6.1. CLI mode

6.2. Web mode

7.1. CLI mode

1 - Introduction

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

what a Package Specification File is and how to create one, setting your package's options
how to build a PHK package
how to display its information, both in CLI and webinfo mode.

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 :

our main script, named 'hello.php' :

<?php



// This will autoload the 'Message' class



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



?>

a file named 'message.php', containing the 'Message' class :

<?php



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

?>

and a file named 'env.php', containing the 'EnvInfo' class :

<?php



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 ?

where to get the source files we want to include into the package and where they will be inserted in the package's virtual tree,
the package's meta-information : name, author, version, etc. These are optional but, on a real package, it is always cleaner to set as much information as possible. The list of possible information is quite long and includes every possible aspects of authorship, licensing, dependencies...
The entry points. PHK supports multiple entry points, which means, for instance, that different scripts can be executed when the package is executed in CLI mode or accessed though the web. Here we will execute the same script for CLI and web access (exercise: once you finish this tutorial, use a different script for CLI and web access).

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

# Add the src subdir and its content as /src



add src



%options



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 :



<None>



* 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.

PHK Tutorial