Portal Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require boson/portal-bundle
   

   Enable the bundle in config/bundles.php:

   Boson\PortalBundle\BosonPortalBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php bin/console boson:portal:install
   

   Review config/packages/boson_portal.yaml for portal settings (e.g., title, logo, routes).

3. First Use Case Access the portal at /portal (or your configured route). The bundle provides:

   • A basic dashboard layout.
   • Predefined routes for common portal pages (e.g., /portal/dashboard, /portal/profile).

Implementation Patterns

Core Workflows

1. Extending the Dashboard Override the default dashboard template by creating a custom controller and template:

   // src/Controller/Portal/DashboardController.php
   namespace App\Controller\Portal;
   
   use Boson\PortalBundle\Controller\AbstractPortalController;
   
   class DashboardController extends AbstractPortalController
   {
       public function index(): Response
       {
           return $this->render('portal/dashboard_custom.html.twig');
       }
   }
   

   Update routes in config/routes/portal.yaml:

   portal_dashboard:
       path: /portal/dashboard
       controller: App\Controller\Portal\DashboardController::index
   

2. Adding Portal Pages Use the bundle’s PortalPage trait to create reusable page components:

   use Boson\PortalBundle\Traits\PortalPage;
   
   class MyPageController extends AbstractController
   {
       use PortalPage;
   
       public function show(): Response
       {
           return $this->renderPortalPage('my_page', [
               'data' => $this->getData(),
           ]);
       }
   }
   

3. Authentication & Authorization Integrate with Symfony’s security system:

   # config/packages/security.yaml
   access_control:
       - { path: ^/portal, roles: ROLE_PORTAL_USER }
   

   Use the bundle’s PortalAuthenticator for custom login/logout flows.

4. Theming Override Twig templates in templates/boson_portal/ to customize:

   • Layouts (base.html.twig).
   • Components (navbar.html.twig, footer.html.twig).

Integration Tips

• API Integration: Use the bundle’s PortalApiClient to fetch data for the portal:

  $client = $this->container->get('boson_portal.api_client');
  $data = $client->get('/api/resource');
  

• Event Listeners: Extend portal behavior via events (e.g., PortalInitializeEvent):

  // src/EventListener/PortalListener.php
  public function onPortalInitialize(PortalInitializeEvent $event)
  {
      $event->addAsset(new Asset('css/custom-portal.css'));
  }
  

  Register in services.yaml:

  services:
      App\EventListener\PortalListener:
          tags:
              - { name: kernel.event_listener, event: portal.initialize }
  

Gotchas and Tips

Pitfalls

1. Route Conflicts Ensure your custom portal routes don’t clash with the bundle’s defaults. Use _prefix in portal.yaml:

   portal:
       prefix: /custom-portal
   

2. Caching Issues Clear the cache after extending templates or routes:

   php bin/console cache:clear
   

3. Dependency Injection The bundle relies on Symfony’s DI container. Avoid hardcoding services in controllers; use dependency injection:

   public function __construct(private PortalService $portalService) {}
   

4. Translation Keys The bundle uses boson_portal translation domain. Add translations to translations/messages.en.yaml:

   boson_portal:
       dashboard: "Custom Dashboard"
   

Debugging Tips

• Check Events: Enable debug mode to see fired events:

  php bin/console debug:event-dispatcher
  

• Log Portal Initialization: Add a listener to log portal startup:

  public function onPortalInitialize(PortalInitializeEvent $event)
  {
      $this->logger->info('Portal initialized with assets:', $event->getAssets());
  }
  

Extension Points

1. Custom Assets Add CSS/JS assets dynamically:

   $event->addAsset(new Asset('js/analytics.js', 'head'));
   

2. Dynamic Menus Override the menu builder by extending PortalMenuBuilder:

   class CustomMenuBuilder extends PortalMenuBuilder
   {
       public function buildMenu(): array
       {
           $menu = parent::buildMenu();
           $menu[] = ['route' => 'portal_custom_route', 'label' => 'Custom Link'];
           return $menu;
       }
   }
   

   Register in services.yaml:

   services:
       Boson\PortalBundle\Menu\PortalMenuBuilder:
           class: App\Menu\CustomMenuBuilder
   

3. Database Integration Use the bundle’s PortalRepository to interact with portal-specific data (if extended):

   $repository = $this->container->get('boson_portal.repository');
   $pages = $repository->findAll();