Getting Started

Minimal Steps

Installation: Symfony Flex is automatically included when you create a new Symfony project via composer create-project symfony/skeleton. For existing projects, add it as a Composer plugin:
```
composer require symfony/flex --dev
```
No additional configuration is needed—Flex activates automatically.
First Use Case: Install a Symfony bundle/Pack and let Flex handle the boilerplate:
```
composer require symfony/orm-pack
```
This auto-generates:
- config/packages/doctrine.yaml
- .env variables (e.g., DATABASE_URL)
- Migration templates in src/Migrations
- Composer scripts (e.g., make:migration).
Where to Look First:
- Recipes: Explore Symfony’s official recipes (e.g., symfony/orm-pack, api-platform/core).
- Commands: Run composer recipes:list to see installed recipes and composer recipes:update to sync configs.
- Debugging: Use composer why-not symfony/flex to check for conflicts or composer why symfony/flex to verify installation.

Implementation Patterns

Core Workflows

Bundle/Pack Installation:
```
composer require vendor/package-name
```
- Flex detects the package’s extra.symfony.recipe metadata and runs its recipe (e.g., copying config files, updating .env).
- Example: Installing symfony/mercure-bundle auto-configures WebSocket endpoints in config/packages/mercure.yaml.
Recipe Updates:
```
composer recipes:update
```
- Syncs all recipes to their latest versions, updating configs without manual intervention.
- Use --yes to skip confirmation prompts:
```
composer recipes:update --yes
```
Custom Recipes:
- Store recipes in config/recipes/ (for project-specific configs) or publish them to a private Git repo.
- Reference them in composer.json:
```
"extra": {
    "symfony": {
        "recipes": [
            "path/to/local-recipe"
        ]
    }
}
```
Environment-Specific Configs:
- Use composer config extra.symfony.env to target specific environments (e.g., dev, prod).
- Example: Override a recipe’s config/packages/security.yaml for staging:
```
composer config extra.symfony.env staging
```
Integration with Laravel:
- Symfony Components: Use Flex for Symfony libraries (e.g., symfony/mailer) in Laravel:
```
composer require symfony/mailer
```
  Flex generates .env vars like MAILER_DSN.
- Hybrid Projects: For Laravel + Symfony bundles (e.g., API Platform), install the bundle normally and let Flex handle its configs while keeping Laravel’s config/ and routes/ separate.

Pro Tips

Composer Scripts: Leverage Flex’s composer-scripts configurator to add project-specific scripts:

"scripts": {
    "post-install-cmd": [
        "@symfony-scripts",
        "php bin/console cache:clear"
    ]
}

Docker: Use Flex in Dockerized Symfony/Laravel apps by mounting config/ and .env volumes to persist auto-generated files.
CI/CD: Run composer recipes:update in CI to ensure all environments use the same configs:
```
# .github/workflows/deploy.yml
- run: composer recipes:update --yes
```

Gotchas and Tips

Pitfalls

File Overwrites:
- Flex recipes may overwrite existing files (e.g., .env, config/packages/*.yaml). Backup critical files before running recipes:update.
- Fix: Use composer recipes:update --dry-run to preview changes or exclude files via .symfony.lock:
```
# .symfony.lock
ignored_files:
    - config/packages/custom.yaml
```
Recipe Conflicts:
- Conflicting recipes (e.g., two bundles defining the same .env var) may cause errors.
- Fix: Check composer why vendor/package to debug dependencies or manually resolve conflicts in config/packages/.
Symfony-Specific Assumptions:
- Flex assumes Symfony’s directory structure (config/, public/, var/). Laravel projects may need to:
  - Exclude Laravel-specific files from Flex’s purview (e.g., config/app.php).
  - Manually merge configs (e.g., place Symfony’s security.yaml in config/packages/security.yaml and load it in Laravel’s config/app.php).
Composer Version Quirks:
- Flex works best with Composer 2.x. Older versions (1.x) may trigger warnings or breakages.
- Fix: Update Composer:
```
composer self-update
```
Private Recipes:
- Private recipes (e.g., from GitHub private repos) require authentication.
- Fix: Set a GitHub token:
```
composer config github-oauth.github.com GH_TOKEN
```

Debugging

Verbose Mode: Run with -vvv to see Flex’s actions:
```
composer recipes:update -vvv
```
Lock File: Inspect .symfony.lock to understand applied recipes and ignored files.

Recipe Isolation: Test recipes in a fresh project:

composer create-project symfony/skeleton test-flex
cd test-flex
composer require vendor/package

Extension Points

Custom Recipes:

Create a recipe for your Laravel/Symfony hybrid project:

# config/recipes/my-hybrid-recipe.yaml
name: My Hybrid Recipe
config:
    packages:
        - { path: config/packages/my_service.yaml }
env:
    MY_VAR: "value"

Reference it in composer.json:

"extra": {
    "symfony": {
        "recipes": ["config/recipes/my-hybrid-recipe.yaml"]
    }
}

Overriding Defaults:

Override a recipe’s config by placing a file in config/packages/ with the same name (Flex merges configs).

Example: Override mercure.yaml:

# config/packages/mercure.yaml
mercure:
    hubs:
        default:
            url: "%env(MERCURE_HUB_URL)%"
            public_url: "https://example.com/.well-known/mercure"

Composer Scripts:

Extend Flex’s scripts in composer.json:

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

Laravel-Specific Tips

Symfony Components: Use Flex for Symfony libraries but avoid its configs for Laravel’s core (e.g., config/app.php).
Environment Variables: Let Flex manage Symfony-specific .env vars (e.g., DATABASE_URL) while keeping Laravel’s vars (e.g., APP_ENV) separate.
Artisan Commands: If using Symfony’s Console component, Flex may generate bin/console—ensure it’s not conflicting with Laravel’s artisan. Rename or alias if needed:
```
alias artisan='php artisan'
```

Flex Laravel Package