freezlike/maintenance-bundle
A PHP maintenance-mode bundle that lets you toggle site downtime with a single command, serve a custom maintenance page, and whitelist IPs or routes so admins and health checks stay online while everyone else sees a clean "back soon" notice.
This is a first release (v1) with a single stated compatibility claim: Symfony 6 or higher. There is no changelog history, no migration notes, and no Laravel-specific documentation yet — so treat the initial assessment as "evaluate before adopting" rather than "ready to install."
Before anything else, check the constraint against your Laravel version, because Laravel pins Symfony components transitively:
symfony: ^6.0 constraint should resolve cleanly.--ignore-platform-reqs to force it.Minimal first pass:
composer require <vendor>/<package> --dry-run
Run the dry-run first. Since this is v1, the goal of the first command is to see what Composer wants to upgrade or downgrade alongside it — a symfony/* bump that ripples into laravel/framework is the most likely early surprise.
Where to look first, in order:
composer.json of the package — confirm the actual constraint is ^6.0 and not 6.* (which would exclude 6.5+ patch lines), and check require-dev to see which Symfony minor they actually test against.config/services.php, services.xml, or services.yaml) — this tells you whether it expects Symfony's DI container or ships a Laravel service provider.README — v1 packages frequently ship with the README as the only real documentation.The most common first use case for a Symfony-first package dropped into Laravel is a self-contained utility: a parser, a formatter, a client wrapper. Start by instantiating it directly in a tinker session or a throwaway route before wiring it into a provider:
// php artisan tinker
$instance = new \Vendor\Package\Thing();
$instance->doSomething('input');
If that works with no container involvement, you have a low-risk integration and can wrap it at your leisure. If it demands constructor-injected Symfony services, budget time for the bridging work described below.
Because this is not a Laravel-native package, the integration pattern you choose matters more than usual.
Pattern 1 — Direct instantiation (preferred for v1). If the class has no hard dependencies on Symfony's container, bind it as a singleton in your own provider rather than relying on auto-discovery:
// app/Providers/AppServiceProvider.php
public function register(): void
{
$this->app->singleton(\Vendor\Package\Thing::class, function ($app) {
return new \Vendor\Package\Thing(
config('services.thing.endpoint'),
);
});
}
This gives you one place to change when v2 inevitably reshapes the constructor.
Pattern 2 — Bridge a Symfony service definition. If the package ships services.xml/services.yaml and expects autowiring, you can pull it into Laravel's container, but be selective. Registering an entire Symfony service file into a Laravel app often drags in EventDispatcherInterface, LoggerInterface, and HttpClientInterface expectations that Laravel satisfies with different concrete classes:
$this->app->bind(
\Symfony\Contracts\HttpClient\HttpClientInterface::class,
fn () => \Illuminate\Support\Facades\Http::getFacadeRoot() // only if the package tolerates it
);
More often than not it is cheaper to hand-wire the two or three services the package truly needs than to mass-register its container config.
Pattern 3 — Wrap behind your own interface. For anything touching I/O (HTTP, filesystem, cache), define a thin interface in your app and let the package be one implementation. This is the single highest-value habit with a v1 Symfony package: it caps your blast radius if the package is abandoned or breaks its API in v2.
interface DocumentConverter
{
public function convert(string $path): string;
}
Then bind the package adapter to it. Your domain code never imports the vendor namespace.
Testing. With no Laravel integration layer, RefreshDatabase and HTTP fakes may not reach the package's internals. Prefer unit tests that hit the package directly with fixture inputs, plus one integration test proving your container binding resolves. If the package makes outbound HTTP calls, check whether it accepts a PSR-18 client in the constructor — that is your seam for Http::fake() equivalents or a stub client.
Config placement. Do not publish a package config file if one exists and you are unsure of its stability. Keep your own settings in config/services.php under a single key and pass values into the constructor explicitly. This makes the upgrade path from v1 → v2 a one-file diff.
The Symfony 6 floor is the whole release note. "Symfony 6 or higher" is unusually broad — it implies ^6.0 || ^7.0 or similar. Verify this directly in composer.json. If the constraint is ^6.0 only, you are locked out of Symfony 7 and therefore out of Laravel 12+ when it moves. That is a forward-compatibility trap worth knowing about on day one, not on upgrade day.
Version 1 means no deprecation policy yet. Nothing in this release tells you what the author considers public API. Assume everything is public, and wrap accordingly. There is no BC promise to rely on, so the defensive posture in the patterns above is not paranoia — it is the correct read of a v1 with a one-line changelog.
Symfony vs. Laravel container semantics. Laravel's container resolves by class name with automatic constructor injection, but it does not honor Symfony's autoconfigure, autowire attributes, or tagged iterators the way Symfony's compiler pass does. If the package relies on tags (kernel.event_listener, monolog.logger, custom tags), those tags are simply invisible to Laravel. Symptoms: silently missing behavior, no exception, no log line — the listeners just never fire. If the package does anything event-driven, test that the code path actually executes rather than assuming registration succeeded.
Symfony\Component\HttpFoundation vs. Laravel's Request. Laravel's Illuminate\Http\Request extends the Symfony request, so passing one in works. Passing a Symfony Response back out does not automatically become a Laravel response — you need to wrap it. This trips people up on packages that return HTTP objects.
Debugging an install failure. Composer conflicts with Symfony-first packages are almost always transitive. Use:
composer why-not symfony/http-foundation ^6.0
That is faster than reading the full solver output. If the conflict is laravel/framework holding you back, you are on too old a Laravel; upgrade rather than fight it.
Extension points are unproven. On a v1, do not assume the package exposes interfaces for the pieces you will want to swap — the logger, the HTTP client, the cache. Read the constructor signatures before designing around them. If a dependency is a concrete final class, you have no seam and should keep the package at arm's length behind your own wrapper interface.
Watch the release cadence before committing. A v1 with a one-line note is a signal to check the repository: recent commits, whether CI runs against Laravel's actual Symfony versions, and whether issues get responses. Adoption risk here is governance, not code.
Log the version you adopt. Because there is no changelog yet, note the exact tag in your composer.json as a pinned constraint (e.g. 1.0.0, not ^1.0) until a second release establishes a track record. Revisit after v1.1.
How can I help you explore Laravel packages today?