空

这个插件什么…也没做。真的！

这是设计用于编写插件的起点，具有非常有用的脚本默认值和一些建议。如果您正在寻找插件的可能性，请查看:doc:示例插件<../example/index>。

新建插件

提供了一个用于创建新插件的实用程序脚本 - “plugin.sh”。您将使用插件名称，版本，可选择的路径来调用它：

$ ./plugin.sh MyGreatPlugin 0.0.1

该脚本将对您提供的名称进行审查和小写，将模板文件复制到新目录中，然后进行一些替换。

使用没有目标参数的脚本，它将创建你的目录插件，``mygreatplugin``就在它自己的目录旁边。否则，它将在指定的路径中创建新目录：

$ ./plugin.sh MyGreatPlugin 0.0.1 /path/to/glpi/plugins/

更新现有插件

没有自动更新现有插件的方法，因为要处理的案例太多。但不要担心，程序很简单;）

使用空功能就像创建一些文件一样简单：

  • composer.json,
  • .travis.yml,
  • Robofile.php,
  • .gitignore.

如果您还没有任何composer或travis配置文件，则可以从空插件中复制那些文件。在你``composer.json``中，只需添加：

{
  "minimum-stability": "dev",
  "prefer-stable": true
}

然后运行``composer require glpi-project/tools``。

在travis配置文件中，只需添加CS调用：

script:
  - vendor/bin/robo --no-interaction code:cs

在``.gitignore``文件中，添加以下内容：

dist/
vendor/
.gh_token
*.min.*

至于Robo.li配置文件，请注意嵌入空插件的那个有点特别，你必须编辑它才能使它正常工作。有关更多信息，请参见下文。

最后，由于``tools``项目将为您提供一些功能，您可以删除重复的工具脚本（例如``release``，extract_template.sh，…等文件）。

特征

编码标准

GLPI PHPCodeSniffer rulesets以``vendor/glpi-project/coding-standard/GlpiStandard/``的形式提供。

检查编码标准，只需使用Robo.li任务``code:cs``：

$ ./vendor/bin/robo code:cs

注解

上面的命令将忽略``vendor``并在当前目录上运行。

如果你想修改忽略列表或检查目录，你可以在插件的``RoboFile.php``中覆盖``$csignore``和/或``$csfiles``：

<?php

class RoboFile extends Glpi\Tools\RoboFile
{
   protected $csignore = ['/vendor/', '/lib/'];
   protected $csfiles  = ['./', 'setup.php.tpl']
   [...]
}

自动检查

为了方便；还提供了``.travis.yml``文件，设置为：

  • 检查编码标准，
  • 在不同的配置上运行堆

您仍然必须从网站启用travis-ci构建才能激活自动化测试。

当然，``.travis.yml``文件可能原型；您可以运行单元测试，创建/更新数据库，激活通知等。请参阅`Travis-CI文档<https://docs.travis-ci.com/>`_了解更多信息。

Minifying CSS and JS

警告

Disabled as of 0.1.13, because libs used from Robo are out of date and connot be replaced.

使用`Robo.li <http://robo.li>`_提供了一个方便的脚本。``RoboFile.php``文件是一个空类，它扩展了``GlpiToolsRoboFile``（由``glpi-project/tools``依赖提供），你可以在其中设置自己的东西。

这样，您可以非常轻松地更新公共文件并使您自己的任务保持不变。

要安装所需的库，你必须“安装镜像<http://getcomposer.org>`_然后运行：

$ composer install -o

有三个目标：

  • ``minify``将缩小所有CSS和JS文件（见下文），
  • minify：css``将缩小插件的``css``目录中的所有css样式表文件，创建一个.min.css``版本以及原始文件，
  • minify:js``将缩小插件的``js``目录中的所有javascript文件，创建一个.min.js``版本以及原始文件。

只需选择目标，然后执行以下操作：

$ ./vendor/bin/robo minify:css

注解

请记住，不应在存储库源上提交已编译的文件。这是一个缩小文件的发布过程。

还记得调整你的脚本，以便加载如果可用的缩小版本，原来的版本:）

截至GLPI 9.2；使用``add_css``和``add_javascript``挂钩时，你不必关心加载缩小的文件！你只需要调用不缩小的脚本；如果存在，则GLPI将使用缩小版本，如果不存在，则使用“DEBUG”模式。

翻译

GLPI及其插件使用gettext进行国际化。在此之前需要执行几个步骤：

1 必须从源文件中提取1个可翻译的字符串，相应地创建或更新``POT``文件，2 ``PO``文件必须从``POT``文件创建或更新，3``PO``文件必须翻译，4``MO``文件必须从最新的``PO``编译。

在``vendor/bin``目录中，你会找到一个``extract_template.sh``脚本。这旨在从源代码中提取可翻译的字符串（请参阅上面的第一点）。

一旦运行，将创建/更新``locale/mygreatplugin.pot``文件。

对于第二步和第三步，您必须做出选择。您可以使用gettext工具更新``PO``文件并使用专用工具进行翻译，例如`poedit <https://poedit.net/>`_;或者你可以使用在线翻译系统，如`Transifex <http://transifex.com/>`_或`Zanata <http://zanata.org/>`_。GLPI核心和许多现有插件现在都使用Transifex进行翻译。

