File Bundle Laravel Package

Getting Started

• Confirm the runtime fit first. v1.1.0 requires PHP 8.4+ and Symfony 6.4 / 7.0 / 8.0, with Doctrine ORM 2.19+ or 3.0+. That PHP floor is the first thing to check against your base images and CI images — it is not an 8.1/8.2 package.
• Know what you're installing. Despite the Laravel framing, this is a Symfony bundle, not a Laravel package. There is no service provider, facade, or config/*.php publish step. composer require will not auto-wire anything into a Laravel app. Before investing time, decide which of these you actually are:
  1. A Laravel shop that also runs a Symfony service (queue worker, export service, admin sidecar) — install there.
  2. A pure Laravel stack — you cannot register the bundle; evaluate the underlying file-operation approach instead (see below).
• Where to look first: composer.json for the real constraints, then the bundle class and its DI extension (the config tree lives there), then the README/config reference for the bundle's config key. The file-operation code is the part that changed in this release — find it and read it before wiring anything.
• First use case: anything where a silent unlink or failed write currently goes unnoticed — temp file cleanup, export/artifact generation, cache pruning. The headline change in 1.1.0 is that these failures are now logged with clearer checks, so the fastest win is wiring the bundle into a path where you already suspect failed deletes are being swallowed.

Implementation Patterns

• Symfony-side (canonical usage): register the bundle in config/bundles.php, configure it under its key in config/packages/*.yaml, and consume its services via autowiring. Keep the config in one place per environment — the bundle's config tree is the main extension point.
• Laravel sidecar pattern: if your Laravel app needs this behaviour, run the Symfony service as a separate deployable (HTTP or shared queue) and have Laravel dispatch a job to it. File operations then live in exactly one codebase, which is the only way the logging improvements stay useful.
• Shared-filesystem discipline: if Laravel and the Symfony service touch the same volume or disk, define one abstraction (stream wrapper or a thin client) and don't let both apps delete the same paths. The new failure logging will otherwise produce two contradictory stories about the same file.
• Log bridging: the improved error messages only help if they reach your aggregator. Route the Symfony service's Monolog to stderr and ship it into the same pipeline as your Laravel logs, tagged by service, so a failed unlink shows up next to the job that triggered it.
• Replicating the hardening in Laravel-only code: check the return value of unlink() and file_put_contents() explicitly, log the path plus error_get_last(), and treat false as a real failure rather than a best-effort miss. That is the substance of this release regardless of framework.
• CI parity: the package now tests on PHP 8.4/8.5. Mirror that in your pipeline if you run its test suite or vendor it into a service you deploy — otherwise you're validating a matrix the maintainer no longer targets.
• Dependency governance: if you run the bundle's tests in your own CI, pin twig/twig to >= 3.27.1 in dev to inherit the sandbox fix.

Gotchas and Tips

• PHP 8.4+ is a hard floor. Container base images, shared CI runners, and any local dev VMs need bumping. A minor version bump that silently raises the minimum is the most common way this update breaks a pipeline.
• Symfony 8 support is brand new. It's listed as added, not battle-tested. If you're on 6.4 or 7.0, stay there and treat 8.x as something to smoke-test on a branch before committing.
• The Twig CVE fix is dev-only. The advisory (CVE-2026-46639 and related sandbox issues) is addressed in a dev dependency. This release does not patch production installs — audit your own twig/twig constraint separately, especially if you render user-supplied or semi-trusted templates through the sandbox.
• "Clearer checks" is a behaviour change. Code that previously tolerated a failed unlink may now log (or surface) an error where it was silent. Grep your callers for best-effort deletes before rolling out, and watch log volume in the first week.
• Doctrine ORM 2.19+ / 3.0+. ORM 3 removed a lot of legacy surface; if you're pinned below 2.19 you'll need a bump, and if you're crossing into 3.x do it as its own change, not bundled with this upgrade.
• No deprecations and no upgrade guide. It's a semver-minor with no API break, so the upgrade is low-risk — but read the diff of the file-operation code yourself, since that's where the only behavioural change lives.
• Extension points are Symfony-shaped. The config tree and DI extension are the hooks. There is nothing Laravel-native to extend; if you need Laravel-side behaviour you decorate Symfony services on the sidecar or reimplement the pattern locally.
• Bottom line for a Laravel team: update if you already run this bundle anywhere, primarily for the file-operation hardening and the Symfony 8 runway. Do not adopt it as a way to get file handling into a pure Laravel app — copy the pattern instead.