Config Helper Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adrenalinkin/config-helper
   

   Add to config/app.php under providers:

   Adrenalinkin\ConfigHelper\ConfigHelperServiceProvider::class,
   

2. First Use Case Create a YAML config file at config/packages/your-package/config.yaml:

   # config/packages/your-package/config.yaml
   app:
       name: "Your Package"
       version: "1.0.0"
       settings:
           debug: true
   

   Access it in a service:

   use Adrenalinkin\ConfigHelper\ConfigHelper;
   
   class YourService
   {
       public function __construct(private ConfigHelper $configHelper)
       {
       }
   
       public function getConfig()
       {
           return $this->configHelper->get('your-package');
       }
   }
   

3. Where to Look First

   • Service Provider: Adrenalinkin\ConfigHelper\ConfigHelperServiceProvider (registers the ConfigHelper binding).
   • Config Structure: Follow the config/packages/{bundle-name}/config.yaml convention.
   • API Docs: Check ConfigHelper class methods (e.g., get(), set(), has()).

Implementation Patterns

Workflows

1. Bundle-Specific Configs Use the package to isolate configs per bundle (e.g., auth-package, payment-package):

   # config/packages/auth-package/config.yaml
   guards:
       web: { driver: session, provider: users }
       api: { driver: jwt, provider: users }
   

2. Dynamic Config Loading Load configs conditionally (e.g., environment-specific):

   $config = $this->configHelper->get('your-package', 'config');
   if ($config['debug'] && app()->environment('local')) {
       // Enable debug features
   }
   

3. Merging Configs Override defaults in config/app.php:

   'your-package' => [
       'settings' => [
           'debug' => env('YOUR_PACKAGE_DEBUG', false),
       ],
   ],
   

Integration Tips

• Service Binding: Bind custom configs to Laravel’s container:

  $this->app->singleton('auth.guards', function ($app) {
      return $app->make(ConfigHelper::class)->get('auth-package.guards');
  });
  

• Validation: Validate YAML configs using Laravel’s Validator:

  use Illuminate\Support\Facades\Validator;
  
  $validator = Validator::make(
      $this->configHelper->get('your-package'),
      ['settings.debug' => 'boolean']
  );
  

• Environment Awareness: Use app()->environment() to switch configs:

  # config/packages/your-package/config.yaml
  database:
      connection: {{ env('DB_CONNECTION') ?: 'mysql' }}
  

Gotchas and Tips

Pitfalls

1. File Naming Conventions

   • Issue: Forgetting config/packages/{bundle-name}/ prefix causes ConfigHelper to throw ConfigNotFoundException.
   • Fix: Enforce naming with a custom rule or config-helper middleware.

2. Caching Quirks

   • Issue: Configs aren’t reloaded after changes unless the cache is cleared (php artisan config:clear).
   • Fix: Use config:cache sparingly or implement a ConfigHelper::refresh() method.

3. YAML Parsing Errors

   • Issue: Invalid YAML (e.g., unquoted keys with special chars) breaks loading.
   • Fix: Validate YAML with Symfony\Component\Yaml\Yaml::parse().

4. Namespace Collisions

   • Issue: Overlapping keys (e.g., auth.guards in multiple packages).
   • Fix: Use unique prefixes (e.g., auth-package.guards).

Debugging Tips

• Log Configs: Dump configs to storage/logs:

  \Log::debug('Your Package Config:', $this->configHelper->get('your-package'));
  

• Check Loaded Files: Override ConfigHelper to log loaded paths:

  $configHelper->setLoader(function ($bundle) {
      \Log::debug("Loading config for bundle: $bundle");
      return file_get_contents("config/packages/$bundle/config.yaml");
  });
  

Extension Points

1. Custom Loaders Extend ConfigHelper to support JSON/ENV files:

   $configHelper->extendLoader('json', function ($bundle) {
       return json_decode(file_get_contents("config/packages/$bundle/config.json"), true);
   });
   

2. Event Listeners Trigger events on config load/change:

   ConfigHelper::loaded(function ($bundle, $config) {
       event(new ConfigLoaded($bundle, $config));
   });
   

3. Testing Mock ConfigHelper in tests:

   $this->app->instance(ConfigHelper::class, new class {
       public function get($bundle) { return ['test' => true]; }
   });