phpDocumentor.phar не создает каталог: ошибка phar на Windows

phpDocumentor is trying to write to a folder inside the PHAR because the
tool mis‑resolves the path to the templates folder when the command is run
from a directory that contains spaces. The short flags (-d / -t) are
accepted, but the argument values are not quoted, so PHP interprets the
space after “Webs” as the end of the path and the rest of the string is
treated as a separate argument. The resolver then constructs a path that
looks inside the PHAR (phar://…/data/templates), and mkdir() fails
because a PHAR archive is read‑only.

Below are the key points that explain why this happens and how to fix it.

Содержание

• Почему phpDocumentor использует каталог внутри PHAR
• Правильный синтаксис команды
• Решения и обходные пути
• Перенос на phpDocumentor 3
• Заключение

Почему phpDocumentor использует каталог внутри PHAR?

When phpDocumentor starts, it resolves the location of its built‑in
templates, which are stored inside the PHAR at data/templates. If the
working directory contains spaces and the argument is not quoted, PHP
splits the path at the first space, and the resulting string is
interpreted as a URL to the PHAR itself (phar://…/data/templates).
Since a PHAR is read‑only, any attempt to create a directory inside it
triggers the error you see:

mkdir(): phar error: cannot create directory "phar://…/data/templates"

This behaviour is documented in the PHP manual’s section on PHAR
paths and has been reported
as a Windows‑specific bug in the phpDocumentor issue tracker
(#1023).

Правильный синтаксис команды

1. Enclose paths that contain spaces in double quotes.

   bash

   php phpDocumentor.phar run \
       -d "D:\Users\Allen\Documents\Websites\My Webs\littlepanda\www\littlepanda\OfficeTools" \
       -t "D:\Users\Allen\Documents\Websites\My Webs\littlepanda\www\littlepanda\office-tools-doc"
   

2. Use the long options for clarity.

   bash

   php phpDocumentor.phar run \
       --directory="D:\Users\Allen\Documents\Websites\My Webs\littlepanda\www\littlepanda\OfficeTools" \
       --target="D:\Users\Allen\Documents\Websites\My Webs\littlepanda\www\littlepanda\office-tools-doc"
   

3. Run the PHAR from its own directory (or set the working directory
   explicitly) to avoid relative‑path confusion:

   bash

   cd "D:\Users\Allen\Documents\Websites\My Webs\littlepanda\www\littlepanda\phpDocumentor"
   php phpDocumentor.phar run -d ..\OfficeTools -t ..\office-tools-doc
   

Решения и обходные пути

Как извлечь PHAR и запустить из распакованной версии

# Извлечь PHAR
phar -x phpDocumentor.phar

# Перейти в каталог, где находится скрипт
cd phpDocumentor/src/phpDocumentor

# Запустить генерацию
php cli.php run -d "..\..\OfficeTools" -t "..\..\office-tools-doc"

Перенос на phpDocumentor 3

phpDocumentor 2 больше не поддерживается, и многие проблемы с PHAR
устранены в версии 3, которая поставляется через Composer и не
использует архив PHAR. Если вы можете перейти на PHP 8.1+ и Composer,
это самый надёжный способ избежать подобных ошибок.

composer require --dev phpdocumentor/phpdocumentor
vendor/bin/phpdoc run --directory="D:\...\OfficeTools" --target="D:\...\office-tools-doc"

Подробнее о миграции см. в официальной справке
(Migration Guide).

Заключение

• Ошибка вызвана тем, что phpDocumentor пытается создать каталог внутри PHAR из‑за некорректного разрешения пути, когда в пути есть пробелы.
• Минимальное исправление: оборачивайте все пути в кавычки и используйте длинные опции (--directory, --target).
• Если проблема сохраняется, извлеките PHAR и запустите из распакованной версии или перейдите на phpDocumentor 3.
• После применения одного из решений генерация документации должна пройти без ошибок, и файлы появятся в указанном каталоге вывода.