README

简介

这个结果对象是一个符合PSR-2规范的、框架无关的帮助工具，用于以面向对象的方式返回数据。它允许你轻松地定义最近操作的成功或失败，以及设置易于检查的状态字符串、更详细的消息、错误字符串和任何额外数据。

需求

Composer

Snscripts\Result需要以下内容

• "php": ">=5.5.0"

如果你希望在开发模式下运行并运行测试，则需要以下内容。

• "phpunit/phpunit": "~4.0"
• "squizlabs/php_codesniffer": "~2.0"

安装

Composer

最简单的安装方式是通过composer。

composer require snscripts/result 1.*

或将其添加到你的项目composer.json文件中。

{
    "require": {
        "snscripts/result": "1.*"
    }
}

用法

在最简单的形式中，该软件包可以按以下方式使用

// A successful result
$Result = \Snscripts\Result\Result::success();

// A failure result
$Result = \Snscripts\Result\Result::fail();

然后你需要从你的函数或库中返回$Result，在调用你的库的代码中，你可以根据需要检查结果是否成功或失败

$Result = $MyLibrary->someAction(); // this returns Result::success();

// check for a success
var_dump($Result->isSuccess());

// check for a fail
var_dump($Result->isFail());

状态代码

有时你可能希望定义一个与结果相关的状态代码，这可以进一步描述结果。在需要固定字符串/代码来确切说明发生了什么的代码的多语言情况下，这也很有用。

您可以使用$Result->setCode('myCode');设置代码，并使用$Result->getCode();从结果中检索代码。

默认情况下，该对象提供了一些定义好的常量，用于常见的结果。

CREATED    = 'created',
UPDATED    = 'updated',
SAVED      = 'saved',
DELETED    = 'deleted',
VALIDATION = 'validation',
AUTH       = 'authorised',
NOT_AUTH   = 'not_authorised',
FOUND      = 'found',
NOT_FOUND  = 'not_found',
ERROR      = 'error',
FAILED     = 'failed',
PROCESSING = 'processing'

这些是对象常量，可以通过以下方式访问。

use Snscripts\Result\Result;

var_dump(Result::CREATED);
var_dump(Result::AUTH);
var_dump(Result::NOT_FOUND);

这意味着您可以使用以下方式结合上面的setCode方法使用它们。

$Result->setCode(Result::ERROR);

echo $Result->getCode(); // 'error'

错误代码也可以作为静态success和fail方法的第一个参数传递。

Result::success(Result::CREATED);
Result::fail(Result::VALIDATION);

消息

除了状态代码外，您还可以定义要传递的消息。这可能是在用户界面中显示的实际消息、用于翻译的语言字符串等...

设置和检索的方式如下。

$Result->setMessage('Your item was added successfully');
$Result->getMessage();

为了方便起见，消息也可以作为静态success和fail方法的第二个参数传递。

Result::success(
	Result::CREATED,
	'Your item was created successfully'
);
Result::fail(
	Result::VALIDATION,
	'There was a validation error, please try again'
);

错误

如果结果是失败结果，你可能需要传递一个错误数组。这通常来自你的系统验证方法。

你可以使用setErrors命令一次性设置一个完整的错误数组。

$Result->setErrors([
	'field' => [
		'is required,
		'must be unique'
	],
	'another_field' => 'is required'
]);

然后，你可以通过调用以下方式非常简单地检索错误列表

var_dump($Result->getErrors());

在某些情况下，你可能正在遍历你的数据，并需要逐个设置错误消息。

你可以通过使用setError来完成此操作

$Result->setError('Field is required');
$Result->setError(['field' => 'is required']);

setError方法已被编写，以便任何设置的字符串都将按正常方式推送到数组中。

$Result->setError('Field is required');
$Result->setError('Another error occurred');

// var_dump($Result->getErrors()); Will result in
[
	'Field is required',
	'Another error occurred'
]

在传递数组的情况下，该方法将尝试合并数组。这有助于防止创建额外的数组级别，并在同一键上发生多个错误时帮助合并数据。

$Result->setError('Field is required');
$Result->setError(['field' => 'is required']);
// var_dump($Result->getErrors()); Will result in
[
	'Field is required',
	'field' => 'is required'
]

为了方便起见，您可以将错误数组传递到success和fail静态方法的第三个参数中，这将执行相当于setErrors命令的操作，并设置完整的错误数组。

Result::fail(
	Result::VALIDATION,
	'There was a validation error, please try again',
	[
		'field1' => 'is required',
		'field2' => [
			'is required',
			'should be unique'
		]
	]
);

额外内容

无论结果如何，您都希望与结果一起传递一些额外的数据，这可能是一份刚刚被修改的数据的副本，或者是一份刚刚失败验证的表单数组的副本。使用Result，您可以通过以下命令简单地进行传递。

您可以使用setExtras命令一次性设置一个完整的额外数据数组。

$Result->setExtras([
	'foo' => 'bar',
	'bar' => 'foo',
	[
		'fizzbuzz',
		'buzzfizz'
	]
]);

然后，您可以通过调用以下方式非常简单地检索额外数据列表。

var_dump($Result->getExtras());

在某些情况下，您可能正在遍历数据，需要逐个设置数据。

您可以通过使用setExtra来实现这一点。

$Result->setExtra('foobar');
$Result->setExtra(['foo' => 'bar']);

setExtra方法被编写成任何设置的字符串都将按正常方式推送到数组中。

$Result->setExtra('foobar');
$Result->setExtra('barfoo');

// var_dump($Result->getExtras()); Will result in
[
	'foobar',
	'barfoo'
]

如果传递了一个数组，该方法将尝试合并该数组。这有助于防止创建额外的数组级别，并有助于在相同键上发生多个项目时合并数据。

$Result->setExtra('foobar');
$Result->setExtra(['foo' => 'bar']);
// var_dump($Result->getExtras()); Will result in
[
	'Foobar',
	'foo' => 'bar'
]

为了方便，您可以将额外数据数组传递给success和fail静态方法的第四个参数，这将执行等效于setExtras命令，并将设置完整的数据数组。

Result::success(
	Result::CREATED,
	'Your item was successfully created',
	[],
	[
		'id' => 1,
		'name' => 'Foo Bar',
		'address' => 'fizzbuzz street'
	]
);

贡献

有关详细信息，请参阅贡献指南。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。