{"id":20520783,"url":"https://github.com/perftools/php-profiler","last_synced_at":"2025-05-15T09:08:07.099Z","repository":{"id":39578659,"uuid":"176778802","full_name":"perftools/php-profiler","owner":"perftools","description":"A PHP profiling library based on XHGUI Data Collector","archived":false,"fork":false,"pushed_at":"2025-02-21T09:05:23.000Z","size":217,"stargazers_count":151,"open_issues_count":8,"forks_count":28,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-11T23:45:50.746Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perftools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-20T16:55:22.000Z","updated_at":"2025-04-24T05:52:26.000Z","dependencies_parsed_at":"2025-02-05T15:01:03.401Z","dependency_job_id":"f6d2cf3f-aefa-4c27-88be-1a422cebd5a8","html_url":"https://github.com/perftools/php-profiler","commit_stats":{"total_commits":235,"total_committers":7,"mean_commits":33.57142857142857,"dds":"0.19148936170212771","last_synced_commit":"b5051e96679aa0d6cb3afe9a13a4e6a1fd890fea"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perftools%2Fphp-profiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perftools%2Fphp-profiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perftools%2Fphp-profiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perftools%2Fphp-profiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perftools","download_url":"https://codeload.github.com/perftools/php-profiler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310520,"owners_count":22049470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T22:22:55.499Z","updated_at":"2025-05-15T09:08:02.066Z","avatar_url":"https://github.com/perftools.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Profiler\n\nA PHP profiling library to submit profilings to [XHGui][xhgui].\n\nSupported profilers:\n - [Tideways XHProf v5.x](#tideways-xhprof-5): PHP \u003e= 7.0\n - [XHProf](#xhprof): PHP \u003e= 5.3, PHP \u003e= 7.0\n - [Tideways v4.x](#tideways-4x): PHP \u003e= 7.0\n - [UProfiler](#uprofiler): PHP \u003e= 5.3, \u003c PHP 7.0\n\nThis profiling library will auto-detect any supported profiler and use that.\nThe specific profiler can be chosen by `profiler` config key.\n\n[xhgui]: https://github.com/perftools/xhgui\n\n## Goals\n\n - Compatibility with PHP \u003e= 5.3.0\n - No dependencies aside from the relevant extensions\n - Customizable and configurable so you can build your own logic on top of it\n\n## Usage\n\nIn order to profile your application, you need to:\n- [Install this package](#installation)\n- [Install profiler extension](#installing-profilers)\n- [Instantiate the profiler](#create-profiler)\n- [Configure saver to send data to XHGui](#savers)\n- [Import jsonl files](#import-jsonl-files) (optional)\n\n## Installation\n\nThe supported way to install this package is via [composer]:\n\n```\ncomposer require perftools/php-profiler\n```\n\n[composer]: https://getcomposer.org/\n\n## Create profiler\n\nCreating profiler would be something like this:\n\n```php\n\u003c?php\n\n// Add this block inside some bootstrapper or other \"early central point in execution\"\ntry {\n    /**\n     * The constructor will throw an exception if the environment\n     * isn't fit for profiling (extensions missing, other problems)\n     */\n    $profiler = new \\Xhgui\\Profiler\\Profiler($config);\n\n    // The profiler itself checks whether it should be enabled\n    // for request (executes lambda function from config)\n    $profiler-\u003estart();\n} catch (Exception $e){\n    // throw away or log error about profiling instantiation failure\n}\n```\n\nIf you need to disable profiler doing `flush`, `session_write_close` and\n`fastcgi_finish_request` at the end of profiling, pass `false` to register\nshutdown handler:\n\n```php\n$profiler-\u003estart(false);\n```\n\n## Using config file\n\nYou can create `config/config.php` and load config from there:\n\n1. copy `config/config.default.php` to `config/config.php`\n2. use `Config::create()` to `new Profiler`\n\n```php\n// Config::create() will load config/config.default.php\n// and then merge with config/config.php (if it exists).\n$config = \\Xhgui\\Profiler\\Config::create();\n$profiler = new \\Xhgui\\Profiler\\Profiler($config);\n```\n\n## Advanced Usage\n\nYou might want to control capture and sending yourself,\nperhaps modify data before sending.\n\n```php\n/** @var \\Xhgui\\Profiler\\Profiler $profiler */\n// start profiling\n$profiler-\u003eenable($flags, $options);\n\n// run program\nfoo();\n\n// stop profiler\n$profiler_data = $profiler-\u003edisable();\n\n// send $profiler_data to saver\n$profiler-\u003esave($profiler_data);\n```\n\n## Autoloader\n\nTo be able to profile autoloader, this project provides `autoload.php` that\nloads classes needed to start up the profiler.\n\nLoad it before loading composer autoloader:\n\n```php\n\nrequire_once '/path/to/your/project/vendor/perftools/php-profiler/autoload.php';\n\n$profiler = new \\Xhgui\\Profiler\\Profiler($config);\n$profiler-\u003estart();\n\nrequire_once '/path/to/your/project/vendor/autoload.php';\n```\n\nLoading composer autoloader is still needed when saving results to MongoDB or PDO directly.\n\n## Config\n\nReference config of what can be configured:\n\n- [examples/autoload.php](examples/autoload.php)\n\nIt includes all configuration options and inline documentation about the options.\n\n## Savers\n\nTo deliver captured data to XHGui, you will need one of the savers to submit to the datastore XHGui uses.\n\n- [Stack saver](#stack-saver)\n- [Upload saver](#upload-saver)\n- [File saver](#file-saver)\n- [MongoDB Saver](#mongodb-saver) (deprecated)\n- [PDO Saver](#pdo-saver) (deprecated)\n- [Custom Saver](#custom-saver) Custom saver\n\n### Stack saver\n\nAllows saving to multiple handlers.\n\nThe example config configures to use Upload Saver, and if that fails, save to File Saver:\n\n```php\n    'save.handler' =\u003e \\Xhgui\\Profiler\\Profiler::SAVER_STACK,\n    'save.handler.stack' =\u003e array(\n        'savers' =\u003e array(\n            \\Xhgui\\Profiler\\Profiler::SAVER_UPLOAD,\n            \\Xhgui\\Profiler\\Profiler::SAVER_FILE,\n        ),\n        // if saveAll=false, break the chain on successful save\n        'saveAll' =\u003e false,\n    ),\n    // subhandler specific configs\n    'save.handler.file' =\u003e array(\n        'filename' =\u003e '/tmp/xhgui.data.jsonl',\n    ),\n    'save.handler.upload' =\u003e array(\n        'url' =\u003e 'https://example.com/run/import',\n        'timeout' =\u003e 3,\n        'token' =\u003e 'token',\n    ),\n```\n\n### Upload saver\n\nThis is the recommended saver as it's the easiest to set up.\n\nExample config:\n\n```php\n    'save.handler' =\u003e \\Xhgui\\Profiler\\Profiler::SAVER_UPLOAD,\n\n    // Saving profile data by upload is only recommended with HTTPS\n    // endpoints that have IP whitelists applied.\n    'save.handler.upload' =\u003e array(\n        'url' =\u003e 'https://example.com/run/import',\n        // The timeout option is in seconds and defaults to 3 if unspecified.\n        'timeout' =\u003e 3,\n        // the token must match 'upload.token' config in XHGui\n        'token' =\u003e 'token',\n        // verify option to disable ssl verification, defaults to true if unspecified.\n        'verify' =\u003e true,\n    ),\n```\n\n### File saver\n\nIf your site cannot directly connect to your XHGui instance, you can choose\nto save your data to a temporary file for a later import to XHGui.\n\nExample config:\n\n```php\n    'save.handler' =\u003e \\Xhgui\\Profiler\\Profiler::SAVER_FILE,\n    'save.handler.file' =\u003e array(\n        // Appends jsonlines formatted data to this path\n        'filename' =\u003e '/tmp/xhgui.data.jsonl',\n    ),\n```\n\nTo import a saved files, see [Import jsonl files](#import-jsonl-files) section.\n\n### MongoDB Saver\n\nNOTE: Saving directly to MongoDB is discouraged, use Upload/File/Stack saver instead.\n\nFor saving directly to MongoDB you would need [ext-mongo] for PHP 5\nand [ext-mongodb] with [alcaeus/mongo-php-adapter] package for PHP 7\nalong with `perftools/xhgui-collector` package:\n\nfor PHP 5:\n```\npecl install mongo\ncomposer require perftools/xhgui-collector\n```\n\nfor PHP 7:\n```\npecl install mongodb\ncomposer require perftools/xhgui-collector alcaeus/mongo-php-adapter\n```\n\n[ext-mongo]: https://pecl.php.net/mongo\n[ext-mongodb]: https://pecl.php.net/mongodb\n[alcaeus/mongo-php-adapter]: https://github.com/alcaeus/mongo-php-adapter\n\nExample config:\n\n```php\n    'save.handler' =\u003e \\Xhgui\\Profiler\\Profiler::SAVER_MONGODB,\n    'save.handler.mongodb' =\u003e array(\n        'dsn' =\u003e 'mongodb://127.0.0.1:27017',\n        'database' =\u003e 'xhprof',\n        // Allows you to pass additional options like replicaSet to MongoClient.\n        // 'username', 'password' and 'db' (where the user is added)\n        'options' =\u003e array(),\n        // Allows you to pass driver options like ca_file to MongoClient\n        'driverOptions' =\u003e array(),\n    ),\n```\n\n### PDO Saver\n\nNOTE: Saving directly to PDO is discouraged, use Upload/File/Stack saver instead.\n\nPDO Saver should be able to save to any PDO driver connection.\n\nYou will need to install additionally `perftools/xhgui-collector` package:\n\n```\ncomposer require perftools/xhgui-collector\n```\n\nExample config:\n\n```php\n    'save.handler' =\u003e \\Xhgui\\Profiler\\Profiler::SAVER_PDO,\n    'save.handler.pdo' =\u003e array(\n        'dsn' =\u003e 'sqlite:/tmp/xhgui.sqlite3',\n        'user' =\u003e null,\n        'pass' =\u003e null,\n        'table' =\u003e 'results'\n    ),\n```\n\n## Custom Saver\nYou can create your own profile saver by implementing `SaverInterface` and calling `setSaver()`.\n\n```php\nuse Xhgui\\Profiler\\Profiler;\nuse Xhgui\\Profiler\\Saver\\SaverInterface;\n\nclass StdOutSaver implements SaverInterface\n{\n    public function isSupported()\n    {\n        return true;\n    }\n\n    public function save(array $data)\n    {\n        fwrite(STDOUT, json_encode($data));\n    }\n}\n\n//...\n/** @var Profiler $profiler */\n$profiler-\u003esetSaver(new StdOutSaver());\n```\n\n### Import jsonl files\n\nYou can use `./bin/import.php` script to submit files saved by [File Saver](#file-saver) to XHGui server.\n\n1. [Setup config file](#using-config-file)\n1. Configure to use [Upload Saver](#upload-saver)\n1. Execute the `./bin/import.php` script\n\nThe script can take multiple [jsonl] formatted files, or if none given read stdin stream.\n\n```sh\n$ ./bin/import.php tests/tmp/php-profiler-xhgui-test-1596093567.787220-c857.json\nImported 1 lines\n```\n\n[jsonl]: https://jsonlines.org/\n\n## Configure Profiling Rate\n\nYou may want to change how frequently you profile the application.  The\n`profiler.enable` configuration option allows you to provide a callback\nfunction that specifies the requests that are profiled.\n\nThe following example configures to profile 1 in 100 requests, excluding\nrequests with the `/blog` URL path:\n\n```php\n    'profiler.enable' =\u003e function() {\n        $url = $_SERVER['REQUEST_URI'];\n        if (strpos($url, '/blog') === 0) {\n            return false;\n        }\n\n        return mt_rand(1, 100) === 42;\n    },\n```\n\nIn contrast, the following example instructs to profile _every_\nrequest:\n\n```php\n    'profiler.enable' =\u003e function() {\n        return true;\n    },\n```\n\n## Profile using XHProf helper\n\nIf you want to start profiling using a browser based tool like [XHProf helper], You can use this method:\n\n```php\n    'profiler.enable' =\u003e function() {\n        return !empty($_COOKIE['_profiler']);\n        // or\n        return !empty($_COOKIE['XHProf_Profile']);\n    },\n```\n\n[XHProf helper]: https://chrome.google.com/webstore/detail/xhprof-helper/adnlhmmjijeflmbmlpmhilkicpnodphi?hl=en\n\n## Configure 'Simple' URLs Creation\n\nThis library generates 'simple' URLs for each profile collected. These URLs are\nused to generate the aggregate data used on the URL view. Since different\napplications have different requirements for how URLs map to logical blocks of\ncode, the `profile.simple_url` configuration option allows you to provide\nthe logic used to generate the simple URL.\n\nBy default, all numeric values in the query string are removed.\n\n```php\n    'profile.simple_url' =\u003e function($url) {\n        return preg_replace('/=\\d+/', '', $url);\n    },\n```\n\n## Configure ignored functions\n\nYou can use the `profiler.options` configuration value to set additional options\nfor the profiler extension. This is useful when you want to exclude specific\nfunctions from your profiler data:\n\n```php\n    'profiler.options' =\u003e array(\n        'ignored_functions' =\u003e array(\n            'call_user_func',\n            'call_user_func_array',\n        ),\n    ),\n);\n```\n\nIn addition, if you do not want to profile all PHP built-in functions,\nAdd `ProfilingFlags::NO_BUILTINS`, to 'profiler.flags'.\n\n## Installing profilers\n\nFor this library to capture profiling data, you would need any of the profiler extension.\nDepending on your environment (PHP version), you may need to install different extension.\n\nSupported profilers:\n - [Tideways XHProf v5.x](#tideways-xhprof-5): PHP \u003e= 7.0\n - [XHProf](#xhprof): PHP \u003e= 5.3, PHP \u003e= 7.0\n - [Tideways v4.x](#tideways-4x): PHP \u003e= 7.0\n - [UProfiler](#uprofiler): PHP \u003e= 5.3, \u003c PHP 7.0\n\n### Tideways XHProf (5.+)\n\n[Tideways XHProf v5.x][tideways_xhprof] requires PHP \u003e= 7.0.\n\nTo install `tideways_xhprof` extension, see their [installation documentation][tideways-xhprof-install].\n\n[tideways_xhprof]: https://github.com/tideways/php-xhprof-extension\n[tideways-xhprof-install]: https://github.com/tideways/php-xhprof-extension#installation\n\nAlternatively on `brew` (macOS) you can use packages from [kabel/pecl] tap:\n\n```\nbrew install kabel/pecl/php@7.4-tideways-xhprof\nbrew install kabel/pecl/php@8.0-tideways-xhprof\nbrew install kabel/pecl/php@8.1-tideways-xhprof\n```\n\nFor outdated php versions few recipes exist in [glensc/tap] tap:\n```\nbrew install glensc/tap/php@7.1-tideways-xhprof\n```\n\n[kabel/pecl]: https://github.com/kabel/homebrew-pecl\n[glensc/tap]: https://github.com/glensc/homebrew-tap\n\n### XHProf\n\n[XHProf] supports all PHP versions.\n\n- `xhprof` 0.9.x requires PHP \u003e= 5.3, \u003c PHP 7.0\n- `xhprof` 2.x requires PHP \u003e= 7.0\n\nfor PHP 5.x:\n```\npecl install xhprof-0.9.4\n```\n\nfor PHP \u003e=7.0:\n```\npecl install xhprof\n```\n\nAlternatively on `brew` (macOS) you can use packages from [kabel/pecl] tap:\n\n```\nbrew install kabel/pecl/php@7.4-xhprof\nbrew install kabel/pecl/php@8.0-xhprof\nbrew install kabel/pecl/php@8.1-xhprof\n```\n\n[XHProf]: https://pecl.php.net/package/xhprof\n\n### Tideways (4.x)\n\n[Tideways] 4.x extension requires with PHP \u003e= 7.0.\n\nTo install `tideways` extension, see their [installation documentation][Tideways].\n\n```\ncurl -sSfL https://github.com/tideways/php-xhprof-extension/archive/v4.1.6.tar.gz | tar zx\ncd php-xhprof-extension-4.1.6/\nphpize\n./configure\nmake\nmake install\necho extension=/usr/local/lib/php/pecl/20160303/tideways.so | tee /usr/local/etc/php/7.1/conf.d/ext-tideways.ini\n```\n\n[Tideways]: https://tideways.com/profiler/downloads\n\n### UProfiler\n\n[UProfiler] requires PHP \u003e= 5.3, \u003c PHP 7.0\n\nTo install `uprofiler` extension, see their [installation documentation][uprofiler-install].\n\n[UProfiler]: https://github.com/FriendsOfPHP/uprofiler\n[uprofiler-install]: https://github.com/FriendsOfPHP/uprofiler#installing-the-uprofiler-extension\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperftools%2Fphp-profiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperftools%2Fphp-profiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperftools%2Fphp-profiler/lists"}