Amnesia Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require symplify/amnesia
   

   Note: Only use this for legacy Laravel/Symfony <5.3 projects where upgrading is not immediately feasible.

2. First Use Case: Replace a hardcoded Symfony extension configuration (e.g., framework.yaml) with PHP constants for type safety and IDE autocompletion. Example:

   use Symplify\Amnesia\ValueObject\Symfony\Extension\FrameworkExtension;
   
   $containerConfigurator->extension(FrameworkExtension::NAME, [
       FrameworkExtension::SECRET => env('APP_SECRET'),
   ]);
   

3. Where to Look First:

   • Browse Symplify\Amnesia\ValueObject\Symfony\Extension for pre-defined constants (e.g., FrameworkExtension, DoctrineExtension).
   • Check Symplify\Amnesia\Functions for helper functions like env().

Implementation Patterns

Usage Patterns

1. Symfony Extension Configuration:

   • Replace YAML/XML configs with PHP-based ContainerConfigurator calls.
   • Example workflow:

     // Before (YAML)
     framework:
         secret: '%env(APP_SECRET)%'
     
     // After (PHP)
     $containerConfigurator->extension(FrameworkExtension::NAME, [
         FrameworkExtension::SECRET => env('APP_SECRET'),
     ]);
     

2. Routing Configuration:

   • Use RoutingConfigurator for annotation-based routes:

     $routes->import(__DIR__ . '/../src/Controller', Routing::TYPE_ANNOTATION);
     

3. Doctrine Configuration:

   • Dynamically generate DBAL/ORM configs:

     $containerConfigurator->extension(DoctrineExtension::NAME, [
         DoctrineExtension::DBAL => [
             DBAL::HOST => env('DATABASE_HOST'),
             // ...
         ],
     ]);
     

Workflows

1. Legacy Migration:

   • Step 1: Identify Symfony extension configs in config/packages/ or config/bundles.php.
   • Step 2: Replace with Amnesia constants in a config.php file using ContainerConfigurator.
   • Step 3: Gradually migrate to Symfony 5.3+ ConfigBuilder or Laravel-native alternatives.

2. Environment-Aware Configs:

   • Use env() helper to inject .env variables:

     $containerConfigurator->extension(FrameworkExtension::NAME, [
         FrameworkExtension::SECRET => env('APP_SECRET'),
         FrameworkExtension::DEBUG => env('APP_DEBUG', 'prod') === 'dev',
     ]);
     

3. Twig Integration:

   • Centralize Twig globals and number formats:

     $containerConfigurator->extension(TwigExtension::NAME, [
         TwigExtension::GLOBALS => ['site_title' => 'MyApp'],
         TwigExtension::NUMBER_FORMAT => [NumberFormat::DECIMALS => 2],
     ]);
     

Integration Tips

1. Laravel-Symfony Bridge:

   • If using Symfony components in Laravel, register a Symfony\Component\DependencyInjection\ContainerBuilder alongside Laravel’s container.
   • Example:

     $symfonyContainer = new ContainerBuilder();
     $loader = new ContainerConfigurator($symfonyContainer);
     // Use Amnesia helpers here...
     

2. Service Provider Integration:

   • Load configs in Laravel’s register() method:

     public function register()
     {
         $container = $this->app->make('service_container');
         $symfonyContainer = new ContainerBuilder();
         $loader = new ContainerConfigurator($symfonyContainer);
         // Configure with Amnesia...
         $this->app->singleton('symfony.container', fn() => $symfonyContainer);
     }
     

3. Testing:

   • Mock ContainerConfigurator in PHPUnit:

     $container = $this->createMock(ContainerBuilder::class);
     $loader = new ContainerConfigurator($container);
     

Gotchas and Tips

Pitfalls

1. Deprecated Status:

   • Risk: The package is archived and may break with Symfony 6+ or Laravel 9+.
   • Workaround: Treat as a temporary migration tool; plan to replace with Symfony’s ConfigBuilder or Laravel-native solutions.

