Merge pull request #3 from fgrosse/feature/client-facade

Feature/client facade

README.md

@@ -7,7 +7,6 @@
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fgrosse/gitlab-api/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/fgrosse/gitlab-api/?branch=master)
 
 [![Latest Stable Version](https://poser.pugx.org/fgrosse/gitlab-api/v/stable.png)](https://packagist.org/packages/fgrosse/gitlab-api)
-[![Total Downloads](https://poser.pugx.org/fgrosse/gitlab-api/downloads.png)](https://packagist.org/packages/fgrosse/gitlab-api)
 [![Latest Unstable Version](https://poser.pugx.org/fgrosse/gitlab-api/v/unstable.png)](https://packagist.org/packages/fgrosse/gitlab-api)
 [![License](https://poser.pugx.org/fgrosse/gitlab-api/license.png)](https://packagist.org/packages/fgrosse/gitlab-api)
 
@@ -35,8 +34,27 @@ $ composer require fgrosse/gitlab-api
 
 ## Usage
 
-The API is still work in progress and the actual usage might change in the future. For now you can use the `GitlabClient`
-directly like this:
+The API is still work in progress and the actual usage might change in the future.
+
+The stable part of this API is available through the [GitlabClient interface](lib/Client/GitlabClient.php):
+
+```php
+$guzzleClient = GitlabGuzzleClient::factory([
+    'base_url'  => $baseUrl,
+    'api_token' => $token,
+]);
+
+$client = new HttpGitlabClient($guzzleClient);
+
+$mergeRequests = $client->listMergeRequests($project,
+    $state='closed',
+    $order='updated_at',
+    $sort='asc',
+    $page=1, $perPage=5
+);
+```
+
+If you want to access more functionality consider using the `GitlabClient` directly:
 
 ```php
 $client = GitlabClient::factory([
@@ -54,9 +72,8 @@ $mergeRequests = $client->listMergeRequests([
 ]);
 ```
 
-In the future I will probably create a facade around the client which follows a well defined interface.
-Until then you need to checkout the [lib/Client/ServiceDescription][6] to see the available
-parameters for each API call.
+Checkout the [lib/Client/ServiceDescription][6] to see the available parameters for each API call.
+An executable example can be found in [examples/merge_requests/api.php](examples/merge_requests_api.php). 
 
 ### Not implemented APIs (yet)
  * deploy_key_multiple_projects API

examples/merge_requests_api.php

@@ -9,7 +9,8 @@
  * file that was distributed with this source code.
  */
 
-use Gitlab\Client\GitlabClient;
+use Gitlab\Client\GitlabGuzzleClient;
+use Gitlab\Client\HttpGitlabClient;
 
 include __DIR__.'/../vendor/autoload.php';
 include __DIR__.'/cli_helper.php';
@@ -19,21 +20,23 @@
 $project = getParameter('project', $argv);
 
 try {
-    $client = GitlabClient::factory([
+    $guzzleClient = GitlabGuzzleClient::factory([
         'base_url'  => $baseUrl,
         'api_token' => $token,
     ]);
 
-    $mergeRequests = $client->listMergeRequests([
-        'project_id' => $project,
-        'state'      => 'closed',
-        'order_by'   => 'updated_at',
-        'sort'       => 'asc',
-        'page'       => 0,
-        'per_page'   => 5,
-    ]);
+    $client = new HttpGitlabClient($guzzleClient);
+
+    $mergeRequests = $client->listMergeRequests($project,
+        $state = 'closed',
+        $order = 'updated_at',
+        $sort = 'asc',
+        $page = 1, $perPage = 5
+    );
 
-    var_dump($mergeRequests);
+    foreach ($mergeRequests as $mergeRequest) {
+        echo $mergeRequest.PHP_EOL;
+    }
 } catch (Exception $exception) {
     printError('An Exception of type '.get_class($exception).' occurred:');
     printError($exception->getMessage());

lib/Client/ResponseParser.php → lib/Client/ArrayParsable.php

@@ -10,12 +10,7 @@
 
 namespace Gitlab\Client;
 
-interface ResponseParser
+interface ArrayParsable
 {
-    /**
-     * Unmarshal a response object from an array.
-     * @param array $data
-     * @return mixed
-     */
     public static function fromArray(array $data);
 }

lib/Client/GitlabClient.php

@@ -10,128 +10,19 @@
 
 namespace Gitlab\Client;
 
-use GuzzleHttp\ClientInterface;
-use GuzzleHttp\Command\Command;
-use GuzzleHttp\Command\Guzzle\DescriptionInterface;
-use GuzzleHttp\Command\Guzzle\GuzzleClient;
-use GuzzleHttp\Message\ResponseInterface;
-
-/**
- * Class GitlabClient is a guzzle client which is configured completely via the service definition (service.yml).
- * Use GitlabClient::factory to create new instances.
- *
- * The following magic methods are available through the service definition:
- *
- * Merge Requests API:
- * @see https://github.com/gitlabhq/gitlabhq/blob/v7.7.0/doc/api/merge_requests.md
- * @method array listMergeRequests($parameters)
- * @method array getMergeRequest($parameters)
- * @method array getMergeRequestChanges($parameters)
- * @method array createMergeRequest($parameters)
- * @method array updateMergeRequest($parameters)
- * @method array createMergeRequestComment($parameters)
- * @method array listMergeRequestComments($parameters)
- * @method array acceptMergeRequest($parameters)
- *
- * Commits API
- * @see https://github.com/gitlabhq/gitlabhq/blob/v7.7.0/doc/api/commits.md
- * @method array listCommits($parameters)
- * @method array getCommit($parameters)
- * @method array getCommitDiff($parameters)
- * @method array getCommitComments($parameters)
- * @method array createCommitComment($parameters)
- *
- * Issues API
- * @see https://github.com/gitlabhq/gitlabhq/blob/v7.7.0/doc/api/issues.md
- * @method array listIssues($parameters)
- * @method array listProjectIssues($parameters)
- * @method array getIssue($parameters)
- * @method array createIssue($parameters)
- * @method array updateIssue($parameters)
- *
- * Labels API
- * @see https://github.com/gitlabhq/gitlabhq/blob/v7.7.0/doc/api/labels.md
- * @method array listLabels($parameters)
- * @method array createLabel($parameters)
- * @method array updateLabel($parameters)
- * @method array deleteLabel($parameters)
- *
- * TODO: branches API
- * TODO: deploy_key_multiple_projects API
- * TODO: deploy_keys API
- * TODO: groups API
- * TODO: milestones API
- * TODO: notes API
- * TODO: oauth2 API
- * TODO: project_snippets API
- * TODO: projects API
- * TODO: repositories API
- * TODO: repository_files API
- * TODO: services API
- * TODO: session API
- * TODO: system_hooks API
- * TODO: users API
- */
-class GitlabClient extends GuzzleClient
+interface GitlabClient
 {
     /**
-     * Factory method to create a fully configured GitlabClient.
-     * @param array $config
-     * @return GitlabClient
-     */
-    public static function factory(array $config)
-    {
-        return GuzzleClientFactory::createClient($config);
-    }
-
-    /**
-     * A list of operations that are executed with a body.
-     * TODO: this is a hack until  https://github.com/guzzle/guzzle-services supports request bodies on PUT or DELETE
-     * @var string[]
-     */
-    private $executeWithBody = [
-        'updateMergeRequest',
-        'acceptMergeRequest',
-        'updateIssue',
-        'updateLabel',
-        'deleteLabel',
-    ];
-
-    /**
-     * @param ClientInterface $client
-     * @param DescriptionInterface $description
-     * @param array $config
-     * @see factory use the static factory method to retrieve a fully configured gitlab GitlabClient
-     */
-    public function __construct(ClientInterface $client, DescriptionInterface $description, array $config = [])
-    {
-        parent::__construct($client, $description, $config);
-    }
-
-    public function __call($name, array $arguments)
-    {
-        if (in_array($name, $this->executeWithBody)) {
-            return $this->executeRequestWithBody($name, $arguments[0]);
-        }
-
-        return parent::__call($name, $arguments);
-    }
-
-    /**
-     * This is a hack to allow guzzle PUT or DELETE requests to have a body.
-     * TODO submit github issue for that.
-     * @param $commandName
-     * @param array $parameters
-     * @return ResponseInterface
+     * Get all merge requests for this project.
+     * The state parameter can be used to get only merge requests with a given state (opened, closed, merged or all).
+     * The pagination parameters page and per_page can be used to restrict the list of merge requests.
+     * @param string $projectId The ID of a project
+     * @param string $state Return 'all' requests or just those that are 'merged', 'opened' or 'closed'
+     * @param string $orderBy Return requests ordered by 'created_at' or 'updated_at' fields
+     * @param string $sort Return requests sorted in 'asc' or 'desc' order
+     * @param int $page
+     * @param int $perPage
+     * @return \Gitlab\Entity\MergeRequest[]
      */
-    private function executeRequestWithBody($commandName, array $parameters)
-    {
-        $parameters['request_options'] = [
-            'body' => [],
-        ];
-
-        /** @var Command $command */
-        $command = $this->getCommand($commandName, $parameters);
-        return $this->execute($command);
-    }
+    public function listMergeRequests($projectId, $state = null, $orderBy = null, $sort = null, $page = null, $perPage = null);
 }