1 - Introduction

As this is the primary goal of the PHK project, using a PHK package is generally easy and does not require high skills in PHP. Typically, a PHK archive comes with some information explaining where to save it, and, generally, how to run it.

If it is not the case, if you encounter a problem, or just for the sake of curiosity, you will find below the information you need to run, troubleshoot, and investigate a PHK package.

2 - What you need

2.1 - PHP Version

In order to use a PHK package, you need PHP version 5.1.0 or more.

Unfortunately, if your version is below this requirement, the PHK runtime cannot detect it and display a nice error message. This is because PHK uses the __halt_compiler() feature introduced in PHP 5.1. If, when running a PHK archive, you get a parse error like the one below, please check your PHP version first :

2.2 - php.ini directives

2.2.1 - enable_dl and safe_mode

If the PHK archive requires PHP extensions which are not already loaded, it will try to load them using the dl() function. If enable_dl is off or safe_mode is on, the dl() calls are forbidden and fail, triggering a fatal error.

There are two possible solutions :

• If it is possible in your environment, switch safe_mode off, and/or enable_dl on (in php.ini or through another way),
• or preload the required extension(s) via some 'extension=' directives in your php.ini file.

2.2.2 - Other directives

Every other 'ini' directives should be compatible with PHK. If it is not the case, please tell us.

2.2.3 - HTTP server configuration

This chapter applies only if you want to access a PHK archive in web direct access mode (see the 'access modes' chapter below).

The original extension, for a PHK archive, is '.phk'. But your web server generally does not know that a '.phk' file must be considered as a PHP source file. You have two options here :

• the first one, recommended but not always possible if you don't have full control on your web server configuration, is to configure your server so that it recognizes '.phk' files as PHP source code. The procedure for Apache is to add a line containing : 'AddType application/x-httpd-php .phk'.
• The second one, to use if you cannot have your web server recognize the '.phk' extension, is to add a recognized suffix to your file name, probably '.php', or maybe '.php5'.
  Example : 'PHK_Creator.phk' could become 'PHK_Creator.phk.php'.
  It is better to keep the '.phk' part, because it identifies the file a PHK archive (the risk, if you just replace the 'phk' suffix with 'php', is to have somebody open the file, see the binary content, and throw it away as a corrupted PHP script).

2.2.4 - PHP extensions

If some of the package's subfiles are compressed, you will need the corresponding extension(s) to run it (zlib and/or bz2).

Note that the package cannot start executing until all of its required extensions are present.

3 - What you don't need

You shouldn't need anything else to use a PHK archive. As it was said before, the runtime code is contained in the archive file.

4 - Improving runtime performance

If you are concerned with performance, follow these steps :

1. Install one of the following cache systems in your environment : APC, XCache, or eAccelerator.
2. Install the PHK extension.
3. Install the Automap extension.

There is nothing to configure as these extensions are automatically detected and used by the runtime code. Just add the corresponding entries in your php.ini file, restart your web server, and use a phpinfo() call to check that they are present.

The increase in performance can be very important. The first tests show that small PHP scripts can run more than 100 times faster after the installation of these 3 PHP extensions.

5 - Access modes

As with any PHP source file, there are three ways to access a PHK archive. These modes are detailed here because some of the PHK archive's behaviors depend on the way it is accessed.

5.1 - Included (lib_run)

In this mode, the archive is included from another PHP script. This is the typical mode for a library or a plugin. That's why this access mode is also called 'library' mode.

When a PHK archive is included/required from another PHP script, it will try to execute the script defined by the 'lib_run_script' option (if this option is defined).

5.2 - Run in CLI mode (cli_run)

In this mode, the package is directly run in CLI mode, which typically means :

• on Unix : from the shell,
• and on other OS : by any way using the CLI PHP interpreter.

Although PHP is used primarily as a web language, it is also an excellent general-purpose programming language. Another example of using PHP in CLI mode is PHP-GTK.

When run as a CLI program, a PHK archive tries to run the script referenced by the 'cli_run_script' option.

Note: if a PHK archive is included from another source file in CLI mode, we consider it is included, and we are in the previous case.

