README

用于与 Xero OAuth API 一起工作的 PHP 库。

简介

XeroOAuth-PHP 是一个用于与 Xero API (http://developer.xero.com) 一起使用的示例库。Xero API 使用 OAuth 1.0a，但我们不推荐将此库用于其他 OAuth 1.0a API，因为 Xero API 具有更先进的实现（RSA-SHA1、客户端 SSL 证书等），因此具有许多在其他 API 中不常用的配置选项。

此库旨在帮助开发者快速入门 OAuth 认证层，但在将其用于生产环境之前，可能需要对其实施进行一些自定义。

要求

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

设置

要设置，您需要修改 _config.php 文件中的值以满足您自己的需求和应用程序设置，或者查看每个不同应用程序类型的定制示例文件，public.php、private.php 或 partner.php。使用 _config.php 文件时，如果使用非合作伙伴应用程序，则应取消注释 合作伙伴应用程序的特殊选项。

使用

在处理 Xero 时，有一些函数会被使用

发送请求

请求函数是任何与 API 通信的核心。您可能希望发送多种类型的请求，所有这些请求都由 request() 函数处理。

request($method, $url, $parameters, $xml, $format)

参数

方法：要使用的 API 方法（GET、PUT、POST）
URL：API 端点的 URL。这由一个特殊函数处理（见下文）
参数：包含诸如 where、order by 等参数的关联数组（见 http://developer.xero.com/documentation/getting-started/http-requests-and-responses/）
XML：请求数据（用于 PUT 和 POST 操作）
格式：响应格式（目前支持 xml、json & pdf）。注意，PDF 不支持所有端点

生成 URL

创建一个正确格式的请求 URL。

url($endpoint, $api)

参数

端点：您希望与之一起工作的端点。注意，除了 Invoices、Contacts 等各种 API 端点外，还有 OAuth 端点，例如 'RequestToken' 和 'AccessToken'。当指定资源，如 Invoices/$GUID 时，您可以通过将 GUID 添加到基本 URL 来构造请求。
API：有两个 API：核心（核心会计 API）和薪酬（薪酬应用程序 API）。默认为核心。

解析响应

一旦您获取了数据，您可以通过 parseResponse 函数将其传递以将其转换为可用的内容。

parseResponse($response, $format)

参数

响应：要解析的原始 API 响应
格式：支持 xml、pdf 和 json，但不能使用此函数将 XML API 响应解析为 JSON - 必须与请求的响应格式相对应。

授权

对于使用 3 腿 OAuth 流程的公共和合作伙伴 API 类型应用程序，我们需要将用户重定向到 Xero 以授权 API 连接。为此，请将用户重定向到使用类似以下调用的 URL

url("Authorize", '') . "?oauth_token=".$oauth_token."&scope=" . $scope;

附加信息

oauth_token：这是在先前的 RequestToken 调用中生成的请求令牌
范围：薪酬 API 是一个受权限控制的 API，需要逗号分隔的应用程序请求访问端点的列表，例如 $scope = 'payroll.payrollcalendars,payroll.superfunds,payroll.payruns,payroll.payslip,payroll.employees';

刷新访问令牌

对于可以通过API程序刷新30分钟访问令牌的合作伙伴API应用程序，您可以使用refreshToken函数

refreshToken('the access token', 'the session handle')

参数

访问令牌：当前访问令牌
会话句柄：会话标识符句柄

调试

设置诊断

在设置过程中，您可能会遇到一些配置问题，特别是与一些更高级的应用类型，如合作伙伴。

为了确保您的配置正确，您可以运行诊断函数

diagnostics();

这会返回一个错误消息数组（如果有）。这些是以人类可读的形式，应该足以让您走上正确的道路。如果不是，请检查Xero开发者中心和论坛以获取更多信息。

在生产代码中运行此操作可能是个坏主意，因为返回的错误只有开发者才能解决，而不是最终用户。

运行时错误

可能遇到错误的原因有很多：数据验证、令牌问题、授权撤销等。检查HTTP响应代码的同时，也要检查相关的错误字符串。

示例代码中包含一个非常基本的错误输出函数，它会输出与错误相关的所有可用信息。在将其用于生产环境之前，需要对其进行大量整理。

outputError($object);

响应助手

了解您从API接收到的消息类型可能很有用。在每次不成功的响应中，都会返回一个助手元素

TokenExpired：这意味着访问令牌已过期。如果您使用的是合作伙伴API类型应用程序，可以自动更新它，或者如果您使用的是公共应用程序，则提示用户重新进行身份验证
TokenFatal：在这种情况下，令牌处于无法更新的状态，用户将需要重新进行身份验证
SetupIssue：连接的设置/配置中存在问题 - 检查诊断函数

待办事项

从报告中读取值
更好的WHERE和ORDER示例
将OAuthsimple更改合并回RSA-SHA1父仓库

许可 & 信用

本软件根据MIT许可证发布。

OAuthSimple

OAuthsimple.php包含来自United Heroes的OAuthSimple PHP类的少量修改。

tmhOAuth

XeroOAuth类基于从tmhOAuth库中衍生出的代码和结构。

主要更改历史

0.6 - 2015年4月19日

添加了composer支持。修改了content-type，以便它也适用于PUT请求

0.5 - 2014年11月16日

添加了跟踪类别和选项的CRU示例。更新了CA证书为最新版本 - 注意，如果您使用的是非常旧的curl版本，可能会收到“证书无效”类型的错误。删除了一个未使用的函数，并对另一个函数的注释进行了整理，使其更加合理。

0.4 - 2014年9月29日

合并了一些拉取请求，解决了多个调用有签名验证问题的问题。

0.3 - 2014年1月3日

合并了许多拉取请求，整理了格式，并扩展了示例测试。

0.2 - 2013年5月13日

合并到主分支，添加了更多测试，并改进了合作伙伴API应用程序的安全性处理。

vegasje / xero-oauth

维护者

详细信息