README

这是官方 Asana PHP API 客户端的扩展。增加了部分功能。仅包含我所需要的功能。

Asana API v1 官方 PHP 客户端库

安装

Composer

如果您使用 Composer 管理依赖项，可以将 "weborganiser/asana" 包作为依赖项包含。

{
    "require": {
        "weborganiser/asana": "^0.5.1"
    }
}

或者，您可以指定版本为 dev-master 以获取 GitHub 上最新的 master 分支。

身份验证

个人访问令牌

使用个人访问令牌创建客户端

<?php
$client = Asana\Client::accessToken('ASANA_PERSONAL_ACCESS_TOKEN');

OAuth 2

Asana 支持 OAuth 2。 asana 为您处理 OAuth 流的某些细节。

使用您的 OAuth 客户端 ID 和密钥创建客户端

<?php
$client = Asana\Client::oauth(array(
    'client_id'     => 'ASANA_CLIENT_ID',
    'client_secret' => 'ASANA_CLIENT_SECRET',
    'redirect_uri'  => 'https://yourapp.com/auth/asana/callback',
));

将用户重定向到客户端的 session 对象获得的授权 URL

<?php
$url = $client->dispatcher->authorizationUrl();

authorizationUrl 可以带有一个可选的 state 参数，通过引用传递，如果为 null，则将其设置为随机数，如果不为 null，则通过传递

<?php
$state = null;
$url = $client->dispatcher->authorizationUrl($state);
// $state will be a random number

或者

<?php
$state = 'foo';
$url = $client->dispatcher->authorizationUrl($state);
// $state will still be foo

当用户重定向回您的回调时，检查 state URL 参数是否匹配，然后将 code 参数传递以获取访问令牌

<?php
if ($_GET['state'] == $state) {
  $token = $client->dispatcher->fetchToken($_GET['code']);
  // ...
} else {
  // error! possible CSRF attack
}

注意：对于 web 服务器，通常的做法是将 state 存储在仅安全的、http-only 的 cookie 中，以便浏览器在回调时自动发送。

注意：如果您正在编写非浏览器应用程序（例如命令行工具），则可以使用特殊的重定向 URI urn:ietf:wg:oauth:2.0:oob 来提示用户将代码复制并粘贴到应用程序中。

用法

客户端的方法分为几个资源：attachments、events、projects、stories、tags、tasks、teams、users 和 workspaces。

返回单个对象的方法直接返回该对象

<?php
$me = $client->users->me();
echo "Hello " . $me->name;

$workspaceId = $me->workspaces[0]->id;
$project = $client->projects->createInWorkspace($workspaceId, array('name' => 'new project'));
echo "Created project with id: " . $project->id;

返回多个项目的方法（例如 findAll）默认返回一个项目迭代器。请参阅“集合”部分

选项

可以在 Client.DEFAULTS 对象上全局设置各种选项，在 client.options 上按客户端设置，或在请求上作为额外的命名参数设置。例如

<?php
// global:
Asana\Client::$DEFAULTS['page_size'] = 1000;

// per-client:
$client->options['page_size'] = 1000;

// per-request:
$client->tasks->findAll(array('project' => 1234), array('page_size' => 1000));

可用选项

base_url（默认值："https://app.asana.com/api/1.0"）：连接到的 API 端点基本 URL
max_retries（默认值：5）：达到 API 速率限制或发生服务器错误时重试的次数。速率限制重试延迟直到速率限制到期，服务器错误以 1 秒的延迟开始指数退避。
full_payload（默认值：false）：返回整个 JSON 响应而不是 'data' 属性（集合方法的默认值和 events.get）
fields 和 expand：包含在响应中的字段名称数组，或要扩展的响应中的子对象。例如 array('fields' => array('followers', 'assignee'))。请参阅 API 文档

集合（返回数组作为其 'data' 属性的方法）

iterator_type（默认值：“items”）：指定要返回的迭代器类型（或不是）。有效值是“items”和 null。
item_limit（默认值：null）：限制集合中返回的项目总数（在迭代器的情况下跨越多个请求）。
page_size（默认值：50）：限制一次获取的项目数。
offset：前一次调用相同方法返回的偏移令牌（在 response->next_page->offset 中）

事件

poll_interval（默认：5）：通过 events->getNext 和 events->getIterator 获取新事件时的轮询间隔
sync：前一次调用 events->get 返回的同步令牌（在 response->sync 中）

集合

项目迭代器

默认情况下，返回对象集合的方法返回一个项目迭代器

<?php
$workspaces = $client->workspaces->findAll();
foreach ($workspaces as $workspace) {
    var_dump($workspace);
}

内部迭代器可能会执行多个HTTP请求，每页请求的结果数量由 page_size 选项控制。

原始API

您还可以使用原始API一次获取一页数据

<?php
$offset = null;
while (true) {
    $page = $client->workspaces->findAll(null, array('offset' => $offset, 'iterator_type' => null, 'page_size' => 2));
    var_dump($page);
    if (isset($page->next_page)) {
        $offset = $page->next_page->offset;
    } else {
        break;
    }
}

贡献

请随意fork并提交代码的pull请求！请按照现有代码作为样式示例，并确保所有代码都通过lint和测试。

开发

git clone git@github.com:Asana/php-asana.git
composer install
phpunit --configuration tests/phpunit.xml

代码生成

特定的Asana资源类（如Tag、Workspace、Task等）是生成代码，因此不应手动修改。有关详细信息，请参阅asana-api-meta仓库。

部署

仅仓库所有者。执行以下步骤发布库的新版本。

将所需更改合并到master分支并提交。
克隆仓库，在master上工作。
在VERSION文件中将包版本升级以指示语义版本更改。
提交更改。
使用v加上您在文件中设置的相同版本号对提交进行标记。git tag v1.2.3
将更改推送到origin，包括标签：git push origin master --tags

其余的将由Composer / Packagist自动完成。访问asana包以验证包已发布。

weborganiser / asana

维护者

详细信息