Download the PHP package seka19/basic-shopify-api without Composer

Basic Shopify API

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 (offline and per-user), HMAC signature validation, call limits, and API requests. It works with both OAuth and private API apps.

Also supported: asynchronous requests through Guzzle's promises.

This library required PHP >= 7.

Table of Contents

• Installation
• Usage
  • Public API
    • REST (sync)
    • REST (async)
    • GraphQL
    • Getting access (offline)
    • Getting access (per-user)
    • Verifying HMAC signature
  • Private API
    • REST
    • GraphQL
  • Making requests
    • REST
      • If sync is true (regular rest call):
      • If sync is false (restAsync call):
    • GraphQL
  • API Versioning
  • Checking API limits
  • Rate Limiting
    • Enable Rate Limiting
    • Disabiling Rate Limiting
    • Checking Rate Limiting Status
    • page_info / pagination Support
    • Getting Timestamps
  • Isolated API calls
  • Errors
  • Logging
• Documentation
• LICENSE

Installation

The recommended way to install is through composer.

$ composer require ohmybrew/basic-shopify-api

Usage

Add use OhMyBrew\BasicShopifyAPI; to your imports.

Public API

This assumes you properly have your app setup in the partner's dashboard with the correct keys and redirect URIs.

REST (sync)

For REST calls, the shop domain and access token are required.

REST (async)

For REST calls, the shop domain and access token are required.

GraphQL

For GraphQL calls, the shop domain and access token are required.

Getting access (offline)

This is the default mode which returns a permanent token.

After obtaining the user's shop domain, to then direct them to the auth screen use getAuthUrl, as example (basic PHP):

Getting access (per-user)

You can also change the grant mode to be per-user as outlined in Shopify documentation. This will receieve user info from the user of the app within the Shopify store. The token recieved will expire at a specific time.

Verifying HMAC signature

Simply pass in an array of GET params.

Private API

This assumes you properly have your app setup in the partner's dashboard with the correct keys and redirect URIs.

REST

For REST (sync) calls, shop domain, API key, and API password are request

GraphQL

For GraphQL calls, shop domain and API password are required.

Making requests

REST

Requests are made using Guzzle.

• type refers to GET, POST, PUT, DELETE, etc
• path refers to the API path, example: /admin/products/1920902.json
• params refers to an array of params you wish to pass to the path, examples: ['handle' => 'cool-coat']
• headers refers to an array of custom headers you would like to optionally send with the request, example: ['X-Shopify-Test' => '123']
• sync refers to if the request should be synchronous or asynchronous.

You can use the alias restAsync to skip setting sync to false.

If sync is true (regular rest call):

The return value for the request will be an object containing:

• response the full Guzzle response object
• body the JSON decoded response body

Note: request() will alias to rest() as well.

If sync is false (restAsync call):

The return value for the request will be a Guzzle promise which you can handle on your own.

The return value for the promise will be an object containing:

• response the full Guzzle response object
• body the JSON decoded response body

GraphQL

Requests are made using Guzzle.

• query refers to the full GraphQL query
• variables refers to the variables used for the query (if any)

The return value for the request will be an object containing:

• response the full Guzzle response object
• body the JSON decoded response body
• errors if there was errors or not

Example query:

Example mutation:

API Versioning

This library supports versioning the requests, example:

You can override the versioning at anytime for specific API requests, example:

Checking API limits

After each request is made, the API call limits are updated. To access them, simply use:

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:

Rate Limiting

This 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.

Enable Rate Limiting

Setup your API instance as normal, with an added:

This will turn on rate limiting with the default 500ms cycle and 100ms buffer. To change this, do the following:

This will set the cycle to 250ms and 0ms buffer.

Disabiling Rate Limiting

If you've previously enabled it, you simply need to run:

Checking Rate Limiting Status

page_info / pagination Support

2019-07 API version introduced a new Link header which is used for pagination (explained here).

If an endpoint supports page_info, you can use $response->link to grab the page_info value to pass in your next request.

Example:

Getting Timestamps

The library will track timestamps from the previous and current (last) call. To see information on this:

Isolated API calls

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.

• shop refers to the Shopify domain
• accessToken refers to the access token for the API calls
• closure refers to the closure to call for the session

$this will be binded to the current API. Example:

Errors

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.

Logging

This library accepts a PSR-compatible logger.

Documentation

Code documentation is available here from phpDocumentor via phpdoc -d src -t doc.

LICENSE

This project is released under the MIT license.