Template Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project (or Symfony if cross-framework):

   composer require common-gateway/template-bundle
   

   Publish the bundle's assets (if needed) via:

   php artisan vendor:publish --provider="CommonGateway\TemplateBundle\TemplateBundle"
   

2. First Use Case Use the bundle to scaffold a Symfony Flex-compatible plugin within Laravel. Example:

   php artisan make:template my-plugin-name
   

   This generates a skeleton bundle structure in src/Bundles/MyPluginBundle/.

3. Key Files to Review

   • config/template.php: Bundle configuration.
   • src/Bundles/MyPluginBundle/Resources/config/services.yaml: Dependency injection.
   • src/Bundles/MyPluginBundle/TemplateBundle.php: Bundle class (extends BaseBundle).

Implementation Patterns

Workflow Integration

1. Plugin Development

   • Extend BaseBundle to create reusable Laravel/Symfony plugins.
   • Override build() in TemplateBundle.php to define routes, services, or assets:

     protected function build(): void
     {
         $this->loadRoutesFrom(__DIR__.'/../Resources/config/routes.yaml');
         $this->loadTemplatesFrom(__DIR__.'/../Resources/views', 'my_plugin');
     }
     

2. Asset Management Use the bundle’s loadAssets() method to compile assets (e.g., CSS/JS):

   $this->loadAssets('public', 'bundles/my_plugin');
   

3. Service Registration Define services in Resources/config/services.yaml and autowire them:

   services:
       MyPlugin\Service\MyService:
           arguments:
               $someDependency: '@some.service'
   

4. Laravel-Specific Adaptations

   • Use Laravel’s ServiceProvider facade to register routes/services:

     use Illuminate\Support\Facades\Route;
     Route::prefix('my-plugin')->group(function () {
         Route::get('/dashboard', [MyController::class, 'dashboard']);
     });
     

   • Leverage Laravel’s View composer for dynamic template data:

     View::composer('my_plugin::dashboard', function ($view) {
         $view->with('data', MyService::fetchData());
     });
     

5. Flex Recipes Create a my-plugin.php recipe in vendor/common-gateway/template-bundle/src/Recipe/ to automate plugin installation:

   return [
       'name' => 'my-plugin',
       'description' => 'A reusable plugin template.',
       'target-dir' => 'src/Bundles/MyPluginBundle',
       'files' => [
           'src/Bundles/MyPluginBundle/TemplateBundle.php' => 'templates/TemplateBundle.php',
       ],
   ];
   

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • Ensure bundle namespaces (e.g., MyPlugin\Bundle) don’t clash with Laravel’s App\ namespace.
   • Use composer.json autoloading to resolve PSR-4 conflicts:

     "autoload": {
         "psr-4": {
             "MyPlugin\\": "src/Bundles/MyPluginBundle/"
         }
     }
     

2. Asset Pipeline Quirks

   • If using Laravel Mix/Vite, manually copy compiled assets to the bundle’s public directory in post-install-cmd:

     "scripts": {
         "post-install-cmd": "npm run prod && cp public/mix-manifest.json src/Bundles/MyPluginBundle/public/"
     }
     

3. Route Prefix Collisions

   • Avoid hardcoding route prefixes. Use Laravel’s Route::prefix() or Symfony’s prefix in YAML:

     # config/routes.yaml
     my_plugin:
         resource: '@MyPluginBundle/Resources/config/routes.yaml'
         prefix: '/my-plugin'
     

4. Debugging Bundle Loading

   • Check if the bundle is registered in config/bundles.php:

     return [
         CommonGateway\TemplateBundle\TemplateBundle::class => ['all' => true],
     ];
     

   • Use php artisan bundle:debug (if available) or php artisan config:clear to reset.

Tips

1. Leverage Laravel’s Facades Inject Laravel services (e.g., Auth, Cache) into Symfony services via services.yaml:

   services:
       MyPlugin\Service\AuthService:
           arguments:
               $auth: '@auth'
   

2. Dynamic Template Paths Use Laravel’s view() helper with bundle-aware paths:

   return view('my_plugin::dashboard', ['data' => $data]);
   

3. Testing Mock the bundle in PHPUnit by overriding its build() method:

   $bundle = new MyPluginBundle();
   $bundle->setTestMode(true); // Disable asset/route loading
   

4. Extending the Bundle

   • Override CommonGateway\TemplateBundle\BaseBundle to add custom logic (e.g., database migrations):

     protected function install(): void
     {
         $this->schema->create('my_plugin_data', function (Blueprint $table) {
             $table->id();
             $table->timestamps();
         });
     }
     

5. Performance

   • Cache bundle configurations in Laravel’s config/cache:

     $this->mergeConfigFrom(__DIR__.'/../config/template.php', 'template');