XMake version: 0.93a
Release Date: 08/17/05
Copyright (c) 2003 Gregory Keranen. All rights reserved.


Introduction Installation Usage Configuration PHP Command Line Environment XMake/phpc Execution Environment Simulated Web Server Environment Error Handling & Quality Control File Dependencies Static & Dynamic Templating Makefile Customization .phpc Source File Security PHP Bugs: Exit Status of the PHP Command


An introductory slide show from International PHP Conference 2003, in Amsterdam is bundled with the xmake distribution. This is also an excellent example of how to use XMake with PHP: phpconf2003/slides/index.html


The 'phpc' XMExtension, requires the command-line version of PHP ("PHP CLI SAPI", or "PHP CLI"). PHP versions >=4.3.2 are recommended, although earlier versions will work. To install PHP, compile PHP sources and run; make install-cli This will copy the command-line binary, sapi/cli/php, to /usr/local/bin/php, unless you configured the option ./configure --prefix=/some/other/path Alternatively will be installed as /usr/local/bin/php, if you configure in one of the following ways: ./configure --with--apxs ... or ./configure --disable-cgi ... then: make install See: http://www.php.net/manual/en/features.commandline.php Relevant points, excerpted from the above link: As of PHP 4.3.0, the name, location and existence of the CLI/CGI binaries will differ depending on how PHP is installed on your system. By default when executing make, both the CGI and CLI are built and placed as sapi/cgi/php and sapi/cli/php respectively, in your php source directory. You will note that both are named php. What happens during make install depends on your configure line. If a module SAPI is chosen during configure, such as apxs, or the --disable-cgi option is used, the CLI is copied to {PREFIX}/bin/php during make install otherwise the CGI is placed there. So, for example, if --with--apxs is in your configure line then the CLI is copied to {PREFIX}/bin/php during make install. If you want to override the installation of the CGI binary, use make install-cli after make install. Alternatively you can specify --disable-cgi in your configure line.


To Use XMake with PHP: + Configure XMake: enable 'phpc' XMExtension + Install PHP CLI SAPI (see above) + Create a new project with 'xmakep' command + Create some source files with .phpc suffix + Process all source files with 'xmake' command + Optional: create custom makefile rules XMake does not ordinarily process .php files; only .phpc files. This naming convention distinguishes environmental requirements: .php files may require a web server environment whereas .phpc files do not.


phpc XMExtension provides configurable options which can be set in the project config file, XMake.conf, or, globally, in ../config/XMExtensions/phpc.conf If set globally, settings will be copied to all XMake.conf files created with 'xmakep' command.

PHP Command Line Environment

There are several important differences in how CLI SAPI behaves compared to other PHP binaries. The PHP manual describes these differences in detail: http://www.php.net/manual/en/features.commandline.php NOTE: The CGI version, used from the command line, is NOT a substitute since it does not allow '-r' option, used by phpc pattern rules "SAPI" (Server Application Programming Interface) is somewhat misleading when applied to the command line PHP binary, since command line PHP scripts execute WITHOUT any server involved at all. Scripts which assume a web server environment probably will not work correctly with CLI SAPI: environmental variables, such as $DOCUMENT_ROOT, $REQUEST_URI (and $_SERVER["DOCUMENT_ROOT"], $_SERVER["REQUEST_URI"]) will not be defined. When processing .phpc files, the following conditions apply: + XMake always changes directory to that of a .phpc file before invoking PHP + Any .phpc script can easily include files in the same directory, with only a filename as relative path. This makes up for the fact that PHP CLI does not change the current directory to the directory of the executed script. Your script can reliably determine the directory it is executing from with getcwd().

XMake/phpc Execution Environment

