Aimeos Symfony Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require aimeos/aimeos-symfony
   

   Add the required configurations to config/packages/aimeos_shop.yaml, fos_user.yaml, and security.yaml as per the README.

2. Database Setup: Configure DATABASE_URL in .env and run:

   composer update
   

   This triggers post-install-cmd scripts to set up the database.

3. Create Admin Account:

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

4. Test the Shop: Start the Symfony server:

   symfony serve
   

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

First Use Case: Adding a Product

1. Access Admin Panel: Log in to the admin interface (/admin) using the credentials created.

2. Navigate to Products: Go to Catalog > Products in the admin dashboard.

3. Create a Product:

   • Click Add product.
   • Fill in details like name, price, description, SKU, and assign to a product type (e.g., "default").
   • Upload images (if needed) via the media tab.
   • Save the product.

4. Publish: Ensure the product is published (check the status in the admin panel).

5. View in Shop: Refresh the shop homepage (/shop) to see the newly added product.

Implementation Patterns

Core Workflows

1. Product Management

• CRUD Operations: Use the admin interface (/admin) to manage products, categories, and attributes. Example Twig snippet to list products in a template:

  {% for product in aimeos.product.list() %}
      <div class="product">
          <h3>{{ product.code }}</h3>
          <p>{{ product.price.value }}</p>
      </div>
  {% endfor %}
  

• Bulk Actions: Use the admin panel to import/export products via CSV or JSON.

2. Order Processing

• Frontend Checkout: Aimeos provides built-in checkout flows. Customize the Twig templates in: templates/AimeosShopBundle/Client/Html/Page/Checkout/. Example: Override checkout-step.html.twig to modify the payment step.

• Order Management: Access orders via /admin > Sales > Orders. Use the Aimeos\ShopBundle\Service\Order\Manager\Standard service to programmatically fetch orders:

  $orderManager = $this->container->get('aimeos_mshop_order_manager_standard');
  $orders = $orderManager->search([], ['order.date' => 'desc']);
  

3. Customer Management

• User Integration: Aimeos integrates with FOSUserBundle. Extend the FosUser entity to include Aimeos customer fields:

  // src/Entity/FosUser.php
  use Aimeos\ShopBundle\Entity\FosUser as BaseFosUser;
  
  class FosUser extends BaseFosUser
  {
      // Add custom fields here
  }
  

• Customer Groups: Define customer groups in /admin > Customers > Groups and assign permissions.

4. Catalog Management

• Categories and Filters: Organize products into categories via /admin > Catalog > Categories. Use the Aimeos\ShopBundle\Service\Catalog\Manager\Standard service to fetch categories:

  $categoryManager = $this->container->get('aimeos_mshop_catalog_manager_standard');
  $categories = $categoryManager->search([], ['catalog.code' => 'asc']);
  

• Dynamic Filters: Enable faceted search by configuring filters in /admin > Catalog > Filters.

5. Payment and Shipping

• Payment Methods: Configure payment providers in /admin > Sales > Payment. Example: Add PayPal by creating a new payment method with the PayPal type.

• Shipping Methods: Define shipping methods in /admin > Sales > Shipping. Use the Aimeos\ShopBundle\Service\Order\Manager\Standard to apply shipping rules:

  $orderManager->save($order, ['shipping' => ['method' => 'DHL']]);
  

Integration Tips

1. Custom Controllers

Extend Aimeos controllers to add custom logic. Example:

// src/Controller/CustomProductController.php
namespace App\Controller;

use Aimeos\ShopBundle\Controller\Frontend\ProductController;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;

class CustomProductController extends AbstractController
{
    public function customAction(ProductController $productController): Response
    {
        $products = $productController->listAction();
        // Add custom logic here
        return $this->render('custom/product.html.twig', ['products' => $products]);
    }
}

2. Twig Extensions

Create custom Twig functions to interact with Aimeos services:

// src/Twig/AppExtension.php
namespace App\Twig;

use Aimeos\ShopBundle\Service\Product\Manager\Standard;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class AppExtension extends AbstractExtension
{
    public function __construct(private Standard $productManager) {}

    public function getFunctions(): array
    {
        return [
            new TwigFunction('get_featured_products', [$this, 'getFeaturedProducts']),
        ];
    }

    public function getFeaturedProducts(): array
    {
        return $this->productManager->search(['product.featured' => true]);
    }
}

3. API Integration

Use the JSON:API client to build custom APIs:

// src/Controller/ProductApiController.php
namespace App\Controller;

use Aimeos\ShopBundle\Service\Client\JsonApi\Manager;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;

class ProductApiController extends AbstractController
{
    public function listAction(Manager $jsonApiManager): JsonResponse
    {
        $products = $jsonApiManager->search('product', ['limit' => 10]);
        return new JsonResponse($products);
    }
}

4. Event Listeners

Listen to Aimeos events to extend functionality. Example:

// src/EventListener/CustomOrderListener.php
namespace App\EventListener;

use Aimeos\ShopBundle\Event\OrderEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class CustomOrderListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            OrderEvent::ORDER_SAVE => 'onOrderSave',
        ];
    }

    public function onOrderSave(OrderEvent $event): void
    {
        $order = $event->getOrder();
        // Add custom logic, e.g., send notification
    }
}

5. Job Scheduling

Use Aimeos' job system to run background tasks:

# config/packages/aimeos_shop.yaml
aimeos_shop:
    madmin:
        job:
            manager:
                name: Cron
            cron:
                jobs:
                    custom_job:
                        command: 'app:custom-job'
                        schedule: '0 0 * * *' # Run daily

Gotchas and Tips

Pitfalls

1. Database Schema Mismatch:

   • Issue: Running composer update without --no-dev installs demo data, which may conflict with existing data.
   • Fix: Use SYMFONY_ENV=prod composer update --no-dev in production.

2. Routing Conflicts:

   • Issue: Aimeos routes may conflict with existing Symfony routes.
   • Fix: Ensure aimeos_shop.yaml routes are loaded after your custom routes. Use _route priorities in YAML:

     # config/routes.yaml
     aimeos_shop:
         resource: "@AimeosShopBundle/config/routing.yaml"
         priority: -10
     

3. Caching Issues:

   • Issue: Aimeos caches content aggressively, leading to stale data.
   • Fix: Disable caching in development:

     # config/packages/aimeos_shop.yaml
     aimeos_shop:
         madmin:
             cache:
                 manager:
                     name: None
     

   • Clear cache manually:

     ./bin/console cache:clear
     

4. FOSUserBundle Integration:

   • Issue: Password hashing conflicts if not configured correctly.
   • Fix: Ensure password_hashers in security.yaml matches Aimeos' expectations:

     password_hashers:
         Aimeos\ShopBundle\Entity\FosUser: bcrypt
     

5. **Admin Perm