Introduction

forp is a lightweight PHP extension which provides PHP profile datas.

Summary of features :

• measurement of time and allocated memory for each function
• CPU usage
• file and line number of the function call
• output as Google's Trace Event format
• caption of functions
• grouping of functions
• aliases of functions (useful for anonymous functions)

forp is non intrusive, it provides PHP annotations to do its work.

Simple (almost the most complicated) example

Example :

<?php
// first thing to do, enable forp profiler
forp_start();

// here, our PHP code we want to profile
function foo()
{
    echo "Hello world !\n";
};

foo();

// stop forp buffering
forp_end();

// get the stack as an array
$profileStack = forp_dump();

print_r($profileStack);

Result :

Hello world !
Array
(
    [utime] => 0
    [stime] => 0
    [stack] => Array
        (
            [0] => Array
                (
                    [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php
                    [function] => {main}
                    [usec] => 94
                    [pusec] => 6
                    [bytes] => 524
                    [level] => 0
                )

            [1] => Array
                (
                    [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php
                    [function] => foo
                    [lineno] => 10
                    [usec] => 9
                    [pusec] => 6
                    [bytes] => 120
                    [level] => 1
                    [parent] => 0
                )

        )

)

Example with annotations

Example :

<?php
// first thing to do, enable forp profiler
forp_start();

/**
 * here, our PHP code we want to profile
 * with annotations
 *
 * @ProfileGroup("Test")
 * @ProfileCaption("Foo #1")
 * @ProfileAlias("foo")
 */
function fooWithAnnotations($bar)
{
    return 'Foo ' . $bar;
}

echo "foo = " . fooWithAnnotations("bar") . "\n";

// stop forp buffering
forp_end();

// get the stack as an array
$profileStack = forp_dump();

echo "forp stack = \n";
print_r($profileStack);

Result :

foo = Foo bar
forp stack =
Array
(
    [utime] => 0
    [stime] => 0
    [stack] => Array
        (
            [0] => Array
                (
                    [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php
                    [function] => {main}
                    [usec] => 113
                    [pusec] => 6
                    [bytes] => 568
                    [level] => 0
                )

            [1] => Array
                (
                    [file] => /home/anthony/phpsrc/php-5.3.8/ext/forp/forp.php
                    [function] => foo
                    [lineno] => 41
                    [groups] => Array
                        (
                            [0] => Test
                        )

                    [caption] => Foo bar
                    [usec] => 39
                    [pusec] => 24
                    [bytes] => 124
                    [level] => 1
                    [parent] => 0
                )

        )

)

php.ini options

• forp.max_nesting_level : default 50
• forp.no_internals : default 0

forp PHP API

• forp_start(flags*) : start forp collector
• forp_end() : stop forp collector
• forp_dump() : return stack as flat array
• forp_print() : display forp stack (SAPI CLI)

forp_start() flags

• FORP_FLAG_CPU : activate collect of time
• FORP_FLAG_MEMORY : activate collect of memory usage
• FORP_FLAG_CPU : retrieve the cpu usage
• FORP_FLAG_CAPTION : enable caption handler
• FORP_FLAG_ALIAS : enable alias handler
• FORP_FLAG_GROUPS : enable groups handler
• FORP_FLAG_HIGHLIGHT : enable HTML highlighting

forp_dump()

forp_dump() provides an array composed of :

• global fields : utime, stime ...
• stack : a flat PHP array of stack entries.

Global fields :

• utime : CPU used for user function calls
• stime : CPU used for system calls

Fields of a stack entry :

• file : file of the call
• lineno : line number of the call
• class : Class name
• function : function name
• groups : list of associated groups
• caption : caption of the function
• usec : function time (without the profiling overhead)
• pusec : inner profiling time (without executing the function)
• bytes : memory usage of the function
• level : depth level from the forp_start call
• parent : parent index (numeric)

forp_json()

Prints stack as JSON string directly on stdout. This is the fastest method in order to send the stack to a JSON compatible client.

See forp_dump() for its structure.

forp_json_google_tracer()

forp_json_google_tracer($filepath) will output stack as Google Trace Event format.

Usage :

// Start profiler
forp_start();

my_complex_function();

// Stop profiler
forp_end();

// Get JSON and save it into file
forp_json_google_tracer("/tmp/output.json");

Then, open Google Chrome or Chromium browser and go to chrome://tracing/. Load the output file and enjoy the result.

forp_inspect()

forp_inspect('symbol', $symbol) will output a detailed representation of a variable in the forp_dump() result.

Usage :

$var = array(0 => "my", "strkey" => "inspected", 3 => "array");
forp_inspect('var', $var);
print_r(forp_dump());

Result :

Array
(
    [utime] => 0
    [stime] => 0
    [inspect] => Array
        (
            [var] => Array
                (
                    [type] => array
                    [size] => 3
                    [value] => Array
                        (
                            [0] => Array
                                (
                                    [type] => string
                                    [value] => my
                                )

                            [strkey] => Array
                                (
                                    [type] => string
                                    [value] => inspected
                                )

                            [3] => Array
                                (
                                    [type] => string
                                    [value] => array
                                )

                        )

                )

        )

)

Available annotations

• @ProfileGroup

Sets groups that function belongs.

/**
 * @ProfileGroup("data loading","rendering")
 */
function exec($query) {
    /* ... */
}

• @ProfileCaption

Adds caption to functions. Caption string may contain references (#) to parameters of the function.

/**
 * @ProfileCaption("Find row for pk #1")
 */
public function findByPk($pk) {
    /* ... */
}

• @ProfileAlias

Gives an alias name to a function. Useful for anonymous functions

/**
 * @ProfileAlias("MyAnonymousFunction")
 */
$fn = function() {
    /* ... */
}

• @ProfileHighlight

Adds a frame around output generated by the function.

/**
 * @ProfileHighlight("1")
 */
function render($datas) {
    /* ... */
}

Demos / UI

forp provides a structure so simple that it's easy to make your own UI.

But, if you are looking for a user interface with a lot of features, we've made a rich JavaScript client : forp-ui

You can see forp in action with the fastest PHP Frameworks :

• Beaba (https://github.com/ichiriac/beaba-light)
• Slim (https://github.com/codeguy/Slim)
• Silex (https://github.com/fabpot/Silex)
• Laravel (https://github.com/laravel/laravel)

Build status

Installation, requirements

Requirements

php5-dev

apt-get install php5-dev

Install with Composer

Require forp-PHP-profiler in your project composer.json

"require-dev":       {
  "aterrien/forp-profiler" : "~1.1"
},
"repositories" : [
  {
     "type" : "git",
     "url"  : "git@github.com:aterrien/forp-PHP-profiler.git"
  }
]

run Composer install

php composer.phar install

compile

cd vendor/aterrien/forp-profiler/ext/forp
phpize
./configure
make && make install

and enable forp in your php.ini

extension=forp.so

or opt for "old school" installation

Use current release

wget https://github.com/aterrien/forp/archive/1.1.0.tar.gz
tar -xvzf 1.1.0.tar.gz
cd 1.1.0/ext/forp

OR dev-master (unstable, at your own risk)

git clone https://github.com/aterrien/forp-PHP-profiler
cd forp-PHP-profiler/ext/forp

compile

phpize
./configure
make && make install

and enable forp in your php.ini

extension=forp.so

Tested OS and platforms

Apache

Apache/2.2.16 (Debian)

PHP 5.3.8 (cli) (built: Sep 25 2012 22:55:18)

Nginx / php-fpm

nginx version: nginx/1.2.6

PHP 5.3.21-1dotdeb.0 (fpm-fcgi) PHP 5.4.10-1dotdeb.0 (fpm-fcgi)

Cloud / AWS

Centos 6.3 (AMI)

Apache/2.2.15 (Unix)

PHP 5.4.13 (cli) (built: Mar 15 2013 11:27:51)

Contributors

Anthony Terrien, Ioan Chiriac, Alexis Okuwa, TOMHTML