# php-capsule

**Repository Path**: liuxiaojinla/php-capsule

## Basic Information

- **Project Name**: php-capsule
- **Description**: 快速开始你的应用开发。内置基础驱动管理器、服务等通用控件，开发你的多驱动类包吧。
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-05-07
- **Last Updated**: 2025-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 驱动, Service, 服务, driver

## README

# capsule

## 介绍

快速开始你的应用开发。内置基础驱动管理器、服务等通用控件，开发你的多驱动类包吧。

## 安装

```bash
composer require xin/capsule
```

## 使用说明

### 核心组件

本库提供了几个核心组件，帮助你快速构建多驱动应用：

#### 1. Manager 类 ([Manager.php](src/Manager.php))

用于管理多种驱动的抽象基类，支持动态驱动创建和管理。

- **功能特性**：
  - 支持多驱动管理
  - 可自定义驱动创建器
  - 支持默认驱动设置
  - 提供配置管理功能

- **核心常量**：
  - `DEFAULT_DRIVER_KEY` - 默认驱动键名，值为 `'driver'`
  - `DEFAULT_DRIVER_VALUE` - 默认驱动类型的默认值，值为 `'default'`
  - `DRIVER_CONFIG_KEY` - 驱动列表的配置键名，值为 `'drivers'`

- **基本用法**：
  ```php
  use Xin\Capsule\Manager;
  
  class DriverManager extends Manager
  {
      protected function createCustomDriver($name, array $config)
      {
          return new CustomDriver($config);
      }
  }
  
  $manager = new DriverManager($config);
  $driver = $manager->driver('custom');
  ```

- **常量使用示例**：
  ```php
  use Xin\Capsule\Manager;
  
  class StorageManager extends Manager
  {
      // 可以重写常量来自定义配置结构
      public const DEFAULT_DRIVER_KEY = 'type'; // 自定义默认驱动键名
      public const DEFAULT_DRIVER_VALUE = 'local'; // 自定义默认驱动值
      public const DRIVER_CONFIG_KEY = 'storages'; // 自定义驱动配置键名
      
      protected function createLocalDriver($name, array $config)
      {
          return new LocalStorageDriver($config);
      }
      
      protected function createCloudDriver($name, array $config)
      {
          return new CloudStorageDriver($config);
      }
  }
  
  // 配置结构将根据重写的常量变化
  $config = [
      'storages' => [ // 使用重写的 [DRIVER_CONFIG_KEY](src/Manager.php#L35-L35)
          'local' => [
              'type' => 'local', // 使用重写的 [DEFAULT_DRIVER_KEY](src/Manager.php#L25-L25)
              'path' => '/storage'
          ],
          'cloud' => [
              'type' => 'cloud',
              'bucket' => 'my-bucket'
          ]
      ],
      'defaults' => [
          'type' => 'local' // 使用重写的 [DEFAULT_DRIVER_KEY](src/Manager.php#L25-L25)
      ]
  ];
  
  $storageManager = new StorageManager($config);
  $defaultDriver = $storageManager->driver(); // 获取默认驱动
  $localDriver = $storageManager->driver('local');
  $cloudDriver = $storageManager->driver('cloud');
  ```

- **主要方法**：
  - `driver($name)` - 获取指定驱动
  - `getDefaultDriver()` - 获取默认驱动
  - `setDefaultDriver($name)` - 设置默认驱动
  - `extend($driver, \Closure $callback)` - 扩展自定义驱动
  - `getDrivers()` - 获取所有驱动
  - `forgetDrivers()` - 清除所有已解析的驱动实例
  - `getDriverConfig($name)` - 获取驱动配置

- **驱动创建机制**：
  - 首先检查是否存在自定义创建器
  - 然后尝试调用 `create{DriverName}Driver` 方法
  - 最后尝试调用 `createDefaultDriver` 方法

- **配置结构**：
  ```php
  $config = [
      'drivers' => [
          'driver_name' => [
              'driver' => 'driver_type', // 驱动类型
              // 其他驱动配置项
          ]
      ],
      'defaults' => [
          'driver' => 'default_driver_name' // 默认驱动
      ]
  ];
  ```

- **魔术方法调用**：
  - 当调用不存在的方法时，会自动转发到默认驱动实例
  - 例如：`$manager->someMethod()` 等同于 `$manager->driver()->someMethod()`

#### 2. Service 类 ([Service.php](src/Service.php))

提供单例模式的服务基类，用于构建单例服务。

- **功能特性**：
  - 单例模式实现
  - 配置管理
  - 宏扩展支持

- **基本用法**：
  ```php
  use Xin\Capsule\Service;
  
  class MyService extends Service
  {
      public static function makeInstance()
      {
          return new static(self::getConfig());
      }
  }
  
  $service = MyService::getInstance();
  ```

- **Service 常用方法**：
  - `getInstance()` - 获取单例实例
  - `makeInstance()` - 生成新实例（需重写）
  - `getConfig()` - 获取配置
  - `setConfig()` - 设置配置

#### 3. Trait 功能组件

##### WithConfig ([WithConfig.php](src/WithConfig.php))
提供配置管理功能，支持配置的获取、设置和检查。

