Php Directive Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ecphp/php-directive-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Ecphp\PhpDirectiveBundle\PhpDirectiveBundle::class => ['all' => true],
   ];
   

2. Configuration: Create config/packages/php_directive.yaml:

   php_directive:
       user_ini_file: "%env(resolve:USER_INI_FILE)%"
   

   Define the .env variable:

   USER_INI_FILE=config/php.user.ini
   

3. First Use Case: Create config/php.user.ini with custom directives:

   memory_limit=256M
   display_errors=On
   

   Restart your web server (or PHP-FPM) to apply changes.

Implementation Patterns

Workflows

1. Project-Specific PHP Tweaks:

   • Store php.user.ini in version control (e.g., config/php.user.ini).
   • Useful for:
     • Development vs. production overrides (e.g., xdebug.mode=debug in dev).
     • Environment-specific settings (e.g., date.timezone per region).

2. Dynamic Configuration:

   • Combine with Symfony’s %kernel.environment% to load different .ini files per environment:

     php_directive:
         user_ini_file: "%kernel.project_dir%/config/php.%kernel.environment%.ini"
     

3. Validation:

   • Validate directives in php.user.ini against a whitelist (extend the bundle or use a pre-commit hook).

4. Integration with Deployment:

   • Automate .ini file placement during deployment (e.g., Ansible, Docker COPY).
   • Example Dockerfile snippet:

     COPY config/php.user.ini /usr/local/etc/php/conf.d/
     

Integration Tips

• Symfony Runtime: Use php_directive to override settings like error_reporting or upload_max_filesize without touching php.ini.
• Laravel Adaptation: While designed for Symfony, adapt by:
  • Publishing the .ini file to a Laravel config path (e.g., bootstrap/php.ini).
  • Using Laravel’s service provider to load the bundle logic (if needed).
• Caching: Clear OPcache after changes:

  // In a command or event listener
  shell_exec('php -r "opcache_reset();"');
  

Gotchas and Tips

Pitfalls

1. Permissions:

   • The .ini file must be readable by the PHP process (e.g., www-data).
   • Avoid restrictive permissions (e.g., chmod 644 config/php.user.ini).

2. Directive Conflicts:

   • System-wide php.ini settings override user .ini directives. Test changes in isolation.
   • Example: memory_limit in php.ini will override php.user.ini unless user_ini.filename is set in php.ini:

     ; Add to php.ini
     user_ini.filename = "php.user.ini"
     user_ini.cache_ttl = 0
     

3. Restart Requirement:

   • Changes to .ini files require a PHP process restart (e.g., sudo service php-fpm restart).
   • Use pcntl_fork() or posix_kill() in CLI scripts to reload PHP-FPM dynamically (advanced).

4. Directive Syntax:

   • Invalid syntax in .ini files may cause PHP to ignore the entire file. Validate with:

     php -n -c /path/to/php.user.ini -i | grep "Configuration File"
     

Debugging

• Check Loaded Directives:

  <?php
  phpinfo();
  

  Look for "Loaded Configuration File" and "Scan this dir for additional .ini files."

• Log Parsing Errors: Add to php.user.ini:

  error_log = /var/log/php/user_ini_errors.log
  log_errors = On
  

Extension Points

1. Custom Validation: Extend the bundle by overriding the PhpDirectiveLoader service to validate directives against a whitelist:

   # config/services.yaml
   Ecphp\PhpDirectiveBundle\Loader\PhpDirectiveLoader:
       arguments:
           $allowedDirectives: ['memory_limit', 'date.timezone']
   

2. Dynamic File Paths: Use Symfony’s ParameterBag to dynamically set the .ini file path based on environment or user input:

   php_directive:
       user_ini_file: "%kernel.project_dir%/config/php.%app_user%.ini"
   

3. Post-Processing: Hook into the kernel.terminate event to log or analyze loaded directives:

   // src/EventListener/PhpDirectiveListener.php
   public function onTerminate(TerminateEvent $event): void {
       $iniSettings = ini_get_all();
       // Log or process $iniSettings
   }
   

Tips

• Environment Separation: Use placeholders in .ini files for environment-specific values:

  ; config/php.user.ini
  date.timezone = "%env(resolve:APP_TIMEZONE)%"
  

  Then define APP_TIMEZONE in .env.

• Backup Originals: Keep a backup of the default php.ini for rollback:

  cp /etc/php/8.1/fpm/php.ini /etc/php/8.1/fpm/php.ini.default
  

• CI/CD: Test .ini file changes in CI by validating output:

  php -n -c config/php.user.ini -i | grep "memory_limit" | grep "256M"