Image Bundle Laravel Package

Getting Started

This is a small, low-adoption Symfony bundle (24 stars, 0 dependents) built for the classic "upload + resize + display" flow. Treat it as a focused helper, not a full media library. v5.1.1 is a dependency-compatibility release, not a feature release — there is no new API to learn, but the install story changed slightly in your favour.

1. Install and register

   • composer require presta/image-bundle
   • Register in config/bundles.php (or AppKernel on legacy apps). Because the bundle predates Symfony Flex, expect to add the bundle entry manually and to import its routing/config only if the docs say so.
   • v5.1.1 note: the bundle now permits vich/uploader-bundle 3.x (PR #104). If your app is already on Vich 3, v5.0.0 would have blocked resolution — go straight to 5.1.1. If you are still on Vich 2.x, either upgrade Vich first or pin presta/image-bundle:5.0.*; do not mix (see Gotchas).
   • Check the symfony/* constraints against your Symfony version first. Vich compatibility is now solved; Symfony major compatibility is still the single biggest go/no-go signal.

2. Configure the upload target

   • Publish/import the bundle config and set the filesystem root and public web path (typically upload_dir / upload_root style keys). If the bundle ships a Configuration.php, read it — it is the authoritative reference since documentation is sparse.
   • Because uploads are delegated to Vich, you now have two config surfaces: the bundle's upload root and Vich's mapping/uri_prefix. Keep them pointed at the same physical directory or you will debug a broken image for an hour.
   • Make sure the web-visible directory exists, is writable by PHP, and is reachable by your assets pipeline.

3. First use case — a single image field on an entity

   • Add an image property + filename column to your entity, and annotate/attribute it as a Vich uploadable field.
   • Use the bundle's ImageType form field instead of a raw FileType. It bundles the preview, the "delete/replace" affordance, and the resize call in one widget.
   • In the controller, after $form->handleRequest() and $form->isValid(), let the uploader move the file and the bundle's image manager produce resized variants, then set the resulting filename on your entity and flush.

4. Render it

   • Store the generated filename on your entity and build the public URL from the configured upload directory. If the bundle exposes a Twig helper or a cache resolver, prefer that over hand-built paths so resize presets stay consistent.

Where to look first: DependencyInjection/Configuration.php, the ImageType class, and the image manager service. Those three files define the whole contract.

Implementation Patterns

Standard upload flow (entity-backed image)

• Form: ImageType with options for preview sizing and delete label.
• Controller: persist the entity first if you need an ID for the filename, or let Vich generate a UUID/hash name.
• Manager: call the bundle service (e.g. presta_image.manager) to move/resize the temp file into the upload root.
• Persist only the relative filename on the entity — never the absolute path or full URL. This keeps the record portable across environments.

Letting Vich own the lifecycle (the v5.1.x-friendly pattern)

• Since 5.1.1 you can run Vich 3.x for the uploadable/annotation side and treat Presta purely as the presentation layer: Vich stores the file and the filename, Presta renders the form widget and generates thumbnails from a named filter set.
• This is the cleanest split if you already use Vich elsewhere in the app — one uploader contract across all entities, with Presta as an optional image-front-end rather than a second upload mechanism.
• Watch the annotation/attribute syntax: Vich 3 moved to PHP attributes and dropped some legacy annotation support. If your entities still use @Vich\Uploadable, the 3.x upgrade is the real work, not the Presta bump.

Remote image ingestion

• The bundle's selling point is that it also accepts a URL. Pattern: one form field that takes either an upload or a remote URL; the manager downloads, validates, and resizes into the same upload directory.
• Always gate remote fetching behind an allowlist or a scheme check (http/https only) and a size/time limit — see Gotchas.

Resize presets rather than ad-hoc dimensions

• Define named sizes/filters in config (thumbnail, medium, hero) and reference them from forms/templates. Ad-hoc width/height calls scattered through controllers are the fastest way to get inconsistent crops across an app.
• If the bundle delegates to Imagine filters, keep the filter set in one YAML block so designers and backend devs share a vocabulary.

Multiple image fields / collections

• For galleries, embed the image type in a CollectionType and let each child own its filename. The bundle handles one image per field; it is not a gallery manager, so keep the collection/ordering logic in your own entity.

Deletion and replacement

• Implement delete as an explicit checkbox in ImageType (if supported) or as a separate action. On delete: remove the DB reference, then unlink the stored file — and ideally the cached resized variants too. With Vich in play, use its listener rather than hand-rolled unlink so both layers agree on what was removed.
• On replace: write the new file, update the filename, then clean up the old file after the flush succeeds to avoid losing the image if the transaction rolls back.

Integration tips

• Wrap the manager call in a small application service (e.g. ImageUploader) so controllers stay thin and you can unit-test the flow without the form.
• Store an updatedAt on the image or entity and append it as a cache-busting query string to image URLs — the bundle's cache resolver won't always invalidate regenerated thumbnails.

Gotchas and Tips

• Symfony-only — not a Laravel package. This is a Symfony bundle; there is no service provider, no facade, no Laravel-side config publishing. If your stack is Laravel, use Intervention Image or Glide and treat this as reference reading only. The v5.1.1 release does nothing to change that.
• Vich version pairing is a hard constraint. 5.1.1 allows Vich 3.x; 5.0.0 did not. Pick a lane deliberately: Presta 5.1.1 + Vich 3.x is the forward path, but it drags in Vich 3's annotation→attribute migration. Presta 5.0.x + Vich 2.x is the low-effort path but freezes you out of Vich 3 adopters' fixes. Document the pairing in your composer.json comment or upgrade notes.
• Maintenance risk is still real. One dependency-bump release with 24 stars and 0 dependents means very little community testing against modern Symfony. It's a positive signal that the bundle is alive in 5.1.x, not a signal that it's battle-tested. Wrap it behind your own interface so it's swappable.
• SSRF via remote images. Any "fetch this URL" feature is an attack surface. Block private IP ranges, restrict to http/https, cap redirects, set timeouts, and validate the response Content-Type before handing bytes to Imagine.
• Filesystem permissions and paths. Upload failures are almost always a 0775 vs 0777 issue or a mismatch between the configured web path and the real document root — now more likely, because two config surfaces (Vich + Presta) must agree. Log the resolved absolute path on failure; the bundle's exceptions are often terse.
• Cache staleness. Resized variants are written once and served forever. If you regenerate or replace an image, the old cached thumbnail can persist. Either version the filename or append ?v=<timestamp> to URLs.
• Imagine driver dependency. The bundle relies on Imagine and therefore GD or Imagick. Confirm the extension is installed and that the driver matches production; GD and Imagick disagree on transparent PNGs and EXIF orientation, so test with real photos, not solid-color squares.
• Silent no-ops on invalid uploads. ImageType may swallow a failed upload and leave the field empty rather than erroring. Always assert after handling the form that the expected filename is non-null when the field is required.
• Config quirks. YAML booleans and trailing slashes matter: upload_dir: uploads/ and upload_dir: uploads can resolve differently. Use absolute paths for the filesystem root and relative paths only for the public URL.
• Extension points. The image manager service is the intended seam — decorate or override it to add virus scanning, watermarking, or CDN upload without forking the bundle. The ImageType can be extended via form type extensions if you need extra validation.
• Debugging tip. When an image doesn't appear, check in this order: DB filename set → file exists on disk at the resolved path → Vich's uri_prefix matches the real document root → URL reachable in the browser → cache variant generated. Most "broken image" reports stop at steps two or three.