PHK User's Guide

Print
Read : 36,821 times
(0 votes, average 0 out of 5)



1. Introduction
2. What you need
     2.1. PHP Version
     2.2. php.ini directives
          2.2.1. enable_dl and safe_mode
          2.2.2. Other directives
          2.2.3. HTTP server configuration
          2.2.4. PHP extensions
3. What you don't need
4. Improving runtime performance
5. Access modes
     5.1. Included (lib_run)
     5.2. Run in CLI mode (cli_run)
     5.3. Web direct access (web_run)
          5.3.1. Access restrictions
          5.3.2. Mime types
6. The webinfo mode
     6.1. Security considerations
     6.2. Running webinfo
     6.3. Webinfo pages
          6.3.1. Home
          6.3.2. Help
          6.3.3. License
          6.3.4. Info
          6.3.5. Files
          6.3.6. Symbol map
          6.3.7. Test
          6.3.8. Application tabs
7. CLI built-in commands
     7.1. @
     7.2. @dump
     7.3. @get
     7.4. @help
     7.5. @info
     7.6. @license
     7.7. @option
     7.8. @set_interp
     7.9. @showfiles
     7.10. @showmap
     7.11. @techinfo
     7.12. @test


1 - Introduction

As this is the primary goal of the PHK project, using a PHK package does not require high skills in PHP. Basically, a PHK package is used like a PHP script. It can be run in CLI mode, though a web server, or included from another script. Most PHK features don't require any specific action from the end-user, as they are generally planned and configured when the package is built.

When you receive a PHK package, you will generally also receive some information explaining where it should be located and how it can be used. Generally, you don't need any other information but, if you are curious or encounter problems when using a package, this document gives the information needed to understand and troubleshoot PHK usage.

2 - What you need

2.1 - PHP Version

In order to use a PHK package, you need PHP version 5.3.0 or more. This version is required because the PHK code is using PHP namespaces.

If your version is below this requirement, but at least 5.1.0, you will get a clean error message when loading a package. If your version is below 5.1.0, you will get a cryptic error message such as :

PHP Parse error: syntax error, unexpected T_STRING in /xxx/xxx/xxx.phk on line 2

2.2 - php.ini directives

2.2.1 - enable_dl and safe_mode

If the PHK package requires PHP extensions which are not already loaded, it will try to load them using dl(). If enable_dl is off or safe_mode is on, the dl() calls are forbidden and fail, triggering a fatal error. In this case, you must add the required extensions in the php.ini (using 'extension=' directives).

2.2.2 - Other directives

Every other 'ini' directives should be compatible with PHK. If it is not the case, please report a bug.

2.2.3 - HTTP server configuration

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

The original extension, for a PHK package, is '.phk'. But your web server probably is not configured to consider '.phk' files as PHP scripts. You have two options here :

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 package. As it was said before, the runtime code is contained in the package.

4 - Improving runtime performance

If you want to improve performance, you should install the PHK PECL extension. Of course, it is possible only if you have full control over your PHP installation.

There is nothing to configure as the extension is automatically detected and used by the runtime code. Just download, compile, install, and activate in your php.ini file. Then, restart your web server, and use a phpinfo() call to check that the extension is active.

The increase in performance can be very important, up to 100 times faster, depending on the application. Work is still in progress to improve the performance of PHK packages.

5 - Access modes

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

5.1 - Included (lib_run)

In this mode, the package 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 package 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 :

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 package tries to run the script referenced by the 'cli_run_script' option.

Note: if a PHK package 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 package 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 CLI.

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

This URL contains two parts :

Example :

An URL to access a page inside a PHK package could look like :

http://my.server/url/path/to/phk/package.phk/virtual/path/to/file.php

In such an URL, '/virtual/path/to/file.php' is the virtual path of the requested file, inside the package. When accessed in direct web mode, the PHK package is seen from the end-user as a virtual file tree.

When loaded in direct web access mode, a PHK package tries to run the script referenced by the 'web_run_script' option before searching for the requested subfile.

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 visible. So, PHK provides a mechanism to control web access to the package's virtual files :

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

:warn This feature can only help increasing 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 package, you can specify the missing 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 package's with a '.webinfo' suffix appended.

Example :

You download a PHK package and save it to :

/appli/example/ex1.phk

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 :

/appli/example/ex1.phk.webinfo

The content of this new file is never used, he just has to exist in the same directory as the PHK package.

Now, as long as the '.webinfo' file exists, the PHK package'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 a way to display the package's help, license, source code, etc. But, this access must be restricted as some of this information can be interesting for hackers.

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

Some other reasons it was done this way :

:note 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 package 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 package 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 package 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, the 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 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 characteristics of every subfile: size, modification time, compression flags, compression ratio...

Notes:

Clicking on a filename displays the subfile's content:

6.3.6 - Symbol map

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.

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.

:note 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.

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 package 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:

// List available built-in commands

# php automap.phk @

Available commands:

    - @help                      Display package help
    - @license                  Display license
    - @get <path>            Display a subfile content
    - @showmap              Display autoload map, if present
    - @showfiles               List subfiles
    - @check                    Check package
    - @option <name>      Display a package option
    - @set_interp <string> Set the first line of the PHK to '#!<string>'
    - @info                        Display information about the PHK file
    - @techinfo                  Display technical information
    - @dump <directory>  Extracts the files
    - @test [switches] [UnitTest]  Run the package's unit tests

# php automap.phk @license

                                  Apache License
                        Version 2.0, January 2004
                     http://www.apache.org/licenses/

  TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

  1. Definitions.
...

7.1 - @

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

7.2 - @dump

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

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

This command is rarely used as, normally, you never don't need to extract files from a package.

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.

:note If you want to display every option that were set when the package was created, use the '@techinfo' command, which displays the whole options array.

7.8 - @set_interp

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

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

Example:

# php hello.phk @set_interp '/usr/bin/env php'
# chmod +x hello.phk
# ./hello.phk
Hello, World

Please note that:

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.

 
Joomla SEO powered by JoomSEF