PHP library updates 1.01 - Fixes for inline documentation to work bet…

…ter with IDEs, reseller API functionality
billogram · Nov 6, 2013 · e6e5a6f · e6e5a6f
1 parent 37a132a
commit e6e5a6f
Show file tree

Hide file tree

Showing 8 changed files with 73 additions and 35 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
 .DS_Store
+.idea
diff --git a/Billogram/Api.php b/Billogram/Api.php
@@ -52,19 +52,21 @@
 class Api
 {
     const API_URL_BASE = "https://billogram.com/api/v2";
-    const USER_AGENT = "Billogram API PHP Library/1.00";
+    const USER_AGENT = "Billogram API PHP Library/1.01";
 
     private $authUser;
     private $authKey;
     private $apiBase;
     private $userAgent;
+    private $extraHeaders;
 
-    private $items;
-    private $customers;
-    private $billogram;
-    private $settings;
-    private $logotype;
-    private $reports;
+    private $itemsConnector;
+    private $customersConnector;
+    private $billogramConnector;
+    private $settingsConnector;
+    private $logotypeConnector;
+    private $reportsConnector;
+    private $creditorsConnector;
 
     /**
      * Create a Billogram API connection object
@@ -76,7 +78,8 @@ public function __construct(
         $authUser,
         $authKey,
         $userAgent = self::USER_AGENT,
-        $apiBase = self::API_URL_BASE
+        $apiBase = self::API_URL_BASE,
+        $extraHeaders = array()
     ) {
         $this->authUser = $authUser;
         $this->authKey = $authKey;
@@ -85,11 +88,15 @@ public function __construct(
             $this->userAgent = $userAgent;
         else
             $this->userAgent = self::USER_AGENT;
+        if (!$extraHeaders)
+            $this->extraHeaders = array();
+        else
+            $this->extraHeaders = $extraHeaders;
     }
 
     /**
-     * Checks the response ($response as a response-objcet from httpRequest)
-     * from the API and throws the apprioate exceptions or returns the
+     * Checks the response ($response as a response-object from httpRequest)
+     * from the API and throws the appropriate exceptions or returns the
      * de-encoded data.
      *
      **/
@@ -100,11 +107,12 @@ private function checkApiResponse($response, $expectContentType = null)
 
         if ($response->statusCode >= 500 && $response->statusCode <= 600) {
             if ($response->headers['content-type'] == $expectContentType &&
-                $expectContentType == 'application/json')
+                $expectContentType == 'application/json') {
                 $data = json_decode($response->content);
                 throw new ServiceMalfunctioningError('Billogram API reported ' .
                     'a server error: ' . $data->status . ' - ' .
                     $data->data->message);
+            }
             throw new ServiceMalfunctioningError('Billogram API reported a ' .
                 'server error');
         }
@@ -184,8 +192,6 @@ private function checkApiResponse($response, $expectContentType = null)
             throw new InvalidObjectStateError($message);
         else
             throw new RequestDataError($message);
