README

Payload 是域层和应用层之间的数据传输对象。其理念是，对于你在域服务/访问层（域 API）上调用的每个方法，你将收到一个 Payload 实例作为响应。

安装

通过 Composer

$ composer require joebengalen/payload

用法

获取与命令方法

域访问层中有两种类型的方法：首先，你有 获取 方法，它们 请求 数据。其次，你有 命令 方法，它们告诉域执行某个操作。Payload 状态将告诉你方法是否成功。除了状态外，Payload 还可能包含其他信息，例如请求的数据或发生错误时的异常。

Payload 状态

可以使用以下方法设置和读取 Payload 状态

• setStatus($status)
• getStatus()

以下 Payload 状态可用。

• PayloadStatus::FOUND 请求的数据找到
• PayloadStatus::NOT_FOUND 请求的数据未找到
• PayloadStatus::SUCCESS 操作成功
• PayloadStatus::INVALID 无效输入
• PayloadStatus::ERROR 执行期间出错

警告：不要依赖常量值，因为它们可能会随时间而更改！始终通过名称使用常量。

PayloadFactory

为了使创建 Payload 对象更容易，有一个可用的 PayloadFactory。该工厂包含用于创建具有每个可用状态或无状态的 payload 对象的方法。

• createPayload() 创建一个新的 Payload 对象
• createSuccessPayload() 创建一个具有成功状态的新 Payload 对象
• createFoundPayload() 创建一个具有找到状态的新 Payload 对象
• createNotFoundPayload() 创建一个具有未找到状态的新 Payload 对象
• createInvalidPayload() 创建一个具有无效状态的新 Payload 对象
• createErrorPayload() 创建一个具有错误状态的新 Payload 对象

Payload 数据

除了状态外，Payload 还可以包含消息、输入和域方法的输入/输出。为了管理这些数据，Payload 类中提供了以下方法。

• setMessage(string $message)
• getMessage()
• setInput(mixed $input)
• getInput()
• setOutput(mixed $input)
• getOutput()

PayloadInterface

应在域内部创建和修改 Payload 对象。如果域方法将 PayloadInterface 作为返回类型，则只有获取方法将可见/可用给应用程序。

当然，您仍然可以通过接口之外的方法修改 payload，但这至少表明您不应使用设置方法。

最佳实践

解释我打算如何使用 Payload 对象。您可以制定自己的规则集，但建议在整个域中统一使用相同的规则。

Payload 状态

获取方法可以返回以下 payload 状态

• PayloadStatus::FOUND
• PayloadStatus::NOT_FOUND
• PayloadStatus::INVALID
• PayloadStatus::ERROR

命令方法可以返回以下 payload 状态

• PayloadStatus::SUCCESS
• PayloadStatus::INVALID
• PayloadStatus::ERROR

Payload 输入/输出

对于每个 payload 状态，应提供以下输入/输出数据

• PayloadStatus::FOUND

  • 输入：null 或命名数组（如有任何）的获取参数
  • 输出：找到的实体或集合

• PayloadStatus::NOT_FOUND

  • 输入：命名数组形式的获取参数（如有）
  • 输出：null

• PayloadStatus::SUCCESS

  • 输入：null
  • 输出：创建/更新/删除的实体或其他相关数据（如有）

• PayloadStatus::INVALID

  • 输入：命名参数数组
  • 输出：错误信息列表

• PayloadStatus::ERROR

  • 输入：命名参数数组
  • 输出：抛出的异常

这样您将始终拥有可能需要的信息。如果发生任何问题（未找到、无效或错误状态），您将看到输入参数以了解原因。您可以选择始终在有效载荷中包含输入参数。

有效载荷消息

有效载荷消息是可选的。它可以包含关于状态的一般消息。这样的消息可以方便地在应用中向用户提供友好的消息。我建议在整个域中至少保持一致，无论是否返回消息。

示例

• 找不到用户
• 用户更新成功
• 消息成功标记为已读
• 提供的评论数据无效
• 无法添加项目

变更日志

有关最近更改的更多信息，请参阅变更日志。

测试

此项目使用PHPSpec进行测试。