Bag Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run in your Symfony project root:

   composer require common-gateway/bag-bundle:dev-main
   

   For Dockerized environments:

   docker-compose exec php composer require common-gateway/bag-bundle:dev-main
   

2. Enable the Bundle Add to config/bundles.php:

   CommonGateway\BagBundle\CommonGatewayBagBundle::class => ['all' => true],
   

3. Install Entities (if applicable) Execute the installation command:

   php bin/console commongateway:install common-gateway/bag-bundle
   

   Or in Docker:

   docker-compose exec php bin/console commongateway:install common-gateway/bag-bundle
   

4. Verify Installation Check the config/packages/common_gateway_bag.yaml for generated configuration or inspect the src/Entity directory for new models.

First Use Case: Creating a Plugin Bundle

Use this package as a template to scaffold a new Symfony Flex bundle. Follow these steps:

1. Generate a New Bundle Use the GitHub template to create a new repository.
2. Customize the Bundle Replace CommonGateway\BagBundle namespace with your own (e.g., YourVendor\YourBundle). Update composer.json metadata (name, description, etc.).
3. Extend Functionality Modify src/Resources/config/services.yaml to register your services. Add custom entities in src/Entity/ and update src/DependencyInjection/Configuration.php for bundle configuration.

Implementation Patterns

Workflow: Developing a Plugin Bundle

1. Scaffold the Bundle Clone the generated template repo and replace placeholders with your logic. Example structure:

   src/
   ├── Controller/       # Custom controllers (e.g., ApiController.php)
   ├── Entity/           # Doctrine entities (e.g., YourEntity.php)
   ├── Repository/       # Custom repositories
   ├── Resources/
   │   ├── config/      # Services, routes, doctrine
   │   ├── public/       # Static assets
   │   └── views/        # Twig templates (if applicable)
   └── DependencyInjection/
       ├── Configuration.php  # Bundle config schema
       └── YourBundleExtension.php  # Config loader
   

2. Integrate with Symfony

   • Services: Define services in src/Resources/config/services.yaml and tag them for autowiring.

     services:
         YourVendor\YourBundle\Service\YourService:
             arguments:
                 - '@doctrine.orm.entity_manager'
     

   • Routes: Load routes via YAML (config/routes/your_bundle.yaml) or annotations.

     your_bundle_homepage:
         path: /your-bundle
         controller: YourVendor\YourBundle\Controller\YourController::index
     

   • Entities: Extend src/Entity/BaseEntity.php (if provided) or create standalone entities with lifecycle callbacks.

     namespace YourVendor\YourBundle\Entity;
     use Doctrine\ORM\Mapping as ORM;
     
     #[ORM\Entity]
     class YourEntity extends BaseEntity {
         #[ORM\Column]
         private string $name;
     }
     

3. Configuration Extend src/DependencyInjection/Configuration.php to add custom parameters:

   $rootNode
       ->children()
           ->scalarNode('default_setting')
               ->defaultValue('default')
           ->end()
       ->end();
   

   Access in controllers/services via:

   $this->container->getParameter('your_bundle.default_setting');
   

4. Commands Add custom console commands in src/Command/ and register them in services.yaml:

   services:
       YourVendor\YourBundle\Command\YourCommand:
           tags: ['console.command']
   

5. Testing Use Symfony’s TestCase and KernelTestCase to test controllers, services, and commands. Example:

   use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
   
   class YourControllerTest extends WebTestCase {
       public function testIndex() {
           $client = static::createClient();
           $client->request('GET', '/your-bundle');
           $this->assertEquals(200, $client->getResponse()->getStatusCode());
       }
   }
   

Integration Tips

• Doctrine Migrations: Generate migrations for new entities:

  php bin/console make:migration
  php bin/console doctrine:migrations:migrate
  

• Flex Recipes: If your bundle includes assets (JS/CSS), use Symfony Flex recipes to automate installation:

  # config/bundles.php
  YourVendor\YourBundle\YourBundle::class => ['all' => true],
  

  Create a resources/stimulus or resources/webpack folder for frontend assets.
• Event Listeners: Subscribe to Symfony events (e.g., KernelEvents::REQUEST) in services.yaml:

  services:
      YourVendor\YourBundle\EventListener\YourListener:
          tags:
              - { name: 'kernel.event_listener', event: 'kernel.request', method: 'onKernelRequest' }
  

• API Platform: If using API Platform, extend src/Entity/YourEntity.php with API resources:

  use ApiPlatform\Metadata\ApiResource;
  
  #[ApiResource]
  class YourEntity extends BaseEntity { ... }
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • Ensure your bundle’s namespace (e.g., YourVendor\YourBundle) is unique to avoid conflicts with other bundles.
   • Check for collisions in composer.json under autoload.psr-4.

2. Missing Configuration

   • If commongateway:install fails, verify:
     • The bundle is listed in config/bundles.php.
     • The CommonGateway\BagBundle namespace is replaced with your bundle’s namespace in all files.
   • Debug with:

     php bin/console debug:container | grep your_bundle
     

3. Doctrine Entity Issues

   • If entities aren’t recognized, clear the cache:

     php bin/console cache:clear
     

   • Ensure src/Entity/ is in your autoload-dev.psr-4 in composer.json:

     "autoload-dev": {
         "psr-4": {
             "YourVendor\\YourBundle\\": "src/"
         }
     }
     

4. Command Not Found

   • If commongateway:install is missing, ensure the bundle’s Command/ directory is properly registered in services.yaml:

     services:
         YourVendor\YourBundle\Command\InstallCommand:
             tags: ['console.command']
     

5. Flex Recipe Conflicts

   • If using Symfony Flex, ensure your bundle’s composer.json includes a replace or conflict section to avoid version clashes:

     "replace": {
         "symfony/framework-bundle": "^5.4"
     }
     

Debugging Tips

1. Log Bundle Activation Add a debug listener to verify bundle loading:

   // src/DependencyInjection/YourBundleExtension.php
   public function load(array $configs, ContainerConfigurator $container) {
       $container->parameters()->set('your_bundle.debug', true);
   }
   

   Check logs:

   php bin/console debug:config your_bundle
   

2. Dump Services Inspect registered services:

   php bin/console debug:container YourVendor\YourBundle
   

3. Doctrine Debugging Enable SQL logging in .env:

   DOCTRINE_DDL_AUTO_CREATE_SCHEMA=true
   DOCTRINE_DDL_AUTO_CREATE_SCHEMA_SAFE_CHARSET=true
   DOCTRINE_DDL_AUTO_CREATE_SCHEMA_SAFE_COLLATE=true
   

   View queries:

   php bin/console debug:query
   

Extension Points

1. Custom Console Commands Extend the commongateway:install command by creating a new command that calls the original:

   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class CustomInstallCommand extends Command {
       protected function execute(InputInterface $input, OutputInterface $output) {
           $installer = new \CommonGateway\BagBundle\Command\InstallCommand();
           $installer->run($input, $output);
           // Add post-install logic here
       }
   }
   

2. Dynamic Configuration Use Symfony’s ParameterBag to load configuration dynamically:

   $this->container->getParameterBag()->add([
       'your_bundle.dynamic_setting'