PHPackages                             arnaud-lb/memprof - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Debugging & Profiling](/categories/debugging)
4. /
5. arnaud-lb/memprof

ActivePhp-ext[Debugging & Profiling](/categories/debugging)

arnaud-lb/memprof
=================

A memory profiler for PHP

3.1.0(1y ago)932604↓30.8%52[10 issues](https://github.com/arnaud-lb/php-memory-profiler/issues)[1 PRs](https://github.com/arnaud-lb/php-memory-profiler/pulls)MITCPHP >= 8.1.0

Since Feb 24Pushed 1y ago15 watchersCompare

[ Source](https://github.com/arnaud-lb/php-memory-profiler)[ Packagist](https://packagist.org/packages/arnaud-lb/memprof)[ RSS](/packages/arnaud-lb-memprof/feed)WikiDiscussions v3 Synced 1mo ago

READMEChangelog (2)DependenciesVersions (3)Used By (0)

 [![memprof logo](https://camo.githubusercontent.com/94ccea5fd25e891a2ee45af980afddfa55546e95f66c4c1683743d02305bb644/68747470733a2f2f692e696d6775722e636f6d2f4e484c657561362e706e67)](https://camo.githubusercontent.com/94ccea5fd25e891a2ee45af980afddfa55546e95f66c4c1683743d02305bb644/68747470733a2f2f692e696d6775722e636f6d2f4e484c657561362e706e67)

memprof
=======

[](#memprof)

[![Supported PHP versions: 7.1 ... 8.x](https://camo.githubusercontent.com/11e333983d8c11bee9e7c4e196772934e435e294ab364e9dc9652699d1099528/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d372e312532302e2e2e253230382e782d626c75652e737667)](https://camo.githubusercontent.com/11e333983d8c11bee9e7c4e196772934e435e294ab364e9dc9652699d1099528/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d372e312532302e2e2e253230382e782d626c75652e737667)

php-memprof is a fast and accurate memory profiling extension for PHP that can be used to find the cause of memory leaks.

Features
--------

[](#features)

The extension tracks the allocation and release of memory blocks to report the amount of memory leaked by every function, method, or file in a program.

- Reports non-freed memory at arbitrary points in the program
- Dumps profile in callgrind, pprof, or raw array formats
- Can track memory allocated by PHP itself as well as native malloc

Install
-------

[](#install)

### Dependencies

[](#dependencies)

php-memprof depends on libjudy and sys/queue.h.

On Debian-based distributions the dependencies can be installed with:

```
# Debian or Ubuntu:
apt install libjudy-dev

```

On Alpine:

```
# Alpine
apk add judy-dev bsd-compat-headers

```

On MacOS:

```
# install libjudy dependency:
brew install traildb/judy/judy

```

### Installing with [PIE](https://github.com/php/pie)

[](#installing-with-pie)

Make sure to install [dependencies](#dependencies), and then:

```
pie install arnaud-lb/memprof

```

> **Note** If libjudy is installed in a non-standard path (not /usr or /usr/local), you need to specify it via the `--with-judy-dir` option.
>
> Example on MacOS:
>
> ```
> pecl install memprof --with-judy-dir=$(brew --prefix traildb/judy/judy)
>
> ```

### Installing with PECL

[](#installing-with-pecl)

Make sure to install [dependencies](#dependencies), and then:

```
pecl install memprof

```

> **Note** If libjudy is installed in a non-standard path (not /usr or /usr/local), you need to specify it via the `JUDY_DEV` environment variable.
>
> Example on MacOS:
>
> ```
> JUDY_DIR=$(brew --prefix traildb/judy/judy) pecl install memprof
>
> ```

### Installing manually

[](#installing-manually)

Make sure to install [dependencies](#dependencies), and then:

Download the source and run the following commands in the source directory:

```
phpize
./configure
make
make install

```

> **Note** If libjudy is installed in a non-standard path (not /usr or /usr/local), you can specify it like this:

```
./configure --with-judy-dir=/opt/homebrew/Cellar/judy/1.0.5

```

### Installing on Arch Linux

[](#installing-on-arch-linux)

Arch Linux users may prefer to install the unofficial php-memprof [package](https://aur.archlinux.org/packages/php-memprof/)with `makepkg` or their preferred AUR [helper](https://wiki.archlinux.org/title/AUR_helpers). If using `yay`, for example:

```
yay -S php-memprof

```

> ℹ️ Please report any issues with this package on its AUR [page](https://aur.archlinux.org/packages/php-memprof/).

Loading the extension
---------------------

[](#loading-the-extension)

The extension can be loaded on the command line, just for one script:

```
php -dextension=memprof.so script.php

```

Or permanently, in php.ini:

```
extension=memprof.so

```

The extension has no overhead when not profiling, so it can be loaded by default on dev environments.

Usage example
-------------

[](#usage-example)

The simplest way to use `memprof` is to let it save the memory profile when the program's memory limit is exceeded.

### Step 1: Enable profiling in `dump_on_limit` mode

[](#step-1-enable-profiling-in-dump_on_limit-mode)

Profiling in `dump_on_limit` mode is enabled at request startup when one of these is true:

- The environment variable `MEMPROF_PROFILE` is equal to `dump_on_limit`
- `$_GET["MEMPROF_PROFILE"]` is equal to `dump_on_limit`
- `$_POST["MEMPROF_PROFILE"]` is equal to `dump_on_limit`

For command line scripts, we can set the environment variable:

```
MEMPROF_PROFILE=dump_on_limit php test.php

```

For web scripts, we can set the `$_GET` variable:

```
curl http://127.0.0.1/test.php?MEMPROF_PROFILE=dump_on_limit

```

Or the `$_POST` variable:

```
curl -d MEMPROF_PROFILE=dump_on_limit http://127.0.0.1/test.php

```

> **Note** The `memprof_enabled_flags()` function can be called to check whether profiling is currently enabled in `dump_on_limit` mode.

### Step 2: Dumping the profile

[](#step-2-dumping-the-profile)

In this mode, `memprof` will automatically save the profile if the program exceeds the memory limit (when PHP triggers an error like `Fatal error: Allowed memory size of 15728640 bytes exhausted (tried to allocate 1024 bytes)` error).

By default, the profile is saved in a file named `memprof.callgrind.*` in `/tmp`or `C:\Windows\Temp`.

### Step 3: Visualizing the profile

[](#step-3-visualizing-the-profile)

The recommended way to visualize the result is to use Kcachegrind (on Linux) or Qcachegrind (on MacOS, Windows). Google Perftools are also supported. See the documentation of `memprof_dump_callgrind()` and variants.

#### Install Kcachegrind on Linux

[](#install-kcachegrind-on-linux)

Most distributions have a `kcachegrind` package ready to be installed.

For example, Ubuntu or Debian:

```
sudo apt install kcachegrind

```

Other distributions most likely have a package ready to be installed as well.

#### Install Qcachegrind on MacOS

[](#install-qcachegrind-on-macos)

Use Homebrew:

#### Install Qcachegrind on Windows

[](#install-qcachegrind-on-windows)

Download it from

Advanced usage
--------------

[](#advanced-usage)

### Profile trigger

[](#profile-trigger)

Profiling is enabled at request startup when one of these is true:

- The environment variable `MEMPROF_PROFILE` is non-empty
- `$_GET["MEMPROF_PROFILE"]` is non-empty
- `$_POST["MEMPROF_PROFILE"]` is non-empty

### Profile flags

[](#profile-flags)

The `MEMPROF_PROFILE` variable accepts a comma-separated list of flags.

Examples of valid `MEMPROF_PROFILE` values:

- `1`: non-empty: profiling is enabled
- `dump_on_limit`: profiling is enabled, will dump on memory limit
- `native`: profiling is enabled, will profile native allocations
- `dump_on_limit,native`: profiling is enabled, will profile native allocations, will dump on memory limit

List of valid flags:

- `dump_on_limit`: Will dump the profile in callgrind format in `/tmp` or `C:\Windows\Temp`. The output directory can be changed with the `memprof.output_dir` ini setting.
- `native`: Will profile native `malloc()` allocations, not only PHP's (This is not thread safe, see bellow).

### Profiling native allocations

[](#profiling-native-allocations)

Memprof doesn't track native allocations by default, but this can be enabled by setting `MEMPROF_PROFILE` to `native`.

Native allocations are the allocations made outside of PHP's own memory allocator. Typically, external libraries such as libxml2 (used in the DOM extension) make native allocations. PHP can also make native allocations for persistent resources.

Enabling native allocation tracking will profile these allocations in addition to PHP's own allocations.

Note that when native tracking is enabled, the program will crash if a native library uses threads, because the underlying hooks are not thread safe.

### Output format

[](#output-format)

The output file format is defined with the `memprof.output_format` ini setting. The options are:

- `callgrind` (default)
- `pprof`

Functions documentation
-----------------------

[](#functions-documentation)

### memprof\_enabled()

[](#memprof_enabled)

Returns whether memory profiling is currently enabled (see above).

### memprof\_enabled\_flags()

[](#memprof_enabled_flags)

Returns whether memory profiling and which profiling features are enabled (see above).

### memprof\_dump\_callgrind(resource $stream)

[](#memprof_dump_callgrindresource-stream)

Dumps the current profile in callgrind format. The result can be visualized with tools such as [KCacheGrind](#install-kcachegrind-on-linux) or [QCacheGrind](#install-qcachegrind-on-macos).

```