Ezenhancedimageassetbundle Laravel Package

Getting Started

This is a Symfony bundle for Ibexa / eZ Platform, not a Laravel package — there is no config/app.php provider entry and no Laravel service container wiring. Treat it as an Ibexa platform extension: composer require novactive/ezenhancedimageassetbundle, then register Novactive\EzEnhancedImageAssetBundle\EzEnhancedImageAssetBundle in your bundle list (config/bundles.php on modern Ibexa, AppKernel::registerBundles() on legacy skeletons).

Before anything else, verify the version-to-platform matrix, because it is the biggest source of wasted time:

• v4.x → Ibexa 5, PHP 8.3
• v3.x → Ibexa 4
• v2.x → Ibexa 3
• v1.x → older eZ Platform

Pin the major version explicitly in composer.json; the release notes are terse ("Ibexa 5 version") and give no compatibility matrix beyond that.

Where to look first. This repository is a read-only subtree split of Novactive/Nova-eZPlatform-Bundles. Do not open issues or PRs here. Read the packaged docs at https://novactive.github.io/Nova-eZPlatform-Bundles/master/EnhancedImageAssetBundle/README.md.html and file anything you find against the main repository. Also check doc/images/ for the focus-point demo GIF — it is the fastest way to understand the editor experience.

First use case. Migrate a single ezimage field on a low-traffic content type:

1. Add image variation config for a focus-aware alias plus its retina twin:

   - { name: hero, params: { size: [1200, 600], focus: [0, 0] } }
   - { name: hero_retina, params: { size: [2400, 1200], focus: [0, 0] } }
   

2. Flip the field: either edit the content type definition and re-save content, or use the documented SQL two-step (update ezcontentclass_attribute.data_type_string, then ezcontentobject_attribute.data_type_string). Note the SQL is written against the legacy table names; confirm they still exist in your Ibexa 5 schema before running it.
3. Clear cache and open the content in the admin UI. You should see the focus-point picker overlaid on the image. Drag it, publish, and confirm the generated variation on disk is cropped around the focus point.
4. Render it with {{ ibexa_render_field(content, 'my_field', { parameters: { alias: 'hero' } }) }} and include the bundle's assets:

   {{ encore_entry_link_tags('enhancedimage-css', null, 'ibexa') }}
   {{ encore_entry_script_tags('enhancedimage-js', null, 'ibexa') }}
   

If all four steps pass, the bundle is viable for your project. If step 4 throws a missing-entry error, your Encore build does not expose those entries — see Gotchas.

Implementation Patterns

Model the alias set as a pair, always. Every alias you expect to render should have a _retina sibling at exactly 2× width and height. The bundle only auto-selects my_alias_retina when the width is precisely double; anything else silently falls back to the 1× asset. Define them together in the same image_variations block so they can't drift.

Use focusedThumbnail for anything that must crop intelligently. Plain size-only filters ignore the contributed focus point. The focus: [0, 0] parameter in variation config is a placeholder — the bundle rewrites it per image at generation time. Keep it in the config for filter arity, but don't try to hardcode a real focal point there.

Standardize rendering in a Twig macro. Almost every template will want the same <picture> shape. Wrap ibexa_render_field in a project macro so alias choice, alternative sources, lazy-loading, and retina toggles are decided once:

{% macro image(content, fieldId, desktopAlias, mobileAlias) %}
  {{ ibexa_render_field(content, fieldId, {
      parameters: {
          alias: desktopAlias,
          alternativeAlias: [{ alias: mobileAlias, media: '(max-width: 767px)' }],
          lazyLoad: true,
          retina: true
      }
  }) }}
{% endmacro %}

This keeps the parameters contract — alias, alternativeAlias[].alias, alternativeAlias[].media, lazyLoad, retina — in one place when a future version changes it.

Drive behaviour per siteaccess, not globally. ez_enhanced_image_asset.default.enable_lazy_load, .enable_retina, .image_default_config, and .image_default_post_processors are all siteaccess-aware parameters. The natural split is: aggressive optimization + lazy loading on the front-end siteaccess, retina enabled, and a conservative configuration on the admin siteaccess where editors inspect the image at native resolution.

