Merge pull request #67 from turbo124/main

Documentation for SDK v5
invoiceninja · Sep 16, 2021 · 4920688 · 4920688
2 parents 911edc4 + ae3fb84
commit 4920688
Show file tree

Hide file tree

Showing 16 changed files with 289 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -32,6 +32,37 @@ Retrieve all clients
     $clients = $ninja->clients->all();
 ```
 
+You can perform complex filtering on the ->all() method. 
+
+Query parameters can be chained together to form complex queries. The current supported values are:
+
+**per_page**: The number of clients per page you want returned  
+**page**: The page number  
+**include**: A comma separated list of relations to include ie. contacts,documents,gateway_tokens  
+**balance**: A query to return clients with a balance using an operator and value  
+ - ie ?balance=lt:10 Returns clients with a balance less than 10  
+ - available operators lt, lte, gt, gte, eq  
+**between_balance**: Returns clients with a balance between two values  
+ - ie ?between_balance=10:20 - Returns clients with a balance between 10 and 20  
+**email**: Returns clients with a contacts.email field equal to an email  
+**id_number**: Search by id_number  
+**number**: Search by number  
+**filter**: Search across multiple columns (name, id_number, first_name, last_name, email, custom_value1, custom_value2, custom_value3, custom_value4)  
+**created_at**: Search by created at (Unix timestamp)  
+**is_deleted**: Search using is_deleted boolean flag  
+
+For example,
+
+```php
+$clients = $ninja->clients->all([
+    'balance' => 'lt:10', // get all clients with a balance less than 10
+    'per_page' => 10, // return 10 results per page
+    'page' => 2, // paginate to page 2
+    'include' => 'documents', // include the documents relationship
+]);
+
+```
+
 Retrieve a client by its primary key.
 ```php
     $client = $ninja->clients->get("CLIENT_HASHED_ID");
@@ -59,7 +90,54 @@ Create an invoice
     $client = $ninja->invoices->create(['client_id' => CLIENT_HASHED_ID]);
 
 ```
-Download an invoice PDF
+
+When creating an invoice, you can perform actions on the invoice in a single call, for example, say you wish to create an invoice and also apply a payment to the invoice:
+
+```php
+    $invoice = $ninja->invoices->create(['client_id'=> 'CLIENT_HASHED_ID'], ['mark_paid' => true]);
+```
+
+Or if you wish to apply a partial payment
+
+```php
+    $invoice = $ninja->invoices->create(['client_id'=> 'CLIENT_HASHED_ID'], ['amount_paid' => 10]);
+```
+
+Or you may want to automatically send and charge the invoice **note requires a payment method on file**
+```php
+    $invoice = $ninja->invoices->create(['client_id'=> 'CLIENT_HASHED_ID'], ['auto_bill' => true, 'send_email' => true]);
+```
+
+
+### Bulk actions
+
+You can perform bulk actions against one or many entities. For example if you wish to batch archive a range of invoice you would do
+
+```php
+  $bulk = $ninja->invoices->archive(["hash_1","hash_2"]);
+```
+
+You can access the raw bulk method using the following:
+
+```php  
+$bulk = $ninja->invoices->bulk("archive", ["hash_1","hash_2"]);
+```
+
+If you wanted to download a invoice PDF
 ```php
