9. Distribution and deployment issues

Now you’ve written your perfect piece of software, your audience eagerly awaits it’s delivery and installation onto their precious machines. Distributing and deploying software comes with its own set of headaches above and beyond those you encountered just writing the damn thing. This chapter covers some of the issues that you may come across when thinking about deployment and distribution of your software, that may vary from the common situation of pushing code to your own server for a PHP website. In particular, we are looking at scenarios where you distribute your software and it is no longer under your direct control and not on your own systems.

9.1 Error handling and logging

You will need to think about how you handle and log errors (and other information) in your scripts when you run with the CLI SAPI. You can use the normal PHP error handling functions and allow PHP to log errors to the file specified in error_log in php.ini. However bear in mind that you may not be able to control which user your software is run under, and so you need to log to an appropriate location where you can be sure your user has appropriate permissions to write to.

One alternative to the standard “log to a file” method in PHP is to instead send errors and other log information to the system’s syslog. In Linux systems this is syslog(3) (man syslog gives more information), in Windows this is the system event log. Using syslog has several advantages :

9.2 Installers and bundling files

In Chapter 3 we looked at different ways to run PHP, but before you can run your PHP scripts you need to get them (and any related assets) onto your target machine. Generic software installer systems are widely available and many platforms have their own software repositories and bundling systems which are well documented, so we won’t cover those in any detail here (although we’ll mention a few good open source ones at the end). Instead, we’ll have a look at a couple of PHP specific options for bundling files and resources ready for distribution and installation.

9.3 Embedded data files at the end of a PHP script

If we just need to include a chunk of data with a PHP script, we can use a language construct introduced in PHP 5.1, the __halt_compiler() instruction. Simply put this at the end of your PHP script, and you can then put anything you want (text strings, binary data, another PHP script etc.) following it. When PHP execution hits the __halt_compiler() line, it simply stops as if it had hit the end of the file itself. This means that whatever follows isn’t executed, and won’t throw any syntax errors or similar. Your script can access the data that follows it by opening a file handle to itself and seeking to the __COMPILER_HALT_OFFSET__ constant which is created when a __halt_compiler() instruction is present. The following example shows the “unbundling” of a text file from a PHP file.

 1 <?
 2 
 3 # Open a pointer to this file using the magic constant __FILE__
 4 
 5 $thisfile = fopen(__FILE__, 'r');
 6 
 7 # Seek down to the 1st byte after the __halt_compiler(); instruction. This
 8 # is contained in the automatically created __COMPILER_HALT_OFFSET__ 
 9 # constant.
10 
11 fseek($thisfile, __COMPILER_HALT_OFFSET__);
12 
13 # Lets grab everything that follows that ...
14 
15 $ourtext = stream_get_contents($thisfile);
16 
17 # and write it out to a new file.
18 
19 file_put_contents('textfile.txt', $ourtext);
20 
21 # Our scripts stops here. 
22 
23 __halt_compiler();The additional content starts here.
24 
25 This is the text file.
26 It would normally cause a PHP fatal syntax error if 
27 this text was simply dumped into a PHP file.

If you run this script, and then look at the created textfile.txt file, you will see that it contains the rest of our script starting with the The additional content starts here line.

Although we’ve used plain text here, as it’s easier to show in a book, there is nothing to stop you adding binary files, PHP files, or even tar/zip archives containing multiple files which your script can save and expand. However if you are intent on including multiple files or large amounts of data, you might want to consider the Phar format option, discussed next.

9.4 Phar executable bundles

Phar bundles are a native PHP way of pulling together lots of files, both PHP code and ancillary data files, into a single file for distribution. Phar bundles are, at their core, either a zip file, tar file or custom phar format file. You can access the individual files in the bundle using the phar stream wrapper as you would a normal file, without having to unbundle the files before use. For example, if you have a bundle called mybundle.phar, you can do :

9.5 Generic installers

9.6 Controlling the (PHP) environment

When you deploy scripts on your own servers or PCs, you can control the environment in which they are deployed. However if you are distributing your software more widely you will suddenly find that environmental factors on external machines can make your PHP scripts misbehave or even stop working completely. Some of the PHP specific environmental factors you need to consider include:

9.7 Extending your application with plug-ins

9.8 Documentation

9.9 Licensing & legal

Warning Note: All the legal information presented below and elsewhere in this book may be incorrect, depends on your jurisdiction, and was believed correct by the non-legally-trained author only at the time of writing. The information is only provided to give you an overview of the topics that you may wish to consider in respect of your particular project. Always consult a qualified legal professional for legal advice. Never drink coffee just before bed.

If you’re coming from a web development environment to, for instance, desktop software development, it is worth taking a moment to think about the consequences and differences in licensing and legal liabilities in your new mode of programming, particularly when programming commercially. With the web, your “product” is usually your website content, not the PHP script itself. Selling software reverses the situation, with your carefully honed PHP code being the saleable commodity and the output belonging to the end users.

9.10 Deploying frameworks