Documentation
Since version 0.1.7 the recommended way of extending phc is
through plugins. Getting Started
explains how to compile plugins for phc.
Because phc does not generate machine
code, it not yet useful to end users. However, it can be used as a
framework for writing applications that process PHP code. phc parses PHP code into an internal
representation known as an abstract syntax tree or
AST. Applications can process PHP code by analysing and
modifying this abstract representation in one of two ways:
- phc supports plugins. Plugins
are modules that can be loaded into phc,
which get access to the AST. phc provides
sophisticated support for writing operations over the AST through
the Tree Transformation API.
- Alternatively, you can export the AST to XML. You can
then process the XML in any way you like, and then use phc to convert the XML back to PHP syntax.
The Usage documentation below explains how to explain
and run phc, and how to convert from PHP
to XML and back. Writing Plugins explains how to write
plugins for phc, and provides numerous
examples. You will find the Reference Documentation very
useful when writing serious applications using phc. Finally, Miscellaneous lists a few
other articles you may find interesting.
Note that you can download the documentation for this and for
older versions from the archive.
Moreover, although we have tried to document phc as well as we can, if anything is still
unclear, please let us know by sending an email to the mailing list.
| Reference |
|---|
The Grammar
phc represents PHP scripts internally as
an abstract syntax tree. The structure of this tree is dictated by
the (abstract) grammar. The grammar
definition is a very important part of phc.
Representing PHP
phc's view on the world (as dictated by
the grammar) does not completely agree with the PHP standard view.
Representing PHP describes how
the various PHP constructs get translated into the abstract syntax.
Overview of the AST classes and transformation API
This gives an overview of the AST
classes, the tree visitor API and the tree transformation API from
a programmer's perspective.
maketea Theory
maketea is a tool bundled with phc which, based on a grammar definition of a
language, generates a C++ hierarchy for the corresponding abstract
syntax tree, a tree transformation and visitor API, and deep
cloning, deep equality and pattern matching on the AST. The maketea theory explains some of the
theory behind maketea; in particular, the
grammar formalism, the mapping from the grammar to the AST classes,
and the derivation of the tree transformation API.
|
| Miscellaneous |
|---|
Memory Layout for Multiple and Virtual Inheritance
Programmers wishing to enhance their knowledge of C++ might
find Memory Layout for Multiple
and Virtual Inheritance an interesting article. It explains the
difficulties C++ compilers face when deciding the (runtime) layout
for objects in the presence of multiple inheritance, and the
consequences this has for programmers.
Writing a Reentrant Parser with Flex and Bison
Writing a Reentrant Parser with Flex
and Bison explains by means of an example how to create a
reentrant parser with Flex and Bison, and how to use more than one
parser in one application.
|
|
| Writing Plugins |
|---|
Getting Started
Getting Started introduces
writing plugins for phc. It then explains
how phc represents PHP scripts internally,
and shows how to write a simple plugin that counts the number of
classes in a PHP script.
Tutorial 1: Traversing the Tree
Tutorial 1 introduces the support that
phc offers for traversing (and
transforming) scripts. It shows how to write a program that counts
the number of function calls in a script.
Tutorial 2: Modifying Tree Nodes
Tutorial 2 shows how you can modify
nodes in the tree (without modifying the structure of the tree). It
shows how to replace calls to mysql_connect by calls
to dbx_connect.
Tutorial 3: Restructuring the Tree
Tutorial 3 shows how you can modify
the structure of the tree. It works through an example that
removes unnecessary string concatenations (for example, $a .
"" is replaced by just $a).
Tutorial 4: Using State
Tutorial 4 explains an advanced
features of pattern matching, and shows an important technique: the
use of state in transformations (where one transformation depends
on a previous transformation). It shows how to write a program that
renames all functions foo in a script to
db_foo, if there are calls to a database engine within
foo.
Tutorial 5: Modifying the Traversal Order
Tutorial 5 explains how to change the
order in which the children of a node are visited, avoid visiting
some children, or how to execute a piece of code in between
visiting two children.
Tutorial 6: Returning Lists
Tutorial 6 shows how to define
transformations that replace nodes in the tree by multiple
other nodes, and how to delete nodes from the tree. It also
shows to call the phc parser and
unparsers from plugins.
|
|
|