phpmd

PHPMD

PHPMD является дочерним проектом PHP Depend и призван стать PHP-эквивалентом известного Java-инструмента PMD. PHPMD можно рассматривать как удобное интерфейсное приложение для потока необработанных показателей, измеряемых PHP Depend.

https://phpmd.org

Установка

См. https://phpmd.org/download/index.html.

Использование командной строки

Введите phpmd [filename|directory[,filename|directory[,...]]] [report format] [ruleset file] , то есть:

 mapi@arwen ~ $ phpmd php/PDepend/DbusUI/ xml rulesets.xml

А файл набора правил rulesets.xml может выглядеть так:

<? xml version = " 1.0 " ?>
< ruleset name = " My first PHPMD rule set "
         xmlns = " https://phpmd.org/xml/ruleset/1.0.0 "
         xmlns : xsi = " http://www.w3.org/2001/XMLSchema-instance "
         xsi : schemaLocation = " https://phpmd.org/xml/ruleset/1.0.0
                       http://phpmd.org/xml/ruleset_xml_schema_1.0.0.xsd "
         xsi : noNamespaceSchemaLocation = "
                       http://phpmd.org/xml/ruleset_xml_schema_1.0.0.xsd " >
  < description >
    My custom rule set that checks my code...
  </ description >

  < rule ref = " rulesets/codesize.xml " />
  < rule ref = " rulesets/cleancode.xml " />
  < rule ref = " rulesets/controversial.xml " />
  < rule ref = " rulesets/design.xml " />
  < rule ref = " rulesets/naming.xml " />
  < rule ref = " rulesets/unusedcode.xml " />
</ ruleset >

Отчет xml будет выглядеть следующим образом:

<? xml version = " 1.0 " encoding = " UTF-8 " ?>
< pmd version = " 0.0.1 " timestamp = " 2009-12-19T22:17:18+01:00 " >
  < file name = " /projects/pdepend/PHP/Depend/DbusUI/ResultPrinter.php " >
    < violation beginline = " 81 "
               endline = " 81 "
               rule = " UnusedFormalParameter "
               ruleset = " Unused Code Rules "
               externalInfoUrl = " https://phpmd.org/rules/unusedcode.html#unusedformalparameter "
               priority = " 3 " >
      Avoid unused parameters such as '$builder'.
    </ violation >
  </ file >
</ pmd >

Вы можете передать в PHPMD разделенную запятыми строку со списком имен файлов или имен каталогов, содержащую исходный код PHP.

Дистрибутив PHPMD Phar включает файлы набора правил в свой архив, даже если приведенный выше параметр «rulesets/codesize.xml» выглядит как ссылка на файловую систему.

Параметры командной строки

• Обратите внимание, что вывод по умолчанию осуществляется в формате XML, поэтому вы можете перенаправить его в файл и XSLT или что-то еще.

• Вы также можете использовать сокращенные имена для ссылки на встроенные наборы правил, например:

   phpmd Размер кода PHP/Depend/DbusUI/xml
  

