Cms Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require chamber-orchestra/cms-bundle

Ensure your project meets the requirements: PHP 8.5+, Symfony 8.0+.

2. Enable the Bundle: Add to config/bundles.php:

   return [
       // ...
       ChamberOrchestra\CmsBundle\ChamberOrchestraCmsBundle::class => ['all' => true],
   ];
   

3. First Use Case:

   • Generate a CRUD Controller: Use the Generator component to scaffold a controller for an existing entity (e.g., Article). Example CLI command (if bundled):

     php bin/console generate:cms-controller Article
     

     Check Generator/ControllerGenerator.php for customization.

   • Extend a Base Controller: Create a custom controller extending AbstractCmsController and use traits like SupportsListOperation or SupportsCreateOperation:

     use ChamberOrchestra\CmsBundle\Controller\AbstractCmsController;
     use ChamberOrchestra\CmsBundle\Controller\SupportsListOperation;
     
     class ArticleController extends AbstractCmsController
     {
         use SupportsListOperation;
         // ...
     }
     

4. Key Directories to Explore:

   • Resources/views/ for Twig templates (e.g., crud/list.html.twig).
   • Form/Type/ for Symfony form types (e.g., ArticleType.php).
   • Processor/ for CRUD logic (e.g., ListProcessor.php).

Implementation Patterns

Workflows

1. Entity Integration:

   • Step 1: Ensure your entity implements ChamberOrchestra\CmsBundle\Entity\CmsEntityInterface (if required).
   • Step 2: Create a DTO in Form/Dto/ (e.g., ArticleDto.php) extending AbstractDto:

     namespace App\Form\Dto;
     
     use ChamberOrchestra\CmsBundle\Form\Dto\AbstractDto;
     
     class ArticleDto extends AbstractDto
     {
         public ?string $title = null;
         public ?string $content = null;
     }
     

   • Step 3: Build a form type in Form/Type/ (e.g., ArticleType.php):

     use ChamberOrchestra\CmsBundle\Form\Type\AbstractCmsType;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
     use Symfony\Component\Form\Extension\Core\Type\TextareaType;
     
     class ArticleType extends AbstractCmsType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
                 ->add('title', TextType::class)
                 ->add('content', TextareaType::class);
         }
     }
     

2. Controller Composition:

   • Use traits to compose CRUD operations. Example for a create + list controller:

     use ChamberOrchestra\CmsBundle\Controller\{
         AbstractCmsController,
         SupportsCreateOperation,
         SupportsListOperation
     };
     
     class ArticleController extends AbstractCmsController
     {
         use SupportsCreateOperation, SupportsListOperation;
     
         protected string $entityClass = Article::class;
         protected string $formType = ArticleType::class;
         protected string $dtoClass = ArticleDto::class;
     }
     

   • Routing: Annotate actions with Symfony’s @Route or use YAML/XML routing.

3. Customizing Views:

   • Override Twig templates by copying them from vendor/chamber-orchestra/cms-bundle/Resources/views/ to your project’s templates/ directory.
   • Extend base templates (e.g., base.html.twig) in templates/base_cms.html.twig.

4. Event-Driven Extensions:

   • Subscribe to CMS events (e.g., CmsEntityCreatedEvent) via EventSubscriber:

     use ChamberOrchestra\CmsBundle\Event\CmsEntityCreatedEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class ArticleSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents(): array
         {
             return [
                 CmsEntityCreatedEvent::class => 'onArticleCreated',
             ];
         }
     
         public function onArticleCreated(CmsEntityCreatedEvent $event): void
         {
             if ($event->getEntity() instanceof Article) {
                 // Custom logic (e.g., send notification).
             }
         }
     }
     

   • Register the subscriber in config/services.yaml:

     services:
         App\EventSubscriber\ArticleSubscriber:
             tags: ['kernel.event_subscriber']
     

5. Asset Customization:

   • Override SCSS variables in assets/scss/cms/_variables.scss (extends vendor/chamber-orchestra/cms-bundle/Resources/assets/scss/bootstrap/_variables.scss).
   • Add custom JS entry points in assets/entry/cms.js:

     import './custom-article-modal';
     

Gotchas and Tips

Pitfalls

1. PHP 8.5+ Strictness:

   • The bundle uses strict types and named arguments. Ensure your codebase complies:

     declare(strict_types=1);
     

   • Example pitfall: Passing null to a non-nullable parameter in a DTO constructor.

2. Entity Repository Assumptions:

   • The bundle assumes your EntityRepository extends ChamberOrchestra\CmsBundle\EntityRepository\AbstractEntityRepository.
   • Fix: If using Doctrine’s base EntityRepository, wrap it or extend the abstract class.

3. Twig Template Overrides:

   • Gotcha: Forgetting to clear the cache after overriding Twig templates:

     php bin/console cache:clear
     

   • Tip: Use {{ dump(_context) }} in Twig to debug template variables.

4. Form Type Inheritance:

   • Gotcha: Extending AbstractCmsType requires implementing configureOptions() to set $this->entityClass and $this->dtoClass.
   • Tip: Use parent::configureOptions($resolver) to avoid redefining common options.

5. Event Dispatching:

   • Gotcha: Events like CmsEntityCreatedEvent are dispatched after entity persistence. Use prePersist lifecycle callbacks for pre-save logic.
   • Tip: Check EventSubscriber/CmsEventSubscriber.php for all dispatched events.

6. Asset Pipeline:

   • Gotcha: Custom JS/SCSS must be imported in Resources/assets/entry/cms.js/cms.scss to avoid 404s.
   • Tip: Use Symfony’s Webpack Encore for bundling:

     npm install --save-dev @symfony/webpack-encore
     

Debugging Tips

1. Enable Debug Mode:

   APP_ENV=dev APP_DEBUG=1 symfony serve
   

   • Check var/log/dev.log for exceptions.

2. DD() in Controllers: Use Symfony’s dump() or dd() for debugging:

   use Symfony\Component\VarDumper\Cloner\VarCloner;
   use Symfony\Component\VarDumper\Dumper\HtmlDumper;
   
   $cloner = new VarCloner();
   $dumper = new HtmlDumper();
   $dumper->dump($cloner->cloneVar($this->getDto()));
   

3. Database Queries: Enable Doctrine’s query logging in config/packages/dev/doctrine.yaml:

   doctrine:
       dbal:
           logging: true
           profiling: true
   

4. Form Errors:

   • Gotcha: Validation errors may not appear if the form type’s configureOptions() doesn’t call parent::configureOptions().
   • Tip: Add this to your form type:

     public function configureOptions(OptionsResolver $resolver): void
     {
         parent::configureOptions($resolver);
         $resolver->setDefaults([
             'csrf_protection' => true,
             'csrf_field_name' => '_token',
             'csrf_token_id'   => 'article_create',
         ]);
     }
     

Extension Points

1. Custom Processors:

   • Extend ChamberOrchestra\CmsBundle\Processor\AbstractProcessor to add custom CRUD logic (e.g., ExportProcessor for CSV/Excel).
   • Example:

     namespace App\Processor;
     
     use ChamberOrchestra\CmsBundle\Processor\AbstractProcessor;
     
     class CustomExportProcessor extends AbstractProcessor
     {
         public function export(array $entities): string
         {
             // Custom export logic.
             return $csvData;
         }
     }
     

   • Register as a service:

     services:
         App\Processor\CustomExportProcessor:
             tags: ['cms.processor']
     

2. **Dynamic