new service to handle multi entity levels

docs/sample/code/test.php

@@ -0,0 +1,98 @@
+<?php
+/**
+ * Copyright © Thomas Klein, All rights reserved.
+ * See LICENSE bundled with this library for license details.
+ */
+declare(strict_types=1);
+
+include __DIR__ . '/../../../vendor/autoload.php';
+
+use Zoho\Desk\Api\Metadata;
+use Zoho\Desk\Client\ConfigProviderBuilder;
+use Zoho\Desk\Exception\CouldNotDeleteException;
+use Zoho\Desk\Exception\CouldNotReadException;
+use Zoho\Desk\Exception\CouldNotSaveException;
+use Zoho\Desk\Gateway;
+use Zoho\Desk\Model\ListCriteria;
+use Zoho\Desk\Model\ListCriteriaBuilder;
+use Zoho\OAuth\ZohoOAuth;
+
+// Optional, it's used by the zoho/oauth package
+define('LOGGER_PATH', __DIR__ . '/');
+
+$configBuilder = ConfigProviderBuilder::getInstance();
+$configBuilder->setClientId('1000.51C3ETBOWTOA03UL19U5EMV0F74VQR')
+    ->setClientSecret('4086937c603d0e174ee58d5b6d9b21fb6b93802fd8')
+    ->setRedirectUrl('')
+    ->setCurrentUserEmail('[email protected]')
+    ->setApiBaseUrl(Metadata::API_ENDPOINT_EU)
+    ->setApiVersion(Metadata::API_VERSION)
+    ->setOrgId(20076919967)
+    ->setIsSandbox(false)
+    ->setAccountsUrl(Metadata::API_ACCOUNTS_EU)
+    ->setTokenPersistencePath(__DIR__);
+
+$config = $configBuilder->create();
+$gateway = new Gateway($config);
+
+// Optional: if you need to register the token first
+// ZohoOAuth::initialize($config->get());
+// ZohoOAuth::getClientInstance()->generateAccessToken('1000.125d9d14ca4c42d8c3be5164d19433a8.c6c3be950b0290639f5126f5d9ff810b');
+
+
+try {
+    $criteriaBuilder = new ListCriteriaBuilder();
+    $criteriaBuilder->setFields(['id','subject', 'email', 'description','webUrl']);
+    // $criteriaBuilder->setFields()->setFilters()...
+    $ticketList = $gateway->getOperationPool()->getListOperation('tickets')->getList($criteriaBuilder->create());
+    //$ticketList = $gateway->getOperationPool()->getListOperation('tickets')->getByIds([1,2,3]);
+} catch (CouldNotReadException $e) {
+    echo $e->getMessage();
+    echo "<br>";
+    echo $e->getPrevious()->getMessage();
+}
+
+echo '<pre>';
+foreach ($ticketList as $ticket) {
+    echo '<hr>';
+    print_r($ticket->toArray());
+}
+
+ die;
+
+/** CRUD Operations **/
+
+$ticketDataObject = $gateway->getDataObjectFactory()->create('tickets', /* Entity values */);
+
+try {
+    $ticketDataObject = $gateway->getOperationPool()->getCreateOperation('tickets')->create($ticketDataObject);
+} catch (CouldNotSaveException $e) {
+    // Handle the exception...
+}
+
+try {
+    $ticketDataObject = $gateway->getOperationPool()->getReadOperation('tickets')->get(1234);
+} catch (CouldNotReadException $e) {
+    // Handle the exception...
+}
+
+try {
+    $criteriaBuilder = new ListCriteriaBuilder();
+    // $criteriaBuilder->setFields()->setFilters()...
+    $ticketList = $gateway->getOperationPool()->getListOperation('tickets')->getList($criteriaBuilder->create());
+    $ticketList = $gateway->getOperationPool()->getListOperation('tickets')->getByIds([1,2,3]);
+} catch (CouldNotReadException $e) {
+    // Handle the exception...
+}
+
+try {
+    $ticketDataObject = $gateway->getOperationPool()->getUpdateOperation('tickets')->update($ticketDataObject);
+} catch (CouldNotSaveException $e) {
+    // Handle the exception...
+}
+
+try {
+    $gateway->getOperationPool()->getDeleteOperation('tickets', ['resolution'])->delete(1234);
+} catch (CouldNotDeleteException $e) {
+    // Handle the exception...
+}

docs/sample/code/zoho_oauth.log

