Wish list for Framework X v0.18.0 🎆

[clue]

Framework X v0.18.0 is coming soon! 🎉

Before releasing, I want to give everybody a chance to chime in. I'll also share some ideas I've been working on. If there's something you've been wanting, now's the time.

Scope for v0.18.0

This release focuses on continuous improvement with smaller improvements and may include some minor BC breaks, but this is probably not the time for major breaking changes. Think:

• Bug fixes and small features
• Minor refactorings and cleanups
• Documentation improvements

For bigger features and major BC breaks, I'll open a v0.19.0 wishlist soon, so feel free to hold those ideas for then.

How to participate

• One idea per comment to make voting easier
• Vote with 👍 on ideas you want to see
• Discussion welcome in reply threads
• I'll post my own ideas below as well, feedback welcome!

Timeline

⏰ This is a short wishlist window, planning to release in the next week or so. Bigger ideas go to v0.19.0.

Looking forward to your ideas! ❤️

[clue]

PHP 8.5+ support: PHP 8.5 has been released in November, time to add full support

[clue]

Resolved via #297

[clue]

Require PHP 8.1+: Probably out of scope for this release, but will likely happen in next release (v0.19.0). We've been playing on hard mode and see little demand for legacy PHP versions, dropping legacy PHP support should make maintenance much easier.

[clue]

Drop Generator-based coroutines and Promises: Probably out of scope for this release, but will likely happen in next release (v0.19.0).

Right now, request handlers can return either a response object, a promise which resolves to a response object or a coroutine that yields promises and eventually returns a response object. Similarly, middleware handlers have to support all three return types, making middleware implementations somewhat complex even for simple tasks (think adding a response header).

Modern code should use async()/await() provided by reactphp/async v4 which in turn requires PHP 8.1+ for full support (see also previous wish list item to require PHP 8.1+).

Supporting only response objects helps us reduce complexity substantially and somewhat simplify writing and reusing middleware handlers. Likewise, this makes PSR-15 middleware a much better fit (see separate wish list item).

Migrating from either Generator-based coroutines or promises to the await() function is relatively straightforward.

[clue]

Support request handler alias names/IDs using Container:

class Foo
{
    public function __invoke() { return new Response(); }
}

$container = new Container([
    Foo::class => new Foo(),
    'foo' => new Foo(),
]);

$app = new App($container);
$app->get('/ok', Foo::class);
$app->get('/future', 'foo');

Using class names is already supported (#89), defining container variables is already supported (#180), so we should also support referencing request handlers by their ID.

[clue]

Support arbitrary request handler method names:

class Foo
{
    public static function staticMethod() { return new Response(); }
    public function instanceMethod() { return new Response(); }
}

$container = new Container([
    Foo::class => new Foo(),
    'foo' => new Foo(),
]);

$app = new App($container);
$app->get('/ok1', [Foo::class, 'staticMethod']);
$app->get('/ok2', [new Foo(), 'instanceMethod']);
$app->get('/ok3', Foo::staticMethod(...));
$app->get('/ok4', new Foo()->instanceMethod(...));
$app->get('/future1', [Foo::class, 'instanceMethod']);
$app->get('/future2', ['foo', 'instanceMethod']);

Especially useful in smaller applications where it may make sense to combine multiple request handler methods in a single class. Using an array to reference static methods is already supported (because it validates the callable type) but the other types are not currently supported. The syntax is pretty widespread, so we should support it as well (see also PR #279 and previous wish list item to support referencing a class by its ID).

[clue]

Support PSR-15 request handlers:

class Foo implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface { return new Response(); }
}

$container = new Container([
    Foo::class => new Foo(),
]);

$app = new App($container);
$app->get('/ok', new Foo()->handle(...));
$app->get('/future1', Foo::class);
$app->get('/future2', [Foo::class, 'handle']);

Somewhat similar to using invokable classes like currently supported, but provides better type-safety and reuse across frameworks. Can currently be done with a simple adapter, but should be provided out-of-the-box for better DX (technically somewhat related to previous wish list item to support arbitrary method names).

[clue]

Support PSR-15 middleware:

class Authenticator implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        return $handler($request);
    }
}

$container = new Container([
    Authenticator::class => new Authenticator(),
    'auth' => new Authenticator(),
]);

$app = new App($container);
$app->get('/future1', Authenticator::class, Foo::class);
$app->get('/future2', 'auth', Foo::class);

Somewhat similar to using invokable classes like currently supported, but provides better type-safety and much better reuse across frameworks. Can currently be done with a PSR-15 adapter requiring some more work than PSR-15 request handlers to also support Generator-based coroutines and Promises, but should be provided out-of-the-box for better DX (technically somewhat related to previous wish list item to support PSR-15 request handlers).

