README

所有 API 端点的访问都通过 LinodeClient 类的一个实例进行，您首先需要创建该实例

use Linode\LinodeClient;

$client = new LinodeClient();

$regions = $client->regions->findAll();

上面的示例创建了一个未认证的客户端，这足以访问一些公共端点，如 regions 或 kernels。要访问您的私有数据，您需要向 LinodeClient 提供您的访问令牌

use Linode\LinodeClient;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

$linodes = $client->linodes->findAll();

访问令牌可以是手动生成的 Personal Access Token 或从 OAuth 工作流中检索的令牌。您可以使用 oauth2-linode 库使用 OAuth 在 Linode 上进行身份验证。

对 Linode 的任何 API 请求都可能失败。在这种情况下，Linode API 返回一个错误列表，每个错误都包含 reason（一个人类可读的错误消息，总是包含）和 field（提交的 JSON 中的特定字段，当不适用时为 null）。

每当请求失败时，库都会抛出 LinodeException。异常的消息总是错误列表中的第一条错误的消息。您也可以使用其 getErrors 函数从异常中获取所有错误。

use Linode\Exception\LinodeException;
use Linode\LinodeClient;
use Linode\LinodeInstances\Linode;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

try {
    $linode = $client->linodes->create([
        Linode::FIELD_TYPE   => 'g6-standard-2',
        Linode::FIELD_REGION => 'us-east',
    ]);
}
catch (LinodeException $exception) {
    // This is the same as the reason of the very first error below.
    $message = $exception->getMessage();

    foreach ($exception->getErrors() as $error) {
        echo $error->field;
        echo $error->reason;
    }
}

库为 Linode API 返回的每个对象提供了一个 实体 类 - linodes、images、nodebalancers、等等。所有实体都是只读的，数据可以通过属性访问。

此外，每个实体类型都有一个专门的存储库。大多数存储库都可通过 LinodeClient 类访问

use Linode\LinodeClient;
use Linode\LinodeInstances\Linode;
use Linode\LinodeInstances\LinodeRepositoryInterface;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

/** @var LinodeRepositoryInterface $repository */
$repository = $client->linodes;

/** @var Linode $linode */
$linode = $repository->find(123);

echo $linode->label;
echo $linode->hypervisor;

某些实体是嵌套的，例如 DomainRecord 对象始终属于某个 Domain 对象。这种嵌套实体的存储库应从相应的父实体获取。LinodeClient 类只包含根实体的存储库。

use Linode\Domains\Domain;
use Linode\Domains\DomainRecord;
use Linode\LinodeClient;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

/** @var Domain $domain */
$domain = $client->domains->findOneBy([
    Domain::FIELD_DOMAIN => 'example.com',
]);

/** @var DomainRecord[] $records */
$records = $domain->records->findAll();

foreach ($records as $record) {
    echo $record->type;
}

为了便于找到相应的实体和存储库，库的源代码结构与原始 API 文档相同。

每个存储库都实现了 Linode\RepositoryInterface 并提供以下两个函数。

find 函数通过其实体 ID 搜索实体

use Linode\LinodeClient;
use Linode\LinodeInstances\Linode;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

/** @var Linode $linode */
$linode = $client->linodes->find(123);

findAll 函数返回类型为 Linode\EntityCollection 对象的所有实体。此类对象实现了标准的 Countable 和 Iterator 接口

use Linode\LinodeClient;
use Linode\LinodeInstances\Linode;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

/** @var Linode[] $linodes */
$linodes = $client->linodes->findAll();

printf('Found %d linode(s).', count($linodes));

foreach ($linodes as $linode) {
    // ...
}

当您从 Linode API 获取对象列表时，API 会分页返回列表。为了使您的生活更轻松，库在内部管理分页，因此您可以像处理简单数组一样处理实体列表。

例如，假设您的账户中有 270 个 Linode，您需要列出它们的标签

use Linode\LinodeClient;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

$linodes = $client->linodes->findAll();

foreach ($linodes as $linode) {
    echo $linode->label;
}

在这个示例中，当你调用 findAll 函数时，只会加载前100个实体（100是API中的默认页面大小）。一旦你在枚举中达到第101个实体，库会再次调用以获取下一个100个linode，依此类推。因此，库将为您270个linode发出三个API请求，但对您来说这是完全透明的。当然，只有当需要时才会执行额外的请求，所以如果您在中间断开枚举，剩余的实体将不会被请求。

此外，检索到的实体按集合进行缓存，因此可以安全地多次枚举相同的集合

