Creating Nominet EPP messages using Smarty

As mentioned in a previous post on Connecting to Nominet EPP with PHP, the Smarty templating system is an easy to use way to create EPP messages without having to resort to complicated XML generation.

For information on how to get started with Smarty, see my Introduction To Smarty.

EPP requests are standard XML documents with a few variables that change on each request.

For example, to query information related to a domain name the info command is used:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
         epp-1.0.xsd">
      <command>
        <info>
          <domain:info
           xmlns:domain="http://www.nominet.org.uk/epp/xml/nom-domain-1.0"
           xsi:schemaLocation="http://www.nominet.org.uk/epp/xml/nom-domain-1.0
           nom-domain-1.0.xsd">
            <domain:name>webma.co.uk</domain:name>
         </domain:info>
       </info>
       <clTRID>EXAMPLE-12345</clTRID>
     </command>
   </epp>

The only two elements that change in this XML from one request to the next are the domain name and the clTRID which is the client transaction id, therefore a smarty template of the following:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
         epp-1.0.xsd">
      <command>
        <info>
          <domain:info
           xmlns:domain="http://www.nominet.org.uk/epp/xml/nom-domain-1.0"
           xsi:schemaLocation="http://www.nominet.org.uk/epp/xml/nom-domain-1.0
           nom-domain-1.0.xsd">
            <domain:name>{$domain_name}</domain:name>
         </domain:info>
       </info>
       <clTRID>{$transaction_id}</clTRID>
     </command>
   </epp>

would fit the purpose, assuming this is saved in a file called info.tpl, to get the correct XML for an info request use the following PHP code:

$smarty->assign('domain_name','webma.co.uk');
$smarty->assign('transaction_id','TAG_NAME-123');
$xml = $smarty->fetch('info.tpl');

This can be repeated for any EPP request needed very simply.

Introduction to Smarty

Smarty is a template engine for PHP, and one that is very easy to use at that.

It can be downloaded from http://www.smarty.net/download.php or is included in some Linux distributions.

Rather than repeat them all here, there are easy to use installation instructions on the Smarty website at http://www.smarty.net/quick_start.php

There are two ways primary ways to assign variables to Smarty, directly as a variable, e.g. a string or an integer which can be down via the following:

//assign an integer of 1 to the variable 'var1'
$smarty->assign('var1',1);

//assign a string 'test' to the variable 'var2'
$smarty->assign('var2','test');

//assign an array to the variable 'var3'
$smarty->assign('var3',array(1,2,3,4));

You can also pass an associative array to assign multiple variables at once, e.g:
$smarty->assign(array('var1' => 1,'var2' => 'test', 'var3' => array (1,2,3,4)));
This will have the same effect as the 3 lines above.

In the Smarty template, to use the variables, all you would need to do is the following:
{$var1}, this will output the value of $var1 wherever you write this.

The second way is to assign by reference, you would use this if you are assigning an object to the template, for example given a class called HelloClass that returns "Hello World" when you call its hello() function, you can assign it to smarty with:
$smarty->assign_by_ref('hello_class',new HelloClass);
and in the template you would call it with {$hello_class->hello()}

To display a template, the code is as follows:
$smarty->display('template.tpl');

There is much much more to Smarty, you can find its full manual at http://www.smarty.net/manual/en/

Connecting to Nominet EPP with PHP

EPP stands for Extensible Provisioning Protocol, this is the method that a large number of domain registries use to communicate.

This is a basic example of how to connect to an EPP server using a basic script supplied by CentralNic.

The script, Net_EPP_Client can be downloaded from CentralNic Labs and can be installed using PEAR or manually by copying into the relevant directory.

For the examples in the post, we will be logging into the Nominet EPP server.

EPP clients connect to a server, login and then send the commands that wish to make. An example of connecting is as follows:

<?php
require('Net/EPP/Client.php');

$client = new Net_EPP_Client;
$host = 'epp.nominet.org.uk';
$port = 700;
$timeout = 10;
$ssl = true;

$greeting = $client->connect($host, $port, $timeout, $ssl);

echo $greeting;
?>

