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应用程序的安全性处理。

elliotchance / xero-api

维护者

详细信息