README

这是一个用于 SmarterU LMS API 的 API 客户端。本项目与 Neovation 无关。

要求

PHP 7.4 或更高版本
PHP SimpleXML 扩展已启用

第三方依赖

Guzzle

安装

使用 composer 将库添加到您的项目中。

composer require cbssoftware/smarteru-client

使用方法

类 CBS\SmarterU\Client 用于与 SmarterU API 交互。其构造函数需要两个参数：您的 SmarterU 账户 API 密钥和您的 SmarterU 用户 API 密钥。查找这些密钥的说明可以在这里找到。

use CBS\SmarterU\Client;

$accountAPIkey = 'insert your account API key here';
$userAPIkey = 'insert your user API key here';

$client = new Client($accountAPIkey, $userAPIkey);

以下是在 Client.php 中与 SmarterU API 交互的公共方法列表

有关每个方法的用法细节，请参阅 docs/Client.md。

数据类型

自定义字段是向用户或学习报告分配额外值的方式，这些值除了数据类型内置的值之外。分配自定义字段给用户或学习报告时，所有属性都是必需的。更多信息可以在 docs/DataTypes/CustomField.md 中找到。

外部授权是 SmarterU 在用户从外部网站通过单点登录进行身份验证时返回的信息容器。更多信息可以在 docs/DataTypes/ExternalAuthorization.md 中找到。

在SmarterU中，群组是用户集合，可以将他们分配到相同的培训课程。创建群组时，"groupId"，"userHelpOverrideDefault"，"userHelpEnabled"，"userHelpEmail"，"userHelpText"，"tags"，"userLimitEnabled"，"userLimitAmount"，"subscriptionVariants"和"groupId"属性是可选的。"users"，"permissions"，"oldName"和"oldGroupId"属性将不会使用。所有其他属性都是必需的。如果您想将用户添加到您的新群组中，您可以使用客户端中的addUsersToGroup方法。如果您想授予这些用户在群组中的高级权限，您可以使用客户端中的grantPermissions方法。当更新群组而不更改其名称或ID时，必须设置"名称"或"groupId"属性以标识要更新的群组，并且必须设置的其他属性是您希望更新的属性。群组成员（即"users"和"permissions"）不能使用客户端中的"updateGroup"方法更新，而应依靠它们自己的专用方法。当更改群组的名称或ID时，必须设置"oldName"或"oldGroupId"属性以标识要更新的群组，并设置相应的"名称"或"groupId"属性以标识新值。向SmarterU发出请求将清除"oldName"和"groupId"字段中的任何值，以防止在将同一群组实例用于API的未来请求时错误地使用过时信息。更多信息请参阅docs/DataTypes/Group.md。

学习报告（也称为报名报告）允许培训经理查看已分配给课程的用户的进度，并在课程完成后查看用户的结果。使用客户端中的getLearnerReport方法通过API读取学习报告，该方法将CBS\SmarterU\Queries\GetLearnerReportQuery实例作为参数。所有标记为可空的属性是可选的，而所有未标记为可空的属性是必需的。更多信息请参阅docs/DataTypes/LearningModule.md。

学习模块（也称为课程）是可以分配给群组的培训任务。通过updateGroup方法添加或从群组中删除学习模块时，所有属性都是必需的。通过createGroup方法将学习模块添加到群组时，不使用"action"，而所有其他属性都是必需的。更多信息请参阅docs/DataTypes/LearningModule.md。

订阅变体是分配给群组的订阅记录。通过updateGroup方法添加或从群组中删除订阅变体时，所有属性都是必需的。通过createGroup方法将订阅变体添加到群组时，不使用"action"，而所有其他属性都是必需的。更多信息请参阅docs/DataTypes/SubscriptionVariant.md。

标签是将额外值分配给群组的一种方式，这些值是除数据类型内建值之外的其他值。"tagValues"属性始终是必需的，但"tagName"和"tagId"属性是互斥的。其中之一是必需的。尝试在同一标签实例中设置这两个属性将只保存最近更新的一个，而较早更新的一个将被自动设置为null。更多信息请参阅docs/DataTypes/Tag.md。

用户是SmarterU中用户账户的记录。默认将设置两个值：“状态”将设置为“活动”且“receiveNotifications”将设置为“true”。如果您想将用户设置为不活跃或不接收通知，则必须明确指定。创建用户时，至少必须指定“电子邮件”字段或“employeeId”字段中的一个。如果愿意，可以同时设置这两个字段。“givenName”、“surname”、“password”、“learnerNotifications”、“supervisorNotifications”、“sendEmailTo”、“authenticationType”和“homeGroup”字段是必需的。如果将“sendEmailTo”属性设置为“Alternate”，则必须同时设置用户的“alternateEmail”字段。“Groups”字段不使用。默认情况下，用户将是普通用户，在他们的主组中没有管理权限，并且不是任何其他组的成员。如果您想将用户分配到任何其他组，可以使用Client中的addUsersToGroup方法。如果您希望用户在其任何组中拥有任何管理权限，可以使用Client中的grantPermissions方法授予这些权限。所有其他值都是可选的。在更新用户时，您必须设置“电子邮件”或“employeeId”字段以标识正在更新的用户。除了这些字段外，仅必需的是您希望更新的值。《updateUser》方法不能用于更改用户的组成员资格或更改用户的密码。如果用户是多个组的成员，则可以更改用户的主组。如果您想更新用户的电子邮件地址或员工ID，可以通过将“oldEmail”或“oldEmployeeId”字段设置为当前值，然后将“email”或“employeeId”字段设置为新值来实现。在向SmarterU发出请求时，“oldEmail”和“oldEmployeeId”字段将被设置为null，以防止在将来对同一用户对象发出请求时错误地传递过时的信息。更多信息可以在docs/DataTypes/User.md中找到。