一旦获得更新的``PO``文件，就必须将它们编译为``MO``文件。你可以手动运行它，发布脚本会再次编译它们；请参阅:ref:编译MO文件部分<compile_mo>。

发布脚本

在``vendor/bin/plugin-release``中提供了一个发布脚本。这是一个“简单的”Python script；你应该在系统上安装Python（默认安装在大多数Linux发行版上）。

警告

Note that the release script is only compatible if you use semantic versionning!

仅使用默认值，脚本将尝试检索git存储库中的最新标记，添加第三方依赖项并在github项目上创建“Release”：

$ ./vendor/bin/plugin-release
Do you want to build version 1.9.5? [Yes/no] y
Building glpi-order-1.9.5...
Archiving GIT tag 1.9.5
Adding vendor libraries
$ ls dist
glpi-order-1.9.5.tar.bz2  glpi-order-1.9.5.tar.bz2.asc

要求

您将需要安装python解释器以及以下模块：

  • termcolor,
  • gitdb,
  • github <https://github.com/PyGithub/PyGithub>`_（在草稿中检查现有版本，并创建github版本），除非你使用`–nogithub``选项

如果你想获得有关脚本的帮助，请尝试运行``./vendor/bin/plugin-release -h``。

进程

发布过程将为您完成以下任务：

  • 检查版本常量是否与您请求的标记相同；
  • 检查网站XML文件中的版本是否与您请求的标记相同；
  • 检查版本是否已存在，本地和远程（假设您的项目托管在* pluginsGLPI *组织中，并且该版本是公开的）;
  • 制作一个未被排除的路径的`git archive`（.git，tools，tests，…）;
  • 如果有的话，请安装composer依赖项;
  • 如果有的话，编译你的``MO``文件;
  • 如果有的话，编译你的CSS样式表和Javascript文件（使用`Robo.li <http://robo.li>`_）;
  • 创建一个包含所有这些的发布存档；这将在``dist``目录中提供；
  • 使用GPG对存档进行签名。

注解

标准的发布过程不能直接对你的文件起作用，它会在``dist/src``目录中复制。唯一的例外是:ref:MO编译选项<compile_mo>。

在进行实际发布之前检查是否一切正常；创建你的标签并在推动你的标签**之前运行`./vendor/bin/plugin-release -C`` **。这样，您就可以解决潜在问题并在本地重新创建标记（请记住，发布的标记应该永远不会被删除）。

编译MO文件

发布过程将自动编译它将在``locales``目录中找到的每个``PO``文件。但是你可能希望源包含最后的``MO``文件，用于测试目的。发布脚本提供``–compile-mo``（或``-m``）来实现：

$ ./vendor/bin/plugin-release --compile-mo

警告

以上命令将直接对您的插件文件起作用；不像其他命令那样在副本上。

预览版

默认情况下，发布脚本仅适用于现有标记。任何预发布都应该有自己的标签；但在某些情况下，您可能希望创建没有任何标记的版本存档。

为了告诉发布脚本它应归档的内容，您必须指定几个参数：

  • --commit``（或-c``）给出提交哈希，
  • --release``（或-r``）给出发布版本（通常，它将是下一个发行版本），
  • --extra``（或-e``）指定一个额外的字符串（例如* alpha ， beta ， rc1 *等…）

作为* order *插件的示例：

$ ./vendor/bin/plugin-release --commit 632d515d4ac0 --release 1.9.5 --extra alpha1
$ ls dist
glpi-order-1.9.5-alpha1-20161103-632d515d4a.tar.bz2

签署版本

使用GPG密钥签名版本将允许用户在安装之前检查下载完整性。您需要向用户公开提供GPG密钥；默认情况下会激活sign选项，您可以使用``–nosign``（或``-S``）选项取消激活。

将在``dist``目录中创建一个包含与具有“.asc``扩展名的存档同名的签名的文件。

GitHub发布

发布脚本将在您的GitHub存储库上创建一个发布版本，除非您使用``–nogithub``（或``-g``）选项。

注解

不幸的是，我无法将新创建的档案上传到这个新版本……也许这可以在将来修复。

要使用此功能，您需要安装`github <https://github.com/PyGithub/PyGithub>`_；你需要一个访问口令。访问口令对每个用户有效，并提供对其所有存储库的访问权限。

您必须访问个人访问令牌选项卡<https://github.com/settings/tokens>`_中的`github帐户设置页面。单击*生成新令牌*，给出您想要的描述，并确保您只检查* public_repo *框（无需检查任何其他内容，如果需要，您可以创建多个访问令牌）。

令牌只会显示一次；将它存储在插件目录中的``.gh_token``文件中；结束！

Excluding files

You can create a .ignore-release file at the root of your plugin and list here files and directories you want to explicitely exclude from the release archive. Write one expression per line

.+\.png
screenshots/

Some files will automatically be excluded:

  • .git*,
  • .gh_token
  • .tx/
  • tools/
  • tests/
  • .atoum.php
  • .travis.yml
  • .circleci/
  • .ignore-release
  • composer.lock
  • Robofile.php

|CC-BY-NC-ND|