README

此包是 UNCG Canvas API PHP 库包的 Laravel 包装器，因此可以在 Laravel 应用中使用 Canvas API PHP 库。

安装

1. composer require uncgits/canvas-api-wrapper-laravel
2. 如果您正在运行 Laravel 5.4 或更低版本： 将 Uncgits\CanvasApiLaravel\ServiceProvider::class, 添加到您的 config/app.php 文件中
3. 运行 php artisan vendor:publish --provider='Uncgits\CanvasApiLaravel\ServiceProvider' - 以发布 canvas-api.php 配置文件
4. 在您的 .env 文件中设置环境凭据，并在 config/canvas-api.php 中设置配置选项

依赖

此包依赖于 uncgits/canvas-api-php-library 和 standaniels/flash

快速入门

配置和 .env 设置

您需要在发布的 canvas-api.php 文件中填写您环境的相关详细信息。这里的关键是您可能需要使用多组凭据，因为 Canvas 为每个客户端提供了生产、测试和测试实例。您应该查看配置文件中的默认占位符，并将 mydomain 替换为您的 Canvas 域名（例如，对于 'myschool.instructure.com' 使用 'myschool'）。此外，您还需要修改对 .env 变量的引用，使其更有意义。示例

// config/canvas-api.php

'configs' => [
    'myschool' => [
        'production' => [
            'class' => \App\CanvasApiConfigs\Myschool\Production::class,
            'host'  => env('CANVAS_API_MYSCHOOL_PRODUCTION_HOST'),
            'token' => env('CANVAS_API_MYSCHOOL_PRODUCTION_TOKEN'),
            'proxy' => [
                'use'  => env('CANVAS_API_MYSCHOOL_PRODUCTION_USE_HTTP_PROXY', 'false') == 'true',
                'host' => env('CANVAS_API_MYSCHOOL_PRODUCTION_HTTP_PROXY_HOST'),
                'port' => env('CANVAS_API_MYSCHOOL_PRODUCTION_HTTP_PROXY_PORT'),
            ],
        ],
    ]
]

设置配置类

根据 uncgits/canvas-api-php-library 包的文档，为要与此包一起使用的每组 Canvas 凭据设置一个配置类。建议使用 App\CanvasApiConfigs 命名空间。在这里，您很可能需要使用 config() 指令回滚到 canvas-api.php 配置文件。示例

// app/CanvasApiConfigs/Myschool/Production.php

<?php

namespace App\CanvasApiConfigs\Myschool;

use Uncgits\CanvasApi\CanvasApiConfig;

class Production extends CanvasApiConfig
{
    public function __construct()
    {
        $this->setApiHost(config('canvas-api.configs.myschool.production.host'));
        $this->setToken(config('canvas-api.configs.myschool.production.token'));

        if (config('canvas-api.configs.myschool.production.proxy.use', false)) {
            $this->setUseProxy(true);
            $this->setProxyHost(config('canvas-api.configs.myschool.production.proxy.host'));
            $this->setProxyPort(config('canvas-api.configs.myschool.production.proxy.port'));
        }
    }
}

.env 变量

至少，您应该添加计划与该库一起使用的环境（们）的主机和令牌信息。

注意：不要在主机信息中使用协议（http:// 或 https://）

CANVAS_API_MYDOMAIN_PRODUCTION_HOST=
CANVAS_API_MYDOMAIN_PRODUCTION_TOKEN=

设置默认客户端和适配器

在 canvas-api.php 配置文件中，填写 defaults 下的两项。 defaults.config 应指向同一文件中的另一个配置键，该键指向您要使用的 configs 中的条目。 defaults.adapter 应指向您要使用的适配器类（可以使用 ::class 语法或完整的字符串名称）。

完成此步骤后，您应该可以开始使用 Canvas API 进行调用了！

用法

在进行以下操作之前，请确保您已阅读并熟悉了 uncgits/canvas-api-php-library 包的详细信息。

使用外观

此包装器包的推荐用法涉及 CanvasApi 顶级外观。请注意，这要求您在每个调用上设置所使用的客户端（例如，账户、用户等），但是

$result = \CanvasApi::using('accounts')->listAccounts();

