Merge pull request #6 from rickkuilman/add-default-enterprise-id

Add ability to set a default enterprise for all requests
rickkuilman · Oct 23, 2021 · 8c8e4ad · 8c8e4ad
2 parents ccbc51b + 2f48099
commit 8c8e4ad
Show file tree

Hide file tree

Showing 12 changed files with 220 additions and 58 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,12 +2,18 @@
 
 All notable changes to `digital-humani-php-sdk` will be documented in this file
 
-## 1.0.0 - 2021-08-08
+## 2.0.0 - 2021-10-23
 
-- Initial release 🎉
+- Added ability to set a default enterprise for all requests
+- Added ability to plant a tree right from an Enterprise
 
 ## 1.1.0 - 2021-10-05
 
 - Refactored package to plain PHP package (removed Laravel specific files)
 - Added ability to switch between sandbox and production environment
 - Renamed package (and namespace) to emphasize the fact that this is a "PHP" SDK
+
+
+## 1.0.0 - 2021-08-08
+
+- Initial release 🎉
diff --git a/README.md b/README.md
@@ -14,69 +14,122 @@ composer require rickkuilman/digital-humani-php-sdk
 
 ## Preparation
 
-- Create a [sandbox](https://my.sandbox.digitalhumani.com/register) or [production](https://my.digitalhumani.com/register) account on DigitalHumani.com.
+- Create a [sandbox](https://my.sandbox.digitalhumani.com/register)
+  or [production](https://my.digitalhumani.com/register) account on DigitalHumani.com.
 - Grab your Enterprise ID and API Key from the "Developer" tab.
 
 ## Basic Usage
 
 ```php
-// Create new instance
-$digitalHumani = new DigitalHumani($apiKey);
+// Create new sandbox instance
+$digitalHumani = new DigitalHumani($apiKey, $enterpriseId);
 
 // Plant a tree
-$digitalHumani->plantTree($enterpriseId, 'rick@example.com');
+$digitalHumani->plantTree('rick@example.com');
+
+// Count trees planted
+$digitalHumani->treeCount();
 ```
 
-Using the `DigitalHumani` instance you may perform multiple actions as well as retrieve the different resources [DigitalHumani's API](https://digitalhumani.com/docs/) provides:
+Using the `DigitalHumani` instance you may perform multiple actions as well as retrieve the different
+resources [DigitalHumani's API](https://digitalhumani.com/docs/) provides:
 
 ### Managing Enterprises
 
 ```php
-// Get Enterprise by ID
-$enterprise = $digitalHumani->enterprise('4c6e672d')
-    ->treeCount(); // ..and count trees for this enterprise
+// Get current Enterprise
+$enterprise = $digitalHumani->enterprise();
+
+// .. or get Enterprise by ID
+$enterprise = $digitalHumani->enterprise('4c6e672d'); 
 
-// Count trees for a range of dates
-$enterprise->treeCount(Carbon::make('2021-01-01'), Carbon::make('2022-01-01'));
+// 🌳 Count planted trees 
+$enterprise->treeCount(); 
 
-// Count trees for specific month
+// 🌳 Count planted trees since 2021-01-01
+$enterprise->treeCount(Carbon::make('2021-01-01'));
+
+// 🌳 Count planted trees between 2021-01-01 and 2021-08-01
+$enterprise->treeCount(Carbon::make('2021-01-01'), Carbon::make('2022-08-01'));
+
+// 🌳 Count planted trees for specific month
 $enterprise->treeCountForMonth(Carbon::make('2021-08'));
+
+// 🌳 Plant tree
+$enterprise->plantTree('rick@example.com')
 ```
 
+#### Notice for lines with 🌳 icon:
+
+> Since the Enterprise ID is available in the DigitalHumani instance, you may replace `$enterprise`
+> with `$digitalHumani` and expect the same results.
+
 ### Managing Projects
 
 ```php
 // Get list of all Projects
-$digitalHumani->projects();
+$projects = $digitalHumani->projects();
+
+// Get second project
+$project = $projects[1];
 
-// Get Project by ID
-$digitalHumani->project('81818182')
-        ->plantTree('4c6e672d', 'rick@example.com', 3); // ..and plant tree
+// .. or get Project by ID
+$project = $digitalHumani->project('81818182');
+
+// Plant a tree for this project
+$project->plantTree('rick@example.com', 3);
 ```
 
 ### Managing Trees
 
 ```php
-// Plant one or many trees
-$digitalHumani->plantTree('4c6e672d', 'rick@example.com', 2);
+// Plant one tree
+$tree = $digitalHumani->plantTree('rick@example.com');
+
+// Plant ten trees
+$trees = $digitalHumani->plantTree('rick@example.com', 10);
 
-// Get details of a single request to plant one or many trees
+// Get UUID of tree(s)
+$uuid = $tree->uuid;
+
+// Get details of a planted tree (or trees) by ID
 $digitalHumani->tree('9f05511e-56c6-40f7-b5ca-e25567991dc1');
 
 // Count trees for a user
-$digitalHumani->countTreesPlantedByUser('4c6e672d', 'rick@example.com');
+$digitalHumani->countTreesPlantedByUser('rick@example.com');
 ```
 
 ### Switch to production environment
 
 ```php
-// Set the second parameter to "true"
-$digitalHumani = new DigitalHumani($apiKey, true);
+// Set the third parameter to "true"
+$digitalHumani = new DigitalHumani($apiKey, $enterpriseId, true);
 
 // ..or use a method
 $digitalHumani->useProductionEnvironment();
 ```
 
+### Overrule (default) project or enterprise
+
+Many methods allow additional parameters to overrule the (default) project or enterprise:
+
+```php
+// Create new sandbox instance, leaving out the enterpriseId
+$digitalHumani = new DigitalHumani($apiKey);
+
+// Plant a tree for a specific project and enterprise
+$digitalHumani->plantTree('rick@example.com', 1, $projectId, $enterpriseId);
+
+// Set a default enterprise afterwards, which will be used for all requests from now on
+$digitalHumani->setEnterprise('11111111');
+
+// Plant a tree for a specific project using the default enterprise from above
+$digitalHumani->plantTree('rick@example.com', 1, $projectId);
+
+// Count trees of a specific month for a specific enterprise, overruling the default
+$digitalHumani->treeCountForMonth(Carbon::make('2021-10'), '99999999');
+```
+
 Happy planting! 🌳
 
 ## Changelog
@@ -102,4 +155,5 @@ The MIT License (MIT). Please see [License File](LICENSE.md) for more informatio
 
 ## PHP Package Boilerplate
 
-This package was generated using the [PHP Package Boilerplate](https://laravelpackageboilerplate.com) by [Beyond Code](http://beyondco.de/).
+This package was generated using the [PHP Package Boilerplate](https://laravelpackageboilerplate.com)
+by [Beyond Code](http://beyondco.de/).
diff --git a/src/Actions/ManagesEnterprises.php b/src/Actions/ManagesEnterprises.php
@@ -3,30 +3,35 @@
 namespace Rickkuilman\DigitalHumaniPhpSdk\Actions;
 
 use Carbon\Carbon;
+use Exception;
 use Rickkuilman\DigitalHumaniPhpSdk\Resources\Enterprise;
 
 trait ManagesEnterprises
 {
     /**
      * Get Enterprise by ID
      *
-     * @param string $enterpriseId Id of the enterprise for which you want to get the details.
+     * @param string|null $enterpriseId Id of the enterprise for which you want to get the details.
      * @return Enterprise
+     * @throws Exception
      */
-    public function enterprise(string $enterpriseId): Enterprise
+    public function enterprise(string $enterpriseId = null): Enterprise
     {
-        return new Enterprise($this->get("enterprise/{$enterpriseId}"), $this);
+        return new Enterprise($this->get(sprintf("enterprise/%s",
+            $enterpriseId ?? $this->getDefaultEnterpriseId()
+        )), $this);
     }
 
     /**
      * Count trees for an enterprise for any range of date
      *
-     * @param string $enterpriseId Id of your enterprise.
      * @param Carbon|null $startDate Start Date of the range to specify
      * @param Carbon|null $endDate End Date of the range to specify
+     * @param string|null $enterpriseId Id of your enterprise.
      * @return int
+     * @throws Exception
      */
-    public function treeCount(string $enterpriseId, Carbon $startDate = null, Carbon $endDate = null): int
+    public function treeCount(Carbon $startDate = null, Carbon $endDate = null, string $enterpriseId = null): int
     {
 
         if (is_null($startDate)) {
@@ -38,7 +43,7 @@ public function treeCount(string $enterpriseId, Carbon $startDate = null, Carbon
         }
 
         return $this->get(sprintf("enterprise/%s/treeCount?startDate=%s&endDate=%s",
-            $enterpriseId,
+            $enterpriseId ?? $this->getDefaultEnterpriseId(),
             $startDate->format('Y-m-d'),
             $endDate->format('Y-m-d')
         ))['count'];
@@ -47,18 +52,19 @@ public function treeCount(string $enterpriseId, Carbon $startDate = null, Carbon
     /**
      * Count trees for an enterprise by month
      *
-     * @param string $enterpriseId Id of your enterprise.
      * @param Carbon|null $month Month for which you want to count the number of trees planted.
+     * @param string|null $enterpriseId Id of your enterprise.
      * @return int
+     * @throws Exception
      */
-    public function treeCountForMonth(string $enterpriseId, Carbon $month = null): int
+    public function treeCountForMonth(Carbon $month = null, string $enterpriseId = null): int
     {
         if (is_null($month)) {
             $month = today();
         }
 
         return $this->get(sprintf("enterprise/%s/treeCount/%s",
-            $enterpriseId,
+            $enterpriseId ?? $this->getDefaultEnterpriseId(),
             $month->format('Y-m')
         ))['count'];
     }

diff --git a/src/Actions/ManagesProjects.php b/src/Actions/ManagesProjects.php
@@ -2,6 +2,7 @@
 
 namespace Rickkuilman\DigitalHumaniPhpSdk\Actions;
 
+use Exception;
 use Rickkuilman\DigitalHumaniPhpSdk\Resources\Project;
 
 trait ManagesProjects
@@ -10,6 +11,7 @@ trait ManagesProjects
      * Get list of all Projects
      *
      * @return array
+     * @throws Exception
      */
     public function projects(): array
     {
@@ -23,6 +25,7 @@ public function projects(): array
      *
      * @param string $projectID Id of the reforestation project for which you want to get the details
      * @return Project
+     * @throws Exception
      */
     public function project(string $projectID): Project
     {

diff --git a/src/Actions/ManagesTrees.php b/src/Actions/ManagesTrees.php
@@ -2,29 +2,31 @@
 
 namespace Rickkuilman\DigitalHumaniPhpSdk\Actions;
 
+use Exception;
 use Rickkuilman\DigitalHumaniPhpSdk\Resources\Tree;
 
 trait ManagesTrees
 {
     /**
      * Plant one or many trees
      *
-     * @param string $enterpriseId Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise
-     * Ids are 8 digits long)
      * @param string $user End user by whom the trees were planted. Example of an user: email@test.com
      * @param int $amount Number of trees requested to plant. Example: 1
      * @param string|null $projectId Id of the reforestation project for where you want the trees to be planted.
      * Example of an id: 93333333 (Project Ids are 8 digits long)
+     * @param string|null $enterpriseId Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise
+     * Ids are 8 digits long)
      * @return Tree
+     * @throws Exception
      */
-    public function plantTree(string $enterpriseId, string $user, int $amount = 1, string $projectId = null): Tree
+    public function plantTree(string $user, int $amount = 1, string $projectId = null, string $enterpriseId = null): Tree
     {
         if (is_null($projectId)) {
             $projectId = $this->defaultProjectId();
         }
 
         return new Tree($this->post('tree', [
-            'enterpriseId' => $enterpriseId,
+            'enterpriseId' => $enterpriseId ?? $this->getDefaultEnterpriseId(),
             'user' => $user,
             'treeCount' => $amount,
             'projectId' => (string)$projectId,
@@ -36,6 +38,7 @@ public function plantTree(string $enterpriseId, string $user, int $amount = 1, s
      *
      * @param string $uuid uuid of the trees for which you want to get the details.
      * @return Tree
+     * @throws Exception
      */
     public function tree(string $uuid): Tree
     {
@@ -45,15 +48,16 @@ public function tree(string $uuid): Tree
     /**
      * Count trees for a user
      *
-     * @param string $enterpriseId Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise
-     * Ids are 8 digits long)
      * @param string $user End user by whom the trees were planted. Example of an user: email@test.com
+     * @param string|null $enterpriseId Id of your enterprise. Example of an enterprise id: 11111111 (Enterprise
+     * Ids are 8 digits long)
      * @return array
+     * @throws Exception
      */
-    public function countTreesPlantedByUser(string $enterpriseId, string $user): array
+    public function countTreesPlantedByUser(string $user, string $enterpriseId = null): array
     {
         return $this->get(sprintf("tree?enterpriseId=%s&user=%s",
-            $enterpriseId,
+            $enterpriseId ?? $this->getDefaultEnterpriseId(),
             $user
         ));
     }

diff --git a/src/DigitalHumani.php b/src/DigitalHumani.php
@@ -6,6 +6,7 @@
 use Rickkuilman\DigitalHumaniPhpSdk\Actions\ManagesEnterprises;
 use Rickkuilman\DigitalHumaniPhpSdk\Actions\ManagesProjects;
 use Rickkuilman\DigitalHumaniPhpSdk\Actions\ManagesTrees;
+use Rickkuilman\DigitalHumaniPhpSdk\Resources\Enterprise;
 
 class DigitalHumani
 {
@@ -39,17 +40,26 @@ class DigitalHumani
      */
     public string $baseUrl;
 
+    /**
+     * @var string|null
+     */
+    public ?string $enterpriseId = null;
+
     /**
      * Create a new Forge instance.
      *
      * @param string|null $apiKey
      * @param HttpClient|null $guzzle
      * @return void
      */
-    public function __construct(string $apiKey = null, bool $useProduction = false, HttpClient $guzzle = null)
+    public function __construct(string $apiKey = null, string $defaultEnterpriseId = null, bool $useProduction = false, HttpClient $guzzle = null)
     {
         $this->useProductionEnvironment($useProduction);
 
+        if (!is_null($defaultEnterpriseId)) {
+            $this->setEnterprise($defaultEnterpriseId);
+        }
+
         if (!is_null($apiKey)) {
             $this->setApiKey($apiKey, $guzzle);
         }
@@ -142,6 +152,26 @@ public function setBaseUrl(string $baseUrl)
         $this->baseUrl = $baseUrl;
     }
 
+    /**
+     * Set enterprise by id or instance
+     *
+     * @param string|Enterprise $enterprise
+     */
+    public function setEnterprise($enterprise)
+    {
+        $this->enterpriseId = $enterprise instanceof Enterprise
+            ? $enterprise->id
+            : $enterprise;
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getDefaultEnterpriseId(): ?string
+    {
+        return $this->enterpriseId;
+    }
+
     /**
      * Returns whether the production environment is used.
      *