README

Resourceful是一个简单的组件，用于快速原型设计REST JSON资源，主要暴露CRUD操作。它基于JSON Hyper-Schemas和SILEX。
您使用Hyper-Schemas来定义资源及其相互关系。除了编写Hyper-Schemas和注册新资源外，无需编写其他代码。您只需关注API的实现即可。适当的HTTP响应代码和头信息将自动管理。

此包受到Jason Desrosiers的jdesrosiers/resourceful项目的启发。

工作原理

使用composer安装Resourceful

> composer require e-artspace/resourceful

定义您的入口控制器。

$app = new Silex\Application;
$app->register(new Resourceful\ServiceProvider,array(
	'data.dir' => __DIR__ . '/../data'
));

$app->mount("/", new Resourceful\IndexControllerProvider);
$app->mount("/schema", new Resourceful\SchemaControllerProvider);

//here add your restful resources
$app->mount("/foo", new Resourceful\CRUDControllerProvider('foo'));

$app->run();

这就完成了。您已经准备好开始使用了。使用内置的PHP服务器运行应用程序。

> php -S localhost:8080 front.php

您可以使用位于http://json-browser.s3-website-us-west-1.amazonaws.com/?url=http%3A//%3A8080/的json浏览器实现。在首次运行时，将创建一个名为schema的文件夹，并创建一个默认索引模式和资源。您预计将在添加资源时添加到默认索引模式的链接。这些链接将为您的用户提供一个起点。

向您的应用程序添加另一个新资源，只需要在您的入口控制器中编写一行代码。

