Klientská knižnica PHP5 I. - návod na použitie

Návod na použitie knižnice systému ZMS.

Obsah

1. Technické požiadavky na použitie knižnice
2. Stianuť knižnicu
3. Príklad použitia knižnice v aplikácii
4. Formát vstupných parametrov funkcií
   • param
   • table
5. Formát návratových hodnôt funkcií
   • param
   • table
   • result
6. Spojenie sa serverom ZMS
   
7. Popis chybových správ
   • Syntaktické chyby
   • Runtime chyby
   • SQL chyby
   • Chyby CZNICu
8. Komplexný príklad použitia knižnice

1. Technické požadavky na použitie knižnice

• PHP verzie 5.1.4 a vyššej
• SimpleXML extension

2. Stiahnuť knižnicu

Aby ste mohli klienta skutočne používať, musíte najskôr získať oprávnenie. Pre získanie oprávnenia sa obráťte na technickú podporu admin@zoner.sk.

• aktuálna verzia knižnice na stiahnutie je 1.2.0

3. použitie knižnice v aplikácii

require_once 'Zoner/Cms/Client.php';

4. Formát vstupných parametrov funkcií

Všetky parametre (presnejšie, názvy kľúčov poľa) sú case-sensitive!

Existujú dva typy vstupných parametrov:

1. param - parameter

   Parametre sa predávájú ako asociatívne pole:

   $params = array( "parameter" => "hodnota_parametru");
   $request->metóda($params);
   

2. table - tabuľka

   Súbor hodnôt rovnakého typu sa zapisuje do tabuľky - poľa. Pokiaľ pole nie je viacrozmerné, hodnoty sú zapisované bez kľúčov, v prípade viacrozmerného poľa sú kľúčmi jednotlivých hodnôt postupne po sebe idúce písmená abecedy. Význam jednotlivých kľúčov je vždy vysvetlený v príslušnej metóde.

   // parameter
   $id = 'ID';
   
   // jednorozmerné pole
   $tech_rem = array('TECH-1', 'TECH-2', 'TECH-3'); 
   
   // vícerozmerné pole
   $ds_add = array(array('a' => '2001',
                         'b' => '5',
                         'c' => '1',
                         'd' => '9E93399CB85993754DE862E594B7598C702FD31B',
                         'e' => '3600'),
   		array('a' => '2002',
                         'b' => '5',
                         'c' => '1',
                         'd' => 'BA88596CB85993754DE862E594B7598C702FD8B1',
                         'e' => '3600')); 
   
   $params = array('id' => $id,
                   'tech_rem' => $tech_rem,
                   'ds_add' => $ds_add);
   
   $request->metóda($params);
   
   

5. Formát návratových hodnôt funkcií

Existují dva typy návratových hodnôt:

1. param - parameter

   K získániu hodnoty určitého parametra slúži metóda getParam() objektu Zoner_Cms_Client_Response.

   Funkčný prototyp:

   public function getParam($node);
   

   Kde hodnota $node udáva názov parametra, ktorého hodnotu metóda vráti.

   K získániu všetkých paramerov slúží metóda getParams() objektu Zoner_Cms_Client_Response

   Funkčný prototyp:

   public function getParams();
   

2. table - tabuľka

   K získání tabuľky slúži metóda getTable() objektu Zoner_Cms_Client_Response.

   Funkčný prototyp:

   public function getTable($table_name);
   

   Kde $table_name udává, z ktorej tabuľky chceme získať jej hodnoty

   Návratovou hodnotou je jednorozmerné, alebo viacrozmerné pole, ktoré je možné veľmi jednoducho použíť v iteračných cykloch:

   $table_rows = $response->getTable('street');
   print_r($table_rows);
   
   Array
   (
       [0] => Nové sady 583/18,
       [1] => Staré sady XYZ/AB,
       [2] => Velmi staré sady FGD/IJ
   )
   
   $table_rows = $response->getTable('ds');
   print_r($table_rows);
   
   Array
   (
       [0] => Array
           (
               [a] => 2001,
               [b] => 5,
               [c] => 1,
               [d] => 9E93399CB85993754DE862E594B7598C702FD31B,
               [e] => 3600
           ),
       [1] => Array
           (
               [a] => 2002,
               [b] => 5,
               [c] => 1,
               [d] => BA88596CB85993754DE862E594B7598C702FD8B1,
               [e] => 3600
           )
   )
   
   
   

