Installing phpDocumentor should be easy. At least, I read here and there in the Internet, besides of course in the official website, that you have many options to install it, one easier of the previous one!
So I was absolutely confident that in a bunch of minutes I'd have been able to run phpDocumentor and create the documentation for my new Php class.
Do you know? I was wrong. This is what happened.
The first thing I tried it has been to use the .phar file. I know the first way they suggest is to use PEAR, but I have had a positive experience about using .phar files just a day before: I wanted to have php-cs-fixer setup and running in Atom and after several attempts I ended up using php-cs-fixer.phar file. So, when ti came the moment to install phpDocumentor I told myself: "why should I have to struggle with the command line, dependencies issues and the rest when I can just download a single, wonderful file and put in my php directory?" Done! Once I had phpDocumentor.phar installed, I have opened the command prompt directly in my class folder and typed
phpdoc -d "." -t "./docs"
Could not open input file: "phpDocumentor.phar"
Wooops, what's this? Started googling a bit, but with no success, so I sadly abandoned the .phar file and I went on with Composer. worst than before!
phpdoc is not recognized as an internal or external command
To Google or not to Google? No, I don't want to waste time to understand why something is told to work doesn't work (not talking about Composer itself, which is a great tool I use in several occasions, just talking about installing phpDocumentor via Composer). Filed attempt.
I always had good experience installing php extensions through PEAR so I thought it would have worked even installing phpDocumentor. I typed the following command and I eagerly awaited the response:
pear channel-discover pear.phpdoc.org pear install phpdoc/phpDocumentor
Wow, everything seemed to go fine! Once the process has finished, I have done another attempt to create my documentation typing the usual command:
phpdoc -d "." -t "./docs"
Aaarrghhh!!! The command prompt window has been filled with a lot of warnings and errors related to Smarty templates!
I will spare you the details. I just say that thirty/forty minutes of googling gave me the solution: downloading the version 2.9.0 directly from Github. I went to https://github.com/phpDocumentor/phpDocumentor2/releases/tag/v2.9.0 and clicked to the compressed file with the name phpDocumentor-2.9.0.tgz to download it and... Don't ask me why, maybe that day I was terribly unlucky, but the download was terribly slow, it stopped several times and once it has been completed, the archive was corrupted!
Fortunately I have found another website which allows to download that file: https://fossies.org/linux/www/phpDocumentor-2.9.0.tgz/. Finally, I've got the file. I put it in a temporary folder, opened the command prompt and simply typed:
pear install phpDocumentor-2.9.0.tgz
A small adjustement to the file phpdoc.bat is still missing. Go in your php folder (In my Windows 10 partition I have installed xampp, so my php is located in C:\xampp\php folder) and open phpdoc.bat with a text editor. It should look like this:
@echo off if "%PHPBIN%" == "" set PHPBIN=php.exe if not exist "%PHPBIN%" if "%PHP_PEAR_PHP_BIN%" neq "" goto USE_PEAR_PATH GOTO RUN :USE_PEAR_PATH set PHPBIN=%PHP_PEAR_PHP_BIN% :RUN "%PHPBIN%" "%PHP_PEAR_BIN_DIR%\phpdoc" %*
Just change the last line replacing "%PHP_PEAR_BIN_DIR%\phpdoc" with the plain full path to your phpdoc file. In my case, the resulting phpdoc.bat file looks liek this:
@echo off if "%PHPBIN%" == "" set PHPBIN=php.exe if not exist "%PHPBIN%" if "%PHP_PEAR_PHP_BIN%" neq "" goto USE_PEAR_PATH GOTO RUN :USE_PEAR_PATH set PHPBIN=%PHP_PEAR_PHP_BIN% :RUN "%PHPBIN%" "C:\xampp\php\phpdoc" %*
That's all, now it works! And I've got my full documentation with my favourite template:
phpdoc -d "." -t "./docs" --template="responsive-twig"
If you have found useful this article, please share it through your social networks. If you want to leave me a comment, I'll be happy to hear from you!