README

关于
配置
绑定点
执行
- 初始化
- 处理
安装
单元测试
参考指南
规范

关于

此API是一个骨架（需要开发者进行绑定），用于高效处理使用MVC范式方言的Web应用程序中的错误或未捕获异常

模型是可重用的逻辑，用于报告处理过的 \Throwable 实例或包含要发送到视图的数据的持有者
视图是处理错误/异常后发送给调用者的响应
控制器 将 \Throwable 实例绑定到模型，以便配置视图（通常是向其发送数据）

正如MVC API处理STDOUT中的HTTP请求到响应一样，此API处理STDERR中的错误或未捕获异常，这些异常发生在处理过程中。它以既高效又模块化的方式执行，不捆绑到任何框架中

首先，MVC API for STDERR（此API）将自己注册为封装在 \Throwable 实例中的错误和未捕获异常的唯一处理程序，然后被动等待触发
然后，MVC API for STDOUT（您选择的框架）开始处理用户请求到响应。在这个过程中是否发生了错误或未捕获的异常？
- 是：MVC API for STDERR自动唤醒并开始处理相应的 \Throwable 到响应
- 否：响应返回给调用者

此外，整个过程通过以下组合实现了灵活性：

配置：设置一个XML文件，其中配置此API
绑定点：将XML/代码中定义的用户自定义组件绑定到API原型，以获得必要的功能
初始化：实例化 FrontController 以将其注册为唯一的 \Throwable 处理程序
处理：一旦在STDOUT阶段发生任何错误或未捕获的异常，上述 handle 方法将自动调用，启动 \Throwable-response过程

API完全符合PSR-4规范，仅需抽象MVC API进行基本MVC逻辑处理，PHP7.1+解释器和SimpleXML扩展。要快速了解其工作原理，请查看

安装：描述了如何在您的计算机上安装API，基于上述步骤
单元测试：API具有100%的单元测试覆盖率，使用UnitTest API代替PHPUnit以获得更大的灵活性
示例：根据FrontController单元测试展示了API功能的一个深入示例
参考指南：描述了所有与开发者相关的API类、方法和字段

内部所有类都属于Lucinda\STDERR命名空间！

配置

要配置此API，您必须有一个包含以下标签的XML文件

应用：（必选）在一般应用基础上配置处理
显示错误：（可选）配置是否显示错误
报告器：（可选）配置应用程序如何报告已处理的错误/异常
解析器：（必选）配置应用程序能够解析响应到已处理错误/异常的格式
路由：（必选）配置基于错误/异常的路由到控制器/视图

应用程序

标签文档完全由继承的抽象MVC API 规范涵盖！由于此API的STDIN由已处理的可抛出对象组成，但没有任何通用的可抛出值，因此default_route属性的默认值必须是default。

显示错误

此标签的最大语法是

<display_errors>
    <{ENVIRONMENT}>{VALUE}</{ENVIRONMENT}>
    ...
</display_errors>

大多数标签逻辑已由抽象MVC API 规范涵盖。以下额外子标签/属性已定义

display_errors：（可选）根据以下内容决定是否将已处理的错误/异常详情暴露给调用者
- {ENVIRONMENT}：开发环境的名称（将被替换为“local”、“dev”、“live”等）。{VALUE}可以是
  - 1：表示错误/异常详情将显示给调用者
  - 0：表示错误/异常详情不会显示给调用者

如果没有定义display_errors或没有找到匹配当前开发环境的{ENVIRONMENT}子标签，则假定值为0（\Throwable详情不会被暴露）！

标签示例

<display_errors>
    <local>1</local>
    <live>0</live>
</display_errors>

报告器

此标签的最大语法是

<reporters>
    <{ENVIRONMENT}>
        <reporter class="..." {OPTIONS}/>
        ...
    </{ENVIRONMENT}>
    ...
</reporters>

位置

reporters：（必选）包含配置应用程序进行错误报告的设置的集合
- {ENVIRONMENT}：（必选）开发环境的名称（将被替换为“local”、“dev”、“live”等）。包含一个或多个报告器，每个报告器由一个标签定义
  - reporter：（必选）根据属性配置错误/异常报告器
    - class：（必选）用户定义的PS-4自动加载兼容类的名称（包括命名空间），该类将报告\Throwable。
      类必须是报告器实例！
    - {OPTIONS}：配置上述class所标识相应报告器所需的额外属性列表

标签示例

<reporters>
    <local>
        <reporter class="Lucinda\Project\Reporters\File" path="errors" format="%d %f %l %m"/>
    </local>
    <live>
        <reporter class="Lucinda\Project\Reporters\SysLog" application="unittest" format="%v %f %l %m"/>
    </live>
</reporters>

解析器

标签文档完全由继承的抽象MVC API 规范覆盖！

路由

此标签的最大语法是

