README

组件管理器是一个辅助Moodle学习环境打包和管理的工具。

关键概念

有关销售点，请参阅演示和幻灯片。

• 包仓库包含有关组件的元数据。这些元数据描述了组件本身，并包含有关插件可用版本以及获取它们的方法的信息。
• 组件源描述了获取组件的可能位置，无论是源形式还是分发形式，并基于包仓库提供的数据进行组装。
• 包源定义了可以从特定类型的源（例如版本控制系统、从仓库下载的存档文件）获取组件的策略。
• 版本控制实现允许我们从各种不同的源下载和检出组件的特定版本。

许可

组件管理器在GPL v3的条款下发布。这是与Moodle核心分发相同的许可。

要求

• PHP >= 5.6
• Moodle >= 2.7

安装

组件管理器可以通过多种不同的方式安装，每种方式都适用于不同的用例。

全局，通过CGR（推荐）

CGR提供了一个安全的选择，用于全局要求包，通过沙箱化单个包及其依赖项。此方法适用于大多数用户。

1. 使用composer global require consolidation/cgr全局要求CGR。
2. 使用cgr lukecarrier/moodle-componentmgr安装组件管理器。

全局，通过Composer

在此配置中，组件管理器在shell上可用（通过您首选的$SHELL或命令提示符），并且所有项目使用相同的安装。此方法不建议用于组件管理器，因为全局要求带有依赖项的包可能会引起依赖问题。

1. 为您的平台安装PHP。
2. 按照他们的入门指南安装Composer。我们假设您可以在shell上启动composer。
3. 确保Composer的全局vendor/bin目录在您的PATH中

• 在Linux/Mac上，这可能是$HOME/.composer/vendor/bin
• 在Windows上，这通常是%APPDATA%\Roaming\Composer\vendor\bin

1. 使用composer global require lukecarrier/moodle-componentmgr全局安装组件管理器

本地，通过Composer

在此配置中，组件管理器在shell中无法全局访问，因此只能通过手动将bin目录添加到您的PATH或指定componentmgr可执行文件的完整路径来执行package操作。

$ composer require lukecarrier/moodle-componentmgr

手动（适合开发）

组件管理器还可以就地运行。建议在组件管理器内部进行开发时使用此功能。

1. 将此存储库克隆到您的磁盘上的某个位置。
2. 确保我们的bin目录位于您的系统PATH中。
3. 在存储库中运行composer install以获取依赖项。

install用法

在此模式下，组件管理器从Moodle站点的根目录启动。它从当前工作目录读取项目文件和项目锁定文件，然后从指定的包存储库部署指定的组件。此模式旨在用于开发环境。

在您的Moodle项目根目录中创建一个componentmgr.json文件。此文件，称为项目文件或清单，包含安装您的平台所需的所有插件及其关联版本的摘要。

为了使组件管理器能够获取您的插件，您需要明确指定哪些位置应被视为包存储库。这些在项目文件的"packageRepositories"部分声明，并使用您将用于在组件条目中引用它们的别名进行索引。至少，它们将包含一个"type"，但其他实现可能还需要其他选项。

要使用Moodle.org/plugins存储库，您需要在项目文件中包含以下部分

{
    "packageRepositories":
    {
        "moodle":
        {
            "type": "Moodle"
        }
    }
}

其他包存储库可供使用，允许从企业版本控制和分发系统部署。目前

• 可以使用"Filesystem"在本地磁盘上查找组件。
• "Git"允许您直接指定本地和远程Git存储库URI。
• "Github"允许组件管理器查询指定每个组件的"repository"属性的GitHub.com存储库。为了启用更高的API速率限制，请考虑将token字段设置为使用public_repo范围生成的令牌此处。
• "Moodle"允许访问Moodle.org/plugins存储库，通过插件版本（YYYYMMDDXX）或发布名称来对插件进行版本控制。
• "Stash"允许访问Bitbucket Server（原名Stash）部署中的单个项目。项目名称应与组件名称匹配，组件通过Git引用进行版本控制。

您现在可以开始声明组件。组件在项目文件的"components"部分声明，并按其frankenstyle组件名称进行索引。每个组件对象有三个键

• "version"键指定插件版本或发布名称，两者与Moodle的version.php文件保持一致。
• "packageRepository"键指定包存储库，在项目文件的"packageRepositories"部分声明，该存储库应作为此组件的数据源。
• 最后，"packageSource"键指定要获取的组件源类型。目前，以下源可用
  • "Directory"从指定的文件系统位置获取组件。
  • "Git"从指定的Git引用获取组件。
  • "Zip"通过远程位置的zip存档获取组件。

