PHPackages                             peroks/api-server - 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. [HTTP & Networking](/categories/http)
4. /
5. peroks/api-server

ActiveLibrary[HTTP & Networking](/categories/http)

peroks/api-server
=================

An ultra-light api server based on PSR-7, PSR-14 and PSR-15 best-practice standards.

0.6.1(11mo ago)039MITPHPPHP >=8.1

Since Jun 16Pushed 11mo ago1 watchersCompare

[ Source](https://github.com/peroks/api-server)[ Packagist](https://packagist.org/packages/peroks/api-server)[ RSS](/packages/peroks-api-server/feed)WikiDiscussions main Synced 1mo ago

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

Peroks REST API Server
======================

[](#peroks-rest-api-server)

### An ultra-light REST API server based on PSR-7, PSR-14 and PSR-15 best practice standards.

[](#an-ultra-light-rest-api-server-based-on-psr-7-psr-14-and-psr-15-best-practice-standards)

The REST API server is not a stand-alone application, but a **host** for your PSR-15 server request handlers and middleware. You can use the server as a module in your own application or extend it to create custom api servers.

How to use
----------

[](#how-to-use)

### Create a new REST API server instance

[](#create-a-new-rest-api-server-instance)

```
use Peroks\ApiServer\Server;
$server = new Server();

```

### Handle server requests

[](#handle-server-requests)

The REST API server itself only provides one single method: It takes a [PSR-7 Server Request](https://www.php-fig.org/psr/psr-7/#321-psrhttpmessageserverrequestinterface) and returns a [PSR-7 Response](https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface).

```
use Peroks\ApiServer\Server;
use GuzzleHttp\Psr7\ServerRequest;

$server   = new Server();
$request  = new ServerRequest( 'POST', '/test', [], 'Hello World' );
$response = $server->handle( $request );

```

This server does not process any requests by itself, it just distributes them to the registered request handlers and middleware and returns their responses.

### Register API endpoints

[](#register-api-endpoints)

In order to register an API endpoint, you first need to create your own [PSR-15 Server Request Handler](https://www.php-fig.org/psr/psr-15/#11-request-handlers). You'll find an example of a very simple implementation for testing purposes here: [TestHandler.php](tests/TestHandler.php).

Use an [Endpoint](src/Endpoint.php) wrapper to set the endpoint **route** (server path) and **http method** in addition to your PSR-15 server request **handler**.

The `route` and `action` properties are added to the request as reserved request **attributes**: `__route` and `__action`. The `handler` may use these attributes to map server requests to functions.

```
use Peroks\ApiServer\Server;
use Peroks\ApiServer\Endpoint;

$server  = new Server();
$handler = new YourRequestHandler();

$server->registry->addEndpoint( new Endpoint( [
    'route'   => '/test',           // Endpoint route (server path)
    'method'  => Endpoint::POST,    // Endpoint http method
    'action'  => 'echo',            // Endpoint action
    'handler' => $handler,          // PSR-15 server request handler
] ) );

```

You can check if an endpoint is registered, get it and remove it.

```
if( $server->registry->hasEndpoint( '/test', 'POST' ) ) {
    $endpoint = $server->registry->getEndpoint( '/test', 'POST' );
    $endpoint = $server->registry->removeEndpoint( '/test', 'POST' );
}

```

You can also get an array of all registered endpoints.

```
$array = $server->registry->getEndpoints();

```

### Register server middleware

[](#register-server-middleware)

Server middleware is used to modify or monitor server requests or responses. Typical examples are middleware for **authorisation**, **logging** and **caching**.

In order to register a server middleware, you first need to create your own [PSR-15 Server Middleware](https://www.php-fig.org/psr/psr-15/#12-middleware). You'll find an example of a very simple implementation for testing purposes here: [TestMiddleware.php](tests/TestMiddleware.php).

Use a [Middleware](src/Middleware.php) wrapper to provide the middleware `id`and your PSR-15 server middleware `instance` (both are required). The `id` can be any string identifying the registered middleware entry. In many cases, the middleware class name is a good choice.

```
use Peroks\ApiServer\Server;
use Peroks\ApiServer\Middleware;

$server     = new Server();
$middleware = new YourMiddleware();

$server->registry->addMiddleware( new Middleware( [
    'id'       => YourMiddleware::class,
    'name'     => 'Middleware instance for testing',
    'priority' => 20, // default is 50.
    'instance' => $middleware,
] ) );

```

You'll need the registered `id` if you later want to check if the middleware is registered, and to get or remove the middleware, i.e. like this:

```
if( $server->registry->hasMiddleware( YourMiddleware::class ) ) {
    $middleware = $server->registry->getMiddleware( YourMiddleware::class );
    $middleware = $server->registry->removeMiddleware( YourMiddleware::class );
}

```

You can also get an array of all registered middleware entries.

```
$array = $server->registry->getMiddlewareEntries();

```

### Register event listeners

[](#register-event-listeners)

In addition to middleware, you can also register **event listeners** to hook into the execution flow and modify data.

Use a [Listener](src/Listener.php) wrapper to provide an `id`, `type` and `callback` function for the listener (all are required). The `id` can be any string identifying the registered event listener.

In this example, we add authorization headers to all requests before they are handled and possibly rejected by a middleware or request handler.

```
use Peroks\ApiServer\Server;
use Peroks\ApiServer\Listener;
use Peroks\ApiServer\Event;

$server   = new Server();
$callback = function( Event $event ): void {
    $event->data->request = $event->data->request->withHeader( 'authorization', 'yes' );
};

$server->registry->addListener( new Listener( [
    'id'       => 'set-authorization',
    'type'     => 'server/request',
    'callback' => $callback,
] ) );

```

You'll need the registered `id` if you later want to check if the event listener is registered, and to get or remove the listener, i.e. like this:

```
if( $server->registry->hasListener( 'set-authorization' ) ) {
    $listener = $server->registry->getListener( 'set-authorization' );
    $listener = $server->registry->removeListener( 'set-authorization' );
}

```

You can also get an array of all registered event listeners.

```
$array = $server->registry->getListeners();

```

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance51

Moderate activity, may be stable

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 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 ~361 days

Total

3

Last Release

344d ago

PHP version history (2 changes)0.5.0PHP ^8.1

0.6.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/64a1f51e6583f76524ca53eab07eace42fece47d689585ee63cfbe27fb82515e?d=identicon)[peroks](/maintainers/peroks)

---

Top Contributors

[![peroks](https://avatars.githubusercontent.com/u/14331921?v=4)](https://github.com/peroks "peroks (50 commits)")

---

Tags

api-serverevent-dispatcherjson-serverpsr-14psr-15psr-7request-handlerrest-serverserver-handlerserver-middlewarepsr-7psr-14event dispatcherpsr-15request-handlerapi-serverrest-serverserver-middlewareserver-handler

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/peroks-api-server/health.svg)

```
[![Health](https://phpackages.com/badges/peroks-api-server/health.svg)](https://phpackages.com/packages/peroks-api-server)
```

###  Alternatives

[league/route

Fast routing and dispatch component including PSR-15 middleware, built on top of FastRoute.

6633.1M115](/packages/league-route)[relay/relay

A PSR-15 server request handler.

3302.1M86](/packages/relay-relay)[mezzio/mezzio-swoole

Swoole support for Mezzio

92238.9k3](/packages/mezzio-mezzio-swoole)[sunrise/http-router

A powerful solution as the foundation of your project.

16249.8k10](/packages/sunrise-http-router)[php-middleware/php-debug-bar

PHP Debug Bar PSR-15 middleware with PSR-7

76433.5k2](/packages/php-middleware-php-debug-bar)[laminas/laminas-mvc-middleware

Dispatch middleware pipelines in place of controllers in laminas-mvc.

22659.3k9](/packages/laminas-laminas-mvc-middleware)

PHPackages © 2026

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