Proteus Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require stillat/proteus

No service provider or facade needed—use the Proteus class directly.

2. First Use Case: Reading Config

   use Stillat\Proteus\Proteus;
   
   $config = Proteus::read(config_path('app.php'));
   // Returns an array of the parsed config
   

3. Where to Look First

   • Documentation: Check the GitHub repo for examples.
   • Source Code: The package is lightweight (~100 lines). Review src/Proteus.php for core logic.
   • Laravel Config Structure: Understand Laravel’s native config() helper and config.php structure.
   • Laravel 13 Compatibility: Verify your Laravel 13 project by checking the Laravel 13 upgrade guide for any config system changes that may interact with Proteus.

Implementation Patterns

Core Workflows

1. Reading Config Files

$appConfig = Proteus::read(config_path('app.php'));
$customConfig = Proteus::read(base_path('config/custom.php'));

• Use Case: Dynamically load config files without require or include.
• Integration: Replace hardcoded require config_path('app.php'); in custom config loaders.
• Laravel 13 Note: Ensure your Laravel 13 project’s config structure aligns with Proteus’ expectations (e.g., return []; format).

2. Modifying Config

$config = Proteus::read(config_path('app.php'));
$config['debug'] = env('APP_DEBUG', false);
Proteus::write(config_path('app.php'), $config);

• Use Case: Update config values programmatically (e.g., during deployment or CLI tasks).
• Workflow:
  1. Read → Modify → Write.
  2. Validate changes with Proteus::validate() (if extended).
• Laravel 13 Note: If using Laravel’s new config() caching system, clear the cache post-write:

  Proteus::write($path, $config);
  config()->clear();
  

3. Merging Configs

$base = Proteus::read(config_path('app.php'));
$override = Proteus::read(config_path('app-override.php'));
$merged = array_replace_recursive($base, $override); // Prefer array_replace_recursive for deeper overrides
Proteus::write(config_path('app.php'), $merged);

• Use Case: Override settings dynamically (e.g., environment-specific configs).
• Laravel 13 Note: Leverage Laravel 13’s improved config() merging for consistency.

4. CLI/Artisan Integration

// In a custom Artisan command
public function handle() {
    $config = Proteus::read(config_path('app.php'));
    $config['timezone'] = 'America/New_York';
    Proteus::write(config_path('app.php'), $config);
    $this->info('Config updated!');
}

• Use Case: Runtime config adjustments via CLI.
• Laravel 13 Note: Use Laravel 13’s new Artisan::command() syntax if creating custom commands.

5. Environment-Aware Loading

$env = app()->environment();
$configPath = config_path("app-{$env}.php");
if (file_exists($configPath)) {
    $config = Proteus::read($configPath);
} else {
    $config = Proteus::read(config_path('app.php'));
}

• Use Case: Load environment-specific configs (e.g., app-local.php, app-production.php).
• Laravel 13 Note: Laravel 13’s .env system remains unchanged, so this pattern is still valid.

Integration Tips

With Laravel’s Config System

• Avoid Duplication: Use Proteus for non-standard config files (e.g., third-party or dynamic configs).
• Cache Awareness: Clear config cache after writing:

  Proteus::write($path, $config);
  config()->clear(); // Laravel 13+ method
  

• Laravel 13 Note: Laravel 13’s config caching is more robust. Test thoroughly after updates.

With Package Development

• Dynamic Configs: Let users override defaults via config/package-name.php:

  $defaults = Proteus::read(__DIR__.'/config.php');
  $userConfig = config_path('package-name.php');
  if (file_exists($userConfig)) {
      $defaults = array_replace_recursive($defaults, Proteus::read($userConfig));
  }
  

With Testing

• Isolated Configs: Load test-specific configs:

  $testConfig = Proteus::read(base_path("tests/config/test.php"));
  

• Laravel 13 Note: Use Laravel 13’s Testing facade for cleaner test setups:

  use Laravel\Lumen\Testing\TestCase;
  
  public function testConfig() {
      $this->app->instance('config', ['test' => true]);
  }
  

Gotchas and Tips

Pitfalls

1. File Permissions

   • Writing config files requires writable permissions on the target file.
   • Fix: Ensure storage/ or config/ has 755 permissions or use storage_path('app/config-custom.php').

2. Syntax Errors

   • Proteus::read() throws exceptions on invalid PHP syntax (unlike Laravel’s require).
   • Debug: Use Proteus::validate($config) (if implemented) or wrap in a try-catch.
   • Laravel 13 Note: Laravel 13’s stricter error handling may amplify syntax issues.

3. Recursive Merging Quirks

   • array_merge_recursive may not behave as expected with nested arrays.
   • Tip: Use array_replace_recursive for deeper overrides:

     $merged = array_replace_recursive($base, $override);
     

4. Caching Interactions

   • Writing configs does not auto-clear Laravel’s config cache.
   • Workaround: Call config()->clear() (Laravel 13+) or use Artisan::call('config:clear').

5. Non-Standard Config Files

   • Proteus assumes PHP files with return []; structure.
   • Fix: Pre-process non-standard files or extend the package.
   • Laravel 13 Note: Laravel 13 supports JSON/YAML configs natively. Use Proteus for custom formats.

6. Laravel 13 Breaking Changes

   • Config Caching: Laravel 13’s config caching is more aggressive. Ensure Proteus writes are followed by config()->clear().
   • Dependency Injection: If using Proteus in service providers, ensure compatibility with Laravel 13’s container changes.

Debugging Tips

1. Inspect Raw Config

   $raw = file_get_contents(config_path('app.php'));
   var_dump($raw); // Check for syntax issues
   

2. Validate Before Writing

   $config = Proteus::read($path);
   if (isset($config['invalid_key'])) {
       throw new \RuntimeException('Invalid config detected!');
   }
   

3. Log Changes

   $old = Proteus::read($path);
   Proteus::write($path, $new);
   \Log::info('Config updated', ['old' => $old, 'new' => $new]);
   

4. Laravel 13 Debugging

   • Use php artisan config:cache to test caching behavior.
   • Check Laravel’s logs for config-related errors:

     tail -f storage/logs/laravel.log
     

Extension Points

1. Custom Parsers

   • Extend Proteus to support non-PHP config files (e.g., JSON, YAML):

     class JsonProteus extends Proteus {
         public static function read(string $path) {
             return json_decode(file_get_contents($path), true);
         }
     }
     

   • Laravel 13 Note: Prefer Laravel’s native JSON/YAML support where possible.

2. Validation Rules

   • Add schema validation:

     use Stillat\Proteus\Contracts\Validatable;
     
     class ValidatedProteus implements Validatable {
         public function validate(array $config): bool {
             return isset($config['required_key']);
         }
     }
     

3. Event Dispatching

   • Trigger events on read/write: