Resource Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sylius/resource-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Sylius\Bundle\ResourceBundle\SyliusResourceBundle::class => ['all' => true],
   ];
   

2. Define a Resource Create a Resources/config/doctrine/YourEntity.orm.yml (or equivalent for ODM):

   Sylius\Bundle\ResourceBundle\Doctrine\ORM\ResourceEntityRepository:
       arguments:
           $entityClass: App\Entity\YourEntity
   

3. Register the Resource In config/packages/sylius_resource.yaml:

   sylius_resource:
       resources:
           app.your_entity:
               driver: doctrine/orm
               classes:
                   model: App\Entity\YourEntity
                   repository: Sylius\Bundle\ResourceBundle\Doctrine\ORM\ResourceEntityRepository
   

4. First Controller Extend ResourceController in src/Controller/YourEntityController.php:

   use Sylius\Bundle\ResourceBundle\Controller\ResourceController;
   
   class YourEntityController extends ResourceController
   {
       public function __construct(
           YourEntityRepository $repository,
           YourEntityManagerInterface $manager
       ) {
           parent::__construct($repository, $manager);
       }
   }
   

5. Route the Controller In config/routes.yaml:

   app_your_entity:
       resource: |
           alias: app.your_entity
           section: admin
           templates: "@SyliusResourceBundle:Crud"
           except: ['new', 'create']
           path: /admin/your-entities
       type: sylius.resource
   

First Use Case: Basic CRUD

• List: /admin/your-entities (automatically paginated, sortable, filterable).
• Show: /admin/your-entities/{id}.
• Update: POST/PUT to /admin/your-entities/{id} with _method=_put or X-HTTP-Method-Override.
• Delete: DELETE /admin/your-entities/{id}.

Implementation Patterns

1. Repository-Driven Workflows

• Custom Queries: Extend ResourceEntityRepository to add methods:

  public function findByActive(bool $active): array
  {
      return $this->createQueryBuilder('o')
          ->andWhere('o.active = :active')
          ->setParameter('active', $active)
          ->getQuery()
          ->getResult();
  }
  

  Use in controller:

  $this->repository->findByActive(true);
  

• Criteria-Based Filtering:

  use Sylius\Bundle\ResourceBundle\Criteria\Criteria;
  
  $criteria = new Criteria();
  $criteria->add('name', 'LIKE', '%search%');
  $this->repository->matching($criteria);
  

2. Controller Customization

• Override Actions:

  public function indexAction(): Response
  {
      $this->repository->addFilter('active', true);
      return parent::indexAction();
  }
  

• Pre/Post Hooks:

  protected function preUpdate(YourEntityInterface $entity): void
  {
      $entity->setUpdatedAt(new \DateTime());
  }
  

3. API Integration

• Serialization Groups: Configure in config/packages/serializer.yaml:

  sylius_resource:
      resources:
          app.your_entity:
              serialization_groups: [api]
  

  Use in entity:

  #[Groups(['api'])]
  private string $name;
  

• API Platform Compatibility:

  use Sylius\Bundle\ResourceBundle\Controller\ApiPlatformResourceController;
  
  class YourEntityController extends ApiPlatformResourceController
  {
      // Extend for custom logic
  }
  

4. Event-Driven Extensions

• Listen to Events:

  use Sylius\Bundle\ResourceBundle\Event\ResourceControllerEvent;
  
  $dispatcher->addListener(
      ResourceControllerEvent::PRE_CREATE,
      function (ResourceControllerEvent $event) {
          $event->getSubject()->setCreatedBy($this->getUser());
      }
  );
  

5. Multi-Repository Setups

• Shared Logic:

  sylius_resource:
      resources:
          app.your_entity:
              driver: doctrine/orm
              classes:
                  repository: App\Repository\YourEntityRepository
          app.your_entity_archive:
              driver: doctrine/orm
              classes:
                  repository: App\Repository\YourEntityArchiveRepository
  

  Reuse controllers with different repositories.

Gotchas and Tips

Pitfalls

1. Repository Injection:

   • Issue: Forgetting to inject the custom repository in the controller.
   • Fix: Always extend ResourceController and pass the correct repository in the constructor:

     public function __construct(YourEntityRepository $repository, YourEntityManagerInterface $manager)
     {
         parent::__construct($repository, $manager);
     }
     

2. Filter Persistence:

   • Issue: Filters applied in indexAction persist across requests if not cleared.
   • Fix: Reset filters explicitly:

     $this->repository->removeAllFilters();
     

3. ORM vs. ODM:

   • Issue: Mixing ORM and ODM repositories in the same resource.
   • Fix: Stick to one persistence layer per resource. Configure driver correctly in sylius_resource.yaml.

4. Serialization Conflicts:

   • Issue: API responses include sensitive fields (e.g., password).
   • Fix: Explicitly define serialization groups and use #[Groups] attributes.

5. Caching Headaches:

   • Issue: matching(Criteria) results not cached.
   • Fix: Implement CacheableInterface in your repository or use Cache component manually.

Debugging Tips

1. Enable SQL Logging:

   # config/packages/dev/doctrine.yaml
   doctrine:
       dbal:
           logging: true
           profiling: true
   

2. Criteria Debugging: Dump criteria before execution:

   $criteria = $this->repository->getUsedCriteria();
   dump($criteria->getFilters());
   

3. Event Dispatcher: Check fired events in PRE_*/POST_* hooks:

   $dispatcher->addListener(
       ResourceControllerEvent::PRE_CREATE,
       function (ResourceControllerEvent $event) {
           error_log('Creating: ' . $event->getSubject()->getId());
       }
   );
   

Extension Points

1. Custom Managers: Implement ManagerInterface for non-Doctrine backends (e.g., Elasticsearch):

   class ElasticsearchManager implements ManagerInterface
   {
       public function createNew(): YourEntityInterface
       {
           return new YourEntity();
       }
   
       public function persist(YourEntityInterface $entity): void
       {
           // Elasticsearch logic
       }
   }
   

2. Dynamic Routes: Use sylius.resource route type with dynamic segments:

   app_your_entity_show:
       path: /your-entities/{id}/{slug}
       methods: GET
       defaults:
           _controller: app.your_entity.controller:showAction
           _sylius:
               resource: app.your_entity
               id: id
               criteria:
                   slug: =context.get('slug')
   

3. Bulk Actions: Extend ResourceController to handle bulk operations:

   public function bulkUpdateAction(Request $request): Response
   {
       $ids = $request->request->get('ids', []);
       $entities = $this->repository->findBy(['id' => $ids]);
   
       foreach ($entities as $entity) {
           $entity->setActive(false);
           $this->manager->persist($entity);
       }
   
       $this->manager->flush();
   
       return new JsonResponse(['success' => true]);
   }
   

Configuration Quirks

1. Driver Mismatch:

   • Ensure driver in sylius_resource.yaml matches your setup (e.g., doctrine/orm, doctrine/mongodb).

2. Repository Aliasing:

   • If using multiple repositories for the same entity, alias them:

     sylius_resource:
         resources:
             app.your_entity:
                 driver: doctrine/orm
                 classes:
                     repository: App\Repository\YourEntityRepository
                     archive_repository: App\Repository\YourEntityArchiveRepository
     

3. Template Overrides:

   • Override templates in templates/SyliusResourceBundle/Crud/ (e.g., index.html.twig).
   • Use templates option in routes:

     templates: "@App/Crud"
     

4. Pagination Defaults: