Most Referenced Functions
  » google_pagerank()
  » preg_replace()
  » imagecreatefrompng()
  » site_pageranks()
  » imagepng()
  » imagedestroy()
  » imagestring()
  » imagecolorallocate()
  » htmlentities()
  » fopen()
  » preg_match()
  » header()
  » getimagesize()
  » htmlspecialchars()
  » session_start()
  » ob_start()
  » strstr()
  » ob_flush()
  » preg_match_all()
  » strpos()
  » flush()
  » setcookie()
  » str_replace()
  » array2vars()
  » nl2br()
  » preg_split()
  » ereg()
  » urlencode()
  » ereg_replace()
  » readgzfile()

Become a sponsor for $15/month. Link is sitewide - PR5 homepage, 20+ PR4 pages, 90+ PR3 pages. Email dave[AT]icemelon[D0T]c0m.

PHP Functions

Function: virtual

(PHP 3, PHP 4, PHP 5)

virtual -- Perform an Apache sub-request


bool virtual ( string filename )

virtual() is an Apache-specific function which is equivalent to <!--#include virtual...--> in mod_include. It performs an Apache sub-request. It is useful for including CGI scripts or .shtml files, or anything else that you would parse through Apache. Note that for a CGI script, the script must generate valid CGI headers. At the minimum that means it must generate a Content-type header.

To run the sub-request, all buffers are terminated and flushed to the browser, pending headers are sent too.

This function is only supported when PHP is installed as an Apache module.



The file that the virtual command will be performed on.

Return Values

Performs the virtual command on success, or returns FALSE on failure.


Version Description 4.0.6 This function may be used on PHP files. However, it is typically better to use include() or require() for PHP files.



The query string can be passed to the included file but $_GET is copied from the parent script and only $_SERVER['QUERY_STRING'] is filled with the passed query string. The query string may only be passed when using Apache 2. The requested file will not be listed in the Apache access log.

Note: As of PHP 4.3.3 you can use this function with the NSAPI server module in Netscape/iPlanet/SunONE webservers, too.

II. Advanced PHP debugger


APD is the Advanced PHP Debugger. It was written to provide profiling and debugging capabilities for PHP code, as well as to provide the ability to print out a full stack backtrace. APD supports interactive debugging, but by default it writes data to trace files. It also offers event based logging so that varying levels of information (including function calls, arguments passed, timings, etc.) can be turned on or off for individual scripts.


APD is a Zend Extension, modifying the way the internals of PHP handle function calls, and thus may or may not be compatible with other Zend Extensions (for example Zend Optimizer).


APD is currently available as a PECL extension from . Make sure you have installed the CGI version of PHP and it is available in your current path along with the phpize script.

Run the following command to download, build, and install the latest stable version of APD:

pear install apd

This automatically installs the APD Zend module into your PHP extensions directory. It is not mandatory to keep it there; you can store the module in any directory PHP can read as long as you set the zend_extension parameter accordingly.

Windows users can download the extension dll php_apd.dll from .

In your INI file, add the following lines:

zend_extension = /absolute/path/to/
apd.dumpdir = /absolute/path/to/trace/directory
apd.statement_tracing = 0

Depending on your PHP build, the zend_extension directive can be one of the following:

zend_extension              (non ZTS, non debug build)
zend_extension_ts           (    ZTS, non debug build)
zend_extension_debug        (non ZTS,     debug build)
zend_extension_debug_ts     (    ZTS,     debug build)

Building on Win32

To build APD under Windows you need a working PHP compilation environment as described on -- basically, it requires you to have Microsoft Visual C++,, bison/flex, and some know how to get it to work. Also ensure that adp.dsp has DOS line endings; if it has unix line endings, Microsoft Visual C++ will complain about it.

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini .

Table 1. APD Configuration Options

Name Default Changeable Changelog apd.dumpdir NULL PHP_INI_ALL   ini.apd.statement-tracing "0" PHP_INI_ALL   For further details and definitions of the PHP_INI_* constants, see the Appendix H .

