README

一些设计决策

依赖解释

项目依赖于几个关键依赖

• PHP: ^8.3 - 与项目兼容的最新 PHP 版本。
• cuyz/valinor: ^1.12 - 从松散类型的源中方便地编写强类型 DTO。
• delolmo/valinor-console: ^1.7.1 - 允许使用控制台输入作为 cuyz/valinor 的源。
• doctrine/orm: ^3.2 - 库的对象关系映射器 (ORM)。
• giggsey/libphonenumber-for-php: ^8.13 - 用于在 Doctrine 嵌入式对象中验证电话号码。
• nikic/php-parser: ^4.19 - 用于解析某些库工具中的 PHP 文件。
• pragmarx/google2fa: ^8.0 - 用于生成 2FA 认证的密钥。
• psr/container: ^2.0 - 用于确保可重用性的基本 ContainerInterface 实现。
• ramsey/uuid: ^4.7 - 允许为实体创建 UUID 作为主键。
• ramsey/uuid-doctrine: ^2.1 - 添加 'uuid' 和 'uuid_binary' Doctrine 类型。
• simpod/doctrine-utcdatetime: ^0.3 - 将所有 DateTime 对象转换为 UTC 时区。
• symfony/cache: ^7.0 - 由 doctrine/orm 需要。
• symfony/console: ^7.0 - 用于管理命令行界面。
• webmozart/assert: ^1.11 - 在 Doctrine 嵌入式对象中执行基本断言。

实体

• 独立对象: 所有实体都是独立的对象，从实例化开始就是有效的。
• UUID 主键: 主键是 UUID，以确保一致性和性能。
• 单向关联: 不允许双向关联以增强性能。
• 唯一字段: 每个实体必须有一个唯一字段（除主键外）以方便查询。
• 日期/时间字段: 应始终为类型 \DateTimeImmutable 并转换为 UTC。这通过覆盖默认的 'datetime_immutable' 字段自动管理。
• 类和方法约束: 实体类不能为 final，但默认情况下，所有实体方法应该是 final 和 private，实体属性应该是 readonly。偏差必须由业务逻辑证明。

命令

• 数据传输对象 (DTO): 命令由处理器处理。所有命令应扩展 DelOlmoPro\Command\Command 并声明为 final 和 readonly。
• 实体传递: 如果通过查询传递实体，则命令对象应传递实体的一个主键。
• 属性: 控制台命令、参数和选项分别通过 Attribute\AsCommand、Attribute\AsArgument 和 Attribute\AsOption 注解类配置。CommandReader 能够读取这些属性并将这些信息配置为根控制台 Command。

处理器

• 单一职责: 处理器应仅执行一个功能并接受 __invoke 函数中的一个命令。
• 依赖: 处理器依赖应使用依赖注入加载。
• final 类: 处理器应声明为 final。

异常

• 根异常: 所有异常都继承自 DelOlmoPro\Exception\Exception，它扩展了 \Exception。
• 特殊异常: 定义了 EntityNotFound 和 EntityAlreadyExists 异常以供常见用途。
• 通用命令: 异常查询保持通用以确保库在保持数据完整性方面的作用。

依赖注入

这个库包含了一个非常简单的 Psr\Container\ContainerInterface 实现，用于管理依赖关系。基本上，服务通过 set 方法进行注册——就这样。

整个想法是不通过自定义的 Psr\Container\ContainerInterface 引导项目，而是允许将库集成到其他使用自己的依赖注入组件的项目中。

内部提供了一些实用类，以简化定义服务的任务。

• CommandLoader：从目录加载控制台命令并将其添加到 Symfony 控制台应用中。
• DescriptorLoader：从目录加载描述符并将其注册到依赖容器中。假设描述符没有依赖关系。
• DocumentLoader：不过是 DocumentManager 工厂，允许按命名空间添加多个实体路径，并为每个命名空间添加文档前缀。
• EntityLoader：不过是 EntityManager 工厂，允许按命名空间添加多个实体路径，并为每个命名空间添加表前缀。
• HandlerLoader：从目录加载查询处理器并将其注册到依赖容器中。处理器参数通过简单自动装配从容器中加载。

不幸的是，HandlerLoader 和 DescriptorLoader 类使用了特定的容器实现，因为它需要 set 方法。然而，当使用其他依赖注入库时，处理器和描述符可以很容易地进行自动装配。

然而，CommandLoader 更灵活。要将库的命令加载到自己的应用中

1. CommandLoader 从 Commands 中读取属性，以配置整个库的单点命令。

$reader = new CommandReader($container); // pass on the PSR-11 compliant container of your choosing
$reader->load('./src'); // specify the directory on which to look for Command objects

1. 确保符合 PSR-11 规范的容器包含每个处理器和描述符的定义。单点命令将尝试从容器中加载它们。
2. 使用详细程度修饰符（-vvv）检查命令执行流程。