phpc XMExtension uses makefile macros to execute .phpc files (or any PHP files you want) within an enhanced command line PHP environment. Full details of how this works are contained in the source files: + ../config/XMExtensions/phpc.mkh + ../config/XMExtensions/phpc.mkr + ../config/XMExtensions/phpc.inc .phpc files are processed by XMake by including them within a command line of the (simplified) form: /path/to/php \ -c ${XMAKE_EXT_PHPC_PHP_INI} \ -d log_errors=1 \ -d error_log= \ -d display_errors=0 \ -d display_startup_errors=0 \ -r '... \ include(getenv("XMAKE_HOME")."/config/XMExtensions/phpc.inc"); ... \ $XMAKE_XME_PHPC_ERROR_REPORTING_MASK = getenv("XMAKE_XME_PHPC_ERROR_REPORTING_MASK"); \ error_reporting($XMAKE_XME_PHPC_ERROR_REPORTING_MASK); \ /* set some PHP globals */ \ set_error_handler("phpc_error_handler"); \ /* execute any PHP code passed in: */ \ include("/path/to/myFile.phpc"); \ ...' \ 1> "/path/to/myFile" ... Important functions for error handling, file dependency detection and other utility functions are included in the file ${XMAKE_HOME}/config/XMExtensions/phpc.inc. XMake.conf options can be used to simulate a web server environment (see discussion below). phpc.inc sets several PHP globals variables to the full path of the current script, resolving any symbolic links to the current directory. The affected variables are: $_SERVER["PHP_SELF"] $_SERVER["SCRIPT_NAME"] $_SERVER["SCRIPT_FILENAME"] $_SERVER["PATH_TRANSLATED"] $HTTP_SERVER_VARS["PHP_SELF"] $HTTP_SERVER_VARS["SCRIPT_NAME"] $HTTP_SERVER_VARS["SCRIPT_FILENAME"] $HTTP_SERVER_VARS["PATH_TRANSLATED"] $_SERVER["SCRIPT_FILENAME"] and $_SERVER["PATH_TRANSLATED"] will have the same values in PHP CLI context as they would have running in a web server context. $_SERVER["PHP_SELF"] and $_SERVER["SCRIPT_NAME"] are not the same, since these would be relative to $_SERVER["DOCUMENT_ROOT"].

Simulated Web Server Environment

phpc.inc uses the XMake.conf variable XMAKE_EXT_PHPC_GLOBAL_INC to allow you to easily simulate a web server environment in command line phpc scripts. The absence of $DOCUMENT_ROOT in the command line context is of special concern since it is often useful for .phpc scripts to create valid links to other files that will be referenced at run time. In the project XMake.conf file, set the variable XMAKE_EXT_PHPC_GLOBAL_INC: export XMAKE_EXT_PHPC_GLOBAL_INC=${XMAKE_PROJECT_DIR}/phpc.global.inc This file will be automatically included by XMake, prior to including any .phpc source files. Now create the file 'phpc.global.inc' in your project directory to set any global variables you need; or copy and edit the included sample ../config/XMExtensions/phpc.global.inc Now your scripts can create static links that will work in any web server environment. Simply set $DOCUMENT_ROOT in the XMake project equal to the same value as $DOCUMENT_ROOT that applies to the project and reference it from your .phpc file, for example: <?php echo '<a href="'.$_SERVER['DOCUMENT_ROOT'].'relative/path/to/file.html">file.html</a>'; ?> EXAMPLE: If you use Apache and have several virtual servers configured below the apache/htdocs/ directory, generally you should create a separate XMake project in the DocumentRoot directory corresponding to each VirtualHost directive and create a 'phpc.global.inc' file in each XMake project, setting XMAKE_DOCUMENT_ROOT=[VirtualHost DocumentRoot value]

Error Handling & Quality Control

