PHK Tutorial

Read : 20,405 times
(0 votes, average 0 out of 5)

1. Introduction
2. Download the PHK building software
3. The subfiles
4. The Package Specification File
5. Build the package
6. Running the package
     6.1. CLI mode
     6.2. Web mode
7. Displaying information
     7.1. CLI mode
     7.2. web mode (webinfo)

1 - Introduction

This tutorial explains how to build a basic PHK package. Here, you will learn :

We'll follow the tradition : the package we are building here is a typical 'hello, world' example. When run, it just displays a welcome message.

In order to illustrate the autoload system, we'll display the message through an autoloaded class..

This tutorial can be run on any operating system. For this basic example, everything is created and run in a single directory.

Before you start, please ensure that your PHP version is 5.3.0 or newer.

2 - Download the PHK building software

First, if not already done, download the latest distribution from Github. The software comes in the form of a tar/gz file. Uncompress/untar it, you will find a file named phkmgr. This is the PHK building/management tool. The rest of the distribution is made of docs, tests, and examples.

Now, create an empty directory, anywhere on the system, cd there, and copy the phkmgr file into this directory (use a 'ls -l' to check that the copy is executable). This will be our base directory.

:note For the sake of simplicity, we put the phkmgr file in our base directory. In a real build environement, it would probably be located elsewhere on the system, to be shared by every project. This file is needed to create PHK packages only. It must not be distributed along with the resulting packages, which are self-sufficient.

3 - The subfiles

Create a subdirectory named 'src'. In this subdirectory, create these 3 files :


// This will autoload the 'Message' class

Message::display('Hello, world');



class Message

public static function display($msg)
// This will autoload the 'EnvInfo' class

if (EnvInfo::is_web()) echo "<h1>$msg</h1>";
else echo "$msg\n";

} // End of class Message


class EnvInfo

public static function is_web()
return (php_sapi_name()!='cli');

} // End of class EnvInfo

That's all for the PHP code. Now we will focus on the package's parameters.

4 - The Package Specification File

In the PHK documentation, PSF stands for Package Specification File. As its name implies, this file contains every information needed to build the package.

Here, we create a very basic, almost minimal, PSF. What do we have to specify ?

Create a file named 'hello.psf' with the following content :

# Add the src subdir and its content as /src

add src


name          : My first package
version      : '1.0'
author        : Bond... James Bond
license      : Top secret
cli_run_script: /src/hello.php # This is the entry point in CLI mode
web_run_script: /src/hello.php # This is the entry point in web mode

:note The default syntax for PSF meta-information is Yaml. It is also possible to use JSON or a PHP script returning an array.

:note The complete list of supported options is in the PHK builder's guide.

5 - Build the package

Now, we have everything we need to build the package.

We will assume that the 'php' command (or the 'php.exe' file on Windows) is in your path. If it is not the case, prefix the command below with the complete path to your PHP executable.

In command line mode (in a shell/command window), run:

./phkmgr build hello.phk

This command will build a 'hello.phk' package file in the current directory. If everything goes well, it shouldn't display anything.

:note You may note that we didn't specify anything to have the class names recorded in the autoload map, as it is the default behavior.

6 - Running the package

Now, we run our new PHK package.

6.1 - CLI mode

# php hello.phk
Hello, world

Amazing, it works ! 

:note Note that the 'Message' and 'EnvInfo' classes were automagically loaded, as they are not explicitely included.

6.2 - Web mode

Copy your 'hello.phk' file to a directory you can access through a web server and rename it to hello.php (so that the web server recognizes it as a PHP script).

:note Later, you will configure your web server to associate the '.phk' suffix with PHP but, for this tutorial, it is easier to rename the file with a known file suffix.

Now, display it in your favorite browser :

It works again !

:note You will note that it is now displayed in HTML, showing that everything was autoloaded correctly.

7 - Displaying information

7.1 - CLI mode

Now, we are going to display some technical information about this new package. Of course, as you are the package's author, it's quite useless but imagine you just downloaded this package from a remote website :

Run :

# php hello.phk @techinfo
==== Package =====================================================

Name: My first package
Summary: <>
Version: 1.0

We can also display the list of its subfiles:

# php hello.phk @showfiles
D      /
D       /src
F 47       /src/hello.php
D       /src/lib
F 181     /src/lib/env.php
F 222     /src/lib/message.php

And, finally, we display the package's symbol map. As we could expect, it contains our two classes :

# php hello.phk @showmap

* Global information :

        Map version : x.x.x
        Min reader version : x.x.x
        Symbol count : 2

* Options :


* Symbols :

| Type  |  Name  | T |    Defined in      |
| Class | EnvInfo | S | src/lib/env.php    |
| Class | Message | S | src/lib/message.php |

Now, it's time to display these information in a browser.

7.2 - web mode (webinfo)

In order to switch to webinfo mode, you will create an empty file in the same directory as the 'hello.php' file. This new file must be named 'hello.php.webinfo'. Once you have created this file, ask your browser to access the same URL as above (the one which displayed 'Hello, World' in HTML). You should get a very different result :

Your package now runs in webinfo mode and it behaves as a small website showing information about the package. Navigate through the different pages by using the tabs at the top of the screen. Note that there is no 'License' or 'Help' tab, as we didn't define the corresponding options.

Now, you know how to build a simple PHK package. But PHK still provides a lot of features you will discover in the PHK builder's guide.

Joomla SEO powered by JoomSEF