Platform Portal Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require digitalstate/platform-portal-bundle
   

   Register the bundle in config/app.php under ExtraBundles:

   DigitalState\PlatformPortalBundle\DigitalStatePlatformPortalBundle::class,
   

2. Publish Configuration Run:

   php artisan vendor:publish --provider="DigitalState\PlatformPortalBundle\DigitalStatePlatformPortalBundle" --tag="config"
   

   This generates config/platform_portal.php. Review and customize:

   • Portal routes (routes array)
   • Default controller mappings (controllers array)
   • Frontend assets (assets array)

3. First Use Case: Basic Portal Page Define a route in routes/web.php:

   use DigitalState\PlatformPortalBundle\Controller\PortalController;
   
   Route::get('/portal', [PortalController::class, 'index'])->name('portal.index');
   

   Override the default template by publishing assets:

   php artisan vendor:publish --provider="DigitalState\PlatformPortalBundle\DigitalStatePlatformPortalBundle" --tag="views"
   

   Customize resources/views/portal/index.html.twig.

Implementation Patterns

1. Controller Integration

• Extend PortalController for custom logic:

  namespace App\Http\Controllers;
  
  use DigitalState\PlatformPortalBundle\Controller\PortalController as BasePortalController;
  
  class PortalController extends BasePortalController
  {
      public function customAction()
      {
          return $this->render('portal/custom', [
              'data' => $this->getCustomData(),
          ]);
      }
  }
  

• Dependency Injection: Use the bundle’s services (e.g., PortalService) via constructor:

  public function __construct(private PortalService $portalService) {}
  

2. Twig Templating

• Layout Overrides: Extend base.html.twig (published to resources/views/portal/layouts/).
• Dynamic Content: Pass data via controller:

  {% block content %}
      {{ dump(data) }} {# Debug passed variables #}
  {% endblock %}
  

• Partial Templates: Reuse components (e.g., portal/_header.html.twig).

3. Routing

• Custom Routes: Define in config/platform_portal.php:

  'routes' => [
      'home' => [
          'path' => '/home',
          'controller' => 'App\Http\Controllers\PortalController@home',
      ],
  ],
  

• Route Model Binding: Use Laravel’s built-in binding for portal-specific models:

  Route::get('/portal/{portal}', [PortalController::class, 'show']);
  

4. Asset Management

• Publish Assets:

  php artisan vendor:publish --tag="public"
  

  Customize CSS/JS in public/vendor/platform-portal/.
• Versioning: Append ?v={{ config('app.version') }} to static assets for cache busting.

5. Service Integration

• Extend PortalService:

  namespace App\Services;
  
  use DigitalState\PlatformPortalBundle\Services\PortalService as BasePortalService;
  
  class PortalService extends BasePortalService
  {
      public function getExtendedData()
      {
          return $this->client->get('/api/extended');
      }
  }
  

• Bind Service in AppServiceProvider:

  $this->app->bind(
      \DigitalState\PlatformPortalBundle\Services\PortalService::class,
      \App\Services\PortalService::class
  );
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Issue: Forgetting to publish config after updates.
   • Fix: Always run php artisan config:clear after modifying config/platform_portal.php.

2. Twig Autoloading

   • Issue: Twig templates not found if published views are not in resources/views/portal/.
   • Fix: Verify the views_path in config/platform_portal.php matches your structure.

3. Route Conflicts

   • Issue: Bundle routes clashing with existing routes.
   • Fix: Explicitly prefix bundle routes in config/platform_portal.php:

     'prefix' => 'portal',
     

4. Asset Paths

   • Issue: Hardcoded asset paths breaking in production.
   • Fix: Use Laravel Mix or Vite to compile assets and reference them via mix() helper.

5. Service Binding

   • Issue: PortalService not injected due to incorrect binding.
   • Fix: Ensure the service is bound in AppServiceProvider (see Implementation Patterns).

Debugging Tips

• Enable Debug Mode: Set 'debug' => true in config/platform_portal.php to log service calls.
• Twig Debug: Add {% debug %} to Twig templates for variable inspection.
• Route Listing: Use php artisan route:list to verify bundle routes are registered.

Extension Points

1. Custom Controllers

   • Override any method in PortalController (e.g., index(), show()).

2. Event Listeners

   • Listen for PortalEvent (if the bundle emits them):

     public function handle(PortalEvent $event)
     {
         // Custom logic
     }
     

3. Middleware

   • Apply middleware to portal routes:

     Route::middleware(['portal.middleware'])->group(function () {
         // Portal routes
     });
     

4. Database Integration

   • Extend the bundle’s Portal model (if it uses Eloquent):

     namespace App\Models;
     
     use DigitalState\PlatformPortalBundle\Models\Portal as BasePortal;
     
     class Portal extends BasePortal
     {
         protected $customAttribute = 'value';
     }
     

Performance Tips

• Caching: Cache portal data in PortalService:

  $data = Cache::remember('portal_data', now()->addHours(1), function () {
      return $this->client->get('/api/data');
  });
  

• Lazy Loading: Load assets dynamically with defer in Twig:

  <script src="{{ asset('js/portal.js') }}" defer></script>