API Booster

Features' details

Retrieving a resource from the cache

For instance, if we want to retrieve the attribute which code is my_attribute :

$attribute = $apiBooster->getAttribute(‘my_attribute’);

The method will return the response that is normally returned by the API. No changes are made. As the official Akeneo PHP client is used internally, that means it can either return an array containing all data of this attribute in case of success, or throw an Akeneo\Pim\Exception\HttpException in case of error. If the response is a success, it will be stored in the cache to prevent the API to be called next time.

The other methods getAttributeOption, getCategory, getAttributeGroup, getAssociationType, getLocale, getChannel, getCurrency, getReferenceEntityRecord, getAsset, getMeasureFamily and getMeasurementFamily work the same.

Knowing the type of an attribute

Internally, the cache will be called, which means you can use this method without suffering any penalty hit.

$attributeType = $apiBooster->getAttributeType(‘my_attribute’);

Format input data into API format

The methods formatProduct (and formatProductModel) allows to automatically format product (and product model) values. All you have to do is to respect the global format expected by Akeneo PIM API.

Please note that those methods do not send the products data to Akeneo. They are just here to format the data.

Format booleans

The strings 1, true and yes are converted to the boolean true for boolean attributes. This also works for the German ja, the Spanish sí, the French oui, the Italian si, the portuguese sim, the Swedish ja and the Russian да / da. For instance :

$formatted = $apiBooster->formatProduct([ 'values' => [ 'a_boolean' => [ [ 'locale' => null, 'scope' => null, 'data' => 'oui'], ] ] ]); // $formatted = [ // 'values' => [ // 'a_boolean' => [ // [ 'locale' => null, 'scope' => null, 'data' => true], // ] // ] // ];

The strings 0, false and no are converted to the boolean false for boolean attributes. This also works for the German nein, the Spanish no, the French non, the Italian no, the Portuguese não, the Swedish nej and the Russian нет / nyet. For instance :

$formatted = $apiBooster->formatProduct([ 'values' => [ 'a_boolean' => [ [ 'locale' => null, 'scope' => null, 'data' => '0'], ] ] ]); // $formatted = [ // 'values' => [ // 'a_boolean' => [ // [ 'locale' => null, 'scope' => null, 'data' => false], // ] // ] // ];

Format collections

The strings containing a given separator are split and converted to arrays for asset collections, multi selects and reference entity collections. For instance :

$formatted = $apiBooster->formatProduct([ 'values' => [ 'a_multi_select' => [ ['locale' => null, 'scope' => null, 'data' => 'foo,bar'], ] ] ]); // $formatted = [ // 'values' => [ // 'a_multi_select' => [ // ['locale' => null, 'scope' => null, 'data' => ['foo', 'bar']], // ] // ] // ];

The default separator for collections is ,. If you need a different separator, you can provide it as a second argument of the methods formatProduct and formatProductModel. For instance :

$formatted = $apiBooster->formatProduct([ 'values' => [ 'a_multi_select' => [ ['locale' => null, 'scope' => null, 'data' => 'foo|bar'], ] ] ], '|');

Format dates

The \DateTime and \DateTimeImmutable objects are converted to ISO-8601 for date attributes. For instance :

$formatted = $apiBooster->formatProduct([ 'values' => [ 'a_date' => [ ['locale' => null, 'scope' => null, 'data' => new \DateTimeImmutable('2000-01-01')], ] ] ]); // $formatted = [ // 'values' => [ // 'a_date' => [ // ['locale' => null, 'scope' => null, 'data' => '2000-01-01T00:00:00+0000'], // ] // ] // ];

Format metrics

The metrics represented as strings are converted to arrays with keys amount and unit. The unit can be before or after the amount. For instance :

$formatted = $apiBooster->formatProduct([ 'values' => [ 'a_metric' => [ ['locale' => 'fr_FR', 'scope' => null, 'data' => '15.56 KILO'], ['locale' => 'de_DE', 'scope' => null, 'data' => 'GRAM 18'], ] ] ]); // $formatted = [ // 'values' => [ // 'a_metric' => [ // ['locale' => 'fr_FR', 'scope' => null, 'data' => ['amount' => '15.56', 'unit' => 'KILO']], // ['locale' => 'de_DE', 'scope' => null, 'data' => ['amount' => '18', 'unit' => 'GRAM']], // ] // ] // ];

Format prices