以下是一个示例，展示如何从Moodle.org的压缩分发包中安装版本0.4.0的local_cpd插件：

{
    "components": {
        "local_cpd": {
            "version": "0.4.0",
            "packageRepository": "moodle",
            "packageSource": "Zip"
        }
    }
}

将这些信息整合起来，我们得到一个看起来像下面的componentmgr.json文件：

{
    "components": {
        "local_cpd": {
            "version": "0.4.0",
            "packageRepository": "moodle",
            "packageSource": "Zip"
        }
    },

    "packageRepositories": {
        "moodle": {
            "type": "Moodle"
        }
    }
}

我们现在准备安装插件。首先，我们将让组件管理器从我们配置的软件包仓库中获取所有可用组件的元数据。它将缓存这些数据以节省流量和时间。

$ componentmgr refresh

有了这些数据，我们现在可以通过切换到包含我们的Moodle安装目录并运行安装命令来获取插件。

$ cd ~/Sites/LukeCarrier-Moodle
$ componentmgr install

现在，我们可以选择通过在站点管理下的Moodle通知页面或方便的CLI脚本执行插件数据库升级。

$ php admin/cli/upgrade.php

包的使用

在此模式下，组件管理器可以从任何任意位置启动，并生成包含整个Moodle站点的包。要部署的Moodle和相关组件的版本由项目文件中的一个属性确定。此模式适用于CI和生产环境。

要使用组件管理器打包Moodle版本，您首先需要确定您希望使用的Moodle版本的适当表达式。建议您在这里使用分支，因为组件管理器在安装过程中将在项目锁定文件中固定确切版本。

然后，您需要选择一个安装源。

• "zip"是推荐的选项。组件管理器将从download.moodle.org获取指定的发布存档。这些发布将通过Moodle HQ的测试流程。
• "git"应用于更复杂的配置。

不同安装源对不同版本格式的支持如下：

将这些信息整合起来，您应该在项目文件中放置以下段落：

{
    "moodle": {
        "version": "2.7+",
        "source": "zip"
    }
}

包可以生成以下格式：

• "Directory"简单地复制打包文件到指定的目录。
• "WebDeploy"包使用Microsoft的msdeploy实用程序生成，非常适合在Windows上部署。
• "ZipArchive"包适用于所有部署。

例如，要生成包含您的Moodle站点的通用压缩包，可以运行以下命令：

$ componentmgr package --package-format=ZipArchive \
                       --package-destination=/tmp/moodle.zip \
                       --project-file=moodle.org.json

组件生命周期

组件管理器允许在安装和打包过程的特定阶段运行脚本。这些是：

• build -- 在所有组件都已安装到站点后触发，用于通过包管理器安装客户端依赖项并执行任何构建/压缩资产。

为了利用此功能，在您的存储库顶级创建一个componentmgr.component.json，内容如下：

{
    "scripts": {
        "build": "your command (e.g. npm install && npm run gulp)"
    }
}

您可以使用run-script命令验证构建步骤是否按预期工作，而无需执行安装或打包操作。

$ cd local/componentmgrtest/
$ componentmgr run-script build

开发

里程碑是根据GitHub问题准备的，并使用HuBoard维护。

要将更改合并到组件管理器中：

1. 如果是一个为下一个主要版本的功能，则从 develop 分支创建一个新的分支；如果是错误修复，则从 master 分支创建。
2. 进行您的更改，并提交它们。尽量注意提交信息，不要害怕将特别大或复杂的更改分散到多个提交中。
3. 提交一个 pull request。

测试

组件管理器既经过单元测试也经过集成测试。

集成测试

集成测试是用 ServerSpec 编写的，使用 Test Kitchen 配置在干净的环境中运行，使用 Docker 驱动程序。

要开始，请使用 Bundler 安装 Kitchen 和必要的依赖项。

$ bundle install

然后运行测试

$ bundle exec kitchen test

单元测试

单元测试是用 PHPUnit 编写的。确保已安装 Composer 开发依赖项，然后运行测试

$ vendor/bin/phpunit

这将在 tmp 目录中生成各种覆盖率及通过/失败报告。

请注意，对于平台支持组件的部分测试，在它们未设计的平台上将失败。要排除它们，使用 PHPUnit 的 --exclude-group 开关，针对以下组适当使用

• platform-linux
• platform-windows