README

轻松将 API 消费添加到您的 PHP 类中。

Siesta 将添加方法来消费您的 JSON REST API，并将结果转换为您的 PHP 模型实例。

安装

composer.json

{
    "require": {
        "komodohq/siesta": "dev-master"
    }
}

$ composer install

用法

class User {

    use Siesta\Siesta;

    private static $siestaConfig = [
            "url" => "https://:9999",
            "endpoint" => "users"
        ];

    // constructor takes assoc array of properties
    function __construct($data) {
        $this->_id = $data['id'];
        $this->name = $data['name'];
    }
}

$users = User::find();

方法

`Siesta::find`

User::find([$queryParams[, $options]]);

User::find();
User::find(["username" => "OiNutter"]);
User::find(["username" => "OiNutter"], ["endpoint" => "administrators"]);

执行到 /<endpoint> 的 GET 请求，该请求返回与提供的查询参数匹配的项目集合。

注意。此方法也用于 findOne 方法，所以如果覆盖此方法，它也会影响该方法。

`Siesta::findOne`

User::findOne([$queryParams[, options]]);

User:find();
User::findOne(["username" => "OiNutter"]);
User::findOne(["username" => "OiNutter"], ["endpoint" => "administrators"]);

执行到 /{{endpoint}} 的 GET 请求，并返回与提供的查询参数匹配的第一个结果。设置一个额外的 limit 参数为 1，因此如果正在消耗的 API 支持该参数，它将限制返回的响应数量，并减少您的工作量。

`Siesta::findById`

User::findById($id[, $options]);

User::findById(1);
User::findById(1, ["endpoint" => "administrators"]);

执行到 /{{endpoint}}/{{this->id}} 的 GET 请求，并返回具有匹配 id 的单个结果。

`Siesta::create`

User::create($data[, $options]);

User::create(["username" => "Bob", "email" => "bob@komododigital.co.uk"]);
User::create(
    ["username" => "Bob", "email" => "bob@komododigital.co.uk"],
    ["endpoint" => "administrators"]
);

使用提供的数据向 /{{endpoint}} 执行 POST 请求，并返回新创建的资源。

`$siestaItem->update`

$user->update($data[, $options]);

$user->update(["location" => "Newcastle Upon Tyne"]);
$user->update(["location" => "Newcastle Upon Tyne"], ["endpoint" => "administrators"]);

使用提供的数据向 /{{endpoint}}/{{this->id}} 执行 PUT 请求，并返回更新后的资源。它还会更新本地资源，以包含在服务器上更新的任何字段。

`$siestaItem->save`

$user->save([$options]);

$user->save();
$user->save(["endpoint" => "administrators"]);

使用当前资源向 /{{endpoint}}/{{this->id}} 执行 PUT 请求，并返回更新后的资源。它还会更新本地资源，以包含在服务器上更新的任何字段。

如果资源尚未保存到服务器（未设置 id），则此方法将执行 POST 请求。然后，本地对象将更新为新创建的 id。

注意。此方法也用于 update 方法，所以如果覆盖此方法，它也会影响该方法。

`$siestaItem->delete()`

$user->delete([$options]);

$user->delete(["endpoint" => "administarots"]);

向 /{{endpoint}}/{{this->id}} 执行 DELETE 请求，并返回从服务器返回的表示 HTTP 响应体的关联数组。

自定义

`Siesta::$siestaConfig`

要配置您的类以使用 Siesta，您需要在您的类中添加一个 private static $siestaConfig 变量。这是一个 关联数组，可以包含以下键

url - 与您将要交互的 API 的 FQDN。必需
endpoint - API 上的端点，该端点映射到您的类表示的资源。默认为 ''。
idProperty- 您的类的主键字段。可以与 API 响应中的主键不同。默认为 id。
resultField - API 响应中包含查询或操作结果的属性。默认为 result
tokenField - 存储您的 oauth 令牌的 $_SESSION 键。默认为 SIESTA_OAUTH_TOKEN。
requestContentType - 在 PUT 和 POST 请求中发送的正文内容类型。默认为 application/json。

`Siesta::populate`

要更改从返回的 API 数据创建新模型的方式，您需要覆盖 populate 方法。默认情况下，它将返回的数据作为 关联数组 传递给类的构造函数方法。

public static function populate($item)
{
    return new static($item);
}

但是如果你希望将属性作为单独的参数传递给构造函数，你可以在你的类定义中重写它，使其看起来像这样

public static function populate($item)
{
    $reflect  = new ReflectionClass($class);
    return $reflect->newInstanceArgs($item);
}

`Siesta->toArray`

Siesta 为你的类添加了一个 public 的 toArray 方法。这个方法用于将类序列化以便在保存请求中发送。默认情况下，它只是调用自身的 get_object_vars，如下所示

public function toArray()
{
    return get_object_vars($this);
}

但你也可以重写它以提供自己的序列化。

`Siesta->setValue`

Siesta 添加了一个 public 的 setValue 方法，这个方法用于更新属性，基于从服务器返回的响应。默认情况下，它只是将属性设置为值。

public function setValue($property, $value)
{
    $this->$property = $value;
}

你可以重写这个方法，在设置属性之前对它们进行任何额外的操作。

public function setValue($property, $value)
{
    if ($property == 'registered') {
        $this->$property = strtotime($value);
    } else {
        $this->$property = $value;
    }
}

异常

`SiestaGeneralException`

任何一般异常的基类。存储响应体，可以像这样检索

$e->getResponse();

`SiestaClientException`

用于 400 范围内 HTTP 错误代码的异常类。扩展 SiestaGeneralException。

`SiestaServerException`

用于 500 范围内 HTTP 错误代码的异常类。扩展 SiestaGeneralException。

Laravel

如果你使用 Laravel，你可以省略 Siesta 的 URL 配置变量，它将寻找 Config::get('api.url')。

TODO

改进错误处理
更多的测试
整理测试

测试

运行 composer install 来获取测试库。

启动测试 API 服务器

$ php -S localhost:9999 ./tests/index.php

运行测试

$ bin\behat

贡献

代码应符合 PSR 2 编码标准。
将拉取请求保留为重大更改和添加。对于小的错别字和文档添加，只需提出问题即可。
确保所有单元测试通过，并且如果你添加了新功能，请为它添加单元测试并确保它们通过。
如果我们觉得它们与库的目标不一致或者我们认为它们没有带来显著的好处，我们可能不会接受拉取请求。我们总是会尝试解释我们的理由，并且准备好被说服。
保持礼貌 ;)

komodohq / siesta

维护者

详细信息