PHPackages                             front-interop/interface - 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. front-interop/interface

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

front-interop/interface
=======================

Interoperable front controller interfaces for PHP.

1.x-dev(1mo ago)111[1 issues](https://github.com/front-interop/interface/issues)1MITPHPPHP >=8.4CI passing

Since May 8Pushed 1mo agoCompare

[ Source](https://github.com/front-interop/interface)[ Packagist](https://packagist.org/packages/front-interop/interface)[ Docs](https://github.com/front-interop/interface)[ RSS](/packages/front-interop-interface/feed)WikiDiscussions 1.x Synced today

READMEChangelog (1)Dependencies (5)Versions (2)Used By (1)

Front-Interop Standard Interface Package
========================================

[](#front-interop-standard-interface-package)

[![PDS Skeleton](https://camo.githubusercontent.com/50d01a5094afcc3a827c3cadaec43d23b2a256cb249f5fdd6e5ffdb53ea7971c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7064732d736b656c65746f6e2d626c75652e7376673f7374796c653d666c61742d737175617265)](https://github.com/php-pds/skeleton)[![PDS Composer Script Names](https://camo.githubusercontent.com/0c17df07fd0a51ad878f1de0d4c17ea8e460f2e96ce796c8cd58e6c96ed9c08d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7064732d636f6d706f7365722d2d7363726970742d2d6e616d65732d626c75653f7374796c653d666c61742d737175617265)](https://github.com/php-pds/composer-script-names)

Front-Interop provides an interoperable package of standard interfaces for front controller functionality in any execution context (HTTP, CLI, etc.). It reflects, refines, and reconciles the common practices identified within [several pre-existing projects](./README-RESEARCH.md).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/bcp14/) ([RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119), [RFC 8174](https://datatracker.ietf.org/doc/html/rfc8174)).

This package attempts to adhere to the [Package Development Standards](https://php-pds.com/) approach to [naming and versioning](https://php-pds.com/#naming-and-versioning).

Interfaces
----------

[](#interfaces)

This package defines the following interfaces:

- [*FrontController*](#frontcontroller) affords an entry point into the outermost presentation layer in any execution context (HTTP, CLI, etc.).
- [*FrontTypeAliases*](#fronttypealiases) provides custom PHPStan types to aid static analysis.

### *FrontController*

[](#frontcontroller)

[*FrontController*](#frontcontroller) affords an entry point into the outermost presentation layer in any execution context (HTTP, CLI, etc.).

- Directives:

    - Implementations MUST gracefully handle all [*Throwable*](https://php.net/Throwable)s.
- Notes:

    - **Handle all possible exceptions.** The logic calling the front controller should not have to deal with any exceptions bubbling up from it. The implementation may accomplish this by catching [*Throwable*](https://php.net/Throwable)directly, by registering a [`set_exception_handler()`](https://php.net/set_exception_handler) callback, or by some other means.

#### *FrontController* Methods

[](#frontcontroller-methods)

- ```
    public function run() : front_exit_status_int;
    ```

    - Runs the front controller.
    - Directives:

        - Implementations MUST report success by returning an integer `0`.
        - Implementations MUST report non-success by returning an integer between `1` and `254` (inclusive).
    - Notes:

        - **The return value is intended as an exit status code.** Exit status codes may be received initially by the in-process logic that invoked `run()` (bootstrap scripts, test harnesses, etc.), and may ultimately be received by a parent process (shell, supervisor, init system, CI runner, monitoring tool, or similar) via [`exit()`](https://php.net/exit). Whether or not the exit status is consumed by the calling code or parent process depends on the execution environment: php-fpm and mod\_php typically have no consumer, whereas worker loops, supervised long-running processes, runtime layers, and CI harnesses do.
        - **"Success" and "non-success" are context-dependent.** In an HTTP context, "success" typically means that the request was processed and a response was emitted regardless of the HTTP status code, whereas "non-success" may indicate that a [*Throwable*](https://php.net/Throwable) had to be handled by the *FrontController*itself. In a command line context, "success" typically means that the command completed without errors, whereas "non-success" may be one of several error conditions (cf. the [`sysexits.h`](https://man7.org/linux/man-pages/man3/sysexits.h.3head.html) conventions where applicable).
        - **The exit status code `255` is reserved by PHP itself.** Cf. [`exit()`](https://php.net/exit): "Exit codes should be in the range 0 to 254, the exit code 255 is reserved by PHP and should not be used."

### *FrontTypeAliases*

[](#fronttypealiases)

[*FrontTypeAliases*](#fronttypealiases) provides custom PHPStan types to aid static analysis.

- ```
    front_exit_status_int int

    ```

    - An `int` exit status code: `0` for success, `1` to `254` for non-success. The value `255` is reserved by PHP itself.

Implementations
---------------

[](#implementations)

Implementations MAY define additional class members not defined in these interfaces.

Notes:

- **Reference implementations** are available at .

Q & A
---------

[](#q--a)

### Why `run()`?

[](#why-run)

The researched projects use one of six verbs for the front controller's main method: `dispatch()`, `execute()`, `handle()`, `__invoke()`, `run()`, or `start()`. Of these, `run()` is the clear majority at 12 of 23 projects; the remaining five verbs together account for the other 11. Front-Interop follows the majority practice.

### Why does `run()` return `int`?

[](#why-does-run-return-int)

Of the 23 researched projects:

- 11 return `void` or `null` and handle response-sending themselves;
- 7 return a response object for the calling code to send;
- 3 return some other value (`$this` or `mixed`);
- 1 (Tempest) `never` returns; and
- 1 (Symfony) returns an `int` exit code.

The majority of researched projects in an HTTP execution context have the front controller handle response-sending itself and return nothing.

However, Front-Interop observes that a front controller in a different execution context may need to return an integer exit status code to its caller or parent process. These contexts include, among others:

- command line invocations
- continuous integration runners
- long-running processes
- queue workers
- test harnesses
- worker loops

While providing two interfaces (one to return `void` and another to return `int`) would cover both cases, it leads to inconsistencies in setup and expectations.

Thus, contra the most common `void` or `null` return, Front-Interop directs that `run()` returns an integer exit status code. This is an unusual practice for front controllers in an HTTP execution context, but imposes only a trivial implementation burden. Doing so allows the same interface to be used across many different execution contexts, and keeps the interface machine-friendly.

### Why handle all [*Throwable*](https://php.net/Throwable)s?

[](#why-handle-all-throwables)

Of the 23 researched projects, 21 handle exceptions in some way. The specific handling location varies between projects: 4 in the bootstrap, 2 in the front controller itself, and the remainder somewhere deeper in the call stack. For that remainder, either the bootstrap or the front controller defines or registers the handling logic.

Of the 21 projects that handle exceptions, 19 handle all types of [*Throwable*](https://php.net/Throwable), 1 handles all types of [*Exception*](https://php.net/Exception), and 1 handles only specific exception subtypes.

Front-Interop observes that a front controller invocation occurs at the outermost boundary of the presentation layer. This is the last point at which any uncaught [*Throwable*](https://php.net/Throwable)s may be handled gracefully. The choice then is whether they are handled by the bootstrap script, or by the front controller proper.

In the interest of keeping such handling within a class, Front-Interop directs that *FrontController* itself must act as (or delegate to) a final backstop against [*Throwable*](https://php.net/Throwable)s. There may be other handling subsystems in the logic called by the *FrontController*, but any [*Throwable*](https://php.net/Throwable) that escapes them will be handled by the *FrontController* or its delegate.

---

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance69

Regular maintenance activity

Popularity9

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

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

Total

2

Last Release

56d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/25754?v=4)[Paul M. Jones](/maintainers/pmjones)[@pmjones](https://github.com/pmjones)

---

Top Contributors

[![pmjones](https://avatars.githubusercontent.com/u/25754?v=4)](https://github.com/pmjones "pmjones (15 commits)")

---

Tags

controllerfront

###  Code Quality

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/front-interop-interface/health.svg)

```
[![Health](https://phpackages.com/badges/front-interop-interface/health.svg)](https://phpackages.com/packages/front-interop-interface)
```

###  Alternatives

[aimeos/ai-controller-frontend

Aimeos business controller logic for frontend

1.0k351.6k20](/packages/aimeos-ai-controller-frontend)[aura/dispatcher

Creates objects from a factory and invokes methods using named parameters; also provides a trait for invoking closures and object methods with named parameters.

3697.9k3](/packages/aura-dispatcher)

PHPackages © 2026

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