3. result - result

   K získaniu detailného výsledku akcie slúži metóda getResult() objektu Zoner_Cms_Client_Response.

   Výsledok je reťazec 4 čísel oddelených dvojbodkou x:y:z:w tohoto významu:

   • x - číslo modulu (8 je modul pre prácu s doménami CZ NICu)
   • y - číslu subsystému daného modulu (väčšinou 0, nevýznamné)
   • z - dalšia špecifikácia správy (0 - kontakt, 1 - nsset, 2 - doména)
   • w - výsledok operácie (30000 - 49999 chyba, 50000 - 65530 úspech)

6. Spojenie so serverom ZMS

Spojenie na server ZMS sa vykonáva vytvorením inštancie triedy Zoner_Cms_Client. Parametre, nutné pre spojenie sú uvedené v asociativnom poli, predanom ako vstupné paramtetre objektu:

• host - adresa serveru ZMS. Možné je aj špecifikovať prefix použitého komunikačného protokolu. Napr. nejčasteji: ssl://.
• port - port serveru (6535 - ostrá prevádzka, 6735 - testovacia prevádzka)
• module - použitý modul pre komunikáciu so serverom. V tomto prípade je nutné tento parameter nastaviť na hodnotu 'cznic'. Iné moduly zatiaľ neboli implementované.

Pri nesprávne zadaných vstupných parametroch a pri neúspechu pri natiahnutí modulu je zobrazená výnimka: Zoner_Cms_Client_Exception, pri zlyhaní pripojenia k ZMS serveru je zobrazená výnimka Zoner_Cms_Client_Socket_Exception.

Po úspešnom pripojení k ZMS serveru je nutné sa autentizovať pomocou prideleného loginu a hesla, predaných ako parametre metody login(). Úspešnosť operácie je možné potom otestovať pomocou funkcie isSuccess().

Príklad použitia:

$params = array(
		'host' => 'ssl://admin.czechia.com',
		'port' => '6535',
		'module' => 'cznic',
);

try {
	$client = new Zoner_Cms_Client($params);

	$login_params = array(
		'id_user' => 'superuser',
		'password' => 'verysimple',
		'remote_addr' => $_SERVER['REMOTE_ADDR']
	);

	$reponse = $client->login($login_params);

	if ( ! $response->isSuccess() ) {
		// nespravne prihlasovacie udaje, chyba autentizace
		return;
	}

	// pripojenie k serveru a autentizacia je v poriadku.

} catch (Zoner_Cms_Client_Exception $zcce) {
	// reakcia na chybu vstupnych parametrov, chybu natiahnutia modulu a
	// alebo chybu XML engine
} catch (Zoner_Cms_Client_Socket_Exception $zccse) {
	// chyba pripojenia k serveru
}

7. Popis chybových správ

Existují štyri typy chýb, s kterými sa môžete stretnúť. Další detailný popis konkrétneho typu chyby nájdete v príslušných parametroch správy (metóda getParams() triedy Zoner_Cms_Client_Result)