- **使用方法**：
  ```php
  use Xin\Capsule\WithConfig;
  
  class MyClass
  {
      use WithConfig;
      
      protected $config = [
          'database' => [
              'host' => 'localhost',
              'port' => 3306,
          ],
          'cache' => [
              'ttl' => 3600,
          ]
      ];
  }
  
  $obj = new MyClass();
  $host = $obj->getConfig('database.host', 'default'); // 获取配置值，结果为 'localhost'
  $port = $obj->getConfig('database.port'); // 获取配置值，结果为 3306
  $allConfig = $obj->getConfig(); // 获取所有配置
  $exists = $obj->hasConfig('database.host'); // 检查配置是否存在，结果为 true
  $notExists = $obj->hasConfig('database.user'); // 检查配置是否存在，结果为 false
  
  // 设置配置
  $obj->setConfig('database.host', '127.0.0.1'); // 更新单个配置项
  $obj->setConfig(['database' => ['user' => 'root']]); // 批量设置配置
  $obj->setConfig('cache.ttl', 7200); // 设置嵌套配置
  ```

- **主要方法**：
  - `getConfig($key, $default)` - 获取配置值，支持点号分隔的嵌套键
  - `setConfig($key, $value)` - 设置配置值，支持点号分隔的嵌套键或批量设置
  - `hasConfig($key)` - 检查配置是否存在

##### WithContainer ([WithContainer.php](src/WithContainer.php))
提供容器支持，支持依赖注入和实例创建。

- **使用方法**：
  ```php
  use Xin\Capsule\WithContainer;
  use Psr\Container\ContainerInterface;
  
  class MyClass
  {
      use WithContainer;
  }
  
  $obj = new MyClass();
  
  // 假设有一个 PSR-11 兼容的容器
  $container = new SomeContainer(); // 实现 ContainerInterface
  $obj->setContainer($container);
  
  // 获取容器实例
  $retrievedContainer = $obj->getContainer();
  
  // 创建类实例
  $instance = $obj->makeClassInstance('SomeClass', ['arg1', 'arg2']); // 使用容器的 make 方法
  $instance2 = $obj->makeClassInstance('SomeClassWithMake'); // 如果类有 __make 静态方法
  $instance3 = $obj->makeClassInstance('RegisteredService'); // 使用容器的 get 方法
  ```

- **主要方法**：
  - `getContainer()` - 获取容器实例
  - `setContainer($container)` - 设置容器实例
  - `makeClassInstance($abstract, $args)` - 创建类实例，优先尝试容器的 make 方法，然后是类的 __make 方法，最后是容器的 get 方法

##### WithCache ([WithCache.php](src/WithCache.php))
提供缓存功能支持。

- **使用方法**：
  ```php
  use Xin\Capsule\WithCache;
  use Psr\SimpleCache\CacheInterface;
  
  class MyClass
  {
      use WithCache;
  }
  
  // 设置默认缓存解析器（通常在应用启动时设置一次）
  MyClass::setDefaultCacheResolver(function() {
      return new SomeCache(); // 返回实现 CacheInterface 的缓存实例
  });
  
  $obj = new MyClass();
  
  // 获取缓存实例
  $cache = $obj->cache(); // 会使用默认缓存解析器创建缓存实例
  $value = $cache->get('key'); // 使用缓存
  $cache->set('key', 'value', 3600); // 设置缓存
  
  // 设置自定义缓存实例
  $customCache = new AnotherCache(); // 实现 CacheInterface
  $obj->setCache($customCache);
  $customCacheInstance = $obj->cache(); // 现在返回的是自定义缓存实例
  ```

- **主要方法**：
  - `cache()` - 获取缓存实例，如果没有设置则使用默认缓存解析器创建
  - `setCache($cache)` - 设置缓存实例
  - `setDefaultCacheResolver($resolver)` - 设置默认缓存解析器，这是一个静态方法，为所有类实例设置默认解析器

### 实际应用示例

```php
// 创建一个数据库驱动管理器
class DatabaseManager extends Xin\Capsule\Manager
{
    protected function createMysqlDriver($name, array $config)
    {
        return new MysqlDriver($config);
    }
    
    protected function createPostgresqlDriver($name, array $config)
    {
        return new PostgresqlDriver($config);
    }
}

// 配置
$config = [
    'drivers' => [
        'mysql' => [
            'driver' => 'mysql',
            'host' => 'localhost',
            'database' => 'test'
        ],
        'postgresql' => [
            'driver' => 'postgresql',
            'host' => 'localhost',
            'database' => 'test'
        ]
    ],
    'defaults' => [
        'driver' => 'mysql'
    ]
];

$manager = new DatabaseManager($config);
$mysqlDriver = $manager->driver('mysql');
$defaultDriver = $manager->driver(); // 使用默认驱动
```

### 扩展 Manager 功能

- **使用 extend 方法**：
  ```php
  $manager->extend('custom', function($name, $config) {
      return new CustomDriver($config);
  });
  ```

- **重写默认驱动**：
  ```php
  protected function createDefaultDriver($name, $config)
  {
      return new DefaultDriver($config);
  }
  ```

## 扩展功能

- **宏支持**：所有核心类都支持宏扩展，可以通过 `macro` 方法添加自定义功能
- **链式调用**：支持链式调用风格的 API
- **配置驱动**：通过配置灵活切换不同驱动实现

## 适用场景

- 多数据库驱动管理
- 多存储驱动（文件、云存储等）
- 多支付网关管理
- 多消息队列管理
- 其他需要多驱动支持的场景

这个库提供了一个灵活的基础架构，帮助开发者快速构建支持多种实现的组件系统。