PIM-7761: Add reference entity resource

Author: LaurentPetard

content/php-client/resources/reference-entity/reference-entities.md

@@ -0,0 +1,56 @@
+### Reference entity
+
+::: warning
+This resource is only available in the [Entreprise Edition](https://www.akeneo.com/enterprise-edition/).
+:::
+
+#### Get a reference entity
+
+```php
+$client = new \Akeneo\PimEnterprise\ApiClient\AkeneoPimEnterpriseClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
+
+/*
+ * Returns an array like this:
+ * [
+ *     'code' => 'brand',
+ *     'labels' => [
+ *         'en_US' => 'Brand',
+ *         'fr_FR' => 'Marque',
+ *     ],
+ *     'image' => '5/e/e/e/5eee4242ed8d2f1a5f5ff41d00457ecbe637b71e_brand.jpg',
+ *     '_links' => [
+ *         'image_download' => [
+ *             'href' => 'http://localhost:8080/api/rest/v1/reference-entities-media-files/5/e/e/e/5eee4242ed8d2f1a5f5ff41d00457ecbe637b71e_brand.jpg',
+ *         ],
+ *     ],
+ * ]
+ */
+ $referenceEntity = $client->getReferenceEntityApi()->get('brand');
+ ```
+ 
+#### Get the list of the reference entities
+
+You can get more information about the available query parameters [here](/api-reference.html#get_reference_entities).
+
+```php
+$client = new \Akeneo\PimEnterprise\ApiClient\AkeneoPimEnterpriseClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
+
+$referenceEntitiesCursor = $client->getReferenceEntityApi()->all();
+```
+
+#### Upsert a reference entity
+
+If the reference entity does not exist yet, this method creates it, otherwise it updates it.
+
+```php
+$client = new \Akeneo\PimEnterprise\ApiClient\AkeneoPimEnterpriseClientBuilder('http://akeneo.com/')->buildAuthenticatedByPassword('client_id', 'secret', 'admin', 'admin');
+
+$client->getReferenceEntityApi()->upsert('brand', [
+    'code' => 'brand',
+    'labels' => [
+        'en_US' => 'Brand',
+        'fr_FR' => 'Marque',
+    ],
+    'image' => '5/e/e/e/5eee4242ed8d2f1a5f5ff41d00457ecbe637b71e_brand.jpg'
+]);
+```

tasks/client-documentation.js

@@ -78,7 +78,7 @@ gulp.task('create-PAM-md', function () {
         .pipe(gulp.dest('tmp/php-client-resources/'));
 });
 gulp.task('create-reference-entity-md', function () {
-    return gulp.src(['content/php-client/resources/reference-entity/*.md'])
+    return gulp.src(['content/php-client/resources/reference-entity/reference-entities.md', 'content/php-client/resources/reference-entity/*.md'])
         .pipe(concat('reference-entity.md'))
         .pipe(insert.prepend('## Reference entities\n'))
         .pipe(gulp.dest('tmp/php-client-resources/'));