@@ -0,0 +1 @@
+2021-03-24 09:14:01 INFO: Access Token has expired. Hence refreshing.

src/Client/RequestBuilder.php

@@ -12,14 +12,20 @@
 use Zoho\Desk\Exception\Exception;
 use Zoho\Desk\Exception\InvalidArgumentException;
 use Zoho\Desk\OAuth\ClientInterface;
+
+use function array_keys;
+use function array_map;
 use function array_merge;
+use function array_values;
 use function curl_init;
 use function curl_setopt;
 use function http_build_query;
 use function is_array;
 use function is_numeric;
 use function json_encode;
 use function sprintf;
+use function str_replace;
+
 use const CURLOPT_CUSTOMREQUEST;
 use const CURLOPT_HEADER;
 use const CURLOPT_HTTPHEADER;
@@ -61,13 +67,25 @@ public function __construct(ClientInterface $client, array $mandatoryData = [])
         $this->data = [];
     }
 
+    /**
+     * @deprecated
+     */
     public function setEntityType(string $entityType): self
     {
         $this->data['entityType'] = $entityType;
 
         return $this;
     }
 
+    public function setPath(string $path, array $bind = []): self
+    {
+        $search = array_map(static function (string $variable): string {
+            return '{' . $variable . '}';
+        }, array_keys($bind));
+
+        return $this->setEntityType(str_replace($search, array_values($bind), $path));
+    }
+
     public function setMethod(string $method): self
     {
         $this->data['method'] = $method;

src/Model/Operation/CreateOperationInterface.php

@@ -12,6 +12,7 @@
 
 /**
  * @api
+ * @deprecated
  */
 interface CreateOperationInterface
 {

src/Model/Operation/DeleteOperationInterface.php

@@ -11,6 +11,7 @@
 
 /**
  * @api
+ * @deprecated
  */
 interface DeleteOperationInterface
 {

src/Model/Operation/ListOperationInterface.php

@@ -13,6 +13,7 @@
 
 /**
  * @api
+ * @deprecated
  */
 interface ListOperationInterface
 {

src/Model/Operation/ReadOperationInterface.php

@@ -12,6 +12,7 @@
 
 /**
  * @api
+ * @deprecated
  */
 interface ReadOperationInterface
 {

src/Model/Operation/UpdateOperationInterface.php

@@ -12,6 +12,7 @@
 
 /**
  * @api
+ * @deprecated
  */
 interface UpdateOperationInterface
 {

src/Model/OperationPool.php

@@ -21,6 +21,9 @@
 use function implode;
 use function md5;
 
+/**
+ * @deprecated
+ */
 final class OperationPool
 {
     private RequestBuilder $requestBuilder;

src/Service/CreateOperation.php

@@ -0,0 +1,76 @@
+<?php
+/**
+ * Copyright © Thomas Klein, All rights reserved.
+ * See LICENSE bundled with this library for license details.
+ */
+declare(strict_types=1);
+
+namespace Zoho\Desk\Service;
+
+use Zoho\Desk\Client\RequestBuilder;
+use Zoho\Desk\Client\ResponseInterface;
+use Zoho\Desk\Exception\CouldNotSaveException;
+use Zoho\Desk\Exception\Exception;
+use Zoho\Desk\Exception\InvalidArgumentException;
+use Zoho\Desk\Exception\InvalidRequestException;
+use Zoho\Desk\Model\DataObjectFactory;
+use Zoho\Desk\Model\DataObjectInterface;
+
+final class CreateOperation implements CreateOperationInterface
+{
+    private RequestBuilder $requestBuilder;
+
+    private DataObjectFactory $dataObjectFactory;
+
+    private string $entityType;
+
+    private ?string $path;
+
+    /**
+     * @var string[]
+     */
+    private array $arguments;
+
+    public function __construct(
+        RequestBuilder $requestBuilder,
+        DataObjectFactory $dataObjectFactory,
+        string $entityType,
+        ?string $path = null,
+        array $arguments = []
+    ) {
+        $this->requestBuilder = $requestBuilder;
+        $this->dataObjectFactory = $dataObjectFactory;
+        $this->entityType = $entityType;
+        $this->path = $path;
+        $this->arguments = $arguments;
+    }
+
+    public function create(DataObjectInterface $dataObject, array $bind = []): DataObjectInterface
+    {
+        try {
+            return $this->dataObjectFactory->create($this->entityType, $this->saveEntity($dataObject)->getResult());
+        } catch (InvalidArgumentException $e) {
+            throw new CouldNotSaveException($e->getMessage(), $e->getCode(), $e);
+        } catch (InvalidRequestException $e) {
+            throw new CouldNotSaveException($e->getMessage(), $e->getCode(), $e);
+        } catch (Exception $e) {
+            throw new CouldNotSaveException('Could not create the entity.', $e->getCode(), $e);
+        }
+    }
+
+    /**
+     * @throws Exception
+     * @throws InvalidArgumentException
+     * @throws InvalidRequestException
+     */
+    private function saveEntity(DataObjectInterface $dataObject, array $bind = []): ResponseInterface
+    {
+        return $this->requestBuilder
+            ->setPath($this->path ?? $this->entityType, $bind)
+            ->setMethod(RequestBuilder::HTTP_POST)
+            ->setArguments($this->arguments)
+            ->setFields($dataObject->toArray())
+            ->create()
+            ->execute();
+    }
+}

src/Service/CreateOperationInterface.php

@@ -0,0 +1,22 @@
+<?php
+/**
+ * Copyright © Thomas Klein, All rights reserved.
+ * See LICENSE bundled with this library for license details.
+ */
+declare(strict_types=1);
+
+namespace Zoho\Desk\Service;
+
+use Zoho\Desk\Exception\CouldNotSaveException;
+use Zoho\Desk\Model\DataObjectInterface;
+
+/**
+ * @api
+ */
+interface CreateOperationInterface
+{
+    /**
+     * @throws CouldNotSaveException
+     */
+    public function create(DataObjectInterface $dataObject, array $bind = []): DataObjectInterface;
+}

src/Service/DeleteOperation.php

@@ -0,0 +1,70 @@
+<?php
+/**
+ * Copyright © Thomas Klein, All rights reserved.
+ * See LICENSE bundled with this library for license details.
+ */
+declare(strict_types=1);
+
+namespace Zoho\Desk\Service;
+
+use Zoho\Desk\Client\RequestBuilder;
+use Zoho\Desk\Exception\CouldNotDeleteException;
+use Zoho\Desk\Exception\Exception;
+use Zoho\Desk\Exception\InvalidArgumentException;
+use Zoho\Desk\Exception\InvalidRequestException;
+use function array_merge;
+use function reset;
+use function rtrim;
+use function sprintf;
+
+final class DeleteOperation implements DeleteOperationInterface
+{
+    private RequestBuilder $requestBuilder;
+
+    private string $entityType;
+
+    private ?string $path;
+
+    /**
+     * @var string[]
+     */
+    private array $arguments;
+
+    public function __construct(
+        RequestBuilder $requestBuilder,
+        string $entityType,
+        ?string $path = null,
+        array $arguments = []
+    ) {
+        $this->requestBuilder = $requestBuilder;
+        $this->entityType = $entityType;
+        $this->path = $path;
+        $this->arguments = $arguments;
+    }
+
+    public function delete(array $bind): void
+    {
+        try {
+            $this->requestBuilder
+                ->setPath($this->path ?? $this->entityType, $bind)
+                ->setMethod(RequestBuilder::HTTP_DELETE)
+                ->setArguments($this->path ? $this->arguments : array_merge([reset($bind)], $this->arguments))
+                ->create()
+                ->execute();
+        } catch (InvalidArgumentException $e) {
+            throw new CouldNotDeleteException($e->getMessage(), $e->getCode(), $e);
+        } catch (InvalidRequestException $e) {
+            throw new CouldNotDeleteException($e->getMessage(), $e->getCode(), $e);
+        } catch (Exception $e) {
+            $flatten = '';
+            foreach ($bind as $key => $value) {
+                $flatten .= sprintf('%s: %s ', $key, $value);
+            }
+            throw new CouldNotDeleteException(
+                sprintf('Could not delete the entity with %s.', rtrim($flatten)),
+                $e->getCode(),
+                $e
+            );
+        }
+    }
+}

src/Service/DeleteOperationInterface.php

@@ -0,0 +1,21 @@
+<?php
+/**
+ * Copyright © Thomas Klein, All rights reserved.
+ * See LICENSE bundled with this library for license details.
+ */
+declare(strict_types=1);
+
+namespace Zoho\Desk\Service;
+
+use Zoho\Desk\Exception\CouldNotDeleteException;
+
+/**
+ * @api
+ */
+interface DeleteOperationInterface
+{
+    /**
+     * @throws CouldNotDeleteException
+     */
+    public function delete(array $bind): void;
+}