Darvin Content Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require darvinstudio/darvin-content-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       DarvinStudio\ContentBundle\DarvinContentBundle::class => ['all' => true],
   ];
   

2. Database Migration Run migrations to set up the core tables:

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

3. First Use Case: Basic Content Widget Create a widget via CLI:

   php bin/console darvin:content:widget:create --name="Header" --type="text"
   

   Render it in a Twig template:

   {{ render(controller('DarvinContentBundle:Widget:render', {'id': widget.id})) }}
   

4. Key Documentation

   • Content Widgets
   • Content Controllers

Implementation Patterns

Core Workflows

1. Widget Management

   • Creation: Use darvin:content:widget:create for predefined types (text, html, image, etc.).
   • Editing: Extend DarvinStudio\ContentBundle\Entity\Widget or use the admin interface (if provided).
   • Rendering: Inject the WidgetManager service to fetch and render widgets dynamically:

     $widget = $widgetManager->find($widgetId);
     return $this->renderView('DarvinContentBundle:Widget:render.html.twig', ['widget' => $widget]);
     

2. Content Controllers

   • Routing: Define custom routes for content sections:

     # config/routes.yaml
     darvin_content_section:
         path: /content/{slug}
         controller: DarvinStudio\ContentBundle\Controller\ContentController::sectionAction
     

   • Templates: Override default templates in templates/DarvinContentBundle/ to customize layouts.

3. Metadata Handling

   • Attach metadata to widgets/entities via annotations or YAML:

     # config/packages/darvin_content.yaml
     darvin_content:
         metadata:
             widget.header:
                 title: "Header Widget"
                 description: "Displays a promotional header"
     

   • Access metadata in controllers:

     $metadata = $this->get('darvin_content.metadata_reader')->getMetadata('widget.header');
     

4. Translations

   • Localize widget content by defining translation keys in translations/messages.en.yaml:

     widget:
         header:
             title: "Welcome"
     

   • Use in Twig:

     {{ 'widget.header.title'|trans }}
     

Integration Tips

• Symfony Forms: Bind widgets to forms for editable content:

  $form = $this->createForm(WidgetType::class, $widget);
  

• API Endpoints: Expose widgets via API using FOSRestBundle or API Platform:

  #[ApiResource]
  class Widget extends BaseWidget {}
  

• Event Listeners: Extend functionality via events (e.g., WidgetPreSaveEvent):

  $eventDispatcher->addListener(WidgetEvents::PRE_SAVE, function (WidgetEvent $event) {
      $event->setWidgetContent(strtoupper($event->getWidgetContent()));
  });
  

Gotchas and Tips

Pitfalls

1. Database Schema

   • Migrations may not cover all edge cases. Manually verify tables (widget, widget_type, metadata) exist.
   • Fix: Run php bin/console doctrine:schema:update --force if migrations fail.

2. Widget Caching

   • Widgets are cached by default. Clear cache after updates:

     php bin/console cache:clear
     

   • Tip: Disable caching for development:

     # config/packages/darvin_content.yaml
     darvin_content:
         cache: false
     

3. Translation Overrides

   • Custom translations may conflict with bundle defaults. Use explicit domains:

     # translations/messages.custom.yaml
     widget.header.title: "Custom Title"
     

   • Tip: Use trans with domain:

     {{ 'widget.header.title'|trans({'%domain%': 'custom'}) }}
     

4. Security

   • Widgets rendered via render() may expose sensitive data. Validate input:

     $widget = $widgetManager->find($id);
     if (!$widget->isPublished()) {
         throw $this->createAccessDeniedException();
     }
     

Debugging

• Widget Not Rendering?

  • Check if the widget type exists in widget_type table.
  • Verify the template path (templates/DarvinContentBundle/Widget/{type}.html.twig).
  • Debug: Enable dev mode and check logs:

    php bin/console debug:config darvin_content
    

• Metadata Not Loading?

  • Ensure YAML files are in config/packages/darvin_content.yaml.
  • Clear cache after changes.

Extension Points

1. Custom Widget Types

   • Extend DarvinStudio\ContentBundle\Entity\BaseWidget and register the type:

     $widgetType = new WidgetType();
     $widgetType->setName('custom');
     $widgetType->setClass('App\Entity\CustomWidget');
     $entityManager->persist($widgetType);
     

2. Admin Panel

   • Integrate with EasyAdmin or SonataAdmin for a GUI:

     // Example for EasyAdmin
     $builder
         ->setEntity(Widget::class)
         ->add('content', TextType::class);
     

3. Event Subscribers

   • Hook into lifecycle events (e.g., WidgetPostSave) for analytics or notifications:

     public static function getSubscribedEvents()
     {
         return [
             WidgetEvents::POST_SAVE => 'onWidgetSave',
         ];
     }
     

4. Custom Metadata Drivers

   • Implement MetadataReaderInterface for non-YAML sources (e.g., database):

     class DatabaseMetadataReader implements MetadataReaderInterface
     {
         public function getMetadata(string $key): array
         {
             // Fetch from DB
         }
     }