Construction Kit Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require c33s/construction-kit-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       C33s\ConstructionKitBundle\C33sConstructionKitBundle::class => ['all' => true],
   ];
   

2. Define a Building Block: Create a YAML file (e.g., config/construction_kit/blocks/my_block.yml):

   my_block:
       type: bundle
       bundle: Symfony\Bundle\FrameworkBundle\FrameworkBundle
       config:
           router:
               resource: "%kernel.project_dir%/config/routes.yml"
   

3. Apply the Block: Use the CLI command to apply blocks to a project:

   php bin/console construction-kit:apply my_block
   

4. First Use Case: Reuse a common configuration (e.g., security, routing) across multiple Symfony projects without manual setup.

Where to Look First

• Documentation: The README and Resources/doc/ directory (if available) for block types (bundle, asset, config).
• Example Configs: Check config/construction_kit/ for pre-defined blocks.
• CLI Commands:

  php bin/console list construction-kit
  

Implementation Patterns

Usage Patterns

1. Bundle Reusability:

   • Define a block for a bundle (e.g., FOSUserBundle) with its config in construction_kit/blocks/fos_user.yml:

     fos_user:
         type: bundle
         bundle: FOS\UserBundle\FOSUserBundle
         config:
             fos_user:
                 db_driver: orm
                 firewall_name: main
     

   • Apply it to any project with construction-kit:apply fos_user.

2. Asset Management:

   • Reuse static assets (e.g., CSS/JS) across projects:

     # config/construction_kit/blocks/assets.yml
     project_assets:
         type: asset
         source: "%kernel.project_dir%/src/Resources/public/assets"
         destination: "%kernel.project_dir%/web/assets"
     

   • Apply with construction-kit:apply project_assets.

3. Config Snippets:

   • Share partial configs (e.g., Doctrine, Twig):

     # config/construction_kit/blocks/doctrine.yml
     doctrine:
         type: config
         target: config/packages/doctrine.yaml
         content: |
             doctrine:
                 dbal:
                     url: "%env(DATABASE_URL)%"
     

4. Project Templates:

   • Use blocks to scaffold new projects with consistent setups:

     php bin/console construction-kit:apply base_template
     

Workflows

1. Centralized Block Repository:

   • Store block definitions in a shared Git repo (e.g., company-construction-kit).
   • Clone the repo into config/construction_kit/ of each project.

2. Versioned Blocks:

   • Tag block versions (e.g., v1.0.0) and reference them in projects:

     my_block:
         version: v1.0.0
     

3. Conditional Application:

   • Use environment variables to toggle blocks:

     debug_tools:
         type: bundle
         bundle: Symfony\WebProfilerBundle\WebProfilerBundle
         enabled: "%kernel.debug%"
     

4. Post-Apply Hooks:

   • Extend the ConstructionKitEvents to run custom logic after applying blocks (e.g., cache clearing):

     // src/EventListener/ConstructionKitListener.php
     public function onPostApply(PostApplyEvent $event) {
         $this->container->get('cache_clearer')->clear();
     }
     

Integration Tips

1. Symfony Flex:

   • Combine with symfony/flex for dynamic bundle installation:

     # config/construction_kit/blocks/symfony_flex.yml
     symfony_flex:
         type: command
         command: composer require symfony/orm-pack
     

2. Propel ORM:

   • Use the type: propel block for Propel-specific configs (if extended):

     propel:
         type: propel
         config:
             propel:
                 database:
                     connections:
                         default:
                             adapter: mysql
     

3. CI/CD Pipelines:

   • Automate block application in deployment scripts:

     # deploy.sh
     git clone company-construction-kit config/construction_kit
     php bin/console construction-kit:apply --all
     

4. Custom Block Types:

   • Extend the bundle to support new block types (e.g., database, environment):

     // src/DependencyInjection/Compiler/BlockTypePass.php
     public function process(ContainerBuilder $container) {
         $definition = $container->findDefinition('construction_kit.block_type');
         $definition->addMethodCall('addType', ['database', new Reference('app.database_block')]);
     }
     

Gotchas and Tips

Pitfalls

1. Overwriting Configs:

   • Applying blocks to config/packages/*.yaml may overwrite existing configs. Use !import or merge strategies:

     # construction_kit/blocks/doctrine.yml
     doctrine:
         type: config
         target: config/packages/doctrine.yaml
         strategy: merge
         content: |
             doctrine:
                 orm:
                     mappings:
                         App:
                             is_bundle: false
     

2. Circular Dependencies:

   • Blocks referencing each other (e.g., block_a depends on block_b, which depends on block_a) will fail silently. Validate block graphs:

     php bin/console construction-kit:validate
     

3. File Permissions:

   • Blocks writing to web/ or var/ may fail due to permissions. Set up proper ownership:

     chown -R www-data:www-data config/construction_kit
     

4. Propel-Specific Issues:

   • If using Propel, ensure the propel:build command is run post-application:

     php bin/console construction-kit:apply propel_config && php bin/console propel:build
     

Debugging

1. Dry Runs:

   • Test block application without changes:

     php bin/console construction-kit:apply my_block --dry-run
     

2. Verbose Output:

   • Enable debug mode for detailed logs:

     php bin/console construction-kit:apply my_block -vvv
     

3. Event Listeners:

   • Debug block application lifecycle with listeners:

     public function onPreApply(PreApplyEvent $event) {
         error_log("Applying block: " . $event->getBlockName());
     }
     

4. Block Validation:

   • Validate YAML syntax and structure:

     php bin/console construction-kit:validate my_block
     

Config Quirks

1. Parameter Placeholders:

   • Use %kernel.project_dir% or custom parameters in block configs:

     assets:
         type: asset
         source: "%construction_kit.assets.source%"
     

   • Define parameters in config/packages/construction_kit.yaml:

     construction_kit:
         assets:
             source: "%kernel.project_dir%/src/Resources/public"
     

2. Environment-Specific Blocks:

   • Use %env() in block configs for environment variables:

     database:
         type: config
         target: config/packages/doctrine.yaml
         content: |
             doctrine:
                 dbal:
                     url: "%env(DATABASE_URL)%"
     

3. Block Inheritance:

   • Extend blocks to avoid duplication:

     # base.yml
     base_config:
         type: config
         content: |
             framework:
                 secret: "%env(APP_SECRET)%"
     
     # app.yml
     app_config:
         extends: base_config
         content: |
             framework:
                 http_method_override: true
     

Extension Points

1. Custom Block Types:

   • Implement C33s\ConstructionKitBundle\Block\BlockTypeInterface:

     class DatabaseBlockType implements BlockTypeInterface {
         public function apply(Block $block, Project $project) {
             // Custom logic (e.g., create SQL dump)
         }
     }
     

   • Register in services.yaml:

     services:
         app.database_block:
             class: App\Block\DatabaseBlockType
             tags:
                 - { name: construction_kit.block_type, type: database }
     

2. Block Storage:

   • Override the block storage system to use a database or API:

     // src/DependencyInjection/Compiler/StoragePass.php
     public function process(ContainerBuilder $container) {
         $