Проверка стандартов кода — первое, что делает любой, кто принимает плагин в каталог, и первое, что ломается в чужом коде при передаче проекта. В Moodle для этого есть готовый набор правил для phpcs, а проверять код можно тремя способами: плагином в самой установке, командной строкой или в автоматическом конвейере. Расскажу, чем они отличаются, и какие замечания встречаются чаще всего.
Чем проверять
| Способ | Что это | Когда подходит |
|---|---|---|
| Плагин local_codechecker | страница в админке, проверяет выбранный каталог | разовая проверка на тестовой установке |
Набор правил moodle-cs + phpcs | правила Moodle для PHP_CodeSniffer, ставятся через Composer | локальная работа в редакторе и командной строке |
moodle-plugin-ci | набор команд для CI: линтер PHP, phpcs, проверка документации, Mustache, JS и другие | автоматический прогон при каждом коммите |
Сами правила описаны в кодовом стиле Moodle, репозиторий набора правил — moodlehq/moodle-cs. Для командной строки запуск выглядит так:
vendor/bin/phpcs --standard=moodle local/myplugin
vendor/bin/phpcbf --standard=moodle local/myplugin
Первая команда выводит замечания, вторая автоматически исправляет то, что можно исправить механически (отступы, пробелы, форма массивов). Исправление всегда проверяйте глазами по разнице в git и запускайте после него тесты.
Ошибки и предупреждения
Проверка выдаёт два уровня. Ошибки обязательны к исправлению, предупреждения — рекомендации, но в каталог плагин с большим числом предупреждений принимать не любят. Чистый вывод — нормальная цель для нового кода. Для унаследованного кода реалистичнее убрать ошибки, а предупреждения закрывать по мере правок.
Таблица частых замечаний
| Замечание | В чём дело | Как исправить |
|---|---|---|
| Нет описания файла | в начале файла отсутствует блок с @package, @copyright и @license | добавить стандартный заголовок с GPL-лицензией |
Нет проверки MOODLE_INTERNAL | файл можно открыть напрямую по адресу, в обход Moodle | добавить defined('MOODLE_INTERNAL') || die(); в файлы, которые не подключают config.php |
| Отступы табуляцией | стандарт требует четыре пробела | заменить, а в редакторе включить пробелы |
| Длинные строки | слишком длинная строка кода или комментария | разбить по аргументам и операторам |
Старый синтаксис массива array() | принят короткий синтаксис [] | автоисправление через phpcbf |
| Комментарий не по форме | однострочный комментарий начинается с маленькой буквы или не заканчивается точкой | привести к стандарту оформления |
| Нет документации у класса или функции | отсутствует docblock | описать назначение, параметры @param и результат @return |
Закрывающий тег ?> | в конце PHP-файла он не нужен и опасен лишними пробелами | удалить |
| Пробелы в конце строк | невидимый мусор | включить удаление в редакторе |
| Имена переменных | в имени переменной заглавные буквы или подчёркивания | переименовать в нижний регистр без разделителей |
Точный набор проверок меняется с версиями набора правил, поэтому ориентируйтесь на вывод своей версии, а не на список из статьи.
Пример заголовка файла
Эта часть чаще всего вызывает замечание на новом плагине. Образец:
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Менеджер записей плагина.
*
* @package local_myplugin
* @copyright 2026 Автор
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
Заголовок удобно хранить как шаблон в редакторе, чтобы не набирать каждый раз.
Что проверяет moodle-plugin-ci помимо phpcs
Утилита moodle-plugin-ci собирает проверки в один конвейер. Среди команд, которые я использую: phplint (синтаксис), phpcs, phpdoc (документация), validate (проверка структуры плагина и version.php), savepoints (правильность точек обновления в upgrade.php), mustache (шаблоны), grunt (сборка JavaScript и стилей), а также запуск phpunit и behat. Файл конфигурации для GitHub Actions есть в документации утилиты. Если репозиторий плагина размещён на GitHub, прогон на каждом коммите занимает пару минут настройки и потом работает сам.
Порядок работы с унаследованным кодом
Когда плагин достался от предыдущего подрядчика и phpcs выдаёт сотни замечаний, я не исправляю всё одним коммитом. Порядок такой:
- Зафиксировать текущее состояние в git и убедиться, что плагин работает.
- Прогнать
phpcbfи сделать отдельный коммит «автоисправление стиля», не смешивая его с изменениями логики. - Прогнать тесты и открыть основные страницы плагина.
- Исправить оставшиеся ошибки вручную по группам: сначала заголовки и документация, затем имена и структура.
- Включить проверку в CI, чтобы новые замечания не накапливались.
Отдельный коммит для автоисправления нужен, чтобы в истории изменений логику можно было отличить от пробелов; иначе поиск причины регрессии превращается в чтение тысяч строк.
Что не ловит Code Checker
Стиль не гарантирует безопасность и правильность. Проверка не заметит запрос к базе со строкой, склеенной из пользовательского ввода, или забытую проверку прав. Поэтому после стиля нужны ручной обзор и тесты (см. PHPUnit для плагина Moodle). Правила, на которые я смотрю глазами: вся работа с базой через параметры, ввод — через required_param и optional_param с типом, вывод — с экранированием, на каждой странице и в каждой внешней функции — проверка прав.
Перед публикацией
Настройка в редакторе
Самое дешёвое исправление стиля — то, которое происходит при наборе. В PhpStorm и в VS Code можно подключить phpcs с набором правил moodle и увидеть замечания прямо в строке. Дополнительно в редакторе стоит включить:
- замену табуляции четырьмя пробелами;
- удаление пробелов в конце строки при сохранении;
- перевод строки в конце файла;
- шаблон заголовка файла, о котором речь выше.
После такой настройки основная масса замечаний просто не возникает, и проверка в CI превращается в формальность.
Коммитить ли автоисправления в чужой плагин
Если вы дорабатываете плагин стороннего автора, будьте осторожны с массовым переформатированием: при следующем обновлении плагина из каталога ваши правки конфликтуют с его новой версией. В таком случае стиль чужого кода лучше не трогать, а свои доработки выносить в отдельный плагин или патч. Это тот же принцип, что и для ядра: чем меньше расхождений с оригиналом, тем дешевле обновление.
Какие замечания можно не исправлять
Есть замечания, которые допустимо подавить. Например, в чужой сторонней библиотеке, лежащей в каталоге плагина, стиль Moodle не применяют: такие каталоги исключают из проверки или перечисляют в файле thirdpartylibs.xml, который заодно сообщает о лицензии и версии библиотеки. Отдельные строки можно пометить комментарием, отключающим конкретное правило, но только когда нарушение осознанное и объяснено рядом. Злоупотреблять этим нельзя: рецензент каталога видит такие пометки и вправе потребовать объяснений. В собственном коде проще и честнее исправить замечание, чем оставлять исключение.
Документация в коде: что считать достаточным
Самая объёмная группа замечаний — недостающая документация. Правило простое: у каждого файла есть описание и теги пакета; у каждого класса — назначение в одно-два предложения; у каждой публичной функции — описание, типы параметров и результата. Тип пишут в формате, который понимает редактор (int, string, array, \stdClass, \context), а для массивов уточняют содержимое словами. Писать «получает данные» бесполезно: полезна фраза, в которой названо, что за данные и откуда. Хорошая проверка: прочитайте только документацию функции, не заглядывая в тело. Если вы не можете сказать, что она вернёт при пустом входе, комментарий недостаточен. Языком комментариев может быть русский: стандарт этого не запрещает, но каталог ожидает английских комментариев в публикуемом коде, поэтому для плагинов, которые вы собираетесь выкладывать, пишите на английском.
Отдельное правило — не оставлять закомментированный код и не прятать за комментарием отладочный вывод: var_dump, print_r и die() в рабочем коде вызывают замечания проверки и просто мешают. Перед коммитом найдите их поиском по каталогу плагина.
Если плагин готовится к выкладке в каталог, прогоните его через те же проверки: замечания там увидят в первую очередь. Подробности — в статье про публикацию плагина в каталоге moodle.org. А если вам нужен аудит чужого плагина на соответствие стандартам, это часть работы по разработке и доработке плагинов.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.