My First Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require common-gateway/pet-store-plugin:dev-main in your Laravel project root. Note: Since this is a Symfony Flex bundle, ensure your Laravel project uses Symfony components (e.g., symfony/console, symfony/dependency-injection).

2. First Use Case

   • Check for Bundle Activation: Verify the bundle is registered in config/bundles.php (Symfony) or config/app.php (Laravel) if manually added.
   • Test a Basic Feature: If the bundle includes a command, run:

     php artisan <bundle:command>  # Replace with the actual command name
     

   • Inspect Dependencies: Check composer.json for required Symfony/Laravel packages (e.g., symfony/http-kernel).

3. Where to Look First

   • src/MyFirstBundle.php: Entry point for bundle configuration (services, routes, etc.).
   • src/Service/: Example service classes (extend or override these).
   • config/: Bundle-specific configurations (if any).
   • Resources/config/services.yaml: Symfony service definitions (map to Laravel’s config/services.php if needed).

Implementation Patterns

Core Workflows

1. Service Integration

   • Register Services: Extend MyFirstBundle.php to add services:

     public function loadExtension(array $containerConfig, ContainerBuilder $container, ExtensionInterface $extension) {
         $container->register('my_first_service', MyFirstService::class);
         $container->setAlias('my_first_service', MyFirstServiceInterface::class);
     }
     

   • Laravel Binding: In AppServiceProvider@boot(), bind Symfony services to Laravel’s container:

     $this->app->singleton(MyFirstServiceInterface::class, function ($app) {
         return $app->make('my_first_service'); // Symfony service ID
     });
     

2. Command Line Tools

   • Create Commands: Extend src/Command/ (if provided) or add your own:

     namespace MyFirstBundle\Command;
     use Symfony\Component\Console\Command\Command;
     class MyCommand extends Command {
         protected function execute(InputInterface $input, OutputInterface $output) {
             $output->writeln('Hello from MyFirstBundle!');
         }
     }
     

   • Register Commands: In MyFirstBundle.php, override getCommands():

     public function getCommands() {
         return [new MyCommand()];
     }
     

3. Routing

   • Symfony Routes: Define routes in Resources/config/routes.yaml:

     my_first_route:
         path: /my-first
         controller: MyFirstBundle\Controller\MyController::index
     

   • Laravel Integration: Use Route::prefix('my-first')->group() in routes/web.php and proxy requests to Symfony’s router if needed.

4. Event Listeners

   • Hook into Symfony Events: Register listeners in services.yaml:

     services:
         my_first.listener:
             class: MyFirstBundle\EventListener\MyListener
             tags:
                 - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
     

   • Laravel Events: Convert Symfony events to Laravel events in a service provider:

     Event::listen('kernel.request', function ($request) {
         // Call Symfony listener logic here
     });
     

Integration Tips

• Dependency Injection: Prefer constructor injection for services. Example:

  public function __construct(private MyFirstService $service) {}
  

• Configuration: Use Symfony’s ExtensionInterface to load config from config/packages/my_first.yaml:

  # config/packages/my_first.yaml
  my_first:
      enabled: true
      timeout: 30
  

  Access in PHP:

  $this->container->getParameter('my_first.timeout');
  

• Asset Management: If the bundle includes assets (JS/CSS), publish them:

  php artisan vendor:publish --tag=my-first-assets
  

  Then link in resources/views/layouts/app.blade.php.

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Issue: Symfony bundles use Bundle suffix (e.g., MyFirstBundle), while Laravel uses ServiceProvider. Avoid naming conflicts.
   • Fix: Use unique namespaces (e.g., Vendor\BundleName\MyFirstBundle).

2. Composer Autoloading

   • Issue: Forgetting to update autoload in composer.json after renaming classes.
   • Fix: Run composer dump-autoload after changes.

3. Symfony vs. Laravel Container

   • Issue: Mixing Symfony’s ContainerBuilder with Laravel’s Container. Symfony’s container is stricter about service IDs.
   • Fix: Use Laravel’s container for most cases; bridge only when necessary:

     $symfonyService = $this->app->make('service_id')->getWrappedObject();
     

4. Flex Recipe Conflicts

   • Issue: Symfony Flex recipes may override Laravel’s configurations (e.g., config/bundles.php).
   • Fix: Manually merge configurations or disable the recipe:

     composer remove symfony/flex
     

5. Command Registration

   • Issue: Commands not appearing in php artisan list.
   • Fix: Ensure the bundle is loaded in config/bundles.php (Symfony) or AppServiceProvider (Laravel):

     $this->app->register(MyFirstBundle::class);
     

Debugging

1. Service Not Found

   • Debug: Check if the service is registered in services.yaml and the bundle is loaded.
   • Command: List all services:

     php bin/console debug:container
     

2. Route Not Found

   • Debug: Verify the route is in routes.yaml and the bundle is enabled.
   • Command: Dump routes:

     php bin/console debug:router
     

3. Event Not Triggered

   • Debug: Ensure the listener is tagged correctly in services.yaml and the event name matches (e.g., kernel.request).

Extension Points

1. Customize Bundle Behavior

   • Override bundle classes by extending them (e.g., MyFirstBundle → MyCustomFirstBundle).
   • Example:

     namespace Vendor\BundleName\MyCustomFirstBundle;
     use MyFirstBundle\MyFirstBundle as BaseBundle;
     class MyCustomFirstBundle extends BaseBundle {
         public function getPath() {
             return \dirname(__DIR__);
         }
     }
     

2. Add New Features

   • Extend the Service/ directory with your own classes and register them in services.yaml.

3. Publish Assets/Config

   • Add publish tags to composer.json:

     "extra": {
         "publish": {
             "config": "Resources/config/my_first.yaml",
             "assets": "Resources/public/"
         }
     }
     

   • Then publish:

     php artisan vendor:publish --tag=config --tag=assets
     

4. Laravel-Specific Extensions

   • Create a Laravel facade for Symfony services:

     namespace Vendor\BundleName\Facades;
     use Illuminate\Support\Facades\Facade;
     class MyFirstFacade extends Facade {
         protected static function getFacadeAccessor() {
             return 'my_first_service'; // Symfony service ID
         }
     }
     

   • Register the facade in config/app.php:

     'aliases' => [
         'MyFirst' => Vendor\BundleName\Facades\MyFirstFacade::class,
     ],