README

分层组邮件列表管理
运行测试
基本示例
使用Composer包含此库
配置您的认证信息
准备您的数据
扩展示例
创建服务认证器
认证
创建标准组策略
创建Google Apps组控制器
创建组对象并更新它
调试、记录或提示

组管理

此库协助管理分层组的邮件列表。假定组成员资格将由某些外部系统（例如Drupal）管理；邮件列表本身是在Google Groups for Business（或非营利组织、教育）账户中作为Google组创建的。

假设组层次结构按地区组织（例如，州、县和市）；每个地区称为“分支”。每个分支有许多办事处，每个办事处可以有多个官员（例如，办公人员和助手，联合办事处等）。每个分支办事处都是一个组，每个组恰好有一个电子邮件列表。如果办事处需要多个列表，可以通过创建子办事处来实现，因为办事处也可以是分层的。这仅在需要每个列表的组成员资格不同时才是必要的，因为每个邮件列表可以有任意数量的备用地址，可以使用任意一个地址向列表发送邮件。

对组进行的更新是批量进行的。更新过程大致如下

通过PHP关联数组提供成员数据，该数组定义了组名称和成员电子邮件地址。
预计调用者还将提供类似的数组，其中包含上次更新时从组成员资格数据中缓存的表示。
此类中的更新函数将调用Google API来对组成员列表进行任何必要的添加或删除。

当更新函数运行时，它将根据需要创建、更新和删除组以及组成员，以使Google Groups的成员资格与提供的输入数组中描述的成员资格完全匹配。除了这些组外，还会同时自动创建一些“聚合”组。一个“聚合”组是由其他组完全组成的组。创建了三种类型的聚合组

某一类型的所有官员：为系统中的每个独特类型的官员创建一个聚合列表。例如，创建一个“主席”列表，以联系每个分支的主席。
分支官员：为系统中的每个分支创建一个聚合列表。这个“官员”列表将向该分支的每个官员发送电子邮件。
自定义聚合列表：调用者可以定义可以单地址消息的官员集合。例如，可以定义一个“执行”组，包含主席、财务官员和秘书；在这种情况下，每个分支都会得到一个“执行”邮件列表，这些官员将收到邮件。

这些聚合组将自动管理。

运行测试

此库包含一个测试套件，使用PHPUnit和Prophecy来确保提供的类是正确的。测试使用了Google Apps API，但不向Google发起任何调用，因此只需运行测试不需要设置任何身份验证凭据。

克隆此仓库
运行 composer install
运行 ./vendor/bin/phpunit tests

所有测试在每次提交时也由Travis CI运行。

基本示例

如果遵循以下部分中的说明，以下基本概述中的代码应该可以工作。

use Westkingdom\HierarchicalGroupEmail\GroupsManager;

$groupsManager = GroupsManager::createForDomain('My application', 'mydomain.org', $currentState);
$currentState = $groupsManager->update($newState);

即使使用这个简单的表单，也需要了解这个API如何搜索和使用您的身份验证数据，以及如何管理您数据的状态。下面有更多关于它是如何工作的详细信息。

Composer说明

在您的应用程序中安装此库的最佳方式是使用Composer。只需将以下行添加到您的composer.json文件的require部分

{
  "require": {
    "westkingdom/hierarchical-group-email": "~1"
  }
}

有关使用Composer与流行的内容管理系统相关的信息，请参阅以下资源

当然，您可以在不使用Composer的情况下使用此库；您只需负责设置自动加载器，或者自己包含类文件。但是，强烈建议使用Composer。

配置您的认证信息

遵循授权信息设置说明，这些说明在文档网站上。

准备您的数据

此库期望您将有关所有组及其成员资格的所有信息累积在一个嵌套的层次数组中。

结构如下面的yaml中所示，但您可以根据应用程序的便利性存储在任何格式中。

GROUPNAME:
  lists:
    OFFICENAME:
      members:
        - user1@domain1.org
        - user2@domain2.org
      properties:
        group-name: 'Full name of Office'
  subgroups:
    - subgroup1
    - subgroup2
    - subgroup3