查询

三个Client方法listUsers、listGroups和getLearnerReport分别接受它们各自的CBS\SmarterU\Queries\对象实例作为参数。GetUserQuery和GetGroupQuery仅由Client中的私有辅助方法内部使用，而其他Query类必须由用户处理。在构造要传递给Client的查询时，任何未标记为可空且没有默认值的值都是必需的，而任何标记为可空或有默认值的值都是可选的。SmarterU API将返回一个数组，其中包含符合查询提供条件的每个用户、组或学习报告。

位于CBS\SmarterU\Queries\Tags目录中的类是查询段，用于在查询类中填充某些属性时使用。DateRangeTag使用两个DateTimeInterface对象通过特定时间段过滤查询结果，例如仅返回在提供的日期之间完成的课程的学习报告。MatchTag用于通过组名过滤ListGroups请求的结果，或通过用户的电子邮件地址、员工ID或姓名过滤ListUsers请求的结果。以下示例将仅返回名为John Smith的用户

use CBS\SmarterU\Queries\ListUsersQuery;
use CBS\SmarterU\Queries\Tags\MatchTag;

$matchTag = (new MatchTag())
    ->setMatchType('EXACT')
    ->setValue('John Smith');

$query = (new ListUsersQuery())
    ->setName($matchTag);

此示例将返回任何具有example.com电子邮件地址的用户

use CBS\SmarterU\Queries\ListUsersQuery;
use CBS\SmarterU\Queries\Tags\MatchTag;

$matchTag = (new MatchTag())
    ->setMatchType('CONTAINS')
    ->setValue('@example.com');

$query = (new ListUsersQuery())
    ->setEmail($matchTag);

输出

Client类中与SmarterU API交互的所有方法将返回适当的DataType（即，readUserByEmailAddress方法将返回一个User实例），如果SmarterU API返回多个值，则返回相应类型的数组；如果没有查询到匹配的结果（即在您的SmarterU账户中不匹配任何用户的电子邮件地址），则返回null。有关返回值的更详细说明，请参阅docs/Client.md。

Client类中的一些方法接受特定类型的数组作为参数，例如用户数组。如果提供的输入不是可接受值之一（即包含非User实例的User数组），则会抛出CBS\SmarterU\Exceptions\InvalidArgumentException异常。异常消息将命名触发它的参数。

SmarterU要求在传递给参数的DataType中设置某些属性。由于使用同一DataType的方法的属性可能不同，因此在构造函数中像Client类中的API密钥一样要求这些属性是不切实际的。相反，如果在将DataType传递到Client中的方法时，其中一个必需的属性未设置，则会抛出CBS\SmarterU\Exceptions\MissingValueException异常。异常消息将命名触发它的属性。

如果某种HTTP错误阻止了您的请求执行，将抛出GuzzleHttp\Exception\ClientException。

如果SmarterU API报告失败，将抛出CBS\SmarterU\Exceptions\SmarterUException异常，并将在异常消息中列出SmarterU API返回的任何错误。所有可能的SmarterU错误列表可在此处找到：here。

日志记录

此库使用psr/log库将有关失败请求的信息记录到您选择的记录器。如果使用Client::setLogger()注入了Psr\Log\LoggerInterface实例，则任何失败的请求都将被记录，并且将向记录器发送请求和响应的净化版本。

贡献

如果您想为此库做出贡献，可以使用以下过程

Fork GitHub存储库。
将项目克隆到您的计算机上。
根据您要更改的内容创建一个基于'main'的新分支。
在您的分支上提交您的更改。确保更新受您更改影响的任何单元测试，并为任何新类和/或方法提供测试。
将您的分支推回到Fork。
提交一个针对'main'分支的拉取请求，以便我们可以审查您的更改。

测试

此库附带一组用于与PHPunit一起使用的单元测试。如果您已使用composer安装了开发依赖项，则可以使用提供的vendor/bin/phpunit命令运行这些测试。

composer install
vendor/bin/phpunit

许可证

MIT许可证

凡获得此软件及其相关文档文件（“软件”）副本的任何人，免费许可使用该软件，不受任何限制，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许向软件提供方提供软件的人这样做，前提是遵守以下条件

cbs-software / smarteru-php-client

维护者

详细信息

README

要求

第三方依赖

安装

使用方法

数据类型

查询

标签

输出

日志记录

贡献

测试

许可证

贡献者