Domain and Domain Registration

Navigation: skip navigation

Client's library in PHP5 I. - how to use

Description how to use client of ZMS system.

Contents

  1. Technical requirements for library use
  2. Download library
  3. Example of library use in aplication
  4. Format of functions' input parameters
  5. Format of functions' release values
  6. Connection to ZMS server
  7. Description of error messages
  8. Complex example of library use

1. Technical requirements for library use

  • PHP version 5.1.4 and higher
  • SimpleXML extension

2. Download library

You must have a permission to the ZMS server to use the client. Write to our technical support on e-mail admin@zoner.cz to get this rights.

  • currrent version of library can be downloaded here

3. Library use in aplication

require_once 'Zoner/Cms/Client.php';

4. Format of functions' input parameters

All parameters(precisely, names of field keys) are case-sensitive! Values of keys MUST BE IN UTF-8 encoding!

There are two types of input parameters:

  1. param - parameter

    Parameters are transmitted as associative field:

    
$params = array( "parametr" => "hodnota_parametru");
$request->metoda($params);
  2. table - table

    Table is a set of values of the same type (array). In case of one-dimensional array the values are written without keys, in case of more dimensional array the keys are the successive letters of alphabet. Meaning of every key is described in respective method.

    
// parametr
$id = 'ID';

// jednorozměrné pole
$tech_rem = array('TECH-1', 'TECH-2', 'TECH-3'); 

// vícerozměrné 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->metoda($params);

5. Format of functions' release values

There are two types of release values:

  1. param - parameter

    To get value of particular parameter, you can use method of getParam() object Zoner_Cms_Client_Response.

    Function prototype:

    
public function getParam($node);

    Where the value $node gives parameter name whose value the method returns.

    To get all parameters, you can use method of getParams() object Zoner_Cms_Client_Response

    Function prototype:

    
public function getParams();
  2. table - tabulka

    To get table, you can use method of getTable() object Zoner_Cms_Client_Response.

    Function prototype:

    
public function getTable($table_name);

    Where $table_name gives, from which table we want to get its values

    The return value is one or more dimensional array, which can be very easily used in iteration cycles:

    
$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

    To get detailed result of action, you can use method of getResult() object Zoner_Cms_Client_Response.

    Result is chain of 4 numbers divided by colon x:y:z:w of this meaning:

    • x - module number (8 is module for work with domains of CZ NIC)
    • y - subsystem number of given module (mostly 0, insignificant)
    • z - other specifications of message (0 - contact, 1 - nsset, 2 - domain)
    • w - operation result (30000 - 49999 error, 50000 - 65530 success)

6. Connection to ZMS server

The connection to the ZMS server is established by creation instance of class Zoner_Cms_Client. The connection's parameters:

  • host - address of the ZMS server. It is also possible to specify prefix of used communication protocole, e.g. mostly: ssl://.
  • port - port of the ZMS server (6535)
  • module - used module for communication with server. In this time you can choose from cznic and zoner module.

With wrongly given input parameters and with no success during module protraction, exception Zoner_Cms_Client_Exception is ejected, with the failure of connection to ZMS server, exception Zoner_Cms_Client_Socket_Exception is ejected.

In case of successfully connection to the ZMS server is important to make authentization by the given login and password (details in the description of login() method). Success of operation can be tested by means of function isSuccess().

Example of use:


$params = array(
		'host' => 'ssl://zms-api.zoner.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']
	);

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

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

	// pripojeni k serveru i autentizace je v poradku.

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

8. Description of error messages