Here's a short explanation of the configuration directives.

apd.dumpdir string

Sets the directory in which APD writes profile dump files. You can specify an absolute path or a relative path.

You can specify a different directory as an argument to apd_set_pprof_trace() .

apd.statement_tracing boolean

Specfies whether or not to do per-line tracings. Turning this on (1) will impact the performance of your application.

Resource Types

This extension has no resource types defined.

Predefined Constants

This extension has no constants defined.

How to use PHP-APD in your scripts

As the first line of your PHP script, call the apd_set_pprof_trace() function to start the trace:


You can insert the line anywhere in your script, but if you do not start tracing at the beginning of your script you discard profile data that might otherwise lead you to a performance bottleneck.

Now run your script. The dump output will be written to apd.dumpdir/pprof_pid.ext .

Tip: If you're running the CGI version of PHP, you will need to add the '-e' flag to enable extended information for apd to work properly. For example: php -e -f script.php

To display formatted profile data, issue the pprofp command with the sort and display options of your choice. The formatted output will look something like:

bash-2.05b$ pprofp -R /tmp/pprof.22141.0

Trace for /home/dan/testapd.php
Total Elapsed Time = 0.00
Total System Time  = 0.00
Total User Time    = 0.00

Real         User        System             secs/    cumm
%Time (excl/cumm)  (excl/cumm)  (excl/cumm) Calls    call    s/call  Memory Usage Name
100.0 0.00 0.00  0.00 0.00  0.00 0.00     1  0.0000   0.0009            0 main
56.9 0.00 0.00  0.00 0.00  0.00 0.00     1  0.0005   0.0005            0 apd_set_pprof_trace
28.0 0.00 0.00  0.00 0.00  0.00 0.00    10  0.0000   0.0000            0 preg_replace
14.3 0.00 0.00  0.00 0.00  0.00 0.00    10  0.0000   0.0000            0 str_replace

The -R option used in this example sorts the profile table by the amount of real time the script spent executing a given function. The "cumm call" column reveals how many times each function was called, and the "s/call" column reveals how many seconds each call to the function required, on average.

To generate a calltree file that you can import into the KCacheGrind profile analysis application, issue the pprof2calltree comand.

Contact information

If you have comments, bugfixes, enhancements or want to help developing this beast, you can send an mail to . Any help is very welcome.

Table of Contents apd_breakpoint  -- Stops the interpreter and waits on a CR from the socket apd_callstack  -- Returns the current call stack as an array apd_clunk  -- Throw a warning and a callstack apd_continue  -- Restarts the interpreter apd_croak  -- Throw an error, a callstack and then exit apd_dump_function_table  -- Outputs the current function table apd_dump_persistent_resources  -- Return all persistent resources as an array apd_dump_regular_resources  -- Return all current regular resources as an array apd_echo  -- Echo to the debugging socket apd_get_active_symbols  -- Get an array of the current variables names in the local scope apd_set_pprof_trace  -- Starts the session debugging apd_set_session_trace  -- Starts the session debugging apd_set_session  -- Changes or sets the current debugging level apd_set_socket_session_trace  -- Starts the remote session debugging override_function  -- Overrides built-in functions rename_function  -- Renames orig_name to new_name in the global function_table

Related Function(s)

  • include()
  • require()
  • apd_set_pprof_trace()
  • apd_breakpoint()
  • apd_callstack()
  • apd_clunk()
  • apd_continue()
  • apd_croak()
  • apd_dump_function_table()
  • apd_dump_persistent_resources()
  • apd_dump_regular_resources()
  • apd_echo()
  • apd_get_active_symbols()
  • apd_set_session_trace()
  • apd_set_session()
  • apd_set_socket_session_trace()
  • override_function()
  • rename_function()
  • Icemelon -- PHP, CSS, Javascript Tutorials, & More!
      © 2005-2010   Email: dave[AT]icemelon[D0T]c0m