First Test Bundle Laravel Package

Getting Started

Minimal Steps to Install and Test

1. Install the Bundle Run in your Laravel project root:

   composer require common-gateway/first-test-bundle:dev-main
   

   (Note: Replace dev-main with a stable version if available.)

2. Enable the Bundle Add to config/app.php under providers:

   CommonGateway\FirstTestBundle\FirstTestBundle::class,
   

   (If using Symfony Flex, this may auto-register.)

3. First Use Case: Verify Installation Create a test route in routes/web.php:

   use CommonGateway\FirstTestBundle\Service\ExampleService;
   Route::get('/test-bundle', function (ExampleService $service) {
       return $service->getExampleMessage(); // Hypothetical method
   });
   

   Visit /test-bundle to confirm the bundle’s core functionality works.

Implementation Patterns

Core Workflows

1. Service Integration

   • Inject the bundle’s services (e.g., ExampleService) into Laravel controllers/services.
   • Example:

     public function __construct(private ExampleService $exampleService) {}
     

   • Tip: Use dependency injection for loose coupling.

2. Configuration Overrides

   • Publish the bundle’s config (if included) via:

     php artisan vendor:publish --provider="CommonGateway\FirstTestBundle\FirstTestBundle" --tag="config"
     

   • Override defaults in config/first-test-bundle.php.

3. Event Listeners

   • Subscribe to bundle events (if documented) in EventServiceProvider:

     protected $listen = [
         'common-gateway.event.example' => [
             'App\Listeners\HandleExampleEvent',
         ],
     ];
     

4. Asset Integration

   • If the bundle includes assets (JS/CSS), register them in app.blade.php:

     @vite(['resources/js/first-test-bundle.js'])
     

Laravel-Specific Tips

• Service Providers: Extend the bundle’s provider by binding additional services:

  $this->app->bind('custom.service', function ($app) {
      return new CustomService($app->make(ExampleService::class));
  });
  

• Migrations/Seeders: If the bundle includes database logic, run:

  php artisan migrate --path=/vendor/common-gateway/first-test-bundle/src/Database/Migrations
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • The bundle’s default namespace (CommonGateway\FirstTestBundle) may conflict with your app’s namespace.
   • Fix: Alias classes in composer.json:

     "autoload": {
         "psr-4": {
             "App\\": "app/",
             "CommonGateway\\FirstTestBundle\\": "vendor/common-gateway/first-test-bundle/src/"
         }
     }
     

     Then run composer dump-autoload.

2. Missing Documentation

   • The bundle lacks detailed usage docs. Workaround:
     • Inspect src/Service/ for available classes/methods.
     • Check tests/ for usage examples (if present).

3. Dev Dependency Lock

   • Installed via :dev-main, which may break across updates.
   • Fix: Pin to a specific commit hash or use a stable release when available.

4. Symfony vs. Laravel Quirks

   • The bundle is Symfony Flex-based. Laravel-specific issues:
     • Service Container: Laravel’s container may not auto-resolve Symfony’s ArgumentResolver or EventDispatcher. Fix: Manually bind Symfony services in AppServiceProvider:

       $this->app->singleton(Symfony\Component\EventDispatcher\EventDispatcher::class, function () {
           return new EventDispatcher();
       });
       

Debugging Tips

1. Check for Errors

   • Run composer dump-autoload after installation.
   • Clear Laravel’s cache:

     php artisan cache:clear && php artisan config:clear
     

2. Log Bundle Activity

   • Add a debug listener to the bundle’s events (if any):

     $dispatcher->addListener('common-gateway.event.example', function ($event) {
         \Log::debug('Bundle event triggered', $event->toArray());
     });
     

3. Verify Autoloading

   • If classes aren’t found, check:

     composer show common-gateway/first-test-bundle
     

     Ensure the autoload section in composer.json is correct.

Extension Points

1. Customizing Services

   • Override bundle services by binding them in AppServiceProvider:

     $this->app->bind(
         CommonGateway\FirstTestBundle\Service\ExampleService::class,
         CustomExampleService::class
     );
     

2. Adding Commands

   • Extend the bundle’s commands (if included) by creating a new command that calls the original:

     use CommonGateway\FirstTestBundle\Command\ExampleCommand;
     class CustomExampleCommand extends ExampleCommand {
         protected function execute(InputInterface $input, OutputInterface $output) {
             // Extend logic here
             parent::execute($input, $output);
         }
     }
     

3. Database Schema

   • If the bundle includes migrations, extend them in app/Database/Migrations/:

     use CommonGateway\FirstTestBundle\Database\Migrations\CreateExampleTable;
     class ExtendExampleTable extends CreateExampleTable {
         public function up() {
             parent::up();
             Schema::table('example_table', function ($table) {
                 $table->string('custom_column')->nullable();
             });
         }
     }