Article Index
Automap advanced concepts
Base path
Directives
Structure of a map file
All Pages

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 :

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 :

Directives

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 :

which means :

• a line starting with '// <Automap>:' (one or more spaces after '//'),
• then the directive, optionally followed with arguments

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

The following directives are available :

ignore-file

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

declare

This is an explicit symbol declaration :

• <type> is one of {function|constant|class}.
• <name> is the symbol name.

Example :

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.

ignore

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

• <type> is one of {function|constant|class}.
• <name> is the symbol name.

Note that :

• The 'ignore' directive is valid even if it appears after the symbol declaration.
• The directive is valid for this script file only.

Example :

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 :

• the item referenced with the 'options' key contains the map options. It is an array of (<option-name> => <value>) elements.
• the item referenced with the 'map' key is an array of strings. Each element defines a slot. Each slot contains the information for the symbols belonging to a given namespace. Each namespace has its slot.

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 :

• Key is a string. It is the concatenation of the symbol type (one of the \Automap\Mgr::T_xxx constants) and the symbol name. Remember that, starting with version 3.0.0, Automap is fully case-sensitive, eliminating the need to convert the key to lowercase. Note that, for performance reasons, the symbol name contains the namespace.
• Value is a string too. It is the concatenation of a target type (one of \Automap\Mgr::F_xxx constants) and the target value. If the target type corresponds to a PHP script, target values are combined with the base path, if any, to compute target file paths.