Demonstration App

Introduction

This is a very basic setup for using the BigCommerce V3 API client. It will cover setting up a simple composer-based PHP command-line project and using it to query the BigCommerce API.

If you want documentation about specific endpoints, view the BigCommerce API Reference. If you're looking for the documentation for this library, see the client documentation.

If you can't be bothered copying the steps here, there's a reference git repo here: https://github.com/jswift/bigcommerce-api-demo-app.

Before You Get Started

Prerequisites for running this tutorial:

You'll need PHP available (at least PHP 7.4)
composer

Creating Your Project

Create the directory you want to store your project in, mine is ~/test-client and then run composer init to setup your project.

jarrod.swift:~/ $ mkdir test-client
jarrod.swift:~/ $ cd test-client/
jarrod.swift:~/test-client $ composer init

You will be prompted to set some values for your project. Choose some that make sense, but they can always be changed later by editing composer.json.

Package name (<vendor>/<name>) [root/app]: jarrod/bc-test-client
Description []: A demonstration client for BigCommerce
Author [, n to skip]: n
Minimum Stability []: 
Package Type (e.g. library, project, metapackage, composer-plugin) []: project
License []:

After setting these composer will ask you if you wish to define your dependencies interactively, enter yes. Then search for aligent/bigcommerce and select the package. This will install the BigCommerce V3 API Client into your vendor folder, ready for use in your project.

Define your dependencies.

Would you like to define your dependencies (require) interactively [yes]? yes
Search for a package: aligent/bigcommerce

Found 1 packages matching aligent/bigcommerce

   [0] aligent/bigcommerce-api-client 

Enter package # to add, or the complete package name if it is not listed: 0
Enter the version constraint to require (or leave blank to use the latest version): 
Using version ^1.7 for aligent/bigcommerce-api-client
Search for a package: 
Would you like to define your dev dependencies (require-dev) interactively [yes]? no
Add PSR-4 autoload mapping? Maps namespace "Jarrod\BcTestClient" to the entered relative path. [src/, n to skip]: src/

{
    "name": "jarrod/bc-test-client",
    "description": "A demonstration client for BigCommerce",
    "type": "project",
    "require": {
        "aligent/bigcommerce-api-client": "^1.7"
    },
    "autoload": {
        "psr-4": {
            "Jarrod\\BcTestClient\\": "src/"
        }
    }
}

Do you confirm generation [yes]? yes

Once you've confirmed this, and installed the dependencies (either now or later with composer install) you're ready to write some code. You should now have:

a composer.json file (which defines your project and it's dependencies),
a composer.lock file (which defines the specific versions of dependencies that are installed),
a vendor/ directory that contains the downloaded packages, and
a src/ directory that is empty.

Using the API Client

All code files should be in the folder specified by the PSR autoload statement in composer.json, in our case - src/. Lets make a file called products.php in that folder.

Lets start by checking that everything is working ok.

src/products.php

<?php
include __DIR__.'/../vendor/autoload.php';

echo "Hello World", PHP_EOL;

Then run this file from the terminal, and it should print "Hello World"

jarrod.swift:~/test-client $ php src/products.php 
Hello World

So if this has worked, now we can go ahead and use the API Client. Update the products.php file to match the following:

<?php
include __DIR__.'/../vendor/autoload.php';

$client = new BigCommerce\ApiV3\Client(
    $_ENV['STORE_HASH'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']
);

$products = $client->catalog()->products()->getAll()->getProducts();

echo "There were ", count($products), " fetched!", PHP_EOL;

Run this again, but this time we'll see an error!

Warning: Undefined array key "STORE_HASH" in /app/src/products.php on line 5

Warning: Undefined array key "CLIENT_ID" in /app/src/products.php on line 5

Warning: Undefined array key "ACCESS_TOKEN" in /app/src/products.php on line 5

Fatal error: Uncaught TypeError: BigCommerce\ApiV3\BaseApiClient::__construct(): Argument #1 ($storeHash) must be of type string, null given

Looks like we need to define our environment variables to access our store!

Define Store Credentials

We don't want to store our credentials in a code repo, or hard-code them so it's hard to update in the future, so lets add a library to help us manage this. For this we are going to use vlucas/phpdotenv.

First, update our dependencies by running composer require vlucas/phpdotenv in your project directory. Then we can update the file src/products.php and add these two lines after the include line.

$dotenv = Dotenv\Dotenv::createImmutable(getcwd());
$dotenv->load();

These two lines load the Dotenv class which will read key-value pairs from a ".env" file and put them into the $_ENV global array in PHP.

Run the file again with php src/products.php. Now we see another error, telling us it could not read any environment files. This is because we haven't defined our .env file that it will use to generate environment variables for us. Create a file called .env in the project directory. The following is an example, you'll need to update the values with the correct ones for your BigCommerce instance. Note: if you're putting your project in git, make sure to put ignore the .env file!

.env

STORE_HASH=ysab9vwhnt
CLIENT_ID=hrlkjnfdlkjnfdknfdlkdfjnvdfdy
ACCESS_TOKEN=g0d7i7xnuvj8hdsjfsorh25i255mg0d7i

Now running the products.php file for the final time, you should get a result! This will be limited by the page size of the request, so if you have more than 250 products don't be alarmed -- that's the default page size!

jarrod.swift:~/test-client $ php src/products.php 
There were 250 fetched!

If you are interested in seeing the full implementation of this tutorial, it's available on github at jswift/bigcommerce-api-demo-app.

Provide feedback

Saved searches