Running phc

Once you have installed phc, run it by typing

./phc

You should see something like

phc 0.1.6

Usage: phc [OPTIONS]... [FILES]...

  -h, --help                   Print help and exit
      --full-help              Print help, including hidden options, and exit
  -V, --version                Print version and exit
      --dump-php               Dump PHP code back immediately after parsing to 
                                 standard output (pretty printing)  
                                 (default=off)
      --dump-ast-dot           Dump the AST from the source in dot format  
                                 (default=off)
      --dump-ast-xml           Dump the AST from the source in XML format  
                                 (default=off)
      --compile-time-includes  When possible, replace include() statements with 
                                 the parsed contents of the specified file  
                                 (default=off)
      --tab=STRING             String to use for tabs while unparsing  
                                 (default=`     ')

(the exact output will depend on the version of phc)

Now write a very small PHP script, for example

<? echo "Hello world!"; ?>

and store it in a file, for example in helloworld.php. Then run phc as follows:

./phc --dump-php helloworld.php

This should output a pretty-printed version of your PHP script back to standard output:

<?php
   echo "Hello world!";
?>

Graphical Output

phc represents PHP scripts internally as trees (this is further explained in Tutorial 1). If you have a DOT viewer installed on your system (for example, graphviz), you can view this tree graphically. First, ask phc to output the tree in DOT format:

./phc --dump-ast-dot helloworld.php > helloworld.dot

You can then view the tree (helloworld.dot) using Graphviz. In most Unix/Linux systems, you should be able to do

dotty helloworld.dot

And you should see the tree (it should look similar to the one we generated).

Writing and Reading XML

phc can also output an XML representation of the tree. You can use this representation if you want to process PHP scripts without using the phc framework, but yet using the phc abstract representation of PHP scripts. To generate an XML version of the tree, run

./phc --dump-ast-xml helloworld.php > helloworld.xml

phc can also read the XML back in, after which all the usual features of phc are again available; in particular, it is possible to read an XML file, and write PHP syntax. To convert the XML file we just generated back to PHP syntax, run

./phc --read-ast-xml --dump-php helloworld.xml

The generated XML uses the schema http://www.phpcompiler.org/phc-1.0.

Compile-time Includes

phc now has initial support for compile-time processing of PHP's include built-in. Enabling this feature inserts the included statements in the AST in the place of the include statement. Included functions become part of the %MAIN% class, and included classes become part of the script. In the event that phc is not able to process the include statement (for example, if it would require using the remote feature of include), a warning is issued, and the include statement is left in place. To enable this support, run

./phc --compile-time-includes script_with_includes.php

The include support is intended to mimic PHP's include built-in, as far as can be achieved at compile time. phc supports:

• Moving included statements to the point at which include was called. Naturally, these statement's use the variable scope at the point at which they are included,
• Preserving __FILE__ and __LINE__ statements,
• Moving included functions to the %MAIN% class, and importing the included classes,
• include, and require. If the specified file cannot be found, parsed, or if the argument to include is not a string literal, the include statement is left in place.

• Return values in included scripts. We intend to support these in the future. They will likely be supported in a later stage of the compilation process, instead of in the AST,
• Calling include on anything other than a literal string containing the filename of a local file. This excludes variables and remote files. These may be supported when more static analyses are available,
• include_once and require_once, as we cannot guarantee that the file to be included is not included elsewhere. These statements will not be processed, and combinations of include or require and include_once or require_once may cause incorrect behaviour with this option set,
• Updating get_included_files() to reflect the included files.