Views : 1772  |
This document explains how to use the Automap autoloader without PHK. For
more information about Automap as the PHK embedded autoloader, refer to the PHK
user's and builder's guides.
1 - Introduction
Automap is a map-based autoloader for PHP. As such, it is composed of two
parts :
- A builder software scans some PHP script files and extracts their
symbols to a map file. After every script files have been
analyzed, the map file contains a lookup table, with each symbol associated to
the file it is defined in. This build process is done only once, or when PHP
scripts are modified.
- At run time, each PHP request begins its execution by, first, loading the
Automap runtime library and, then, loading one or several map file(s). Once this
is done, the symbols present in the loaded map files are resolved
automatically when needed.
 We talk about symbols, and not classes because, even if the
current PHP engine only supports class autoloading, in the future it can be
extended to also autoload functions and constants. Automap is already able to
autoload them, as it extracts classes, functions, and constants from the PHP
scripts. The only missing links are two hooks in the PHP core and one more
argument to the function_exists() and defined() functions.
A map-based autoloader is different from usual path-based autoloaders :
- implementing it as a C extension allows to cache the maps in persistent
memory, making it faster.
- It also limits the interaction with the file system, providing another
increase in performance (less stat() calls).
- it does not impose any constraint on the structure of the directory tree
containing the script files, making it much easier to port an existing
software.
- It does not impose any constraint on the number of functions, classes, or
constants that can be defined in a single script, which also makes an existing
software adaptation easier.
- As it supports an unlimited number of symbols in the same script file, it can be used as
a basis to extend the autoload mechanism in the PHP core to functions and
constants. This is a planned future developement.
2 - Pre-requisites
Automap requires PHP 5.1 or more.
PHP 6 is not supported yet.
3 - Getting Automap
The Automap builder and the Automap runtime library are provided as a single
file, a PHK package named Automap.phk, which can be downloaded from the
download area.
The fact that the Automap software is distributed as a PHK package is
not related to the fact that PHK, itself, embeds an Automap autoloader. It is
just a distribution format allowing to distribute the software as a single file.
You can optionally install the
Automap PECL
extension. This extension acts as an accelerator : when present, it is
automatically used and dramatically increases the runtime performance. But,
except for the performance boost, everything remains functionnally identical.
Even if the extension is technically redundant with the PHP runtime
code, we'll keep distributing both formats because a lot of PHP users don't
have, either the possibility (shared hosting), or the skills needed to install a
PECL extension into their environment. So, as in PHK, the PECL extension will
remain optional.
4 - Building maps
map files store the paths of script files as relative paths from their own
directory. This allows to move a whole directory tree along with its map file,
without having to rebuild the map. Generally, the map file is stored in the base
directory of the software tree.
Map files are built using the PHP CLI interpreter. The syntax to extract the symbols from one or more PHP script files to a map
file (existing or not) is :
php Automap.phk register_scripts <map> <base-dir> <rel-file1>
[<rel-file2> ... ] |
where :
- <map> is the path to the map file. If the file does not exist, it is
created. If the file exists, its content is kept and the symbols of each
source file we are scanning are added or replaced. This allows incremental
builds, using several commands, each scanning a set of PHP files. It also allows to scan a
modified script file without having to rebuild the whole map file.
- <base-dir> is the base directory we will use to access the script files we
want to scan. This directory will be combined with the <rel-filex>
relative paths to access the files. In many cases, your current directory is
the base directory of your software tree, and, as such, <base_dir> is '.'.
- <rel-file1> [<rel-file2> ... ] is a list of one or more relative paths
from the <base-dir> argument, each leading to a script file we want to
analyze. This path is the one that will be stored in the map. This means that,
at runtime, Automap will compute the file's path by appending this relative
path to the directory where the map file lies.
Example :
Let's consider that : your software is composed of several PHP scripts, all
with a '.php' suffix, and located under the '/myapp' directory, you want to
create a map file name 'auto.map' in the '/myapp' directory, and populate it
with all the symbols of your script files. We also assume that you have
downloaded the 'Automap.phk' file in '/myapp' and that the 'php' command is in
your path. Here are the commands you can use for this :
# cd /myapp
# php Automap.phk register_scripts auto.map . `find . -name '*.php'` |
For another example, please see the basic tutorial below.
5 - Using maps
In order to be able to autoload symbols from an existing map, you will :
- Load the Automap library. This means including the 'Automap.phk' file.
- Load one or several map files.
In theory, loading the library file is mandatory only if the Automap
extension is not present in the environment. In practice, conditionally loading the PHP runtime library makes your software portable and should be
preferred, as the performance penalty is negligible. The most efficient way to
do this is to execute such a line at the beginning of every requests :
if (!class_exists('Automap',0)) require '/path/to/Automap.phk'; |
Once it is done, it is time to load our map(s). This is done with the
following call :
$mnt=Automap::mount('/path/to/the/automap_file'); |
The '$mnt' return value is what we call the 'mount point'. It is a string uniquely identifying your mounted map.
Saving it to a variable is not mandatory but you will need it, for instance,
if you want to unload ('umount') the map. In the simple cases, as you will see
with the tutorial below, you won't need it.
If the map file cannot be mounted (because the file does not exists,
or for any other reason), Automap::mount() throws an exception with an
informative message
That's all you need to add to your software. Once the map(s) is/are mounted,
their symbols will be autoloaded when first referenced.
6 - Tutorial - an 'hello, world' example
This tutorial explains how to build a basic map file. Here, you will
learn :
- how to build a map file,
- how to display its content,
- how to use it from your code.
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. We'll display the message through
an autoloaded class..
For this basic example,
everything is created and run in a single directory.
Before you start, ensure that your PHP version is 5.1.0 or newer.
6.1 - Download the Automap.phk file
First, if it is not already done, download the Automap.phk file from the
download area and store it in
your current directory.
6.2 - The PHP scripts
First, we define our main script. Create a file named 'hello.php' with the
following content :
<?php
// Load the Automap library and mount the map
if (!class_exists('Automap')) require 'Automap.phk';
Automap::mount('auto.map');
// This will autoload the 'Message' class
Message::display('Hello, world');
?> |
Now, we define the 'Message' class. Create a file named 'message.php' with
the following content :
<?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
?> |
Now, we define the 'EnvInfo' class. Create a file named 'env.php' with the
following content :
<?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 build the map file.
6.3 - Building the map file
We will assume that the 'php' command (or the 'php.exe' file on Windows) is
in your path. If it is not the case, add it to your path or modify the command
below to specify the absolute path to the php executable.
In command line mode (in a shell/command window), run:
php Automap.phk register_scripts auto.map . message.php env.php |
This command will build an 'auto.map' file in the current directory.
6.4 - Displaying the map's content
Now, we have our map file. But, before running the program, we would like to
check that the classes where correctly registered.
Here is the command to display the content of the map file :
php Automap.phk showmap auto.map |
This will display :
* Global information :
Map version : 1.1.0
Min reader version : 1.1.0
Symbol count : 2
* Options :
Array
(
)
* Symbols :
-------------------------------------
| Type | Name | T | Defined in |
|-------|---------|---|-------------|
| Class | envinfo | S | env.php |
| Class | message | S | message.php | |
As PHP considers class and function names as case-insensitive, you
will notice that they are converted to lowercase when registered in an automap.
6.5 - Running the package
Now, we run our program and check that it autoloads the 'Message' and
'EnvInfo' classes :
6.5.1 - CLI mode
# php hello.php
Hello, world |
Amazing, it works !
6.5.2 - Web mode
Now, copy 'Automap.phk', 'auto.map', 'hello.php', 'message.php', and
'env.php' to a directory you can access through a web
server and display it in your favorite browser :
It works again !
7 - Automap.phk commands
The Automap.phk software supports the following commands :
- help : displays the list of available commands. Use it to get the usage of
the commands below.
- showmap : displays the content of a map file (see tutorial above)
- register_scripts : extracts the symbols from one or more scripts and
stores them in a map file.
- register_extensions : scans the extension directory for extension
libraries and registers their symbols in a map.
- export : exports a map content as plain text.
- import : import the result of a previous export.
8 - Automap API
Coming soon...
Last update : Saturday, 19 January 2008
|
|
|
Support 
(0 vote)