PHPackages oilstone/api-commerce-layer-integration - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. oilstone/api-commerce-layer-integration ActiveLibrary[API Development](/categories/api) oilstone/api-commerce-layer-integration ======================================= A Commerce Layer integration package for garethhudson07/api 099↓33.3%PHPCI passing Since Feb 27Pushed 2mo agoCompare [ Source](https://github.com/oilstone/api-commerce-layer-integration)[ Packagist](https://packagist.org/packages/oilstone/api-commerce-layer-integration)[ RSS](/packages/oilstone-api-commerce-layer-integration/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (2)Used By (0) API Commerce Layer Integration ============================== [](#api-commerce-layer-integration) A PHP library that streamlines communication between the [Commerce Layer](https://commercelayer.io) platform and the [`garethhudson07/api`](https://github.com/garethhudson07/api) toolkit. It packages a configured HTTP client, a JSON:API aware query builder, repository abstractions, caching helpers, and optional Laravel bindings so you can focus on modelling your business logic instead of wiring requests. Table of contents ----------------- [](#table-of-contents) - [Features](#features) - [Requirements](#requirements) - [Installation](#installation) - [Configuration](#configuration) - [Quick start](#quick-start) - [Core components](#core-components) - [CommerceLayer client](#commercelayer-client) - [Query builder](#query-builder) - [Repositories](#repositories) - [Record helpers](#record-helpers) - [Schema meta properties](#schema-meta-properties) - [Caching](#caching) - [Laravel integration](#laravel-integration) - [Error handling](#error-handling) - [Testing](#testing) - [Contributing](#contributing) - [License](#license) Features -------- [](#features) - **Dedicated HTTP client** that encapsulates authentication headers, JSON:API defaults, logging hooks, and request level options tailored to Commerce Layer endpoints. - **Fluent query builder** for composing Commerce Layer filters, includes, sparse fieldsets, pagination, and sorting using a familiar chainable API. - **Repository abstraction** that wraps CRUD access with default constraints, eager loading, cache integration, and payload preparation. - **Cache handler** with PSR-16 support that can memoise both direct client calls and higher level queries. - **Laravel service provider** offering container bindings, configuration publishing, automatic token management, and an artisan cache management command. Requirements ------------ [](#requirements) - PHP 8.1 or higher. - Composer with the ability to install `garethhudson07/api`, `guzzlehttp/guzzle`, `nesbot/carbon`, and PSR logging & caching interfaces. - (Optional) Laravel 11+ for the provided service provider and artisan command. Installation ------------ [](#installation) Install the package via Composer: ``` composer require oilstone/api-commerce-layer-integration ``` ### Laravel [](#laravel) When using Laravel the service provider will be auto-discovered. Publish the configuration file if you need to customise connection settings: ``` php artisan vendor:publish --provider="Oilstone\ApiCommerceLayerIntegration\Integrations\Laravel\ServiceProvider" --tag=config ``` This will place `config/commerce-layer.php` in your application so you can set environment variables such as API URLs, OAuth client credentials, scopes, and cache defaults. Configuration ------------- [](#configuration) Create a Commerce Layer integration by providing: - **API base URL** (e.g. `https://{organisation}.commercelayer.io/api`). - **OAuth access token** or, in Laravel, the client credentials used to fetch one automatically. - **Optional logging** channel and cache handler for diagnostics and performance. When not using Laravel you are responsible for managing token lifetimes and instantiating the cache handler if desired. The examples below demonstrate the manual approach. Quick start ----------- [](#quick-start) ``` use GuzzleHttp\Client as HttpClient; use Oilstone\ApiCommerceLayerIntegration\Clients\CommerceLayer; use Oilstone\ApiCommerceLayerIntegration\Repository; $http = new HttpClient(); $client = new CommerceLayer( $http, 'https://your-organisation.commercelayer.io/api', 'your-access-token' ); $orders = (new Repository('orders')) ->setClient($client) ->setDefaultIncludes(['customer', 'line_items']) ->get([ ['status', '=', 'placed'], ['number', 'like', 'UK%'], ]); $firstOrder = (new Repository('orders')) ->setClient($client) ->find('order-id-123'); ``` Core components --------------- [](#core-components) ### CommerceLayer client [](#commercelayer-client) The `Clients\CommerceLayer` class wraps a `GuzzleHttp\Client` instance and automatically: - Applies Commerce Layer JSON:API headers and bearer token authentication. - Exposes CRUD helpers (`listResources`, `retrieve`, `create`, `update`, `delete`). - Provides optional request logging and integrates with the query cache handler. Each call accepts request-specific options (headers, query overrides, or logging flags) which are merged with sensible defaults. ### Query builder [](#query-builder) `Query` offers a fluent interface for constructing JSON:API compliant requests: - `where`, `orWhere`, and collection helpers (`whereIn`, `whereNotIn`, etc.) compile into Commerce Layer filter parameters. - `with` registers relationship includes; `select` applies sparse fieldsets for the primary resource. - Pagination via `limit`/`offset` is converted into `page[size]` and `page[number]` values. - Supports retrieving the first record, fetching by id, and generating cache keys for PSR-16 integration. ### Repositories [](#repositories) `Repository` encapsulates common patterns when working with a specific Commerce Layer resource: - Configure defaults for constraints, includes, identifier field, and payload values when instantiating or via setters. - Generate new `Query` instances with defaults applied and layer in ad-hoc options (conditions, includes, sorting, pagination, cache options). - Convenience methods for `find`, `findOrFail`, `get`, `getById`, `create`, `update`, and `delete`. - Automatic cache handler propagation to the underlying client when provided. ### Record helpers [](#record-helpers) Use `Record::make()` or `RecordCollection::make()` to wrap JSON:API payloads in lightweight value objects with helper accessors for attributes, relationships, and metadata. ### Schema meta properties [](#schema-meta-properties) When loading schema definitions through the bundled API integration you can mark individual properties with `meta` flags to tailor how payloads are transformed before requests are sent or after responses are received. The table below summarises the supported keys and the behaviour they unlock: Meta keyEffect`isMetadata`Treats the property as part of the Commerce Layer `metadata` object so it is automatically included when building sparse fieldsets and skipped when preparing write payloads.`validationOnly`Excludes the property from transformed payloads entirely so it can exist purely for local validation rules.`isRelation`Signals a relationship field that should be ignored when building attribute payloads and defaults.`calculated`Prevents the property from being sent back to the API because its value is computed by Commerce Layer.`readonly` / `isReadonly`Skips the property during reverse transformation unless values are forced (e.g. via `forceReverse`).`default`Supplies a fallback value (or resolver callback) that is merged into outgoing payloads when no explicit value is provided.`fixed`Always injects the provided value (or resolver callback result), overriding request data and bypassing `readonly` checks.`delimited`Converts between delimited strings and arrays when transforming responses and requests.`beforeTransform` / `afterTransform`Callbacks that run before or after a value is normalised during response transformation.`beforeReverse` / `afterReverse`Callbacks that run before or after a value is converted back to request format.Callbacks receive the property definition and, when applicable, the source attributes so you can derive contextual values. Combining these meta flags allows you to model complex behaviours such as computed defaults, coercing list fields, or ensuring metadata is always available without leaking into write operations. ### Caching [](#caching) `Cache\QueryCacheHandler` implements query-level caching using a PSR-16 cache store: - Generates namespaced cache keys and supports TTL configuration. - Offers opt-in request logging and the ability to skip retrieval (useful for console operations). - Integrates seamlessly with both `CommerceLayer` and `Query` to reduce duplicate API calls. ### Laravel integration [](#laravel-integration) If you are building a Laravel application: - The service provider binds the query cache handler and client into the container, handling token retrieval and caching automatically. - Publish the configuration to adjust URLs, credentials, logging, and cache TTLs. - Use the `commerce-layer:cache:clear` command to flush cached query results or invalidate entries for specific records. - Console command behaviour is now exposed through framework-agnostic services (`Services\ClearCacheService`, `Services\DeleteDraftCartService`, `Services\DeleteStaleDraftCartsService`, and `Services\DeleteSkuService`) so you can trigger the same workflows directly without relying on Laravel console integration. Error handling -------------- [](#error-handling) All client requests raise a `CommerceLayerException` when the API responds with a non-2xx status. The exception surfaces the HTTP status code and any JSON:API error payloads for richer debugging. Additional exceptions (such as `ObjectNotSpecifiedException` or `RecordNotFoundException`) help identify misconfigured repositories or missing records. Testing ------- [](#testing) Validate the package using the provided Composer scripts: ``` composer validate find src -name "*.php" -print0 | xargs -0 -n1 php -l ``` These commands ensure the manifest is consistent and that all PHP files pass syntax checks. Contributing ------------ [](#contributing) Pull requests are welcome! Please ensure that new features include appropriate documentation and remain consistent with the existing architecture. Run the testing commands above before submitting changes. License ------- [](#license) This package is open-sourced software licensed under the [MIT license](LICENSE). ### Health Score 23 — LowBetter than 27% of packages Maintenance56 Moderate activity, may be stable Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity14 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://avatars.githubusercontent.com/u/30072434?v=4)[oilstone](/maintainers/oilstone)[@oilstone](https://github.com/oilstone) --- Top Contributors [![bullenb](https://avatars.githubusercontent.com/u/66941?v=4)](https://github.com/bullenb "bullenb (72 commits)") ### Embed Badge ![Health badge](/badges/oilstone-api-commerce-layer-integration/health.svg) ``` [![Health](https://phpackages.com/badges/oilstone-api-commerce-layer-integration/health.svg)](https://phpackages.com/packages/oilstone-api-commerce-layer-integration) ``` ### Alternatives [stripe/stripe-php Stripe PHP Library 4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk A PHP wrapper for Twilio's API 1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk PHP SDK for Facebook Business 90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php PHP wrapper for the Meilisearch API 74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax Google API Core for PHP 265103.1M454](/packages/google-gax)[google/common-protos Google API Common Protos for PHP 173103.7M50](/packages/google-common-protos) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)