PhpDocumentor for Laravel 5.7/6.x

Question

This might be a very newbie question but, how exactly do you use phpDocumentor to generate your docs through Laravel? In my Laravel project there's no phpdoc in the vendor/bin directory, and trying to install phpDocumentor via composer fails (as suggested on the GitHub page).

I couldn't find any recent resources about it, the only thing I had luck with is running the phpDocumentor.phar file from the terminal, but the newest version fails immediately.

Karl Hill · Accepted Answer · 2020-12-13T20:09:12.417

4

To get this working, downgrade to PHP 7.1. Then download the latest phpDocumentor.phar file from [http://www.phpdoc.org/phpDocumentor.phar]. Place the phpDocumentor.phar into your Laravel 6.x project's /vendor/bin/ directory.

Then use Homebrew to install other needed packages...

brew install intltool
brew install graphviz

Lastly, cd into /vendor/bin and run...

php phpDocumentor.phar -d  ../../app/Http/Controllers

Your documentation output should be at /vendor/bin/output.

edited Dec 13 '20 at 20:09

answered Jan 26 '20 at 19:57

Karl Hill

12,937
5
58
95

Thanks for the reply! I'll test it today or tomorrow, and if it works, I'll accept it as the answer – Narc0t1CYM Jan 28 '20 at 09:18
Unfortunately it still throws a lot of errors and I'm not sure if it's because the version of php we use is 7.2.24. This is one of the types of error it throws: Warning: count(): Parameter must be an array or an object that implements Countable in phar:///Applications/MAMP/htdocs/www/website/vendor/bin/phpDocumentor.phar/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1293 Call Stack: 0.0712 2222752 1. {main}() /Applications/MAMP/htdocs/www/website/vendor/bin/phpDocumentor.phar:0 0.0735 2217872 2. – Narc0t1CYM Jan 28 '20 at 15:58
1

@Zh4rsiest Right, you'd have to downgrade to 7.1 to get rid of those count() warning messages. However, they are just warning messages, not errors... you should still be able to get your documentation output. – Karl Hill Jan 28 '20 at 16:15
Indeed, but - which I haven't mentioned - I already could do the export before with the phpDocumentor2 phar file, but the documentation was a mess, because these warning take up a whole page. Anyways, I'll accept your answer, but for the sake of other people, edit the part about downgrading, so they won't get these warning messages :) – Narc0t1CYM Jan 29 '20 at 13:09

TechNerd · Answer 2 · 2020-11-22T07:24:34.807

Adding a more complete solution that worked for me on creating documentation of my Laravel project with the system environment comprising of MacOS Catalina,Laravel 6 and PHP 7.2.

Visit https://docs.phpdoc.org/3.0/guide/getting-started/installing.html. To install the dependencies, recommended to update homebrew as brew update and brew upgrade. After updating the homebrew, execute the following: brew install graphviz brew install plantuml
Once the dependencies are installed, download the phpDocumentor.phar from the above link, and make the file executable as follows: chmod +x phpDocumentor.phar Then, copy and paste this file to your laravel app under /vendor/bin I also placed this file under local bin mv phpDocumentor.phar /usr/local/bin/phpDocumentor for easier access (as shown in step 6 below).
For testing purpose, create a simple test.php file under /vendor/bin/docs/test.php directory with the following content as mentioned in https://docs.phpdoc.org/3.0/guide/getting-started/your-first-set-of-documentation.html

<?php

    /**
     * This is a DocBlock.
     */
    function associatedFunction()
    {
    }

Then execute the phpdoc script from the same /vendor/bin location as: phpDocumentor.phar -d docs/test.php -t docs/test This will generate several files.
Open the index.html file generated in your web browser (eg. Chrome) to view the documentation: open -a "Google Chrome" ./docs/test/index.html
Notably, because we placed the phpDocumentor.phar in /usr/local/bin/phpDocumentor/phpDocumentor.phar, we can easily access phpdoc and easily create the documentation of our whole App as follows ( the documentation will be stored inside the folder DOCS) phpDocumentor.phar -d app/ -t DOCS/

score 0 · Answer 3 · edited Dec 02 '21 at 03:41

I have found the problem with most PHP documentation solutions is they require large amounts of code just to get something you can actually use. And that takes a lot of time and trial and error to set up.

I also have issues with the generated documentation. Often it is not even sorted! Also it is hard to navigate and understand the whole class. As a consumer of a class, you are not interested in private or even protected things (unless you are trying to extend it). But often the docs only show you the methods and properties of the current class, and not what it inherits (which is the WHOLE point of OO!).

Anyway, I got sick of the current state of PHP documentation and decided to do it right. I wrote PHPFUI/InstaDoc to address all the issues I had with existing solutions. InstaDoc is the fastest document generator out there because it simply scans the class directory structure and saves it off. This generally only takes a few seconds (for large code bases) each time you generate (on release, or if you add a new class in your dev env). Then it renders the docs for a specific class at runtime, because, hey, who ever looks at the documentation anyway? Just us nerds, and there are not many of us, and we can wait a fraction of a second for the server to generate the docs on the fly. Also you don't need server disk space to store all your docs. They are generated on the fly. And of course if you have a high volume site, InstaDoc can generate static HTML files, but who has a high volume PHP doc site (like nobody).

Anyway, check out a live example at PHPFUI/InstaDoc and see if it fits your needs. It is not a Laravel module or plug in, but you should be able to run it under Laravel easily. Just return the output of the controller in your controller, and it should just work.

PhpDocumentor for Laravel 5.7/6.x

3 Answers3