PHPackages                             kaz29/phork - 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. [Testing & Quality](/categories/testing)
4. /
5. kaz29/phork

ActiveLibrary[Testing & Quality](/categories/testing)

kaz29/phork
===========

Runtime-based parallel test distribution tool for PHPUnit

0.0.1(3mo ago)00MITPHPPHP ^8.1CI passing

Since Mar 22Pushed 2mo agoCompare

[ Source](https://github.com/kaz29/phork)[ Packagist](https://packagist.org/packages/kaz29/phork)[ RSS](/packages/kaz29-phork/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (1)Dependencies (4)Versions (3)Used By (0)

phork
=====

[](#phork)

[![Tests](https://github.com/kaz29/phork/actions/workflows/tests.yml/badge.svg)](https://github.com/kaz29/phork/actions/workflows/tests.yml)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](LICENSE)

[日本語版 README はこちら](README.ja.md)

**phork** is a runtime-based parallel test distribution tool for PHPUnit. It intelligently distributes your test files across multiple workers using previous execution time data, minimising total CI time through load-balanced parallel runs.

---

Features
--------

[](#features)

- **Runtime-aware distribution** – parses JUnit XML logs to balance test load by actual execution time
- **Graceful fallback** – uses round-robin distribution when no prior runtime data is available
- **Merged JUnit output** – combines per-worker JUnit XML reports into a single file
- **Auto CPU detection** – automatically picks the number of workers based on available CPU cores
- **PSR-4 aware** – reads simple PSR-4 mappings in `composer.json` (one directory per namespace) to map file paths to PHP class names

---

Requirements
------------

[](#requirements)

- PHP 8.1 or later
- [Composer](https://getcomposer.org/)
- [Paratest](https://github.com/paratestphp/paratest) 7.0+ (installed automatically as a dependency)

---

Installation
------------

[](#installation)

```
composer require --dev kaz29/phork
```

---

Usage
-----

[](#usage)

### Basic parallel run

[](#basic-parallel-run)

```
# Run tests in parallel across all available CPU cores
./vendor/bin/phork --test-dir=tests/
```

### Runtime-balanced run

[](#runtime-balanced-run)

First, generate a JUnit baseline with a regular PHPUnit run:

```
vendor/bin/phpunit --log-junit junit.xml
```

Then use that baseline to balance the next run:

```
./vendor/bin/phork --workers=4 --log=junit.xml --test-dir=tests/ --output=results.xml
```

---

CLI Options
-----------

[](#cli-options)

OptionDefaultDescription`--workers=N`auto (CPU cores)Number of parallel worker processes`--log=PATH`*(none)*Path to a previous JUnit XML file used for runtime-based distribution`--test-dir=PATH``tests/`Directory to scan for `*Test.php` files`--output=PATH`same as `--log`Path to write the merged JUnit XML result> **Note:** If you specify `--log` but omit `--output`, the merged result will overwrite your baseline JUnit file. It is recommended to always set `--output` explicitly.

---

How It Works
------------

[](#how-it-works)

1. **Scan** – recursively discovers all `*Test.php` files under `--test-dir`
2. **Parse** – reads `--log` (if provided) to build a class → execution-time map
3. **Split** – distributes test files into `--workers` buckets using a greedy load-balancing algorithm (falls back to round-robin with no prior data)
4. **Run** – spawns one `paratest` process per bucket in parallel
5. **Merge** – combines JUnit XML results from all workers into `--output`

---

Docker
------

[](#docker)

The repository ships Dockerfiles for PHP 8.3 and 8.4 and a `compose.yml` for local development:

```
# Start services (PHP 8.4 + PostgreSQL)
docker compose up -d

# Run tests inside the container
docker compose exec phork-app vendor/bin/phpunit
```

---

Development
-----------

[](#development)

```
# Install dependencies
composer install

# Run unit tests
vendor/bin/phpunit --testsuite Unit

# Run integration tests
vendor/bin/phpunit --testsuite Integration
```

---

Database Isolation
------------------

[](#database-isolation)

When running tests in parallel, each worker needs its own database. Use the `TEST_TOKEN` environment variable provided by paratest in your `bootstrap.php`:

```
// tests/bootstrap.php
$token = getenv('TEST_TOKEN') ?: '1';
putenv("DB_DATABASE=testdb_{$token}");
```

---

License
-------

[](#license)

This project is licensed under the [MIT License](LICENSE).

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance84

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 83.3% 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

Unknown

Total

1

Last Release

93d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/63869?v=4)[Kaz Watanabe](/maintainers/kaz29)[@kaz29](https://github.com/kaz29)

---

Top Contributors

[![kaz29](https://avatars.githubusercontent.com/u/63869?v=4)](https://github.com/kaz29 "kaz29 (10 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kaz29-phork/health.svg)

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

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[brianium/paratest

Parallel testing for PHP

2.5k129.9M910](/packages/brianium-paratest)[phpro/grumphp

A composer plugin that enables source code quality checks.

4.3k16.3M975](/packages/phpro-grumphp)[magento/magento2-functional-testing-framework

Magento2 Functional Testing Framework

15311.8M36](/packages/magento-magento2-functional-testing-framework)[testo/testo

A lightweight PHP testing framework.

1923.4k32](/packages/testo-testo)

PHPackages © 2026

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