Unorthodox Monoliths in Laravel
Laravel is often synonymous with simplicity and developer-friendly experience. But what happens when your application scales far beyond what Laravel’s default patterns provide? At Studocu, we’ve pushed the boundaries of what’s considered “standard” in Laravel development to keep our growing monolith efficient, maintainable, and evolving.
In this article, I’ll share some unconventional practices and techniques we’ve embraced that might make you rethink how you approach your Laravel projects. Whether navigating scaling challenges or just curious how far you can stretch Laravel, there’s something here for you.
In this article we will learn about:
- Multi-Application Infrastructure
- Circuit-Breaker (fuse) for Distributed Databases
- Hybrid Optimizations When MySQL Alone Isn’t Enough
1. Multi-Application Infrastructure
By default, Laravel ships with a single application and shared service providers. However, as projects grow, you might end up with multiple applications within the same Laravel codebase. Think of the main website, a CMS, a Webhooks service, etc. Initially, this setup works fine, but as performance becomes critical and different applications evolve at different paces, you may need a more isolated approach.
In our case, we’re migrating incrementally to a Next.js frontend powered by a REST API, while still maintaining and evolving our Laravel monolith. The simplest and most efficient solution was embedding the REST API within the monolith itself, reusing the same infrastructure, configuration, and models to keep everything in sync.
This approach worked well until our REST API started conflicting with other applications due to the shared core middleware and HTTP Kernel. To solve this, we needed a way to boot the REST API separately while keeping it inside the monolith.
Plus we were faced with two facts:
- Rest API expects larger traffic than the rest of the applications, which means the faster it is the better.
- We don’t need to support heavy and diverse features in Rest, such as CMS services, UI services, Translation services, etc.
1.1. The Solution: Multi-Application Bootstrapping
The key idea is to spawn a separate Laravel application instance for the REST API with its own HTTP Kernel and exception handler. This allows isolating its global middleware, service providers, and error handling from the other applications.
This not only improves performance but also makes the code much more readable. We eliminate any possible conditional logic that might arise in the codebase to give Rest API a slightly different treatment and vice-versa.
How Laravel Handles Requests
Laravel is a front-controller framework, meaning every request first hits ./public/index.php, where Laravel:
- Captures the request
- Instantiates the application
- Creates the Kernel
- Handles the request and returns a response
A simplified version of this process looks like:
<?php
$app = require_once __DIR__.'/../bootstrap/app.php';
$kernel = $app->make(Kernel::class);
$response = $kernel->handle(
$request = Request::capture()
)->send();
$kernel->terminate($request, $response);This is where we introduce our multi-application logic. We check whether the request is for the REST API and load a separate application instance if needed:
$request = Request::capture();
$isRest = $request && str_starts_with($request->getRequestUri(), '/rest-api');
$app = $isRest
? require_once __DIR__ . '/../bootstrap/rest-app.php'
: require_once __DIR__ . '/../bootstrap/app.php';
$kernel = $app->make(Kernel::class);
$response = $kernel
->handle($request)
->send();The key difference here is that REST API requests load bootstrap/rest-app.php, while other requests load the default Laravel app.
Booting a Separate Application
Inside bootstrap/rest-app.php, we define a custom application instance:
<?php
// rest-api.php
$app = new App\Http\RestApi\RestApiApplication(
$_SERVER['APP_BASE_PATH'] ?? dirname(__DIR__)
);
$app->singleton(
Illuminate\Contracts\Http\Kernel::class,
App\Http\RestApi\Kernel::class
);
$app->singleton(
Illuminate\Contracts\Debug\ExceptionHandler::class,
App\Exceptions\RestApiHandler::class
);
return $app;This achieves three things:
- It creates a custom
RestApiApplicationinstance. - It binds a separate HTTP Kernel for handling requests.
- It registers a separate exception handler.
By isolating the REST API, we ensure it has its own middleware stack and error handling without affecting the rest of the monolith.
1.2. Customizing Service Providers
To take this further, we customize the RestApiApplication class to load only the necessary service providers:
<?php
namespace App\Http\RestAPI;
use Illuminate\Foundation\Application as BaseApplication;
class RestApiApplication extends BaseApplication
{
public function registerConfiguredProviders(): void
{
parent::registerConfiguredProviders();
foreach (config('app.contextual_providers.rest-api', []) as $provider) {
$this->register($provider);
}
}
}The app.contextual_providers.rest-api config defines which service providers to load specifically for the REST API.
Configuring Providers Per Application
Our config/app.php file now includes:
'providers' => [
/*
* Core Services Providers.
* These are the providers used by all applications.
* Don't register anything freely here. Check `app.contextual_providers` first for contextual providers.
*/
Illuminate\Auth\AuthServiceProvider::class,
Illuminate\Bus\BusServiceProvider::class,
Illuminate\Broadcasting\BroadcastServiceProvider::class,
Illuminate\Cache\CacheServiceProvider::class,
Illuminate\Session\SessionServiceProvider::class,
Illuminate\Cookie\CookieServiceProvider::class,
Illuminate\Database\DatabaseServiceProvider::class,
Illuminate\Encryption\EncryptionServiceProvider::class,
Illuminate\Filesystem\FilesystemServiceProvider::class,
Illuminate\Foundation\Providers\FoundationServiceProvider::class,
Illuminate\Hashing\HashServiceProvider::class,
Illuminate\Pagination\PaginationServiceProvider::class,
Illuminate\Queue\QueueServiceProvider::class,
Illuminate\Redis\RedisServiceProvider::class,
Illuminate\Auth\Passwords\PasswordResetServiceProvider::class,
Illuminate\Validation\ValidationServiceProvider::class,
App\Providers\RouteServiceProvider::class,
App\Providers\StorageServiceProvider::class,
Illuminate\Foundation\Providers\ConsoleSupportServiceProvider::class,
App\Providers\AuthServiceProvider::class,
Illuminate\Mail\MailServiceProvider::class,
// As per Laravel 10, these are bound in a deep level. So we need to keep them.
// They are however not ideal for all applications.
// e.g. The Rest API is translation agnostic and doesn't render UI components.
App\Providers\TranslationServiceProvider::class,
Illuminate\View\ViewServiceProvider::class,
],
'contextual_providers' => [
'rest-api' => [
App\Providers\RestApiAppServiceProvider::class,
App\Services\JWTAuth\JWTAuthServiceProvider::class,
/etc.
],
'monolith' => [
App\Providers\AppServiceProvider::class,
Collective\Html\HtmlServiceProvider::class,
App\Providers\DebugBarCollectorServiceProvider::class,
App\Providers\CMSServiceProvider::class,
// etc.
],
],This setup lets us:
- Load specific service providers per application.
- Enable separate global features, such as a stricter Eloquent mode for the REST API (
Model::shouldBeStrict(!$this->app->isProduction());). - Optimize performance by excluding unnecessary providers in the REST API.
Note 1: To fully achieve this, you need to have a custom application for the non-rest, that will load the contextual providers (similar to what we did with RestApplication).
Note 2: To see how you can achieve this with Laravel 11, check the supporting repository. It has all the examples from the article in Laravel 11.
1.3. Bonus: Further Optimizations
Disable Auto-Discovery
Laravel’s package auto-discovery can slow down boot times. Manually registering packages per application can further improve the overall performance of different applications.
To disable auto-discovery you need to add this to composer.json ,
"extra": {
"laravel": {
"dont-discover": ["*"]
}
},Per-Application Deployment
If your setup allows it, you can deploy and roll back each application independently within the same Laravel codebase. To make your monolith more flexible and reliable, you can configure your load balancer to route requests to different infrastructures based on the request path.
For example, if a bug appears on the main website and you need to roll back a few releases, a traditional setup might also undo fixes/features for the Rest API. With separate deployments, the Rest API(or any other application) remains unaffected.
2. Circuit-Breaker (fuse) for Distributed Databases
Large monoliths often mean large databases, multi-region availability, and replication challenges. As traffic grows, the database tends to be the first component to show scalability issues, and at Studocu, we’ve encountered our share of them. We’ve been using AWS Aurora for a while, and while it solved some issues we had with traditional MySQL, it introduced its own set of problems, most notably, issues with table replication.
One recurring problem was the loss of large tables during replication. These tables, which store pre-computed data for things like recommendations and popularity, often got lost due to how we synced them. We called this issue the “bricked reader” problem.
2.1. Circuit Fuse
In typical setups, a circuit breaker sits between an implementation and a service, acting as a proxy to manage request availability. In our case, however, the database replication was our main point of failure. Large, frequently synced tables were often lost during replication, but their absence didn’t directly impact the product, it mainly affected SEO-related features like interlinking.
To avoid taking the entire website down because of a missing meta table, we introduced the concept of a “circuit fuse”. This fuse acts as a software proxy for database interactions that consumes the shock, it detects replication failures and fails gracefully. When a table is missing, it returns an empty state, allowing the UI to adjust accordingly.
Let’s see how we can build one.
Step 1: Register a Custom Database Connection
The first step in implementing a circuit fuse is to override the default MySQL connection class with our custom version. This can be done inside Laravel’s AppServiceProvider (or a dedicated DatabaseServiceProvider) using the Connection::resolverFor() method:
use App\Core\Database\Connections\MySqlConnection;
// AppServiceProvider or DatabaseServiceProvider, etc.
public function register(): void
{
// Register a custom MySQL connection class
Connection::resolverFor('mysql', fn (...$args) => new MySqlConnection(...$args));
}This tells Laravel to use MySqlConnection (our custom database connection class) instead of the default MySQL connection whenever a MySQL database connection is used. Which allows us to intercept database queries and handle failures gracefully.
Step 2: Extend the MySQL Connection Class
Next, we define our custom connection class MySqlConnection.
The custom connection extends the base one, and uses a custom trait (HandlesConnectionErrors), which will handle the database failures in a re-usable way so you can attach it to other connections.
<?php
namespace App\Core\Database\Connections;
use App\Core\Database\Concerns\HandlesConnectionErrors;
use Illuminate\Database\MySqlConnection as BaseConnection;
class MySqlConnection extends BaseConnection
{
use HandlesConnectionErrors;
}Step 3: Handle Database Errors Gracefully
Inside the HandlesConnectionErrors trait, we override the select() method to catch query exceptions and handle them based on the error code.
<?php
trait HandlesConnectionErrors {
public function select($query, $bindings = [], $useReadPdo = true): array
{
try {
return parent::select($query, $bindings, $useReadPdo);
} catch (QueryException $exception) {
if (!app()->isProduction()) {
throw $exception;
}
/**
* @see https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html
*/
return match ($exception->errorInfo[1] ?? null) {
1051, // Bad table
1146, // No such table
1109, // Unknown table
1356 // Invalid View or view permission issue
=> $this->failGracefully($exception),
default => throw $exception,
};
}
}
private function failGracefully(QueryException $exception): array
{
Log::info('A table was not readable', context: [
'sql' => $exception->getSql(),
'error' => $exception->getMessage(),
]);
return [];
}What it does:
- It overrides Laravel’s default
select()method to catch query exceptions. - If the database error is related to a missing table, it returns an empty array instead of crashing, allowing the UI to handle the missing data gracefully.
- It logs the error so developers can track issues without affecting users.
Note: The example above is tailored for MySQL server errors. Check the supporting repository to see a more elaborate matching that includes another driver, SQLite.
2.2. Bonus: Handling Maintenance Failures Gracefully
During maintenance tasks (like a blue/green deployment or failover) outside a maintenance mode, the database might be expectedly unavailable for a brief time. We can catch these errors separately and return a 503 Service Unavailable response:
@@ public function select($query, $bindings = [], $useReadPdo = true): array
[..]
return match ($exception->errorInfo[1] ?? null) {
1051, // Bad table
1146, // No such table
1109, // Unknown table
1356 // Invalid View or view permission issue
=> $this->failGracefully($exception),
+ 2002, // Operation timed out (failover, blue/green switch)
+ 1290 // Database has an option preventing statement execution, like `readonly` mode
+ => $this->failMaintenenaceErrorGracefully($exception),
default => throw $exception,
};The method that handles the errors might look like this,
private function failMaintenenaceErrorGracefully(QueryException $exception): never
{
// Report each exception
// Optionally, implement throttling to report only if the error persists after X seconds.
report($exception);
abort(
response(
view('errors.503', ['title' => trans('messages.website_under_maintenance')]),
503,
[
'Refresh' => config('app.maintenance.refresh'),
],
),
);
}2.3. Real Circuit Breaker
While the circuit fuse works well for internal systems like the database, it’s not enough when dealing with external services or third-party APIs. In these cases, a true circuit breaker is the right call.
I won’t go into the implementation details here, to avoid being too orthodox, but I recommend the Ganesha PHP package for those looking for a simple solution. You can use it directly or wrap it with your logic to integrate it into your application.
3. Hybrid Optimizations When MySQL Alone Isn’t Enough
As established in the previous section, the database is often the first component to struggle under increased traffic. Weak database designs and the lack of proper indices are the usual culprits.
Often, adding the missing index or optimizing queries to use the right indices can solve the problem. However, sometimes you encounter blockers, such as:
- Locking issues when adding an index to a large table (which can cause downtime).
- Technical limitations that prevent further optimization.
When this happens, it helps to think outside the box, literally, and use a combination of PHP + SQL to optimize queries and improve performance.
Let’s have a practical example, and see how this technique can solve it.
3.1. The Problem: Paginating Course Documents by Category
We have a course page that displays paginated documents per category. The categories are dynamic, meaning they depend on what documents are available for a course.
SEO Requirements:
- The first two pages of documents for each category should be pre-loaded during SSR (Server-Side Rendering).
- This makes pagination tricky since we need to paginate per category and load multiple pages in one go.
Why is MySQL Alone Not Enough?
- LIMIT in subqueries is not allowed, so we’d need a UNION query to handle every possible category.
- Counting all results per category for pagination would require many
COUNT()queries, making it inefficient.
Goal: Load Two Pages Per Category as Fast as Possible
We want to achieve this with a few queries while ensuring fast execution times.
3.2. Solution: Using an Index-Only Query
An index-only query retrieves results without accessing the full table, making it almost instantaneous.
Gladly, for this page, all the information we needed to find the first two pages of valid documents per category with the default sorting are all present in a composite index on the following columns: [course_id, category_id, published_at, deleted_at, popularity_score].
This means we can:
- Load all documents for a course using an index-only query.
- Group, sort, paginate, and extract metadata in PHP.
- Fetch full document details (for the initial pages) in a second query.
Implementation Steps
We’ll build a Query class to handle this in three steps:
- Extract metadata per category using an index-only query.
- Load the full document data for selected IDs.
- Hydrate metadata by mapping documents back to their categories.
In case you are interested on what Query classes are, they were discussed in a previous article: You might not need a repository in Laravel: 3 alternatives)
—
The Query class skeleton:
<?php
class CourseInitialDocumentPerCategoryQuery
{
public const PER_PAGE = 8;
private readonly int $totalPerCategory;
public function __construct(
private readonly Course $course,
private readonly int $perPage = self::PER_PAGE,
) {
$this->totalPerCategory = $this->perPage * 2; // Load two pages per category
}
public function get(): Collection
{
$metadata = $this->getMetadataPerCategory();
$documentsById = $this
->loadDocumentsFromIds(
ids: $metadata->flatMap->items->pluck('id')->all(),
)
->keyBy('id');
$documents = $this->metadataToPaginatedCategories($metadata, $documentsById);
// you might also eager load the documents' relations.
return $documents;
}
}Step 1: Extract metadata per category using an index-only query
In this step, we leverage an index-only query to retrieve document metadata quickly. With this metadata, we can find the first two pages of documents per category (after sorting) plus the total number of documents which is information needed for length-aware pagination.
private function getMetadataPerCategory(): Collection
{
return Document::query()
->select('id', 'category_id', 'popularity_score', 'published_at')
->where('course_id', $this->course->id)
->whereNotNull('published_at')
->toBase() // <- Avoids Eloquent hydration
->get() // <- Fetches ALL assigned documents for the course
->groupBy('category_id')
->map(fn (Collection $documents): array => [
'total' => $documents->count(),
'items' => $this->rearrangeDocumentsOnPages($documents),
]);
}
private function rearrangeDocumentsOnPages(Collection $documentsMetadata): Collection
{
return $documentsMetadata
->sortBy([
['popularity_score', 'desc'],
['published_at', 'desc'],
['id', 'desc'],
])
->take($this->totalPerCategory); // Keep only two pages worth of documents
}Step 2: Load Full Document Data
After gathering the metadata, we can now proceed to load the full documents based on the IDs we collected. This is done with a single query that selects only the necessary fields for display.
private function loadDocumentsFromIds(array $ids): Collection
{
return Document::query()
->select([
// Required columns
])
->whereIntegerInRaw('id', $ids)
->get();
}Step 3: Hydrate Metadata with Full Documents
We map the full documents back to the metadata, ensuring the correct order. We also calculate pagination-related metadata like the current page and total pages based on the document count per category.
private function metadataToPaginatedCategories(Collection $metadata, Collection $documentsById): Collection
{
return $metadata
->map(fn (array $categoryMetadata, int $categoryId) => [
'items' => EloquentCollection::make(
$categoryMetadata['items']
->map(fn (object $rawDocumentObject): Document => $documentsById->get($rawDocumentObject->id))
->values(),
),
'metadata' => [
'total' => $categoryMetadata['total'],
'per_page' => ...,
'current_page' => ...,
'last_page' => ...,
],
]);
}3.3. The Results
With the above technique, we’ve achieved our goal with just 2 queries (not counting the eager loading) and massively optimized the page.
The courses with a large document pool went from ~8s to <200ms. The ones with a small document pool went from ~200ms to <34ms. Plus, the total number of queries on the page went from 58 to 24. These are amazing numbers for what we had originally.
Are you struggling with your database?
In case you are in the stage already and adding indices is not helping, make sure to consider reading this book <Indexing Beyond The Basics>. It will be a massive help for your query optimization journey.
Closing Notes
This article explored different strategies for addressing scalability/maintainability challenges in large monoliths. We covered multi-application infrastructure to separate code per application, circuit fuses for more reliable databases, and index-only queries to handle complex data requirements. Keep in mind that what works for one system may not be the best for another, so adapting these approaches to fit your specific needs is important. Happy optimizing!
Check out this repository that has examples for everything discussed in this article (adjusted for Laravel 11).
Thanks for reading!
