README

This project contains a library that makes it easy to use the Community Store API.

You can use it in concrete5 v8 and in ConcreteCMS v9+ projects, as well as in custom (non concrete) projects.

Installation

With Composer

Simply add the concretecms-community-store/community_store_api_client dependency:

composer require concretecms-community-store/community_store_api_client

Without Composer

Download this repository somewhere and include the register.php file.

For example, if your local copy of this project is available at /path/to/community_store_api_client, add this line in your PHP files:

require_once '/path/to/community_store_api_client/register.php';

Usage

Creating the Client instance

You need the base URL of your website, as well as the client ID and client secret.

$baseURL = 'http://www.yoursite.com';
$clientID = 'your-client-id';
$clientSecret = 'your-client-secret';

You also need to tell the client the scopes you need:

use CommunityStore\APIClient\Scope;

$scopes = [
    Scope::CONFIG_READ,
    Scope::PRODUCTS_READ,
    Scope::PRODUCTS_WRITE,
    Scope::ORDERS_READ,
    Scope::ORDERS_WRITE,
];

In a concrete5/ConcreteCMS environment

use CommunityStore\APIClient\Client;

$app = app();

$client = new Client(
    $baseURL
    $clientID,
    $clientSecret,
    $scopes,
    $app->make('http/client'),
    $app->make('cache/expensive')
);

Not in a concrete5/ConcreteCMS environment

In this case, you need the Guzzle HTTP Client library:

use CommunityStore\APIClient\Client;
use GuzzleHttp\Client as GuzzleClient;

$client = new Client(
    $baseURL
    $clientID,
    $clientSecret,
    $scopes,
    new GuzzleClient()
);

Retrieving the Community Store configuration

$configuration = $client->getConfiguration();

echo 'Currency code: ', $configuration->currency->code, "\n";
echo 'Currency symbol: ', $configuration->currency->symbol, "\n";
echo 'Currency decimal digits: ', $configuration->currency->decimalDigits, "\n";

Sample output:

Currency code: EUR
Currency symbol: €
Currency decimal digits: 2

Retrieving the defined fulfilment satuses

$statuses = $client->getFulfilmentStatuses();

echo 'Number of statuses: ', count($statuses), "\n";
echo 'ID of first status: ', $statuses[0]->id, "\n";
echo 'Handle of first status: ', $statuses[0]->handle, "\n";
echo 'Name of first status: ', $statuses[0]->name, "\n";

Sample output:

Number of statuses: 6
ID of first status: 1
Handle of first status: incomplete
Name of first status: Awaiting Processing

Retrieving an order given its ID

foreach ([123456, 11] as $id) {
    $order = $client->getOrder($id);
    if ($order === null) {
        echo "Order with ID {$id} could not be found\n\n";
        continue;
    }
    echo 'Order ID: ', $order->id, "\n";
    echo 'Date placed: ', $order->datePlaced->format('c'), "\n";
    echo 'Total: ', $order->total, "\n";
    echo 'Payment method: ', $order->paymentMethodName, "\n";
    echo 'Payment date: ', $order->paymentDate === null ? 'n/a' : $order->paymentDate->format('c'), "\n";
    echo 'Payment reference: ', $order->paymentReference, "\n";
    echo 'Shipping method: ', $order->shippingMethodName, "\n";
    echo 'Fulfilment status name: ', $order->fulfilment->statusName, "\n";
    echo 'Fulfilment status handle: ', $order->fulfilment->statusHandle, "\n";
    echo 'Tracking ID: ', $order->fulfilment->trackingID, "\n";
    echo 'Tracking code: ', $order->fulfilment->trackingCode, "\n";
    echo 'Tracking url: ', $order->fulfilment->trackingURL, "\n";
    echo 'Language: ', $order->locale, "\n";
    echo 'Customer email: ', $order->customer->email, "\n";
    echo 'Customer user name: ', $order->customer->username, "\n";
    echo 'Billing first name: ', $order->customer->billing->firstName, "\n";
    echo 'Billing last name: ', $order->customer->billing->lastName, "\n";
    echo 'Billing company: ', $order->customer->billing->company, "\n";
    echo 'Billing address line 1: ', $order->customer->billing->address->address1, "\n";
    echo 'Billing city: ', $order->customer->billing->address->city, "\n";
    echo 'Billing state/province: ', $order->customer->billing->address->stateProvince, "\n";
    echo 'Billing country code: ', $order->customer->billing->address->country, "\n";
    echo 'Billing postal code: ', $order->customer->billing->address->postalCode, "\n";
    echo 'Billing phone: ', $order->customer->billing->phone, "\n";
    echo 'Billing VAT: ', $order->customer->billing->vatNumber, "\n";
    echo 'Shipping first name: ', $order->customer->shipping->firstName, "\n";
    echo 'Shipping last name: ', $order->customer->shipping->lastName, "\n";
    echo 'Shipping company: ', $order->customer->shipping->company, "\n";
    echo 'Shipping address line 1: ', $order->customer->shipping->address->address1, "\n";
    echo 'Shipping city: ', $order->customer->shipping->address->city, "\n";
    echo 'Shipping state/province: ', $order->customer->shipping->address->stateProvince, "\n";
    echo 'Shipping country code: ', $order->customer->shipping->address->country, "\n";
    echo 'Shipping postal code: ', $order->customer->shipping->address->postalCode, "\n";
    echo 'Number of custom attributes: ', count($order->attributes), "\n";
    echo 'Refunded: ', $order->refunded === null ? 'no' : ('on ' . $order->refunded->date->format('c') . " ({$order->refunded->reason})"), "\n";
    echo 'Number of items: ', count($order->items), "\n";
    echo 'First item - ID: ', $order->items[0]->id, "\n";
    echo 'First item - name: ', $order->items[0]->name, "\n";
    echo 'First item - SKU: ', $order->items[0]->sku, "\n";
    echo 'First item - quantity: ', $order->items[0]->quantity, "\n";
    echo 'First item - price: ', $order->items[0]->price, "\n";
    echo 'First item - number of options: ', count($order->items[0]->options), "\n";
    echo 'First item - number of digital uploads: ', count($order->items[0]->uploads), "\n";
    echo "\n";
}

