Cms Bundle Laravel Package

Getting Started

Minimal Setup

1. Prerequisite: Ensure akyos/core-bundle is installed and configured first (this bundle depends on it).
2. Installation:

   composer require akyos/cms-bundle
   

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

   Akyos\CmsBundle\AkyosCmsBundle::class => ['all' => true],
   

4. Database Migrations: Run:

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

5. First Use Case: Access the admin dashboard at /admin (default route) to create your first page or menu.

Key Initial Steps

• Admin Access: Register a user via akyos/core-bundle (e.g., php bin/console make:user) and assign the ROLE_ADMIN role.
• Page Creation: Use the admin UI to create a page (e.g., "Home") with a template (e.g., default.html.twig). Place templates in templates/AkyosCmsBundle/ (e.g., templates/AkyosCmsBundle/page/default.html.twig).
• Menu Management: Create menus via the admin panel and assign pages to them.

Implementation Patterns

Core Workflows

1. Page Management

• Dynamic Content: Use Twig variables passed via {{ page.content }} or custom fields (e.g., {{ page.meta_title }}). Extend with custom fields via Doctrine entities (see Doctrine Extensions).
• Templates: Override default templates by copying files from the bundle to your project’s templates/AkyosCmsBundle/ directory. Example:

  {# templates/AkyosCmsBundle/page/custom.html.twig #}
  <h1>{{ page.title }}</h1>
  <div>{{ page.content|raw }}</div> {# CKEditor HTML #}
  

2. Menu Integration

• Menu Blocks: Use the admin panel to create menus (e.g., "Header", "Footer"). Render menus in Twig:

  {{ render(akyos_cms_menu('header')) }}
  

• Dynamic Menu Items: Link menu items to pages or external URLs via the admin UI.

3. User & RGPD Compliance

• User Management: Leverage akyos/core-bundle for users. Extend with CMS-specific roles (e.g., ROLE_CMS_EDITOR).
• RGPD Tools: Use the admin panel to manage user consent and data exports (via karser/recaptcha3-bundle for form protection).

4. Content Editing with CKEditor

• Rich Text: Edit page content in the admin panel using CKEditor (configured via friendsofsymfony/ckeditor-bundle). Access content in Twig as {{ page.content|raw }}.

5. Pagination

• List Views: Use knp-paginator-bundle for paginated lists (e.g., blog posts). Example controller:

  use Knp\Component\Pager\PaginatorInterface;
  
  public function listPages(PaginatorInterface $paginator, Request $request)
  {
      $pages = $this->getDoctrine()->getRepository(Page::class)->findAll();
      return $this->render('page/list.html.twig', [
          'pages' => $paginator->paginate($pages, $request->query->getInt('page', 1), 10),
      ]);
  }
  

Integration Tips

• Event Listeners: Subscribe to events like akyos.cms.page.save to extend page logic:

  // src/EventListener/CmsListener.php
  public static function getSubscribedEvents()
  {
      return [
          'akyos.cms.page.save' => 'onPageSave',
      ];
  }
  

• Custom Fields: Extend the Page entity (located in Akyos\CmsBundle\Entity\Page) by creating a child class and using inheritance mapping.
• Asset Management: Use Symfony’s asset pipeline (webpack-encore) for CSS/JS. Place files in assets/cms/ and import via:

  {{ encore_entry_link_tags('cms-admin') }}
  

Gotchas and Tips

Pitfalls

1. Missing CoreBundle:

   • Error: Class 'Akyos\CoreBundle\AkyosCoreBundle' not found.
   • Fix: Install akyos/core-bundle first and ensure it’s enabled in bundles.php.

2. Template Overrides Not Working:

   • Issue: Custom templates in templates/AkyosCmsBundle/ are ignored.
   • Fix: Clear the cache:

     php bin/console cache:clear
     

   • Ensure the template filename matches the bundle’s default (e.g., default.html.twig for the default template).

3. CKEditor Configuration:

   • Problem: CKEditor toolbar is missing or misconfigured.
   • Fix: Configure via config/packages/fos_ck_editor.yaml:

     fos_ck_editor:
         base_path: /bundles/akyosckeditor
         config:
             default:
                 toolbar: Full
     

4. Doctrine Extensions Conflicts:

   • Warning: beberlei/doctrineextensions and stof/doctrine-extensions-bundle may cause conflicts.
   • Tip: Stick to one bundle for extensions (e.g., use stof for Sluggable and Timestampable).

5. Recaptcha3 Validation:

   • Error: Form submissions fail with "Invalid reCAPTCHA".
   • Debug: Check karser_recaptcha3 configuration in .env:

     KARSER_RECAPTCHA3_SECRET=your_secret_key
     KARSER_RECAPTCHA3_SITE_KEY=your_site_key
     

Debugging Tips

• Admin Panel Issues:
  • Check Symfony’s profiler (/profiler) for errors.
  • Verify user roles (ROLE_ADMIN) are assigned correctly.
• Database Schema:
  • After migrations, validate tables with:

    php bin/console doctrine:schema:validate
    

• Twig Debugging: Dump variables in templates:

  {{ dump(page) }}
  

Extension Points

1. Custom Page Types:

   • Extend the Page entity to add fields (e.g., BlogPost):

     // src/Entity/BlogPost.php
     #[ORM\Entity]
     #[ORM\Table(name: 'akyos_cms_pages')]
     #[ORM\InheritanceType("SINGLE_TABLE")]
     #[ORM\DiscriminatorColumn(name: "type", type: "string")]
     #[ORM\DiscriminatorMap(["page" => Page::class, "blog_post" => BlogPost::class])]
     class BlogPost extends Page
     {
         #[ORM\Column(type: "string", length: 255)]
         private string $author;
     
         // Getters/setters...
     }
     

   • Register the new type in the admin panel via a custom controller or event listener.

2. Custom Admin Routes:

   • Override or extend admin routes by creating a custom controller and routing:

     # config/routes.yaml
     akyos_cms_custom_admin:
         resource: "@AkyosCmsBundle/Resources/config/routing/admin.yaml"
         prefix: /admin/custom
     

3. Custom Fixtures:

   • Use doctrine-fixtures-bundle to seed test data:

     // src/DataFixtures/CmsFixtures.php
     public function load(ObjectManager $manager)
     {
         $page = new Page();
         $page->setTitle('Home');
         $page->setContent('<h1>Welcome!</h1>');
         $manager->persist($page);
         $manager->flush();
     }
     

   • Load fixtures with:

     php bin/console doctrine:fixtures:load
     

Configuration Quirks

1. Paginator Bundle:

   • Ensure knp_paginator is configured in config/packages/knp_paginator.yaml:

     knp_paginator:
         page_range: 5
         default_options:
             page_name: page
             sort_field_name: sort
             sort_direction_name: direction
             distinct: true
     

2. Webpack Encore:

   • If using Encore, ensure webpack.config.js is linked:

     yarn install
     yarn build
     

3. Mailer Configuration:

   • Configure symfony/mailer in .env:

     MAILER_DSN=smtp://user:pass@smtp.example.com:port
     

   • Use for RGPD-related emails (e.g., password resets).

Performance