Add some documentation and tests (#63)

Hold on to your hats because we're increasing code coverage like mad ones.
AfriCC · Jan 6, 2019 · 7011511 · 7011511
1 parent 3d9aa5e
commit 7011511
Show file tree

Hide file tree

Showing 19 changed files with 512 additions and 18 deletions.
diff --git a/examples/update_contact.php b/examples/update_contact.php
@@ -1,5 +1,6 @@
 <?php
 
+// TODO: This example generates code not compliant with RFC 5733
 // debug
 error_reporting(E_ALL);
 ini_set('display_errors', true);

diff --git a/src/AfriCC/EPP/AbstractFrame.php b/src/AfriCC/EPP/AbstractFrame.php
@@ -28,6 +28,11 @@ abstract class AbstractFrame extends DOMDocument implements FrameInterface
     protected $mapping;
     protected $extension;
 
+    /**
+     * Construct (with import if specified) frame
+     *
+     * @param DOMDocument $import
+     */
     public function __construct($import = null)
     {
         parent::__construct('1.0', 'UTF-8');
@@ -50,6 +55,11 @@ public function __construct($import = null)
         $this->getStructure();
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @see \AfriCC\EPP\FrameInterface::set()
+     */
     public function set($path = null, $value = null)
     {
         $path = $this->realxpath($path);
@@ -65,6 +75,11 @@ public function set($path = null, $value = null)
         return $this->nodes[$path];
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @see \AfriCC\EPP\FrameInterface::get()
+     */
     public function get($query)
     {
         $nodes = $this->xpath->query($query);
@@ -86,18 +101,32 @@ public function get($query)
         }
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @see \AfriCC\EPP\FrameInterface::__toString()
+     */
     public function __toString()
     {
         return $this->saveXML();
     }
 
+    /**
+     * Create nodes specified by path
+     *
+     * @param string $path
+     *
+     * @throws Exception
+     *
+     * @return null|string
+     */
     protected function createNodes($path)
     {
         $path_parts = explode('/', $path);
         $node_path = null;
 
         for ($i = 0, $limit = count($path_parts); $i < $limit; ++$i) {
-            $attr_name = $attr_value = null;
+            $attr_name = $attr_value = $matches = null;
 
             // if no namespace given, use root-namespace
             if (strpos($path_parts[$i], ':') === false) {
@@ -123,12 +152,11 @@ protected function createNodes($path)
                 ++$next_key;
                 $path_parts[$i] = sprintf('%s:%s[%d]', $node_ns, $node_name, $next_key);
             }
-            // direct node-array access
             if (preg_match('/^(.*)\[(\d+)\]$/', $node_name, $matches)) {
+                // direct node-array access
                 $node_name = $matches[1];
-            }
-            // check if attribute needs to be set
-            elseif (preg_match('/^(.*)\[@([a-z0-9]+)=\'([a-z0-9_]+)\'\]$/i', $node_name, $matches)) {
+            } elseif (preg_match('/^(.*)\[@([a-z0-9]+)=\'([a-z0-9_]+)\'\]$/i', $node_name, $matches)) {
+                // check if attribute needs to be set
                 $node_name = $matches[1];
                 $attr_name = $matches[2];
                 $attr_value = $matches[3];
@@ -146,7 +174,7 @@ protected function createNodes($path)
                 throw new Exception(sprintf('unknown namespace: %s', $node_ns));
             }
 
-            // create node (but don't explicitely define root-node)
+            // create node (but don't explicitly define root-node)
             if ($node_ns === 'epp') {
                 $this->nodes[$node_path] = $this->createElementNS($node_xmlns, $node_name);
             } else {
@@ -170,13 +198,19 @@ protected function createNodes($path)
         return $node_path;
     }
 
+    /**
+     * Get Real XPath for provided path
+     *
+     * @param string $path
+     *
+     * @return string
+     */
     protected function realxpath($path)
     {
         if ($path === null) {
             $path_parts = [];
-        }
-        // absolute path
-        elseif (isset($path[1]) && $path[0] === '/' && $path[1] === '/') {
+        } elseif (isset($path[1]) && $path[0] === '/' && $path[1] === '/') {
+            // absolute path
             return substr($path, 2);
         } else {
             $path_parts = explode('/', $path);
@@ -237,6 +271,13 @@ private function getStructure()
         }
     }
 
+    /**
+     * Get Class name from full class
+     *
+     * @param string $class
+     *
+     * @return string
+     */
     private function className($class)
     {
         if (!is_string($class)) {

diff --git a/src/AfriCC/EPP/AddrTrait.php b/src/AfriCC/EPP/AddrTrait.php
@@ -20,6 +20,14 @@ trait AddrTrait
 {
     protected $host_attr_index = 0;
 
+    /**
+     * Set value to path
+     *
+     * @param string $path
+     * @param mixed $value
+     *
+     * @return \DOMElement
+     */
     abstract public function set($path = null, $value = null);
 
     protected function appendAddr($path, $ip)

diff --git a/src/AfriCC/EPP/Extension/NICMX/Info/Rar.php b/src/AfriCC/EPP/Extension/NICMX/Info/Rar.php
@@ -12,7 +12,7 @@
 namespace AfriCC\EPP\Extension\NICMX\Info;
 
 use AfriCC\EPP\ExtensionInterface as Extension;
-use AfriCC\EPP\Frame\Command\Info as Info;
+use AfriCC\EPP\Frame\Command\Info;
 
 /**
  * @see http://www.registry.mx

diff --git a/src/AfriCC/EPP/Frame/Command/Update/Contact.php b/src/AfriCC/EPP/Frame/Command/Update/Contact.php
@@ -7,6 +7,8 @@
  *
  * For the full copyright and license information, please view the LICENSE file
  * that was distributed with this source code.
+ *
+ * TODO: This class can generate content not compliant with RFC 5733. I wonder if we should force it to be compliant and rely on extensions for non-compliant registrars.
  */
 
 namespace AfriCC\EPP\Frame\Command\Update;

diff --git a/src/AfriCC/EPP/Frame/Response.php b/src/AfriCC/EPP/Frame/Response.php
@@ -21,6 +21,11 @@
  */
 class Response extends AbstractFrame
 {
+    /**
+     * Get Results from response frame
+     *
+     * @return Result[]
+     */
     public function results()
     {
         $results = [];
@@ -32,6 +37,13 @@ public function results()
         return $results;
     }
 
+    /**
+     * Whether response is successful
+     *
+     * @todo On response with multiple codes this fails miserably
+     *
+     * @return bool true on succes, false otherwise.
+     */
     public function success()
     {
         $code = $this->code();
@@ -42,11 +54,25 @@ public function success()
         return false;
     }
 
+    /**
+     * Get Response code
+     *
+     * @todo on response with multiple results this fails miserably
+     *
+     * @return int response code
+     */
     public function code()
     {
         return (int) $this->get('//epp:epp/epp:response/epp:result/@code');
     }
 
+    /**
+     * Get Response message
+     *
+     * @todo check message against multiple responses
+     *
+     * @return string message
+     */
     public function message()
     {
         return (string) $this->get('//epp:epp/epp:response/epp:result/epp:msg/text()');

diff --git a/src/AfriCC/EPP/Frame/ResponseFactory.php b/src/AfriCC/EPP/Frame/ResponseFactory.php
@@ -17,6 +17,13 @@
 
 class ResponseFactory
 {
+    /**
+     * Build response frame
+     *
+     * @param string $buffer
+     *
+     * @return string|\AfriCC\EPP\Frame\Response\MessageQueue|\AfriCC\EPP\Frame\Response
+     */
     public static function build($buffer)
     {
         $xml = new DOMDocument('1.0', 'UTF-8');

diff --git a/src/AfriCC/EPP/FrameInterface.php b/src/AfriCC/EPP/FrameInterface.php
@@ -17,9 +17,27 @@
  */
 interface FrameInterface
 {
+    /**
+     * Set value to path
+     *
+     * @param string $path
+     * @param mixed $value
+     *
+     * @return \DOMElement
+     */
     public function set($path, $value);
 
+    /**
+     * Get value from path
+     *
+     * @param string $query
+     *
+     * @return string|bool|\DOMNodeList
+     */
     public function get($query);
 
+    /**
+     * @return string
+     */
     public function __toString();
 }
diff --git a/src/AfriCC/EPP/PeriodTrait.php b/src/AfriCC/EPP/PeriodTrait.php
@@ -18,10 +18,19 @@
  */
 trait PeriodTrait
 {
+    /**
+     * Set value to path
+     *
+     * @param string $path
+     * @param mixed $value
+     *
+     * @return \DOMElement
+     */
     abstract public function set($path = null, $value = null);
 
     protected function appendPeriod($path, $period)
     {
+        $matches = [];
         if (preg_match('/^(\d+)([a-z])$/i', $period, $matches)) {
             $this->set(sprintf($path, $matches[2]), $matches[1]);
         } else {

diff --git a/tests/EPP/Frame/Command/Create/ContactCreateTest.php b/tests/EPP/Frame/Command/Create/ContactCreateTest.php
@@ -3,6 +3,7 @@
 namespace AfriCC\Tests\EPP\Frame\Command\Create;
 
 use AfriCC\EPP\Frame\Command\Create\Contact;
+use Exception;
 use PHPUnit\Framework\TestCase;
 
 class ContactCreateTest extends TestCase
@@ -282,4 +283,67 @@ public function testContactCreateEntities()
             (string) $frame
         );
     }
+
+    public function testContactCreateForceAscii()
+    {
+        $frame = new Contact();
+        $frame->forceAscii();
+        $frame->setId('CONTACT1');
+        $frame->setOrganization('Fäther & Sons"');
+
+        $this->assertXmlStringEqualsXmlString(
+            '
+                <epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
+                  <command>
+                    <create>
+                      <contact:create xmlns:contact="urn:ietf:params:xml:ns:contact-1.0">
+                        <contact:id>CONTACT1</contact:id>
+                        <contact:postalInfo type="loc">
+                          <contact:org>Father &amp; Sons"</contact:org>
+                        </contact:postalInfo>
+                        <contact:postalInfo type="int">
+                          <contact:org>Father &amp; Sons"</contact:org>
+                        </contact:postalInfo>
+                      </contact:create>
+                    </create>
+                  </command>
+                </epp>
+            ',
+            (string) $frame
+        );
+    }
+
+    public function testContactCreateInvalidCC()
+    {
+        $frame = new Contact();
+        $frame->setId('CONTACT1');
+
+        if (method_exists($this, 'expectException')) {
+            $this->expectException(Exception::class);
+            $frame->setCountryCode('Canada');
+        } else {
+            try {
+                $frame->setCountryCode('Canada');
+            } catch (Exception $e) {
+                $this->assertEquals('Exception', get_class($e));
+            }
+        }
+    }
+
+    public function testContactCreateInvalidEmail()
+    {
+        $frame = new Contact();
+        $frame->setId('CONTACT1');
+
+        if (method_exists($this, 'expectException')) {
+            $this->expectException(Exception::class);
+            $frame->setEmail('Canada');
+        } else {
+            try {
+                $frame->setEmail('Canada');
+            } catch (Exception $e) {
+                $this->assertEquals('Exception', get_class($e));
+            }
+        }
+    }
 }