README

Resto是一个受Laravel Eloquent启发的ORM，用于类似REST的Web服务，底层使用Guzzle。

使用Resto，您可以：

1. 在项目中处理无限数量的Rest API。
2. 在另一个项目中重用已经构建的API。
3. 自定义Resto以处理大多数API。

## 快速入门

#### 使用composer "require" { "sahanh/resto": "dev-master" }

然后执行composer install

假设有一个XYZ.com的API，它有帖子、用户。用户有多个帖子。该API使用一个密钥来验证每个请求。

#### 设置项目

Resto使用基于命名空间的约定来管理不同的API，这允许更好的代码管理和处理多个API。

app/
	XYZ/
		User.php
		Post.php

User.php

namespace XYZ;

class User extends Resto\Entity\Model
{
	public function posts()
	{
		//no need to put the namespace
		return $this->hasMany('Post');
	}
}

Post.php

namespace XYZ;

class Post extends Resto\Entity\Model
{
	public function user()
	{
		//no need to put the namespace
		return $this->belongsTo('Post');
	}
}

在开始使用之前，我们需要将此模块注册为Resto模块。

$module = Resto\Common\Module::register('XYZ');

模块类是一个API的容器，特定API的所有配置数据都将存储在模块类中。模块通过它们的命名空间来识别/注册。一旦模块被注册，我们就可以在执行之前访问Guzzle请求对象。

#### 设置API端点

#### 设置http传输器的选项

"initiateHttpClient"是一个在特定模块的每个请求之前执行的回调

$module = Resto\Common\Module::resolve('XYZ');
$module->setCallback('initiateHttpClient', function($request, $client){
	
	//append json ext to every request url
	$request->setPathExt('json');

	//guzzle http client
	$client->setDefaultOption('query', array('key' => 'password'));

	//http auth
	$client->setAuth('user', 'pass');
});

将这些配置设置放在引导文件中，并在应用程序启动时包含它。

#### 使用模型

XYZ\User::all(); //GET http://api.xyz.com/v2/users.json

$user = XYZ\User::find(1); //GET http://api.xyz.com/v2/users/1.json
$user->email = 'john@doe.com';
$user->save(); //PUT http://api.xyz.com/v2/users/1.json, changed email will be sent as a post fields.

$posts = $user->posts(); //GET http://api.xyz.com/v2/users/1/posts.json

//query
XYZ\User::query()->where('email', 'john@doe.com')->get(); //GET http://api.xyz.com/v2/users.json?email=john@doe.com

## 每个组件的介绍

### 模块 http://d.pr/i/fYSm 为了能够同时管理几个不同的API，Resto使用模块。每个API及其模型应创建在命名空间目录下，Resto将使用命名空间来识别每个模块。一旦模块被注册，就可以在任何时候访问它来设置配置选项，如API端点、API认证选项等。

### 查询 Query类生成请求并执行。Query类是API请求和模型之间的中间人。

### 请求 在底层，Query类使用Request类来构建每个请求。Request类是主要的传输器。Query类与特定的模块紧密耦合，而Request类则不是。

### 解析器 Resto使用解析器在数据离开应用程序之前和响应到来之后格式化数据。

### 请求解析器 当执行新的查询时，它会在执行之前通过请求解析器运行。请求解析器接收包含请求对象的查询对象。解析器随后相应地修改请求对象。例如，当进行PUT请求时，您的API需要一个xml正文，您可以创建一个请求解析器来完成此操作。

### 响应解析器 与请求解析器类似，查询对象在请求后运行响应。在每个请求之后，查询类需要数组中的数据，响应解析器确保查询类接收到它所需的数据。

默认情况下，Resto与JSON输出一起工作，对于POST\PUT，使用post字段。但是，您可以创建自己的解析器来与XML或其他特定格式一起工作，并将其注册在特定模块下。

### 关系 模型可以与其他模型有关联。

### 错误 默认响应解析器检查响应体中的"错误"键并创建Resto\Exception\ResponseErrorException。

============

### 模块 Resto\Common\Module

在API下使用模型集之前，应将其注册为模块。Resto采用命名空间方法，因此所有模型都应位于命名空间目录中。命名空间将用于识别特定模块。请确保您的应用程序可以在给定命名空间下自动加载这些模型。

多亏了模块方法，您可以使用Resto处理少量API。

app/
	ZenDesk/
		Ticket.php
		User.php
		Group.php
	
	BaseCamp/
		Account.php
		Projectphp
		People.php

Resto\Common\Module::register('ZenDesk'); Resto\Common\Module::register('Basecamp');

配置选项

一旦注册了模块，您就可以开始设置配置、回调，并注册用于解析器（以下将介绍）的不同类。

### 请求 Resto\Common\Module

响应

查询

模型

集合

关系

解析器