The e-commerce SDK from commercetools for PHP.
Clone or download
Failed to load latest commit information.
bin fix(tls-check): update urls for TLS 1.2 check Oct 10, 2018
build docs: update URL for CTP api documentation Feb 13, 2018
docroot feat(Builder): add request and update actions builder DSL May 28, 2018
features docs: update URL for CTP api documentation Feb 13, 2018
src feat(Payment): support anonymousId Sep 10, 2018
tests fix RamlModelTest for messages Oct 19, 2018
tools chore(Git): show phpcs progress Apr 6, 2018
.gitattributes Windows compat of build (step 1). Jul 21, 2015
.gitignore feat(ProductType): support product type changeAttributeName & changeE… ( Apr 9, 2018
.scrutinizer.yml chore(CI): bump dependencies Feb 23, 2018
.travis.yml TLS 1.2 check (#405) Jul 23, 2018 docs(Changelog): update changelog Aug 16, 2018 Create Feb 20, 2018
LICENSE bump license year Sep 27, 2017 Create Feb 20, 2018 docs(Readme): update readme Jul 13, 2018
behat.yml add integration tests for category Apr 15, 2015
build.xml feat(Extension): support API extensions Aug 15, 2018
composer.json feat(Extension): support API extensions Aug 15, 2018
github_deploy_key.enc chore(Travis): refactor GH pages deployment (#387) Mar 14, 2018
index.php WIP: prepare building of a phar distribution of the SDK Jan 3, 2017 Merge release 2.0.0 Jun 2, 2017 Windows compat of build (step 1). Jul 21, 2015
package-lock.json chore(Changelog): add conventional changelog to package.json Apr 6, 2018
package.json docs(Changelog): update changelog Aug 16, 2018
phpunit.xml.dist test(Integration): fix warning message for PHPUnit 6 Aug 25, 2017
phpunit5.xml.dist chore(Travis): fix error listener for phpunit 5 Aug 25, 2017 chore(Travis): refactor GH pages deployment (#387) Mar 14, 2018 feat(Extension): support API extensions Aug 15, 2018
yarn.lock chore(Changelog): add conventional changelog to package.json Apr 6, 2018

commercetools PHP SDK

Build Status Scrutinizer Scrutinizer Packagist Packagist

The PHP SDK allows developers to build applications on the commercetools platform (technically speaking against our REST API) using PHP native interfaces, models and helpers instead of manually using the HTTP and JSON API.

You gain lots of IDE Auto-Completion, type checks on a literal API, Warnings, Object Mapping, i18n support etc.. The Client manages the OAuth2 security tokens, provides caches and interfaces for concurrent and asynchronous API calls.

The SDK is licensed under the permissive MIT License. Don't hesitate to contribute!

Using the SDK

The PHP API documentation provides all the details you need in a searchable form (link points to latest stable release).

Install & Integrate the SDK into your Project

The SDK requires a PHP version of 5.6 or higher. The SDK tries to use the APC(u) as it's default cache. If you provide a PSR-6 or PSR-16 compliant cache adapter, APC(u) is not necessary. The cache/filesystem-adapter is tried to be used if no APC(u) is installed.

The curl extension is recommended but not strictly necessary because the SDK is using the Guzzle library library, which falls back to PHP stream wrappers if curl is not available. The intl extension is required to directly output Money objects as a String.

The recommended way to install the SDK is through Composer.

# Install Composer if not installed yet
curl -sS | php

Next, run the Composer command to install the latest version of the SDK:

composer require commercetools/php-sdk

The SDK supports Guzzle6 as well as Guzzle5 as HTTP client. For Guzzle6:

composer require guzzlehttp/guzzle ^6.0

When you want to use Guzzle5 you have to ensure react/promise at minimum version 2.2:

composer require guzzlehttp/guzzle ^5.3.1
composer require react/promise ^2.2

After installing, you need to require Composer's autoloader if that's not yet the case:

require 'vendor/autoload.php';

If you don't use Composer, just download a zip archive of the latest release, manually integrate it and configure your own autoloader.

The project follows the semantic versioning guidelines, i.e. everything but major version changes are backwards-compatible. This matches composer's default behavior.

With composer just run composer update commercetools/php-sdk to update to compatible versions. Edit your composer.json file to update to incompatible versions.

Please read the Changelog before updating in any case.

Getting started

To get up and running, create a free test project (EU located or US located) on the commercetools platform. To generate your API credentials go to EU Merchant Center or US Merchant Center (Menu "Settings"->"Developer Settings"->"API Clients"->"Create New Api Client"). You need to select the template for the "Admin client".


require '../vendor/autoload.php';

use Commercetools\Core\Builder\Request\RequestBuilder;
use Commercetools\Core\Client;
use Commercetools\Core\Config;
use Commercetools\Core\Model\Common\Context;

$config = [
    'client_id' => 'my client id',
    'client_secret' => 'my client secret',
    'project' => 'my project id'
$context = Context::of()->setLanguages(['en'])->setLocale('en_US')->setGraceful(true);
$config = Config::fromArray($config)->setContext($context);

 * create a search request and a client,
 * execute the request and get the PHP Object
 * (the client can and should be re-used)
$search = RequestBuilder::of()->productProjections()->search()
    ->addParam('text.en', 'red');

$client = Client::ofConfig($config);
$products = $client->execute($search)->toObject();

 * show result (would be a view layer in real world)
header('Content-Type: text/html; charset=utf-8');

foreach ($products as $product) {
    echo $product->getName()->en . '<br/>';

If you prefer not to have a client with all admin rights, you need to explicitly include the client's permission scopes that you selected when creating the client, on the client's configuration:

$config = [
    'client_id' => 'my client id',
    'client_secret' => 'my client secret',
    'project' => 'my project id',
    'scope' => 'permission_scope and_another_scope'

In real world, you will not put your API credentials directly into code but use a config file or your framework's config or dependency injection system for that.

Using the phar distribution

Since version 1.6 the SDK is also released as a PHAR. You can find them in the releases section at Github.

Usage example:


require __DIR__ . '/commercetools-php-sdk.phar';

$config = \Commercetools\Core\Config::fromArray([
    'client_id' => 'myClientId',
    'client_secret' => 'myClientSecret',
    'project' => 'myProjectId'
$client = \Commercetools\Core\Client::ofConfig($config);
$request = \Commercetools\Core\Request\Project\ProjectGetRequest::of();

$response = $client->execute($request);

$project = $request->mapFromResponse($response);

Improve & Contribute to the SDK project

Mac OS X preparations:

assuming Homebrew is installed, do the following:

xcode-select --install
brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/homebrew-php
brew install php56
brew install php56-intl
brew install php56-xdebug
brew install ant
# you probably also need to fix a (=any) timezone in your php.ini:
echo "date.timezone='Europe/Berlin'" >> /usr/local/etc/php/5.6/conf.d/60-user.ini
# initialize the dependencies:
php composer.phar update

Linux preparations :

  • install php 5.6+, xdebug and ant according to their distro's package system.
  • make sure the curl, intl, mbstring and openssl extensions are activated in php.ini

Windows preparations:

  • install php 5.6+, i.e. extract ZIP and make add php.exe location to your PATH. Use WAMP etc. if you like, but plain PHP commandline is all you really need (you can test example code in the built-in webserver).
  • enable the curl, intl, mbstring and openssl extenstions in php.ini
  • make a working ant available in the PATH
  • and install composer.

Start working:

Clone the develop branch of the repository (we're using the gitflow branching model, so master is for releases only):

git clone

Please follow the PSR-2 coding style, ideally via your IDE settings (see below for PhpStorm instructions).

Please make sure that exiting Unit and Integration tests don't fail and fully cover your new code with Unit Tests. You can run all tests locally:


Built In Test Server

You can use the docroot directory with the built-in PHP web server. Add to the docroot directory a file called "myapp.yml". Add following content and setup with your API credentials:

    client_id: my client id
    client_secret: my client secret
    project: my project id

Then activate the php builtin web server

cd <project_folder>
php -S localhost:8000 -t docroot

Now navigate to http://localhost:8000 in your browser.

PhpStorm configuration

To enable code style checks directly in PhpStorm you have to configure the path to the phpcs at Preferences > Languages & Frameworks > PHP > Code Sniffer. Now you can enable at Preferences > Editor > Inspections > PHP the "PHP code sniffer validation" with PSR-2 standard. Change the severity if needed.

Running integration tests

For running the integration tests you need an empty commercetools project and have to create an API client using the commercetools Admin Center with the scopes manage_project, view_orders and view_products.

Local environment

composer update

Using docker

Running the test image:

echo "COMMERCETOOLS_CLIENT_ID=YourClientID" > env.list
echo "COMMERCETOOLS_CLIENT_SECRET=YourClientSecret" >> env.list
echo "COMMERCETOOLS_PROJECT=YourProjectKey" >> env.list

docker run --env-file env.list -v $PWD:/opt/app -w /opt/app --rm=true jaysde/php-test-base tools/


On bigger effort changes, please open a GitHub issue and ask if you can help or get help with your idea. For typos and documentation improvements just make a pull request.


  1. fork the repository on GitHub
  2. code and add tests that cover the created code. Your code should be warning-free.
  3. stick to PSR-2 and and don't reformat existing code.
  4. make a pull request. @jenschude will review it and pull or come back to you.