README

一个轻量级的PHP框架，提供一种强大而灵活的方式来管理服务、单例、绑定和服务提供者，支持依赖注入和解析。

概览

Argon框架旨在通过提供轻量级和模块化的结构来简化PHP应用程序的开发。它提供以下功能：

• 服务注册：注册服务和单例。
• 依赖注入：通过构造函数注入自动注入依赖。
• 服务提供者：模块化服务注册和引导。
• 绑定：将接口绑定到具体实现。
• 钩子：自定义行为的解析前和解析后钩子。
• 内核管理：抽象内核用于应用程序引导和错误处理。
• 错误处理：集中处理错误和异常。
• CLI应用程序支持：轻松构建命令行应用程序。
• 门面：通过静态接口简化对容器服务的访问。

需求

• PHP >= 8.2

安装

通过Composer安装

composer require maduser/argon

入门指南

创建容器

use Maduser\Argon\Container\ServiceContainer;

$container = new ServiceContainer();

注册服务

注册服务

$container->register('serviceAlias', SomeClass::class);

注册多个服务

$container->register([
    'serviceAlias1' => SomeClass::class,
    'serviceAlias2' => AnotherClass::class,
]);

注册单例

$container->singleton('singletonAlias', SomeSingletonClass::class);

绑定接口

将接口绑定到具体实现

$container->bind(InterfaceName::class, ConcreteClass::class);

或将多个接口绑定

$container->bind([
    InterfaceOne::class => ConcreteOne::class,
    InterfaceTwo::class => ConcreteTwo::class,
]);

解析服务

$service = $container->resolve('serviceAlias');

依赖注入

在解析服务时，通过构造函数注入自动注入依赖。

class SomeClass {
    public function __construct(DependencyClass $dependency) {
        // ...
    }
}

$instance = $container->resolve(SomeClass::class);

使用服务提供者

通过扩展ServiceProvider创建服务提供者

use Maduser\Argon\Container\ServiceProvider;

class MyServiceProvider extends ServiceProvider {
    public function register() {
        $this->container->register('myService', MyService::class);
    }

    public function resolve() {
        return $this->container->resolve('myService');
    }
}

注册服务提供者

$container->register('myServiceProvider', MyServiceProvider::class);

使用钩子

添加解析前和解析后钩子

// Pre-resolution hook
$container->addPreResolutionHook(SomeInterface::class, function($descriptor, $params) {
    // Custom logic before resolution
});

// Post-resolution hook
$container->addPostResolutionHook(SomeInterface::class, function($instance, $descriptor) {
    // Custom logic after resolution
    return $instance;
});

自动解析未注册的类

默认情况下，容器可以自动解析未显式注册的类

$container->setAutoResolveUnregistered(true);

$instance = $container->resolveOrMake(UnregisteredClass::class);

示例用法

以下是一个示例，演示如何使用Argon框架来管理服务、单例、服务提供者和钩子。

<?php

namespace App;

use Maduser\Argon\Container\ServiceContainer;
use Maduser\Argon\Container\ServiceProvider;
use Maduser\Argon\Hooks\HookServiceProviderPostResolution;
use Maduser\Argon\Hooks\HookServiceProviderSetter;
use Maduser\Argon\Hooks\HookRequestValidationPostResolution;

require_once 'vendor/autoload.php';

// Create a new ServiceContainer instance
$container = new ServiceContainer();

// Add hooks to the container
$container->addSetterHook(ServiceProvider::class, new HookServiceProviderSetter($container));
$container->addPostResolutionHook(RequestValidation::class, new HookRequestValidationPostResolution($container));
$container->addPostResolutionHook(ServiceProvider::class, new HookServiceProviderPostResolution($container));

// Define classes
class SingletonObject
{
    public int $value = 0;

    public function __construct() {}
}

class SomeObject
{
    public SingletonObject $singletonObject;

    public function __construct(SingletonObject $singletonObject)
    {
        $this->singletonObject = $singletonObject;
    }
}

class RequestValidation {
    public function validate()
    {
        // Validation logic here
    }
}

class SaveUserRequest extends RequestValidation
{
    public function __construct()
    {
        // Initialization logic here
    }
}

class UserController
{
    private SaveUserRequest $request;
    private string $someValue = 'Hello';

    public function __construct(SaveUserRequest $request)
    {
        $this->request = $request;
    }

    public function action()
    {
        // Controller action logic here
        return $this->request;
    }

    public function setSomeValue(string $value): void
    {
        $this->someValue = $value;
    }

    public function getSomeValue(): string
    {
        return $this->someValue;
    }
}

class UserControllerServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Registration logic here
    }

    public function resolve(): mixed
    {
        return $this->container->make(UserController::class);
    }
}

