Image Bundle Laravel Package

Getting Started

The package is a Symfony 2-era bundle with no dependents and a bare-minimum README, so treat the source as the authoritative docs. Budget 15 minutes to read three files before writing any code:

1. DependencyInjection/Configuration.php — the exact YAML root key and options (dimensions, quality, driver, cache path).
2. Resources/config/services.xml — the service IDs you'll inject.
3. Any Twig/ or Helper/ directory — to see if a filter or helper is exposed.

Installation:

composer require paradigmate/image-bundle

Because this is a Symfony 2 bundle, pin a known-working version rather than dev-master, and verify the symfony/symfony constraint in the bundle's composer.json before assuming it works on 2.8 vs 3.x.

Register the bundle in app/AppKernel.php:

$bundles = [
    // ...
    new Paradigmate\ImageBundle\ParadigmateImageBundle(),
];

Add minimal config in app/config/config.yml (fill in from Configuration.php):

paradigmate_image:
    # driver: gd   # or imagick
    # cache_dir: %kernel.root_dir%/../web/uploads/cache

First use case: resizing an uploaded avatar into a thumbnail inside a controller.

$resizer = $this->get('paradigmate_image.resizer'); // verify ID from services.xml
$resizer->resize(
    $file->getPathname(),
    $targetPath,
    128, 128
);

Confirm the service exists with php app/console container:debug paradigmate before wiring it into anything else.

Implementation Patterns

Service injection over container access. Once you know the service ID, inject it via services.yml (or services.xml) rather than calling $this->get() in every controller. This keeps the resizer swappable and makes tests straightforward.

Upload + resize workflow. The common pattern is a two-step pipeline: move the uploaded file to permanent storage, then create a resized derivative alongside it. Doing both in one controller action is fine for low-traffic apps; extract into a dedicated ImageUploader service once you have more than two call sites.

Twig usage. If the bundle ships a Twig extension (check for a Twig/ folder), register it and use the filter for rendering-time thumbnails. If it does not, generate derivative URLs at upload time and store them on your entity — this avoids a resize call per page view.

Integration with existing upload flows. Wrap the resizer behind a small interface (ImageProcessor::thumbnails(File $file): array) so you can plug in LiipImagineBundle later without touching controllers. Given the project's low activity, that migration is likely.

Batch processing. For galleries or import jobs, call the resizer from a console command and stream file paths rather than loading all images into memory at once. The bundle has no queue integration, so you own concurrency and retries.

Caching derivatives. Generate the resized file once at a deterministic path (/uploads/cache/{id}/{w}x{h}.jpg), check file_exists() before calling the resizer, and serve via a static route or web server rewrite. This is the single biggest performance win and the bundle does not provide it for you.

Gotchas and Tips

Symfony version drift is the main risk. This is a Symfony 2 bundle with zero dependents. Expect it not to install cleanly on Symfony 3+. If you're on a modern stack, treat this as a reference implementation and copy the resizing logic into a standalone service rather than fighting the bundle registration.

GD vs Imagick. Most older resizers default to GD. Check that the gd PHP extension (with jpeg/png support) is compiled in — php -m | grep gd. Imagick handles transparency and EXIF orientation better; if the bundle supports both, prefer Imagick for user uploads.

Memory limits. GD loads the entire decoded image into memory. A 12MP JPEG can consume ~48MB before resizing. Set ini_set('memory_limit', '256M') around the resize call, or reject uploads above a pixel threshold.

EXIF orientation is almost certainly not handled. Phone photos will appear rotated after resize. Rotate before scaling, using exif_read_data() plus imagerotate() in your own wrapper.

Path handling. Older bundles often expect paths relative to web/ or absolute filesystem paths inconsistently. Log the exact path being passed on the first failure; the exception message is usually vague.

Silent failures on unsupported formats. Verify the return value of the resize call and check the output file actually exists and is non-zero. Wrap in try/catch and surface a domain-level exception in your own code.

Debugging. Start with php app/console container:debug paradigmate_image to list every service the bundle registers. If a Twig filter is missing, check container:debug twig.extension for a lazy-loaded extension that isn't tagged.

Extension points are minimal. If you need watermarking, focal-point crops, or WebP output, plan to wrap the service rather than extend the bundle classes. The abstraction is thin, and subclassing old bundles tends to couple you to internals.

Evaluate alternatives early. For any non-trivial image requirement, LiipImagineBundle provides a maintained, filter-based API with caching and Twig integration. Use this bundle only if you need something trivially small and are already on Symfony 2.