5.3 - Web direct access (web_run)

In this mode, a PHK archive is executed by a web server, typically via a SAPI like CGI or a web server module like 'apache2handler'. This mode includes every SAPI except the CLI one.

This mode is more complex as the PHK archive is accessed through an URL. Here, the PHK runtime acts as a controller in MVC terminology.

This URL contains two parts :

• the first part gives the path to the PHK archive.
• the second part gives the path of a subfile inside the PHK archive.

This way, the PHK archive is seen from the end-user as a virtual file tree.

For an example, have a look at the Zend Framework documentation demo packages, especially the API documentations.

When accessed in direct web access mode, a PHK archive tries to run the script referenced by the 'web_run_script' option.

The following chapters detail some features and limitations specific to this mode:

5.3.1 - Access restrictions

As a web feature, we cannot let the whole subfile tree 'open' to any request. The typical solution is to create an empty 'index.htm' file in every directory so that its content cannot be listed. PHK provides a more elegant solution :

• 1. A virtual directory cannot be listed from the web. If you specify the path of a directory in web direct access mode, you get an error.
• 2. The requested path is filtered through a list of 'authorized' paths. This list is defined by the package's 'web_access' option. Any request for a path which is not specified as authorized is discarded (or sent to the 'web_run_script' if it is defined).

Thanks to this, it becomes easier to increase an application's security level.

This feature can only make it easier for you to increase your security level, and will be effective only when used as a complement to the right security techniques.

5.3.2 - Mime types

As PHK implement a virtual file tree, it has the responsibility to determine which mime-type to return to the client when a subfile is requested. For this purpose, it defines a default table of mime types to associate with the most common file suffixes. See the documentation for the mime_types option in the PHK builder's guide to see this default table.

If the default table does not contain every mime type you intend to return from your PHK archive, you must specify the additional types using the mime_types option.

6 - The webinfo mode

The webinfo mode is a special subcase of the web direct access mode. What we saw previously was the usual execution mode.

In order to switch your package to webinfo mode, you just create another (empty) file, in the same directory as the package file, whose name is the same as the PHK archive's with a '.webinfo' suffix appended.

Example :

You download a PHK archive and save it to :

This file is in execution mode by default : if you call it through your browser, it will behave the way intended by the package's builder.

In order to switch it to webinfo mode, just create a new empty file named :

This new file's content is never used, he just has to exist in the same directory as the PHK archive.

Now, as long as the '.webinfo' file exists, the PHK archive's behavior is completely different : When it is run through a web browser, it does not execute its software any more. Instead of this, it displays a small embedded web site, where you can see all its characteristics.

6.1 - Security considerations

Why is it done this way ? Why isn't it just an extension of the 'normal' execution mode ?

The main reason is security. The webinfo mode displays every aspect of a PHK package and it is also the standard way to display the package's help, license, source code, etc. But, as it allows any access to the package's information, it would be a very bad idea to keep this access always open.

That's why both modes are mutually exclusive. You cannot forget to switch the webinfo mode off, as your package cannot run normally in this mode !

Some other reasons it was done this way :

• it is easy to remember,
• no modification needed in the archive file,
• it does not require a shell access to the installation directory, and can be switched on/off through an FTP connection.

If you want to keep a package running in execution mode and, at the same time, analyze it in webinfo mode, you must make a copy of your PHK archive under a different name and/or in a different directory, and create the webinfo-enabler file to match the new name and/or location. Symbolic links don't work in this case.

6.2 - Running webinfo

Now, webinfo mode is on. How do we display all this information ?

As we said before, just point your browser to the PHK archive behind a PHP-enabled web server. It should display the webinfo home page.

6.3 - Webinfo pages

Several pages can be displayed, by clicking on the tabs on the top of the screen.

6.3.1 - Home

This is the first page you display when accessing the PHK archive in webinfo mode.

The packager has the possibility to provide a PHP script to be executed and displayed on this page (through the info_script option). If this option is not set, this page displays some general information about the package : name, summary, version, etc.

6.3.2 - Help

