Cmsbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alpixel/cmsbundle
   

   Ensure SonataAdminBundle and its dependencies (sonata-project/*) are installed (listed in composer.json).

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

   Alpixel\CMSBundle\AlpixelCMSBundle::class => ['all' => true],
   

3. First Use Case:

   • Create a Sonata Admin Class: Extend Alpixel\CMSBundle\Admin\AbstractAdmin for your CMS entities (e.g., pages, articles). Example:

     use Alpixel\CMSBundle\Admin\AbstractAdmin;
     
     class PageAdmin extends AbstractAdmin {
         protected $baseRouteName = 'page';
         protected $baseRoutePattern = 'page';
     }
     

   • Register the Admin: In services.yaml:

     services:
         App\Admin\PageAdmin:
             tags: [sonata.admin]
     

4. Key Configs:

   • Locales: Configure in config/packages/lunetics_locale.yaml (required for multilingual support).
   • SEO: Extend Alpixel\SEOBundle via config/packages/alpixel_seo.yaml.
   • Media: Use Alpixel\MediaBundle for file uploads (configured in config/packages/alpixel_media.yaml).

5. First Route: Access the admin panel at /admin (default route). The bundle integrates with Sonata’s admin dashboard.

Implementation Patterns

Core Workflows

1. Entity Management:

   • Tree Structure: Leverage pixassociates/sortable-behavior-bundle for hierarchical content (e.g., nested pages). Example entity:

     use Pix\SortableBehavior\SortableTrait;
     
     class Page {
         use SortableTrait;
         // ...
     }
     

   • Drafts: Use the built-in draft feature (enabled via isDraftable() in AbstractAdmin).

2. Multilingual Content:

   • Translations: Use happyr/translation-bundle or jms/translation-bundle for locale-specific fields. Example admin field:

     $fieldDescription = $this->getTranslationField('description', 'text', [
         'template' => 'AlpixelCMSBundle:Admin:Field:translation.html.twig',
     ]);
     

3. SEO Optimization:

   • Meta Tags: Extend Alpixel\SEOBundle to auto-generate meta titles/descriptions from entity fields. Example:

     // In your Admin class
     public function configureRoutes(RouteConfiguration $configuration) {
         $configuration->add('seo', $this->getRouterIdParameter() . '/seo');
     }
     

4. Media Handling:

   • Uploads: Use Alpixel\MediaBundle for file/image uploads. Link media to entities via Sonata’s AssociationType. Example field:

     $formMapper->add('image', 'sonata_type_media', [
         'provider' => 'sonata.media.provider.file',
     ]);
     

5. Routing:

   • Dynamic Routes: Use jms/i18n-routing-bundle for locale-aware URLs. Example route:

     # config/routes.yaml
     page_show:
         path: /{_locale}/page/{slug}
         defaults: { _controller: 'App\Controller\PageController::show' }
         requirements:
             _locale: %app.supported_locales%
     

6. Blocks and Layouts:

   • Sonata Blocks: Customize the admin dashboard using sonata-block-bundle. Example block service:

     services:
         app.block.service.page_list:
             class: App\Block\PageListBlock
             tags: [sonata.block]
     

Integration Tips

• Custom Templates: Override Sonata templates in templates/AlpixelCMSBundle/ (e.g., Admin/Field/translation.html.twig).
• Event Listeners: Extend functionality via Symfony events. Example:

  // src/EventListener/SitemapListener.php
  class SitemapListener {
      public function onKernelRequest(GetResponseEvent $event) {
          // Modify sitemap generation logic
      }
  }
  

  Register in services.yaml:

  services:
      App\EventListener\SitemapListener:
          tags: [kernel.event_listener, kernel.request]
  

• White-Labeling: Use the white_label feature to customize the admin UI (e.g., logos, colors). Configure in config/packages/alpixel_cms.yaml:

  alpixel_cms:
      white_label:
          logo: 'bundles/acms/images/logo.png'
          name: 'My CMS'
  

Gotchas and Tips

Pitfalls

1. Locale Handling:

   • Issue: Forgetting to configure lunetics_locale-bundle can break multilingual features.
   • Fix: Ensure config/packages/lunetics_locale.yaml includes:

     lunetics_locale:
         default_locale: en
         supported_locales: en|fr|de
     

   • Debug: Check for LocaleNotFoundException if translations fail to load.

2. Sonata Admin Version Mismatch:

   • Issue: The bundle targets SonataAdminBundle ^3.0. Using ~2.0 may cause errors.
   • Fix: Pin dependencies in composer.json:

     "sonata-project/admin-bundle": "^3.0"
     

3. Draft Feature Quirks:

   • Issue: Drafts may not appear in the admin list if the isDraftable() method isn’t implemented.
   • Fix: Override isDraftable() in your AbstractAdmin:

     protected function isDraftable() {
         return true;
     }
     

4. Sitemap Generation:

   • Issue: Sitemap listener may fail if routes aren’t properly configured.
   • Fix: Ensure your entity’s getRoute() method returns a valid route:

     public function getRoute() {
         return 'page_show';
     }
     

5. Media Provider Conflicts:

   • Issue: Alpixel\MediaBundle may conflict with other media bundles (e.g., sonata-media-bundle).
   • Fix: Explicitly configure the provider in config/packages/alpixel_media.yaml:

     alpixel_media:
         providers:
             file: sonata.media.provider.file
     

6. Translation Bundle Conflicts:

   • Issue: Using both jms/translation-bundle and happyr/translation-bundle can cause conflicts.
   • Fix: Stick to one bundle. Example for happyr/translation-bundle:

     happyr_translation:
         default_locale: en
         locales: [en, fr, de]
     

Debugging Tips

1. Admin Panel Issues:

   • Clear cache after changes:

     php bin/console cache:clear
     

   • Check Sonata admin logs:

     php bin/console sonata:admin:debug
     

2. Database Migrations:

   • Run migrations after installing:

     php bin/console doctrine:migrations:migrate
     

   • Verify sortable_behavior and translatable extensions are applied to entities.

3. CKEditor Configuration:

   • If CKEditor fields don’t render, ensure egeloen/ckeditor-bundle is configured:

     egeloen_ckeditor:
         editor: ckeditor
         config: {}
     

4. Event Debugging:

   • Dump events in a listener to trace execution:

     public function onKernelRequest(GetResponseEvent $event) {
         dump($event->getRequest()->attributes->all());
     }
     

Extension Points

1. Custom Admin Classes:

   • Extend Alpixel\CMSBundle\Admin\AbstractAdmin to add custom logic (e.g., prePersist hooks):

     protected function prePersist($object) {
         $object->setCreatedAt(new \DateTime());
     }
     

2. Dynamic Forms:

   • Use sonata_type_model_list for dynamic entity selection:

     $formMapper->add('parent', 'sonata_type_model_list', [
         'by_reference' => false,
         'property' => 'title',
         'model_manager' => $this->getModelManager(),
         'class' => 'App\Entity\Page',
     ]);
     

3. API Endpoints:

   • Expose CMS data via API using Symfony’s Serializer or ApiPlatform. Example:

     # config/packages/api_platform.yaml
     api_platform:
         formats:
             jsonld: ['application/ld+json']
             json: ['application/json']
         patch_formats:
             json