Symfony Pro Backup Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. Release 0.1.0 is the first tagged version and its headline change is PHP 8.5 / Symfony 8 support, so treat everything below as "read the source before you wire it in."

Minimal path to a first backup:

1. composer require raffaelecarelle/symfony-pro-backup-bundle:^0.1
2. If you are in a real Symfony app, register it in config/bundles.php; in Laravel there is no auto-discovery, so you'll add a small service provider that binds the bundle's services manually (see Gotchas — this is the main friction point).
3. Publish/copy the bundle's default config (typically config/packages/<bundle_alias>.yaml) and set the storage destination and the sources you want to back up.
4. Run the bundle's console command once by hand (bin/console list / php artisan list after registering it) before scheduling anything.

Where to look first:

• src/ for the command classes and the main backup service — that service is what you'll call from your own code.
• The bundle's DependencyInjection/ directory for the actual config keys and their defaults. The README is likely thin at 0.1.0; the Configuration.php is the source of truth.
• composer.json for the symfony/* constraints — see the Gotchas section, this matters more than usual in a Laravel app.

First useful use case: a nightly database dump to local/S3 disk, run manually once, then scheduled. Everything else (retention, multi-destination, notifications) can wait until that loop is proven.

Implementation Patterns

Wrap, don't scatter. Register one thin application-level service (e.g. BackupRunner) that resolves the bundle's backup service and exposes two methods: run(string $profile) and runAsync(string $profile). Your commands, jobs, and tests talk to that wrapper, so an upgrade that renames the underlying service only breaks one file.

Scheduling. In Laravel, don't try to reuse the bundle's scheduler hooks — call your wrapper from routes/console.php / the kernel:

Schedule::call(fn () => app(BackupRunner::class)->run('daily'))
    ->dailyAt('02:30')
    ->withoutOverlapping()
    ->onOneServer();

withoutOverlapping() and onOneServer() are non-negotiable here: a long backup that overlaps itself is the classic way to fill a disk.

Queue the heavy part. Backups are I/O-bound and slow. A ShouldQueue job that calls the wrapper keeps the HTTP/scheduler path fast, and gives you retries and failed-job visibility for free. Set an explicit $timeout above your longest observed run.

Profiles over config branching. Define named profiles (e.g. db, uploads, full) in the bundle config and select by name from your wrapper rather than mutating config at runtime. It keeps the config file the single place a new backup target is declared.

Storage via the adapter/stream layer. If the bundle exposes a filesystem abstraction, point it at the same disk you already use for Storage::disk() in Laravel so retention and monitoring tooling is shared. If it only ships a local-disk implementation, write a small adapter against the package's interface rather than copying files around in your own code.

Post-run hook. Every backup should emit something you can observe. Even if the bundle has no events yet at 0.1.0, have your wrapper return a result object (path, size, duration, success) and log it plus a metric. When the bundle later adds events/subscribers, you replace the log call and nothing else.

Gotchas and Tips

• Symfony 8 constraint vs. Laravel's pinned Symfony components. Laravel 11/12 pin symfony/* in the ^7.x range. A bundle that requires Symfony 8 components will either fail composer update outright or pull a parallel set of Symfony packages and produce subtle runtime breakage. Check composer why symfony/console before installing, and if it conflicts, run the backup work in a separate small Symfony app or a container/sidecar rather than fighting the resolver inside your Laravel monolith.
• No Laravel auto-discovery at 0.1.0. You will be hand-wiring: registering the bundle's extension, binding the backup service, and mapping the config array into whatever the service expects. Do this in a dedicated provider and keep it under test — this is the file most likely to break on a patch release.
• Pre-1.0 means no BC promise. 0.1.0's only change is platform support, which tells you the public surface is still moving. Pin to ~0.1.0 (not ^0.1), commit composer.lock, and read the diff of every bump before merging. Namespace, service IDs, and config keys are all fair game for renaming.
• Config key mismatch is the #1 silent failure. Bundle config is nested under the bundle alias (e.g. <alias>:), and Symfony's config tree silently ignores unknown keys by default. If your backup writes to the wrong disk or skips a source, dump the resolved config (debug:config <alias> in Symfony, or var_dump your mapped array in Laravel) instead of re-reading the YAML.
• Debug runs with full verbosity. -vvv on the console command is where the bundle is most likely to tell you what actually failed (permission denied on the temp directory, dump binary not found, etc.). Most "backup succeeded but file is 0 bytes" reports are a missing mysqldump/pg_dump binary in the PHP-FPM user's PATH.
• Extension points to plan for. Custom storage backends, custom dumpers, and post-backup subscribers are the three things you will want. If the bundle doesn't expose tagged-service interfaces for them at 0.1.0, isolate the corresponding logic in your own layer now so adopting the official hook later is a swap, not a rewrite.
• Test against a fake filesystem. Assert the wrapper produces a file at the expected path on an in-memory/stub disk, and separately assert the failure path (dump command returns non-zero) surfaces as a failed job rather than a silently empty archive.