Перейти к содержимому
M
Все статьи
Разработка 8 мин чтения

Стандарты кода Moodle: Code Checker, phpcs и что ломается на проверке

Как проверить плагин на соответствие стандартам кода Moodle: Code Checker, phpcs с правилами moodle-cs, moodle-plugin-ci и таблица частых замечаний.

Как проверить плагин на соответствие стандартам кода Moodle: Code Checker, phpcs с правилами moodle-cs, moodle-plugin-ci и таблица частых замечаний.

Проверка стандартов кода — первое, что делает любой, кто принимает плагин в каталог, и первое, что ломается в чужом коде при передаче проекта. В 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 выдаёт сотни замечаний, я не исправляю всё одним коммитом. Порядок такой:

  1. Зафиксировать текущее состояние в git и убедиться, что плагин работает.
  2. Прогнать phpcbf и сделать отдельный коммит «автоисправление стиля», не смешивая его с изменениями логики.
  3. Прогнать тесты и открыть основные страницы плагина.
  4. Исправить оставшиеся ошибки вручную по группам: сначала заголовки и документация, затем имена и структура.
  5. Включить проверку в 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. А если вам нужен аудит чужого плагина на соответствие стандартам, это часть работы по разработке и доработке плагинов.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.