Automap advanced concepts

Read : 7,543 times
(0 votes, average 0 out of 5)

This document lists advanced concepts you generally don't need to use Automap.

Map file location and base path

Map files store the paths of script files as relative paths. At runtime, when a symbol is resolved, the relative path is combined with what we call the base path.

The default base path is the directory containing the map file. This way, a map file and the related code can be moved anywhere, provided the scripts are accessible from the map file using the same relative paths. This is what you will use in most cases. Remember that the path you specify on the command line when registering your scripts will be registered along with your symbols.

It is also possible to set a base_path option in the map file. It can be used, for instance, when the relative path from the map to the scripts is modified, and the map cannot be rebuilt. In this case, the base_path option contains the relative path from the directory containing the map to the root of the file tree.

In other words, the scripts are accessed using this path combination :

<map file directory>/<base_path>/<path registered in the map>

where the default base_path is empty.

It is also possible to set an absolute path as base_path option. In this case, the location of the map file is not used anymore when accessing script files. This practice is discouraged because it is generally better to keep the scripts and their map in the same file tree, no matter where this tree is physically located. But, if you know what you're doing, it is supported.

The syntax to add and remove a base path to/from a map file is :

php automap.phk set_option [-m <map path>] base_path <new-base-path>

php automap.phk unset_option [-m <map path>] base_path


In rare cases, you may want to modify the behavior of the scanner program. You may, for instance, explictely declare a symbol definition that the scanner is unable to detect, or ask it not to register a given symbol. You may also ask the scanner to ignore every symbol defined in the file.

All of this is possible using directives you include in your PHP scripts.

The general format of directives is described below :

// <Automap>:directive args

which means :

Directives may appear anywhere in the script file and apply to the whole file.

The following directives are available :


// <Automap>:ignore-file

This directive causes the scanner to ignore every symbol defined in this script file.


// <Automap>:declare <type> <name>

This is an explicit symbol declaration :

Example :

// <Automap>:declare class MyClass

A class symbol named 'MyClass' will be added to the map and associated with this script file. Of course, when using this directive, it is your responsibility to ensure that the given symbol is defined when the script is included.


// <Automap>:ignore <type> <name>

This asks the scanner to ignore a given symbol in this file:

Note that :

Example :

class MyClass
// <Automap>:ignore class MyClass

In this case, the 'MyClass' class won't be registered in the map. Of course, it can still be registered if also defined in another file.

Structure of a map file

This information is here for information only and may change without prior notice.

Offset Size Field Comments
0 14 Magic string Contains "AUTOMAP M\024\x8\6\3"
14 12 Min version Minimal version of runtime required to read/understand this map
26 12 Map version Version of the Automap_Creator class that created the map
38 8 File size Size in bytes of the map file
46 8 CRC Adler32 checksum of the whole file (replacing this field with eight '0'.
54 8 Symbol count  
62 8 Data size Size in bytes of the subsequent data block
70 DSIZE Data block (See below for structure)

Structure of the Data block

The data block is a serialized array. It always contains two elements :

Structure of the slots array :

The array keys are normalized namespaces (without leading/trailing separators),

Each array value is a serialized array. Each element of this array has the following structure :

Joomla SEO powered by JoomSEF