$app->mount("/bar", new Resourceful\CRUDControllerProvider("bar");

CRUDControllerProvider的第一个参数是定义类型项结构的JSON模式的名称。它必须对应用程序是唯一的。

持久性由存储服务在$app['schema name.store']（例如$app['foo.store']）中管理，如果没有提供，则由默认创建的本地文件系统存储服务$app['data.store']管理。

存储服务可以是任何Doctrine Cache实现。默认实现通常足以用于快速原型，但您可以选择memcache或redis等其他服务。如果您使用默认存储实现，您可以在$app['data.dir']参数中设置数据目录（默认为'/tmp/resourceful'）。

一旦注册了资源，下一步就是向索引模式添加一个链接来创建“foo”。刷新Jsonary浏览器，您应该会看到您添加到索引中的链接。此外，在您的/schema文件夹中已生成一个默认的“foo”模式。根据您的喜好填写“foo”模式，然后使用您添加的索引链接创建“foo”。所有CRUD操作都可用于资源。您可以通过重新定义$app['schema name.controller']（例如 $app['foo.controller']）来自定义操作。

您可以通过设置$app['createDefault']为false来禁用模式和示例数据的自动创建；

您可以通过重新定义$app['uniqid']或为每种数据类型定义不同的版本来自定义从项目创建唯一ID的函数。例如，$app['foo.uniqid']（例如 $app['foo.uniqid']）。默认情况下，使用php函数uniqid()生成id；

$app["foo.uniqid"] = $app->protect(function ($data) {
    return md5(serialize($data));
});

这就完成了。只需继续添加资源和资源之间的链接，以创建有用的API。

开发和测试环境

提供了一种流浪虚拟设备，用于在本地工作站上进行开发和测试。

本地工作站要求

• 安装GIT。选择“按原样检出，提交Unix风格的行结束符”。
• 安装Vagrant
• 安装Virtualbox

以下命令可用于执行资源丰富项目的初始检出

git clone https://yourid@bitbucket.org/e-artspace/resourceful.git
cd resourceful

使用vagrant运行虚拟设备

以下命令可用于启动虚拟设备并登录

PORT=8080 vagrant up
vagrant ssh

Apache网络服务器配置为localhost端口号8080（或你在vagrant up中指定的端口号）

在vagrant中运行单元和功能测试

以下命令可用于启动执行所有单元测试

PORT=8080 vagrant up
vagrant ssh
cd /vagrant
vendor/bin/phpunit

注意，所有项目源代码库都挂载（并同步）在虚拟主机上的/vagrant目录。

要获取测试覆盖率报告

sudo apt-get install -y php-xdebug
vendor/bin/phpunit --coverage-html=tests/_support/report/unit

在Postman中运行烟测试系统测试

虚拟设备http服务器映射到工作站上的localhost:8080

在postman中导入tests/system/smoke_test_v1.json并调用运行器。

销毁虚拟设备

销毁虚拟设备

vagrant destroy

更多选项请使用vagrant --help

功能

索引架构

在很大程度上取决于你使你的REST/HTTP应用可发现，但Resourceful通过自动创建一个指向你应用根目录的索引架构来让你有一个良好的起点。索引应更新以指导用户如何使用你的应用。

架构生成

在注册新资源后，首次运行应用程序时，在架构文件夹中创建一个通用架构。这是尝试让你从一些样板代码中解脱出来，以便你可以更快地工作。

检索资源

如果请求的资源不存在，将返回一个404 Not Found响应。返回资源的Content-Type将使用JSON Hyper-Schema建议的包括一个指向响应中定义资源的Hyper-Schema的profile属性。

创建资源

资源可以通过两种方式创建。最常见的方式是使用POST。当使用POST创建资源时，将有一个指向新创建资源的Link头部。资源还可以通过在不包含资源的URI上使用PUT请求来创建。资源创建将始终响应201 Created。新资源将在响应中回显。

修改资源

可以使用PUT请求修改资源。PUT请求不支持部分更新。传递的资源将按照传递的方式存储。修改后的资源将随响应返回。

删除资源

当删除资源时，将返回204 No Content响应。如果要删除的资源不存在，将返回标准的成功响应。删除不存在的资源不会被视为错误。

验证

所有输入的JSON都会自动验证是否符合为该资源定义的JSON Schema。验证失败将导致返回400 Bad Request响应。

内容协商

鉴于Resourceful基于JSON Hyper-Schema和Jsonary，支持的格式只有JSON。因此，任何请求非JSON格式的请求将返回406 Not Acceptable响应。任何传递非JSON内容的请求将返回415 Unsupported Media Type响应。所有这些均由silex-conneg-provider服务提供商处理。

对OPTIONS请求的支持

我认为除非他们需要用于CORS，否则没有人关心OPTIONS请求的支持，但为了HTTP兼容性，最好还是支持。Resourceful从silex-cors-provider获得OPTIONS请求支持。

CORS支持

CORS支持由silex-cors-provider服务提供商提供。要启用CORS支持，请将cors添加到中间件之后。

支持的项目

Silex

Resourceful是一个Silex应用程序，其中配置了一些服务提供商和控制器。

JSON Hyper-Schema

JSON Hyper-Schema是这个项目的基础。JSON Hyper-Schema是我找到的唯一可以同时实现可发现性和超链接的提案。JSON Hyper-Schema使得这个项目成为可能。

Jsonary

Jsonary是一个通用的Hyper-Schema浏览器。它并不完美，也不漂亮，但它让我们能够查看和操作任何由Hyper-Schema驱动的资源，而无需编写任何前端代码。

Jsv4

Jsv4是一个JSON Schema验证器。Resourceful使用它根据您编写的Hyper-Schemas验证请求JSON。

silex-conneg-provider

没有silex REST/HTTP应用程序是完整的，没有silex-conneg-provider或类似的服务提供商。这个服务提供商添加了检查请求内容协商头部的中间件，并在有问题时相应地响应。

silex-cors-provider

silex-cors-provider主要用于生成OPTIONS路由。然而，CORS支持也同样有用。

Doctrine Cache

我选择使用Doctrine Cache进行数据存储。它们有多种实现方式，因此您可以按照自己的需求选择数据存储方式。一些选项包括文件系统、memcache或redis。如果这些都不符合您的需求，您始终可以编写自己的Doctrine\Common\Cache\Cache实现。