PHP

This page will be a collection of resources on PHP programming.

PHP and HTML

• In modern, UTF-8 encoded XHTML pages, use the PHP function htmlspecialchars to convert a string to a HTML compatible representation. Don't use htmlentities, which would also convert accents, and other stuff that does not need to be converted when using UTF-8. Similarly, use htmlspecialchars_decode.

Libraries

• Regular Expressions in PHP

PHP and MySQL

• The PHP MySQL extensions do *not* read the options from my.cnf to set their default connection charset, nor do they take the server charset as the default connection character set. They use the default character set from libmysql (the MySQL library), which is set at compile-time via a configure option. Generally it won't be UTF-8 (usually Latin-1).

• Exception: on Gentoo, the PHP MySQL extensions were patched to read the my.cnf configuration file, so changing values here will have an effect on the connection charset. This is the only distribution that does that (which is a good thing, in my opinion). More information available on this MySQL bug report. Note also that libmysql on Gentoo is compiled with UTF-8 as the default character set.

Documenting a PHP Project: PhpDocumentor

PhpDocumentor is the equivalent of Javadoc for the PHP language.

• Installation under Gentoo:
  • You can use the ebuild in Portage. However the /usr/bin/pear script is broken and must be fixed else you won't be able to emerge PhpDocumentor. In this script the PHP interpreter is called with a memory_limit argument. Thus it won't use the default memory_limit set in the /etc/php/cli-php5/php.ini file. The memory_limit argument provided in /usr/bin/pear is too low (16M), thus you have to remove it. I consider this a Gentoo/PEAR bug.
  • Be sure to emerge at least PhpDocumentor 1.3.0 (currently in testing as of March 2007), as the RC versions are not stable enough.

• Usage:
  • Just document your source code using the standard PhpDocumentor tags (which are very similar to the Javadoc ones).
  • You can also use *some* HTML tags in your PhpDocumentor docblocks. A list is available here with their meanings here.

• Compiling the source to an output format:
  • Several outputs (HTML, HTML with frames, PDF...) are available. And for each of these outputs, several templates (controlling the style - CSS - and the display of the generated documentation) are available. Some are much better than other. I recommend using the HTML:Smarty:HandS one, which can result in the following shell command:

    phpdoc -d source_dir -t output_dir -o HTML:Smarty:HandS --title "This is the general title."

  • Other good templates include HTML:Smarty:PHP, HTML:frames:phpdoc.de or HTML:frames:l0l33t. Note that you can also generate the documentation from a PHP script running on the web server, but I think it is more convenient to use the command line tool.

• Problems or things I'd like to change:
  • Currently I don't know how to remove line numbers from the generated documentation, although I would prefer not to include them.
  • I don't know how to tell PhpDocumentor that it is supposed to generate UTF-8 pages.