phpDocumentor

Tutorial: Install phpDocumentor

Robert AndresenProgramming 2 Comments

I followed the tutorial on phpdoc.org: http://phpdoc.org/docs/latest/getting-started/installing.html#system-requirements.

The phpdoc.org documentation isn’t exactly a beginners tutorial, so I wrote this tutorial for my self and others benifits 🙂

CentOS Server is used in this tutorial!

Requirements are

  • PHP 5.3.3
  • Intl extension for PHP
  • Graphviz

To check for your PHP version, type the following in SSH:

<span style="color: #ff6600;">php -i</span>

To install Intl extension for PHP, type this:

<span style="color: #ff6600;">yum -y install php-intl</span>

For installing Graphviz, type this:

<span style="color: #ff6600;">yum list available 'graphviz*'</span>
<span style="color: #ff6600;"> yum install 'graphviz*'</span>

 

Prepare PEAR:

$ <span style="color: #ff6600;">pear channel-discover pear.phpdoc.org</span>

To install phpDocumentor:

$ <span style="color: #ff6600;">pear install phpdoc/phpDocumentor</span>

 

First error: Fatal error: Allowed memory size….



[root@server ~]# <span style="color: #ff6600;">pear install phpdoc/phpDocumentor</span>
downloading phpDocumentor-2.8.0.tgz ...
Starting to download phpDocumentor-2.8.0.tgz (16,174,605 bytes)
.....................................................................................................................................................................................................................................................................................................................................................................................................done: 16,174,605 bytes
<span style="color: #ff0000;">PHP Fatal error: Allowed memory size of 16777216 bytes exhausted (tried to allocate 64 bytes) in /usr/share/pear/Archive/Tar.php on line 1235</span>

<span style="color: #ff0000;">Fatal error: Allowed memory size of 16777216 bytes exhausted (tried to allocate 64 bytes) in /usr/share/pear/Archive/Tar.php on line 1235</span>

To fix this, edit usr/bin/pear. I right clicked one the file and clicked edit in WinSCP – and changed 16M to 128M.

 

Next error:

