Flex Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation: Add Symfony Flex to your Laravel project via Composer:

   composer require symfony/flex
   

   This installs the plugin globally for your project, enabling recipe-based dependency management.

2. First Use Case: Install a Symfony component (e.g., symfony/mailer) with auto-generated configs:

   composer require symfony/mailer
   

   Flex automatically:

   • Adds the package to composer.json.
   • Generates or updates .env variables (e.g., MAILER_DSN).
   • Creates Symfony-specific configs (e.g., config/packages/mailer.yaml if using YAML configs).

3. Where to Look First:

   • Recipes: Check the Symfony Flex Recipes repository for package-specific configurations.
   • Symfony Lock File: The symfony.lock file tracks installed recipes and their versions.
   • Composer Commands: Run composer recipes:list to see installed recipes and composer recipes:update to update them.

Implementation Patterns

Daily Workflow Integration

1. Dependency Management:

   • Use composer require for Symfony packages (e.g., symfony/console, api-platform/core). Flex handles the rest.
   • Example:

     composer require symfony/console --dev
     

     This installs the package and generates a config/packages/console.yaml file.

2. Updating Dependencies:

   • Update all Symfony recipes with:

     composer recipes:update
     

   • Use --no-changelog to skip changelog generation:

     composer recipes:update --no-changelog
     

3. Environment Configuration:

   • Flex auto-generates .env variables for Symfony packages. Override them in your .env file as needed.
   • Example: If symfony/mailer adds MAILER_DSN, customize it in .env:

     MAILER_DSN=smtp://user:pass@smtp.example.com:2525
     

4. Laravel-Specific Patterns:

   • Symfony Packages in Laravel: Use Flex for Symfony components (e.g., symfony/http-client) while keeping Laravel’s core workflows intact.
   • Hybrid Configs: Merge Laravel’s config/ with Symfony’s config/packages/ by:
     • Placing Symfony configs in config/packages/ (Flex handles this).
     • Using Laravel’s service providers to bridge Symfony services (e.g., register Symfony’s HttpClient in Laravel’s AppServiceProvider).

5. CI/CD Integration:

   • Add to your composer.json scripts for automated updates:

     "scripts": {
       "post-install-cmd": [
         "@symfony/flex:composer:install"
       ],
       "post-update-cmd": [
         "@symfony/flex:composer:update"
       ]
     }
     

   • Run composer recipes:update in CI to ensure consistent environments.

6. Custom Recipes:

   • Create project-specific recipes by extending Symfony’s recipe system.
   • Example: Add a custom recipe for a Laravel-Symfony hybrid package in recipes/YourVendor/YourPackage/.

Integration Tips

1. Laravel Service Providers:

   • Register Symfony services in Laravel’s AppServiceProvider:

     use Symfony\Component\HttpClient\HttpClient;
     
     public function register()
     {
         $this->app->singleton('symfony.http_client', function () {
             return HttpClient::create();
         });
     }
     

2. Environment Variables:

   • Prefix Symfony .env variables with SYMFONY_ to avoid conflicts with Laravel’s variables (e.g., SYMFONY_MAILER_DSN).

3. Docker and Flex:

   • Use Flex’s DockerComposeConfigurator to manage Docker-specific configs. Example:

     # docker-compose.yml
     services:
       app:
         image: your-app
         volumes:
           - .:/var/www/html
           - ./config/packages:/var/www/html/config/packages  # Symfony configs
     

4. Debugging Configs:

   • Dump Symfony’s environment configs to debug:

     php bin/console debug:container --parameters
     

5. Symfony Runtime:

   • For Symfony 6+, use symfony/runtime with Flex for optimized bootstrapping:

     composer require symfony/runtime
     

Gotchas and Tips

Pitfalls

1. File Overwrites:

   • Flex may overwrite files during updates. Use --yes to skip confirmation:

     composer recipes:install --yes
     

   • Exclude files from updates by adding them to .gitignore or .symfony.lock exclusions.

2. Environment Conflicts:

   • Symfony and Laravel may use overlapping .env keys. Prefix Symfony keys (e.g., SYMFONY_) to avoid conflicts.

3. Recipe Conflicts:

   • If two recipes define the same config file, Flex may fail. Resolve conflicts by:
     • Customizing recipes or using composer recipes:remove for problematic packages.

4. Composer Scripts:

   • Avoid running composer dump-autoload manually after Flex updates, as Flex handles this automatically.

5. Symfony Lock File:

   • The symfony.lock file tracks recipe versions. Commit it to version control to ensure consistency across environments.

6. Private Recipes:

   • For private recipes (e.g., internal Symfony packages), use GitHub access tokens:

     composer require your/private-package --auth=github-oauth
     

Debugging Tips

1. Verbose Output:

   • Run Flex commands with -v for debugging:

     composer recipes:update -v
     

2. Check Installed Recipes:

   • List installed recipes and their versions:

     composer recipes:list
     

3. Update Specific Recipes:

   • Update a single recipe:

     composer recipes:update YourVendor/YourPackage
     

4. Symfony Debug Commands:

   • Use Symfony’s debug commands to inspect configs:

     php bin/console debug:config mailer
     

5. Clear Cache:

   • Clear Symfony’s cache if configs aren’t updating:

     php bin/console cache:clear
     

Extension Points

1. Custom Configurators:

   • Extend Flex’s configurators (e.g., ComposerScriptsConfigurator) to handle project-specific logic. Example:

     // In a custom recipe
     public function configure(Configuration $configuration)
     {
         $configuration->setConfigurator(new class implements ConfiguratorInterface {
             public function configure(Configuration $configuration)
             {
                 // Custom logic here
             }
         });
     }
     

2. Recipe Development:

   • Create custom recipes for Laravel-Symfony hybrid packages. Example structure:

     recipes/
       YourVendor/
         YourPackage/
           YourPackageRecipe.php
           resources/
             config/
               packages/
                 your_package.yaml
     

3. Environment-Specific Recipes:

   • Use environment variables to conditionally apply recipes:

     # composer.json
     "extra": {
       "symfony": {
         "require": {
           "dev": ["symfony/debug-bundle"]
         }
       }
     }
     

4. Post-Install Scripts:

   • Add custom scripts to composer.json to run after Flex updates:

     "scripts": {
       "post-recipes-update": [
         "@php artisan config:clear"
       ]
     }
     

5. Symfony Runtime Integration:

   • For Symfony 6+, use symfony/runtime with Flex to optimize bootstrapping:

     composer require symfony/runtime
     

   • Configure in config/bundles.php:

     return [
         // ...
         Symfony\UX\RuntimeBundle\RuntimeBundle::class => ['all' => true],
     ];
     

Pro Tips

1. Leverage Symfony Packs:

   • Use Symfony Packs (e.g., symfony/webpack-encore) with Flex for seamless integration:

     composer require symfony/webpack-encore
     

2. Hybrid Testing:

   • Test Symfony services in Laravel’s PHPUnit by extending Symfony’s test utilities:

     use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
     
     class MyTest extends WebTestCase {
         // Test Symfony services in Laravel
     }
     

3. Flex with Laravel Mix:

   • Combine Flex’s webpack-encore with Laravel Mix for asset management:

     // webpack.mix.js
     const { mix } = require('laravel-mix');
     const Encore = require('@symfony/webpack-encore');
     
     Encore
         .setOutputPath('public/build')