PHPackages                             rdebug/midi - 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. [Utility & Helpers](/categories/utility)
4. /
5. rdebug/midi

ActiveLibrary[Utility & Helpers](/categories/utility)

rdebug/midi
===========

A PHP Replay Client For Rdebug

0.0.6(7y ago)1.2k40171[10 issues](https://github.com/didi/rdebug/issues)[1 PRs](https://github.com/didi/rdebug/pulls)Apache-2.0PHPCI failing

Since Feb 20Pushed 6y ago62 watchersCompare

[ Source](https://github.com/didi/rdebug)[ Packagist](https://packagist.org/packages/rdebug/midi)[ RSS](/packages/rdebug-midi/feed)WikiDiscussions master Synced 2mo ago

READMEChangelog (5)Dependencies (15)Versions (6)Used By (0)

RDebug - Real Debugger
======================

[](#rdebug---real-debugger)

[![Gitter](https://camo.githubusercontent.com/801434278a490334d4afcc2c6273ca8997f8dc09ce40a65b5f55d31f44910472/68747470733a2f2f6261646765732e6769747465722e696d2f646964692f7264656275672e737667)](https://gitter.im/didi/rdebug?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)[![License](https://camo.githubusercontent.com/a549a7a30bacba7bfceebdc207a8e86c3f2c02995a2527640dca30048fd2b64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667)](https://github.com/didi/rdebug/blob/master/LICENSE)

Translation
-----------

[](#translation)

- [中文](./README_zh_CN.md)

1. Introduction
---------------

[](#1-introduction)

Rdebug is an open source *tool chain* that focusing on efficiency of daily developing, testing and debugging for developers. The code will be robust.

### 1.1 Background

[](#11-background)

As micro-service architecture makes services *isomerous*, *easy-to-deploy* and *superbly extensible*, large systems are divided into several micro services.

But, micro-service architecture is not a silver bullet. It has several drawbacks. One service is divided into several small services, test environment becomes hard to maintain. Unit test needs to mock downstream services. This will downgrade the efficiency of developing, and increase production bugs.

We do believe this industry needs an evolution.

### 1.2 Principle

[](#12-principle)

Efficiency improvement, release cycle reduction, code quality improvement, production bug reduction

### 1.3 When to use

[](#13-when-to-use)

Suitable for old api refactoring that traffic have already been recorded.

Not suitable for new api or api that has no traffic recorded.

Support for new api is under investigation.

2. Quick Started
----------------

[](#2-quick-started)

### Traffic Recording

[](#traffic-recording)

```
# Modify php-fpm config, set `clear_env = no`

# Compile koala-libc.so & koala-recorder.so

# Start php-fpm with koala-libc.so & koala-recorder.so
# Set environment first
$ export KOALA_SO=/path/to/koala-recorder.so
$ export KOALA_RECORD_TO_DIR=/path/to/your-save-recorded-session-dir
$ export LC_CTYPE="C"

# Recording
# macOS
$ DYLD_INSERT_LIBRARIES="/path/to/koala-libc.so" DYLD_FORCE_FLAT_NAMESPACE="y" /path/to/sbin/php-fpm

# or, Linux
$ LD_PRELOAD="/path/to/koala-libc.so" /path/to/sbin/php-fpm
```

### Traffic Replaying

[](#traffic-replaying)

Three ways to replay: replay from source, replay by midi.phar, replay by composer vendor/bin.

```
# Source
$ git clone https://github.com/didi/rdebug.git
$ cd rdebug/php/midi
$ sh install.sh
$ cd /path/to/your/project
$ /path/to/rdebug/php/midi/bin/midi run -f RECORD-SESSION-FILE

# Or, Phar
$ wget -O midi.phar -q https://github.com/didi/rdebug/raw/master/output/bin/midi.phar
$ midi.phar run -f RECORD-SESSION-FILE

# Or, Composer global
$ composer global require rdebug/midi
$ cd /path/to/your/project
$ ~/.composer/vendor/bin/midi run -f RECORD-SESSION-FILE

# Or, Composer
$ cd /path/to/your/project
$ composer require rdebug/midi --dev
$ ./vendor/bin/midi run -f RECORD-SESSION-FILE
```

### PHP Example

[](#php-example)

- [Try Record & Replay With Docker](./doc/Docker.md)
- [PHP Record & Replay Example](./example/php/README.md)
- [Replay Local File](./doc/midi/Replay-file.md)

3. Technical Details
--------------------

[](#3-technical-details)

We are using real production traffic to test on non-production environment. So, the core features of `Rdebug` are traffic recording and traffic replaying.

- **Traffic Recording**

    Recording production traffic, including RPC between micro-services. The most difficult part is to trace requests that will span multiple services.
- **Traffic Replaying**

    Replaying recorded production traffic against non-production environment, mock downstream traffic based on traffic matching. The most difficult part is interception and traffic matching.

[![koala-midi](./doc/images/koala-midi_en-US.png)](./doc/images/koala-midi_en-US.png)

### 3.1 Koala & Koala-libc

[](#31-koala--koala-libc)

Koala and Koala-libc is the engine of Rdebug.

Because the problems such as *RPC tracing*, *libc interception* that a traffic replaying system may concern is what a traffic recording system concerns. The traffic recording and replaying system shares the same engine.

#### Koala

[](#koala)

Koala is written in Go, libc contains some c++ code for interception part which will complied to *koala-recorder.so* and *koala-replayer.so*

Koala support replaying and recording separately as well as simultaneously.

For more details: [koala](./koala/README.md) 。

#### Koala-libc

[](#koala-libc)

koala-libc is written in C, and compiled to *koala-libc.so*

Go does not support `fork`. To avoid problems bring by PHP-FPM fork worker, you need to inject *koala-libc.so* into parent process of PHP. So that *koala-libc.so* will forward requests libc intercepted to \*koala-recorder.so when `accept` in child process

For more details: [koala-libc](./koala-libc/README.md) 。

### 3.2 Midi

[](#32-midi)

Midi is a traffic replay client for PHP using command line written in PHP.

*koala-replayer.so* is embedded in Midi, and it can replay production traffic against new code, analyze test result, generate diff report, trace report, coverage report.

Midi support Xdebug.

For more details: [midi](./php/midi/README.md) 。

4. Compile
----------

[](#4-compile)

### 4.1 Requirement

[](#41-requirement)

#### Koala & Koala-libc

[](#koala--koala-libc)

- GCC >= 4.8
- Go >= 1.8
- Glide

#### Midi

[](#midi)

- macOS/Linux
- PHP >= 7.0
- Xdebug (Optional)
- Composer (Optional)

### 4.2 Compile Koala-libc

[](#42-compile-koala-libc)

```
$ cd koala-libc
$ sh build.sh
```

will generate `../output/libs/koala-libc.so`。

### 4.3 Compile Koala

[](#43-compile-koala)

```
$ cd koala

# install depends
$ sh build.sh vendor

# koala-recorder.so
$ sh build.sh recorder

# koala-replayer.so
$ sh build.sh
```

will generate `../output/libs/koala-recorder.so` and `../output/libs/koala-replayer.so`。

### 4.4 Compile midi.phar

[](#44-compile-midiphar)

Before compile midi.pahr, recommend compile `koala-replayer.so` at your system and store in `php/midi/res/replayer` directory.

`php/midi/res/replayer/koala-replayer.so` in repository is for macOS.

```
$ cd php/midi
$ sh build.sh
```

will generate `../output/bin/midi.phar`

Default phar will not include `DiPlugin` plugin, which is an internal plugin of didi.

If your want to compile with `DiPlugin` plugin:

```
$ cd php/midi
$ sh build.sh midi-diplugin

```

5. Usage
--------

[](#5-usage)

### 5.1 Traffic Recording

[](#51-traffic-recording)

Record traffic in file or Elastic.

Set environment variable `KOALA_RECORD_TO_DIR` to save record to specified dir

Inject so. Use `DYLD_INSERT_LIBRARIES` in macOs or `LD_PRELOAD` in Linux

For more details: [Recorder](./doc/recorder/recorder.md)。

#### 5.1.1 macOS Recording

[](#511-macos-recording)

```
$ DYLD_INSERT_LIBRARIES="/path/to/koala-libc.so:/usr/lib/libcurl.dylib" DYLD_FORCE_FLAT_NAMESPACE="y" LC_CTYPE="C" KOALA_SO=/path/to/koala-recorder.so KOALA_RECORD_TO_DIR=/tmp /usr/local/sbin/php-fpm
```

#### 5.1.2 Linux Recording

[](#512-linux-recording)

```
LD_PRELOAD="/path/to/koala-libc.so /usr/lib64/libcurl.so.4" LC_CTYPE="C" KOALA_SO="/path/to/koala-recorder.so" KOALA_RECORD_TO_DIR=/tmp /usr/local/sbin/php-fpm
```

Koala support writing to Elastic by replacing `KOALA_RECORD_TO_DIR` with `KOALA_RECORD_TO_ES` which value is elastic write url

### 5.2 Traffic Replay

[](#52-traffic-replay)

Traffic replaying is to replay recorded traffic in production against non-production environment. You need only to deploy your code w/o deploying downstream services.

Below is a simple example of replaying with '-f', which specified the file to replay.

#### 5.2.1 Replay

[](#521-replay)

```
# Source
$ /path/to/rdebug/php/midi/bin/midi run -f RECORD-SESSION-FILE

# Or, phar
$ midi.phar run -f RECORD-SESSION-FILE

# Or, composer vendor bin
$ ./vendor/bin/midi -f RECORD-SESSION-FILE
```

For more details: [Replay](#traffic-replaying)

Use -v, -vv or -vvv for more verbose log.

#### 5.2.2 Report

[](#522-report)

Use `-R`，`-T`，`-C` to generate：Replay report, Trace report, Coverage report

[![report](./example/php/report.png)](./example/php/report.png)

[![report-upstream](./example/php/report-upstream.png)](./example/php/report-upstream.png)

[![report-coverage](./example/php/report-coverage.png)](./example/php/report-coverage.png)

For more details: [Midi](./php/midi/README.md)。

6. More
-------

[](#6-more)

### 6.1 Translation

[](#61-translation)

- [中文](./README_zh_CN.md)

### 6.2 Documentation

[](#62-documentation)

- [Documentation](./doc/DocList.md)
- [Wiki](https://github.com/didi/rdebug/wiki)

### 6.3 Contribute

[](#63-contribute)

Any contributions are welcome. [More Details](./CONTRIBUTING.md)

### 6.4 Contract

[](#64-contract)

- Add Weixin

[![](https://raw.githubusercontent.com/didi/rdebug/master/doc/images/weixin_add_friend.jpg)](https://raw.githubusercontent.com/didi/rdebug/master/doc/images/weixin_add_friend.jpg)

- QQ Group

[![QQ](doc/images/QQChat.png)](doc/images/QQChat.png)

### 6.5 License

[](#65-license)

Rdebug is licensed under the Apache 2.0 License. [LICENSE](./LICENSE)

### 6.6 Contributors

[](#66-contributors)

Special thanks to [TaoWen](https://github.com/taowen) Developer of Koala & Koala-libc.

Thanks to all the people who [contribute](https://github.com/didi/rdebug/graphs/contributors). [![](https://camo.githubusercontent.com/087b043da4e29f8e4bd6de276502203fa4900c59f164a9e3549efc2686b788f2/68747470733a2f2f6f70656e636f6c6c6563746976652e636f6d2f7264656275672f636f6e7472696275746f72732e7376673f77696474683d38393026627574746f6e3d74727565)](https://github.com/didi/rdebug/graphs/contributors)

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity34

Limited adoption so far

Community27

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 78.6% 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 ~14 days

Total

5

Last Release

2584d ago

### Community

Maintainers

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

---

Top Contributors

[![MingliangT](https://avatars.githubusercontent.com/u/1646738?v=4)](https://github.com/MingliangT "MingliangT (33 commits)")[![727155455](https://avatars.githubusercontent.com/u/13045890?v=4)](https://github.com/727155455 "727155455 (6 commits)")[![Azurx](https://avatars.githubusercontent.com/u/18546555?v=4)](https://github.com/Azurx "Azurx (1 commits)")[![bikong0411](https://avatars.githubusercontent.com/u/1323682?v=4)](https://github.com/bikong0411 "bikong0411 (1 commits)")[![taowen](https://avatars.githubusercontent.com/u/40541?v=4)](https://github.com/taowen "taowen (1 commits)")

---

Tags

phpreplayKoalardebugReal Debugger

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/rdebug-midi/health.svg)

```
[![Health](https://phpackages.com/badges/rdebug-midi/health.svg)](https://phpackages.com/packages/rdebug-midi)
```

###  Alternatives

[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19462.3M1.3k](/packages/drupal-core)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6939.5M343](/packages/drupal-core-recommended)

PHPackages © 2026

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