One of the greatest weaknesses of PHP, and web applications in general, is in the area of quality control. Although excellent debugging tools, such as DBG, Zend IDE, are available, these are designed for manual debugging of individual scripts rather than routine, automated batch processing of an entire site. XMake supports automated testing of fatal errors in .phpc files, as part of the routine build process, as well as lint checking for .phpc and .php files. When you process a .phpc file with XMake, you simultaneously test it: the build process succeeds or fails, based on the exit status of each source file. If fatal errors are encountered, no output file is written. XMake gives you complete control over what level of error codes trigger fatal exit status and, hence, the overall quality of your code is maintained at whatever level you desire. First, some recommended coding conventions: always use trigger_error(...) instead of echo(...); exit(1); for error messages. XMake actually works around this and displays STDOUT on STDERR, but only if a fatal error is generated. POOR: <?php // echo always goes to STDOUT echo("file doesn't exist\n"); exit(1); ?> PREFERRED: <?php // XMake displays on STDERR and exits, at build time trigger_error("file doesn't exist",E_USER_ERROR ); ?> The phpc XMExtension attempts to achieve a clean separation of error messages from normal script output by always setting these php.ini options when invoking PHP CLI: /path/to/php -c /path/to/php.ini \ -d log_errors=1 \ -d error_log= \ -d display_errors=0 \ -d display_startup_errors=0 log_errors=1 - sends errors to error_log, or /dev/stderr error_log= - empty value causes error_log() to use /dev/stderr; inhibits prepending of date to error message for display purposes, as would be the case, if error_log="/dev/stderr" was used. display_errors=0 - don't want errors on STDOUT display_startup_errors=0 - we get all errors on STDERR anyway with logging The desired data flow is: +-> stdout -> myFile | no myFile.phpc -> [xmake-PHP-xmake] --> [error?] | yes +-> stderr -> console We say 'desired' data flow because PHP has some bugs and limitations: + BUG: default error handler sometimes writes to STDOUT instead of STDERR XMake tries to work around this potential issue by dumping STDOUT to STDERR However, this only works for FATAL errors + BUG: fatal errors may not always exit with correct status This happened with require(), until recently; there may be other bugs lurking XMake uses a workaround, for backward compatibility + system errors (E_ERROR, E_CORE_WARNING, etc.) CANNOT be handled with custom error handler; non-fatal errors such as E_CORE_WARNING may occur during startup (prior to installation of custom error handler) You cannot control the fatality of such errors but they should all go to STDERR They key to automated testing is controlling the exit status of scripts. While PHP scripts can control exit status with exit(), it is more effectively managed using a custom error handler. PHP's set_error_handler() function is the primary tool which XMake uses to handle script errors. XMake is bundled with a custom PHP error handler, phpc_error_handler(), which is installed by default before .phpc scripts are parsed. It supports these features: control over which error codes cause 'FATAL' (non-zero) exit status correct routing of all error messages to /dev/stderr custom formatting of error message output phpc_error_handler() and other functions for error handling and file dependency detection are included in: xmake/config/XMExtensions/phpc.inc PHP's default error handler does not allow you to change the level at which errors cause non-zero (fatal) exit status. Changing the error reporting level does not affect exit status; it only affect the level at which error messages are displayed or logged. The default PHP error handler sets the fatal error level to: E_ERROR|E_PARSE|E_CORE_ERROR|E_COMPILE_ERROR|E_USER_ERROR = 1|4|16|64|256 = 341 Warnings, such as E_WARNING are not fatal and will exit normally, with the default error handler. This approach assumes that individual scripts must contain logic to test for non-fatal errors and to 'promote' the error level to E_USER_ERROR, if they should be fatal with something like the following: <?php // failure of readfile("non_existent_file") is not fatal; // E_WARNING error is generated if (!file_exists($file)){ trigger_error("file doesn't exist\n",E_USER_ERROR ); } else { readfile($file); } ?> There are a few of problems with the above approach: Legacy code may not have robust error handling; no custom handler New code may contain bugs; warnings that should be fatal You may want to control your code more selectively, without modifying sources XMake allows user-control over the fatal error level by means of a global variable, XMAKE_XME_PHPC_FATAL_ERROR_MASK, in the project configuration file, XMake.conf. By default, phpc_error_handler() exits with any error except NOTICE level: XMAKE_XME_PHPC_FATAL_ERROR_MASK=770 E_WARNING|E_USER_ERROR|E_USER_WARNING=2|256|512=770 The following errors are always handled by PHP internally, and cannot be handled with any handler installed with set_error_handler(): E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING, E_ERROR, E_PARSE, E_CORE_ERROR If another custom error handler function is installed, from within any script, it will override the phpc_error_handler() function, installed by XMake. It is recommended that any custom error handlers follow the example of phpc_error_handler() to always Do The Right Thing, by supporting control of fatal error levels and proper redirection of error messages to STDERR.

Lint Checking

