Aimeos Symfony2 Laravel Package

Getting Started

Minimal Steps to Launch

1. Installation

   composer create-project symfony/website-skeleton:~4.4 myshop
   cd myshop
   composer require aimeos/aimeos-symfony:^2023.10 friendsofsymfony/user-bundle:^4.0
   

   Add the post-install-cmd and post-update-cmd scripts to composer.json as shown in the README.

2. Configure Bundles

   • Add fos_user config to ./config/packages/fos_user.yaml.
   • Add aimeos_shop config to ./config/packages/aimeos_shop.yaml (FS, MShop, and customer manager settings).
   • Set up routes in ./config/routes/aimeos_shop.yaml and ./config/routes/fos_user.yaml.

3. Database Setup Configure doctrine.yaml and .env with your database credentials.

4. Run Installer

   composer update
   ./bin/console aimeos:account --admin admin@example.com
   

5. Test Start the server:

   php -S 127.0.0.1:8000 -t public
   

   Access the shop at http://127.0.0.1:8000/shop and admin at http://127.0.0.1:8000/admin.

First Use Case: Adding a Product

1. Admin Interface Log in to /admin and navigate to Catalog → Products. Click Add to create a new product.

2. Product Attributes Fill in:

   • Code (unique identifier, e.g., prod-001).
   • Label (display name, e.g., "Premium Widget").
   • Price (set base price and currency).
   • Stock (quantity and availability status).
   • Images (upload via the media manager).

3. Save & Publish Click Save and then Publish to make the product live.

4. Frontend Verification Visit /shop to see the product in the catalog.

Implementation Patterns

Core Workflows

1. Product Management

• CRUD via Admin UI: Use the Aimeos admin interface (/admin) for product, category, and attribute management.
• Programmatic Access:

  $productManager = $this->container->get('aimeos_mshop_product_manager');
  $product = $productManager->findItem('prod-001', ['price', 'stock']);
  

• Bulk Operations: Use the aimeos:mshop:product:import command for CSV/JSON imports.

2. Order Processing

• Frontend Flow:
  1. Add items to cart (/cart/add).
  2. Checkout via /checkout.
  3. Confirm order (/order/confirm).
• Backend Hooks:

  // Extend order workflow in a custom service
  $eventDispatcher = $this->container->get('event_dispatcher');
  $eventDispatcher->addListener('aimeos.mshop.order.place.after', [$this, 'onOrderPlaced']);
  

3. Custom Templates

• Override Twig templates in templates/AimeosShopBundle/ (e.g., product/list.html.twig).
• Extend with custom blocks:

  {% block aimeos_product_price %}
      {{ parent() }}
      <span class="custom-badge">{{ product.custom_field }}</span>
  {% endblock %}
  

4. API Integration

• Use the JSON:API client for headless setups:

  $client = $this->container->get('aimeos.client.jsonapi');
  $response = $client->get('/product?filter[code][like]=prod-001');
  

5. Payment & Shipping

• Configure plugins in aimeos_shop.yaml:

  mshop:
      payment:
          method:
              - name: PayPal
                active: true
      shipping:
          method:
              - name: Standard
                active: true
  

• Extend with custom providers by implementing Aimeos\MShop\Payment\Iface.

Integration Tips

Symfony Services

• Dependency Injection: Inject Aimeos managers directly:

  public function __construct(
      private Aimeos\MShop\Product\Manager\Iface $productManager,
      private Aimeos\MShop\Order\Manager\Iface $orderManager
  ) {}
  

• Event Listeners: Tap into Aimeos events (e.g., aimeos.mshop.product.save.after).

Performance

• Caching: Disable for development (cache.manager.name: None in aimeos_shop.yaml).
• Database Indexes: Ensure code and siteid columns are indexed for large catalogs.

Security

• Admin Access: Restrict /admin via Symfony’s access_control (as shown in the README).
• CSRF Protection: Enabled by default for checkout flows.

Gotchas and Tips

Pitfalls

1. Route Conflicts

   • Aimeos routes are prefixed with /shop by default. Conflicts may arise with custom routes.
   • Fix: Use _route in Twig links or adjust aimeos_shop.yaml:

     route:
         prefix: /my-custom-prefix
     

2. FOSUser Integration

   • Ensure FosUser entity extends Aimeos\ShopBundle\Entity\FosUser.
   • Error: Class not found → Verify composer.json includes aimeos/ai-fosuser.

3. Database Schema Mismatch

   • Running composer update without --no-dev installs demo data, which may conflict with existing tables.
   • Fix: Drop and recreate the database or use --no-dev in production.

4. Twig Template Overrides

   • Overriding templates requires the AimeosShopBundle namespace in templates/.
   • Error: TemplateNotFoundException → Check template paths and permissions.

5. Password Hashing

   • Defaults to Bcrypt. Changing to Argon2 requires updating aimeos_shop.yaml:

     mshop:
         customer:
             manager:
                 password:
                     name: Argon2
     

Debugging Tips

1. Log Configuration

   • Enable debug logs in config/packages/monolog.yaml:

     handlers:
         aimeos:
             type: stream
             path: "%kernel.logs_dir%/aimeos.log"
             level: debug
     

   • Check logs for Aimeos\MShop entries.

2. SQL Queries

   • Use Doctrine’s profiler to inspect queries:

     $this->container->get('profiler')->disable();
     

   • Enable in config/packages/dev/doctrine.yaml:

     dbal:
         profiling: true
     

3. Admin UI Issues

   • Clear cache after config changes:

     ./bin/console cache:clear
     

   • Blank Admin Page: Verify jqadm assets are loaded (check browser console for 404s).

Extension Points

1. Custom Product Attributes

   • Extend the product table via migrations:

     // src/Migrations/VersionYYYYMMDDHHMMSS.php
     public function up(Schema $schema): void {
         $table = $schema->getTable('mshop_product');
         $table->addColumn('custom_field', 'string', ['length' => 255, 'notnull' => false]);
     }
     

   • Add to the admin UI via a custom plugin (extend Aimeos\Admin\Jqadm\Plugin\AbstractPlugin).

2. Custom Payment Methods

   • Implement Aimeos\MShop\Payment\Iface:

     class CustomPaymentMethod extends \Aimeos\MShop\Payment\Standard\Standard implements Iface {
         public function place(Aimeos\MShop\Order\Item\Iface $orderItem, array $context): void {
             // Custom logic (e.g., call external API)
         }
     }
     

   • Register in aimeos_shop.yaml:

     mshop:
         payment:
             method:
                 - name: Custom
                   active: true
                   service: App\Service\CustomPaymentMethod
     

3. Headless API Extensions

   • Extend JSON:API responses by overriding the Aimeos\Client\JsonApi\Resource classes.
   • Example: Add a custom field to product responses:

     class CustomProductResource extends \Aimeos\Client\JsonApi