README

一个完全基于 REST 的服务器实现，适用于 CodeIgniter，使用一个库、一个配置文件和一个控制器。

需求

PHP 5.4 或更高版本
CodeIgniter 3.0+

注意：为支持 1.7.x，请从“下载”标签页下载 v2.2

关于 4.0.0 的重要更新

请注意，版本 4.0.0 正在开发中，被视为破坏性更改（根据 SemVer）。由于 CI 3.1.0 现在具有本机 Composer 支持，因此此库将迁移到基于 Composer。

查看“开发”分支以了解最新情况。

安装和加载

CodeIgniter Rest Server 可在 Packagist 上找到（使用语义版本控制），推荐通过 Composer 安装 Codeigniter Rest Server。只需将此行添加到您的 composer.json 文件中

"chriskacerguis/codeigniter-restserver": "^3.0"

或运行

composer require chriskacerguis/codeigniter-restserver

处理请求

当您的控制器从 REST_Controller 继承时，方法名称将附加到访问请求所使用的 HTTP 方法。例如，如果您正在向 /books 进行 HTTP GET 调用，则会调用 Books#index_get() 方法。

这使得您可以轻松实现 RESTful 接口。

class Books extends REST_Controller
{
  public function index_get()
  {
    // Display all books
  }

  public function index_post()
  {
    // Create a new book
  }
}

REST_Controller 还支持 PUT 和 DELETE 方法，允许您支持真正的 RESTful 接口。

访问参数也很容易。只需使用 HTTP 动词的名称作为方法即可。

$this->get('blah'); // GET param
$this->post('blah'); // POST param
$this->put('blah'); // PUT param

DELETE 请求的 HTTP 规范排除了参数的使用。对于删除请求，您可以将项目添加到 URL 中。

public function index_delete($id)
{
	$this->response([
		'returned from delete:' => $id,
	]);
}

如果通过 URL 传递查询参数，无论是否为 GET 请求，都可以通过查询方法获取。

$this->query('blah'); // Query param

内容类型

REST_Controller 支持多种不同的请求/响应格式，包括 XML、JSON 和序列化 PHP。默认情况下，该类将检查 URL 并查找格式，无论是作为扩展名还是作为单独的段。

这意味着您的 URL 可以看起来像这样

http://example.com/books.json
http://example.com/books?format=json

这可能会因 URI 段而变得不稳定，因此建议使用 HTTP Accept 标头

$ curl -H "Accept: application/json" http://example.com

您从类中发出的任何响应（有关更多信息，请参阅响应）都将以指定的格式序列化。

响应

该类提供了一个 response() 方法，允许您以用户请求的响应格式返回数据。

返回任何对象 / 数组 / 字符串等都很简单

public function index_get()
{
  $this->response($this->db->get('books')->result());
}

这将自动返回一个 HTTP 200 OK 响应。您可以在第二个参数中指定状态码。

public function index_post()
  {
    // ...create new book
    $this->response($book, 201); // Send an HTTP 201 Created
  }

如果您没有指定响应代码，并且您响应的数据 == FALSE（例如空数组或字符串），则响应代码将自动设置为 404 Not Found

$this->response([]); // HTTP 404 Not Found

配置

您可以通过在配置文件夹中创建一个名为rest.php的文件并添加您的配置来覆盖所有默认配置。所有给定的配置将覆盖默认配置。

语言

您可以通过添加rest_controller_lang.php到您的语言文件夹中并覆盖您想要的来覆盖所有默认语言文件。

多语言支持

如果您的应用程序使用语言文件来支持多个区域设置，REST_Controller将自动解析HTTP的Accept-Language头部并在您的动作中提供语言。这些信息可以在$this->response->lang对象中找到。

public function __construct()
{
  parent::__construct();

  if (is_array($this->response->lang))
  {
    $this->load->language('application', $this->response->lang[0]);
  }
  else
  {
    $this->load->language('application', $this->response->lang);
  }
}

身份验证

此类还提供了对HTTP基本身份验证和/或更安全的HTTP摘要访问身份验证的基本支持。

您可以通过将$config['rest_auth']设置为'basic'来启用基本身份验证。然后可以使用$config['rest_valid_logins']指令来设置可以登录到您的系统的用户名和密码。该类将自动发送所有正确的头部来触发身份验证对话框。

$config['rest_valid_logins'] = ['username' => 'password', 'other_person' => 'secure123'];

启用摘要认证同样简单。配置您的登录信息，如上所述，并将$config['rest_auth']设置为'digest'。该类将自动发送头部以启用摘要认证。

如果您正在将此库与使用PHP会话进行身份验证的AJAX端点结合使用，那么您可能不喜欢摘要或基本认证方法。在这种情况下，您可以告诉REST库检查哪个PHP会话变量。如果该变量存在，则用户将被授权。设置该变量的责任将落在您的应用程序上。您可以在$config['auth_source']中定义该变量。然后通过将$config['rest_auth']设置为session来告诉库使用PHP会话变量。

可以通过使用IP白名单进一步保护这三种身份验证方法。如果您的配置文件中启用了$config['rest_ip_whitelist_enabled']，则可以设置一个允许的IP列表。

连接到您的API的任何客户端都将与白名单IP数组进行核对。如果它们在列表中，则允许访问。如果不在此列表中，抱歉，无法完成。白名单是一个逗号分隔的字符串。

$config['rest_ip_whitelist'] = '123.456.789.0, 987.654.32.1';

默认情况下，允许您的本地主机IP（127.0.0.1和0.0.0.0）。

API密钥

除了上述认证方法之外，REST_Controller类还支持使用API密钥。启用API密钥非常简单。在您的config/rest.php文件中将其打开。

$config['rest_enable_keys'] = TRUE;

您需要创建一个新的数据库表来存储和访问密钥。REST_Controller将自动假设您有一个如下所示的表。

CREATE TABLE `keys` (
	`id` INT(11) NOT NULL AUTO_INCREMENT,
	`key` VARCHAR(40) NOT NULL,
	`level` INT(2) NOT NULL,
	`ignore_limits` TINYINT(1) NOT NULL DEFAULT '0',
	`date_created` INT(11) NOT NULL,
	PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

该类将在每个请求中查找带有API键的HTTP头部。无效或缺少的API键将导致HTTP 403 Forbidden。

默认情况下，HTTP头部为X-API-KEY。这可以在config/rest.php中进行配置。

$ curl -X POST -H "X-API-KEY: some_key_here" http://example.com/books

其他文档/教程

NetTuts: 在CodeIgniter中使用RESTful服务

贡献

此项目最初由Phil Sturgeon编写，但他的参与已经转移，因为他不再使用它。截至2013/11/20，进一步的开发和支持将由Chris Kacerguis完成。

Pull Requests 是修复错误或添加功能的最佳方式。我知道很多人都在使用它，所以如果您有改进意见，请贡献出来，我会持续发布版本。

hanischit / codeigniter-restserver

维护者

详细信息