SnapLook Parsed Document
Pharser Admin Manual
What is Pharser?
Pharser is a small fast template parser written for one purpose
-- making the website look uniform, while still making it easy
for users to edit their pages. The biggest problem with many
other templating engines is that they require special tags to be
placed inside the HTML pages, or even worse -- they require
special clients or web interfaces in order to add/change data.
Pharser is a small template parsing engine that will grab the
output of the simple HTML file, and add a small header, footer,
and navigational menus. No special tags or additional knowledge
is required on the user-end in order to edit the pages or create
new ones. Most HTML editing software will do the job quite
fine. For more information about this subject, see the user
How Pharser Works
The idea is quite simple -- capture the page output and modify
it to give it the uniform look and feel of the website. This is
accomplished by using output buffering functions in PHP. As long
as you have mod_php installed with apache, you can use pharser.
Pharser does not concern itself with the website layout -- it
assumes that you do that yourself using a sane directory tree
structure to organize your website. A well-designed website
directory tree will aide you a lot in other tasks as well, not
The only special bit about pharser are the menu files. These are
small files with entries which tell pharser such things as the
title of the directory, and what things to link to whenever
files in this directory are displayed in pharser. Whenever
invoked, pharser will traverse the entire web tree from docroot
and to the current directory. This is the most
processing-expensinve part of the script, although disk caching
helps a lot. See also the "Tweaks" part in the
For more information about the contents of menu files, please
see the user manual.
Setting up Pharser
The idea is to use PHP's output buffering functions to capture
the html produced by the user pages, and to wrap them in a
unform header and footer. To do that, we will do the following:
Place files in some sane locations
Designate an extension to use for pharser-enabled html
Tell PHP to use output-buffering for pharser-enabled files
Placing files into sane locations
There are only three files in pharser, so that's not that
hard. According to the FHS conventions, pharser.inc and
essentials.inc files go into
/usr/share/pharser, while pharser.conf goes
into /etc/pharser. I suggest you adhere to this. Remember
to copy pharser.conf as /etc/pharser/default.conf, otherwise pharser
won't find it.
Designating an extension
By convention, ".ptml" is used for pharser-enabled
pages. Depending on the environment, it can conflict with other
".ptml" pages, as there are plenty of various engines
using "ptml" for their needs. The extension for
pharser can really be anything you like, including
Placing the config file in place
Copy apache.conf file that comes with the distribution into
/etc/httpd/conf.d/pharser.conf. You might want to edit it if you
have changed something from default settings.
Using with virtual servers
Keep your global configs, and just point pharser at different
config files by using SetEnv in apache. E.g. add the following to your
mydomain.com virtual domain:
SetEnv PHARSER_CONFIG /etc/pharser/mydomain.conf
Pharser config file
Pharser config file is in the win.ini config file standard,
since that is easy to read and edit. What follows are the
general conventions of such config files:
"#" and ";" begin comments, unless they
follow a backslash: \# and \; will not be regarded as
whitespace before the variable name and after the variable
name and before the '=' sign will be ignored.
variable names can contain only aphanumerics and '_'
whitespace after the '=' sign and before the variable value
will be ignored.
whitespace after the variable value will NOT be ignored,
except for newlines.
variable values should be on one line, unless
backslash-newline is used to indicate that the value is
continued on the next line.
This almost always is your document root in apache. In fact, I
can't think of the time when it should be something else.
When you need to use pharser not from the top directory of
your website, but from a few dirs down, you can specify that
in relroot. This is only useful for menufile traversing,
though, if you need to enable/disable .ptml files depending on
the directory they are in, you will have to define that using
Directory directives in httpd.conf. However, if you
only want to traverse for menu.inc files starting from
/some/path below the webroot, that's what you will pass to
Special workarounds are needed for ~user/ mappings. Setting
this to on will enable mapping the userspaces in
order to correctly traverse the tree for menu.inc files.
Most commonly public_html. This setting is ignored
unless userspace is set to on.
This section contains definitions for the header and footer
files for pharser to use. See the section about include files
for more information.
Where to look for the header template.
Where to look for the footer template.
Where to look for the special "printer-friendly"
Where to look for the special "printer-friendly"
This is where things related to menu files are defined. See the
section about menu files in the user manual for more information
about the format of the file.
By convention, the filename for menu files is
menu.inc, but depending on your environment, you
might want to set it to something else, like .menu.
Admittedly, pharser is not a very flexible templating
engine. It expects, for example, two things -- that your pages
will contain some sort of a "top menu" where the
linked hierarchy will be placed with directory titles. It also
expects that your template will contain a "side
menu" where the contents of menu.inc will go, as well as
the reverse directory hierarchy in the "Return To"
section. If that confuses you, just look at any of the pages
generated by pharser and you'll see what that means.
Linked items in the top menu lead to the previous dirs in the
tree hierarchy. Here is the example entry:
top_linked_item = <a class="nowrap"
%%LINK%% will be the link leading to the
directory, and %%TITLE%% will be the title of
that directory. If you are confused, again, look at the source
of the pharser-generated file for the moment of clarity.
This is where the title of the page being viewed will go. It
is not linked to anything since it's currently being
displayed. The only template entry it expects is %%TITLE%%.
The title of the directory currently engaged, and the
"Return To" title will be displayed using that
mask. The only template entry it expects is %%TITLE%%.
Similarly to the top_linked_item, this expects %%LINK%% and %%TITLE%% to be both
present. It is used to make the side menu entries linking to
the items in menu.inc files and the reverse hierarchy.
If the page has no title, this will be used instead.
Aliases in Apache confuse the directory traversing in search of
menu.inc files, so they have to be specified separately. An
example entry would be:
/projects = /usr/project
The only filter currently is mail munging, which operates by
replacing @ symbols with arbitrary sequences, "[at]" by default.
Can be 'on' or 'off'. Also, users can set it locally by
providing <?php $MAILMUNGE="on" ?> somewhere in their
page, or per directory by setting "SetEnv PHARSER_MAILMUNGE on"
in their .htaccess file.
What to replace '@' symbols with, '[at]' by default.
Can be set to something like '@REMOVE.THIS.PART.'. Users can set
it per-page by providing <?php $ATSYMBOL="[at]" ?> or per
directory by setting "SetEnv PHARSER_ATSYMBOL [at]" in their
There isn't much here at the moment. Pharser is pretty speedy,
since there isn't much it needs to do. The most expensive part
of the script is traversing the tree and constructing the menus
out of menu.inc files. This process can be tweaked to cache some
of the values for a speedier retrieval.
There is only one tweak available at the moment -- session
tweaking. When on, it will use the php session management to
store the arrays with menu values. According to my tests, this
helps reduce the processing times by 8-10 msec on consecutive
- When set to on turns on session tweaking.
For speedier processing it's best to completely remove all
debugging routines from both pharser.inc and
essentials.inc. To do that, run the following commands:
grep -v '_debug' pharser.inc > pharser.inc.new
grep -v '_debug' essentials.inc > essentials.inc.new
The new files will contain no debugging routines and will
make the parser speedier.
A number from 0 to 2. 0 means off, 1 is normal, 2 adds
execution time measurement outputs.
Where to put the debugging output.
Default location of the config
By default, pharser will look for the config in
Templating and include files
There are 4 include files used for templating, in two categories
-- header files and footer files. When parsing the ptml file
output, pharser will remove anything before <body>
(including <body> tag itself) and replace that with the
header include file. The footer is added in place of whatever
follows </body>, again, including the /body tag itself.
There are several templating entries that can (and should) be
used inside the template files.
This will be replaced with whatever relroot path you defined
in the config file (see that for more info).
This will be replaced with the title of the current page, as
derived from the <title> tag used in the output.
You can define extra stylesheets in .ptml files, but ONLY if
they are externally linked and referenced in the following
manner: <link rel="stylesheet"
This is where the dynamically-constructed top menu will be
placed. See working sites for examples.
Same as above, except on the side.
This is only useful if you are setting up an apache error
redirect page using ptml. %%PAGELOC%% will be
replaced with whatever Apache passed as the redirected page
This will be replaced with the file modification time of the
ptml file currently being viewed.
It is also worth noting that all these template parameters are
available for use inside the ptml files as well, not just the
[Page updated: Aug-13-2007]
Copyright © 2003 by Llamas, inc.