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("我的应用程序"，$searchpath);

"我的应用"是您应用的名称；这将被传递给由认证器创建的任何Google_Client。

$searchpath是搜索认证文件的路径数组。相对路径相对于当前用户的家目录解析。默认的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 Group Controller是实际与Google API通信的对象。始终使用批量模式；您可以自行管理批量对象，如下所示

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

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

创建组对象并更新它

Groups对象负责评估新状态与当前状态的不同之处。然后它指导控制器做出必要的更改，以将当前状态更新为新状态。

$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 / hierarchical-group-email

维护者

详细信息