README

Laravel应用的基本基础。

该软件包包含以下其他软件包，以便尽可能快速地开始开发。

Dingo API 已经依赖于 Fractal，因此转换功能是即插即用的。

Hive 适用于 Laravel 4.2 以及 Laravel 5。

安装

您需要在您的 composer.json 文件中要求它。

"owlgrin/hive": "dev-master"

然后，您需要在您的 app.php 中添加以下服务提供者。

'Dingo\Api\ApiServiceProvider',
'LucaDegasperi\OAuth2Server\OAuth2ServerServiceProvider',
'Owlgrin\Hive\HiveServiceProvider',

验证

Hive 附带了一个具有一些扩展功能的自定义验证器，您可以使用它来代替 Laravel 内置的验证器。（自定义验证器扩展了 Laravel 的验证器，因此您可以得到它提供的一切。）

如何使用自定义验证器

您需要在需要验证器时解决它。为此，您可以在任何自动加载的文件中添加以下代码（例如，在 global.php 中）。

Validator::resolver(function($translator, $data, $rules, $messages)
{
    return new Owlgrin\Hive\Validation\Validator($translator, $data, $rules, $messages);
});

如何使用验证

您需要创建一个文件，例如 UserValidator.php，它扩展 Owlgrin\Hive\Validation\Runner。然后，您可以创建各种属性，这些属性保留不同情况下规则。

<?php

use Owlgrin\Hive\Validation\Runner;

class UserValidator extends Runner {

	protected static $creating = [
		'name' => 'required',
		'email' => 'required|email'
	];
}

一旦完成，您可以将文件作为依赖项传递到您的控制器/仓库中，然后按如下方式验证数据

public function store()
{
	$data = Input::all();

	$if( ! $this->userValidator->when('creating')->isValid($data)) return Redirect::back();

	// All good. Go ahead!
}

请注意，在 when 方法中传递的参数应与扩展 Runner 的类的静态属性相同。

我们建议使用语言文件来指定错误消息，但您也可以创建具有此格式的另一个静态属性：messagesWhen{situation}（例如，messagesWhenCreating），这些自定义消息将在验证时传递给验证器。

额外规则

尽管自定义验证器使验证变得超级简单，但它还有一些额外的规则，可以使验证任何复杂数据结构变得容易。

call_method

使用 call_method 规则，您可以在另一个类上调用一个方法，该方法处理复杂的验证。当验证失败时，调用方法应返回 false，否则返回 true。

用法

protected static $creating = [
	'invoice_items' => 'array|min:1|call_method:Path\To\StockValidator@isEnoughStockInInventory'
];

您可以在您的语言文件中指定此规则的错误消息。在 validation.php 的末尾添加以下部分。

'methods' => array(
    'Path\To\StockValidator@isEnoughStockInInventory' => 'The :attribute does not have enough stock.'
),

call_each

有时，我们需要验证一个数组，并且数组中的每个元素都必须通过某些验证。此规则可用于此类目的。

例如，您想要验证学生每个科目的分数是否都至少为50，才能对其进行证书处理。

数据可能看起来像这样

$student = [
	'name' => 'John Doe',
	'roll_number' => 1337,
	'marks' => [
		['subject' => 'Physics', 'marks' => 32],
		['subject' => 'Programming', 'marks' => 98]
	]
];

现在，我们可能有一个学生验证器，它将验证学生数据，但在需要验证 marks 数组中的每个元素都通过某些规则的情况下，我们可以创建一个类 StudentMarksValidator。

<?php

use Owlgrin\Hive\Validation\Runner;

class StudentMarksValidator extends Runner {

	protected static $certifying = [
		'subject' => 'required',
		'marks' => 'required|min:50'
	];
}

在 StudentValidator 中，我们可以添加如下规则

<?php

use Owlgrin\Hive\Validation\Runner;

class StudentValidator extends Runner {

	protected static $certifying = [
		'name' => 'required',
		'roll_number' => 'required',
		'marks' => 'array|required|size:2|call_each:StudentMarksValidator@certifying'
	];
}

一旦完成，您将得到如下错误消息

[marks 数组中的第一个元素] 分数必须至少为50。

我们处理了跟踪元素位置所需的一切，并创建了正确且有意义的错误消息。

错误信息中的第一部分称为指定符，其格式可以通过语言文件进行控制。要覆盖默认格式，请在 app/lang/packages/{locale}/hive 中创建一个名为 validation.php 的语言文件，内容如下：

<?php

return [

	/*
	|--------------------------------------------------------------------------
	| Specifiers
	|--------------------------------------------------------------------------
	|
	| The following language lines are used to create specifiers for the rules,
	| that are processed in nested fashion (eg. call_each).
	|
	*/
	'specifiers' => [
		'call_each' => ':position item in :parent_attribute'
	],
];

输入

