forp

A simple, non intrusive, production-oriented,
PHP profiler.
View source and download from Github

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 PHP API

forp_start() flags

forp_dump()

forp_dump() provides an array composed of :

Global fields :

Fields of a stack entry :

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.

Example output with an existing Drupal website

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

Sets groups that function belongs.

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

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

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

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

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

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)

groups

Build status

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-1~dotdeb.0 (fpm-fcgi)
PHP 5.4.10-1~dotdeb.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

Home   |  forp-ui, UI for forp