A simple, tested, API wrapper for Shopify using Guzzle. It supports both the REST and GraphQL API provided by Shopify, and basic rate limiting abilities. It contains helpful methods for generating a installation URL, an authorize URL, HMAC signature validation, call limits, and API requests. It works with both OAuth and private API apps.
This library required PHP >= 7.
The recommended way to install is through composer.
$ composer require ohmybrew/basic-shopify-api
Add use OhMyBrew\BasicShopifyAPI; to your imports.
This assumes you properly have your app setup in the partner's dashboard with the correct keys and redirect URIs.
For REST calls, the shop domain and access token are required.
$api = new BasicShopifyAPI();
$api->setShop('your shop here');
$api->setAccessToken('your token here');
// Now run your requests...
$api->rest(...);For GraphQL calls, the shop domain and access token are required.
$api = new BasicShopifyAPI();
$api->setShop('your shop here');
$api->setAccessToken('your token here');
// Now run your requests...
$api->graph(...);After obtaining the user's shop domain, to then direct them to the auth screen use getAuthUrl, as example (basic PHP):
$api = new BasicShopifyAPI();
$api->setShop($_SESSION['shop']);
$api->setApiKey(env('SHOPIFY_API_KEY'));
$api->setApiSecret(env('SHOPIFY_API_SECRET'));
$code = $_GET['code'];
if (!$code) {
/**
* No code, send user to authorize screen
* Pass your scopes as an array for the first argument
* Pass your redirect URI as the second argument
*/
$redirect = $api->getAuthUrl(env('SHOPIFY_API_SCOPES'), env('SHOPIFY_API_REDIRECT_URI'));
header("Location: {$redirect}");
exit;
} else {
// We now have a code, lets grab the access token
$token = $api->requestAccessToken($code);
// You can now do what you wish with the access token after this (store it to db, etc)
$api->setAccessToken($token);
// You can now make API calls as well once you've set the token to `setAccessToken`
$request = $api->rest('GET', '/admin/shop.json'); // or GraphQL
}Simply pass in an array of GET params.
// Will return true or false if HMAC signature is good.
$valid = $api->verifyRequest($_GET);This assumes you properly have your app setup in the partner's dashboard with the correct keys and redirect URIs.
For REST calls, shop domain, API key, and API password are request
$api = new BasicShopifyAPI(true); // true sets it to private
$api->setShop('example.myshopify.com');
$api->setApiKey('your key here');
$api->setApiPassword('your password here');
// Now run your requests...
$api->rest(...);For GraphQL calls, shop domain and API password are required.
$api = new BasicShopifyAPI(true); // true sets it to private
$api->setShop('example.myshopify.com');
$api->setApiPassword('your password here');
// Now run your requests...
$api->graph(...);Requests are made using Guzzle.
$api->rest(string $type, string $path, array $params = null);typerefers to GET, POST, PUT, DELETE, etcpathrefers to the API path, example:/admin/products/1920902.jsonparamsrefers to an array of params you wish to pass to the path, examples:['handle' => 'cool-coat']
The return value for the request will be an object containing:
responsethe full Guzzle response objectbodythe JSON decoded response body
Note: request() will alias to rest() as well.
Requests are made using Guzzle.
$api->graph(string $query, array $variables = []);queryrefers to the full GraphQL queryvariablesrefers to the variables used for the query (if any)
The return value for the request will be an object containing:
responsethe full Guzzle response objectbodythe JSON decoded response bodyerrorsif there was errors or not
Example query:
$result = $api->graph('{ shop { productz(first: 1) { edges { node { handle, id } } } } }');
echo $result->body->shop->products->edges[0]->node->handle; // test-productExample mutation:
$result = $api->graph(
'mutation collectionCreate($input: CollectionInput!) { collectionCreate(input: $input) { userErrors { field message } collection { id } } }',
['input' => ['title' => 'Test Collection']]
);
echo $result->body->collectionCreate->collection->id; // gid://shopify/Collection/63171592234After each request is made, the API call limits are updated. To access them, simply use:
// Returns an array of left, made, and limit.
// Example: ['left' => 79, 'made' => 1, 'limit' => 80]
$limits = $api->getApiCalls('rest'); // or 'graph'For GraphQL, additionally there will be the following values: restoreRate, requestedCost, actualCost.
To quickly get a value, you may pass an optional parameter to the getApiCalls method:
// As example, this will return 79
// You may pass 'left', 'made', or 'limit'
$left = $api->getApiCalls('graph', 'left'); // returns 79
// or
$left = $api->getApiCalls('graph')['left']; // returns 79This library comes with a built-in basic rate limiter, disabled by default. It will sleep for x microseconds to ensure you do not go over the limit for calls with Shopify. On non-Plus plans, you get 1 call every 500ms (2 calls a second), for Plus plans you get 2 calls every 500ms (4 calls a second).
By default the cycle is set to 500ms, with a buffer for safety of 100ms added on.
Setup your API instance as normal, with an added:
$api->enableRateLimiting();This will turn on rate limiting with the default 500ms cycle and 100ms buffer. To change this, do the following:
$api->enableRateLimiting(0.25 * 1000, 0);This will set the cycle to 250ms and 0ms buffer.
If you've previously enabled it, you simply need to run:
$api->disableRateLimiting();$api->isRateLimitingEnabled();The library will track timestamps from the previous and current (last) call. To see information on this:
$response = $api->rest('POST', '/admin/gift_cards.json', ['gift_cards' => ['initial_value' => 25.00]]);
print_r($response->timestamps);
/* Above will return an array of [previous call, current (last) call], example:
* [1541119962.965, 1541119963.3121] */You can initialize the API once and use it for multiple shops. Each instance will be contained to not pollute the others. This is useful for something like background job processing.
$api->withSession(string $shop, string $accessToken, Closure $closure);shoprefers to the Shopify domainaccessTokenrefers to the access token for the API callsclosurerefers to the closure to call for the session
$this will be binded to the current API. Example:
$api = new BasicShopifyAPI(true);
$api->setApiKey('your key here');
$api->setApiPassword('your password here');
$api->withSession('some-shop.myshopify.com', 'token from database?', function() {
$request = $this->rest('GET', '/admin/shop.json');
echo $request->body->shop->name; // Some Shop
});
$api->withSession('some-shop-two.myshopify.com', 'token from database?', function() {
$request = $this->rest('GET', '/admin/shop.json');
echo $request->body->shop->name; // Some Shop Two
});This library internally catches only 400-500 status range errors through Guzzle. You're able to check for an error of this type and get its response status code and body.
$call = $api->rest('GET', '/admin/non-existant-route-or-object.json');
if ($call->errors) {
echo "Oops! {$call->errors->status} error";
print_r($call->errors->body);
// Original exception can be accessed via `$call->errors->exception`
// Example, if response body was `{"error": "Not found"}`...
/// then: `$call->errors->body->error` would return "Not Found"
}Code documentation is available here from phpDocumentor via phpdoc -d src -t doc.
This project is released under the MIT license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent