Cms Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require chaplean/cms-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Chaplean\Bundle\CmsBundle\ChapleanCmsBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Add minimal config/packages/chaplean_cms.yaml:

   chaplean_cms:
       modules:
           block: true
           page: true
           post:
               category: { news: true, testimonial: false }
               action: ['add', 'remove']
           media: true
       template:
           front_layout: 'AppBundle::layout.html.twig'
           front_route: 'homepage'
   

3. First Use Case Generate a basic page via CLI:

   php bin/console chaplean:cms:page:create --title="Home" --slug="home"
   

   Access the backoffice at /cms/backoffice (default route: cms_back_home).

Implementation Patterns

Core Workflows

1. Content Management

   • Pages: Use PageManager service to CRUD pages:

     $page = $this->get('chaplean_cms.page.manager')->findOneBy(['slug' => 'home']);
     $page->setContent('<h1>Welcome</h1>')->save();
     

   • Posts: Manage categories and posts via PostManager:

     $post = $this->get('chaplean_cms.post.manager')->create(
         'news',
         ['title' => 'Breaking News', 'content' => '...']
     );
     

2. Blocks & Media

   • Blocks: Dynamically add reusable blocks to pages:

     {% for block in page.blocks %}
         {{ render_block(block) }}
     {% endfor %}
     

   • Media: Upload assets via MediaManager:

     $media = $this->get('chaplean_cms.media.manager')->upload(
         $file,
         'images'
     );
     

3. Templates & Routing

   • Extend front_layout in Twig to wrap CMS content:

     {# AppBundle/Resources/views/layout.html.twig #}
     {% block content %}
         {{ include('ChapleanCmsBundle::page.html.twig', { page: page }) }}
     {% endblock %}
     

   • Route pages dynamically:

     # config/routes.yaml
     chaplean_cms_page:
         path: /{slug}
         defaults: { _controller: 'ChapleanCmsBundle:Page:show' }
     

4. Backoffice Integration

   • Customize the sidebar menu by overriding back_layout:

     {# AppBundle/Resources/views/backoffice.html.twig #}
     {% extends 'ChapleanCmsBundle::layout-backoffice.html.twig' %}
     {% block sidebar %}
         {{ parent() }}
         <li><a href="{{ path('app_custom_route') }}">Custom</a></li>
     {% endblock %}
     

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Version

   • The bundle targets Symfony 2.8+, but some features (e.g., AppKernel) may break in Symfony 4+. Use config/bundles.php instead.

2. Configuration Overrides

   • Front Layout is Required: Omitting front_layout throws a RuntimeException. Always define it in config.yml.

3. Media Paths

   • Media files are stored in var/media/ by default. Ensure the directory is writable:

     mkdir -p var/media && chmod -R 775 var/media
     

4. Post Categories

   • Only enabled categories (e.g., news: true) appear in the backoffice. Disable unused types to avoid clutter.

5. Route Conflicts

   • The default front_route (app_front) may clash with existing routes. Rename it in config:

     front_route: 'app_home'
     

Debugging Tips

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

   debug: true
   

   Logs errors to var/log/chaplean_cms.log.

2. Clear Cache After Config Changes

   php bin/console cache:clear
   

3. Dump Page/Post Data Use the debug:container command to inspect services:

   php bin/console debug:container chaplean_cms.page.manager
   

Extension Points

1. Custom Block Types Extend the block system by creating a new block class and registering it in the BlockManager:

   // src/Service/CustomBlockManager.php
   public function registerBlocks()
   {
       $this->manager->addBlockType(
           'custom',
           'AppBundle\Entity\CustomBlock',
           'AppBundle:Block:custom.html.twig'
       );
   }
   

2. Override Twig Functions Replace default Twig functions (e.g., render_block) in your theme:

   {% macro render_block(block) %}
       {# Custom logic here #}
       {{ block.content|raw }}
   {% endmacro %}
   

3. Event Listeners Hook into CMS events (e.g., page.save):

   // src/EventListener/CmsListener.php
   public function onPageSave(PageEvent $event)
   {
       if ($event->getPage()->getSlug() === 'home') {
           $event->setContent($event->getContent() . '<!-- Analytics -->');
       }
   }
   

   Register in services.yaml:

   services:
       AppBundle\EventListener\CmsListener:
           tags:
               - { name: kernel.event_listener, event: chaplean.cms.page.save, method: onPageSave }
   

4. Custom Backoffice Routes Add routes to config/routes.yaml:

   app_cms_custom:
       path: /cms/custom
       controller: AppBundle\Controller\CustomCmsController::index