Sample output:

Order with ID 123456 could not be found

Order ID: 11
Date placed: 2024-01-23T16:34:42+01:00
Total: 123
Payment method: Invoice
Payment date: 2024-01-23T16:37:16+01:00
Payment reference: 
Shipping method: 
Fulfilment status name: Awaiting Processing
Fulfilment status handle: incomplete
Tracking ID: 
Tracking code: 
Tracking url: 
Language: en_US
Customer email: john@doe.com
Customer user name: john
Billing first name: John
Billing last name: Doe
Billing company: JoeCo
Billing address line 1: 20, Ocrean Street
Billing city: New York
Billing state/province: NY
Billing country code: US
Billing postal code: 10001
Billing phone: +1234567
Billing VAT: US12345678
Shipping first name: Jane
Shipping last name: Doe
Shipping company: JaneDo
Shipping address line 1: 30, Lake Street
Shipping city: San Francisco
Shipping state/province: CA
Shipping country code: US
Shipping postal code: 94016
Number of custom attributes: 2
Refunded: no
Number of items: 1
First item - ID: 321
First item - name: Stormtrooper armor
First item - SKU: SW-ST-A
First item - quantity: 1
First item - price: 123
First item - number of options: 0
First item - number of digital uploads: 0

Listing orders

Look for orders placed in the last 7 days, which are updaid and are awaiting processing:

use CommunityStore\APIClient\Entity\FulfilmentStatus;
use CommunityStore\APIClient\Query;
use CommunityStore\APIClient\Query\Orders\PaymentStatus;

$query = new Query\Orders();
$query->fromDate = new \DateTimeImmutable('-7 days');
$query->paymentStatus = PaymentStatus::INCOMPLETE;
$query->status = FulfilmentStatus::AWAITING_PROCESSING;

$orders = $client->getOrders($query, $pagination);
/** @var \CommunityStore\APIClient\Entity\Pagination $pagination */
while (true) {
    echo 'Found ', count($orders), ' orders in page ', $pagination->currentPage, "\n";
    $orders = $client->getNextOrders($pagination, $newPagination);
    if ($orders === []) {
        break;
    }
    $pagination = $newPagination;
}

Sample output:

Found 20 orders in page 1
Found 5 orders in page 2

Updating an order

Update the order with ID 5:

use CommunityStore\APIClient\Entity\FulfilmentStatus;
use CommunityStore\APIClient\Query\OrderPatch;

$patch = new OrderPatch(5);
$patch->fulfilment->trackingID = 'TRK-ID-001';
$patch->fulfilment->trackingCode = 'TRK-CODE-001';
$patch->fulfilment->trackingURL = 'https://www.carrier.com/?foo=bar';
$patch->fulfilment->status = FulfilmentStatus::SHIPPED;

$order = $client->updateOrder($patch);

echo "Order with ID {$order->id} has been updated.\n";
echo "Its status is now {$order->fulfilment->statusName}.\n";

Sample output:

Order with ID 5 has been updated.
Its status is now Shipped.

Product related operations

Still to be implemented.