Symfony Laravel Package

Getting Started

Minimal Steps

1. Installation: Run composer require bella-baxter/symfony in your Laravel project.
2. Service Provider: Register the bundle in config/app.php under providers:

   BellaBaxter\Symfony\BellaBundle::class,
   

3. Configuration: Publish the config with php artisan vendor:publish --provider="BellaBaxter\Symfony\BellaBundle" and update .env:

   BELLA_BAXTER_URL=https://api.bella-baxter.io
   BELLA_BAXTER_API_KEY=bax-your-api-key
   

4. First Use Case: Access secrets via $_ENV or getenv() in a controller or service:

   $dbUrl = $_ENV['DATABASE_URL'];
   

Implementation Patterns

Workflows

1. Environment-Based Secrets:

   • Use auto_load: true (default) to inject secrets into $_ENV on the first HTTP request.
   • Access secrets via $_ENV, getenv(), or $_SERVER in any part of your application (controllers, services, commands).

2. Service Injection:

   • Inject BaxterClient directly into services for programmatic access to secrets:

     use BellaBaxter\BaxterClient;
     
     class DatabaseService {
         public function __construct(private BaxterClient $bella) {}
     
         public function getConnection() {
             $url = $this->bella->getSecret('DATABASE_URL');
             // Use $url
         }
     }
     

3. Lazy Loading:

   • Disable auto_load in config/packages/bella.yaml and manually trigger secret loading:

     $this->bella->loadSecrets();
     

4. Environment-Specific Secrets:

   • Use Bella Baxter’s environment tags (e.g., production, staging) to load context-specific secrets:

     bella:
       environment: '%env(APP_ENV)%'
     

Integration Tips

• Laravel Environment: Ensure APP_ENV matches Bella Baxter’s environment tags for correct secret loading.
• Caching: Secrets are loaded once per request; avoid repeated calls to loadSecrets().
• Fallbacks: Use Laravel’s env() helper with defaults for critical secrets:

  $dbUrl = env('DATABASE_URL', $_ENV['DATABASE_URL'] ?? 'fallback-url');
  

Gotchas and Tips

Pitfalls

1. Timing Issues:

   • Secrets are loaded only on the first HTTP request. Avoid accessing $_ENV in service constructors or boot methods before the request lifecycle starts.
   • Fix: Use BaxterClient injection or defer secret access until a controller/action.

2. Configuration Overrides:

   • Bundle config in config/packages/bella.yaml overrides .env values. Ensure consistency:

     bella:
       url: 'https://custom-bella-url.io'  # Overrides BELLA_BAXTER_URL
     

3. API Key Exposure:

   • Never commit .env or config/packages/bella.yaml to version control. Use Laravel’s .env.example for placeholders.

4. Circular Dependencies:

   • Avoid injecting BaxterClient into providers or boot methods that run before the bundle initializes.

Debugging

• Verify Loading: Check if secrets are loaded via:

  if (!isset($_ENV['DATABASE_URL'])) {
      throw new \RuntimeException('Secrets not loaded!');
  }
  

• Logs: Enable debug mode in config/packages/bella.yaml:

  bella:
    debug: true
  

  Check Laravel logs for loading errors.

Extension Points

1. Custom Secret Handlers:

   • Extend BaxterClient to transform secrets before injection:

     $this->bella->on('secret.loaded', function ($secret) {
         $_ENV[strtoupper($secret['name'])] = base64_decode($secret['value']);
     });
     

2. Event Listeners:

   • Listen for bella.secrets.loaded events to react to secret changes:

     use BellaBaxter\Events\SecretsLoaded;
     
     public function handle(SecretsLoaded $event) {
         // Refresh cache or update services
     }
     

3. Fallback Secrets:

   • Combine with Laravel’s env() helper for hybrid secret management:

     $secret = env('SECRET_KEY', $_ENV['SECRET_KEY'] ?? 'default');
     

Config Quirks

• auto_load Behavior:
  • Set to false to manually control loading (e.g., in a command):

    $this->bella->loadSecrets(); // Explicit trigger
    

• Environment Variables:
  • Prefix Bella Baxter-specific env vars with BELLA_BAXTER_ to avoid conflicts with Laravel’s defaults.