There are many ways to contribute to the PHP programming language. You can contribute by writing code, reporting bugs, helping other users on the mailing lists, writing documentation etc. This article is a guide to start documenting for PHP. I think that one of the reasons that PHP is so widely used is because of the quality and completeness of the PHP manual.

The documentation team can't keep up with the code that is being written for PHP, so a lot of functionality that is available in PHP (or its extensions) is still undocumented. This is especially true for functions and modules that were added to PHP in the last couple of years. I think that it is important to create proper documentation, because otherwise the new functionality will only be used by experienced PHP developers that are aware of the existence of the undocumented functionality.

How to start?

To start writing documentation you should think about what PHP functions, classes or extensions that you want to write documentation for. I think one can have several motives to start writing documentation for PHP. This list might help you decide what you want to document about, but is by no means complete.

• You've used an extension in PHP that you've gotten pretty familiar with, but the documentation of this extension is incomplete.
• You've encountered one or more bugs in the current documentation that you want to correct.
• You want to contribute to PHP because you use PHP a lot, but you are not comfortable with programming in C. In this case the pages undocumented functions in the PHP manual or missing examples in the PHP manual are a good place to start.

After you've decided what you want to document, it's time to read the PHP documentation howto. This howto is not a definitive guide to start writing documentation for PHP, but it should be sufficient to get you started. The documentation team has switched to SVN a few months ago so there might be some references to CVS in the howto.

After you've read the basic principles of the PHP documentation process, you can introduce yourself on the phpdoc mailinglist and start submitting patches to this list.

Karma

You need to earn some karma before you will receive direct write access to the phpdoc SVN Repository. To earn karma you can join the discussions on the phpdoc mailinglist and start submitting patches to the documentation on the list. After you've earned some karma you can apply for a SVN account.

Translating the manual

The PHP manual is available in many different languages. If you're not a developer, you can still contribute to the PHP documentation by translating the manual into your own language. You can start by posting a message to the phpdoc mailinglist in which you introduce yourself. It is also possible to subscribe yourself to a language specific mailing list. All documentation related mailing lists start with "php.doc.", you can view the available lists at news.php.net. Additional information can be found in the PHP wiki item "Working with translations".

What you should know about the PHP Manual

Note that this information can also be found in the PHP wiki and elsewhere on the net, but I thought it could be useful to summarize it here.

• The PHP manual is written in docbook XML format with a few enhancements that are PHP manual specific.
• The PHP documentation source resides in the "phpdoc" SVN module from the PHP SVN Repository.
• PhD is the PHP tool that converts the docbook xml files to the various output formats of the PHP manual (currently PHP, HTML, PDF, CHM and man pages can be generated). Information about using PhD on windows can be found in an excellent blog post called "Setting up PhD on Windows" by Elizabeth Marie Smith.
• The PHP manual is generated on a weekly base. The version that's used by the documentation team is updated four times a day and can be found at http://docs.php.net/.
• If you happen to work for a hosting provider, you can help the PHP Community by mirroring the PHP Manual for your country.

Today a colleague at work ran into a problem when trying to store file contents into a MySQL database table. We are using this solution for quite some time now and it has always worked pretty good for documents and files up to 15 MB. The main reason for us to put files in the database is that it is easier to migrate a website to another server because the database contains all the data that we need.

The problem appeared at a customers' webserver that is running Fedora. First we thought there must be something wrong with our PHP code. But as the code worked fine on our servers (Debian) we soon found out that we couldn't store more than 1 MB in our content field in the database. After a little more investigation the only solution to the problem seems to be raising the mysql system variable max_allowed_packet to a value that is bigger than the largest content that should go into a single field.

For Debian the default max_allowed_packet size is 16 MB, but since the max_allowed_packet is not set for Fedora, MySQL defaults to 1 MB. We have no access to the MySQL server configuration so we had to solve problem this on the client side (our PHP code). An example of how this can be done is given here.

$fileName = '/file/name/of/uploaded/file.bin';
$fileSize = filesize($fileName);

// $db holds the (ADODB) database connection
// Fetch current packet size
$packetSize = (int) $db->GetOne('SELECT @@max_allowed_packet');
if ($packetSize < $fileSize + 2048) {
	$sql = sprintf('SET @@max_allowed_packet=%d', $fileSize + 2048);
	$db->Execute($sql);
}

$db->Execute('INSERT INTO `file`(`filename`, `filesize`) VALUES(?, ?)', array($fileName, $fileSize));
$fileId = $db->Insert_ID();

// Here you can store the file contents in database
$handle = fopen($fileName, 'r');
while (($data = fread($handle, 524288)) && strlen($data) > 0) {
	// Update record with chunks of 512K, until the file is completely in the database
	// This prevents PHP from running out of memory
	$sql = sprintf(
		'UPDATE `file` 
		SET `contents` = CONCAT(`contents`, ?) 
		WHERE `id` = ?');
	$this->db->Execute($sql, array($db->Quote($data), $fileId));
}
fclose($handle);

// now set the  max_allowed_packet back to old value
$sql = sprintf('SET @@max_allowed_packet=%d', $packetSize);
$db->Execute($sql);

It is possible to store values up to 1 GB in a field in MySQL (as 1 GB is currently the maximum allowed packet size). It is however not advisable to use the above method using CONCAT to put large files in the database, CONCAT gets very slow when the size of the blob gets bigger. If you want to put large files in the database you probably want to take a look at the LOAD_FILE function. This is however more complex if MySQL doesn't run on the same server as your PHP code is running on.

As you can see in the above PHP code the following MySQL queries can be used to retrieve and set the max_allowed_packet variable for the current connection.

-- Fetch maximum allowed packet size (in bytes)
SELECT @@max_allowed_packet;

-- Set maximum allowed packet size (in bytes)
SET @@max_allowed_packet=33554432;

We use the following table definition to store the files (I have left out some unimportant fields).

CREATE TABLE `file` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `filename` varchar(255) NOT NULL,
  `filesize` varchar(50) NOT NULL,
  `contents` longblob NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=InnoDB CHARSET=utf8