Today I wanted to use the Inotify functions that are supplied by the PECL Package Inotify. It turns out that this PHP extension is not available in the (default) Debian or Ubuntu repositories. Instead of using the PECL command to install the extension, I wanted to create a native package that I could use to install/uninstall the package on multiple servers. This blogpost describes how I did this:

1. Downloading and unpacking the extension

Note that I will create a package for the Inotify extension in this blogpost, but this guide can be applied to any PHP (PECL) extension.

Create a working directory:

mkdir php-notify
cd php-notify

Download the extension:

wget 'http://pecl.php.net/get/inotify-0.1.6.tgz'

Unpack the extension:

tar -zxvf inotify-0.1.6.tgz

The current directory should now contain the extension archive (inotify-0.1.6.tgz) a package.xml file and a directory containing the source of the extension (i.e. inotify-0.1.6). You can verify this with:

ls -las

2. Preparing the extension for packaging

The source code should be in place. Now it's time to prepare the extension for packaging.

3. Creating a package

Now that we have compiled the extension, lets create a package for it! Creating a package is really easy now, all you have to do is issue the checkinstall command, the --install=no parameter prevents the package from being installed immediately. You should run this command as root, because otherwise files could end up having the wrong permissions.

sudo checkinstall --install=no

You can answer with "y" to the question about the ./doc-pak directory that does not exist. After that you can input a description for your extension. Then you're given an overview of the package to be build, you can change any of the properties. Change at least the name of the package, I changed it to "php5-inotify-custom". Hit ENTER to build the package now.

The name of the created package is printed by the checkinstall script (php5-inotify-custom_0.1.6-1_amd64.deb in my case). Now you can install the package with dpkg:

sudo dpkg -i php5-inotify-custom_0.1.6-1_amd64.deb

After installation you can enable the module by creating a new file "/etc/php5/conf.d/inotify.ini" containing the text "extension=inotify.so" (make sure to restart your webserver if needed). If you don't want to create this file manually after installation of the package, read the next chapter.

When you're using a tool such as Puppet to manage your servers you can add this to the list of packages that must be installed.

The system is aware that the package is installed and which version of the package is installed. You can also define the package dependencies for your custom packages.

Checkinstall configfiles bug

After adding the config file (/etc/php5/conf.d/inotify.ini) to the list of files that should be included in the package I started getting warnings when installing (and removing) the package. After some searching, I found a blog entry called Bug in checkinstall regarding conffiles, that explains the warnings and provides a solution for this problem.

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.

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.

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.