[clue]

All-in on PSR-15: Implement PSR-15 interfaces for all built-in middleware and request handlers, plus the App itself, rather than using invokable classes everywhere.

$request = new ServerRequest('GET', '/future');
$response = $app->handle($request);

This provides better type-safety and much better reuse across frameworks.

Somewhat out of scope for this release but worth mentioning to bring this on the radar. Realistically, we can only do so once Generator-based coroutines and promises are no longer supported as return types and built-in PSR-15 support is ready (see previous wish list items).

[clue]

Clean up Container internals, improve error reporting, support modern PHP types with union types and explicit type casting. Most of this has already been implemented in recent days, but worth mentioning here. The goal is to allow more flexible environment configuration with explicit type casts:

$container = new Container([
    Foo::class => fn(string $EVENTSOURCE_URL, float $RETRY_DELAY) => new Foo($EVENTSOURCE_URL, $RETRY_DELAY),
    'RETRY_DELAY' => fn(float|string $RETRY_DELAY = 60.0): float => filter_var($RETRY_DELAY, FILTER_VALIDATE_FLOAT, FILTER_NULL_ON_FAILURE) ?? throw new \ValueError('Invalid $RETRY_DELAY value'),
]);

Eventually, we may implement automatic type casts (type juggling semantics), but I consider this out of scope here.

[clue]

Resolved via #284, #285, #286, #287, #288 and also #289, #290, #291

[clue]

Advanced: Refactor and rename SAPI internals to allow custom application runners, think queue runners, CRON, a FastCGI server and more.

The existing "SAPI" structure abstracts differences between the long-running HTTP server provided by ReactPHP and the more traditional CGI-like PHP SAPIs. I have a number of projects that need a custom "runner" to inject requests into the application, e.g. think a cron scheduler "spawning" a request or a queue runner transforming an incoming queue job into a request or a serverless environment that accepts requests using a custom callback mechanism.

This API would be considered advanced usage, but in either case we should support custom integrations more seamlessly.

[clue]

Resolved via #292, #294, #295, #296

[clue]

Clean up built-in handler structure:

FrameworkX\AccessLogHandler -> FrameworkX\Handler\AccessLogMiddleware
FrameworkX\ErrorHandler -> FrameworkX\Handler\ExceptionHandlerMiddleware
FrameworkX\FilesystemHandler -> FrameworkX\Handler\FileHandler
FrameworkX\Io\RedirectHandler -> FrameworkX\Handler\RedirectHandler
FrameworkX\Io\RouteHandler -> FrameworkX\Handler\RouteHandler
FrameworkX\Io\HtmlHandler -> FrameworkX\Handler\StatusHandler

Besides renaming, this also includes refactoring and rearranging some logic to avoid unneeded coupling and making the code more SOLID. In particular, the future StatusHandler should take care of built-in status responses (like 404 Not Found) instead of the ErrorHandler which in turn should take care of logging and reporting an error response (using the StatusHandler).

On top of this, there's a ton of functionality I would like to improve (e.g. file and redirect handlers should use URI templates, cross-referencing status handlers, custom log formats, support for JSON status replies, etc.).

Seeing the previous wish list items, I'm unsure if it's going to make it for this release. While renaming is straightforward, there's some overlap with future PSR-15 implementation which will likely incur a BC break anyway.

[wpjscc]

support route group

$app->group('/users', function($app){
        //lists
       $app->get('', 'xxxx');
       //create
       $app->post('', 'xxxx');
        //show
       $app->get('/{user_id}', 'xxxx');
        //update
       $app->put('/{user_id}', 'xxxx');
        //delete
       $app->delete('/{user_id}', 'xxxx');
}); 

[clue]

@wpjscc Agree this is very useful for larger APIs! Currently, I'm not entire sure about the API design and its implications, so I'm not sure it will make it in time for v0.18.0 without more substantial sponsorship. Perhaps we can continue the discussion in #134/#216/#219 to flesh out the API design and then bring it up to the roadmap again?

[clue]

Support built-in cron scheduler:

$app->post('/cron/send-reminder', new CronTrigger('0 8 * * Mon-Fri'), ReminderController::class);
$app->post('/cron/cleanup', new CronTrigger('0 * * * *'), new ExecHandler('rm -rf /tmp/*'));

Probably somewhat out of scope for this release but worth mentioning to bring this on the radar. I've been using a custom implementation for this in a number of projects for a while already, but there are longer-term plans to move this upstream when time allows and there's enough demand. Implementation is rock solid but currently makes some assumptions about environment and recent PHP versions (see previous wish list items to drop legacy environments).