Warning: strtotime(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected the timezone 'UTC' for now, but please set date.timezone to select your timezone. in PEAR/Validate.php on line 486
<span style="color: #ff0000;">ERROR: unable to unpack /tmp/tmpfas0UO/phpDocumentor-2.8.0.tgz</span>

We can ignore the timezone-warning for now, but the unable to unpack is because of old PEAR version.

Because I can’t unpack, I need to install/upgrade PEAR with PHAR file.

[root@server ~]# <span style="color: #ff6600;">wget http://pear.php.net/go-pear.phar</span>

--2014-11-06 16:20:55-- http://pear.php.net/go-pear.phar
Resolving proxy.domain.local... 80.xxx.217.xxx
Connecting to proxy.domain.local|80.xxx.217.xxx|:8080... connected.
Proxy request sent, awaiting response... 200 OK
Length: 3673193 (3.5M) [application/octet-stream]
Saving to: `go-pear.phar'

100%[==============================================================================================&gt;] 3,673,193 1.04M/s in 3.4s

2014-11-06 16:20:59 (1.04 MB/s) - `go-pear.phar' saved [3673193/3673193]

[root@server ~]# <span style="color: #ff6600;">php go-pear.phar</span>

Below is a suggested file layout for your new PEAR installation. To
change individual locations, type the number in front of the
directory. Type 'all' to change all of them or simply press Enter to
accept these locations.

1. Installation base ($prefix) : /usr
2. Temporary directory for processing : /tmp/pear/install
3. Temporary directory for downloads : /tmp/pear/install
4. Binaries directory : /usr/bin
5. PHP code directory ($php_dir) : /usr/share/pear
6. Documentation directory : /usr/docs
7. Data directory : /usr/data
8. User-modifiable configuration files directory : /usr/cfg
9. Public Web Files directory : /usr/www
10. Tests directory : /usr/tests
11. Name of configuration file : /etc/pear.conf

1-11, 'all' or Enter to continue:

Beginning install...
Configuration written to /etc/pear.conf...
Initialized registry...
Preparing to install...
installing phar:///root/go-pear.phar/PEAR/go-pear-tarballs/Archive_Tar-1.3.12.tar...
installing phar:///root/go-pear.phar/PEAR/go-pear-tarballs/Console_Getopt-1.3.1.tar...
installing phar:///root/go-pear.phar/PEAR/go-pear-tarballs/PEAR-1.9.5.tar...
installing phar:///root/go-pear.phar/PEAR/go-pear-tarballs/Structures_Graph-1.0.4.tar...
installing phar:///root/go-pear.phar/PEAR/go-pear-tarballs/XML_Util-1.2.3.tar...
install ok: channel://pear.php.net/Archive_Tar-1.3.12
install ok: channel://pear.php.net/Console_Getopt-1.3.1
install ok: channel://pear.php.net/Structures_Graph-1.0.4
install ok: channel://pear.php.net/XML_Util-1.2.3
install ok: channel://pear.php.net/PEAR-1.9.5
PEAR: Optional feature webinstaller available (PEAR's web-based installer)
PEAR: Optional feature gtkinstaller available (PEAR's PHP-GTK-based installer)
PEAR: Optional feature gtk2installer available (PEAR's PHP-GTK2-based installer)
PEAR: To install optional features use "pear install pear/PEAR#featurename"

The 'pear' command is now at your service at /usr/bin/pear

** The 'pear' command is not currently in your PATH, so you need to
** use '/usr/bin/pear' until you have added
** '/usr/bin' to your PATH environment variable.

Run it without parameters to see the available actions, try 'pear list'
to see what packages are installed, or 'pear help' for help.

For more information about PEAR, see:

http://pear.php.net/faq.php
http://pear.php.net/manual/

Thanks for using go-pear!

 

After this, all went great:

[root@server ~]# <span style="color: #ff6600;">pear install phpdoc/phpDocumentor</span>
downloading phpDocumentor-2.8.0.tgz ...
Starting to download phpDocumentor-2.8.0.tgz (16,174,605 bytes)
.........done: 16,174,605 bytes
install ok: channel://pear.phpdoc.org/phpDocumentor-2.8.0

 

To generate documentation:

The basic usage of phpDocumentor is to provide an input location using the command line options (-dfor a directory, -f for a file) and tell it to output your documentation to a folder of your liking (-t).

<span style="color: #ff6600;">phpdoc -d <strong>/path/to/where/your/classes/and/stuff/is</strong> -t <strong>/target/path/in/your/www/folder/somewhere</strong></span>

 

[root@server ~]# <span style="color: #ff6600;">ls -l /target/path/in/your/www/folder/somewhere</span>
total 268
drwxr-xr-x 2 root root 4096 Nov 6 16:49 classes
drwxr-xr-x 3 root root 4096 Nov 6 16:49 css
drwxr-xr-x 2 root root 12288 Nov 6 16:49 files
drwxr-xr-x 2 root root 4096 Nov 6 16:49 font
drwxr-xr-x 2 root root 4096 Nov 6 16:49 graphs
drwxr-xr-x 3 root root 4096 Nov 6 16:49 images
-rw-r--r-- 1 root root 23932 Nov 6 16:49 index.html
drwxr-xr-x 3 root root 4096 Nov 6 16:49 js
drwxr-xr-x 2 root root 4096 Nov 6 16:49 namespaces
drwx------ 2 root root 4096 Nov 6 16:49 phpdoc-cache-05
...
drwx------ 2 root root 4096 Nov 6 16:49 phpdoc-cache-fe
drwxr-xr-x 2 root root 4096 Nov 6 16:49 reports

 

Open directory in web-browser:

phpDocumentor

phpDocumentor

 

Get good documentation:

Read the DocBlock section in phpdoc.org. To get full and good documentation, you need to document your code! As you see in the screenshot above, this is something I have not done yet 🙂

 

Create a config (XML) file for your project:

Documentation: http://phpdoc.org/docs/latest/references/configuration.html

The XML file will tell phpdoc what to document and what not to.

phpdoc.dist.xml

&lt;?xml version="1.0" encoding="UTF-8" ?&gt;

&lt;phpdoc&gt;
&lt;parser&gt;
&lt;target&gt;/extract/path/app/api&lt;/target&gt;
&lt;/parser&gt;

&lt;transformer&gt;
&lt;target&gt;/extract/path/app/api&lt;/target&gt;
&lt;/transformer&gt;

&lt;files&gt;
&lt;directory&gt;admin/modules&lt;/directory&gt;
&lt;directory&gt;lib/common/modules&lt;/directory&gt;
&lt;directory&gt;lib/common/php_functions&lt;/directory&gt;
&lt;/files&gt;

&lt;extensions&gt;
&lt;extension&gt;php&lt;/extension&gt;
&lt;extension&gt;php3&lt;/extension&gt;
&lt;extension&gt;phtml&lt;/extension&gt;
&lt;/extensions&gt;
&lt;/phpdoc&gt;

You can also ignore folders and files – se phpdoc.org docs.

This file needs to be stored in your project root folder. Navigate to your project root folder in terminal and just run:

$ <span style="color: #ff6600;">phpdoc</span>

 

Sources for app and debugging: