[On HOLD] - DX-159: Move PHP client doc from API doc

docs/authentication.md

@@ -0,0 +1,86 @@
+# Authentication
+
+You can be authenticated to the REST API either by providing a username and a password or by providing a token and a refresh token.
+
+## By App token
+
+Authenticate with the access token received from an [OAuth authorization](/apps/authentication-and-authorization.html#token-success-response).
+
+```php
+<?php
+
+require_once '/vendor/autoload.php';
+
+$clientBuilder = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://localhost/');
+$client = $clientBuilder->buildAuthenticatedByAppToken('token');
+```
+
+## By username/password
+
+You can authenticate to the client with your credentials client id/secret and your user/password:
+
+```php
+<?php
+
+require_once '/vendor/autoload.php';
+
+$clientBuilder = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://localhost/');
+$client = $clientBuilder->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
+```
+
+Then, every client's request is automatically authenticated.
+If you don't have any client id, please take a look at [this page](/documentation/authentication.html#client-idsecret-generation) to create it.
+
+This is the easiest way to authenticate the client.
+
+## By token/refresh token
+
+The main drawback of the authentication by password is that it requests a new token before doing any call to the REST API. Therefore, it can decrease the performance if you use the PHP client in an application that creates a lot of processes.
+For example, in a PHP web application, a new PHP process is created for each request. If would be time consuming to get a new token for each process, in order to be authenticated.
+
+In this context, it's better to use the same token for each new request.
+
+That's why you can create a client with the couple token/refresh token instead of username/password.
+
+```php
+<?php
+
+require_once '/vendor/autoload.php';
+
+$clientBuilder = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://localhost/');
+$client = $clientBuilder->buildAuthenticatedByToken('client_id', 'secret', 'token', 'refresh_token');
+```
+
+To get the couple token/refresh token, you just have to do:
+```php
+$client->getToken();
+$client->getRefreshToken();
+```
+
+::: warning
+It's your responsibility to store the token and the refresh token.
+For example, it can be stored in a file or in a database.
+:::
+
+### Example
+
+This is a very basic example to put token and refresh token into a file, in order to be shared with other processes:
+
+```php
+<?php
+
+require_once '/vendor/autoload.php';
+
+$clientBuilder = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://localhost/');
+if (!file_exists('/tmp/akeneo_token.tmp')) {
+    $client = $clientBuilder->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
+} else {
+    $credentials = file_get_contents('/tmp/akeneo_token.tmp');
+    list($token, $refreshToken) = explode(':', $credentials);
+    $client = $clientBuilder->buildAuthenticatedByToken('client_id', 'secret', $token, $refreshToken);
+}
+
+$category = $client->getCategoryApi()->get('master');
+
+file_put_contents('/tmp/akeneo_token.tmp', $client->getToken() . ':' . $client->getRefreshToken());
+```

docs/exception.md

@@ -0,0 +1,114 @@
+# Exception handling
+
+Every request made with the client can throw an HTTP exception.
+
+You can read more about REST API Exception handling : [here](https://api.akeneo.com/documentation/responses.html#)
+
+## HTTP exception
+
+The parent of these HTTP exceptions is `Akeneo\Pim\Exception\HttpException`.
+You can get the request and the response that are responsible for this exception. Also, the HTTP response code and response message are available.
+
+```php
+try {
+    $client->getProductUuidApi()->get('1cf1d135-26fe-4ac2-9cf5-cdb69ada0547');
+} catch (HttpException $e) {
+    // do your stuff with the exception
+    $requestBody = $e->getRequest()->getBody();
+    $responseBody = $e->getResponse()->getBody();
+    $httpCode = $e->getCode(); 
+    $errorMessage = $e->getMessage(); 
+}
+```
+
+
+Two types of exception inherit from this exception: server exception and client exception.
+
+## Server exception (5XX)
+
+A server exception thrown by the client means that the server failed to fulfill an apparently valid request.
+It's an HTTP code from the 5xx family.
+
+## Client exception (4XX)
+
+A client exception could be thrown if the client made an invalid request.
+It's an HTTP code from the 4xx family.
+
+### Bad request exception (400)
+
+This exception is thrown if the request does not contain valid JSON. It corresponds to the HTTP code 400.
+
+::: info
+It should not occur with the PHP client, because the JSON is generated from PHP array.
+:::
+
+### Unauthorized exception (401)
+
+This exception is thrown if you don't have the permission to access to the resource. It corresponds to the HTTP code 401.
+
+::: info
+It should not occur as the PHP client automatically authenticates the request for you.
+:::
+
+### Forbidden exception (403)
+
+This exception is thrown if the server understands the request but refuses to authorize it.
+It corresponds to the HTTP code 403.
+
+### Not found exception (404)
+
+This exception is thrown if the requested resource does not exist. It corresponds to the HTTP code 404.
+
+### Method not allowed exception (405)
+
+This exception is thrown if the requested resource doesn't support this method. It corresponds to the HTTP code 405.
+
+### Not acceptable exception (406)
+
+This exception is thrown if the server cannot produce a response matching the list of acceptable values defined in the
+request's proactive content negotiation headers, and that the server is unwilling to supply a default representation.
+It corresponds to the HTTP code 406.
+
+### Unsupported media type exception (415)
+
+This exception is thrown if the payload format is in an unsupported format. It corresponds to the HTTP code 415.
+
+### Unprocessable entity exception (422)
+
+This exception is thrown if the data are not valid. In this exception, an array of errors could be returned.
+It returns an empty array if there is no error in the array.
+
+```php
+try {
+    $client->getProductUuidApi()->create('1cf1d135-26fe-4ac2-9cf5-cdb69ada0547');
+} catch (UnprocessableEntityHttpException $e) {
+    // do your stuff with the exception
+    $requestBody = $e->getRequest()->getBody();
+    $responseBody = $e->getResponse()->getBody();
+    $httpCode = $e->getCode(); 
+    $errorMessage = $e->getMessage(); 
+    $errors = $e->getResponseErrors();
+    foreach ($e->getResponseErrors() as $error) {
+        // do your stuff with the error
+        echo $error['property'];
+        echo $error['message'];
+    }
+}
+```
+
+### Too many requests exception (429)
+
+This exception is thrown if too many requests are sent in an amount of time ("rate limiting").
+It corresponds to the HTTP code 429.
+
+```php
+try {
+    $client->getProductUuidApi()->get('1cf1d135-26fe-4ac2-9cf5-cdb69ada0547');
+} catch (TooManyRequestsHttpException $e) {
+    $requestBody = $e->getRequest()->getBody();
+    $responseBody = $e->getResponse()->getBody();
+    $httpCode = $e->getCode();
+    $errorMessage = $e->getMessage();
+    $retryAfter = $e->getRetryAfter();
+}
+```

docs/getting-started.md

@@ -0,0 +1,71 @@
+# Getting started
+
+
+## Deprecation notice
+
+::: info
+Note that our PHP client is backward compatible.
+
+For example, if your PIM is currently a v6.0, you can still use a 1.0 version of the PHP client.
+The new endpoints available in v6.0 will not be available in the v1.0 of the PHP client.
+:::
+
+
+## Installation
+
+`api-php-client` use [Composer](http://getcomposer.org).
+The first step is to download Composer:
+
+```bash
+$ curl -s http://getcomposer.org/installer | php
+```
+We use HTTPPlug as the HTTP client abstraction layer. If you want to know more about this, it's documented [here](/php-client/http-client.html).
+In this example, we will use [Guzzle](https://github.com/guzzle/guzzle) v6 as the HTTP client implementation.
+
+Run the following command to require the libraries in your project:
+
+```bash
+$ php composer.phar require akeneo/api-php-client php-http/guzzle6-adapter:^2.0 http-interop/http-factory-guzzle:^1.0
+```
+
+::: info
+If you don't know which implementation to choose, we strongly recommend you to use Guzzle v6, as in the previous example.
+:::
+
+## Initialization of the client
+
+You first need to initialize the client with your credentials (client id, secret, username and password).
+
+If you don't have any client id/secret, let's take a look at [this page](/documentation/authentication.html#client-idsecret-generation) to create it.
+
+```php
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+$clientBuilder = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://localhost/');
+$client = $clientBuilder->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
+```
+
+You can authenticate to the client with your token/refresh token as well.
+```php
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+$clientBuilder = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://localhost/');
+$client = $clientBuilder->buildAuthenticatedByToken('client_id', 'secret', 'token', 'refresh_token');
+```
+
+Want to know more about authentication? It's over [there](/php-client/authentication.html).
+
+## Make your first call
+
+Getting a product is as simple as:
+
+```
+$product = $client->getProductUuidApi()->get('1cf1d135-26fe-4ac2-9cf5-cdb69ada0547');
+echo $product['uuid'];
+```
+
+Want to [update an attribute](/php-client/resources.html#upsert-an-attribute), [create a category](/php-client/resources.html#create-a-category) or [delete a product](/php-client/resources.html#delete-a-product)? You can get code snippets for all the resources [here](/php-client/resources.html)

docs/http-client.md

@@ -0,0 +1,48 @@
+# HTTP client abstraction
+
+We use [HTTPPlug](http://httplug.io/) as the HTTP client abstraction layer. 
+Thanks to it, you are free to use the HTTP client implementation and PSR7 implementation that fits your needs.
+
+For example, if you already are using Guzzle v5 in an existing project, you can use it with Akeneo PHP client as well. 
+Also, it can avoid dependency conflicts that you can experienced by using different version of an HTTP client in the same project (Guzzle v5 and Guzzle v6 for example).
+
+Don't know which client or PSR7 implementation to use? We recommend you to use Guzzle v6:
+
+```bash
+$ php composer.phar require akeneo/api-php-client php-http/guzzle6-adapter
+```
+::: info
+Guzle v6 automatically requires its own PSR7 implementation `guzzlehttp/psr7`.
+:::
+
+You can get the full list of HTTP adapters [here](https://packagist.org/providers/php-http/client-implementation).
+
+The currently supported HTTP client implementation are:
+
+- php-http/guzzle6-adapter (only with Guzzle PSR7 implementation)
+- php-http/curl-client
+- php-http/guzzle5-adapter
+
+The currently supported PSR7 implementation are:
+- guzzlehttp/psr7
+- zendframework/zend-diactoros
+- slim/slim
+
+In order to use Guzzle v5 and PSR7 Guzzle implementation, you have to do it:
+
+```bash
+$ php composer.phar require akeneo/api-php-client php-http/guzzle5-adapter guzzlehttp/psr7
+```
+
+If you prefer the native curl client, with Slim PSR7 implementation:
+
+```bash
+$ php composer.phar require akeneo/api-php-client php-http/curl-client slim/slim
+```
+
+Then, when creating the client, the HTTP client to use will be automatically detected:
+
+ ```
+$clientBuilder = new \Akeneo\Pim\ApiClient\AkeneoPimClientBuilder('http://localhost/');
+$client = $clientBuilder->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
+```

docs/introduction.md

@@ -0,0 +1,18 @@
+# PHP developer, you are?
+> We have a client for you!
+
+The PHP client facilitates the usage of the REST API in your PHP projects when building extensions and/or tools for your favorite PIM.
+
+## Support & issues
+Please be aware that the PHP client is only supported **in best effort**, whether you are an Enterprise or Community customer.
+
+If you ever find a bug, do not hesitate to directly open a Github issue on the [API client repository](https://github.com/akeneo/php-api-client).
+
+Don't forget that we also love when you contribute and help us do better tools. So do not hesitate! Every feedback/pull request is very welcomed! 
+
+
+## Keep in touch
+If you just want to discuss about it, join the community in the [#web-api](https://akeneopim-ug.slack.com/messages/web-api/) channel in our [Slack user group community](https://akeneopim-ug.slack.com/).
+
+:::panel-link Want to be ready quickly?[Let's start with our simple getting started](/php-client/getting-started.html)
+:::