v0.7.0: Type-Safe Adapter Configuration

🚨 Breaking Changes

This release introduces breaking changes to the adapter factory interface to provide better type safety and developer experience.

Updated Interfaces

AdapterFactoryInterface:

// OLD v0.6.2:
public function createAdapter(array $config): PersistenceAdapterInterface

// NEW v0.7.0:
public function createAdapter(AdapterConfiguration $config): PersistenceAdapterInterface

AdapterRegistry:

// OLD v0.6.2:
AdapterRegistry::create(string $type, array $config)

// NEW v0.7.0:
AdapterRegistry::create(string $type, AdapterConfiguration $config)

Method Renames

• getInstance() → getInstanceConfig() (clearer intent)
• getGlobal() → getGlobalSettings() (more descriptive)

✨ New Features

AdapterConfiguration Class

• Type-safe configuration object with immutable design
• Convenience methods with default value support:
  • getInstanceValue(string $key, mixed $default = null)
  • getGlobalValue(string $key, mixed $default = null)
• Constructor validation ensures valid types
• Better IntelliSense support for IDE users

Example Usage

// Create configuration
$config = new AdapterConfiguration(
    instance: ['adapter' => 'redis', 'host' => 'localhost'],
    global: ['debug' => true],
    container: $container
);

// Use in adapter factory
public function createAdapter(AdapterConfiguration $config): PersistenceAdapterInterface
{
    $container = $config->getContainer();
    $host = $config->getInstanceValue('host', 'localhost');
    $debug = $config->getGlobalValue('debug', false);
    
    return new MyAdapter($container->get('client'), ['host' => $host]);
}

🔧 Migration Guide

For Third-Party Adapter Developers

Required Changes:

1. Update factory method signature to accept AdapterConfiguration
2. Replace array access with getter methods:
   • $config['container'] → $config->getContainer()
   • $config['instance'] → $config->getInstanceConfig()
   • $config['global'] → $config->getGlobalSettings()
3. Use convenience methods for safer access:
   • $config->getInstanceValue('key', 'default')
   • $config->getGlobalValue('key', 'default')

Migration Example:

// OLD v0.6.2 implementation:
public function createAdapter(array $config): PersistenceAdapterInterface
{
    $container = $config['container'];
    $instanceConfig = $config['instance'];
    $globalConfig = $config['global'];
    
    $client = $container->get($instanceConfig['my_client']);
    return new MyAdapter($client, $instanceConfig);
}

// NEW v0.7.0 implementation:
public function createAdapter(AdapterConfiguration $config): PersistenceAdapterInterface
{
    $container = $config->getContainer();
    $instanceConfig = $config->getInstanceConfig();
    $globalSettings = $config->getGlobalSettings();
    
    // Use convenience methods with defaults
    $client = $container->get($config->getInstanceValue('my_client', 'default.client'));
    return new MyAdapter($client, $instanceConfig);
}

For End Users

No changes required! The EdgeBinder::fromConfiguration() API remains unchanged. The improvements are internal to the adapter system.

🎯 Benefits

1. Type Safety - Strong typing prevents configuration errors at compile time
2. Better Developer Experience - IntelliSense support and clearer method names
3. Immutability - Configuration cannot be accidentally modified
4. Performance - No array-to-object conversion overhead
5. Maintainability - Cleaner, more consistent API

📊 Quality Assurance

• ✅ All 270 tests passing
• ✅ PHPStan Level 8 clean (no errors)
• ✅ Complete documentation updates
• ✅ All examples updated to new API

🔗 Resources

• Migration Guide
• Extensible Adapters Guide
• Complete Changelog

---

Full Changelog: v0.6.2...v0.7.0