Initial public release

Author: Pavel Batanov

.gitignore

@@ -0,0 +1,7 @@
+vendor/
+.idea/
+build/
+var/
+target/
+*.phar
+composer.lock

README.md

@@ -0,0 +1,208 @@
+# Doctrine-faced RPC Client
+
+## Usage
+
+```php
+class \MyVendor\Api\Entity\MyEntity {
+    /** @var string */
+    private $id;
+    /** @var string */
+    private $payload;
+    
+    public function getId() { return $this->id; }
+    
+    public function getPayload() { return $this->payload; }
+}
+  
+```  
+    
+`Resources/config/api/MyEntity.api.yml` content:
+    
+```yml
+MyVendor\Api\Entity\MyEntity:
+  type: entity
+  id:
+    id:
+      type: int
+
+  fields:
+    payload:
+      type: string
+    
+  client:
+    name: my-client
+    entityPath: my-entity
+```
+
+Configure `EntityManager`
+```php
+class RpcClient implements RpcClientInterface {
+    /** RpcClient impl */
+}
+
+$client = new RpcClient();
+
+$registry = new ClientRegistry();
+$registry->add('my-client', $client);
+
+$configuration = new Configuration();
+$configuration->setMetadataFactory(new EntityMetadataFactory());
+$configuration->setRegistry($this->registry);
+$configuration->setEntityFactoryClass(ProxyFactory::class);
+$configuration->setProxyDir(CACHE_DIR . '/doctrine/proxy/');
+$configuration->setProxyNamespace('MyVendor\Api\Proxy');
+$driver = new MappingDriverChain();
+$driver->addDriver(
+    new YmlMetadataDriver(
+        new SymfonyFileLocator(
+            [
+                __DIR__ . '/../Resources/config/api/' => 'MyVendor\Api\Entity',
+            ],
+            '.api.yml',
+            DIRECTORY_SEPARATOR)
+    ),
+    'MyVendor\Api\Entity'
+);
+$configuration->setDriver($driver);
+
+$manager = new EntityManager($configuration);    
+```  
+    
+
+Call entity-manager to retrieve entities through your api
+```php
+$samples = $manager->getRepository(\MyVendor\Api\Entity\MyEntity::class)->findBy(['payload'=>'sample']);
+foreach ($samples as $sample) {
+   var_dump($sample->getId());
+} 
+```
+
+## References
+
+You could reference other API entities via relation annotations. General bi-directional self-reference relation below:
+
+```yml
+MyVendor\Api\Entity\MyEntity:
+  type: entity
+  id:
+    id:
+      type: int
+
+  fields:
+    payload:
+      type: string
+    
+  manyToOne:
+    parent:
+        target: MyVendor\Api\Entity\MyEntity
+        inversedBy: children
+  oneToMany:
+    children:
+        target: MyVendor\Api\Entity\MyEntity
+        mappedBy: parent
+```
+
+In order to make `*toMany` relations works flawlessly you should define the mapped class property 
+as `Entity[]|ArrayCollection` as hydrator will substitute your relation property with lazy-loading collection interface.   
+
+### Note on lazy-loading
+
+Generic API is not a DB, so eager reference pre-fetching will always result in additional API query, 
+so current implementation always assumes that all requests are extra-lazy.
+This means that no data will be fetched until you really need it, and you'll have only lazy proxy object before that happens.
+
+Keep it in the mind  
+
+## Hacking into fetching process
+
+### Custom repository
+
+Just call defined RpcClient from your repository
+
+```php
+class MyRepository extends \Bankiru\Api\Doctrine\EntityRepository {
+    public function callCustomRpcMethod()
+    {
+        $request = new \Bankiru\Api\Rpc\RpcRequest('my-method',['param1'=>'value1']);
+        $data = $this->getClient()->invoke([$request])->getResponse($request);
+        
+        return $data;
+    }
+} 
+```
+
+Or more portable with mapping
+
+```yml
+MyVendor\Api\Entity\MyEntity:
+  type: entity
+  id:
+    id:
+      type: int
+
+  fields:
+    payload:
+      type: string
+    
+  repositoryClass: MyVendor\Api\Repository\MyRepository # This will override repository for MyEntity
+  client:
+    name: my-client
+    # entityPath: my-entity autoconfigures find and search methods for you as following, but it is not overridable
+    # You can also specify path separator as
+    # entityPathSeparator: "-"
+    # To make autogenerated methods look like my-entity-find 
+    methods: 
+        find: my-entity\find      # find method is mandatory to find calls work
+        search: my-entity\search  # find method is mandatory to findBy calls work
+        custom: my-custom-method  # do some custom stuff
+```
+
+```php
+class MyRepository extends \Bankiru\Api\Doctrine\EntityRepository {
+    public function callCustomRpcMethod()
+    {
+        $request = new \Bankiru\Api\Rpc\RpcRequest(
+            $this->getMetadata()->getMethodContainer()->getMethod('custom'),
+            ['param1'=>'value1']
+        );
+        $data = $this->getClient()->invoke([$request])->getResponse($request);
+        
+        return $data;
+    }
+} 
+```
+
+### Custom searcher
+
+`Searcher` and `SearchTransformer` are the interfaces classes that converts doctrine-faced `findBy` arguments (criteria, order, limit, offset)
+to your custom api query set. This library provides you with the default `DoctrineNativeSearcher` class which translated these arguments to plain criteria array.
+
+You can override searcher via `.api.yml` mapping file:
+
+```yml
+MyVendor\Api\Entity\MyEntity:
+    client:
+        searcher: Bankiru\Api\Rpc\DoctrineNativeSearcher # The defaults
+```
+
+`Searcher` is required to implement the respective `Bankiru\Api\Doctrine\Rpc\Searcher` interface.
+
+### Custom hydrator
+
+`Hydrator` is the object factory which takes the plain ('dehydrated') data and converts it to rich ('hydrated') object with collections, relationship etc. 
+Current Hydrator accepts only plain-list parametrized objects. 
+
+### Custom field types
+
+You could register additional field types to configuration `TypeRegistry` (`Configuration::getTypeRegistry()`). Just implement the `Type` and register it via `TypeRegistry::add('alias', $type)`
+
+### TBD
+
+* No embeddables
+* No relation inheritance
+
+### Todo
+
+* Bad `Finder`|`Searcher`|`Counter` instantiation
+* No cache invalidation
+* 

composer.json

@@ -0,0 +1,40 @@
+{
+  "name": "bankiru/doctrine-api-client",
+  "description": "Doctrine-faced RPC API Client",
+  "authors": [
+    {
+      "name": "Pavel Batanov",
+      "email": "batanov@banki.ru"
+    }
+  ],
+  "license": "MIT",
+  "minimum-stability": "stable",
+  "require": {
+    "php": "~5.5|~7.0",
+    "psr/cache": "~1.0",
+    "psr/log": "~1.0",
+    "scaytrase/rpc-common": "~1.0",
+    "doctrine/common": "~2.5",
+    "doctrine/collections": "~1.3",
+    "symfony/yaml": "~2.3|~3.0",
+    "symfony/property-access": "~2.3|~3.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "~4.5|~5.1",
+    "scaytrase/json-rpc-client": "~1.0, >=1.0.1"
+  },
+  "suggest": {
+    "psr/cache-implementation": "For entity cache support",
+    "psr/log-implementation": "For logging support"
+  },
+  "autoload": {
+    "psr-4": {
+      "Bankiru\\Api\\": "src/Bankiru/Api"
+    }
+  },
+  "extra": {
+    "branch-alias": {
+      "dev-master": "1.0-dev"
+    }
+  }
+}

phpunit.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<phpunit
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.8/phpunit.xsd"
+        backupGlobals="false"
+        backupStaticAttributes="false"
+        colors="true"
+        convertErrorsToExceptions="true"
+        convertNoticesToExceptions="true"
+        convertWarningsToExceptions="true"
+        processIsolation="false"
+        stopOnFailure="false"
+        bootstrap="./vendor/autoload.php">
+
+    <php>
+        <const name="CACHE_DIR" value="./var/cache/test"/>
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine API Tests">
+            <directory>./src/</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory>./src</directory>
+            <exclude>
+                <directory>./vendor</directory>
+            </exclude>
+        </whitelist>
+    </filter>
+</phpunit>

src/Bankiru/Api/ClientRegistry.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Bankiru\Api;
+
+use ScayTrase\Api\Rpc\RpcClientInterface;
+
+final class ClientRegistry implements ClientRegistryInterface
+{
+    /** @var  RpcClientInterface[] */
+    private $clients = [];
+
+    /**
+     * @param string $name
+     *
+     * @return RpcClientInterface
+     * @throws \OutOfBoundsException
+     */
+    public function get($name)
+    {
+        if (!$this->has($name)) {
+            throw new \OutOfBoundsException(sprintf('Client "%s" not registered', $name));
+        }
+
+        return $this->clients[$name];
+    }
+
+    /**
+     * @param string $name
+     *
+     * @return bool
+     */
+    public function has($name)
+    {
+        return array_key_exists($name, $this->clients);
+    }
+
+    /**
+     * @param string             $name
+     * @param RpcClientInterface $client
+     *
+     * @return void
+     * @throws \InvalidArgumentException
+     */
+    public function add($name, RpcClientInterface $client)
+    {
+        if ($this->has($name)) {
+            throw new \InvalidArgumentException();
+        }
+
+        $this->replace($name, $client);
+    }
+
+    /**
+     * @param string             $name
+     * @param RpcClientInterface $client
+     *
+     * @return void
+     */
+    public function replace($name, RpcClientInterface $client)
+    {
+        $this->clients[$name] = $client;
+    }
+
+    /**
+     * @return RpcClientInterface[]
+     */
+    public function all()
+    {
+        return $this->clients;
+    }
+}