Which will output

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.nominet.org.uk/epp/xml/epp-1.0 epp-1.0.xsd">
  <greeting>
    <svID>Nominet EPP server epp.nominet.org.uk</svID>
    <svDate>2008-08-23T16:24:51Z</svDate>
    <svcMenu>
      <version>1.0</version>
      <lang>en</lang>
      <objURI>http://www.nominet.org.uk/epp/xml/nom-account-1.0</objURI>
      <objURI>http://www.nominet.org.uk/epp/xml/nom-domain-1.0</objURI>
      <objURI>http://www.nominet.org.uk/epp/xml/nom-contact-1.0</objURI>
      <objURI>http://www.nominet.org.uk/epp/xml/nom-ns-1.0</objURI>
    </svcMenu>
    <dcp>
      <access><all/></access>
      <statement>
        <purpose><admin/><prov/></purpose>
        <recipient><ours/></recipient>
        <retention><indefinite/></retention>
      </statement>
    </dcp>
  </greeting>
</epp>

This shows that the connection is correctly opened and you are now able to login by sending back the following reply:

<?xml version="1.0" encoding="UTF-8"?>
  <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd">
    <command>
      <login>
        <clID>TAG_NAME</clID>
        <pw>password</pw>
        <options>
          <version>1.0</version>
          <lang>en</lang>
        </options>
        <svcs>
           <objURI>http://www.nominet.org.uk/epp/xml/nom-account-1.0</objURI>
           <objURI>http://www.nominet.org.uk/epp/xml/nom-domain-1.0</objURI>
           <objURI>http://www.nominet.org.uk/epp/xml/nom-contact-1.0</objURI>
           <objURI>http://www.nominet.org.uk/epp/xml/nom-ns-1.0</objURI>
        </svcs>
      </login>
      <clTRID>your_transaction_id</clTRID>
    </command>
  </epp>

I find that an easy way to manage creating EPP XML requests is by using the Smarty templating system, more on that in a later post.

You should then receive a reply indicating your login was successful:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.nominet.org.uk/epp/xml/epp-1.0 epp-1.0.xsd">
  <response>
    <result code="1000">
      <msg>
        Command completed successfully
      </msg>
    </result>
    <trID>
      <clTRID>EPP-your_transaction_id</clTRID>
      <svTRID>12345678</svTRID>
    </trID>
  </response>
</epp>

From there you can go on to perform the actions you require, more information on using Nominet's EPP service can be found at http://www.nic.uk/registrars/systems/epp/

Parsing XML using SimpleXML and PHP

One of the very useful things about the SimpleXML extension in PHP is parsing XML data very simply and easily, for example, using the XML file created in a previous post which looks as follows:

<?xml version="1.0"?>
<messages>
        <message>
                <subject>Hello</subject>
                <from>user@example.com</from>
                <to>user2@example.com</to>
                <body>Hello World</body>
        </message>
        <message>
                <subject>Hello Again</subject>
                <from>user@example.com</from>
                <to>user2@example.com</to>
                <body>Hello World Take 2</body>
        </message>
</messages>

Assuming the xml is located in a file called test.xml we can loop through the contents with the following code:

<?php
$xml = simplexml_load_file("test.xml");

foreach ($xml->message as $message)
{
    print_r($message);
}
?>

The $xml->message object is seen as an array so outputs the following:

SimpleXMLElement Object
(
    [subject] => Hello
    [from] => user@example.com
    [to] => user2@example.com
    [body] => Hello World
)
SimpleXMLElement Object
(
    [subject] => Hello Again
    [from] => user@example.com
    [to] => user2@example.com
    [body] => Hello World Take 2
)

It is also very easy to manipulate data within the array, for example to change to to address on the second message:

<?php
$xml = simplexml_load_file("test.xml");

//find the second element, (starting from 0)
$xml->message[1]->to = "user3@example.com";

foreach ($xml->message as $message)
{
    print_r($message);
}
?>

Would output:

SimpleXMLElement Object
(
    [subject] => Hello
    [from] => user@example.com
    [to] => user2@example.com
    [body] => Hello World
)
SimpleXMLElement Object
(
    [subject] => Hello Again
    [from] => user@example.com
    [to] => user3@example.com
    [body] => Hello World Take 2
)

Creating XML with SimpleXML and PHP

Following on from my Introduction to SimpleXML with PHP, SimpleXML can also be used to create XML documents.

The XML example in the previous post:

<?xml version="1.0"?>
<message>
 <subject>Hello</subject>
 <from>user@example.com</from>
 <to>user2@example.com</to>
 <body>Hello World</body>
</message>

Can be created with the following code:

<?php
//create SimpleXML object
$xml = simplexml_load_string("<message></message>");

//add subject element
$xml->addChild('subject','Hello');

//add from element
$xml->addChild('from','user@example.com');

//add to element
$xml->addChild('to','user2@example.com');

//add body element
$xml->addChild('body','Hello World');

//output XML
echo $xml->asXML();
?>

