<div align="center"> <p> <img src="docs/img/logo.png" alt="Bypass Logo" width="200" /> <h1>Bypass for PHP</h1> </p> </div> <p align="center"> <a href="#about">About</a> | <a href="#requirements">Requirements</a> | <a href="#installation">Installation</a> | <a href="#writing-tests">Writing Tests</a> | <a href="#api-reference">API Reference</a> | <a href="#examples">Examples</a> | <a href="#troubleshooting">Troubleshooting</a> | <a href="#contributing">Contributing</a> | <a href="#credits">Credits</a> | <a href="#inspired">Inspired</a> </p> <p align="center">   <a href="README.md"> <img height="20px" src="https://img.shields.io/badge/English (US)-flag.svg?color=555555&style=flat&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjM1IDY1MCIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiPg0KPGRlZnM+DQo8ZyBpZD0idW5pb24iPg0KPHVzZSB5PSItLjIxNiIgeGxpbms6aHJlZj0iI3g0Ii8+DQo8dXNlIHhsaW5rOmhyZWY9IiN4NCIvPg0KPHVzZSB5PSIuMjE2IiB4bGluazpocmVmPSIjczYiLz4NCjwvZz4NCjxnIGlkPSJ4NCI+DQo8dXNlIHhsaW5rOmhyZWY9IiNzNiIvPg0KPHVzZSB5PSIuMDU0IiB4bGluazpocmVmPSIjczUiLz4NCjx1c2UgeT0iLjEwOCIgeGxpbms6aHJlZj0iI3M2Ii8+DQo8dXNlIHk9Ii4xNjIiIHhsaW5rOmhyZWY9IiNzNSIvPg0KPC9nPg0KPGcgaWQ9InM1Ij4NCjx1c2UgeD0iLS4yNTIiIHhsaW5rOmhyZWY9IiNzdGFyIi8+DQo8dXNlIHg9Ii0uMTI2IiB4bGluazpocmVmPSIjc3RhciIvPg0KPHVzZSB4bGluazpocmVmPSIjc3RhciIvPg0KPHVzZSB4PSIuMTI2IiB4bGluazpocmVmPSIjc3RhciIvPg0KPHVzZSB4PSIuMjUyIiB4bGluazpocmVmPSIjc3RhciIvPg0KPC9nPg0KPGcgaWQ9InM2Ij4NCjx1c2UgeD0iLS4wNjMiIHhsaW5rOmhyZWY9IiNzNSIvPg0KPHVzZSB4PSIuMzE1IiB4bGluazpocmVmPSIjc3RhciIvPg0KPC9nPg0KPGcgaWQ9InN0YXIiPg0KPHVzZSB4bGluazpocmVmPSIjcHQiIHRyYW5zZm9ybT0ibWF0cml4KC0uODA5MDIgLS41ODc3OSAuNTg3NzkgLS44MDkwMiAwIDApIi8+DQo8dXNlIHhsaW5rOmhyZWY9IiNwdCIgdHJhbnNmb3JtPSJtYXRyaXgoLjMwOTAyIC0uOTUxMDYgLjk1MTA2IC4zMDkwMiAwIDApIi8+DQo8dXNlIHhsaW5rOmhyZWY9IiNwdCIvPg0KPHVzZSB4bGluazpocmVmPSIjcHQiIHRyYW5zZm9ybT0icm90YXRlKDcyKSIvPg0KPHVzZSB4bGluazpocmVmPSIjcHQiIHRyYW5zZm9ybT0icm90YXRlKDE0NCkiLz4NCjwvZz4NCjxwYXRoIGZpbGw9IiNmZmYiIGlkPSJwdCIgZD0iTS0uMTYyNSwwIDAtLjUgLjE2MjUsMHoiIHRyYW5zZm9ybT0ic2NhbGUoLjA2MTYpIi8+DQo8cGF0aCBmaWxsPSIjYmYwYTMwIiBpZD0ic3RyaXBlIiBkPSJtMCwwaDEyMzV2NTBoLTEyMzV6Ii8+DQo8L2RlZnM+DQo8cGF0aCBmaWxsPSIjZmZmIiBkPSJtMCwwaDEyMzV2NjUwaC0xMjM1eiIvPg0KPHVzZSB4bGluazpocmVmPSIjc3RyaXBlIi8+DQo8dXNlIHk9IjEwMCIgeGxpbms6aHJlZj0iI3N0cmlwZSIvPg0KPHVzZSB5PSIyMDAiIHhsaW5rOmhyZWY9IiNzdHJpcGUiLz4NCjx1c2UgeT0iMzAwIiB4bGluazpocmVmPSIjc3RyaXBlIi8+DQo8dXNlIHk9IjQwMCIgeGxpbms6aHJlZj0iI3N0cmlwZSIvPg0KPHVzZSB5PSI1MDAiIHhsaW5rOmhyZWY9IiNzdHJpcGUiLz4NCjx1c2UgeT0iNjAwIiB4bGluazpocmVmPSIjc3RyaXBlIi8+DQo8cGF0aCBmaWxsPSIjMDAyODY4IiBkPSJtMCwwaDQ5NHYzNTBoLTQ5NHoiLz4NCjx1c2UgeGxpbms6aHJlZj0iI3VuaW9uIiB0cmFuc2Zvcm09Im1hdHJpeCg2NTAgMCAwIDY1MCAyNDcgMTc1KSIvPg0KPC9zdmc+DQo=" alt="US flag in base64" /> </a>  <a href="docs/README_pt-BR.md"> <img height="20px" src="https://img.shields.io/badge/Português (BR)-gray.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAALCAIAAAD5gJpuAAAABGdBTUEAAK/INwWK6QAAABl0RVh0U29mdHdhcmUAQWRvYmUgSW1hZ2VSZWFkeXHJZTwAAAHjSURBVHjaYmRIZkCAfwwMf2DkLzCCMyDoBwNAALEAlTVGN/5nYPj//x8Q/P3/9++/vzZa31gY/mw5z/Tn3x8g98+f37///fn99/eq2lUAAQTS8J/h/7NPz/9C5P79WRj89f9/zv//fztLvPVezPzrz+8/f3//+vtLhl8GaANAAIE1/P8PVA1U6qn7NVTqb1XVpAv/JH7/+a/848XmtpBlj39PO8gM1PP7z2+gqwACiAnoYpC9TF9nB34NVf5z4XpoZJbEjJKfWaEfL7KLlbaURKj8Opj08RfIVb+BNgAEEBPQW1L8P+b6/mb6//s/w+/+nc4F0/9P2cj65xdHc+p/QR39//9/AdHJ9A/60l8YvjIABBAT0JYH75jStv75zwCSMBY8BXTMxXv/21ezfHj9X5/3BESDy5JfBy7/ZuBnAAggkA1//vx594kpaCnLloe/smLaVT9/ff3y/+/P/w+u/+JuW7fhwS/tSayPXrOycrEyfGQACCAWoA1//oOCDIgm72fu4vy6b4LD/9/S/3///s9+S28yy+9/LEAf//kLChVgCAEEEEjD7z9/JHgkQeHwD8gUjV79O9r6CzPLv6lr1OUFwWH9Fxjcv//9BcYoA0AAMTI4ImIROUYRMf2XARkABBgA8kMvQf3q+24AAAAASUVORK5CYII=" alt="BR flag in base64" /> </a> </p> <p align="center"> <a href="https://github.com/ciareis/bypass/actions/workflows/php.yml"> <img src="https://github.com/ciareis/bypass/actions/workflows/php.yml/badge.svg?branch=main" alt="Tests" style="max-width:100%;" /> </a> <a href="https://packagist.org/packages/ciareis/bypass" rel="nofollow"> <img src="https://img.shields.io/github/v/tag/ciareis/bypass" alt="GitHub tag (latest by date)" data-canonical-src="https://img.shields.io/github/v/tag/ciareis/bypass" style="max-width:100%;" /> </a> <a href="https://packagist.org/packages/ciareis/bypass" rel="nofollow"> <img src="https://img.shields.io/packagist/dt/ciareis/bypass" alt="Packagist Downloads" data-canonical-src="https://img.shields.io/packagist/dt/ciareis/bypass" style="max-width:100%;" /> </a> <a href="https://github.com/ciareis/bypass/blob/main/LICENSE.md"> <img src="https://img.shields.io/packagist/l/ciareis/bypass" alt="Packagist License" data-canonical-src="https://img.shields.io/packagist/l/ciareis/bypass" style="max-width:100%;" /> </a> <a href="https://github.com/ciareis/bypass/commits/main"> <img src="https://img.shields.io/github/last-commit/ciareis/bypass" alt="Last Updated" data-canonical-src="https://img.shields.io/github/last-commit/ciareis/bypass.svg" style="max-width:100%;" /> </a> </p>