-    $pdf = $invoice->download();
-```
+    $pdf = $ninja->invoices->bulk("download", ["hash_1"]);
+```
+
+The following are a list of available bulk actions for invoices:
+
++ mark_sent
++ download
++ restore
++ archive
++ delete
++ mark_paid
++ clone_to_quote
++ clone_to_invoice
++ cancel
++ reverse
++ email
diff --git a/composer.json b/composer.json
@@ -17,6 +17,7 @@
         "guzzlehttp/guzzle": "^7.3"
     },
     "require-dev": {
+        "fakerphp/faker": "^1.16",
         "phpunit/phpunit": "^9.5"
     },
     "autoload-dev": {

diff --git a/src/Endpoints/BaseEntity.php b/src/Endpoints/BaseEntity.php
@@ -0,0 +1,43 @@
+<?php
+/**
+ * Invoice Ninja (https://invoiceninja.com).
+ *
+ * @link https://github.com/invoiceninja/sdk-php source repository
+ *
+ * @copyright Copyright (c) 2021. Invoice Ninja LLC (https://invoiceninja.com)
+ *
+ * @license https://opensource.org/licenses/MIT
+ */
+
+namespace InvoiceNinja\Sdk\Endpoints;
+
+use GuzzleHttp\Exception\GuzzleException;
+use InvoiceNinja\Sdk\InvoiceNinja;
+
+class BaseEntity
+{
+
+    public function bulk(string $action, array $ids)
+    {
+        $query['form_params'] = ["action" => $action, "ids" => $ids];
+
+        return $this->ninja->send("POST", "{$this->uri}/bulk", $query);
+    }
+
+    public function archive(array $entity_array)
+    {
+        return $this->bulk("archive", $entity_array);
+    }
+
+    public function delete(array $entity_array)
+    {
+        return $this->bulk("delete", $entity_array);
+    }
+
+    public function restore(array $entity_array)
+    {
+        return $this->bulk("restore", $entity_array);
+    }
+
+}
+
diff --git a/src/Endpoints/Clients.php b/src/Endpoints/Clients.php
@@ -14,11 +14,13 @@
 use GuzzleHttp\Exception\GuzzleException;
 use InvoiceNinja\Sdk\InvoiceNinja;
 
-class Clients
+class Clients extends BaseEntity
 {
 
     protected InvoiceNinja $ninja;
 
+    protected string $uri = "/api/v1/clients";
+
     public function __construct(InvoiceNinja $ninja)
     {
         $this->ninja = $ninja;
@@ -33,28 +35,28 @@ public function all(array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/clients", $query);
+        return $this->ninja->send("GET", "{$this->uri}", $query);
     }
 
     public function get(string $client_id, array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/clients/{$client_id}", $query);
+        return $this->ninja->send("GET", "{$this->uri}/{$client_id}", $query);
     }
 
     public function update(string $client_id, array $client)
     {
         $query = ['form_params' => $client];
 
-        return $this->ninja->send("PUT", "/api/v1/clients/{$client_id}", $query);
+        return $this->ninja->send("PUT", "{$this->uri}/{$client_id}", $query);
     }
 
     public function create(array $client, array $includes = [])
     {
         $query = ['form_params' => $client, 'query' => $includes];
 
-        return $this->ninja->send("POST", "/api/v1/clients", $query);
+        return $this->ninja->send("POST", "{$this->uri}", $query);
     }
 }
 
diff --git a/src/Endpoints/Invoices.php b/src/Endpoints/Invoices.php
@@ -14,11 +14,13 @@
 use GuzzleHttp\Exception\GuzzleException;
 use InvoiceNinja\Sdk\InvoiceNinja;
 
-class Invoices
+class Invoices extends BaseEntity
 {
 
     protected InvoiceNinja $ninja;
 
+    protected string $uri = "/api/v1/invoices";
+
     public function __construct(InvoiceNinja $ninja)
     {
         $this->ninja = $ninja;
@@ -33,28 +35,28 @@ public function all(array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/invoices", $query);
+        return $this->ninja->send("GET", "{$this->uri}", $query);
     }
 
     public function get(string $invoice_id, array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/invoices/{$invoice_id}", $query);
+        return $this->ninja->send("GET", "{$this->uri}/{$invoice_id}", $query);
     }
 
     public function update(string $invoice_id, array $invoices)
     {
         $query = ['form_params' => $invoices];
 
-        return $this->ninja->send("PUT", "/api/v1/invoices/{$invoice_id}", $query);
+        return $this->ninja->send("PUT", "{$this->uri}/{$invoice_id}", $query);
     }
 
     public function create(array $invoices, array $includes = [])
     {
         $query = ['form_params' => $invoices, 'query' => $includes];
 
-        return $this->ninja->send("POST", "/api/v1/invoices", $query);
+        return $this->ninja->send("POST", "{$this->uri}", $query);
     }
 }
 
diff --git a/src/Endpoints/Payments.php b/src/Endpoints/Payments.php
@@ -14,11 +14,13 @@
 use GuzzleHttp\Exception\GuzzleException;
 use InvoiceNinja\Sdk\InvoiceNinja;
 
-class Payments
+class Payments extends BaseEntity
 {
 
     protected InvoiceNinja $ninja;
 
+    protected string $uri = "/api/v1/payments";
+
     public function __construct(InvoiceNinja $ninja)
     {
         $this->ninja = $ninja;
@@ -33,28 +35,28 @@ public function all(array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/payments", $query);
+        return $this->ninja->send("GET", "{$this->uri}", $query);
     }
 
     public function get(string $payment_id, array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/payments/{$payment_id}", $query);
+        return $this->ninja->send("GET", "{$this->uri}/{$payment_id}", $query);
     }
 
     public function update(string $payment_id, array $payment)
     {
         $query = ['form_params' => $payment];
 
-        return $this->ninja->send("PUT", "/api/v1/payments/{$payment_id}", $query);
+        return $this->ninja->send("PUT", "{$this->uri}/{$payment_id}", $query);
     }
 
     public function create(array $payment, array $includes = [])
     {
         $query = ['form_params' => $payment, 'query' => $includes];
 
-        return $this->ninja->send("POST", "/api/v1/payments", $query);
+        return $this->ninja->send("POST", "{$this->uri}", $query);
     }
 }
 
diff --git a/src/Endpoints/Products.php b/src/Endpoints/Products.php
@@ -14,11 +14,13 @@
 use GuzzleHttp\Exception\GuzzleException;
 use InvoiceNinja\Sdk\InvoiceNinja;
 
-class Products
+class Products extends BaseEntity
 {
 
     protected InvoiceNinja $ninja;
 
+    protected string $uri = "/api/v1/products";
+
     public function __construct(InvoiceNinja $ninja)
     {
         $this->ninja = $ninja;
@@ -33,28 +35,28 @@ public function all(array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/products", $query);
+        return $this->ninja->send("GET", "{$this->uri}", $query);
     }
 
     public function get(string $product_id, array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/products/{$product_id}", $query);
+        return $this->ninja->send("GET", "{$this->uri}/{$product_id}", $query);
     }
 
     public function update(string $product_id, array $product)
     {
         $query = ['form_params' => $product];
 
-        return $this->ninja->send("PUT", "/api/v1/products/{$product_id}", $query);
+        return $this->ninja->send("PUT", "{$this->uri}/{$product_id}", $query);
     }
 
     public function create(array $product, array $includes = [])
     {
         $query = ['form_params' => $product, 'query' => $includes];
 
-        return $this->ninja->send("POST", "/api/v1/products", $query);
+        return $this->ninja->send("POST", "{$this->uri}", $query);
     }
 }
 
diff --git a/src/Endpoints/Quotes.php b/src/Endpoints/Quotes.php
@@ -14,11 +14,13 @@
 use GuzzleHttp\Exception\GuzzleException;
 use InvoiceNinja\Sdk\InvoiceNinja;
 
-class Quotes
+class Quotes extends BaseEntity
 {
 
     protected InvoiceNinja $ninja;
 
+    protected string $uri = "/api/v1/quotes";
+
     public function __construct(InvoiceNinja $ninja)
     {
         $this->ninja = $ninja;
@@ -33,28 +35,28 @@ public function all(array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/quotes", $query);
+        return $this->ninja->send("GET", "{$this->uri}", $query);
     }
 
     public function get(string $quote_id, array $search = [])
     {
         $query = ['query' => $search];
 
-        return $this->ninja->send("GET", "/api/v1/quotes/{$quote_id}", $query);
+        return $this->ninja->send("GET", "{$this->uri}/{$quote_id}", $query);
     }
 
     public function update(string $quote_id, array $quote)
     {
         $query = ['form_params' => $quote];
 
-        return $this->ninja->send("PUT", "/api/v1/quotes/{$quote_id}", $query);
+        return $this->ninja->send("PUT", "{$this->uri}/{$quote_id}", $query);
     }
 
     public function create(array $entity, array $includes = [])
     {
         $query = ['form_params' => $entity, 'query' => $includes];
 
-        return $this->ninja->send("POST", "/api/v1/quotes", $query);
+        return $this->ninja->send("POST", "{$this->uri}", $query);
     }
 }