2. Symfony Dependency:

   • Issue: Requires Symfony’s ContainerBuilder, which Laravel does not natively support.
   • Fix: Use a standalone Symfony DI container or fork the package to remove Symfony dependencies (not recommended).

3. IDE Autocompletion:

   • Problem: Some constants (e.g., FrameworkExtension::SECRET) may not auto-complete in older PHPStorm/Laravel IDE Helper versions.
   • Solution: Regenerate IDE helpers or use @property annotations.

4. Environment Variables:

   • Gotcha: env() helper may not resolve Laravel’s .env files by default.
   • Fix: Ensure Symplify\Amnesia\Functions\env() is patched to use Laravel’s env() or config() helpers.

5. Configuration Overrides:

   • Risk: Dynamic configs can override Laravel’s built-in settings (e.g., APP_DEBUG).
   • Tip: Validate against Laravel’s config() values:

     if (config('app.debug') !== true) {
         $containerConfigurator->extension(FrameworkExtension::NAME, [
             FrameworkExtension::DEBUG => false,
         ]);
     }
     

Debugging

1. Container Dumping:

   • Dump Symfony’s container to debug configs:

     $symfonyContainer->compile();
     file_put_contents(
         storage_path('logs/symfony_container.php'),
         '<?php return ' . var_export($symfonyContainer->getParameterBag()->all(), true) . ';'
     );
     

2. Parameter Conflicts:

   • Error: ParameterNotFoundException if a required parameter (e.g., DATABASE_HOST) is missing.
   • Debug: Check .env or Symfony’s ParameterBag:

     $symfonyContainer->getParameter('database_host'); // Throws exception if missing
     

3. Routing Issues:

   • Symptom: Routes not loading with TYPE_ANNOTATION.
   • Fix: Ensure annotations are enabled in Symfony’s FrameworkBundle and paths are correct:

     $routes->import(__DIR__ . '/../../src/Controller', Routing::TYPE_ANNOTATION);
     

Config Quirks

1. Case Sensitivity:

   • Issue: Symfony extension names/keys are case-sensitive (e.g., FrameworkExtension::NAME vs. framework).
   • Tip: Use constants to avoid typos:

     $containerConfigurator->extension(FrameworkExtension::NAME, [...]); // Correct
     $containerConfigurator->extension('framework', [...]); // May fail
     

2. Default Values:

   • Gotcha: Some extensions (e.g., TwigExtension) require all nested keys to be defined.
   • Example:

     // Correct:
     $containerConfigurator->extension(TwigExtension::NAME, [
         TwigExtension::NUMBER_FORMAT => [
             NumberFormat::DECIMALS => 2,
             NumberFormat::DECIMAL_POINT => '.',
         ],
     ]);
     

3. Circular Dependencies:

   • Risk: Complex configs may cause circular references in Symfony’s container.
   • Solution: Simplify configs or use lazy-loading with ContainerConfigurator::services().

Extension Points

1. Custom Extensions:

   • How: Extend Symplify\Amnesia\ValueObject\Symfony\Extension\AbstractExtension to add new constants.
   • Example:

     namespace App\Amnesia\Extension;
     
     use Symplify\Amnesia\ValueObject\Symfony\Extension\AbstractExtension;
     
     class AppExtension extends AbstractExtension
     {
         public const NAME = 'app';
         public const TIMEZONE = 'timezone';
     }
     

2. Environment Helpers:

   • Override: Replace Symplify\Amnesia\Functions\env() with Laravel’s env():

     if (!function_exists('Symplify\Amnesia\Functions\env')) {
         function env(string $key, $default = null): string
         {
             return \Illuminate\Support\Env::get($key, $default);
         }
     }
     

3. Container Integration:

   • Bridge: Merge Symfony and Laravel containers:

     $laravelContainer = $this->app;
     $symfonyContainer = new ContainerBuilder();
     // Load Amnesia configs into $symfonyContainer...
     $laravelContainer->instance('symfony.container', $symfonyContainer);