Copyright © 2005 Robert Bienert
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License.
This document explains step-by-step how to set up a working LayManSys installation.
Table of Contents
First, make sure you have got the latest LayManSys package by checking your local LayManSys version against the latest one on the official download page. If your one has expired, download the latest one before continue reading this document.
LayManSys packages are distributed as compressed ZIP-archives, so after download the file, uncompress it to your favourite directory; I suggest putting library files outside the document root, so that they are protected by unauthorized access even in the event of a server misconfiguration (leading in serving PHP files as plain text).
Although LayManSys is designed as a library for simply unpacking and using it (without larger patching), there are some places where you have to modify the library (for configuration) to get it working on your webspace. This section explains where this places are and how to modify LayManSys.
Some LayManSys modules need to have some constants set to find other configuration files, such as the global
This constant points to your document root, as seen from the calling file, not from LayManSys!
This constants points to your directory where configuration files are stored, especially the directory location of your
etc/laymansys.rdf is a normal RDF file as described by the LayManSys Elements and Namespace reference. An example file is distributed with the LayManSys library package resp. available in the CVS repository. The more you can fill meta information into this file, the less do you need to specify later in your documents RDF file.
The really important configuration setting here is the array returned by
LayManSysDefaultHeaderOptions. Each configuration setting is a string and so may contain any character you like with one exception: Keys having a dot as first and last character are "private" LayManSys settings. There are currently the following keys you can use customizing LayManSys:
This points to a callback function which is called when an error occurs while generating the XHTML body. So the error handler can be very flexible, because all necessary headers are already sent. Its default value is
This is the location of the global
laymansys.rdf. The default setting requires the
ETC_PATH to be set.
This is the "opposite" of the one above, it points to the documents RDF file. Its value is determined by
getRDFFile by default, but it can be overwritten, e.g. when using a database based content management system.
This boolean value historically came from the successor of LayManSys and is set to
TRUE if LayManSys should write the navigation panel before the documents title, which is not recommended. This setting is deprecated by the more flexible
layout:nav tag in a RDF file.
All of these settings can be overwritten on a per file base using an optional array as second argument to
LayManSysHeader call for an example.
This section explains modules and functions, that are distributed with LayManSys, but unused in the default framework,
lib/laymansys.php. You can use them by including the optional "all inclusive" framework
lib/laymansys-default.php. If you use your own error handling and/or footer, you can skip this section an continue reading with the section Using LayManSys.
This file is the central error handler for LayManSys; it contains the two error callbacks
handle1stStageError for errors while generating the header and
handle2ndStageError for later errors. Both callbacks make use of the
logError function from the module
errors/log.php. By including a different module you can use your own
handle1stStageError shows the HTTP 500 error document and than exits by default. Logging the error is done implicitly by
errors/500.php. You may change this behaviour by using another error document or continuing the script execution; simply delete the
exit statement for this.
handle2ndStageError itself is "optional" because you can overwrite this callback in the
laymansys/config.php. It logs the error and displays a error message by default. You may want to change this message because the default string is in German (this comes from the fact that I first used LayManSys only for my private homepage).
LayManSys contains a module for writing a default footer element and closing the
html tag. The function
writeFooter, that you can modify regarding your needs, writes the documents copyright notice inside a
address id="footer" block and closes the
html tags. It should be the last function executed before ending the script. The function prototype may be interesting for you when modifying this file:
$endTags contains tags that need to be closed at the documents end. The purpose of
$xml is to indicate whether the output should be HTML or XHTML. But the default footer does not need this information.
The LayManSys distribution contains an example error page for HTTP 500 errors that is called by
error.php. This default file contains PHP code for logging the error information to a database, using the module
errors/log.php and displaying a nice HTTP 500 message to the user. You can customize this file as you like for your own needs, you are even allowed using it as ErrorDocument for your webserver.
The distributed file
errors/log.php contains the function
logError for logging error messages to a SQL database.
For this, you have to define some constants so that the
logError function can connect to the SQL server:
This string contains the name of your SQL server and may contain a port number, if supported by the
This is the name of the database which contains the error_log table.
This your SQL username.
And this is your SQL password.
You have to modify this file if you are using a database management system other than MySQL, that means, replacing all direct MySQL API calls, but this are only a few.
Do not forget to change the function
If you would like to use LayManSys' default error handling and logging mechanism, you have to set up a SQL database for the error log. The directory
lib/errors/ contains the SQL file
error_log.sql that you can use for creating the necessary error_log database table. Although exported from MySQL, you should be able using the file with other database engines without larger modifications.
There is currently no public available tool to manage this database.
Now, that you have set up your LayManSys installation, you can use it in your documents in two flavours:
The most simple way using LayManSys is by including one of the LayManSys wrappers in the
Example 1. Including the HTML Strict Auto-Header
include_once(; // $meta contains the LayManSys meta information ?> <!-- Start here your HTML body right now! -->
The given filename
my_error_handler.php is used here as a place-holder for your error handling module.
Each of the following auto-headers includes the LayManSys main file,
lib/laymansys.php and calls the
LayManSysHeader using a certain HTML document type.
html4.phpfor HTML 4.01 Strict
html4loose.phpfor HTML 4.01 Transitional
xhtml1.phpfor XHTML 1.0 Strict
xhtml1loose.phpfor XHTML 1.0 Transitional
If you want to go the real lazy-mans way, you can use the auto-headers whose name ends with
-default.php. They include the
lib/laymansys-default.php library file which provides a complete error-handling and -logging mechanism. Their names are comparable to the ones above, e.g.
html4-default.php is the all-inclusive version of
html4.php and their usage is the same.
If you want to use LayManSys in a document where you need to set some
config.php options, you have to include the
laymansys.php directly and call
LayManSysHeader explicitly. The function takes as first parameter the HTML document type, something like
HTML 4.01 or
XHTML 1.0 Strict. The second parameter is an optional array of
config.php settings. The third parameter is also optional and can be used for passing
$meta from other sources than RDF files, e.g. from a database. An example of a
LayManSysHeader call looks like this:
LayManSysHeader(; ?> <!-- Now we are in the HTML body. -->
array(, /* options */,
array(, /* meta data */)