Push quality settings into image_default_config rather than per-alias. Setting quality: 80 and animated: true once at the default level means new aliases inherit sane compression; per-alias overrides then only handle genuine outliers.

Chain placeholder providers for non-production environments. The chain_provider with two remote entries (one hitting your prod storage URL pattern, one hitting placekitten) lets developers see real layout without pulling gigabytes of assets. This is the single highest-value configuration for onboarding new team members.

Use the conversion command for bulk migrations, not hand-edited SQL. ezenhancedimageasset:convert:field_to_imageasset converts image/relation fields into image asset fields. For a handful of fields the SQL is fine; for dozens, run the command, then diff the content type definitions to confirm the field type changed in both the class attribute and the object attributes.

Plan for alias regeneration in your deploy pipeline. Any change to image_variations invalidates existing aliases. A cache clear alone is not enough — you need the platform's image regenerate/resize command (name varies by Ibexa version) and, in multi-server setups, a way to purge the CDN in front of var/.

Gotchas and Tips

Encore entries are a hard dependency. enhancedimage-css and enhancedimage-js must exist in your Webpack Encore config. The bundle documentation tells you to render them but does not tell you to register them. If they are missing, you get either a build-time "entry not found" error or a silent 404 with a non-functional focus picker. Copy the entry definitions from the main repository's assets directory, or drop the script tags and accept a degraded editor experience — but decide deliberately.

The SQL migration touches two tables for a reason. ezcontentclass_attribute is the schema, ezcontentobject_attribute is the stored data. Updating only the first leaves content that cannot be loaded; updating only the second leaves the admin UI showing the old field type. Run both statements in one transaction per content type, then clear cache, then spot-check one content item in the admin before moving on. Version v1.6.2 specifically fixed "saving focuspoint without modifying the image" — if you are on anything older, editors will lose focus points on unchanged re-publishes.

Retina and focus have interacted badly before. v1.1.1 fixed focus points not being applied when a retina variation existed. If you see a retina alias cropped at centre while the 1× alias is cropped correctly, you are on an old patch release. Always pin at or above the fixes you need.

Post-processors must be installed on the server. pngquant, jpegoptim, and friends are external binaries. If jpegoptim is absent, alias generation will either skip the processor or fail depending on your version — v1.0.1 addressed placeholder generation when no post-processor is installed. Verify binary presence in your container image, not just in composer.json.

Debugging alias output. When a variation looks wrong, work outward: (1) check the raw variation generated under var/ — if it is already mis-cropped, the problem is the filter/focus config, not Twig; (2) dump the resolved variation config with the platform's config debug command to confirm your YAML was actually loaded (siteaccess scoping silently swallows parameters defined in the wrong block); (3) inspect the rendered <picture> markup to see which alias and sources were selected; (4) only then touch templates.

Cache layers stack. Ibexa caches variation config, HTTP caches the <picture> markup, and the browser caches the images themselves. After a variation change, clear all three or you will "fix" the same bug three times.

Extension points worth knowing. The field view template is overridable through the standard Ibexa theme override mechanism — copy the bundle's template into your theme and adjust markup rather than patching the vendor directory. The image placeholder provider is configurable and chainable, which is the cleanest hook for custom placeholder logic. Beyond that, the bundle is thin: it extends ezimage, so all your existing ezimage-specific template branches ({% if field.fieldTypeIdentifier == 'ezimage' %}) will stop matching. Grep your templates for ezimage before you migrate anything.

Assess the support risk honestly. One star, zero dependents, a single vendor, and release notes that are mostly bare "Full Changelog" links. That is not disqualifying for a focused bundle, but it means: pin the exact version, read the diff between release tags rather than trusting the changelog, keep a fork path open, and avoid adopting it for content types you cannot afford to migrate again. Budget time to read the source in Novactive/Nova-eZPlatform-Bundles — the subtree split gives you code but no history, so git blame and PR context are only available upstream.