• Интерфейс командной строки также принимает следующие необязательные аргументы:

  • --verbose, -v, -vv, -vvv — Уровень детализации вывода. Будет распечатана дополнительная информация о том, что обрабатывается или кэшируется. Будет отправлено в STDERR чтобы не мешать выводу отчета. text вывод также будет содержать под каждой ошибкой ссылку на документацию по правилу и форматировать местоположение таким образом, чтобы большинство IDE конвертировали его в ссылку для открытия файла в строке ошибки при нажатии.
  • --minimumpriority — порог приоритета правила; правила с более низким приоритетом, чем они, использоваться не будут.
  • --reportfile — отправляет выходные данные отчета в указанный файл вместо целевого объекта вывода STDOUT по умолчанию.
  • --suffixes — разделенная запятыми строка допустимых расширений имен файлов исходного кода, например php,phtml.
  • --exclude — строка шаблонов, разделенных запятыми, которые используются для игнорирования каталогов. Используйте звездочки, чтобы исключить по шаблону. Например *src/foo/*.php или *src/foo/*
  • --strict — также сообщать об этих узлах с помощью аннотации @SuppressWarnings.
  • --ignore-errors-on-exit — завершится с нулевым кодом, даже в случае ошибки.
  • --ignore-violations-on-exit — выйдет с нулевым кодом, даже если будут обнаружены какие-либо нарушения.
  • --cache — включит кэш результатов. По умолчанию будет .phpmd.result-cache.php в текущем рабочем каталоге.
  • --cache-file — в сочетании с --cache переопределит путь к файлу кэша результатов по умолчанию .phpmd.result-cache.php на заданный путь к файлу.
  • --cache-strategy — устанавливает стратегию кэширования, чтобы определить, является ли файл еще свежим. Либо контент, основанный на содержимом файла, либо временная метка, основанная на временной метке изменения файла.
  • --generate-baseline — создаст файл phpmd.baseline.xml для существующих нарушений рядом с файлом определения набора правил. Пути к файлам нарушений будут относиться к текущему рабочему каталогу.
  • --update-baseline — удалит все нарушения из существующего файла phpmd.baseline.xml , который больше не существует. Новые нарушения _не_ добавляются. Путь к файлу нарушений будет относиться к текущему рабочему каталогу.
  • --baseline-file — путь к пользовательскому базовому XML-файлу. Если его нет, по умолчанию будет phpmd.baseline.xml
  • --color — включить цвет вывода, например, средство рендеринга текста будет отображать имя правила желтым цветом, а описание ошибки — красным.
  • --extra-line-in-excerpt — указать, сколько дополнительных строк добавляется в фрагмент кода в формате html

  Пример командной строки:

   phpmd Размер кода XML PHP/Depend/DbusUI --reportfile "phpmd.xml" --суффиксы "php,phtml"
  

  Опции могут быть до или после аргументов. Их можно отделить от значения либо пробелом, либо знаком равенства ( = ). Таким образом, следующий синтаксис эквивалентен предыдущему:

   phpmd --reportfile="phpmd.xml" --suffixes="php,phtml" Размер кода XML PHP/Depend/DbusUI
  

  Строки, начинающиеся с - будут распознаваться как имена опций. Если у вас есть аргументы, начинающиеся с - , сначала установите параметры, а затем используйте -- чтобы отметить явное начало или список аргументов:

   phpmd --reportfile "phpmd.xml" --suffixes "php,phtml" -- -foo/Folder размер кода xml
  

Использование нескольких наборов правил

PHPMD использует так называемые наборы правил, которые настраивают/определяют набор правил, которые будут применяться к тестируемому источнику. Дистрибутив PHPMD по умолчанию уже поставляется с несколькими наборами по умолчанию, которые можно использовать «из коробки». Вы можете вызвать инструмент PHPMD cli с именем набора, чтобы применить эту конфигурацию:

 ~ $ phpmd /путь/к/размер кода исходного текста

Но что, если вы хотите применить к вашему источнику более одного набора правил? Вы также можете передать список имен наборов правил, разделенных запятой, в инструмент PHPMD cli:

 ~ $ phpmd /путь/к/исходному тексту, размер кода, неиспользуемый код, именование

Вы также можете смешивать файлы собственных наборов правил со встроенными наборами правил:

 ~ $ phpmd /путь/к/размеру кода исходного текста,/my/rules.xml

Вот и все. Благодаря такому поведению вы можете указать собственную комбинацию наборов правил, которые будут проверять исходный код.

Использование нескольких исходных файлов и папок

PHPMD также позволяет вам указать несколько исходных каталогов, если вы хотите создать один вывод для определенных частей вашего кода.

 ~ $ phpmd /путь/к/коду,index.php,/другое/место/с/кодом размер текстового кода

Или используйте шаблон glob:

 ~ $ phpmd src/main/php/*/*/*{Renderer,Node}.php текст my/rules.xml

Сканировать вход

PHPMD также может читать стандартный ввод stdin:

 ~ $ cat src/MyService.php | phpmd — текст my/rules.xml

Таким образом, сканируемый PHP-код может быть сгенерирован другой программой, и не обязательно хранить его в файле.

Коды выхода

Инструмент командной строки PHPMD в настоящее время определяет четыре различных кода выхода.

• 0. Этот код выхода указывает, что все работает как положено. Это означает, что ошибок/исключений не было и PHPMD не обнаружил нарушений правил в тестируемом коде.
• 1. Этот код выхода указывает на то, что произошло исключение, которое прервало выполнение PHPMD.
• 2. Этот код выхода означает, что PHPMD обработал тестируемый код без возникновения ошибки/исключения, но обнаружил нарушения правил в анализируемом исходном коде. Вы также можете предотвратить такое поведение с помощью флага --ignore-violations-on-exit , который приведет к 0, даже если будут обнаружены какие-либо нарушения.

• 3. Этот код выхода означает, что один или несколько тестируемых файлов не могут быть

  быть обработан из-за ошибки. Также могут быть нарушения в других файлах, которые можно было бы обработать корректно.

Рендереры

На данный момент PHPMD поставляется со следующими рендерерами:

• xml , который форматирует отчет в формате XML.
• текст , простой текстовый формат.
• html , один HTML-файл с возможными проблемами.
• json форматирует отчет JSON.
• ansi — формат, удобный для командной строки.
• github — формат, который понимает GitHub Actions.
• gitlab — формат, который понимает GitLab CI.
• sarif — формат обмена результатами статического анализа.
• checkstyle , формат XML, не зависящий от языка и инструмента

Базовый уровень

Для существующих проектов может быть создан базовый уровень нарушений. Все нарушения этого базового показателя будут игнорироваться при дальнейших проверках.

Рекомендуемый подход — файл phpmd.xml в корне проекта. Чтобы создать рядом с ним файл phpmd.baseline.xml :

 ~ $ phpmd /путь/к/исходному тексту phpmd.xml --generate-baseline

Чтобы указать собственный базовый путь к файлу для экспорта:

 ~ $ phpmd /путь/к/исходному тексту phpmd.xml --generate-baseline --baseline-file /путь/к/источнику/phpmd.baseline.xml

По умолчанию PHPMD ищет рядом с phpmd.xml phpmd.baseline.xml . Чтобы перезаписать это поведение:

 ~ $ phpmd /путь/к/исходному тексту phpmd.xml --baseline-file /path/to/source/phpmd.baseline.xml

Чтобы очистить существующий файл базовых показателей и удалить только несуществующие нарушения:

 ~ $ phpmd /путь/к/исходному тексту phpmd.xml --update-baseline

PHPMD для предприятия

Доступно как часть подписки Tidelift.

Разработчики PHPMD и тысяч других пакетов сотрудничают с Tidelift, чтобы обеспечить коммерческую поддержку и обслуживание зависимостей с открытым исходным кодом, которые вы используете для создания своих приложений. Экономьте время, снижайте риски и улучшайте работоспособность кода, платя при этом специалистам по сопровождению именно тех зависимостей, которые вы используете. Узнать больше.

Содействие

Если вы хотите внести свой вклад в PHPMD, обратитесь к руководству по вкладам.