Super Uploader Bundle Laravel Package

Getting Started

First, a framing note: santeacademie/super-uploader-bundle is a Symfony bundle, not a Laravel package. It will not auto-register via Laravel's package discovery, and its service wiring assumes the Symfony DI container. Day-to-day use in a Laravel app means either (a) running it inside a Symfony service container you boot yourself (heavy), or (b) reading it as a reference implementation and porting the upload logic. If your team is Laravel-only, confirm the requirement before committing — intervention/image, spatie/laravel-medialibrary, or a Uppy + signed-URL flow will usually be less friction.

If you do proceed (Symfony app, or a Laravel app with a Symfony subsystem):

1. composer require santeacademie/super-uploader-bundle:^3.3
2. Register the bundle in config/bundles.php:

   SanteAcademie\SuperUploaderBundle\SuperUploaderBundle::class => ['all' => true],
   

3. Copy/import the bundle's default config (config/packages/super_uploader.yaml) and set at minimum the storage path/root and any allowed MIME types.
4. Publish/install the front-end assets (the bundle ships an uploader UI) — check the bundle's Resources/public or asset-mapper instructions.
5. First use case: a single-file, single-entity upload (e.g. a user avatar) through the bundle's upload endpoint, persisted onto an entity property, and read back in a Twig template. Get that end-to-end before touching chunked/multi-file uploads.

Where to look first: the bundle's DependencyInjection/Configuration.php (the authoritative list of config keys), then the controller handling the upload route, then the JS entry point.

Implementation Patterns

v3.3.0 is a compatibility release. The only functional change is Symfony 7.4 support (plus the v3.2.2 release commit). No API changes, no deprecations, no config keys added or removed. Treat it as a drop-in composer update — the assessment below is unchanged from v3.2.x behaviour.

• Entity-owns-file pattern. Attach the uploader to a Doctrine entity property and let the bundle manage the lifecycle (persist on upload, delete on entity removal). Keep the entity field nullable and store the resolved filename/path, not a stream — this keeps serialization and fixtures simple.
• Custom storage adapter. If you're not writing to local disk, implement the bundle's storage interface as a service and alias it in config. This is the cleanest extension point and the one you're most likely to need (S3/Flysystem, GCS, etc.).
• Two-phase upload for large files. Use the bundle's chunked/async flow: client uploads, server returns a token/identifier, then a second request binds that temp artifact to the entity. This decouples "upload succeeded" from "entity saved" and avoids orphaned files on validation failure.
• Validation in two places. Enforce size/MIME both client-side (fast feedback) and server-side via the bundle's validator constraints — never trust the client hint, especially the declared MIME type.
• Laravel integration tip (if unavoidable). Bind the bundle's services into Laravel's container manually, or wrap the upload handler in a thin Laravel controller that delegates to the bundle service. Don't try to use the bundle's Symfony routes directly inside a Laravel app — CSRF and session handling won't line up.

Gotchas and Tips

• Symfony version constraint is the thing to check. "Symfony 7.4 compatibility" means the bundle now permits ^7.4 in its composer.json. If your app is pinned to 7.3 or below, this release changes nothing for you; if you're upgrading to 7.4, this is the release that unblocks you. Run composer why-not santeacademie/super-uploader-bundle if the update is refused.
• No Laravel package discovery. You must register the bundle manually in a Symfony kernel, or wire services by hand. Expect to write glue code; budget for it.
• Config key drift between minor versions. Cache-clearing after config changes is mandatory (bin/console cache:clear, or php artisan config:clear for a mirrored config). A stale container is the most common cause of "my storage adapter is ignored."
• Temp-file orphaning. Uploads that never get bound to an entity leave files behind. Add a scheduled cleanup over the temp upload directory — the bundle generally won't do this for you.
• CSRF and session on the upload endpoint. In Symfony, ensure the upload route is inside the firewall or explicitly CSRF-exempt with an alternative token; in a Laravel port, use the web middleware group or a signed URL. Mismatches here surface as silent 419/403s with no server-side log entry.
• Asset caching. After upgrading, bump your asset version / clear the compiled asset cache, otherwise the old JS keeps POSTing to a route signature that changed.
• Extension point to prefer: the storage adapter interface, then the file-naming/validation services. Avoid subclassing the upload controller — it's the least stable surface across releases.
• Debugging tip: log the resolved storage path and the temp identifier at each phase. Most reported "upload silently fails" issues are a path/permissions problem, not bundle logic.