Composer Construction Kit Installer Laravel Package

Getting Started

Minimal Setup

1. Install the Plugin Add the plugin to your project's composer.json under config.extra.plugins:

   {
       "config": {
           "extra": {
               "plugins": {
                   "c33s/composer-construction-kit-installer": {
                       "type": "composer-plugin",
                       "version": "dev-main" // or latest stable version
                   }
               }
           }
       }
   }
   

   Run composer install or composer update to trigger the plugin.

2. Verify Activation Check for the generated config file at:

   config/config/c33s_construction_kit.composer.yml
   

   This file lists all detected c33s-building-blocks packages.

3. First Use Case Install a package with the c33s-building-blocks extra (e.g., c33s/construction-kit-bundle or a custom block). Example:

   composer require c33s/construction-kit-bundle
   

   The plugin auto-generates the config file, which the ConstructionKitBundle reads to load blocks.

Implementation Patterns

Workflow Integration

1. Symfony Flex Compatibility

   • Works seamlessly with Symfony Flex projects. The plugin hooks into Composer’s post-update-cmd script.
   • No manual configuration needed for new projects.

2. Custom Block Registration

   • To create a custom block, ensure your package’s composer.json includes:

     {
         "extra": {
             "c33s-building-blocks": {
                 "your-block-name": {
                     "type": "form|twig|controller|...",
                     "path": "src/Resources/your-block-resources"
                 }
             }
         }
     }
     

   • The plugin auto-detects and registers the block in c33s_construction_kit.composer.yml.

3. Conditional Block Loading

   • Use the if key in your block’s composer.json to conditionally load blocks:

     {
         "extra": {
             "c33s-building-blocks": {
                 "conditional-block": {
                     "type": "twig",
                     "path": "templates",
                     "if": "env(APP_ENV) == 'dev'"
                 }
             }
         }
     }
     

   • The generated YAML will include the block only if the condition is met.

4. Environment-Specific Blocks

   • Leverage Composer’s environment variables or platform checks:

     {
         "extra": {
             "c33s-building-blocks": {
                 "prod-only-block": {
                     "type": "controller",
                     "path": "src/Controller",
                     "if": "phpversion() >= '8.0'"
                 }
             }
         }
     }
     

5. Post-Install Scripts

   • Manually trigger the plugin for testing or CI/CD:

     composer run-script post-update-cmd
     

6. Disabling the Plugin

   • Disable auto-detection globally in composer.json:

     {
         "extra": {
             "c33s-construction-kit-disabled": true
         }
     }
     

   • Or disable for specific packages by adding the same key to their composer.json.

Gotchas and Tips

Pitfalls

1. Missing post-update-cmd Hook

   • If the plugin doesn’t run, ensure:
     • The plugin is listed under config.extra.plugins (not require-dev).
     • Composer’s scripts section includes post-update-cmd (Symfony Flex adds this by default).
   • Debug with:

     composer dump-autoload --verbose
     

2. Incorrect Block Paths

   • The path in c33s-building-blocks must be relative to the package root. Absolute paths or incorrect paths will cause the block to fail silently.
   • Validate paths by checking the generated c33s_construction_kit.composer.yml.

3. Circular Dependencies

   • If Package A depends on Package B (which is a block for A), ensure both packages declare their blocks correctly. The plugin processes blocks in dependency order, but complex setups may require manual ordering.

4. Case Sensitivity

   • Block names in c33s-building-blocks are case-sensitive. Ensure consistency between the composer.json and the ConstructionKitBundle configuration.

5. Plugin Conflicts

   • Avoid naming conflicts with other Composer plugins. If another plugin modifies post-update-cmd, the installer may not run. Check for conflicts with:

     composer why-not c33s/composer-construction-kit-installer
     

Debugging

1. Dry Run

   • Test changes without modifying files by running:

     composer run-script post-update-cmd -- --dry-run
     

   • Outputs the proposed changes to stderr.

2. Log Generation

   • Enable verbose logging in composer.json:

     {
         "config": {
             "log": true,
             "log-level": "verbose"
         }
     }
     

   • Check logs at ~/.composer/logs/ or project-specific logs.

3. Manual Validation

   • After updates, validate the generated YAML:

     cat config/config/c33s_construction_kit.composer.yml
     

   • Ensure all expected blocks are listed and paths are correct.

Extension Points

1. Custom Block Types

   • Extend the plugin by adding support for new block types. Fork the plugin and modify the BlockDetector class to handle custom type values in c33s-building-blocks.

2. Pre/Post-Processing

   • Override the generated YAML by hooking into the post-update-cmd script. Example:

     {
         "scripts": {
             "post-update-cmd": [
                 "c33s-construction-kit-installer",
                 "@php bin/console c33s:construction-kit:post-process"
             ]
         }
     }
     

3. Dynamic Block Conditions

   • Use PHP expressions in the if key by leveraging Composer’s platform-check or custom scripts:

     {
         "extra": {
             "c33s-building-blocks": {
                 "dynamic-block": {
                     "type": "service",
                     "path": "src/Service",
                     "if": "file_exists('/path/to/feature-flag')"
                 }
             }
         }
     }
     

4. Multi-Environment Configs

   • Generate environment-specific YAML files by extending the plugin’s ConfigWriter class to write to c33s_construction_kit.{env}.yml.

Configuration Quirks

1. Symlink Handling

   • If your project uses symlinks (e.g., for vendor/), ensure the plugin runs in the correct working directory. Symfony Flex handles this, but custom setups may need:

     cd /path/to/project && composer update
     

2. Platform-Specific Paths

   • Avoid hardcoding platform-specific paths (e.g., C:\path on Windows). Use forward slashes or Composer’s platform-check to normalize paths.

3. Caching Issues

   • Clear Composer’s cache if changes aren’t reflected:

     composer clear-cache
     

   • Delete the generated c33s_construction_kit.composer.yml and rerun composer update to force regeneration.