// Register the UserController as a singleton using a ServiceProvider
$container->singleton('UserController', UserControllerServiceProvider::class);

// Resolve the UserController from the container
$userController = $container->resolve('UserController');
$userController->setSomeValue('Hello World');
$userController->action();

// Resolve the UserController again to demonstrate singleton behavior
$userController2 = $container->resolve('UserController');
echo $userController2->getSomeValue(); // Outputs: Hello World

// Demonstrate singleton object sharing
$container->singleton(SingletonObject::class);
$container->register('some-object', SomeObject::class);

$obj1 = $container->resolve('some-object');
$obj1->singletonObject->value = 10;

$obj2 = $container->resolve('some-object');
echo $obj2->singletonObject->value; // Outputs: 10

说明

• 服务容器初始化：创建一个新的服务容器来管理服务。
• 添加钩子：添加钩子来处理服务提供者和请求验证后的操作。
• 定义类：定义了各种类，包括SingletonObject、SomeObject和UserController。
• 服务提供者使用：创建了一个UserControllerServiceProvider来管理UserController的注册和解析。
• 注册服务：将UserController注册为单例，将SomeObject正常注册。
• 解析服务：从容器中解析服务，演示单例行为和依赖注入。

构建CLI应用程序

Argon框架包括通过CliApp类构建命令行应用程序的支持。

创建CLI应用程序

use Maduser\Argon\Container\ServiceContainer;
use Maduser\Argon\Kernel\EnvApp\CliApp;

$container = new ServiceContainer();
$cliApp = new CliApp($container);

// Boot the kernel (register services, providers, etc.)
$cliApp->bootKernel();

// Handle the CLI application
$cliApp->handle();

定义命令

可以使用来自maduser/console包的CommandManager和Console类来管理命令。

1. 安装Console包:

   composer require maduser/console

2. 注册Console和CommandManager:

   如果存在，CliApp类将自动注册Console和CommandManager。

3. 创建命令:

   use Maduser\Console\Command;
   
   class MyCommand extends Command {
       public function execute() {
           $this->console->writeLine('Hello from MyCommand!');
       }
   }

4. 注册命令:

   $commandManager = $container->resolve('CommandManager');
   $commandManager->register('mycommand', MyCommand::class);

5. 运行CLI应用程序:

   $cliApp->handle();

   现在您可以通过命令行执行您的命令

   php script.php mycommand

使用门面

Argon 框架提供了门面，通过静态接口简化对容器服务的访问。

使用 Container 门面

Container 门面提供了静态方法与服务容器进行交互。

use Maduser\Argon\Container;

// Register a service
Container::register('serviceAlias', SomeClass::class);

// Resolve a service
$service = Container::resolve('serviceAlias');

// Create an instance without registering
$instance = Container::make(SomeClass::class);

使用 App 门面

App 门面扩展了 Container 门面，并提供初始化和运行应用程序的方法。

use Maduser\Argon\App;

// Initialize the application
App::init();

// Run the application
App::run();

// Or chain the methods
App::init()->run();

在隔离上下文中分发回调

App::dispatch(function() {
    // Your callback logic here
});

访问 Kernel

$kernel = App::getKernel();

开发

需求

• PHP >= 8.2

开发安装

克隆仓库并安装依赖

git clone https://github.com/yourusername/argon-framework.git
cd argon-framework
composer install

运行测试

该框架使用 PHPUnit 进行单元测试。要运行测试

composer test

静态分析

使用 Psalm 进行静态代码分析。要检查错误

composer check

代码风格

使用 PHP_CodeSniffer 确保代码风格一致性。要自动修复代码风格问题

composer fix

监视更改

您可以监视文件更改并自动运行测试或检查

• 监视和测试:

  composer watch-test

• 监视和修复:

  composer watch-fix

脚本

composer.json 包含了几个有用的脚本

• 测试：运行 PHPUnit 测试。

  composer test

• 检查：运行测试、Psalm 静态分析和 PHP_CodeSniffer。

  composer check

• 修复：尝试自动修复 Psalm 和 PHP_CodeSniffer 发现的问题。

  composer fix

贡献

欢迎贡献！请遵循以下指南

1. Fork 仓库：点击仓库页面右上角的“Fork”按钮。

2. 创建新分支：为每个功能或错误修复创建新分支是一个好习惯。

   git checkout -b feature/my-new-feature

3. 编写测试：确保您的代码更改由单元测试覆盖。

4. 运行检查：在提交之前，确保所有检查都通过。

   composer check

5. 提交拉取请求：一旦您的更改准备就绪，提交拉取请求进行审查。

许可

本项目使用 MIT 许可证授权。

作者

• Julien Duseyau