只需为您的组重复此结构。如果您的组具有层次结构性质，只需在每个组的“子组”部分中命名“子组”即可。列出的名称应与用作组数据的“GROUPNAME”键完全匹配。

请注意，跟踪当前状态和新状态的责任在于调用者。组管理器将只发送与旧状态相比发生更改的更改更新。如果您不提供当前状态，则组永远不会被删除，组成员永远不会被移除。

未来：组管理器可以提供一个“导出”函数，通过调用Google API构建组的当前状态。

扩展示例

如果您想要在更新中拥有更多控制权，您可以自己构造内部类并修改它们，然后再创建您的GroupsManager。

use Westkingdom\HierarchicalGroupEmail\ServiceAccountAuthenticator;
use Westkingdom\HierarchicalGroupEmail\StandardGroupPolicy;
use Westkingdom\HierarchicalGroupEmail\GoogleAppsGroupsController;
use Westkingdom\HierarchicalGroupEmail\GroupsManager;

$authenticator = ServiceAccountAuthenticator("My application");
$client = $authenticator->authenticate();
$policy = new StandardGroupPolicy('mydomain.org', $properties);
$controller = new GoogleAppsGroupsController($client);
$groupManager = new GroupsManager($controller, $policy, $currentState);
$currentState = $groupManager->update($newState);

注意：如果您还想要控制批量操作的行为，可以向GoogleAppsGroupsController构造函数提供一个批量对象。下面有详细信息。

创建服务认证器

服务认证器将帮助您的应用程序从众所周知的文件中加载其身份验证凭据信息，因此它们不需要在应用程序源代码中硬编码。

$authenticator = ServiceAccountAuthenticator("My application", $searchpath);

"My application"是您的应用程序名称；这将传递给认证器创建的任何Google_Client。

$searchpath是搜索身份验证文件的路径数组。相对路径相对于当前用户的家目录解析。默认搜索路径是

.google-api
/etc/google-api

认证

$client = $authenticator->authenticate($serviceAccount, $scopes, $serviceToken);

创建标准组策略

$policy = new StandardGroupPolicy('mydomain.org', $properties);

‘mydomain.org’ 是您的 Google Apps 账户的基础域名。 $properties 包含策略中使用的属性的默认值。以下列出了可以设置的、用于自定义库操作的各个属性。

创建Google Apps组控制器

Google Apps 组控制器是实际与 Google API 通信的对象。始终使用批处理模式；您可以根据以下示例自行管理批处理对象。

$batch = new \Google_Http_Batch($client);
$controller = new GoogleAppsGroupsController($client, $policy, $batch);
$groupManager = new GroupsManager($controller, $currentState);
...
// When finished:
$groupManager->execute();

如果您不想管理批处理对象，只需省略这些行，控制器将在需要时创建和执行批处理。这是首选的操作方法；例如，控制器会在运行任何添加成员到组的命令之前，尝试安排运行创建新组的批处理命令；这使得批处理命令更有可能成功完成。

创建组对象并更新它

组对象负责评估新状态与当前状态的差异。然后，它指示控制器进行必要的更改，以将当前状态更新为新状态。

$groupManager = new Groups($controller, $currentState);
$groupManager->update($newState);

更改始终在批处理模式下进行。批处理模式可以由您处理，或者您可以根据上一节中的示例自行控制。

调试、日志记录或提示

如果您想在 GroupManager 执行操作之前了解它将做什么，您可以使用 BatchWrapper 对象。

use Westkingdom\HierarchicalGroupEmail\BatchWrapper;

$client->setUseBatch(true);
$batch = new \Google_Http_Batch($client);
$batchWrapper = new BatchWrapper($batch);
$controller = new GoogleAppsGroupsController($client, $policy, $batch);
...
// To log or prompt or whatever:
$operationList = $batchWrapper->getSimplifiedRequests();

// When finished:
$batchWrapper->execute();

如果您只是进行报告/调试，根本不需要创建 Google_Http_Batch；您只需使用 BatchWrapper 即可。

属性目录

属性可以包含替换项，有两种形式。

$(var)：替换变量的全小写形式
${var}：替换变量名

westkingdom / google-api-extensions

维护者

详细信息