You can also add sub elements to elements that you create: for example if your XML files was to have a list of messages:

<?php
$xml = simplexml_load_string("<messages></messages>");

//add child to xml object and return new object for that child
$message1 = $xml->addChild('message');
$message1->addChild('subject','Hello');
$message1->addChild('from','user@example.com');
$message1->addChild('to','user2@example.com');
$message1->addChild('body','Hello World');

//add second child to xml object and return new object for that child
$message2 = $xml->addChild('message');
$message2->addChild('subject','Hello Again');
$message2->addChild('from','user@example.com');
$message2->addChild('to','user2@example.com');
$message2->addChild('body','Hello World Take 2');

//output XML
echo $xml->asXML();
?>

This will output:

<?xml version="1.0"?>
<messages>
        <message>
                <subject>Hello</subject>
                <from>user@example.com</from>
                <to>user2@example.com</to>
                <body>Hello World</body>
        </message>
        <message>
                <subject>Hello Again</subject>
                <from>user@example.com</from>
                <to>user2@example.com</to>
                <body>Hello World Take 2</body>
        </message>
</messages>

Introduction to SimpleXML with PHP

The SimpleXML php extension make it very easy to parse and create basic XML files.

Here is a basic xml file that describes a message from one person to another:

<?xml version='1.0'?>
<message>
 <subject>Hello</subject>
 <from>user@example.com</from>
 <to>user2@example.com</to>
 <body>Hello World</body>
</message>

If you create a file called test.xml with the content above then create a php file with the following, it will load in the xml file and output it as an SimpleXML object:

<?php
$xml = simplexml_load_file("test.xml");
print_r($xml);
?>

Will output:

SimpleXMLElement Object
(
    [subject] => Hello
    [from] => user@example.com
    [to] => user2@example.com
    [body] => Hello World
)

To reference a variable within the xml file you can use in the normal object way, e.g. $xml->subject

To change the value of a variable, you can simply do the following:
$xml->subject = "New Subject";

And to output the new XML file:
echo $xml->asXML();

which returns:

<?xml version="1.0"?>
<message>
 <subject>New Subject</subject>
 <from>user@example.com</from>
 <to>user2@example.com</to>
 <body>Hello World</body>
</message>

Any questions/feedback please leave a comment

Connecting to Sage CRM with PHP

I was recently requested to find a way to integrate an online signup form with Sage CRM to allow for signups to be automatically added. I decided to use PHP to do this as its SOAP integration is very easy to use:

Below is example code that shows how to log into Sage using its SOAP interface and pass requests to it:

Note: this example is PHP5 only.

//allow for exceptions to be thrown from sage
try
{
        //define connection options, this allows for recording messages sent and received
        $options = array('trace' => 1);

        $client = new SoapClient("http://localhost/crm/eware.dll/webservice/webservice.wsdl", $options);

        //username and password for sage (the user has to have web service access enabled)
        $login_details  = array('username' => 'username',
                                'password' => 'password');

        //login to sage
        $response = $client->logon($login_details);

        //create header to send on future requests
        $header = "<sessionheader><sessionid>".$response->result->sessionid."</sessionid></sessionheader>";
        $session_var = new SoapVar($header, XSD_ANYXML, null, null, null);
        $session_header = new SoapHeader('http://tempuri.org/type', 'SessionHeader', $session_var);

        //apply header to client
        $client->__setSoapHeaders(array($session_header));

        //define lead data (or pull in from elsewhere), this is only some of the fields
        //I will go into further detail on the fields in another blog post
        $lead_data = array('companyname'     => 'company name',
                           'companyaddress1' => 'address1',
                           'personfirstname' => 'first name',
                           'personlastname'  => 'last name',
                           'status'          => 'In Progress');

        //create soap variable to send
        $lead = new SoapVar($lead_data, XSD_ANYTYPE, "lead", "http://tempuri.org/type");

        //send request to sage
        $response = $client->add(array('entityname' => 'lead', 'records' => $lead));

        //check response
        if (isset($response->result->records->crmid))
        {
             //worked, the lead id can be found in $response->result->records->crmid
        }
        else
        {
              //failed, display
              echo "RESPONSE:\n" . $client->__getLastResponse() . "\n";
        }
}
catch (Exception $e)
{
        //something went wrong, display request and response
        echo "REQUEST:\n" . $client->__getLastRequest() . "\n";
        echo "RESPONSE:\n" . $client->__getLastResponse() . "\n";

        echo $e->getMessage();
}

Any questions/feedback please leave a comment