README

轻松为您的PHP应用程序创建REST API客户端

###是什么？Restinga是一个帮助您为选择的API构建REST客户端的工具。

###为什么？有时候，公司提供的PHP客户端很糟糕，您知道的。有时候，它们甚至比直接使用CURL API本身还要难用。我们构建了这个包，以便在那种情况下帮助您。

###快速入门

开始之前，您需要将Restinga作为项目依赖项安装。您可以通过运行以下命令来完成此操作：

composer require codecasts/restinga ~1.0

因此，现在我们可以开始定义您的服务。

1 - 为所需服务创建描述符

让我们以Digital Ocean API为例，Restinga本身并不设计用于处理授权，因此您应该已经有一个个人令牌或用户令牌。

首先，创建一个文件来描述如何找到请求以及如何授权，您可以通过扩展Codecasts\Restinga\Service\Descriptor类轻松完成此操作。

<?php namespace Codecasts\DigitalOcean;

use Codecasts\Restinga\Authorization\Bearer;
use Codecasts\Restinga\Service\Descriptor;

class DigitalOceanDescriptor extends Descriptor
{
    // the identifier of the service that
    // we're gonna use later when creating
    // our resource classes
    protected $service = 'digital-ocean';

    // the prefix to be used when calling the api
    protected $prefix = 'https://api.digitalocean.com/v2';

    // this method returns an Authorization class instance
    // There are a few available, just check
    // the Codecasts\Restinga\Authorization namespace
    public function authorization()
    {
        return new Bearer('your-token-here');
    }
}

创建此文件后，您需要在Restinga容器中注册它，以便稍后由资源类使用。

您可以通过以下方式完成此操作：

$digital_ocean = new Codecasts\DigitalOcean\DigitalOceanDescriptor();
Codecasts\Restinga\Container::register($digital_ocean);

####2 - 定义您的资源

好的，现在一切准备就绪，让我们创建我们的第一个资源。假设我们想处理Digital Ocean的droplets，对吧？因此，我们将定义一个资源（通过扩展Codecasts\Restinga\Data\Resource）来处理它。

<?php namespace Codecasts\DigitalOcean\Resource;

use Codecasts\Restinga\Data\Resource;
use Codecasts\Restinga\Http\Format\Receive\ReceiveJson;
use Codecasts\Restinga\Http\Format\Receive\ReceiveJsonErrors;
use Codecasts\Restinga\Http\Format\Send\SendJson;

class Droplet extends Resource
{
    // Each resource will need to use 2 traits to
    // define in which format it should send & receive data.
    // In your example, Digital Ocean uses Json to exchange data.
    use ReceiveJson;
    use SendJson;
    
    // Also, a format for errors are needed
    use ReceiveJsonErrors;

    // the identifier of which service restinga should use when
    // handling this resource
    // the name should match with the one you defined on the Service Descriptor
    protected $service = 'digital-ocean';

    // In this attribute, we dine the resource name, that will be used
    // as the sufix for the already defined api prefix
    protected $name = 'droplets';

    // The identifier is the main attribute that should be used when calling the api for
    // the current resource
    protected $identifier = 'id';

    // When receiving Data, the result may be nested inside 
    // a response object, like {"items": {"first_item"}}
    // this attribute is where you set the root element for the response
    // when searching for a collection (multiple items)
    protected $collection_root = 'droplets';

    // works like $collection_root, but now this attribute
    // sets the root when a single result is expected
    // (like getting a droplet by using an id)
    protected $item_root = 'droplet';
}

####3 - 使用定义的资源

好的，现在我们已经定义了您的资源，我们可以开始使用它。

创建Droplet

use Codecasts\DigitalOcean\Resource\Droplet;

$droplet = new Droplet();
$droplet->name = 'server.restinga.dev';
$droplet->region = 'nyc3';
$droplet->size = '512mb';
$droplet->image = 'ubuntu-14-04-x64';

$saved = $droplet->save();

