Ai Laravel Laravel Package

Getting Started

Begin by installing the package via Composer: composer require aimeos/ai-laravel. Run php artisan vendor:publish --provider="Aimeos\AiLaravel\AiLaravelServiceProvider" to publish config and migration files, then execute php artisan migrate to seed the required database tables. For immediate validation, run php artisan aimeos:setup to install sample data and launch a demo storefront. Access basic shop operations using the Aimeos facade—e.g., Aimeos::shop()->get('basket')—and configure site locales, currencies, and payment methods in config/aimeos.php.

Implementation Patterns

• Hybrid Rendering: Combine Aimeos' built-in Blade components (e.g., @aimeos('site/header')) with custom Laravel views for rapid storefront development, while retaining full control over layout and design.
• API-First Frontend: Consume Aimeos’ JSON:API endpoints (/api/jsonadm, /api/jsonapi) to power SPA or mobile frontends; use Laravel Sanctum for stateless auth with the jsonadm guard.
• Site-Aware Multi-Tenancy: Define multiple sites (e.g., en, de, shop-b2b) in config/aimeos.php and use Aimeos::shop()->context()->site() to scope products, prices, and customers per tenant without code changes.
• Custom Order Processing: Extend Aimeos\Shop\Controller\CheckoutController in your app to inject custom logic (e.g., promo validation, tax overrides) before persisting orders—bind replacements via app()->singleton(…) in a service provider.
• Admin Customization: Embed the admin interface in your app using a dedicated route (Route::get('/admin', [AdminController::class, 'index'])) and customize the layout by publishing Aimeos’ admin views (php artisan vendor:publish --tag=aimeos-admin-views).

Gotchas and Tips

• Charset Critical: Use utf8mb4_unicode_ci for MySQL to avoid SQLSTATE[HY000]: General error: 1366 Incorrect string value errors when storing multilingual product names or customer data.
• Config Caching Trap: Always clear config cache (php artisan config:clear) after modifying config/aimeos.php, especially when changing site codes or locale IDs—changes won’t take effect otherwise.
• Auth Boundary: Aimeos uses its own session-based auth layer; avoid mixing Laravel’s Auth::user() with Aimeos’ customer context. Instead, retrieve the current user via Aimeos::shop()->get('account')->getUser().
• Migration Risk: Aimeos may add new database columns during upgrades—always review database/migrations/ diffs before running php artisan migrate and test in staging.
• Log Tuning: Enable detailed checkout tracing via 'log' => ['enabled' => true, 'level' => 4] in config/aimeos.php; inspect storage/logs/aimeos.log for low-level payment gateway errors not surfaced in Laravel’s default logs.