Easy Shop Bundle Laravel Package

Getting Started

Minimal Setup for First Use

1. Installation

   composer require agence-adeliom/easy-shop-bundle
   bin/console sylius:install:check-requirements
   

   Verify PHP version (^7.4|^8.0) and dependencies (e.g., ext-json).

2. Configure Security Update config/packages/security.yaml with:

   • Encoders for Sylius\Component\User\Model\UserInterface (e.g., argon2i).
   • Providers (sylius_api_admin_user_provider, sylius_shop_user_provider).
   • Firewalls for API (new_api_admin_user, new_api_shop_user) and shop (shop).
   • Access controls (e.g., ROLE_USER for /account).

3. Initialize Sylius

   bin/console sylius:install:setup
   

   This sets up databases, fixtures, and default configurations.

4. First Integration Extend EasyAdmin with shop routes by adding the bundle’s CRUD controllers to your EasyAdmin dashboard configuration:

   # config/easyadmin.yaml
   easy_admin:
       entities:
           Sylius\Bundle\CoreBundle\Entity\Product: ~
           Sylius\Bundle\CoreBundle\Entity\Order: ~
   

Implementation Patterns

Workflows

1. Admin Panel Integration

   • Use EasyAdmin CRUD for Sylius entities (e.g., Product, Order, Customer).
   • Customize fields with agence-adeliom/easy-fields-bundle for Sylius-specific attributes (e.g., price, stock).
   • Example:

     // src/Controller/Admin/ProductCrudController.php
     use EasyCorp\Bundle\EasyAdminBundle\Config\Crud;
     use EasyCorp\Bundle\EasyAdminBundle\Field\AssociationField;
     
     class ProductCrudController extends AbstractCrudController {
         public function configureFields(string $pageName): iterable {
             yield AssociationField::new('category')->autocomplete();
             yield TextField::new('name');
             yield MoneyField::new('price')->setCurrency('EUR');
         }
     }
     

2. Shop Frontend

   • Leverage Sylius routes (e.g., /shop, /cart) via sylius_shop_regex in security.yaml.
   • Override Sylius templates (e.g., twig/Shop/Product/show.html.twig) for custom UI.
   • Use EasyPageBundle for dynamic shop pages (e.g., CMS-driven product pages).

3. API Development

   • Secure API endpoints with JWT (configured via lexik_jwt_authentication).
   • Example API route for products:

     # config/routes.yaml
     sylius_shop_api_product:
         path: /api/products
         controller: sylius.controller.product:showAction
         methods: GET
     

   • Authenticate with:

     curl -X POST -H "Content-Type: application/json" \
          -d '{"email":"user@example.com","password":"password"}' \
          http://your-app/_api/login
     

4. Event-Driven Extensions

   • Subscribe to Sylius events (e.g., sylius.order.completed) to extend functionality.
   • Example:

     // src/EventListener/OrderListener.php
     use Sylius\Component\Core\Event\OrderEvents;
     
     class OrderListener {
         public function __construct(private MailerInterface $mailer) {}
     
         public function onOrderCompleted(OrderCompletedEvent $event) {
             $this->mailer->send(new OrderConfirmationEmail($event->getOrder()));
         }
     }
     

     Register in services.yaml:

     services:
         App\EventListener\OrderListener:
             tags:
                 - { name: kernel.event_listener, event: sylius.order.completed }
     

Gotchas and Tips

Pitfalls

1. Security Misconfigurations

   • Forgetting to set ROLE_USER for /account routes can expose sensitive data.
   • Ensure sylius.security.shop_regex matches your shop routes exactly (e.g., /shop/*).

2. Database Schema Conflicts

   • Sylius migrations may conflict with existing EasyAdmin or custom migrations. Run:

     bin/console doctrine:migrations:diff
     bin/console doctrine:migrations:migrate
     

     after installing the bundle.

3. JWT Authentication Issues

   • If API tokens fail, verify:
     • lexik_jwt_authentication is installed (composer require lexik/jwt-authentication-bundle).
     • APP_SECRET is set in .env.
     • Firewall patterns in security.yaml match your API routes.

4. EasyAdmin CRUD Limitations

   • Sylius entities may require custom field types (e.g., MoneyField for price). Use agence-adeliom/easy-fields-bundle for extensions:

     use Adeliom\EasyFieldsBundle\Field\MoneyField;
     
     yield MoneyField::new('price')->setCurrency('USD');
     

Debugging Tips

1. Enable Sylius Debug Mode Add to config/packages/dev/sylius.yaml:

   sylius:
       debug: true
   

   This logs events and entity changes.

2. Check Event Dispatching Use bin/console debug:event-dispatcher to verify Sylius events are registered.

3. Override Sylius Templates Copy templates from vendor/sylius/sylius/src/Resources/views to templates/Sylius/ to avoid updates overwriting changes.

Extension Points

1. Custom Fields Extend EasyFieldsBundle to support Sylius-specific fields (e.g., TaxonField for product categories):

   // src/Field/TaxonField.php
   use Adeliom\EasyFieldsBundle\Field\AssociationField;
   
   class TaxonField extends AssociationField {
       protected static $defaultOptions = [
           'label' => 'Category',
           'entity' => Sylius\Bundle\CoreBundle\Entity\Taxon::class,
       ];
   }
   

2. API Resource Customization Override Sylius API controllers (e.g., ProductController) to add/remove fields:

   // src/Controller/ProductApiController.php
   use Sylius\Bundle\ApiBundle\Controller\ProductController as BaseController;
   
   class ProductApiController extends BaseController {
       public function showAction(ProductInterface $product) {
           $data = $this->serializer->serialize($product, 'json', [
               'attributes' => ['name', 'slug', 'price'], // Custom fields
           ]);
           return new JsonResponse($data);
       }
   }
   

3. EasyAdmin Dashboard Integration Add shop-specific widgets to the EasyAdmin dashboard:

   # config/easyadmin.yaml
   easy_admin:
       dashboard:
           title: Shop Dashboard
           items:
               - { entity: Sylius\Bundle\CoreBundle\Entity\Order, label: 'Recent Orders', icon: 'shopping-cart' }
   

4. Multi-Language Support Use a2lix/translation-form-bundle for translatable Sylius entities (e.g., Product names):

   # config/packages/a2lix_translation_form.yaml
   a2lix_translation_form:
       default_locale: en
       supported_locales: [en, fr]
       entity_manager: default
   

   Then add translatable fields to your EasyAdmin CRUD:

   yield TranslationField::new('name')->setTranslatable();