README

Billow是一个数字海洋API包装器，它允许您检索信息、配置虚拟机（Droplets）并执行现有虚拟机的操作。与这个库交互有几种不同的方式；方便的类和直接客户端使用。

本README将作为库的文档，并提供使用方便类和直接与客户端使用库的示例。

客户端

Billow\Client在Billow和HTTP客户端之间充当中间件。默认情况下，Billow\Client使用Guzzle 5.3，但它也使用Billow\ClientInterface，允许您创建自己的客户端实现。如果您想使用Guzzle 6，可以很容易地编写一个实现Billow\ClientInterface的客户端，并编写适合您需求的get和post方法的实现。

虚拟机服务

DropletService提供了一种轻松检索、创建和执行虚拟机（Droplets）操作的方法。如果您通常使用Guzzle的特定配置，可以将这些配置传递给Billow\Client构造函数，Billow\Client不会覆盖构造函数；因此，配置可以像传递给GuzzleHttp\Client一样传递。如果没有设置客户端，虚拟机服务将实例化默认客户端的一个实例。您只需要在具有默认配置的情况下注入Billow\Client的实例。

创建

创建方法需要您提供请求体，以及作为授权头部的访问令牌。数字海洋提供了一些关于请求体应如何构造的文档：数字海洋API v2 创建虚拟机。请求体必须以数组的形式发送，以下是一个将传递给创建方法的示例数组。

$dropletBody = [
    'name' => 'My New Droplet',
    'region' => 'nyc2',
    'size' => '40gb',
    'image' => 'ubuntu-14-04-x64',
    'ssh_keys' => ['public key content'],
    'backups' => true,
    'ipv6' => true,
    'private_networking' => true,
    'user_data' => 'meta data to be associated with the droplet'
];

如果我们使用上面的示例，创建新虚拟机的调用将如下所示

<?php
use Billow\DropletService;

$headers = ['Authorization' => 'Bearer xxxxxxxxx'];

// assuming the body of the request is the same as above
$dropletService = new DropletService();
$response = $dropletService->create($dropletBody, $headers);

响应是一个GuzzleHttp\Message\Response对象，因此如果响应没有成功完成，您仍然可以使用getBody()、getHeaders()、getStatusCode()方法来获取更多信息。如果Guzzle抛出异常，Billow将抛出Billow\Exceptions\ProvisionException，该异常将显示响应消息、状态码和之前的异常。

检索

检索方法需要您提供虚拟机ID和头部信息。如果您不提供Content-type头部，它将默认创建并设置为application\json。这些头部应包括您的访问令牌，在授权头部中。

数字海洋提供了一些不同的发行版，当您使用DropletService来检索虚拟机时，它将返回一个Billow\Droplets\Droplet实例。通过使用Billow\Droplets\DropletFactory，检索将尝试创建您正在尝试检索的虚拟机的值对象。例如，如果您检索的是Ubuntu虚拟机，返回类型将是Billow\Droplets\Ubuntu。

以下是一个通过DropletService检索虚拟机的示例

<?php
use Billow\DropletService;

$headers = [
    'Authorization' => 'Bearer xxxxxxx'
];

$dropletId = 123456;

$dropletService = new DropletService();
$droplet = $dropletService->retrieve($dropletId, $headers);

echo $droplet->toJSON();

如果Guzzle抛出异常，它将被捕获并重新抛出为Billow\Exceptions\DropletException

执行操作

Digital Ocean通过API提供执行以下操作的能力：重启、关闭电源、开启电源等。使用DropletService，通过performAction()方法可以使这个过程相对简单。所有可用的操作都可以实例化并通过performAction(DropletInterface $droplet, ActionInterface $action, $headers)方法传入。在某些情况下，例如重命名，可能需要构造函数参数。以下有两个示例，一个使用构造函数参数，另一个没有使用。

<?php
use Billow\DropletService;
use Billow\Actions\EnableBackups;

$headers = [
    'Authorization' => 'Bearer xxxxxxxx'
];
$enableBackups = new EnableBackups();
$dropletId = 123456;

$dropletService = new DropletService();
$droplet = $dropletService->retrieve($dropletId);

$response = $dropletService->performAction($droplet, $enableBackups, $headers);

<?php
use Billow\DropletService;
use Billow\Actions\Rename;

$headers = [
    'Authorization' => 'Bearer xxxxxxxx'
];
$rename = new Rename('my-renamed-droplet');
$dropletId = 123456;

$dropletService = new DropletService();
$droplet = $dropletService->retrieve($dropletId, $headers);

$response = $dropletService->performAction($droplet, $rename, $headers);