如果您已经使用 Eloquent，那么您可能不需要这个功能。

Hive 提供了一种简单的方法来转换和映射输入，以便您可以得到一致的数据来工作。

假设您想要将输入数据映射成如下有意义的格式

$input = array(
	'name' => 'John Doe',
	'age' => 24, // note that this is integer,
	'gender' => null // user doesn't want to tell, hence mapped to null
);

要实现这一点，您需要创建一个特质，例如 UserProperties，它使用 Owlgrin\Hive\Input\Mapper，如下所示：

<?php

trait UserProperties {
	use Owlgrin\Hive\Input\Mapper;

	protected $defaultProperties = array(
		'name' => 'string|null',
		'age' => 'int|0',
		'gender' => 'string|null'
	);
}

现在，在您的控制器中使用这个特质。

// UserController.php
class UserController extends Controller {
	use UserProperties;

	public function store()
	{
		$input => $this->getInput(); // this will get you the properly mapped input
	}
}

您也可以通过创建一个类而不是特质来实现这一点，如下所示：

<?php

class UserMapper {
	use Owlgrin\Hive\Input\Mapper;

	// properties here
}

类可以扩展，也可以注入。因此，有时它们更方便。

属性

您需要在一个数组中定义属性，其中键是属性的名称，值是以下格式的字符串： {type}|{default}。该属性将被转换为定义的类型，如果不存在，则用定义的默认值替换。

所有属性都必须在以下格式的 tair 属性中定义：${specifier}Properties。默认情况下，Mapper 会查找 'defaultProperties'，但您可以使用 $this->getInput('updation') 查找不同的属性，这将在特质中查找 $updationProperties。

默认值

您可以定义任何默认值，并且它们都将转换为属性的指定类型。这保证了数据的一致性。

然而，有几个特殊的默认值。

null：无论类型是什么，此值都将值设置为 null。

unset：如果它是假值，则将从输入中删除属性。

回调

当您需要在数据映射后执行某些操作时，可能会需要。为此，您只需在特质或使用特质的类中创建一个方法，如下所示：

protected function {specifier}Callback($original, &$mapped)
{

}

回调将接收两个参数，一个是请求获得的原输入，另一个是映射输入的引用。您可以根据需要更改映射输入，因为它作为引用传递。

响应

我们需要创建有意义的响应，我们提供了一个特质，使其变得非常简单。在您的控制器中，您可以使用以下语句使用该特质：

use Owlgrin\Hive\Response\Responses;

然后您可以轻松地创建响应

return $this->respondWithData($data);

或者对于没有内容的响应（HTTP 状态码：204），您可以使用此方法

return $this->respondNoContent();

您还可以使用以下方法来发送错误消息，带有适当的 HTTP 状态、自定义代码和自定义类型。

$this->respondBadRequest();
$this->respondUnauthorized();
$this->respondForbidden();
$this->respondNotFound();
$this->respondInvalidInput();
$this->respondInternalError();

这些方法中的每个都接受两个可选参数： $message 和 $code，您可以将它们传递以覆盖默认值。

错误的结构如下

{
	error: {
		code: 400,
		type: "invalid_input",
		message: "Invalid input."
	}
}

如果您的控制器扩展了 Dingo\Api\Routing\Controller，则可以使用转换器使用 Fractal 来转换响应。您可以在 Fractal 的文档中找到更多信息。

异常

Hive 提供自定义异常，以便更容易处理。以下是可以使用的以下自定义异常：

Owlgrin\Hive\Exceptions\BadRequestException;
Owlgrin\Hive\Exceptions\UnauthorizedException;
Owlgrin\Hive\Exceptions\ForbiddenException;
Owlgrin\Hive\Exceptions\NotFoundException;
Owlgrin\Hive\Exceptions\InvalidInputException;
Owlgrin\Hive\Exceptions\InternalException;

每个都扩展了一个抽象类 Owlgrin\Hive\Exceptions\Exception，这允许我们解析验证器或语言文件键的消息并准备响应。

您可以使用它如下所示：

try
{
	if($this->validator->when('creating')->isInvalid($data))
	{
		throw new Owlgrin\Hive\Exceptions\InvalidInputException($this->validator->getErrors());
	}
}
catch(Owlgrin\Hive\Exceptions\InvalidInputException $e)
{
	return $this->respondInvalidInput($e->getMessage(), $e->getCode());
}

作为额外的好处，Owlgrin\Hive\HiveServiceProvider 已经为您应用程序注册了各种异常处理程序，这样您可以专注于重要工作而不是捕获异常。Hive 自动捕获并准备所需响应。

尝试从您的路由文件中抛出异常。 ;)

我们不断努力改进这个包，并欢迎提交拉取请求。我们希望让开始使用变得非常简单。我们在开始任何新项目时都会使用这个包。

owlgrin / hive

维护者

详细信息