<routes>
    <route id="..." controller="..." view="..." error_type="..." http_status="..."/>
    ...
</routes>

大多数标签逻辑已经由抽象MVC API 规范覆盖。以下额外的观察需要注意

id：（必填）映射错误/异常类名称或默认（匹配 default_route @ application 标签）。
类必须是 \Throwable 实例！
controller：（可选）用户定义的PS-4自动加载兼容类（包括命名空间）的名称，该类将基于模型缓解请求和响应。
类必须是 Controller 实例！
error_type：（必填）定义默认异常/错误发起者。必须匹配 ErrorType 枚举案例值！例如："LOGICAL"。
http_status：（必填）定义默认响应HTTP状态。必须是有效的HTTP状态代码！例如："500"。

标签示例

<routes>
    <route id="default" http_status="500" error_type="LOGICAL" view="500"/>
    <route id="Lucinda\MVC\STDOUT\PathNotFoundException" controller="Lucinda\Project\Controllers\PathNotFound" http_status="404" error_type="CLIENT" view="404"/>
</routes>

如果处理的 \Throwable 不匹配任何路由，将使用默认路由！

绑定点

为了保持灵活并实现最高性能，API 不做任何绝对必要的假设！相反，它为开发者提供了一种绑定到其原型以获得一定功能的能力。

声明性绑定

它为开发者提供了通过 XML 声明性 绑定到其原型类/接口的能力

程序性绑定

它为开发者提供了通过 FrontController 构造函数 程序性 绑定到其原型的能力

执行

初始化

现在开发者已经完成设置配置API的XML，他们最终可以通过实例化 FrontController 来初始化它。

作为 \Throwable 实例的处理者，上述需要实现 ErrorHandler。除了上述接口所需的 run 方法外，FrontController 还提供了以下公共方法，所有这些都与初始化过程相关

位置

$documentDescriptor：XML 配置文件的相对位置。例如："configuration.xml"。
$developmentEnvironment：要用于决定如何报告或是否暴露处理过的 \Throwable 的开发环境名称（将被替换为 "local"、"dev"、"live" 等）。
$includePath：项目根目录的绝对位置（因为有时在抛出错误时，包含路径会丢失）。例如：DIR。
$emergencyHandler：在 FrontController 的 handle 方法执行期间处理错误时使用的 ErrorHandler 实例。
$displayFormat：显示格式的值，与 resolvers XML 标签的 format 属性相匹配。

非常重要的一点是，一旦注册了处理程序，API 就会使用面向切面编程的概念来异步监听错误事件，然后自动触发处理程序。因此，一旦初始化了API，就可以立即开始处理http请求到响应的框架！

处理

一旦在STDOUT请求响应阶段发生<\Throwable>事件，将调用FrontController的handle方法。这

将构造函数参数中提供的处理器注册为捕获处理过程中可能发生的任何错误
根据配置了API和开发环境的XML构建Application对象
检测匹配已处理的<\Throwable>的Application\Route
根据处理的<\Throwable>和上述Application\Route构建Request对象
根据与开发环境匹配的XML中的reporters标签构建Reporter实例列表
如果找到，则为每个Reporter调用其run()方法以将<\Throwable>报告给相应的介质
检测匹配application标签中default_format属性的Lucinda\MVC\Application\Format或通过setDisplayFormat方法手动设置的格式
根据上述检测到的所有对象构建\Lucinda\MVC\Response对象
根据XML中routes标签的id属性检测匹配<\Throwable>处理的Controller或如果无路由匹配，则默认为default
如果找到，则执行Controller的run方法以操作响应
如果\Lucinda\MVC\Response还没有体
- 根据与XML中匹配的resolver标签以及上述检测到的对象构建\Lucinda\MVC\ViewResolver对象。例如，这将把模板转换为完整的响应体。
- 如果没有找到，程序将带错误退出，否则它将执行\Lucinda\MVC\ViewResolver的run方法以将视图转换为响应体
调用\Lucinda\MVC\Response的commit方法将响应发送给调用者

所有由开发者负责的组件（Controller，\Lucinda\MVC\ViewResolver，Reporter）实现\Lucinda\MVC\Runnable接口。

安装

首先选择一个文件夹，然后在控制台中在该文件夹中写入此命令

composer require lucinda/errors-api

然后在项目根目录中创建一个包含配置设置的configuration.xml文件（见上文的配置）和一个包含以下代码的index.php文件（见上文的初始化）

// detects current development environment from ENVIRONMENT environment variable (eg: set in .htaccess via "SetEnv ENVIRONMENT local");
define("ENVIRONMENT", getenv("ENVIRONMENT"));

// starts API as error handler to listen for errors/exceptions thrown in STDOUT phase below
new FrontController("configuration.xml", getenv("ENVIRONMENT"), __DIR__, new EmergencyHandler());

