dvolkering/laravel-magento-guidelines

Laravel Boost guidelines and skill for building Adobe Commerce (Magento 2) integrations with justbetter/laravel-magento-client.

dev-master 2026-04-22 22:00 UTC

Requires

• php: ^8.2

Requires (Dev)

• justbetter/laravel-magento-client: ^2.0
• laravel/boost: ^2.0

Suggests

• justbetter/laravel-magento-client: The Magento client these guidelines assume. Install it in your Laravel app.
• laravel/boost: Required to auto-discover and load the guidelines and skill shipped by this package.

MIT

• Your Name

• laravel
• magento
• ai
• magento2
• adobe-commerce
• laravel-boost
• boost-guidelines

README

Opinionated Laravel Boost guidelines and an on-demand skill for building Adobe Commerce (Magento 2) integrations on top of justbetter/laravel-magento-client.

When this package is installed alongside Laravel Boost, Boost auto-discovers the contents of resources/boost/ and makes them available to your coding agent. The philosophy:

• Thin upfront guideline (resources/boost/guidelines/core.blade.php, ~60 lines) — always loaded. Tells the agent what stack to use, the required app/Magento/ layout, and the non-negotiable rules.
• On-demand skill (resources/boost/skills/magento-development/) — loaded only when the agent is actually doing Magento work. Contains the detailed conventions: SearchCriteria gotchas, DTO pattern, bulk endpoints, jobs + AvailableMiddleware, error handling, testing.
• Reference files under the skill — the full Adobe Commerce 2.4.8 Admin REST OpenAPI spec (swagger.json, ~2 MB), a grouped paths index (paths-index.md, ~40 KB), and a jq cheatsheet (lookup.md). The agent discovers endpoints via the cheap index and jq's into the spec only for the specific endpoint it needs — no context pollution.

Installation

In a Laravel application that already has Boost installed:

composer require dvolkering/laravel-magento-guidelines --dev
php artisan boost:update --discover

boost:update --discover tells Boost to pick up guidelines and skills from newly installed packages. After this, the Magento guidelines will be part of your project's AI context, and the magento-development skill will load when you ask your agent to work on Magento-facing code.

What the agent gets

Always in context (from core.blade.php)

• Which client to use (justbetter/laravel-magento-client), and which ones to avoid
• The required app/Magento/ folder layout
• A handful of non-negotiable rules (inject the client, use AvailableMiddleware in jobs, resolve by business key, return DTOs not raw arrays)
• A pointer to the magento-development skill for depth

Loaded on demand (from the skill's SKILL.md)

• Decision guide: Controller vs Job, single call vs Action, GraphQL vs REST
• SearchCriteria builder usage, full filter-condition table, pagination rules, sparse fieldsets
• DTO pattern with custom-attribute indexing (Magento's list-of-objects → map pitfall)
• Resource class pattern with correct 404 handling and rawurlencode() for SKUs
• Create / update / delete patterns, idempotent PUT over POST for sync
• Bulk / async API usage and status polling
• Error handling: RequestException, ConnectionException, and a MagentoNotFoundException
• Jobs with AvailableMiddleware and retry rules (5xx retry, 4xx fail)
• Multi-connection and store-code handling
• Testing with Http::fake() and the store-code wildcard trap

Loaded only when looking up an endpoint

• reference/paths-index.md — grouped flat TOC of all 477 endpoints
• reference/lookup.md — jq recipes for request/response shapes and $ref resolution
• reference/swagger.json — the full 2 MB spec, never read wholesale

Customising

The guideline and skill are opinionated — they reflect one way of structuring a Magento integration in Laravel. To adapt:

• Fork this package and adjust resources/boost/guidelines/core.blade.php and resources/boost/skills/magento-development/SKILL.md to your team's conventions.
• Override per project by placing a file with a matching path in your app's .ai/guidelines/ — Boost will use your override instead of the one shipped here.
• Swap the swagger in reference/swagger.json for a spec generated from your specific Magento instance (including third-party modules and extension attributes). The Adobe Commerce docs describe how to generate a local API reference.

Why a package and not just .ai/guidelines/ in the app?

Use this package if:

• You maintain multiple Laravel apps that integrate with Magento and want the same conventions applied to all of them.
• You want to version and changelog the guidelines separately from any individual app.
• You want the swagger reference to be a cached Composer artifact, not a committed file in every app.

For a single project, copying the contents of resources/boost/ into the app's .ai/ directory is simpler.

License

MIT.