front-interop/interface

1.x-dev 2026-02-06 19:07 UTC

Requires

• php: >=8.4

Requires (Dev)

• pds/composer-script-names: ^1.0
• pds/skeleton: ^1.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0
• star-interop/stardoc: 1.x@dev

MIT

• Paul M. Jones

• controller
• front

README

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.

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 (RFC 2119, RFC 8174).

Interfaces

This package defines the following interface:

• FrontController affords an entry point into the outermost presentation layer in any execution context (HTTP, CLI, etc.).

FrontController

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

• Directives:

  • Implementations MUST gracefully handle all Throwables.

• Notes:

  • Handle all possible exceptions. The logic calling the front controller should not have to deal with any exceptions bubbling up from it. This may be accomplished by catching all Throwables or using set_exception_handler().

FrontController Methods

• public function run() : int;

  • Runs the front controller.

  • Directives:

    • Implementations MUST return a meaningful exit code.

  • Notes:

    • Return 0 on success, 1 (or another non-zero exit code) on failure. Because this interface is intended to be usable in any execution context, it should be machine-friendly. Returning an exit code helps to make it so.

Implementations

• Directives:

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

• Notes:

  • Reference implementations may be found at https://github.com/front-interop/impl.

Q & A

Why does run() return int?

Most of the researched front controllers handle response-sending internally and return void. One (Symfony) handles response-sending internally and returns an int exit code. The remainder return a response to be sent by the calling logic (typically a bootstrap script).

As such, pre-release review indicated that the front controller in an HTTP execution context should handle sending the response, as do the majority of projects. However, a front controller in a CLI execution context will need to return an exit code.

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 majority of void returns, Front-Interop directs that run() should return an integer exit 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 in CLI and other execution contexts, and keeps the interface machine-friendly.