phpDocumentor

Что такое phpDocumentor?

phpDocumentor — это фактически стандарт инструмента документации для PHP-проектов, предлагающий надёжное решение для лёгкого создания исчерпывающей документации. Анализируя исходный код PHP и комментарии DocBlock, phpDocumentor создаёт полный набор документации API, что делает его незаменимым инструментом для разработчиков, стремящихся к созданию ясных и хорошо документированных кодовых баз.

Помимо мастерства в создании документации API, phpDocumentor предлагает дополнительные функции. Он оснащён возможностью создавать диаграммы UML, что делает его универсальным инструментом для визуализации структуры кода. Кроме того, phpDocumentor предоставляет полнофункциональный парсер языка разметки, поддерживающий синтаксис RestructuredText и Markdown. Эта гибкость позволяет вам документировать свой проект с использованием языка разметки, который наилучшим образом соответствует вашим предпочтениям.

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

Вдохновлённый своими предшественниками, phpDocumentor 1 и JavaDoc, phpDocumentor продолжает инновации, оставаясь в курсе последних технологий и особенностей языка PHP. Это обязательство гарантирует разработчикам доступ к наилучшему возможному опыту работы с документацией, соответствующему современным практикам разработки.

В этом руководстве мы рассмотрим различные функции phpDocumentor, от его основной функциональности по созданию документации API до его расширенных возможностей по анализу языков разметки. Независимо от того, являетесь ли вы новичком или опытным разработчиком, phpDocumentor станет вашим союзником в создании хорошо документированных, поддерживаемых и понятных PHP-проектов.

phpDocumentor v3 (стабильный)

v3 — это последний стабильный релиз.

Документация

Для получения более подробной информации вы можете ознакомиться с нашей онлайн-документацией по адресу https://docs.phpdoc.org/.

Функции

phpDocumentor поддерживает следующее:

• Совместимость с PHP 7.0+, предоставляется полная поддержка пространств имён, замыканий и многого другого.
• Docblock над типами, docblocks могут быть более явными в отношении типов, не все форматы поддерживаются нативным php.
• Показывает любой тег, некоторые теги добавляют дополнительную функциональность в phpDocumentor (например, @link).
• Низкое использование памяти, пиковое использование памяти для небольших проектов составляет менее 20 МБ, средних проектов — 40 МБ, а больших фреймворков — 100 МБ.
• Инкрементный анализ, если вы сохранили файл структуры из предыдущего запуска, вы получаете дополнительное повышение производительности до 80% в дополнение к упомянутому увеличению скорости обработки.
• Простое создание шаблонов, если вы хотите сделать брендинг, вам нужно только вызвать 1 задачу и отредактировать 3 файла.
• Двухэтапный процесс, сначала phpDocumentor генерирует кэш со структурой вашего приложения перед созданием вывода. Если вы хотите, вы можете использовать его для питания своих собственных инструментов или средств форматирования!
• Поддержка дженериков, с более статическим анализом в php типы стали более сложными. phpDocumentor понимает эти типы и будет отображать их как первоклассные типы.

Установка

PhpDocumentor требует PHP 8.1 или выше для работы. Однако можно анализировать код более ранних версий PHP.

Все шаблоны, предоставляемые с phpDocumentor, поддерживают диаграммы классов на основе прочитанной кодовой базы. Для этого потребуется... Установка приложения [PlantUml] на машину с phpDocumentor

Рендеринг диаграмм классов с помощью [PlantUml] является опциональным, и предупреждения об отсутствии [PlantUml] можно игнорировать. Однако в этом случае ваша документация будет содержать некоторые неработающие ссылки.

Диаграмма классов будет создана с опцией --setting=graphs.enabled=true.

Существует 4 способа установить phpDocumentor:

1. С помощью phive (рекомендуется).
2. Используя PHAR (ручная установка).
3. Через Docker.
4. Через Composer.

Использование Phive

$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42

Для получения дополнительной информации о phive посетите их веб-сайт. Теперь, когда у вас установлен phpDocumentor, его можно выполнить следующим образом:

php tools/phpDocumentor

С использованием PHAR

1. Загрузите файл phar с https://github.com/phpDocumentor/phpDocumentor/releases.
2. Вы можете выполнить phar следующим образом: php phpDocumentor.phar.

Через Docker

1. $ docker pull phpdoc/phpdoc.
2. $ docker run --rm -v $(pwd):/data phpdoc/phpdoc

Через Composer (не рекомендуется)

Но подождите? Что насчёт композитора?

Ах, вы обнаружили наш секрет. Существует пакет phpdocumentor composer, который вы можете использовать для установки phpDocumentor.

Однако: phpDocumentor — это сложное приложение, и его библиотеки используются в бесчисленных других библиотеках и приложениях (2 из наших библиотек имеют более 150 миллионов загрузок каждая); и это означает, что вероятность конфликта между одной из наших зависимостей и вашей высока. И когда я говорю «высока», это действительно так.

Поэтому из-за вышеизложенного мы не поддерживаем и не активно рекомендуем устанавливать phpDocumentor с помощью Composer.

Как использовать phpDocumentor?

Самый простой способ запустить phpDocumentor — выполнить следующую команду:

$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

Эта команда проанализирует исходный код, предоставленный с помощью аргумента -d, и выведет его в папку, указанную аргументом -t.

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

$ phpdoc run -h

Конфигурационные файлы

phpDocumentor также поддерживает использование конфигурационных файлов (по умолчанию они называются phpdoc.xml или phpdoc.dist.xml). Пожалуйста, обратитесь к документации, чтобы увидеть формат и поддерживаемые опции.

Ночные сборки

У phpDocumentor нет ночных выпусков. Однако во время каждого конвейера создаётся артефакт phar. Если вы хотите протестировать новейшую версию phpDocumentor, загляните в раздел actions этого репозитория. Каждый успешный рабочий процесс QA имеет раздел «Артефакты» внизу с созданным артефактом phar.

Контакты

Связаться с нами легко, и это можно сделать с помощью:

• Twitter: @phpDocumentor.
• Веб-сайта: https://www.phpdoc.org.
• GitHub: https://www.github.com/phpDocumentor/phpDocumentor.
• Электронной почты: mike@phpdoc.org.