README

Laravel应用程序的一组基本PHP异常。

安装

在您的 composer.json 文件中要求此包

{
	"require": {
		"antarctica/laravel-base-exceptions": "0.*"
	}
}

运行 composer update。

用法

HttpException

扩展Symfony HttpException。

此异常旨在用于API或其他在处理HTTP请求过程中发生错误的情况。

它扩展了Symfony HttpException，以确保与Laravel的JSON Exception Formatter包的易于集成/兼容性。

此异常还添加了一些自定义属性，以便更容易地将异常用作错误。

属性

注意：此异常还支持标准的 message 属性，但在此处未进行文档说明。

statusCode (int)

设置要在响应中使用的HTTP状态码，如父异常中定义。

headers (int)

要返回的响应头数组，如父异常中定义

kind (string)

人类/机器可读的错误 '类型'，通常类似于异常类，因为这在生产环境中的错误中不包括。

details (array)

自由形式，但结构化的 '捕获所有' 错误内容。这可能根据需要为机器或人类阅读而设计。

例如，如果您需要包含一些其他服务应消费的数据或描述特定的验证错误（这些错误不适用于在 kind 或 message 属性中涵盖）。

resolution (string)

人类可读的、简短的错误修复描述，如果需要详细信息来实现此操作，请在外部托管并在 resolutionURLs 属性中包含其位置。

resolutionURLs (array)

人类/机器可读的错误修复相关URL/URI列表。这些可能由服务自动消费（即指向另一个API资源或服务），或链接到相关的文档等，更详细地描述如何修复错误。

基本用法（Laravel）

<?php

use Antarctica\LaravelBaseExceptions\Exception\HttpException;

class SomeException extends HttpException {

	protected $statusCode = 501; // Not implemented - used for demonstration purposes only.

	protected $kind = 'some_fault';

	protected $details = [
		"something" => [
			"Something went wrong."
		]
	];

	protected $resolution = 'Please don\'t do that again.';

	protected $resolutionURLs = ['http://www.example.com'];
}

InvalidArgumentTypeException

扩展此包的 HttpException 异常。

此异常旨在用于方法，其中用作方法参数或参数的值被确定不是正确的数据类型。

例如，一个参数必须是一个数据类型 string，但给定的数据类型是 array。

注意：此异常不需要您确定数据类型，而是您提供有效值的示例以及给定的值及其相应的类型，这些类型将被自动确定。

注意：如果您需要一个实际值无效的异常，请使用 InvalidArgumentValueException 异常。

注意：如果您需要为确保值属于特定类别（或其父类）创建一个异常，请不要仅使用此类别。此类别只能确认值是一个对象，它也会检查其类别。有关可用的异常详细信息，请参阅BASWEB-157。

此异常还添加了一些自定义属性，使使用此类型错误的异常更容易。

属性

注意：由HttpException使用的属性也受此异常支持，但在此处未记录。

argumentName（字符串）

注意：此属性是异常构造函数的一部分

用于输出消息，涉及任何参数或参数的名称。

例如，对于一个要求参数position为整数的方法，参数名称可以是Position。

注意：此值仅用于在异常中构造显示消息，因此其值不需要与参数名称匹配。然而，由于用户可能会使用此值（例如，如果用作API方法参数），强烈建议确保此值确实与参数名称匹配。

validArgumentValue（混合类型）

注意：此属性是异常构造函数的一部分

已知良好值，是正确数据类型的参数。

例如，对于一个要求参数position为整数的方法，此值可以是任何整数，如3。

对于更复杂类型，例如一个要求参数dataProvider为对象的方法，此值可以是任何对象变量。

givenArgumentType（混合类型）

注意：此属性是异常构造函数的一部分

用于参数的值。通常您可以直接从方法构造函数将此值传递到异常中。

例如，如果参数是position，您可能可以使用$position为此属性。

基本用法（Laravel）

<?php

use Antarctica\LaravelBaseExceptions\Exception\InvalidArgumentTypeException;

/**
 * Determines if the value for an argument is an integer
 *
 * @param string $argument name of the argument
 * @param mixed $var value given for the argument
 * @return int
 * @throws InvalidArgumentTypeException
 * @throws InvalidArgumentValueException
 */
private function validateInt($argument, $var)
{
    if (is_numeric($var) === false)
    {
        throw new InvalidArgumentTypeException(
            $argumentName = $argument,
            $valueOfCorrectArgumentType = 0,
            $argumentValue = $var
        );
    }
    
    // ...
    
    return $var;
}

InvalidArgumentValueException

扩展此包的 HttpException 异常。

此异常设计用于与那些用于方法参数的值不正确的值的方法一起使用。

例如，一个参数必须在Red, Green, Blue三种颜色列表中，但给出的是Yellow的值。

注意：如果您需要针对值的数据类型创建异常，请使用InvalidArgumentTypeException异常。

注意：如果您需要为确保值属于特定类别（或其父类）创建一个异常，请不要仅使用此类别。此类别只能确认值是一个对象，它也会检查其类别。有关可用的异常详细信息，请参阅BASWEB-157。

