Aimeos Laravel Laravel Package

Getting Started

Start by installing Aimeos in an existing Laravel app using Composer. Require aimeos/aimeos-laravel (e.g., ~2025.10 for Laravel 10/11/12), run composer update -W, then execute:

php artisan vendor:publish --tag=config --tag=public
php artisan migrate
php artisan aimeos:setup --option=setup/default/demo:1

Ensure your .env uses a supported DB (MySQL ≥5.7.8, PostgreSQL, etc.), not SQLite. Set up Laravel Breeze/Jetstream first—Aimeos integrates with Laravel’s auth but requires correct route naming (e.g., avoid /profile conflict by renaming to /profile/me). First use case: quickly spin up a production-ready shop frontend/backend in minutes, with demo products pre-loaded.

Implementation Patterns

• Modular UI: Inject frontend components via Blade directives (@aimeos('shop')) or routes (/shop). Use @aimeos('admin') to embed the full admin backend anywhere (e.g., yoursite.com/admin).
• API-first: Leverage the built-in JSON:API (e.g., /rest) or GraphQL admin API (/graphql/admin) for headless setups (e.g., Vue/React SPAs). The headless distribution simplifies this.
• Customization layers:
  • Override views via resources/views/vendor/aimeos/
  • Extend controllers/actions using Laravel’s extends pattern (e.g., extends \Aimeos\Shop\Controller\AccountController)
  • Add custom job classes for cart rules, pricing, or fulfillment
• Multi-tenancy: Configure multiple shops per installation using config/shop.php shops array—each with its own currency, locale, pricing, and vendors.
• Vendor integrations: Use the vendor extension to build marketplaces (e.g., vendor dashboard, own inventory, separate payouts) via aimeos:setup --option=setup/default/vendors:1.

Gotchas and Tips

• Database pitfall: MySQL’s utf8mb4 default key length issues cause "Specified key was too long" errors. Fix by switching to utf8 + utf8_unicode_ci in config/database.php before running migrate.
• Auth route clash: Laravel Breeze’s default /profile route overrides Aimeos’s aimeos_shop_account. Rename routes in routes/web.php to /profile/me (and update controller references).
• Config quirks: config/shop.php is auto-generated on vendor:publish --tag=config—never edit the package’s original config. Use aimeos:setup to regenerate if needed.
• Performance: Enable Redis caching (CACHE_STORE=redis) for catalog/product lists. Use aimeos:cache:warmup in deployment scripts to pre-fill caches.
• Extensibility: The Composer::join script hook in composer.json auto-links Aimeos assets—don’t remove it. To override services, use Laravel’s app()->bind() in AppServiceProvider.
• RTL & i18n: Full RTL support is automatic but requires setting locale.orientation to rtl in config/shop.php—update language files under lang/vendor/aimeos/.