#BPI-67 by Inlead: Cover bpi-client with PHP docs

Bpi/Sdk/Authorization.php

@@ -1,15 +1,33 @@
 <?php
+
 namespace Bpi\Sdk;
 
+/**
+ * Class Authorization prepare authorization credentials.
+ */
 class Authorization
 {
+    /**
+     * @var string agency id
+     */
     protected $agency_id;
+
+    /**
+     * @var string public key used to authorize on rest server
+     */
     protected $public_key;
+
+    /**
+     * @var string secret key used to authorize on rest server
+     */
     protected $secret_key;
+
+    /**
+     * @var string token by which client authorizes on service
+     */
     protected $token;
 
     /**
-     *
      * @param string $agency_id
      * @param string $public_key
      * @param string $secret_key
@@ -23,16 +41,16 @@ public function __construct($agency_id, $public_key, $secret_key)
     }
 
     /**
-     * Generate authorization token
+     * Generate authorization token.
      */
     protected function generateToken()
     {
-        $this->token = crypt($this->agency_id . $this->public_key . $this->secret_key);
+        $this->token = crypt($this->agency_id.$this->public_key.$this->secret_key);
     }
 
     /**
      * Represent as HTTP Authorization string.
-     * Will return value part, e.g. Authorization: <value>
+     * Will return value part, e.g. Authorization: <value>.
      *
      * @return string
      */

Bpi/Sdk/Bpi.php

@@ -1,38 +1,38 @@
 <?php
-require_once __DIR__ . '/../../vendor/autoload.php';
 
+require_once __DIR__.'/../../vendor/autoload.php';
+
+/**
+ * Class Bpi represents methods for requests to REST server.
+ */
 class Bpi
 {
     /**
-     *
-     * @var \Goutte\Client
+     * @var \Goutte\Client crawler library
      */
     protected $client;
 
     /**
-     *
-     * @var \Bpi\Sdk\Authorization
+     * @var \Bpi\Sdk\Authorization authorization credentials
      */
     protected $authorization;
 
     /**
-     *
-     * @var \Bpi\Sdk\Document
+     * @var \Bpi\Sdk\Document url to service
      */
     protected $endpoint;
 
     /**
-     *
-     * @var \Bpi\Sdk\Document
+     * @var \Bpi\Sdk\Document current loaded document
      */
     protected $current_document;
 
     /**
-     * Create Bpi Client
+     * Create Bpi Client.
      *
-     * @param string $endpoint URL
-     * @param string $agency_id Agency ID
-     * @param string $api_key App key
+     * @param string $endpoint   URL
+     * @param string $agency_id  Agency ID
+     * @param string $api_key    App key
      * @param string $secret_key
      */
     public function __construct($endpoint, $agency_id, $api_key, $secret_key)
@@ -44,7 +44,7 @@ public function __construct($endpoint, $agency_id, $api_key, $secret_key)
     }
 
     /**
-     * Create new document
+     * Create new document.
      *
      * @return \Bpi\Sdk\Document
      */
@@ -54,10 +54,11 @@ protected function createDocument()
     }
 
     /**
-     * Get list of node based on some conditions
+     * Get list of node based on conditions.
      *
      * @param array $queries available keys are: amount, offset, filter, sort
-     *   filter and sort requires nested arrays
+     *                       filter and sort requires nested arrays
+     *
      * @return \Bpi\Sdk\NodeList
      */
     public function searchNodes(array $queries = array())
@@ -78,10 +79,12 @@ public function searchNodes(array $queries = array())
     }
 
     /**
-     * Push new node to BPI
+     * Push new node to BPI.
+     *
+     * @param array $data of node which will be pushed to service.
      *
-     * @param array $data
      * @throws \InvalidArgumentException
+     *
      * @return \Bpi\Sdk\Item\Node
      */
     public function push(array $data)
@@ -90,23 +93,27 @@ public function push(array $data)
         $nodes = clone $this->endpoint;
         $nodes->firstItem('name', 'node')
             ->template('push')
-            ->eachField(function ($field) use ($data) {
-                if (!isset($data[(string)$field]))
-                    throw new \InvalidArgumentException(sprintf('Field [%s] is required', (string) $field));
+            ->eachField(
+                function ($field) use ($data) {
+                    if (!isset($data[(string) $field])) {
+                        throw new \InvalidArgumentException(sprintf('Field [%s] is required', (string) $field));
+                    }
 
-                $field->setValue($data[(string) $field]);
-            })->post($node);
+                    $field->setValue($data[(string) $field]);
+                }
+            )->post($node);
 
         $this->current_document = $node;
 
         return new \Bpi\Sdk\Item\Node($node);
     }
 
     /**
-     * Mark node as syndicated
+     * Mark node as syndicated.
      *
      * @param string $id BPI node ID
-     * @return boolean operation status
+     *
+     * @return bool operation status
      */
     public function syndicateNode($id)
     {
@@ -123,10 +130,11 @@ public function syndicateNode($id)
     }
 
     /**
-     * Mark node as deleted
+     * Mark node as deleted.
      *
      * @param string $id BPI node ID
-     * @return boolean operation status
+     *
+     * @return bool operation status
      */
     public function deleteNode($id)
     {
@@ -144,28 +152,31 @@ public function deleteNode($id)
 
     /**
      * Get statistics
-     * Parameterformat: Y-m-d
+     * Parameterformat: Y-m-d.
      *
      * @param string $dateFrom
      * @param string $dateTo
+     *
+     * @return \Bpi\Sdk\Item\BaseItem
      */
     public function getStatistics($dateFrom, $dateTo)
     {
         $result = $this->createDocument();
         $endpoint = clone $this->endpoint;
         $endpoint->firstItem('name', 'node')
             ->query('statistics')
-            ->send($result, array('dateFrom'=>$dateFrom, 'dateTo'=>$dateTo));
+            ->send($result, array('dateFrom' => $dateFrom, 'dateTo' => $dateTo));
 
         $this->current_document = $result;
 
         return new \Bpi\Sdk\Item\BaseItem($result);
     }
 
     /**
-     * Get single Node by ID
+     * Get single Node by ID.
      *
      * @param string $id BPI node ID
+     *
      * @return \Bpi\Sdk\Item\Node
      */
     public function getNode($id)
@@ -183,7 +194,7 @@ public function getNode($id)
     }
 
     /**
-     * Get list of dictionaries
+     * Get list of dictionaries.
      *
      * @return array
      */
@@ -199,12 +210,13 @@ public function getDictionaries()
         $this->current_document = $result;
 
         $dictionary = array();
-        foreach ($result as $item)
-        {
+        foreach ($result as $item) {
             $properties = array();
-            $item->walkProperties(function($property) use (&$properties){
-                $properties[$property['name']] = $property['@value'];
-            });
+            $item->walkProperties(
+                function ($property) use (&$properties) {
+                    $properties[$property['name']] = $property['@value'];
+                }
+            );
 
             $dictionary[$properties['group']][] = $properties['name'];
         }
@@ -213,10 +225,11 @@ public function getDictionaries()
     }
 
     /**
+     * Get current document.
      *
      * @return \Bpi\Sdk\Document
      */
-    public function _getCurrentDocument()
+    protected function _getCurrentDocument()
     {
         return $this->current_document;
     }