README

这是一个针对Xero API的客户端库，包括OAuth接口和类似ORM的抽象。

这个库基于XeroAPI/XeroOAuth-PHP的功能流程，但更合理地划分为面向对象设计。

这个库已经与私有、公共和合作伙伴应用程序进行了测试。

需求

• PHP 5.5+
• php_curl 扩展 - 确保使用最新版本（7.30+）
• php_openssl 扩展

设置

使用composer

composer require calcinai/xero-php

否则，只需下载包并将其添加到自动加载器中。命名空间遵循PSR-4规范。

用法

以下所有示例均针对XeroPHP\Models\Accounting命名空间中的模型。此外，还有针对PayrollAU、PayrollUS、Files和Assets的模型。

创建XeroPHP实例（包含示例配置）

$xero = new \XeroPHP\Application\PrivateApplication($config);

加载一组对象并遍历它们

$contacts = $xero->load(Contact::class)->execute();

foreach ($contacts as $contact) {
    print_r($contact);
}

加载单页面的对象集合并遍历它们 （为什么？）

$contacts = $xero->load(Contact::class)->page(1)->execute();

foreach ($contacts as $contact) {
    print_r($contact);
}

搜索满足特定条件的对象

$xero->load(Invoice::class)
    ->where('Status', Invoice::INVOICE_STATUS_AUTHORISED)
    ->where('Type', Invoice::INVOICE_TYPE_ACCREC)
    ->execute();

通过GUID加载某些东西

$contact = $xero->loadByGUID(Contact::class, $guid);

或创建并填充它

$contact = new Contact($xero);

$contact->setName('Test Contact')
    ->setFirstName('Test')
    ->setLastName('Contact')
    ->setEmailAddress('test@example.com');

保存它

$contact->save();

如果您已创建了多个相同类型的对象，您可以通过传递数组到$xero->saveAll()来批量保存所有对象。

从v1.2.0+开始，可以在创建对象时直接注入Xero上下文，这将暴露->save()方法。这对于对象与其关系维护状态是必要的。

保存相关模型

如果您一次保存多个模型，默认情况下不会更新额外模型属性。这意味着如果您正在保存带有新联系人的发票，联系人的ContactID不会更新。如果要将相关模型属性更新，可以将布尔标志true传递给保存方法。

$xero->save($invoice, true);

嵌套对象

$invoice = $xero->loadByGUID(Invoice::class, '[GUID]');
$invoice->setContact($contact);

附件

$attachments = $invoice->getAttachments();
foreach ($attachment as $attachment) {
    //Do something with them
    file_put_contents($attachment->getFileName(), $attachment->getContent());
}

//You can also upload attachemnts
$attachment = Attachment::createFromLocalFile('/path/to/image.jpg');
$invoice->addAttachment($attachment);

要在附件上设置IncludeOnline标志，请将true作为第二个参数传递给->addAttachment()。

PDF - 支持PDF导出的模型将继承一个->getPDF()方法，它返回PDF的原始内容。目前这仅限于发票和信用证明。

有关更复杂的使用和嵌套/相关对象的示例，请参阅示例。还有一个使用此库的PHP应用程序示例。

Webhooks

如果您从Xero接收webhooks，有一个Webhook类可以帮助处理请求和解析相关事件列表。

$webhook = new Webhook($application, $request->getContent());

/**
 * @return int
 */
$webhook->getFirstEventSequence();

/**
 * @return int
 */
$webhook->getLastEventSequence();

/**
 * @return \XeroPHP\Webhook\Event[]
 */
$webhook->getEvents();

请参阅：Webhooks文档

验证Webhooks

为了确保webhooks来自Xero，您应该验证Xero提供的传入请求头。

if (! $webhook->validate($request->headers->get('x-xero-signature'))) {
    throw new Exception('This request did not come from Xero');
}

请参阅：签名文档

处理错误

您的请求可能会引起Xero的错误，您可能需要处理。您可能会遇到如下错误：

• HTTP 400 Bad Request，例如发送格式不正确的电子邮件地址。
• HTTP 503 Rate Limit Exceeded 是通过在短时间内快速调用API来触发的。
• HTTP 400 Bad Request 是通过请求一个不存在的资源来触发的。

这只是一些示例，你应该阅读官方文档以了解更多可能的错误信息。

抛出异常

这个库会解析Xero返回的响应，并在遇到这些错误之一时抛出异常。下表显示了响应代码和相应的抛出异常：

查看：响应代码和错误文档

处理异常

为了捕获和处理这些异常，你可以在请求周围包裹try / catch块，并按需处理每个异常。

try {
    $xero->save($invoice);
} catch (NotFoundException $exception) {
    // handle not found error
} catch (RateLimitExceededException $exception) {
    // handle rate limit error
}

查看：异常处理