If a documentation is included in the package (e.g. if the help_prefix option is set), this page will display it. If an HTML documentation has been provided, this page can contain any HTML content, including images and hypertext links (internal or external to the package).

6.3.3 - License

This page is displayed only if the license_prefix option is defined. It displays the license subfile.

6.3.4 - Info

This page displays every technical information about the package.

6.3.5 - Files

This page displays the list of the subfiles contained in the package. Here, you will see the charactics of every subfile: size, modification time, compression flags, compression ratio...

Notes:

• The displayed size is the original uncompressed size.
• The compression ratio is computed as : <compressed size>*100/<original size>

Clicking on a filename displays the subfile's content:

6.3.6 - Automap

If an automap is defined in the package, this page displays every symbol defined in the package's subfiles. For each symbol, you will see its name, type (function, class, or constant), and the name of the subfile it is defined in.

Since PHK 1.3.0, as PHP considers interfaces are 'special' classes, and because classes and interfaces cannot share the same name, the autoloader considers and registers interfaces as classes.

As PHP does not distinguish between uppercase and lowercase in class and function names, the automap stores them in lowercase, as they are stored and compared internally by PHP.

Clicking on a subfiles's name displays this subfile's content.

6.3.7 - Test

This tab is displayed only if the package defines unit tests. When clicked, it runs the package's unit tests. The script's output must be in HTML format.

Most packages provide only CLI-mode tests because it allows to get rid of the max_execution_time PHP parameter. In this case, the test script should test for CLI mode and, if it is not the case, display a message asking to run the tests in CLI mode (look at the ZF example test package for an example).

6.3.8 - Application tabs

The package can define its own webinfo pages. If it is the case, your page will display some additional tabs, along with the default ones.

7 - CLI built-in commands

A PHK archive can execute several built-in CLI commands. The role of these commands is to display the same information as the webinfo mode, in a CLI environment.

To run a built-in command, just execute your PHK file through the CLI PHP interpreter (generally /usr/bin/php) and provide the built-in command as second argument.

Every built-in command starts with the '@' char, meaning that CLI programs ported to the PHK format should avoid using such a string as 1st argument.

In order to list the available built-in commands, run you PHK package with a single '@' argument.

Example:

7.1 - @

The '@' command displays the list of available built-in commands.

7.2 - @dump

Arguments: a non-existing base directory where the archive content will be dumped.

This command extracts the whole subfile tree out of the PHK archive and creates the corresponding file tree under the directory given as argument.

7.3 - @get

Argument: a subfile's path

This command displays a subfile's content on stdout.

7.4 - @help

Arguments: none

if the 'help_prefix' option is defined, this command will display the corresponding document in text mode.

If the option is not defined, it will display '<No help file>'.

7.5 - @info

Arguments: none

This command will display the same information as the 'Home' page in webinfo mode.

7.6 - @license

Arguments: none

if the 'license_prefix' option is defined, this command will display the corresponding document in text mode.

If the option is not defined, it will display '<No license file>'.

7.7 - @option

Arguments: option name

This command displays the value corresponding to the supplied option name.

7.8 - @set_interp

Arguments: a PHP interpreter's path or an empty string

This command will modify the PHK archive's 1st line, so that it can be executed as a Unix script.

Example:

Please note that:

• When a package is created by the PHK_Creator tool, the interpreter string is not set.
• Setting the interpreter string on a PHK archive will make it usable only as a CLI command, as any attempt to include or run it as a web script will display the interpreter line.
• To remove the interpreter setting, run the '@set_interp' command with an empty string as argument.
• If the PHK package is signed, running @set_interp does not invalidate the signature.

7.9 - @showfiles

This command is similar to the webinfo 'Files' page. It displays the list of subfiles contained in the package.

7.10 - @showmap

This command is similar to the webinfo 'Automap' page. It displays the list of symbols defined in the package with the corresponding subfile's path.

7.11 - @techinfo

This command is similar to the webinfo 'Info' page. It displays the technical information about the package.

7.12 - @test

Arguments: none

Runs the package's unit tests.

Last update : Saturday, 19 January 2008

Average user rating

   (0 vote)

Display 14 of 14 comments