There are four types of errors which you can encounter. You will find other detailed description of concrete error type in relevant parameters of the message (method getParams() class Zoner_Cms_Client_Result)

  1. Syntactic errors (30002)

    • syntax_error_number - error number
    • syntax_error_param - parameter, to which the error is connected (can take all the values of message's input parameters (Fax, Voice, Id, Street, DiscloseVat, etc.)
    • syntax_error_value - parameter's value, to which the error is connected
    • syntax_error_desc - description of error with regard to parameter, to which the error is connected. This parameter can take these values:

      • CannotErase - item cannot be removed
      • CannotBeEmpty - item mustn't be blank
      • InvalidAuthorizationMethod - item has wrong method of logging
      • InvalidValue - item has wrong value
      • LengthMustBe0To16 - item can have size max. 16 signs
      • LengthMustBe0To17 - item can have size max. 17 signs
      • LengthMustBe0To20 - item can have size max. 20 signs
      • LengthMustBe0To32 - item can have size max. 32 signs
      • LengthMustBe0To255 - item can have size max. 255 signs
      • LengthMustBe0To300 - item can have size max. 300 signs
      • LengthMustBe1To66 - item must be in range from 1 to 66 signs
      • LenghtMustBe1To255 - item must be in range from 1 to 255 signs
      • LengthMustBe2 - item must have size 2 signs
      • LengthMustBe3To45 - item must be in range from 3 to 45 signs
      • LengthMustBe3To63 - item must be in range from 3 to 63 signs
      • LengthMustBe4To255 - item must be in range from 4 to 255 signs
      • MustBeCountryCode - item must be given as code of country
      • MustBeDefined - item must be given
      • MustBeEmail - item must be given in format of e-mail
      • MustBeNameServerFQDN - item must be given in format of FQDN
      • MustBeIPAddress - item must be given in IP address format
      • MustBeLowerCase - item must be given in small letters
      • MustBeNormalizedString - item must be string
      • MustBeNotDefined - item mustn't be defined
      • MustBeNumbersOrLettersOrUnderlineOrHyphenOrColonOrDot - item can consist of numbers, letters, underline sign, hyphen, colon or dot
      • MustBeTelephoneNumberFormat - item must be given in format of phone number
      • MustBeToken - item must be chain method without gaps
      • MustBeTypeDateTime - item must be given in format of date
      • MustBeTypeInt - item must be number
      • MustBeUpperCase - item must be given in capitals
      • MustBeValidDomainNameCz - item must be valid .cz domain
      • ValueMustBe0To10 - item must be value from 0 to 10
      • ValueMustBe1To10 - item must be value from 1 to 10
      • ValueMustBe1To365 - item must be value from 1 to 3658

    Example:

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

  2. Runtime errors (30003)

    • runtime_error_number - error number
    • runtime_error_desc - description of error. This parameter can take these values:

      • ContactIsAlreadyDomainOwner - contact is simultaneously domain owner
      • AlreadyCurrentRegistrar - given registrar of this is already ZONER software, Ltd.
      • AuthInfoNotMatching - wrong password
      • AuthIdNotAcquired - unable to verify the password
      • ContactMustBeDomainOwner - contact must be domain owner
      • MustBeTech - contact must be technical administrator
      • InvalidAuthorization - unsuccessful verification of ZONER authorization code
      • InvalidAuthorizationMethod - wrong logging method
      • InvalidContactEmail - wrong contact's e-mail
      • NotAvailable - identificator is already taken
      • NotCurrentRegistrar - given registrar is not ZONER software, Ltd.
      • MaxLimitForAuthPwdCreationExceeded - maximum number for password creation was exceeded
      • MaxLimitOfUnexpiredAuthPwdsReached - maximum limit for valid passwords was reached
      • UnableToSaveAuthPwd - unable to save password
      • UnableToSendEmail - unable to send e-mail
      • MustBeAlreadyRegistred - verification of registration existence failed
      • AdminIdMustBeDefined - code of request mustn't be blank
      • ContactIsAlreadyDomainOwner - contact is already domain owner
      • ContactMustBeDomainOwnerOrAdmin - contact must be domain owner or domain administrator
      • NsSetIsAlreadyDomainNsSet - set of nameservers is already assigned to domain
      • ContactIsAlreadyDomainAdmin - contact is already domain administrator

    Example:

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

  3. SQL errors (30004)

    • sql_error_detail - description of error

    Example:

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

  4. CZNIC errors (30005)

    • cznic_error_code - error number
    • cznic_error_msg - description of error
    • cznic_error_objectid - object's id , to which is error related

    Example:

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

Inspiration during listing error messages:


function showError($response)
{

  $_syntaxt_error_param = array(
    'voice' => 'Telefonní číslo'
  );    

  $_syntaxt_error_desc = array(
    'MustBeTelephoneNumberFormat' => 'Položka %s musí být zadána 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;
}

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

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

9. Complex example of library use


<?php

require_once 'Zoner/Cms/Client.php';

$params = array(
		'host' => 'ssl://zms-api.zoner.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'],
        );

	$response = $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' => 'CZ',
	'email' => 'hrdy.majitel@kontaktu.cz',
	// nepřejeme 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',
	// Nepřejeme si ve WHOIS zobrazovat NotifyEmail
	'disclose_notify_email' => 0,
	'disclose_type' => 'passport',
	'disclose_ident' => '554125484',
	'auth_info' => ''
);

try {

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

	if (!$response->isSuccess()) {
		// vyhodime vyjimku a ziskame chybovou zpravu
		throw new Exception('Vytvoření 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 se vlastne stalo
	echo $e->getMessage();
	return;
}

?>

back

.CZ - Certified Registrar

Website

CMS, photo gallery,
e-mail,
with every domain.

Free with domain
FREE Security each domain of GB
CloudMail - kompletní mailové řešení
Log on the administration account Help