此异常还添加了一些自定义属性，使使用此类型错误的异常更容易。

属性

注意：由HttpException使用的属性也受此异常支持，但在此处未记录。

argumentName（字符串）

注意：此属性是异常构造函数的一部分

用于输出消息，涉及任何参数或参数的名称。

例如，对于一个要求参数position为整数的方法，参数名称可以是Position。

注意：此值仅用于在异常中构造显示消息，因此其值不需要与参数名称匹配。然而，由于用户可能会使用此值（例如，如果用作API方法参数），强烈建议确保此值确实与参数名称匹配。

details (array)

注意：此属性是异常构造函数的一部分

为什么值无效的人或机器可读原因。结构化为数组，以适应不同的受众和目的。

您可能希望提供结构良好的信息，以便客户端解释错误并自动解决它们或显示给用户，其中生成此异常的服务用作后端服务。

您还可以提供用于调试或其他人类与生成此异常的服务交互的描述性消息。

注意：您可以根据需要使这些方法复杂化

• 对于简单的验证类型情况（例如，值不是列表）仅声明给出的值不在列表中可能就足够详细。
• 对于更复杂的情况（例如，至少有一位经理不在且不在周二或当风向为东风时不能使用日期），您可能希望结构化错误。
• 您可能想提供动态信息（例如，您不能使用比当前温度高10度的有效值）。

resolution (string)

注意：此属性是异常构造函数的一部分

此属性从HttpException继承，但对于此异常是强制性的。

如何提供允许值的可读描述。这些通常与details参数协同工作。

例如，如果一个方法需要一个参数在列表中，详细说明将表明所提供的值（并显示此值）不在有效术语列表中（并列出这些术语）。在这种情况下，解决方案可以简单地声明重试之前的行为，使用有效术语列表中的一个术语。

通过继承自HttpException的属性，也可以提供文档链接或其他来源/URL，具体为resolutionURLs属性。

基本用法（Laravel）

<?php

use Antarctica\LaravelBaseExceptions\Exception\InvalidArgumentValueException;

/**
 * Determines if the value for an argument is an integer
 *
 * @param string $argument name of the argument
 * @param mixed $var value given for the argument
 * @return int
 * @throws InvalidArgumentTypeException
 * @throws InvalidArgumentValueException
 */
private function validateInt($argument, $var)
{
    // ...

    if ($var <= 0)
    {
        throw new InvalidArgumentValueException(
            $argumentName = $argument,
            $reasons = ['Value must not be equal to or less than 0, ' . $var . ' given.'],
            $resolution = 'Ensure you are providing a value greater than, and not including 0.'
       );
    }

    return $var;
}

贡献

本项目欢迎贡献，请参阅CONTRIBUTING以了解我们的通用政策。

开发

为了帮助开发并保持您的本地计算机整洁，使用VM（由Vagrant管理）创建一个具有所有必需工具/库的隔离环境。

需求

• Mac OS X
• Ansible brew install ansible
• VMware Fusion
• Vagrant brew cask install vmware-fusion vagrant
• 主机管理器和Vagrant VMware插件vagrant plugin install vagrant-hostmanager && vagrant plugin install vagrant-vmware-fusion
• 您在~/.ssh/中有一个私钥id_rsa和公钥id_rsa.pub。
• 您在~/.ssh/config中有一个类似[1]的条目。

[1] SSH配置条目

Host bslweb-*
    ForwardAgent yes
    User app
    IdentityFile ~/.ssh/id_rsa
    Port 22

配置开发VM

使用Vagrant管理VM，并使用Ansible进行配置。

$ git clone ssh://git@stash.ceh.ac.uk:7999/basweb/laravel-base-exceptions.git
$ cp ~/.ssh/id_rsa.pub laravel-base-exceptions/provisioning/public_keys/
$ cd laravel-base-exceptions
$ ./armadillo_standin.sh

$ vagrant up

$ ssh bslweb-laravel-base-exceptions-dev-node1
$ cd /app

$ composer install

$ logout

提交更改

使用Git flow工作流程来管理此包的开发。

应该在feature分支中进行离散更改，从develop分支创建，并合并回develop（直接在develop中进行小型单行更改）。

准备发布一系列功能/更改时，从develop创建一个release分支，根据需要更新文档，并与标记的master合并，使用语义版本（例如v1.2.3）。

发布后，应将master分支与develop合并，以重新启动流程。高影响力的错误可以在hotfix分支中解决，从master创建并直接合并到master（然后合并到develop）。

问题跟踪

与该包相关的问题、错误、改进、问题、建议和其他任务通过BAS Web & Applications Team Jira项目（BASWEB）进行管理。

清理

为了删除开发VM

vagrant halt
vagrant destroy

然后可以安全地像平常一样删除laravel-base-exceptions目录。

许可

版权所有2014 NERC BAS。在MIT许可下许可，有关详细信息请参阅LICENSE。