The built-in PHP CLI 'lint' option, 'php -l ...', is almost useless since it only detects E_PARSE errors, which are fatal and, therefore, always caught by XMake anyway. PHP lint checking is built in to XMake, for both *.php and *.phpc files, using targets: 'php.lint' and 'phpc.lint'. Fatal error levels are configured in XMake.conf: # by default, non-fatal errors are not 'promoted': XMAKE_XME_PHPC_LINT_FATAL_ERROR_MASK=0 WARNING: Lint checking EXECUTES all *.php or *.phpc scripts in the XMake project tree. If you have a script lying around that could do bad things like <?php system("rm -rf /;");?> then it most likely WILL do those things if it resides within an XMake project and you execute 'xmake php.lint' or 'xmake phpc.lint'. Of course, this depends on the file permissions in effect.

File Dependencies

The most important requirement in writing .phpc files is to enable XMake to know about all file dependencies: any file used by a PHP script could affect the output and is considered a prerequisite file - any changes to prerequisites cause Make to rebuild the output file. In the case of included and required files, XMake will determine these automatically by calling the built in function, get_included_files(). In all other cases, when a script accesses a file with file(), readfile(), etc., there is no way for XMake to know of these dependencies unless the programmer includes logic to register such files. XMake provides a function which handles registration of file dependencies: void phpc_add_prerequisites( mixed $prerequisiteFiles ) phpc_add_prerequisites() accepts a single filename string or array of filenames as input. EXAMPLE: example1.phpc <?php // suppose you want to use 'file1' in the same directory as this script: $prerequisite_file='file1'; phpc_add_prerequisites( $prerequisite_file ); readfile($prerequisite_file); ?> Perhaps the trickiest aspecs of using PHP with XMake is: 1. Determining what the prerequisite files are 2. Remembering to call phpc_add_prerequisites($file) when your script uses a $file 3. Make sure phpc_add_prerequisites() is called for all files used, IN ALL POSSIBLE CODE PATHS. Dependencies are determined by XMake simply by executing the source file, without knowledge of any particular modes of use: parameters, global vars, etc. that might affect what code gets executed in building any particular targets. The points to keep in mind are: 1. All files which affect script behavior, other than those inside include() or require() statements, must be passed to phpc_add_prerequisites(). 2. You can call phpc_add_prerequisites() at any point, before or after using the registered files since XMake disgards all input when determining prerequisites: dependency makefiles are made when the makefile is parsed, PRIOR to building all other targets, such as output files. 3. To force XMake to always rebuild a file, use: phpc_add_prerequisites( "FORCE" ); 4. If you use remote files, use: phpc_add_prerequisites( "FORCE" ); Sometimes determining prerequisites is obvious - as in the above example when readfile() is called to output the contents of a file - but sometime it is not. Consider the following case: example2.phpc <?php if (file_exists("volatile_file")) echo("file exists"); ?> What is the prerequisite of example2.phpc? "volatile_file"? No. It is the directory containing "volatile_file" since it will change if "volatile_file" is created or deleted; if "volatile_file" was registered as a prerequisite, then example2 would not be re-made if "volatile_file" were deleted. The correct usage is: example2.phpc <?php if (file_exists("volatile_file")) echo("file exists"); phpc_add_prerequisites( getcwd() ); ?> Consider another example: example3.phpc <?php echo(disk_free_space ( getcwd())); ?> What is the the prerequisite file here? The current directory? NO! In this case, all files below the current directory, including all directories, could be registered as prerequisite files, but that would be very cumbersome to code. What we really want is to FORCE XMake to always re-make the output file related to this script. This is accomplished with the special PHONY makefile target: 'FORCE' (case-sensitive). Since Make always considers PHONY prerequisites out of date, adding "FORCE" as a prerequisite has the desired effect of making the output file always appear out of date. The correct usage is: example3.phpc <?php echo(disk_free_space ( getcwd())); phpc_add_prerequisites( "FORCE" ); ?> The above example can apply to any dynamic script: example4A.phpc <?php echo("the time is:".date("D M j G:i:s T Y")); phpc_add_prerequisites( "FORCE" ); ?> But you wouldn't use it in this case: example4B.phpc <?php // no prerequisites echo("Hello World"); echo("This file was last updated on:".date("D M j G:i:s T Y")); ?> Another case for using "FORCE", is when accessing remote files: example5.phpc <?php $html = implode ('', file ('http://www.example.com/ ')); echo $html; phpc_add_prerequisites( "FORCE" ); ?> Gnu Make cannot read the file modification times of http or ftp resources such as, http://www.example.com/ ; it only handles files on locally mounted filesystems.