The prices represented as strings are converted to arrays with keys amount and currency. The currency can be before or after the amount. The currency can be a symbol. For instance :

$formatted = $apiBooster->formatProduct([ 'values' => [ 'a_price_collection' => [ ['locale' => 'fr_FR', 'scope' => null, 'data' => '23 EUR'], ['locale' => 'de_DE', 'scope' => null, 'data' => '$24'], ['locale' => 'it_IT', 'scope' => null, 'data' => '15.75 €, 16 USD, GBP 8'], ] ] ]); // $formatted = [ // 'values' => [ // 'a_price_collection' => [ // ['locale' => 'fr_FR', 'scope' => null, 'data' => [['amount' => '23', 'currency' => 'EUR']]], // ['locale' => 'de_DE', 'scope' => null, 'data' => [['amount' => '24', 'currency' => 'USD']]], // ['locale' => 'de_DE', 'scope' => null, 'data' => [['amount' => '15.75', 'currency' => 'EUR'], ['amount' => '16', 'currency' => 'USD'], ['amount' => '8', 'currency' => 'GBP']]], // ] // ] // ];

What if my data can't be formatted?

If API Booster can't format your data, it won't be modified. No error is thrown. The goal is to let you call the API so that it returns you the actual error.

Installation

Once you have downloaded the ZIP file containing API Booster, activate your license key:

curl https://api.gumroad.com/v2/licenses/verify \ -d "product_permalink=akeneo-api-booster" \ -d "license_key=YOUR-LICENSE-KEY" \ -X POST

There is currently no simple distribution system. If enough customers are interested, I'll set up a private packagist. This would be more convenient. Contact me in case of need.

Go to the root directory of your project and unzip the file:

cd /path/to/my/project unzip api-booster-*.zip rm api-booster-*.zip mv api-booster-* api-booster

Edit your composer.json to add API Booster's repository:

{ # ... "repositories": [ { "type": "path", "url": "./api-booster" # path where the folder "api-booster" is located relatively to your composer.json } ] }

Now you can require API Booster:

composer require "jjanvier/api-booster":"dev-master"

Don't worry about the dev-master version. This is required as we use here a path repository, but the ZIP file you downloaded matches a real release.

And that's it! Now you are ready to configure API Booster.

Configuration

If your project is based on Symfony

Configuration

Activate the bundle ApiBoosterBundle in the kernel.

# config/bundles.php <?php return [ //... Jjanvier\ApiBooster\Integration\Symfony\ApiBoosterBundle::class => ['all' => true], ];

Configure the caches you want to use in your framework configuration. You can use any number of cache solutions you want. The only requirement is that the cache pool must be named api_booster.cache.internal. In the following example we’ll use the in memory array and the apcu adapters.

# config/packages/framework.yaml framework: cache: pools: api_booster.cache.internal: adapters: - 'cache.adapter.array' - 'cache.adapter.apcu'

Define the following environment variables in the root .env file :

AKENEO_API_CLIENT_ID=client AKENEO_API_SECRET=secret AKENEO_API_USERNAME=username AKENEO_API_PASSWORD=password AKENEO_API_URL=url

And that’s it! You’re now ready to use ApiBooster.

Usage

You can retrieve the service api_booster from the container and use it in your code. It will return an instance of the class Jjanvier\ApiBooster\Library\ApiBooster. For instance :

$apiBooster = $this->getContainer()->get(‘api_booster’); $attribute = $apiBooster->getAttribute(‘my_attribute’);

A demo command is available to check everything is working well :

bin/console api_booster:demo-cache my_attribute

You have an example of a small Symfony application configured to work with API Booster in your vendor/jjanvier/api-booster/demo/symfony folder.

If you use another framework than Symfony or no framework at all

Configuration and usage

You have an example of a small PHP application configured to work with API Booster in your vendor/jjanvier/api-booster/demo/vanilla folder.

All you need to do is to build the API Booster instance via its factory :

$myCaches = [/* an array of PSR6 or Symfony contracts caches*/ ]; $logger = null; // a PSR logger if you want to debug $apiBooster = Jjanvier\ApiBooster\Integration\Vanilla\ApiBoosterFactory::build( $myCaches, $url, $clientId, $secret, $username, $password, $logger );

And that’s it! You’re now ready to use ApiBooster. For instance :

$attribute = $apiBooster->getAttribute(‘my_attribute’);