实例化 CanvasApi 类

如果您愿意，可以实例化 Uncgits\CanvasApiLaravel\CanvasApi 类并在该实例上设置客户端类，以便更好地保持持久性

$api = new Uncgits\CanvasApiLaravel\CanvasApi; // Config and Adapter classes are pulled in based on defaults in the config file
$api->setClient(new Uncgits\CanvasApi\Clients\Accounts); // this is not discernable via a default setting, so it must be set.

$result = $api->listAccounts();

配置选项

日志记录

如果您想实现日志记录或闪存消息等，建议创建一个监听器，将其挂钩到 ApiRequestFinished 事件，然后从那里执行日志记录/消息等逻辑。

缓存

为了提高速度、遵守速率限制以及整体性能，本库中内置了缓存功能。这利用了Laravel的缓存机制（就像日志一样，可以在Laravel配置中随意设置）。您可以通过在.env文件中添加CANVAS_API_CACHING=off来选择性地禁用此功能。

缓存TTL

默认情况下，缓存的TTL设置为10分钟，但您可以通过在.env文件中添加CANVAS_API_CACHE_MINUTES=x来设置缓存在x分钟后过期。

缓存的客户端/方法

只针对指定的客户端/方法进行缓存，并且仅在GET请求时生效（显然，您不会想要缓存旨在实际修改Canvas中信息的请求，如POST、PUT或DELETE请求）。

要指定应该缓存的客户端，请使用canvas-api.php配置文件中的cacheable_calls数组。

'cacheable_calls' => [
    // use the Client as the key for an array entry
    'Uncgits\CanvasApi\Clients\Accounts' => [
        // list each method name you wish to cache here. aliases need to be listed separately!
        'listAccounts',
        'getSingleAccount',
        'getAccount', // an alias for getSingleAccount - needs to be listed here as well
    ],

    // to cache all GET transactions made with a client, just use an asterisk instead
    'Uncgits\CanvasApi\Clients\Users' => ['*']
],

确定是否使用了缓存

此包中的CanvasApi类将返回一个扩展了原始类的CanvasApiResult类，并添加了两个属性：$source和$cacheKey。您可以使用标准获取器getSource()和getCacheKey()在对象上访问这些属性。

绕过缓存

在单个API调用中，您可以通过链式调用withoutCache()来绕过缓存，无论应用程序的整体设置如何。

事件

当API事务开始时，将触发ApiRequestStarted事件。类似地，当结果返回时，将触发ApiRequestFinished事件。默认情况下，没有设置任何内容来监听这些事件，但您可以根据需要在应用程序中监听它们。

如上所述，监听器是实施日志记录或其他记录API请求/结果的好地方。

验证规则

默认情况下提供了一些验证规则作为示例，说明您可以向表单中添加哪些内容。您可以自由扩展这些规则或编写自己的规则；对于额外的规则，欢迎提交拉取请求！

贡献

请随时提交拉取请求以帮助改进此包或修复问题。

许可

有关许可权利和限制，请参阅LICENSE文件（BSD）。

有问题？有疑虑？

请使用此存储库的问题跟踪器来报告错误。对于与安全相关的问题，请直接联系its-laravel-devs-l@uncg.edu，而不是使用问题跟踪器。

版本历史

1.0.2

• 更新说明以增强清晰度

1.0.1

• 将BSD许可信息添加到composer.json

1.0

• 官方开源许可

0.2.5

• 修复了AllUsersExistInCanvas规则中文件名称的问题

0.2.4

• 为UserExistsInCanvas规则添加了指定要使用的登录ID的能力
• 在UserExistsInCanvas规则中添加了更明确的失败消息

0.2.3

• 修复了UserExistsInCanvas规则，以明确使用Users客户端。

0.2.2

• 由于我们已经在遵循PSR-4声明，因此进行了更改

0.2.1

• 修复了在开启缓存时进行API调用的错误

0.2

• 添加了对最大结果（限制结果集大小）的支持

0.1.2

• 需要canvas-api-php-library的编号版本 - 目前为0.5

0.1.1

• 修复了一个在缓存中不会正确传递未序列化结果到事件类的错误，导致PHP警告

0.1

• 首次发布。