-
-        return $data;
     }
 
     /**
@@ -211,6 +217,9 @@ private function httpRequest(
         foreach ($sendHeaders as $header => $value) {
             $streamParams['http']['header'] .= $header . ': ' . $value . "\r\n";
         }
+        foreach ($this->extraHeaders as $header => $value) {
+            $streamParams['http']['header'] .= $header . ': ' . $value . "\r\n";
+        }
 
         if (is_array($data)) {
             if (in_array($request, array('POST', 'PUT')))
@@ -350,43 +359,52 @@ public function __get($key)
     {
         switch ($key) {
             case 'items':
-                if (!$this->items)
-                    $this->items = new SimpleClass($this, 'item', 'item_no');
+                if (!$this->itemsConnector)
+                    $this->itemsConnector = new SimpleClass($this, 'item', 'item_no');
 
-                return $this->items;
+                return $this->itemsConnector;
             case 'customers':
-                if (!$this->customers)
-                    $this->customers = new SimpleClass(
+                if (!$this->customersConnector)
+                    $this->customersConnector = new SimpleClass(
                         $this,
                         'customer',
                         'customer_no'
                     );
 
-                return $this->customers;
+                return $this->customersConnector;
             case 'billogram':
-                if (!$this->billogram)
-                    $this->billogram = new BillogramClass($this);
+                if (!$this->billogramConnector)
+                    $this->billogramConnector = new BillogramClass($this);
 
-                return $this->billogram;
+                return $this->billogramConnector;
             case 'settings':
-                if (!$this->settings)
-                    $this->settings = new SingletonObject($this, 'settings');
+                if (!$this->settingsConnector)
+                    $this->settingsConnector = new SingletonObject($this, 'settings');
 
-                return $this->settings;
+                return $this->settingsConnector;
             case 'logotype':
-                if (!$this->logotype)
-                    $this->logotype = new SingletonObject($this, 'logotype');
+                if (!$this->logotypeConnector)
+                    $this->logotypeConnector = new SingletonObject($this, 'logotype');
 
-                return $this->logotype;
+                return $this->logotypeConnector;
             case 'reports':
-                if (!$this->reports)
-                    $this->reports = new SimpleClass(
+                if (!$this->reportsConnector)
+                    $this->reportsConnector = new SimpleClass(
                         $this,
                         'report',
                         'filename'
                     );
 
-                return $this->reports;
+                return $this->reportsConnector;
+            case 'creditors':
+                if (!$this->creditorsConnector)
+                    $this->creditorsConnector = new SimpleClass(
+                        $this,
+                        'creditor',
+                        'id'
+                    );
+
+                return $this->creditorsConnector;
             default:
                 throw new UnknownFieldError("Invalid parameter: " . $key);
         }

diff --git a/Billogram/Api/Models/BillogramClass.php b/Billogram/Api/Models/BillogramClass.php
@@ -53,9 +53,20 @@ public function __construct($api)
         $this->objectIdField = 'id';
     }
 
+    /**
+     * Makes a POST request to the API and creates a new object.
+     *
+     * @return \Billogram\Api\Objects\BillogramObject
+     **/
+    public function create($data)
+    {
+        return parent::create($data);
+    }
+
     /**
      * Creates and sends a billogram using the $data and $method supplied.
      *
+     * @return \Billogram\Api\Objects\BillogramObject
      **/
     public function createAndSend($data, $method)
     {
@@ -75,6 +86,7 @@ public function createAndSend($data, $method)
     /**
      * Creates and sells a billogram.
      *
+     * @return \Billogram\Api\Objects\BillogramObject
      **/
     public function createAndSell($data, $method)
     {

diff --git a/Billogram/Api/Models/SimpleClass.php b/Billogram/Api/Models/SimpleClass.php
@@ -36,6 +36,7 @@
  *
  * See the online documentation for the actual structure of remote objects.
  *
+ * @property \Billogram\Api $api
  **/
 class SimpleClass
 {
@@ -58,6 +59,7 @@ public function __construct($api, $urlName, $objectIdField)
     /**
      * Create a query for objects of this type.
      *
+     * @return \Billogram\Api\Query
      **/
     public function query()
     {
@@ -67,7 +69,7 @@ public function query()
     /**
      * Finds an object by id $objectId and returns an object.
      *
-     * @return void
+     * @return \Billogram\Api\Objects\SimpleObject
      **/
     public function get($objectId)
     {
@@ -80,7 +82,7 @@ public function get($objectId)
     /**
      * Makes a POST request to the API and creates a new object.
      *
-     * @return void
+     * @return \Billogram\Api\Objects\SimpleObject
      **/
     public function create($data)
     {
@@ -93,6 +95,7 @@ public function create($data)
     /**
      * Formats and returns a URL to an object or object id.
      *
+     * @return string
      **/
     public function url($object = null)
     {

diff --git a/Billogram/Api/Objects/BillogramObject.php b/Billogram/Api/Objects/BillogramObject.php
@@ -94,7 +94,6 @@ public function creditFull()
     /**
      * Creates a credit invoice for the remaining amount of the billogram.
      *
-     * @return void
      **/
     public function creditRemaining()
     {
@@ -181,7 +180,7 @@ public function resend($method = null)
      * or letter document. Will throw a ObjectNotFoundError with message
      * 'Object not available yet' if the PDF has not yet been generated.
      *
-     * @throws Billogram\Api\Exceptions\ObjectNotFoundError
+     * @throws \Billogram\Api\Exceptions\ObjectNotFoundError
      **/
     public function getInvoicePdf($letterId = null, $invoiceNo = null)
     {

diff --git a/Billogram/Api/Objects/SingletonObject.php b/Billogram/Api/Objects/SingletonObject.php
@@ -43,6 +43,8 @@
  *
  * See the online documentation for the actual structure of remote objects.
  *
+ * @property \Billogram\Api $api
+ * @property \Billogram\Api\Models\SimpleClass $objectClass
  **/
 class SingletonObject
 {

diff --git a/Billogram/Api/Query.php b/Billogram/Api/Query.php
@@ -39,6 +39,8 @@
  * The exact fields and special queries available for each object type varies,
  * see the online documentation for details.
  *
+ * @property \Billogram\Api $api
+ * @property \Billogram\Api\Models\SimpleClass $typeClass
  **/
 class Query
 {

diff --git a/examples.php b/examples.php
@@ -99,6 +99,7 @@ function autoload($className)
    already be sent out to the customer (via Letter, or Email). */
 echo 'Waiting for PDF to be generated, this may take a few seconds.' . "\n";
 do {
+    $pdfContent = '';
     try {
         $pdfContent = $billogramObject->getInvoicePdf();
         break;