Simple Page Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beelab/simple-page-bundle
   

   Add to config/bundles.php:

   BeeLab\SimplePageBundle\BeeLabSimplePageBundle::class => ['all' => true],
   

2. Database Migration Run migrations to create the page table:

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

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

   php bin/console bee:page:create --slug="about" --title="About Us" --content="Welcome to our site!"
   

   Access it at /page/about.

Where to Look First

• Documentation: Resources/doc/index.md (in the bundle directory).
• Controller: Controller/PageController.php (handles routing).
• Entity: Entity/Page.php (core model).
• Twig Extension: Twig/PageExtension.php (for template integration).

Implementation Patterns

Core Workflows

1. Page Creation

   • Manual: Use CLI (bee:page:create).
   • Programmatic:

     $page = new \BeeLab\SimplePageBundle\Entity\Page();
     $page->setSlug('contact');
     $page->setTitle('Contact Us');
     $page->setContent('<h1>Reach Out</h1>');
     $em->persist($page);
     $em->flush();
     

2. Routing

   • Pages are auto-routed via page/{slug}.
   • Override routes in config/routes.yaml:

     bee_simple_page_page:
         path: /custom-path/{slug}
         controller: BeeLab\SimplePageBundle\Controller\PageController::showAction
     

3. Template Integration

   • Use Twig’s page extension:

     {% set currentPage = page('about') %}
     {{ currentPage.title }}
     {{ currentPage.content|raw }}
     

   • List all pages:

     {% for page in page.all() %}
         <a href="{{ path('bee_simple_page_page_show', {'slug': page.slug}) }}">{{ page.title }}</a>
     {% endfor %}
     

4. Admin Management

   • Use the built-in CRUD admin interface (if enabled in config):

     # config/packages/bee_simple_page.yaml
     bee_simple_page:
         admin:
             enabled: true
     

Integration Tips

• Custom Fields: Extend the Page entity:

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

  Update the bundle’s PageType (Symfony Form) to include the new field.

• Event Listeners: Hook into page events (e.g., PageEvents::PRE_SAVE):

  // src/EventListener/PageListener.php
  use BeeLab\SimplePageBundle\Event\PageEvents;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class PageListener implements EventSubscriberInterface
  {
      public static function getSubscribedEvents()
      {
          return [
              PageEvents::PRE_SAVE => 'onPreSave',
          ];
      }
  
      public function onPreSave(PageEvent $event)
      {
          $page = $event->getPage();
          $page->setSlug(strtolower($page->getSlug()));
      }
  }
  

• API Endpoints: Expose pages via API:

  // src/Controller/ApiPageController.php
  use BeeLab\SimplePageBundle\Entity\Page;
  use Symfony\Component\HttpFoundation\JsonResponse;
  
  class ApiPageController extends AbstractController
  {
      public function show(PageRepository $repo, string $slug): JsonResponse
      {
          $page = $repo->findOneBy(['slug' => $slug]);
          return new JsonResponse($page->toArray());
      }
  }
  

Gotchas and Tips

Pitfalls

1. Slug Conflicts

   • The bundle auto-generates slugs from titles but doesn’t handle duplicates.
   • Fix: Implement a unique constraint in the database or override setSlug() in your extended entity.

2. Caching Issues

   • Pages are cached by default. Clear cache after programmatic updates:

     php bin/console cache:clear
     

   • Disable caching in config/packages/bee_simple_page.yaml:

     bee_simple_page:
         cache:
             enabled: false
     

3. Route Overrides

   • If you override the route path, ensure the controller action signature matches:

     public function showAction(string $slug): Response
     

4. Doctrine Proxy Conflicts

   • If extending the Page entity, regenerate proxies:

     php bin/console doctrine:generate:entities BeeLab\SimplePageBundle\Entity
     

Debugging Tips

• Check Entity State:

  $em->getUnitOfWork()->getEntityState($page); // Returns 1 (managed) or 0 (detached)
  

• Enable SQL Logging:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
          profiling: true
  

• Validate Slugs: Use the PageSlugValidator service to check slug availability:

  $validator = $container->get('bee_simple_page.validator.slug');
  if (!$validator->isValid('my-slug')) {
      throw new \RuntimeException('Slug already exists!');
  }
  

Extension Points

1. Custom Repository Methods Add methods to PageRepository:

   // src/Repository/ExtendedPageRepository.php
   class ExtendedPageRepository extends \BeeLab\SimplePageBundle\Repository\PageRepository
   {
       public function findPublished(): array
       {
           return $this->createQueryBuilder('p')
               ->where('p.published = :published')
               ->setParameter('published', true)
               ->getQuery()
               ->getResult();
       }
   }
   

   Update services.yaml to replace the default repository.

2. Form Type Overrides Extend the PageType to add fields:

   // src/Form/ExtendedPageType.php
   use BeeLab\SimplePageBundle\Form\PageType as BasePageType;
   
   class ExtendedPageType extends BasePageType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           parent::buildForm($builder, $options);
           $builder->add('customField', TextType::class);
       }
   }
   

   Register the new type in services.yaml.

3. Twig Filters Add custom filters to the PageExtension:

   // src/Twig/ExtendedPageExtension.php
   class ExtendedPageExtension extends \BeeLab\SimplePageBundle\Twig\PageExtension
   {
       public function getFunctions()
       {
           return array_merge(parent::getFunctions(), [
               new \Twig\TwigFunction('page_excerpt', [$this, 'getExcerpt']),
           ]);
       }
   
       public function getExcerpt(string $content, int $length = 100): string
       {
           return substr($content, 0, $length) . '...';
       }
   }
   

   Override the service in services.yaml.