Image Bundle Laravel Package

Getting Started

Install with Composer:

composer require small-team/image-bundle

This is a Symfony 2 bundle, so registration is manual. Add it to app/AppKernel.php:

public function registerBundles()
{
    return array(
        // ...
        new SmallTeam\ImageBundle\ImageBundle(),
    );
}

Then expose the bundle config in app/config/config.yml under the extension alias (check DependencyInjection/Configuration.php for the exact root key — typically image_bundle: or small_team_image:). At minimum you will likely need to set a cache/output directory:

image_bundle:
    cache_dir: %kernel.root_dir%/../web/media/cache

Clear the cache (php app/console cache:clear) and verify the bundle's services are registered:

php app/console container:debug | grep -i image

Where to look first:

1. DependencyInjection/Configuration.php — the authoritative list of every config key and default.
2. Resources/config/services.yml (and any *.xml) — the service IDs you can inject.
3. Resources/views/ and any Twig/ directory — Twig filters/helpers shipped with the bundle.
4. Resources/doc/ — if a README is missing, this is usually the only usage documentation.

First use case: resizing a user-uploaded image. In a controller, grab the relevant service from the container (or inject it), point it at the uploaded file's absolute path, request a size, and write to a public web path:

$image = $this->get('image_bundle.manager'); // confirm ID via container:debug
$image->open($uploadedFile->getPathname())
      ->resize(320, 240)
      ->save($webDir . '/uploads/thumb_' . $uploadedFile->getClientOriginalName());

If the bundle provides a Twig filter, the equivalent template usage is typically:

<img src="{{ asset('uploads/photo.jpg') | image_resize(320, 240) }}">

Confirm the filter name with php app/console debug:twig (or twig:debug on your Symfony 2.x patch level).

Implementation Patterns

Service injection over container lookups. The bundle is small enough that get() calls work, but wiring the manager into your services via constructor injection is what you want for anything beyond a single controller. Define your own service in Resources/config/services.yml with the bundle's service ID as an argument:

services:
    app.image_pipeline:
        class: AppBundle\Service\ImagePipeline
        arguments: ['@image_bundle.manager', '%kernel.root_dir%']

Wrap it in an application-level service. For day-to-day work, the bundle's raw API is thin. Build one ImagePipeline class that owns naming, output paths, quality, and cache-busting, so controllers and Twig stay clean and you have one place to swap implementations later (see Gotchas — you probably will).

Thumbnail-on-upload flow. The most common integration point is a Doctrine entity listener or form handler after a file upload:

public function postPersist(LifecycleEventArgs $args)
{
    $entity = $args->getEntity();
    if (!$entity instanceof Photo) {
        return;
    }
    $this->pipeline->generateThumbnails($entity->getImagePath());
}

Keep generation synchronous for small images; for anything user-uploaded and large, push to a queue (Symfony 2 era: oldsound/rabbitmq-bundle or a EnqueueBundle-style worker) so a slow Imagick call doesn't block the request.

Store variants, don't overwrite sources. Treat the original as immutable and write derivatives to a cache directory with a deterministic name ({sha1(path)}_{width}x{height}.{ext}). This makes regeneration idempotent, gives you free cache-busting, and — critically with this bundle — lets you delete the whole cache directory safely.

Twig-side responsive variants. If the bundle exposes a filter, compose it with Symfony's asset helper:

{% set sizes = [320, 640, 1280] %}
<img
  src="{{ asset(photo.path) | image_resize(640) }}"
  srcset="{% for s in sizes %}{{ asset(photo.path) | image_resize(s) }} {{ s }}w{% if not loop.last %}, {% endif %}{% endfor %}"
  alt="{{ photo.alt }}">

Integration with admin generators. If you're on Sonata Admin or EasyAdmin (Symfony 2 era: Sonata), use the bundle only inside the admin's file field rendering and keep generation in an entity listener. Don't put resize logic in admin templates — it makes tests and CLI regeneration impossible.

Batch regeneration command. Add a console command (app/console app:images:regenerate) that walks your entities and re-runs the pipeline. This is the single highest-value thing you can build around this bundle: it turns "our thumbnails look wrong after we changed sizes" from an incident into a 30-second fix.

Testing. Mock the bundle's service in unit tests rather than hitting GD/Imagick. For integration tests, use tiny fixture images (1×1 or 10×10 PNG) and assert on output dimensions with getimagesize().

Gotchas and Tips

Treat this as legacy. Plan the exit. Last release 2018-12-25, 1 star, 0 dependents. It is a Symfony 2 bundle, and Symfony 2 has been end-of-life since 2019. There is effectively no upstream maintenance, no security response process, and no one to ask when it breaks. Use it if you're already on Symfony 2 and it solves your problem today, but budget for replacement. liip/LiipImagineBundle (the de facto standard, and it has a Symfony 2 branch) or a direct Imagine/Glide integration are the realistic migration targets. Isolate every call behind your own ImagePipeline service so the swap is a one-file change.

Bundle registration is not Flex-friendly. There is no config/bundles.php support and no recipe. On Symfony 2, add to AppKernel. If you're attempting this on Symfony 3/4, expect services.yml to fail to load, deprecated kernel.root_dir assumptions, and missing autowiring — don't. Stay on Symfony 2.x semantics or don't use the bundle.

PHP version constraints bite first. A 2018 package may declare php: >=5.3 but use syntax or dependency versions that break on PHP 7.3+. Check composer.json require before installing; run composer why-not if it conflicts with your Symfony version. If Composer refuses to install, do not use --ignore-platform-reqs in production — it masks real runtime incompatibilities.

Extension availability. Image code paths depend on either GD or Imagick. Verify with php -m | grep -iE 'gd|imagick' and check that the chosen backend is configured. Imagick is more capable but its policy.xml can silently refuse PDFs and large images; GD is nearly always present but has lower memory ceilings. The bundle's config usually picks one — confirm which and standardize across dev, CI, and production images.

Memory and Allowed memory size exhausted. Resizing a 12MP JPEG can need ~200MB in GD. Set memory_limit generously for the process that does image work rather than globally, and cap input dimensions before processing (getimagesize() first, reject anything above your limit). This is the most common production failure with image bundles of this vintage.

Filesystem permissions and path handling. The cache/output directory must exist and be writable by the web user (www-data/nginx). The bundle likely resolves paths relative to the web root or a configured dir; passing absolute paths where it expects relative (or vice versa) produces confusing failed to open stream errors. Log the resolved absolute path once during setup and confirm it matches what you expect. In dev, cache:clear may wipe generated images if you point the output dir inside app/cache — always write to web/ or a dedicated media dir.

Overwriting originals. Some usage examples save back over the source file. Don't. You lose the original, and repeated resizes compound JPEG artifacts. Always read source, write derivative to a new path.

Debugging steps that actually work: container:debug to get the real service ID (the alias often differs from what docs claim); debug:twig for filter names; then drop to a standalone PHP script that calls the underlying library (Imagine/GD/Imagick) directly with the same file to determine whether the failure is in the bundle wiring or the image operation itself.

Extension points are limited. Realistically you have three: config values exposed by Configuration.php, decorating/overriding the bundle's services in your own services.yml (same ID, your class — works but silently breaks on any bundle update), and the Twig filter namespace if it registers one. There is no event system worth hooking. If you need behavior the bundle doesn't expose, don't fight it — wrap it or replace it.

No tests, no CI, no changelog. Read Resources/config/services.yml end to end before relying on any documented behavior; the code is the spec. Pin the exact version in composer.json (no ^), and vendor-lock it, because there will be no patch releases to bail you out.