1. Syntaktické chyby (30002)

   • syntax_error_number - číslo chyby
   • syntax_error_param - parameter, na ktorý sa chyba vzťahuje (môže nadobúdať všetky hodnoty vstupných parametrov správ (Fax, Voice, Id, Street, DiscloseVat, atd.)
   • syntax_error_value - hodnota parametra, na který sa chyba vzťahuje
   • syntax_error_desc - popis chyby vzhľadom k parametru, na ktorý sa chyba vzťahuje. Tento parameter môže nadobúdať tieto hodnoty:
     
     
     • CannotErase - položku nie je možné odstrániť
     • CannotBeEmpty - položka nesmie byť prázdna
     • InvalidAuthorizationMethod - položka má nesprávnu metódu prihlásenia
     • InvalidValue - položka má nesprávnu hodnotu
     • LengthMustBe0To16 - položka môže mať veľkost maximálne 16 znakov
     • LengthMustBe0To17 - položka môže mať veľkost maximálne 17 znakov
     • LengthMustBe0To20 - položka môže mať veľkost maximálne 20 znakov
     • LengthMustBe0To32 - položka môže mať veľkost maximálne 32 znakov
     • LengthMustBe0To255 - položka môže mať veľkost maximálne 255 znakov
     • LengthMustBe0To300 - položka môže mať veľkost maximálne 300 znakov
     • LengthMustBe1To66 - položka musí byť v rozmedzí od 1 do 66 znakov
     • LenghtMustBe1To255 - položka musí byť v rozmedzí od 1 do 255 znakov
     • LengthMustBe2 - položka musí mať veľkost 2 znaky
     • LengthMustBe3To45 - položka musí byť v rozmedzí od 3 do 45 znakov
     • LengthMustBe3To63 - položka musí byť v rozmedzí od 3 do 63 znakov
     • LengthMustBe4To255 - položka musí byť v rozmedzí od 4 do 255 znakov
     • MustBeCountryCode - položka musí musi byť zadaná ako kód krajiny
     • MustBeDefined - položka musí byť zadaná
     • MustBeEmail - položka musí byť zadaná v tvare e-mailu
     • MustBeNameServerFQDN - položka musí byť zadaná v tvare FQDN
     • MustBeIPAddress - položka musí byť zadaná v tvare IP adresy
     • MustBeLowerCase - položka musí byť zadaná malými písmenami
     • MustBeNormalizedString - položka musí byť reťazec
     • MustBeNotDefined - položka nesmie byť definovaná
     • MustBeNumbersOrLettersOrUnderlineOrHyphenOrColonOrDot - položka môže byť zložená z čísel, písmen, podčiarnika, pomlčky, dvojbodky alebo bodky
     • MustBeTelephoneNumberFormat - položka musí byť zadaná v tvare telefónneho čísla
     • MustBeToken - položka musí byť retemetoda zec bez medzier
     • MustBeTypeDateTime - položka musí byť zadaná v tvare data
     • MustBeTypeInt - položka musí byť číslo
     • MustBeUpperCase - položka musí byť zadaná velkými písmenami
     • MustBeValidDomainNameCz - položka musí byť valídna .cz doména
     • ValueMustBe0To10 - položka musí byť hodnota od 0 do 10
     • ValueMustBe1To10 - položka musí byť hodnota od 1 do 10
     • ValueMustBe1To365 - položka musí byť hodnota od 1 do 3658

   Príklad:

         Array(
   	   [syntax_error_number] => 12
   	   [syntax_error_param] => Fax
   	   [syntax_error_value] => 554778551
   	   [syntax_error_desc] => MustBeTelephoneNumberFormat
         )
        

2. Runtime chyby (30003)

   • runtime_error_number - číslo chyby
   • runtime_error_desc - popis chyby. Tento parameter môže nadobúdať tieto hodnoty:
     
     
     • ContactIsAlreadyDomainOwner - kontakt je zároveň vlastník domény
     • AlreadyCurrentRegistrar - určeným registrátorom je už ZONER software, s.r.o.
     • AuthInfoNotMatching - nesprávne heslo
     • AuthIdNotAcquired - heslo sa nepodarilo overiť
     • ContactMustBeDomainOwner - kontakt musí byť vlastník domény
     • MustBeTech - kontakt musí byť technickým správcom
     • InvalidAuthorization - neúspešné overenie ZONER autorizačného kódu
     • InvalidAuthorizationMethod - chybná metóda prihlásenia
     • InvalidContactEmail - nesprávny e-mail kontaktu
     • NotAvailable - identifikátor je už obsadený
     • NotCurrentRegistrar - určeným registrátorom nie je ZONER software, s.r.o.
     • MaxLimitForAuthPwdCreationExceeded - bol prekonaný maximálny počet na vytvorenie hesiel
     • MaxLimitOfUnexpiredAuthPwdsReached - bol dosiahnutý maximálny limit platných hesiel
     • UnableToSaveAuthPwd - nie je možné uložiť heslo
     • UnableToSendEmail - nie je možné odoslať e-mail
     • MustBeAlreadyRegistred - overenie existencie registrácie zlyhalo
     • AdminIdMustBeDefined - kód žiadosti nesmie byť prázdny
     • ContactIsAlreadyDomainOwner - kontakt už je držiteľom domény
     • ContactMustBeDomainOwnerOrAdmin - kontakt musí byť držiteľ alebo administrátor domény
     • NsSetIsAlreadyDomainNsSet - sada nameserverov je už priradená doméne
     • ContactIsAlreadyDomainAdmin - kontakt je už administrátorem domény

   Príklad:

         Array(
   	   [runtime_error_number] => 4
   	   [runtime_error_desc] => ContactMustBeDomainOwner
         )
        

3. SQL chyby (30004)

   • sql_error_detail - popis chyby

   Príklad:

         Array(
   	   [sql_error_detail] => Unable to cast object of type 
                                   'System.DateTime' to type 'System.String'.
         )
        

4. Chyby CZNICu (30005)

   • cznic_error_code - číslo chyby
   • cznic_error_msg - popis chyby
   • cznic_error_objectid - id objektu, na ktorý sa chyba vzťahuje

   Príklad:

         Array(
   	   [cznic_error_code] => 2005
   	   [cznic_error_msg] => Chybná syntaxe hodnoty parametru
   	   [cznic_error_objectid] =NSSID:AAAA:2
         )
        

Inšpirácia pri vypisovaní chybových hlásení:

function showError($response)
{
  
  $_syntaxt_error_param = array(
    'voice' => 'Telefonní číslo'
  );    

  $_syntaxt_error_desc = array(
    'MustBeTelephoneNumberFormat' => 'Položka %s musí byť zadaná ve tvaru 
                                      telefonního čísla'
  );    

  list($x, $y, $z, $w) = explode(':', $response->getResult());

  switch ($w) {

    case '30002':

        $param = $response->getParam('syntax_error_param');
        $desc = $response->getParam('syntax_error_desc');
    
        $error = sprintf($_syntaxt_error_desc[$desc], 
                         $_syntaxt_error_param[$param]);         
        
    break;
    
  }

  return $error;
}

$reponse = $client->contactCreate($params);

if (!$response->isSuccess()) {
   echo showError($response);
}

8. Komplexný príklad použitia knižnice

<?php
require_once 'Zoner/Cms/Client.php';

$params = array(
		'host' => 'ssl://admin.czechia.com',
		'port' => '6535',
		'module' => 'cznic',
);

try {

	$client = new Zoner_Cms_Client($params);

$login_params = array(
	'id_user' => 'superuser',
	'password' => 'verysimplepassword',
	'remote_addr' => $_SERVER['REMOTE_ADDR'],
);

	$reponse = $client->login($login_params);

	if ( ! $response->isSuccess() ) {
		// spatne prihlasovaci udaje, chyba autentizace
		return;
	}


} catch (Zoner_Cms_Client_Exception $zcce) {
	// reakce na chybu vstupnich parametru, chybu natazeni modulu a
	// nebo chybu XML engine
	return;
} catch (Zoner_Cms_Client_Socket_Exception $zccse) {
	// chyba pripojeni k serveru
	return;
}

// pripojeni k serveru i autentizace je v poradku.
// proste vse je ok, pokracujeme dale

$params = array(
	'id' => 'VygenerovanyIdKontaktu',
	'street_1' => 'Baker Street 22',
	'city' => 'London',
	'pc' => '123456',
	'cc' => 'Oceanie',
	'email' => 'hrdy.majitel@kontaktu.cz',
	// neprejeme si zobrazovat náš email ve WHOIS
	'disclose_email' => 1,
	'org' => 'Ministry of Love',
	// žádné další ulice
	'street_2' => '',
	'street_3' => '',
	'sp' => '',
	'vat' => '1984',
	'disclose_vat' => '1',
	// Velky bratr faxy zakázal
	'fax' => '',
	'disclose_fax => '1',
	'voice' => '+420.123456789',
	'disclose_voice' => '1',
	'notify_email' => 'velky.bratr@tevidi.cz',
	// Neprejeme si ve WHOIS zobrazovat NotifyEmail
	'disclose_notify_email' => 0,
	'disclose_type' => 'passport',
	'disclose_ident' => '554125484',
	'auth_info' => ''
);

try {

	$reponse = $client->contactCreate($params);

	if (!$response->isSuccess()) {
		// vyhodime vyjimku a ziskame chybovou zpravu
		throw new Exception('Vytvorení kontaktu selhalo');
	}

} catch (Zoner_Cms_Client_Exception $zcce) {
	// reakce na chybu vstupnich parametru, chybu natazeni modulu a
	// nebo chybu XML engine
	return;
} catch (Zoner_Cms_Client_Socket_Exception $zccse) {
	// chyba pripojeni k serveru
	return;
} catch (Exception $e) {
	// nechame si vypsat co sa vlastne stalo
	echo $e->getMessage();
	return;
}


?>