Static & Dynamic Templating

To create dynamic .php files from .phpc files, it is necessary to pass run-time code through as text - i.e., outside of any <?php ... ?> processing instruction tags. This can be accomplished in two ways: 1. using readfile(), instead of include() or require(), to output code from another file 2. embed dynamic code directly, as plain text Case 1: using readfile(): <?php // register prerequiste file: $prerequisite_file="dynamic_code.php.inc"; phpc_add_prerequisites( $prerequisite_file ); readfile($prerequisite_file); ?> Case 2: embedded, using phpc constants: <?= PHP_OPEN_TAG;?> // code to execute at run time <?= PHP_CLOSE_TAG;?>

Makefile Customization

The default makefile pattern rule used for processing .phpc source files applies to all .phpc, unless you write custom rules. Because the default rule is a generic rule, it does not pass any custom options or variable settings to the source files. In order to make the most of XMake, we can write custom rules to allow cusom PHP code to be evaluated in global scope prior to evaluating a source file. Make requires escaping '$', which is a little ugly but worth the price: this technique allow you to pass arbitrary code, not just command line arguments. Another advantage is that you can pass arrays from XMake to PHP, without multiple assignments ('php -f myfile.php a[]=a a[]=b a[]=c') or serialization, for example, as would be required otherwise. EXAMPLE: creating explicit rules for .phpc files # $(XMAKE_PROJECT_DIR)/XMakefile.mks # XME_explicitRule USAGE: # $(eval $(call # XME_explicitRule,$(ext),$(srcfile),$(prerequisites),$(cmdOptions))) # '$' must be escaped by '$$$$' if used in a variable php_code:=$$$$user="greg"; $(eval $(call XME_explicitRule,phpc,$(CURDIR)/custom1.php.phpc,,$(php_code))) # '$' must be escaped by '$$' if passed directly $(eval $(call XME_explicitRule,phpc,$(CURDIR)/custom2.php.phpc,,$$user="greg";)) # EOF XMake is not limited to creating output from .phpc files with a one-to-one source->output file mapping. You can use phpc makefile macros to provide a one-to-many source->output file relationship with .php source files, for example. EXAMPLE: using phpc macros to create rules for .php files # Makefile example # create localized output from a PHP script; pass runtime parameters LOCALIZED_OUTFILES:=$(CURDIR)/multi-lingual.en $(CURDIR)/multi-lingual.fr $(LOCALIZED_OUTFILES): $(CURDIR)/multi-lingual.% :$(CURDIR)/multi-lingual.php @$(call XME_phpc_outfileMacro,$(CURDIR)/multi-lingual.php,$$lang="$*";,$@) # EOF

.phpc Source File Security

Two choices: 1. Don't upload these files to a public server. Instead, create an 'upload' target that excludes all *.phpc files 2. Configure Apache with the following .htaccess options: This method is preferred since it is fastest: .phpc files are parsed like .php files: #for PHP3 AddType application/x-httpd-php3 .phpc #for PHP4 AddType application/x-httpd-php .phpc OR: use <Files ...> directive to give the user a "permission denied" error when any .phpc file is requested. Slower than the AddType method since every requested file must be matched against the pattern. <Files ~ ".phpc"> Order allow,deny Deny from all </Files>

PHP Bugs: Exit Status of the PHP Command

For XMake to work correctly, it depends on receiving the correct exit status from commands used by XMExtensions: when a command fails, it must return non-zero exit status to the shell. For phpc XMExtension to work correctly, PHP must exit with non-zero status when fatal errors occur. PHP versions prior to 4.3.2-RC of Mar 19 2003 exhibit a bug and FAIL to exit properly. Bug #22775: Fatal error from require() exits with status=0. See: http://bugs.php.net/bug.php?id=22775 Therefore, either use PHP >= 4.3.2, or use the following workaround in your scripts, for prior versions. The only workaround is to never use require(). ${XMAKE_HOME}/config/XMExtensions/phpc.inc contains a workaround function, phpc_require_once(), which uses include(), calling exit(1), if the file doesn't exist. All bundled XMake PHP scripts use the above workaround and will work correctly with PHP versions >= 4.3.0 (and possibly earlier).