Flex Laravel Package

Getting Started

Minimal Steps to Begin

1. Install Flex in a Symfony Project Ensure your project has composer.json with "extra": { "symfony": { ... } } or is a Symfony skeleton. Flex is pre-installed in Symfony 4+ skeletons.

   composer require symfony/flex  # Only needed if not using a Symfony skeleton
   

2. First Use Case: Installing a Bundle Require a Symfony bundle (e.g., doctrine/doctrine-bundle) and let Flex handle the rest:

   composer require doctrine/doctrine-bundle
   

   • Flex auto-detects the bundle’s recipe (e.g., doctrine/doctrine-bundle recipe).
   • Applies default configurations (e.g., config/packages/doctrine.yaml, environment variables, or scripts).
   • No manual AppKernel registration (Symfony 4+) or AppBundle creation needed.

3. Verify Configuration Check config/packages/ for new files. Run:

   php bin/console debug:config doctrine  # Confirm bundle is enabled
   

4. Explore Recipes Browse Symfony Recipes or a bundle’s RECIPES.md (if provided) to understand what Flex applies.

Implementation Patterns

Core Workflows

1. Bundle Integration

• Add a Bundle: Use composer require with Flex’s auto-configuration:

  composer require api platform/core
  

  • Flex installs dependencies, applies recipes (e.g., api_platform.yaml config, Doctrine mappings), and updates config/bundles.php.
• Customize Defaults: Override recipe-generated files in config/packages/override/ (Symfony 4+) or merge configs manually.

2. Symfony Packs

• Install pre-configured stacks (e.g., API, Web, CLI) for consistent setups:

  composer require symfony/webpack-encore-pack
  

  • Packs include Flex recipes for bundles, tools (Webpack, Babel), and configs.

3. Environment-Specific Configs

• Flex generates environment-aware configs (e.g., .env.local variables for bundles like monolog).
• Extend with config/packages/dev/doctrine.yaml for environment-specific tweaks.

4. Post-Install Scripts

• Recipes often add scripts to composer.json (e.g., post-install-cmd for migrations):

  "scripts": {
      "post-install-cmd": [
          "@symfony-scripts",
          "DoctrineMigrations\\Migrations\\MigrationsGenerator:generate"
      ]
  }
  

• Run scripts manually with:

  composer post-install
  

5. Updating Packages

• Flex handles updates gracefully:

  composer update api-platform/core
  

  • Recipes may update configs/scripts (e.g., new Doctrine types in doctrine.yaml).

Integration Tips

• Laravel-Specific Adaptations:

  • Flex isn’t Laravel-native, but you can mimic its benefits by:
    • Using Laravel Packages with config/ and migrations/ auto-loading (e.g., spatie/laravel-package-tools).
    • Leveraging Service Providers to auto-register configs (e.g., PackageServiceProvider).
  • Example: A Laravel package’s composer.json could define:

    "extra": {
        "laravel": {
            "providers": ["Vendor\\Package\\ServiceProvider"],
            "aliases": {
                "Package": "Vendor\\Package\\Facades\\Package"
            }
        }
    }
    

• Debugging Recipe Issues:

  • Check var/cache/dev/app_recipes.json for applied recipes.
  • Use composer why-not <package> to diagnose dependency conflicts.

• Extending Recipes:

  • Create custom recipes for your packages by defining a RECIPES.md in your repo (see Symfony Recipe Guide).

Gotchas and Tips

Pitfalls

1. Recipe Conflicts

   • Issue: Two recipes try to modify the same config file (e.g., doctrine.yaml).
   • Fix: Use config/packages/override/ to merge configs or manually resolve conflicts.
   • Debug: Run composer why-not symfony/orm-pack to check dependency issues.

2. Caching Quirks

   • Issue: Changes to config/packages/ aren’t reflected due to cached recipes.
   • Fix: Clear the recipe cache:

     rm -rf var/cache/dev/app_recipes.json
     composer dump-autoload
     

3. Legacy Symfony (3.x) Limitations

   • Issue: Flex auto-configuration assumes Symfony 4+ (e.g., no AppKernel).
   • Fix: Manually register bundles in AppKernel.php if using Symfony 3.

4. Overzealous Scripts

   • Issue: Recipes add scripts that run on every composer install (e.g., migrations).
   • Fix: Disable scripts in composer.json:

     "scripts": {
         "post-install-cmd": [
             "@symfony-scripts --no-scripts"
         ]
     }
     

5. Pack Compatibility

   • Issue: Mixing Packs (e.g., web-pack + api-pack) may cause conflicts.
   • Fix: Use Packs as standalone stacks or manually resolve overlaps.

Debugging Tips

• Inspect Applied Recipes:

  composer show --tree | grep recipe
  

• Check Recipe Sources:

  composer why symfony/orm-pack
  

• Disable Flex Temporarily:

  composer config extra.symfony.enable-flex false
  

  (Re-enable with true after debugging.)

Extension Points

1. Custom Recipes

   • Define a RECIPES.md in your package’s root:

     # MyPackage Recipe
     ## Config
     - Copy `config/my_package.php` to `config/packages/my_package.yaml`
     
     ## Scripts
     - Add to `composer.json`:
       ```json
       "scripts": {
           "post-install-cmd": [
               "MyPackage\\Installer\\Installer::postInstall"
           ]
       }
     

   • See Symfony Recipe Format.

2. Hook into Flex Events

   • Use symfony/flex’s post-install events in your package’s composer.json:

     "scripts": {
         "post-install-cmd": [
             "@symfony-scripts",
             "Vendor\\Package\\Composer\\ScriptHandler::postInstall"
         ]
     }
     

3. Laravel Package Auto-Loading

   • For Laravel, use spatie/laravel-package-tools to auto-publish configs:

     // config/my_package.php
     return [
       'enabled' => env('MY_PACKAGE_ENABLED', true),
     ];
     

   • The package will auto-publish this to config/my_package.php on install.

Pro Tips

• Symfony 5+: Use config/packages/_default/ for shared configs across environments.
• CI/CD: Cache var/cache/dev/app_recipes.json to speed up builds.
• Local Development: Symlink recipe-generated configs to avoid overwrites:

  ln -s vendor/symfony/orm-pack/Resources/stubs/config/doctrine.yaml config/packages/doctrine.yaml