// runs preferred STDOUT framework (eg: STDOUT MVC API) to handle requests into responses

紧急处理器的示例

class EmergencyHandler implements \ErrorHandler
{
    public function handle($exception): void
    {
        var_dump($exception);
        die();
    }
}

单元测试

有关测试和示例，请检查API源代码中的以下文件/文件夹

test.php：在控制台中运行单元测试
unit-tests.xml：设置单元测试并模拟 "loggers" 标签
tests：来自 src 文件夹的类的单元测试

参考指南

这些类由API完全实现

Application：读取 configuration XML文件并封装信息
- Application\Route：封装与 route XML标签匹配的 \Throwable 处理
Request：封装处理的 \Throwable 和 Application\Route

这些抽象类需要由开发者扩展以获得能力

Reporter：封装 \Throwable 报告
Controller：根据 \Throwable 封装绑定 Request 到 \Lucinda\MVC\Response

Application 类

Application 类继承自 Lucinda\MVC\Application 并添加了一个针对开发者的相关方法

Application\Route 类

Application\Route 类继承自 Lucinda\MVC\Application\Route 并添加了以下公共方法

Request 类

Request 类封装了处理的 \Throwable 和匹配的 Application\Route。它定义了以下针对开发者的公共方法

ErrorHandler 接口

ErrorHandler 接口包含通过方法处理 \Throwable 的蓝图

使用示例

https://github.com/aherne/lucinda-framework/blob/master/src/EmergencyHandler.php

Reporter 抽象类

Reporter 抽象类实现了 \Lucinda\MVC\Runnable 并封装了一个单独的 \Throwable 报告器。它定义了以下针对开发者的公共方法

开发者需要为每个报告器实现 run 方法，其中他们可以访问通过构造函数注入的以下受保护的字段

使用示例

https://github.com/aherne/lucinda-framework-engine/blob/master/src/AbstractReporter.php https://github.com/aherne/lucinda-framework/blob/master/src/Reporters/File.php

有关如何检测报告器的更多信息，请查看下面的如何定位报告器部分！

抽象类控制器

抽象类 Controller 实现 \Lucinda\MVC\Runnable) 以根据先前检测到的信息设置响应（特别是视图）。它定义了以下与开发者相关的公共方法

开发者需要为每个控制器实现 run 方法，其中他们可以访问通过构造函数注入的以下受保护的字段

使用示例

https://github.com/aherne/lucinda-framework/blob/master/src/Controllers/SecurityPacket.php

有关如何检测控制器的更多信息，请查看下面的如何定位控制器部分！

规范

由于此API在抽象MVC API规范之上运行，它遵循其要求，并添加了额外的要求

如何检测响应格式
如何定位视图解析器
如何检测路由
如何定位控制器
如何定位报告器
如何定位视图

如何检测响应格式

这遵循父API 规范，只是根据处理的 \Throwable 来检测路由。一个区别是，可以使用 setDisplayFormat 方法（请参阅初始化）覆盖检测到的值。

如何定位视图解析器

这完全遵循父API 规范。

如何检测路由

这遵循父API 规范，只是根据处理的 \Throwable 来检测路由。以下是一个XML示例

<application default_route="default" ...>
	...
</application>
<routes>
    <route id="default" .../>
    <route id="\Bar\Exception" .../>
    ...
</routes>

对于上述内容将有以下情况

如何定位控制器

这遵循父API 规范，只是将 route 标签中的 controller 属性定义的类必须扩展 Controller。

如何定位报告器

为了更好地理解 class 属性在 reporter 标签中如何与 开发环境 匹配，以下是一个XML示例

<reporters>
    <ENVIRONMENT1>
        <reporter class="Lucinda\Project\Reporters\File" .../>
        <reporter class="Lucinda\Project\Reporters\SysLog" .../>
    </ENVIRONMENT1>
    <ENVIRONMENT2>
        <reporter class="Lucinda\Project\Reporters\SysLog" .../>
    </ENVIRONMENT2>
    ...
</reporters>

在这种情况下，如果 composer.json 中的 "psr-4" 属性将 "Lucinda\Project" 与 "src/" 文件夹相关联，则

上述所有引用的类必须是 Reporter 的实例！

如何定位视图

这完全遵循父API 规范。扩展尚未确定，因为它取决于解析视图的类型！

lucinda / errors-mvc

维护者

详细信息

README

关于

配置

应用程序

显示错误

报告器

解析器

路由

绑定点

声明性绑定

程序性绑定

执行

初始化

处理

安装

单元测试

参考指南

Application 类

Application\Route 类

Request 类

ErrorHandler 接口

Reporter 抽象类

抽象类控制器

规范

如何检测响应格式

如何定位视图解析器

如何检测路由

如何定位控制器

如何定位报告器

如何定位视图