PHPackages                             popphp/pop-debug - 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. popphp/pop-debug

ActiveLibrary[Debugging & Profiling](/categories/debugging)

popphp/pop-debug
================

Pop Debug Component for Pop PHP Framework

3.0.0(6mo ago)311.0k↑38.9%2BSD-3-ClausePHPPHP >=8.3.0CI passing

Since Aug 31Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/popphp/pop-debug)[ Packagist](https://packagist.org/packages/popphp/pop-debug)[ Docs](https://github.com/popphp/pop-debug)[ RSS](/packages/popphp-pop-debug/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (20)Used By (2)

pop-debug
=========

[](#pop-debug)

[![Build Status](https://github.com/popphp/pop-debug/workflows/phpunit/badge.svg)](https://github.com/popphp/pop-debug/actions)[![Coverage Status](https://camo.githubusercontent.com/1337d674316e0c8a9c82dd8f340487ee263c9e23c3668e0024e7747f2bb971c1/687474703a2f2f63632e706f707068702e6f72672f636f7665726167652e7068703f636f6d703d706f702d6465627567)](http://cc.popphp.org/pop-debug/)

[![Join the chat at https://discord.gg/TZjgT74U7E](https://camo.githubusercontent.com/acad7b0eeb78b78d08ffd2b85681ab243436388b5f86f8bcb956a69246e53739/68747470733a2f2f6d656469612e706f707068702e6f72672f696d672f646973636f72642e737667)](https://discord.gg/TZjgT74U7E)

- [Overview](#overview)
- [Install](#install)
- [Quickstart](#quickstart)
- [Handlers](#handlers)
    - [Exception](#exception)
    - [Memory](#memory)
    - [Message](#message)
    - [PHP](#php)
    - [Query](#query)
    - [Request](#request)
    - [Time](#time)
- [Storage](#storage)
    - [File](#file)
    - [Database](#database)
- [Logging](#logging)

Overview
--------

[](#overview)

`pop-debug` is a debugging component that can be used to hook into an application to track certain aspects of the application's lifecycle. It can help provide insight to an application's performance or any issues that may arise within an application.

`pop-debug` is a component of the [Pop PHP Framework](https://www.popphp.org/).

Install
-------

[](#install)

Install `pop-debug` using Composer.

```
composer require popphp/pop-debug

```

Or, require it in your composer.json file

```
"require": {
    "popphp/pop-debug" : "^3.0.0"
}

```

[Top](#pop-debug)

Quickstart
----------

[](#quickstart)

The basic concept of the debugger is that it works with a handler object or multiple handler objects and one storage object. The handlers are wired to listen to and track various aspects of the application and push their results to the storage object to be retrieved at a later time.

In this simple example, we can set up a generic message handler to store its triggered messages in a file.

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\MessageHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new MessageHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));

$debugger['message']->addMessage('Hey! Something happened!');

$debugger->save();
```

The above code will save the following output to the `log` folder in a CSV file:

```
key,handler,start,end,elapsed,type,message,context
b8c00658be2aee93703deea23e58b99f,message,1762216971.7394,,,message,Hey! Something happened!,

```

[Top](#pop-debug)

Handlers
--------

[](#handlers)

There are a total of 6 available handlers. More handlers can be added, provided they implement the `Pop\Debug\Handler\HandlerInterface` interface.

### Exception

[](#exception)

The exception handler captures and tracks any exceptions thrown by an application.

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\ExceptionHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new ExceptionHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));

try {
    throw new \Exception('Error: This is a test exception');
} catch (\Exception $e) {
    $debugger['exception']->addException($e);
    $debugger->save();
}
```

[Top](#pop-debug)

### Memory

[](#memory)

The memory handler captures memory usages and peak memory usage. At any point in the application, you can call the `updateMemoryUsage()` and `updatePeakMemoryUsage()` methods to take a snapshot of memory usage in the app at that time.

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\MemoryHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new MemoryHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));

$debugger['memory']->updateMemoryUsage();
$debugger['memory']->updatePeakMemoryUsage();
sleep(2);
$debugger['memory']->updateMemoryUsage();
$debugger['memory']->updatePeakMemoryUsage();

$debugger->save();
```

[Top](#pop-debug)

Message
-------

[](#message)

The message handler provides simple and generic messaging to record debug events from within the application:

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\MessageHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new MessageHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));

$debugger['message']->addMessage('Hey! Something happened!');

$debugger->save();
```

[Top](#pop-debug)

PHP
---

[](#php)

The PHP handler provides a way to take a snapshot of common PHP info and INI values:

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\PhpHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new PhpHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));

$debugger->save();
```

[Top](#pop-debug)

### Query

[](#query)

The query handler is a special handler that ties into the `pop-db` component and the profiler available with that component. It allows you to capture any database queries and any information associated with them.

You can set up the query handler like this:

```
use Pop\Debug\Debugger;
use Pop\Debug\Storage\File;
use Pop\Db\Db;
use Pop\Db\Record;

$db = Db::mysqlConnect([
    'database' => 'DATABASE',
    'username' => 'DB_USER',
    'password' => 'DB_PASS'
]);

class Users extends Record {}

Record::setDb($db);

// Register the query handler with the DB adapter
$queryHandler = $db->listen('Pop\Debug\Handler\QueryHandler');

$debugger = new Debugger();
$debugger->addHandler($queryHandler);
$debugger->setStorage(new File('log'));

// Interact with the database
$user = new Users([
    'username' => 'admin',
    'password' => 'password'
]);

$user->save();

$debugger->save();
```

[Top](#pop-debug)

### Request

[](#request)

The request handler works with a `Pop\Http\Server\Request` object from the `pop-http` component and tracks all of the inbound request data. The following example would be a block of code that would run in a script that receives an inbound HTTP request:

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\RequestHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new RequestHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));
$debugger->save();
```

[Top](#pop-debug)

### Time

[](#time)

The time handler provides a simple way to track how long a application request takes, which is useful for performance metrics.

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\TimeHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new TimeHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));

sleep(2);

$debugger->save();
```

[Top](#pop-debug)

Storage
-------

[](#storage)

There are two different storage options are available to store the output of the debugger:

- CSV (or TSV) File
- Database Table

### File

[](#file)

Store the debugger output into a file in a folder location:

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\TimeHandler;
use Pop\Debug\Storage\File;

$debugger = new Debugger();
$debugger->addHandler(new TimeHandler());
$debugger->setStorage(new File(__DIR__ . '/log'));
```

[Top](#pop-debug)

### Database

[](#database)

Store the debugger output into a table in a database. The default table name is `pop_debug` but that can be changed with the database storage object.

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\TimeHandler;
use Pop\Debug\Storage\Database;
use Pop\Db\Db;

$db = Db::mysqlConnect([
    'database' => 'DATABASE',
    'username' => 'DB_USER',
    'password' => 'DB_PASS'
]);

$debugger = new Debugger();
$debugger->addHandler(new TimeHandler());
$debugger->setStorage(new Database($db, 'text', 'my_debug_table'));
```

[Top](#pop-debug)

Logging
-------

[](#logging)

The debug component can also work with the `pop-log` component to deliver syslog-compatible logging messages to a logging resource using the standard BSD syslog protocol [RFC-3164](http://tools.ietf.org/html/rfc3164). Logging can be used in additional to the storage adapters, or by itself, sending the debug data and information to the logging resource only and without storing anything to a storage adapter.

To work with a logger, a logger object must be passed to the debugger, along with logging parameters, which is an array of options. The minimum parameter required is a `level` value. The `context` option can also be used to log the body of the debug messaging results:

```
use Pop\Debug\Debugger;
use Pop\Debug\Handler\ExceptionHandler;
use Pop\Debug\Storage\File;
use Pop\Log;

$debugger = new Debugger();
$debugger->addHandler(new ExceptionHandler(true));
$debugger->addLogger(
    new Log\Logger(new Log\Writer\File(__DIR__ . '/log/debug.log')),
    [
        'level'   => Log\Logger::ERROR,
        'context' => 'json'
    ]
);

try {
    throw new Pop\Debug\Exception('This is a test debug exception');
} catch (\Exception $e) {
    $debugger['exception']->addException($e);
    $debugger->save();
}
```

Other logging parameters options include:

***Memory***

The `usage_limit` and `peak_limit` are memory-specific limits to monitor is an operation goes above the specified limits.

```
$loggingParams = [
    'level'       => Log\Logger::WARNING,
    'usage_limit' => '500000',  // Limit in bytes.
                                // If the usage goes above the limit,
                                // the log message is sent
    'peak_limit'  => '1000000', // Limit in bytes.
                                // If the peak usage goes above the limit,
                                // the log message is sent
];
```

***Query, Request & Time***

The `limit` parameter is supported for the query, request and time handlers. It is a time limit. If any of those operations take longer than the time limit, a log message is sent.

```
$loggingParams = [
    'level' => Log\Logger::WARNING,
    'limit' => 1, // Time limit in seconds.
                  // If the operation takes longer than the time limit,
                  // the log message is sent
];
```

##### Query Example:

[](#query-example)

```
use Pop\Debug\Debugger;
use Pop\Db\Db;
use Pop\Db\Record;
use Pop\Db\Adapter\Profiler\Profiler;
use Pop\Log;

$db = Db::mysqlConnect([
    'database' => 'DATABASE',
    'username' => 'DB_USER',
    'password' => 'DB_PASS'
]);

class Users extends Record {}

Record::setDb($db);

// Register the debugger and query handler with the DB adapter
$debugger = new Debugger();
$db->listen('Pop\Debug\Handler\QueryHandler', null, new Profiler($debugger));

// Add logger to the debugger
$debugger->addLogger(
    new Log\Logger(new Log\Writer\File(__DIR__ . '/log/debug.log')),
    [
        'level' => Log\Logger::INFO,
        'limit' => 1
    ]
);

// Save a user to the database - debugging and logging will automatically happen
$user = new Users([
    'username' => 'testuser',
    'password' => 'password',
    'email'    => 'testuser@test.com'
]);

$user->save();
```

[Top](#pop-debug)

###  Health Score

53

—

FairBetter than 97% of packages

Maintenance67

Regular maintenance activity

Popularity28

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity87

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~213 days

Recently: every ~89 days

Total

15

Last Release

196d ago

Major Versions

1.3.2 → 2.0.02023-12-18

2.2.2 → 3.0.02025-11-04

PHP version history (7 changes)1.0.0PHP >=5.6.0

1.1.0PHP >=7.1.0

1.3.0PHP >=7.3.0

1.3.1PHP >=7.4.0

2.0.0PHP >=8.1.0

2.2.1PHP >=8.2.0

3.0.0PHP >=8.3.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/c19dee900e9e20039c723cc403f76b5c22ac2dddb3f86773ae64fb082d4949e2?d=identicon)[nicksagona](/maintainers/nicksagona)

---

Top Contributors

[![nicksagona](https://avatars.githubusercontent.com/u/898670?v=4)](https://github.com/nicksagona "nicksagona (104 commits)")

---

Tags

phpdebuggerpoppop phpphp debugger

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/popphp-pop-debug/health.svg)

```
[![Health](https://phpackages.com/badges/popphp-pop-debug/health.svg)](https://phpackages.com/packages/popphp-pop-debug)
```

###  Alternatives

[popphp/popphp-framework

The Pop PHP Framework - Full Installation

686.5k1](/packages/popphp-popphp-framework)[popphp/popphp

Pop PHP Framework, a lightweight, robust PHP framework

5713.5k9](/packages/popphp-popphp)[popphp/pop-db

Pop Db Component for Pop PHP Framework

1814.6k11](/packages/popphp-pop-db)[popphp/pop-pdf

PHP PDF library for generating and importing PDF documents. A component of the Pop PHP Framework

207.8k1](/packages/popphp-pop-pdf)[popphp/pop-http

Pop Http Component for Pop PHP Framework

1018.5k13](/packages/popphp-pop-http)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)