Skip to content

Latest commit

 

History

History
124 lines (84 loc) · 5.13 KB

utils.md

File metadata and controls

124 lines (84 loc) · 5.13 KB
Raw

Utility methods

The library provides a set of functions that make it easier to perform certain tasks. These functions allow apps to:

  1. Execute smaller parts of the logic required for Shopify apps individually
  2. Leverage the above functions to avoid repetition, by providing shortcuts to features that are often used together

These methods are provided as a collection of static methods under Shopify\Utils. The following methods are currently supported:

sanitizeShopDomain

Returns a sanitized Shopify shop domain, ensuring that the domain is always in the format my-domain.myshopify.com.

Accepted arguments:

Parameter Type Required Default Value Notes
shop string Yes - A Shopify shop domain or hostname
myshopifyDomain string | null No 'myshopify.com' A custom Shopify domain, mostly used for testing

This method will return a string, or null if the domain is invalid.

getQueryParams

Retrieves the query string arguments from a URL string, if any.

Accepted arguments:

Parameter Type Required Default Value Notes
url string Yes - The url string with query parameters to be extracted

This method will return an associative array containing the query parameters.

validateHmac

Determines if a request is valid by checking the HMAC hash received in a request.

Accepted arguments:

Parameter Type Required Default Value Notes
params array Yes - Query parameters from a URL
secret string Yes - The secret key associated with the app in the Partners Dashboard

This method will return whether the hmac key in params is valid.

decodeSessionToken

Decodes the given session token (JWT) and extracts its payload, using Context::$API_SECRET_KEY as the secret.

Accepted arguments:

Parameter Type Required Default Value Notes
jwt string Yes - The JWT to decode

This method will return the payload of the JWT.

isApiVersionCompatible

Checks if the current version of the app (from Context::$API_VERSION) is compatible, i.e. more recent, than the given reference version.

Accepted arguments:

Parameter Type Required Default Value Notes
referenceVersion string Yes - The version to check against

This method will return true if the current version in Context is more recent than (or equal to) the reference version.

loadOfflineSession

Loads an offline session. This method does not perform any validation on the shop domain, so it must not rely on user input for the domain.

Accepted arguments:

Parameter Type Required Default Value Notes
shop string Yes - The shop url to find the offline session for
includeExpired bool No false Include expired sessions

This method will return a Session object if a session exists, or null otherwise. Please refer to the OAuth documentation for more information.

loadCurrentSession

Loads the current user's session based on the given headers and cookies.

Accepted arguments:

Parameter Type Required Default Value Notes
rawHeaders array Yes - The headers from the HTTP request
cookies array Yes - The cookies from the HTTP request
isOnline bool Yes - Whether to load online or offline sessions

This method will return a Session object if a session exists, or null otherwise. Please refer to the OAuth documentation for more information.

graphqlProxy

Forwards the GraphQL query in the HTTP request to Shopify, returning the response.

Accepted arguments:

Parameter Type Required Default Value Notes
rawHeaders array Yes - The headers from the HTTP request
cookies array Yes - The cookies from the HTTP request
rawBody string Yes - The raw HTTP request payload

This method will return a HttpResponse object. Please refer to the GraphQL client documentation for more information.

getEmbeddedAppUrl

Produces the Shopify URL that should load the embedded app, and ensures the embedded app URL is properly constructed and brings the merchant to the right place. It's more reliable than using the shop param.

Accepted arguments:

Parameter Type Required Default Value Notes
host string Yes - Base64-encoded host argument received from Shopify

This method will return a string containing the URL.