About

<table> <tr> <td> <p>Bypass for PHP provides a quick way to create a custom HTTP Server to return predefined responses to client requests.</p> <p>This is useful in tests when your application makes requests to external services, and you need to simulate different situations like returning specific data or unexpected server errors.</p> <p>Just open a Bypass server and configure your application/service to reach Bypass instead of the real-world API end point.</p> </td> </tr> </table>

Requirements

PHP: 8.2 or higher (tested up to PHP 8.4)
Composer: For dependency management

Known Issues

PHP 8.4: You may see deprecation warnings from testing dependencies (Pest/PHPUnit) related to ReflectionMethod::setAccessible(). These warnings are harmless and come from the testing frameworks themselves, not from Bypass. They will be resolved when the dependencies are updated to support PHP 8.4 fully.

Installation

To install via composer, run the following command:

composer require --dev ciareis/bypass

Video demo

Pest and Bypass

Writing Tests

🔥 Check out full code examples here section.

1. Open a Bypass Server

To write a test, first open a Bypass server:

//Open a new Bypass server
$bypass = Bypass::open();

Bypass will always run at http://localhost listening to a random port number.

To specify a custom port, just pass it in the argument (int) $port.

//Open a new Bypass using port 8081
$bypass = Bypass::open(8081);

Alternative method: You can also use Bypass::up() which is an alias for Bypass::open():

//Same as Bypass::open()
$bypass = Bypass::up();

2. Bypass URL and Port

You can retrieve the Bypass server URL using getBaseUrl().

$bypassUrl = $bypass->getBaseUrl(); //http://localhost:16819

If you need to retrieve only the port number, use the getPort() method:

$bypassPort = $bypass->getPort(); //16819

3. Routes

Bypass provides two types of routes: The Standard Route to return a text body content and the File Route, which returns a binary file.

When running your test suit, you should pass the URL created with Bypass to your service. In this way, you will make the service you are testing reach Bypass instead of reaching the real-world API end point.

3.1 Standard Route

use Ciareis\Bypass\Bypass;

//Json body
$body = '{"username": "john", "name": "John Smith", "total": 1250}';

//Route retuning the JSON body with HTTP Status 200
$bypass->addRoute(method: 'GET', uri: '/v1/demo/john', status: 200, body: $body);

//Instantiates a DemoService class
$service = new DemoService();

//Configure your service to access Bypass URL
$response = $service->setBaseUrl($bypass->getBaseUrl())
  ->getTotalByUser('john');

//Your test assertions here...

The method addRoute() accepts the following parameters:

Bypass

Install / Use

README