if ($saved) {
    echo $droplet->id; // 4242424
}

创建Droplet时出错

use Codecasts\DigitalOcean\Resource\Droplet;

$droplet = new Droplet();
$droplet->name = 'server.restinga.dev';
$droplet->region = 'nyc3';
$droplet->size = '512mb';
// Image is required, let's send the request without it to see an error happening
//$droplet->image = 'ubuntu-14-04-x64';

$saved = $droplet->save();

if ($saved) {
    echo $droplet->id;
} else {
    // will print:
    // "unprocessable_entity, You specified an invalid image for Droplet creation."
    echo implode(', ', $droplet->getErrors()->all()); 
}

通过其标识符查找资源

use Codecasts\DigitalOcean\Resource\Droplet;

$droplet = new Droplet();

$found = $droplet->find('4242424'); // the id of the droplet we just created

if ($found) {
    echo $droplet->name; // server.restinga.dev
} else {
    foreach ($droplet->errors->all() as $code => $error) {
        echo $code . ": " . $error . "\n"; 
    }
    // id: not_found
    // message: The resource you were accessing could not be found.
}

更新资源

基本思路相同

use YourApp\Resources\YourResource();

$resource = new YourResource();
$resource->find('123');

$resource->price = '43.99';

$resource->update();

删除资源

操作方式相同

use YourApp\Resources\YourResource();

$resource = new YourResource();
$resource->find('123');

$resource->destroy();

嵌套资源到目前为止，一切都很顺利，但现实世界的API有嵌套对象。没问题，让我们看看如何处理它。

Digital Ocean有域名和域名记录，让我们创建这两个资源并将它们链接起来。

域名

<?php namespace Codecasts\DigitalOcean\Resource;

use Codecasts\Restinga\Data\Resource;
use Codecasts\Restinga\Http\Format\Receive\ReceiveJson;
use Codecasts\Restinga\Http\Format\Receive\ReceiveJsonErrors;
use Codecasts\Restinga\Http\Format\Send\SendJson;

class Domain extends Resource
{
    use ReceiveJson;
    use SendJson;
    use ReceiveJsonErrors;

    protected $service = 'digital-ocean';

    protected $name = 'domains';

    protected $identifier = 'name';

    protected $collection_root = 'domains';

    protected $item_root = 'domain';
}

域名记录

<?php namespace Codecasts\DigitalOcean\Resource;

use Codecasts\Restinga\Data\Resource;
use Codecasts\Restinga\Http\Format\Receive\ReceiveJson;
use Codecasts\Restinga\Http\Format\Receive\ReceiveJsonErrors;
use Codecasts\Restinga\Http\Format\Send\SendJson;

class DomainRecord extends Resource
{
    use ReceiveJson;
    use SendJson;
    use ReceiveJsonErrors;

    protected $service = 'digital-ocean';

    protected $name = 'records';

    protected $identifier = 'id';

    protected $collection_root = 'records';

    protected $item_root = 'record';
}

这两个已经创建，但尚未链接，让我们通过在域名资源类中创建一个record()方法来完成此操作。

    public function record()
    {
        return $this->childResource(new DomainRecord());
    }

现在，我们可以这样使用它：

use Codecasts\DigitalOcean\Resource\Domain;

$domain = new Domain();

$domain->find('restinga.dev');

$records = $domain->record()->all();

foreach ($records as $record) {
    echo $record->id . ' - ' . $record->type. ' - ' . $record->data . "\n";
}
//6124929 - NS - ns1.digitalocean.com
//6124930 - NS - ns2.digitalocean.com
//6124931 - NS - ns3.digitalocean.com
//6124932 - A - 123.123.123.123

其他方法也以相同的方式工作，例如，查找和更新记录

use Codecasts\DigitalOcean\Resource\Domain;

$domain = new Domain();

$domain->find('restinga.dev');

$record = $domain->record()->find('6124932');

$record->data = '222.222.222.222';

$record->update();

注意：即将编写完整文档。感谢您的理解