Donkey Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require avexsoft/donkey
   

   Register the service provider in config/app.php under providers:

   Avexsoft\Donkey\DonkeyServiceProvider::class,
   

2. First Use Case Define a config override in config/donkey.php:

   return [
       'app.debug' => env('APP_DEBUG', false),
       'mail.driver' => env('MAIL_DRIVER', 'smtp'),
   ];
   

   Overrides will now take precedence in production without modifying .env.

Where to Look First

• Config File: config/donkey.php – Centralized override definitions.
• Service Provider: DonkeyServiceProvider – Boot logic for merging configs.
• Facade: Donkey::override() – Programmatic overrides (if needed).

Implementation Patterns

Workflow: Config Management

1. Environment-Specific Overrides Use donkey.php to define production defaults:

   return [
       'services.loggly.key' => env('LOGGLY_KEY', null),
       'queue.connections.redis.database' => env('REDIS_QUEUE_DB', 1),
   ];
   

   • Fallback to .env if keys are missing.

2. Dynamic Overrides via Facade Override configs programmatically (e.g., in a service provider):

   Donkey::override('app.locale', 'en_US');
   

3. Integration with Laravel Config Access overrides like any other config:

   $locale = config('app.locale'); // Respects Donkey overrides
   

Best Practices

• Avoid Hardcoding: Use env() fallbacks in donkey.php to keep .env as the source of truth.
• Group Overrides: Organize by feature (e.g., mail, queue, services).
• Testing: Mock Donkey overrides in tests:

  Donkey::shouldReceive('override')->andReturnUsing(fn($key, $value) => config([$key => $value]));
  

Gotchas and Tips

Pitfalls

1. Priority Conflicts

   • Donkey overrides only apply in production (checks APP_ENV). Test locally with:

     php artisan config:clear && php artisan config:cache
     

   • Overrides do not merge with existing config arrays (use array_merge manually if needed).

2. Caching Issues

   • Clear config cache after changes:

     php artisan config:clear
     

   • Cache must be rebuilt for overrides to take effect:

     php artisan config:cache
     

3. Facade vs. Config File

   • Prefer donkey.php for static overrides; use Donkey::override() sparingly (e.g., for runtime changes).

Debugging Tips

• Verify Overrides: Dump loaded config:

  dd(config('donkey')); // Check if your overrides are registered
  

• Check Environment: Donkey skips overrides in non-production environments. Test with:

  if (app()->environment('production')) {
      // Donkey overrides apply here
  }
  

Extension Points

1. Custom Override Logic Extend the service provider’s boot() method to add dynamic logic:

   public function boot()
   {
       if (someCondition()) {
           Donkey::override('custom.key', 'dynamic_value');
       }
   }
   

2. Environment-Specific Files Use donkey.php in config/ and override it in config/production/donkey.php for environment-specific tweaks.

3. Validation Validate overrides in donkey.php:

   return [
       'app.timezone' => env('APP_TIMEZONE', 'UTC'),
       'cache.default' => env('CACHE_DRIVER', 'file'), // Default to 'file' if unset
   ];