PHP

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

Installation and configuration

• PHP ships by default two versions of the php.ini configuration file, one suited to development and the other to production. On Gentoo you can control which file gets installed by setting PHP_INI_VERSION="production" for instance in /etc/make.conf.

PHP Versions and Evolution

• PHP 5.2.4 needs *a lot more* memory than previous versions (even 5.2). From PHP 5.2.4+ you should allocate at least 128M of memory to your scripts. The default in PHP 5.2 was only 16M.

Escaping / Encoding Strings

• Beware of the magic quotes for G/P/C: you may need to use stripslashes() if you don't want them. This can easily happen when you serialize something for example, and send the string to a remote server.

• Also do not forget that urlencode can be very useful. Else strings containing characters such as & will pose problems.

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.

PHP and File system functions

• When opening a file for reading and writing, the mode is "r+" !! Not "rw" as one would expect.

$file = fopen($filename, "r+");

Libraries

SimpleXML

• This library allows you to do XML parsing/writing, if the operations you need are not too complex.
• Very important note: cast your objects to strings when you send SimpleXML objects to functions that expect a string. Else everything will fail; SimpleXML objects are not strings. This is true with attributes or values of XML nodes.

XML Support

• PHP does have XSLT support, DOM support and XPath support, starting with PHP 5. XSLT support is achieved through libxslt and the XSL extension.

Smarty

• A very useful directive is include:

{include file='header.tpl' title=$title }

This would include the header template, assigning to title the current value of the title variable. Note that you can assign the output of an include to a variable.

• To access the array element myArray["myKey"] in Smarty, write myArray.myKey.

XDebug

• An useful library to profile the performance of your code. Also adds some nice debugging features (stacktrace etc).

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.

• Update: apparently on Windows too the configuration file my.ini would be read by the PHP extensions.

• When using MySQLi extension, persistent connections to the database are not supported which means that a database connection always dies at the end of the script execution. Apparently MySQL has some support for persistent connections, but since it is deprecated, a modern approach would be to use the PDO (PHP Data Objects) driver. This driver supports persistent connections and other advanced features.

• On Gentoo, to get MySQL working via the PDO extension, you need both the pdo and mysql USE flags. Note that mysqli is not used by pdo, so you really need the mysql one.

Hints and tips

• Use bin2hex() to obtain the hexa representation of a string. Useful to debug some encoding problems.

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). The documentation is available here.
  • 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.