Page Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sonata-project/page-bundle
   

   Add to config/bundles.php:

   SonataProject\PageBundle\SonataPageBundle::class => ['all' => true],
   

2. Database Migrations: Run php bin/console doctrine:migrations:diff and php bin/console doctrine:migrations:migrate to create the required tables (page, page_slot, page_block, etc.).

3. First Use Case: Create a page via CLI:

   php bin/console sonata:page:create --name="Homepage" --slug="home" --enabled=true
   

   Access the admin interface at /admin/page (ensure SonataAdminBundle is installed).

Where to Look First

• Admin Dashboard: /admin/page for CRUD operations.
• Configuration: config/packages/sonata_page.yaml (default settings).
• Twig Usage: Check templates/sonata/page/page.html.twig for rendering logic.
• Blocks: Explore src/Sonata/PageBundle/Block/ for reusable components.

Implementation Patterns

Core Workflows

1. Page Creation & Management:

   • Use the Sonata Admin UI or create programmatically:

     $page = new Page();
     $page->setName('About Us');
     $page->setSlug('about');
     $page->setEnabled(true);
     $manager = $this->getDoctrine()->getManager();
     $manager->persist($page);
     $manager->flush();
     

2. Block Integration:

   • Extend Sonata\PageBundle\Model\BlockInterface for custom blocks:

     namespace App\Block;
     use Sonata\PageBundle\Model\BlockInterface;
     
     class CustomBlock implements BlockInterface {
         public function execute() { /* ... */ }
     }
     

   • Register in services.yaml:

     services:
         app.block.custom:
             class: App\Block\CustomBlock
             tags:
                 - { name: sonata.page.block }
     

3. Page Rendering:

   • Use Twig in templates:

     {% render page %}
     

   • Override default templates by copying from vendor/sonata-project/page-bundle/Resources/views to templates/sonata/page/.

4. Routing:

   • Pages are auto-routed via sonata.page.canonical route. Override with:

     # config/routes.yaml
     sonata_page_homepage:
         path: /
         defaults: { _controller: 'SonataPageBundle:Page:homepage' }
     

Integration Tips

• Symfony Flex: Use config/packages/sonata_page.yaml for minimal config.
• CMS Workflow: Combine with SonataAdminBundle for a full CMS.
• Dynamic Content: Use sonata.page.block.service to fetch blocks dynamically:

  $blockService = $this->get('sonata.page.block.service');
  $blocks = $blockService->getBlocks($page);
  

• Event Listeners: Extend functionality via events (e.g., sonata.page.pre_persist):

  use Sonata\PageBundle\Event\PageEvent;
  
  public function onPrePersist(PageEvent $event) {
      $page = $event->getPage();
      $page->setMetaDescription('Default meta');
  }
  

Gotchas and Tips

Common Pitfalls

1. Cache Issues:

   • Clear cache after changes:

     php bin/console cache:clear
     

   • Ensure sonata.page.cache is configured in framework.yaml:

     framework:
         cache:
             app: cache.adapter.redis
     

2. Block Ordering:

   • Blocks are ordered by position field. Update via:

     $block->setPosition(10); // Higher = lower in UI
     

3. Slug Conflicts:

   • Slugs must be unique. Handle duplicates in PageAdmin:

     $page->setSlug(uniqid('page_', true));
     

4. Twig Debugging:

   • Use {% debug page %} to inspect page/block data.
   • Override templates before clearing cache to avoid issues.

Debugging Tips

• Log Blocks:

  $this->get('logger')->debug('Blocks:', $blocks->toArray());
  

• Check Events: Enable event dispatching logs in config/packages/dev/monolog.yaml:

  handlers:
      sonata_events:
          type: stream
          path: "%kernel.logs_dir%/sonata_events.log"
          level: debug
  

Extension Points

1. Custom Block Types:

   • Extend Sonata\PageBundle\Block\BaseBlockService for custom logic.
   • Example:

     class CustomBlockService extends BaseBlockService {
         public function getType() { return 'custom'; }
         public function execute($block, $page) { /* ... */ }
     }
     

2. Page Metadata:

   • Add custom fields to Page entity:

     // src/Entity/Page.php
     use Doctrine\ORM\Mapping as ORM;
     
     #[ORM\Entity]
     class Page extends BasePage {
         #[ORM\Column(type: 'string', nullable: true)]
         private $customField;
     }
     

3. Routing Overrides:

   • Disable auto-routing by setting sonata.page.canonical to false in config:

     sonata_page:
         canonical: false
     

4. Security:

   • Restrict page access via sonata.page.security.handler:

     sonata_page:
         security_handler: app.page_security_handler
     

     Implement Sonata\PageBundle\Security\PageSecurityHandlerInterface.