Installing and setting up PhpDocumentor HOWTO

From openSUSE

Introduction

So what is PhpDocumentor, what does it do, do you need it?

PhpDocumentor is a PHP based application that creates documentation out of comments in a specific format that you put in your code, but it doesn't do just that. It also analyzes your code and creates a complete hierarchy of how the files relate to each other making it very easy to find the parent of class, or the other way around.. find which classes extend a class (the children of that file). PhpDocumentor was inspired by [JavaDoc] which is similar in function as it creates documentation out of [java] files.

So the question is, are you a PHP programmer that would like to improve upon the documentation of your code? If so then PhpDocumentor is certainly worth a look, you can find the official site at [phpDoc.org].

Some of the advantages are:

• The documentation is close to your code
  • A quick look up takes just a bit of scrolling
  • You're less likely to forget the documentation when updating a file
• It automates a big part of your documentation by examining your code for file/class relations.
• You can export your code in multiple formats
  • PDF
  • HTML (Customizable trough smarty templates)
  • Many others

For an example of what the documentation looks like, take a look at the [site where it came from].

Installation

PEAR

Before we can install PhpDocumentor we will need to install [PEAR] a PHP framework providing many functions, to do so follow the steps below.

1. Start up YaST Control Center
2. Start up Software Management
3. Search for php5-pear and mark it for install
4. Hit Accept

PHP Documentor

We'll need to install three extra packages for phpDocumentor to work

• XML_Util
• XML_Parser
• XML_Beautifier

So we'll install those along with PhpDocumentor all nice and tidy in one command, just follow the steps below.

1. su

2. pear install XML_Util XML_Parser XML_Beautifier PhpDocumentor

   This should produce some output similar to the text below

   downloading XML_Util-1.2.1.tgz ...
   Starting to download XML_Util-1.2.1.tgz (17,729 bytes)
   ......done: 17,729 bytes
   downloading XML_Parser-1.3.1.tgz ...
   Starting to download XML_Parser-1.3.1.tgz (14,565 bytes)
   ...done: 14,565 bytes
   downloading XML_Beautifier-1.2.0.tgz ...
   Starting to download XML_Beautifier-1.2.0.tgz (12,948 bytes)
   ...done: 12,948 bytes
   downloading PhpDocumentor-1.4.2.tgz ...
   Starting to download PhpDocumentor-1.4.2.tgz (2,421,028 bytes)
   .....done: 2,421,028 bytes
   install ok: channel://pear.php.net/XML_Util-1.2.1
   install ok: channel://pear.php.net/XML_Parser-1.3.1
   install ok: channel://pear.php.net/PhpDocumentor-1.4.2
   
   install ok: channel://pear.php.net/XML_Beautifier-1.2.0

   If you get the following error

   PHP Warning: PHP Startup: Unable to load dynamic library '/usr/lib64/php5/extensions/iconv.so' - /usr/lib64/php5/extensions/iconv.so: cannot open shared object file: No such file or directory in Unknown on line 0
   Then please scroll down to "64 bits specific error".

Configuration

phpDocumentor

1. If you ever set your servers root path to another directory you'll need to use that directory for the path instead of the default /srv/www/htdocs/.

   pear config-set data_dir /srv/www/htdocs/

   If it goes well you're shown

   config-set succeeded

Confirming phpDocumentor works

So let's see if our efforts paid off yet, pay a visit to http://127.0.0.1/PhpDocumentor/ and if it went well you'll be shown a pretty welcome page with something like the text below

Welcome to docBuilder.

This is the new web-interface for running, in our opinion, the best in-code documentation compiler there is: phpDocumentor.

What's new in this release? Heaps of things, but here are the headlines:

• Much greater support for PEAR on both windows and linux
• CHM, PDF and XML:DocBook/peardoc2 converters are all stable!
• New tokenizer-based parser is literally twice as fast as the old parser (requires PHP 4.3.0+)
• New external user-level manual parsing and generation allows cross-linking between API docs and DocBook-format tutorials/manuals!
• Color syntax source highlighting and cross-referencing with documentation of source code in HTML, CHM and PDF with customizable templating
• New Configuration files simplify repetitive and complex documentation tasks
• Brand new extensive manual - which can be generated directly from the source using makedocs.ini!
• Many improvements to in-code API documentation including new tags, and better handling of in-code html tags
• New XML:DocBook/peardoc converter makes generating PEAR manual formats easy for PEAR developers along with the --pear command-line switch
• Many new HTML templates, all of them beautiful thanks to Marco von Ballmoos
• A brand new web interface thanks to Andrew Eddie!

Now as for as a how-to use it, the official site has [plenty of good documention].

An example of a command to create documentation (in HTML form in this case)

phpdoc -t /srv/www/htdocs/createthisdir -o HTML:default:default -d /srv/www/htdocs/existingdocumenteddir

You'll obviously need to change the paths to reflect where you want your documentation to be created and from where it should be created.

Ensure that your wwwrun user/www group have write access to the directory you're creating the documentation, if you run into a out of memory error, simply run the command phpdoc and it will inform you about where the configuration file is stored. In this file are instruction on how to increase memory limit.

64 bits specific error

THIS IS ONLY FOR THOSE WHO EARLIER ENCOUNTERED AN ERROR, SKIP IT IF YOU DID NOT GET ANY ERRORS
Somehow a 32 bit version of iconv.so got installed causing the error about a missing 64 bit one. Open up Software Management search for php5-iconv and under the versions tab change it to some source with x86_64 behind it.

pear uninstall XML_Util XML_Parser XML_Beautifier PhpDocumentor

External resources

• Pear.net Home of the pear framework which provides many extra features for PHP
• phpdoc.org Home of PhpDocumentor official website, look here for the documentation/tutorial
• PHP.net The official PHP site