Page Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require stiwl/page-bundle
   

   Ensure all 13 dependencies (SonataAdmin, IvoryGoogleMap, CKEditor, etc.) are installed via Composer.

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

   return [
       // ...
       Stiwl\PageBundle\StiwlPageBundle::class => ['all' => true],
   ];
   

3. Database & Fixtures Run migrations:

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

   Load demo data (if needed):

   php bin/console doctrine:fixtures:load --append
   

4. First Use Case Access the Sonata Admin dashboard at /admin to manage Pages, Menus, or News via the UI. Example:

   • Create a new Page entity with multilingual support.
   • Assign it to a Menu via the Sonata Admin interface.

Implementation Patterns

Core Workflows

1. Page Management

   • Frontend Rendering: Use the stiwl_page Twig extension to fetch pages by slug/ID:

     {{ render(stiwl_page.getPage('about-us')) }}
     

   • Dynamic Content: Extend Stiwl\PageBundle\Entity\Page to add custom fields (e.g., metaTitle, customCta).

2. Menu Integration

   • KnpMenu + Paginator: Build menus with paginated items:

     // src/Controller/DefaultController.php
     use Knp\Menu\MenuItemInterface;
     use Stiwl\PageBundle\Menu\PageMenuBuilder;
     
     public function menuAction(MenuBuilder $menuBuilder)
     {
         $menu = $menuBuilder->createMenu();
         $menu->addChild('Home', ['route' => 'homepage']);
         $menu->addChild('Pages', ['route' => 'stiwl_page_list']);
     }
     

   • Sonata Admin: Configure menu items in config/sonata_admin.yml:

     sonata_admin:
         options:
             menu:
                 - label: 'Pages'
                   uri: '~/admin/page/'
     

3. Multilingual Content

   • Use SonataIntlBundle for translations. Example in a Page entity:

     // src/Entity/Page.php
     use Gedmo\Mapping\Annotation as Gedmo;
     
     /**
      * @Gedmo\Translatable
      */
     private $title;
     

4. Contact Form + Google Maps

   • Extend the default contact form:

     {{ form_start(form) }}
         {{ form_widget(form.name) }}
         {{ form_widget(form.email) }}
         {{ render(ivory_google_map({
             'address': '123 Main St',
             'zoom': 12,
             'width': '100%',
             'height': '400px'
         })) }}
     {{ form_end(form) }}
     

   • Handle submissions in a controller:

     public function contactAction(Request $request)
     {
         $form = $this->createForm(ContactType::class);
         if ($request->isMethod('POST') && $form->handleRequest($request)) {
             $this->mailer->send($form->getData());
             return $this->redirectToRoute('homepage');
         }
         return $this->render('contact.html.twig', ['form' => $form->createView()]);
     }
     

5. CKEditor Integration

   • Configure in config/packages/ckeditor.yaml:

     ckeditor:
         editor_configs:
             default:
                 toolbar: [['bold', 'italic'], ['numberedList']]
     

   • Use in Twig:

     {{ form_row(form.content, {'attr': {'class': 'ckeditor'}}) }}
     

Gotchas and Tips

Pitfalls

1. Dependency Hell

   • The bundle requires 13+ packages (SonataAdmin, IvoryGoogleMap, etc.). Ensure compatibility:

     composer why-not stiwl/page-bundle
     

   • Fix: Use composer.lock from a working project or pin versions in composer.json.

2. Sonata Admin Overrides

   • Customizing Sonata Admin templates (e.g., base.html.twig) may break updates. Use:

     # config/packages/sonata_admin.yaml
     sonata_admin:
         templates:
             layout: 'StiwlPageBundle:layout.html.twig'
     

3. Multilingual Quirks

   • Translations may not sync automatically. Run:

     php bin/console doctrine:query:sql "UPDATE page_translations SET title = ? WHERE locale = ? AND page_id = ?"
     

   • Tip: Use SonataIntlBundle's sonata_intl_update command:

     php bin/console sonata_intl_update
     

4. Google Maps API Key

   • The bundle uses IvoryGoogleMapBundle, which requires a Google Maps API key. Configure in .env:

     IVORY_GOOGLE_MAP_KEY=your_api_key_here
     

   • Gotcha: Free tier has usage limits. Monitor with:

     php bin/console debug:config ivory_google_map
     

5. CKEditor Asset Conflicts

   • If CKEditor assets fail to load, clear cache and rebuild:

     php bin/console assets:install
     php bin/console cache:clear
     

Debugging Tips

1. Sonata Admin Debugging

   • Enable debug toolbar and check:
     • sonata_admin events in dev.log.
     • Database queries with doctrine:query:

       php bin/console doctrine:query:sql "SELECT * FROM page WHERE slug = ?" "about-us"
       

2. Menu Builder Issues

   • Verify PageMenuBuilder is tagged as a service:

     # config/services.yaml
     Stiwl\PageBundle\Menu\PageMenuBuilder:
         tags: ['knp_menu.menu_builder']
     

3. Translation Sync

   • Manually trigger translation updates:

     // src/EventListener/TranslationListener.php
     use Gedmo\Translatable\TranslatableListener;
     
     public function __construct()
     {
         $this->translatableListener = new TranslatableListener();
     }
     
     public function onKernelRequest(GetResponseEvent $event)
     {
         $this->translatableListener->preFlush();
     }
     

Extension Points

1. Custom Page Types

   • Extend the Page entity:

     // src/Entity/CustomPage.php
     use Stiwl\PageBundle\Entity\Page;
     
     class CustomPage extends Page
     {
         /**
          * @ORM\Column(type="string", nullable=true)
          */
         private $customField;
     }
     

   • Register in StiwlPageBundle config:

     stiwl_page:
         page_classes:
             - App\Entity\CustomPage
     

2. Override Sonata Admin Templates

   • Copy templates from vendor/sonata-project/admin-bundle/Resources/views/ to templates/sonata/admin/ and modify.

3. Add Custom Blocks

   • Create a block service:

     # config/services.yaml
     app.block.custom:
         class: App\Block\CustomBlock
         tags:
             - { name: sonata.block }
     

   • Implement Sonata\BlockBundle\Block\BlockInterface.

4. Extend Contact Form

   • Override the default ContactType:

     // src/Form/Type/CustomContactType.php
     use Stiwl\PageBundle\Form\Type\ContactType as BaseContactType;
     
     class CustomContactType extends BaseContactType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             parent::buildForm($builder, $options);
             $builder->add('customField', TextType::class);
         }
     }
     

   • Update the route in routing.yml:

     stiwl_page_contact:
         path: /contact
         defaults: { _controller: 'App\Controller\DefaultController::contact' }