Env Providers Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle via Composer:

   composer require c0ntax/env-providers-bundle
   

   Register the bundle in config/bundles.php (or app/Kernel.php if not using Flex):

   C0ntax\EnvProvidersBundle\C0ntaxEnvProvidersBundle::class => ['all' => true],
   

2. First Use Case Define an array-like environment variable in .env:

   MY_ARRAY=apple,banana,cherry
   

   Reference it in config/packages/dev.yaml (or your preferred config file):

   parameters:
       my_fruit_array: '%env(array:MY_ARRAY)%'
   

   Access it in PHP:

   $fruits = $this->getParameter('my_fruit_array'); // ['apple', 'banana', 'cherry']
   

Implementation Patterns

Workflows

1. Array Parsing Use env(array:VAR_NAME) to split comma-separated .env values into PHP arrays. Example:

   parameters:
       allowed_roles: '%env(array:ALLOWED_ROLES)%'  # .env: ALLOWED_ROLES=admin,user,moderator
   

2. Boolean Handling Leverage Symfony’s built-in %env(bool:VAR_NAME)% for true/false/1/0/yes/no values:

   DEBUG_MODE=true
   

   parameters:
       debug: '%env(bool:DEBUG_MODE)%'
   

3. Default Fallbacks Combine with Symfony’s %env(VAR_NAME::default_value)% syntax:

   parameters:
       api_timeout: '%env(int:API_TIMEOUT::30)%'  # Defaults to 30 if API_TIMEOUT is missing
   

4. Conditional Logic Use parsed values in when clauses (e.g., config/packages/dev.yaml):

   when@dev:
       parameters:
           cache_enabled: '%env(bool:CACHE_ENABLED::false)%'
   

Integration Tips

• Validation: Validate parsed arrays in config/validator/constraints.yaml:

  App\Validator\Constraints\ValidFruits:
      params:
          allowed: '%env(array:ALLOWED_FRUITS)%'
  

• Type Safety: Cast to specific types in PHP:

  $timeout = (int) $this->getParameter('api_timeout');
  

• Environment-Specific Configs: Override .env values per environment (e.g., .env.prod, .env.test).

Gotchas and Tips

Pitfalls

1. Empty Arrays By default, env(array:VAR_NAME) returns an empty array if VAR_NAME is empty. To return null instead, configure:

   c0ntax_env_providers:
       array:
           return_null_if_empty: true
   

   EMPTY_ARRAY=
   

   parameters:
       empty_array: '%env(array:EMPTY_ARRAY)%'  # Now returns `null`
   

2. Whitespace Handling Comma-separated values with spaces (e.g., apple, banana) will include whitespace in array items. Trim manually:

   $fruits = array_map('trim', $this->getParameter('my_fruit_array'));
   

3. Symfony Version Compatibility Tested for Symfony 3+. For Symfony 4/5/6, ensure the bundle’s registerBundles() method aligns with your kernel’s structure.

4. Caching Quirks Changes to .env require cache clearing:

   php bin/console cache:clear
   

Debugging

• Validate .env Syntax: Use php bin/console debug:env to check parsed values.
• Log Parsed Values: Temporarily log parameters in a service constructor:

  public function __construct(private array $params) {
      \Log::debug('Parsed params:', $this->params);
  }
  

Extension Points

1. Custom Providers Extend the bundle by creating a new provider class (e.g., for JSON arrays):

   // src/Provider/JsonArrayProvider.php
   namespace App\Provider;
   use Symfony\Component\DependencyInjection\ContainerBuilder;
   class JsonArrayProvider implements \C0ntax\EnvProvidersBundle\Provider\ProviderInterface {
       public function parse($value, ContainerBuilder $container) {
           return json_decode($value, true) ?: [];
       }
   }
   

   Register it in config/packages/c0ntax_env_providers.yaml:

   c0ntax_env_providers:
       providers:
           json_array: App\Provider\JsonArrayProvider
   

   Usage:

   parameters:
       json_config: '%env(json_array:JSON_CONFIG)%'
   

2. Override Default Behavior Replace the bundle’s ArrayProvider service definition in config/services.yaml:

   services:
       C0ntax\EnvProvidersBundle\Provider\ArrayProvider:
           class: App\Provider\CustomArrayProvider