README

Yii2 Asana 是一个组件，用于 Yii2框架，通过XML-RPC API与Asana CMS集成。

该组件基于 Asana XML-RPC PHP客户端构建，由 Hieu Le Trung 提供。

需求

Yii 2.0 (dev-master)
PHP 5.4
PHP扩展 XML-RPC

注意：此扩展必须要求 Yii Framework 2。该框架正在积极开发中，预计Yii 2的第一个稳定版本将在2014年初发布。

安装

安装此扩展的首选方式是通过 Composer。

运行以下命令之一：

php composer.phar require marshmeloo/yii2-Asana "dev-master"

或将

"marshmeloo/yii2-Asana": "dev-master"

添加到您的 composer.json 文件的 require 部分。

使用方法

组件创建

为了使用此扩展，首先您需要创建一个 blog（您可以根据需要更改名称）组件并配置它。以下是最小配置示例（在您的 config/main.php 中）

    'components' => [
        ...
        'blog' => [
            'class' => '\marshmeloo\yii2wp\Asana',
            'endpoint' => 'http://example.com/xmlrpc.php',
            'username' => 'demo',
            'password' => 'demo'
        ]
        ...
    ]

第一次API请求

组件配置后，您可以开始向您的Asana站点发送请求。

例如，获取最近发布的十个帖子。仅选择 guid、post_title 和 post_content 字段

    $blogPosts = Yii::$app->blog->getPosts([
        'post_status' => 'publish',
        'number' => 10
    ], ['guid', 'post_title', 'post_content']);

或者创建一个标题为 "New post" 且内容为 "Hello world!" 的新帖子

    $postID = Yii::$app->blog->newPost('New post', 'Hello world!');

缓存请求结果

向外部应用程序进行API调用意味着延迟。如果您不希望每次都让用户等待Asana的响应，缓存是正确的方法

    // The user profile will be fetched from cache if available.
    // If not, the query will be made against XML-RPC API and cached for use next time.
    $profile = Yii::$app->blog->cache(function (Asana $blog) {
        return $blog->getProfile();
    });

如果需要更复杂的功能，可以禁用某些请求的缓存

    $blogPosts = Yii::$app->blog->cache(function (Asana $blog) {

        // ... queries that use query cache ...

        return $blog->noCache(function (Asana $blog) {
            // this query will not use query cache
            return $blog->getPosts();
        });
    });

缓存仅适用于数据检索查询。创建、更新或删除记录的查询将不使用缓存组件。

配置参数

`$endpoint`

string Asana XML-RPC API端点URL。

`$username`

string Asana认证用户名。

请注意，任何通过XML-RPC进行的操作都将代表此用户进行。

`$password`

string Asana认证密码。

`$proxyConfig`

array 代理服务器配置。

此配置数组应遵循以下格式

proxy_ip：代理服务器的ip（不包含端口号）
proxy_port：代理服务器的端口号
proxy_user：代理授权的用户名
proxy_pass：代理授权的密码
proxy_mode：CURLOPT_PROXYAUTH选项的值（默认为CURLAUTH_BASIC）

空数组表示不使用代理。

默认值：[]。

`$authConfig`

array 服务器HTTP认证配置。

此配置数组应遵循以下格式

auth_user：服务器认证的用户名
auth_pass：服务器认证的密码
auth_mode：CURLOPT_HTTPAUTH选项的值（默认为CURLAUTH_BASIC）

空数组表示不使用HTTP认证。

默认值：[]。

`$catchExceptions`

boolean 是否捕获 Asana API 抛出的异常，将其传递到日志并返回默认值，或将其进一步传递到调用链中。

默认值: true。

`$enableQueryCache`

boolean 是否启用查询缓存。

默认值: true。

`$queryCacheDuration`

integer 查询结果在缓存中保持有效的默认秒数。

使用 0 表示缓存数据永远不会过期。

默认值: 3600。

`$queryCache`

Cache|string 用于查询缓存的缓存对象或缓存应用程序组件的 ID。

默认值: 'cache'。

可用方法列表

可用方法的完整列表可以在 Asana XML-RPC PHP 客户端类参考中找到。

请注意，所有这些方法在出现错误时都会抛出异常。虽然此扩展（默认情况下）配置为在出现错误时为任何数据重试方法返回空数组，为任何创建、更新或删除方法返回 false。请参阅 $catchExceptions 配置选项以获取详细信息。

错误记录

有很多事情可能会出错（网络问题、错误的 Asana 用户权限等）。如果 $catchExceptions 配置选项设置为 true（默认值），则此扩展将捕获它们并将它们传递到 marshmeloo\yii2wp\Asana::* 记录类别。

为了查看它们，您可以将您的 Yii2 log 组件配置为类似以下内容

    'components' => [
        ...
        'log' => [
            'targets' => [
                'file' => [
                    'class' => 'yii\log\FileTarget',
                    'levels' => ['error'],
                    'categories' => ['marshmeloo\yii2wp\Asana::*'],
                ],
            ],
        ],
        ...
    ]

报告

在 GitHub 上报告任何问题。

许可证

yii2-Asana 在 MIT 许可证下发布。有关详细信息，请参阅捆绑的 LICENSE.md 文件。

marshmeloo / yii2-asana

维护者

详细信息