ApplicationBuilder and DX

[andrii-androshchuk]

Motivation

When starting a new Laravel application—especially using the ApplicationBuilder pattern in bootstrap/app.php — I encountered several limitations and DX (developer experience) concerns. The current approach, where a single “plain” PHP file is responsible for creating and configuring the entire application, feels inefficient and less maintainable in the long run. In this discussion, I want to highlight the issues I faced and propose a few suggestions for your review and feedback.

Problems & Solutions

1. Application Bootstrapping as a plain PHP File
   The application is currently created and returned from a single, plain PHP file via require_once. While this is simple, I believe it's not ideal for more complex applications. Additionally, this logic lives outside the App/ namespace.
   Suggestion: Introduce a dedicated class — perhaps something like [App | Kernel | AppFactory | ... ], that will be located in App/ namespace — to encapsulate the creation and configuration of the application. This class could expose a create() or build() method and be referenced directly from the front controller (e.g., public/index.php).

2. Provider Loading as a Separate File
   There is another plain PHP file (bootstrap/providers.php) just to return an array of providers. This again feels unnecessarily constrained and with limited flexibility.
   Suggestion: Move this logic into a method of the same proposed [App | Kernel] or builder class. That way, the list of providers can be built dynamically based on the environment or other conditions. This opens up more flexible and expressive configuration options, including use of private methods, composition, or other classes for modular setup.

3. Reducing Root-Level Directories
   If the logic from bootstrap/app.php and bootstrap/providers.php is moved into a dedicated class, the only remaining directory in bootstrap/ is bootstrap/cache.
   Suggestion: Consider moving bootstrap/cache to storage/framework/bootstrap to reduce clutter in the root and keep all writable directories under storage/. This could be done manually with $app->useBootstrapPath(...) but why not making it a standard practice and keep all writable directories only under storage/.

Inconsistencies in with*() Methods

Another set of concerns relates to the inconsistency in how with*() methods are defined and used in the ApplicationBuilder, here are the examples:

public function withProviders(array $providers = [], bool $withBootstrapProviders = true);
public function withEvents(array|bool $discover = []);
public function withBroadcasting(string $channels, array $attributes = []);
public function withMiddleware(?callable $callback = null);
public function withCommands(array $commands = []);
public function withExceptions(?callable $using = null);
public function withBindings(array $bindings);
public function withRouting(
    ?Closure $using = null,
    array|string|null $web = null,
    array|string|null $api = null,
    ?string $commands = null,
    ?string $channels = null,
    ?string $pages = null,
    ?string $health = null,
    string $apiPrefix = 'api',
    ?callable $then = null
);

A few issues I’ve encountered:

• There’s no consistent parameter style — some methods accept Closure, some callable, others only arrays or primitives.
• In the case of withRouting(), it accepts both a $using and a $then callback:
  • $using is called via $this->app->call(...), so it receives full dependency injection.
  • $then is just directly invoked with $then($this->app), with the container instance, but without DI.

Suggestion: Standardize how callbacks are handled. Ideally, all should accept Closure|callable, and all should be invoked through the container (e.g., $this->app->call(...)) to allow for proper DI.

Summary

To summarize, here are the proposed improvements:

• Replace bootstrap/app.php and bootstrap/providers.php with a dedicated builder class [App | Kernel].
• Enable dynamic provider resolution and modular configuration.
• Move bootstrap/cache into storage/framework/ for cleaner project structure, and remove bootstrap from the root.
• Standardize with*() method signatures and invocation strategy for better consistency DI, and DX.

Here is the example of the final class:

class Kernel
{
    public function create(): Application
    {
        return Application::configure(basePath: dirname(__DIR__.'/../../'))
            ->withRouting(...)
            ->withMiddleware($this->configureMiddleware())
            ->withExceptions(new ExeptionsHandler)
            ->withProviders($this->getProviders(), false)
            ->create();
    }

    private function getProviders(): array
    {
        return [
            \App\Providers\AppServiceProvider::class,
        ];
    }

    private function configureMiddleware(): \Closure
    {
        return function (Middleware $middleware) {

            // ...
        };
    }
}

The resulting project structure after applying these suggestions would look as follows:

app\
  ...
  Kernel.php
bootstrap\ -- removed
config\
storage\
...

I’d love to hear your thoughts and feedback on the proposed solution.

Thank you.

[macropay-solutions]

Anything would be better than the current laravel 11/12 sausage (chained) way of blindly (if you don't have documentation with examples you are doomed) bootstrapping the application.