use Linode\LinodeClient;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

$linodes = $client->linodes->findAll();

// This will make three API requests.
foreach ($linodes as $linode) {
    echo $linode->label;
}

// This will make no API requests at all.
foreach ($linodes as $linode) {
    echo $linode->type;
}

$linodes2 = $client->linodes->findAll();

// This will make three API requests again, as this is another collection.
foreach ($linodes2 as $linode) {
    echo $linode->type;
}

Linode API支持对请求对象的排序，这可以在findAll函数的两个可选参数中指定

use Linode\LinodeClient;
use Linode\LinodeInstances\Linode;
use Linode\RepositoryInterface;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

$linodes = $client->linodes->findAll(Linode::FIELD_LABEL, RepositoryInterface::SORT_DESC);

第一个参数是要按其排序实体的字段名称。每个实体类都包含有用的常量，因此您无需硬编码字段名称。

第二个参数是排序方向，如果省略，则等于Linode\RepositoryInterface::SORT_ASC。

Linode API支持对请求对象进行过滤，这通过相同的Linode\RepositoryInterface接口通过findBy、findOneBy和query函数实现。

findBy函数接受一个由标准作为第一个参数的参数数组。所有标准都通过逻辑AND操作连接。

use Linode\LinodeClient;
use Linode\LinodeInstances\Linode;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

$linodes = $client->linodes->findBy([
    Linode::FIELD_REGION => 'us-west',
    Linode::FIELD_TAGS   => 'app-server',
]);

函数的第二个和第三个参数用于排序，与findAll函数的相应参数完全相同。

findBy函数返回一个集合，如果找不到任何内容，则可能为空。当您需要使用过滤器检索单个对象时，可以使用接受一个参数数组作为唯一参数的findOneBy函数。

use Linode\LinodeClient;
use Linode\LinodeInstances\Linode;

$client = new LinodeClient('03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c');

$linode = $client->linodes->findOneBy([
    Linode::FIELD_LABEL => 'mysql-server-02',
]);

如果没有找到任何内容，则函数返回null。如果找到多个实体，则函数引发一个LinodeException。

上述提到的最后一个函数 - query - 允许您使用Linode API的查询语言执行复杂请求。

API查询语言假设您将条件转换为JSON，这实际上使得它们难以阅读、调试和维护。例如，当前的API文档建议以下JSON对象以获取所有属于standard或highmem类或具有12到20个vcpus的Linode类型：

{
  "+or": [
    {
      "+or": [
        {
          "class": "standard"
        },
        {
          "class": "highmem"
        }
      ]
    },
    {
      "+and": [
        {
          "vcpus": {
            "+gte": 12
          }
        },
        {
          "vcpus": {
            "+lte": 20
          }
        }
      ]
    }
  ]
}

query函数允许您使用更易于阅读的表达式来编写条件，这些表达式作为字符串传递给第一个参数。上述示例可以按以下方式实现：

use Linode\LinodeClient;

$client = new LinodeClient();

$types = $client->linodeTypes->query('(class == "standard" or class == "highmem") or (vcpus >= 12 and vcpus <= 20)');

foreach ($types as $type) {
    echo $type->class;
    echo $type->vcpus;
}

库使用以下词法项支持所有Linode API运算符

如果您的表达式中存在语法错误，库将引发一个带有所有找到的错误列表的LinodeException。

如果您需要使用一些变量创建表达式，则可以使用参数化表达式，如下例所示

use Linode\LinodeClient;

$client = new LinodeClient();

$parameters = [
    'class1' => 'standard',
    'class2' => 'highmem',
    'min'    => 12,
    'max'    => 20,
];

$types = $client->linodeTypes->query('(class == :class1 or class == :class2) or (vcpus >= :min and vcpus <= :max)', $parameters);

每个参数以冒号开头，整个参数集作为数组一次性提供。

而且，就像findAll和findBy函数一样，query函数有两个最后的可选参数用于排序

use Linode\LinodeClient;
use Linode\LinodeTypes\LinodeType;
use Linode\RepositoryInterface;

$client = new LinodeClient();

$parameters = [
    'class1' => 'standard',
    'class2' => 'highmem',
    'min'    => 12,
    'max'    => 20,
];

$types = $client->linodeTypes->query(
    '(class == :class1 or class == :class2) or (vcpus >= :min and vcpus <= :max)',
    $parameters,
    LinodeType::FIELD_MEMORY,
    RepositoryInterface::SORT_DESC);