new service to handle multi entity levels

.gitignore

@@ -1,3 +1,4 @@
+/docs/sample/code/test.php
 /vendor/
 .php_cs.cache
 composer.lock

docs/sample/code/index.php

@@ -34,6 +34,7 @@
 
 $config = $configBuilder->create();
 $gateway = new Gateway($config);
+$serviceFactory = $gateway->getServiceFactory();
 
 // Optional: if you need to register the token first
 // ZohoOAuth::initialize($config->get());
@@ -42,36 +43,41 @@
 /** CRUD Operations **/
 
 $ticketDataObject = $gateway->getDataObjectFactory()->create('tickets', /* Entity values */);
+$threadDataObject = $gateway->getDataObjectFactory()->create('threads', /* Entity values */);
 
 try {
-    $ticketDataObject = $gateway->getOperationPool()->getCreateOperation('tickets')->create($ticketDataObject);
+    $ticketDataObject = $serviceFactory->createOperation('tickets')->create($ticketDataObject);
+    $threadDataObject = $serviceFactory->createOperation('threads', 'tickets/{ticket_id}/threads')->create($threadDataObject, ['ticket_id' => $ticketDataObject->getEntityId()]);
 } catch (CouldNotSaveException $e) {
     // Handle the exception...
 }
 
 try {
-    $ticketDataObject = $gateway->getOperationPool()->getReadOperation('tickets')->get(1234);
+    $ticketDataObject = $serviceFactory->readOperation('tickets')->get([1234]);
+    $threadDataObject = $serviceFactory->readOperation('threads', 'tickets/{ticket_id}/threads/{thread_id}')->get(['ticket_id' => 1234, 'thread_id' => 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]);
+    // $criteriaBuilder->setFields(...)->setFilters(...)...
+    $ticketList = $serviceFactory->listOperation('tickets')->getList($criteriaBuilder->create());
+    $threadList = $serviceFactory->listOperation('threads', 'tickets/{ticket_id}/threads')->getList($criteriaBuilder->create(), ['ticket_id' => 1234]);
 } catch (CouldNotReadException $e) {
     // Handle the exception...
 }
 
 try {
-    $ticketDataObject = $gateway->getOperationPool()->getUpdateOperation('tickets')->update($ticketDataObject);
+    $ticketDataObject = $serviceFactory->updateOperation('tickets')->update($ticketDataObject);
+    $ticketDataObject = $serviceFactory->updateOperation('threads', 'tickets/{ticket_id}/threads/{thread_id}')->update($threadDataObject, ['ticket_id' => 1234, 'thread_id' => $threadDataObject->getEntityId()]);
 } catch (CouldNotSaveException $e) {
     // Handle the exception...
 }
 
 try {
-    $gateway->getOperationPool()->getDeleteOperation('tickets', ['resolution'])->delete(1234);
+    $serviceFactory->deleteOperation('tickets', null, ['resolution'])->delete([1234]);
+    $serviceFactory->deleteOperation('threads', 'tickets/{ticket_id}/threads/{thread_id}')->delete(['ticket_id' => 1234, 'thread_id' => 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;
@@ -35,7 +41,7 @@ final class RequestBuilder
     public const HTTP_PATCH = 'PATCH';
     public const HTTP_DELETE = 'DELETE';
 
-    private const MANDATORY_FIELDS = ['entityType', 'method'];
+    private const MANDATORY_FIELDS = ['path', 'method'];
 
     private ClientInterface $client;
 
@@ -61,9 +67,23 @@ public function __construct(ClientInterface $client, array $mandatoryData = [])
         $this->data = [];
     }
 
+    /**
+     * @deprecated
+     */
     public function setEntityType(string $entityType): self
     {
-        $this->data['entityType'] = $entityType;
+        $this->data['path'] = $entityType;
+
+        return $this;
+    }
+
+    public function setPath(string $path, array $bind = []): self
+    {
+        $search = array_map(static function (string $variable): string {
+            return '{' . $variable . '}';
+        }, array_keys($bind));
+
+        $this->data['path'] = str_replace($search, array_values($bind), $path);
 
         return $this;
     }
@@ -153,7 +173,7 @@ private function buildUrl(): string
             'https://%s/%s/%s',
             $this->client->getApiBaseUrl(),
             $this->client->getApiVersion(),
-            $this->data['entityType']
+            $this->data['path']
         );
 
         if (isset($this->data['arguments']) && is_array($this->data['arguments'])) {

src/Gateway.php

@@ -12,38 +12,51 @@
 use Zoho\Desk\Model\DataObjectFactory;
 use Zoho\Desk\Model\OperationPool;
 use Zoho\Desk\OAuth\Client;
+use Zoho\Desk\Service\ServiceFactory;
 
 /**
  * @api
  */
 final class Gateway
 {
+    private Client $client;
+
+    private RequestBuilder $requestBuilder;
+
     private DataObjectFactory $dataObjectFactory;
 
     private OperationPool $operationPool;
 
-    private Client $client;
-
-    private RequestBuilder $requestBuilder;
+    private ServiceFactory $serviceFactory;
 
     public function __construct(ConfigProviderInterface $configProvider, array $registeredEntityTypes = [])
     {
-        $this->dataObjectFactory = new DataObjectFactory($registeredEntityTypes);
         $this->client = new Client($configProvider);
         $this->requestBuilder = new RequestBuilder($this->client);
+        $this->dataObjectFactory = new DataObjectFactory($registeredEntityTypes);
         $this->operationPool = new OperationPool($this->requestBuilder, $this->dataObjectFactory);
+        $this->serviceFactory = new ServiceFactory($this->requestBuilder, $this->dataObjectFactory);
     }
 
     public function getDataObjectFactory(): DataObjectFactory
     {
         return $this->dataObjectFactory;
     }
 
+    /**
+     * @deprecated
+     * @see Gateway::getServiceFactory
+     */
     public function getOperationPool(): OperationPool
     {
         return $this->operationPool;
     }
 
+    public function getServiceFactory(): ServiceFactory
+    {
+        return $this->serviceFactory;
+    }
+
     public function getClient(): Client
     {
         return $this->client;

src/Model/Operation/CreateOperation.php

@@ -16,6 +16,10 @@
 use Zoho\Desk\Model\DataObjectFactory;
 use Zoho\Desk\Model\DataObjectInterface;
 
+/**
+ * @deprecated
+ * @see \Zoho\Desk\Service\CreateOperation
+ */
 final class CreateOperation implements CreateOperationInterface
 {
     private RequestBuilder $requestBuilder;

src/Model/Operation/CreateOperationInterface.php

@@ -12,6 +12,8 @@
 
 /**
  * @api
+ * @deprecated
+ * @see \Zoho\Desk\Service\CreateOperationInterface
  */
 interface CreateOperationInterface
 {

src/Model/Operation/DeleteOperation.php

@@ -15,6 +15,10 @@
 use function array_merge;
 use function sprintf;
 
+/**
+ * @deprecated
+ * @see \Zoho\Desk\Service\DeleteOperation
+ */
 final class DeleteOperation implements DeleteOperationInterface
 {
     private RequestBuilder $requestBuilder;

src/Model/Operation/DeleteOperationInterface.php

@@ -11,6 +11,8 @@
 
 /**
  * @api
+ * @deprecated
+ * @see \Zoho\Desk\Service\DeleteOperationInterface
  */
 interface DeleteOperationInterface
 {

src/Model/Operation/ListOperation.php

@@ -20,6 +20,10 @@
 use function implode;
 use function is_array;
 
+/**
+ * @deprecated
+ * @see \Zoho\Desk\Service\ListOperation
+ */
 final class ListOperation implements ListOperationInterface
 {
     private RequestBuilder $requestBuilder;

src/Model/Operation/ListOperationInterface.php

@@ -13,6 +13,8 @@
 
 /**
  * @api
+ * @deprecated
+ * @see \Zoho\Desk\Service\ListOperationInterface
  */
 interface ListOperationInterface
 {

src/Model/Operation/ReadOperation.php

@@ -17,6 +17,10 @@
 use Zoho\Desk\Model\DataObjectInterface;
 use function array_merge;
 
+/**
+ * @deprecated
+ * @see \Zoho\Desk\Service\ReadOperation
+ */
 final class ReadOperation implements ReadOperationInterface
 {
     private RequestBuilder $requestBuilder;

src/Model/Operation/ReadOperationInterface.php

@@ -12,6 +12,8 @@
 
 /**
  * @api
+ * @deprecated
+ * @see \Zoho\Desk\Service\ReadOperationInterface
  */
 interface ReadOperationInterface
 {

src/Model/Operation/UpdateOperation.php

@@ -18,6 +18,10 @@
 use function array_merge;
 use function sprintf;
 
+/**
+ * @deprecated
+ * @see \Zoho\Desk\Service\UpdateOperation
+ */
 final class UpdateOperation implements UpdateOperationInterface
 {
     private RequestBuilder $requestBuilder;

src/Model/Operation/UpdateOperationInterface.php

@@ -12,6 +12,8 @@
 
 /**
  * @api
+ * @deprecated
+ * @see \Zoho\Desk\Service\UpdateOperationInterface
  */
 interface UpdateOperationInterface
 {

src/Model/OperationPool.php

@@ -18,9 +18,14 @@
 use Zoho\Desk\Model\Operation\ReadOperationInterface;
 use Zoho\Desk\Model\Operation\UpdateOperation;
 use Zoho\Desk\Model\Operation\UpdateOperationInterface;
+
 use function implode;
 use function md5;
 
+/**
+ * @deprecated
+ * @see \Zoho\Desk\Service\ServiceFactory
+ */
 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;
+}