By gausarts on
Change record status: 
Published (View all published change records)
Project: 
Blazy
Introduced in branch: 
4.0.x
Introduced in version: 
4.0.0
Description: 

Table of Contents

Notable 4.x Changes

Blazy 4.x introduces architectural refinements, service decoupling, namespace
reorganization and improved forward-compatibility patterns. Several legacy
services, properties, and shorthand methods deprecated in 3.0.18 are now
removed or scheduled for removal.

Blazy 4.x Revamp, Deprecation and Removal Window

  • Marked deprecated in 3.0.18 and 4.0.0.
  • Removed in 4.0.0 or 5.0.0 at the latest.
  • Anything marked @internal or considered so may immediately
    apply to encourage smooth 4.x revamp.
  • Any potential BC misses may be fixed or refined along the revamp; however
    these are not crucial since we aim for D12 maximum FC.

1. Service & Infrastructure Deprecations

Core Service Separation

  • @blazy and @blazy.manager.base are decoupled
    from @blazy.base.
  • The @blazy service now contains core infrastructural services
    shared across the Blazy ecosystem.
    • Static methods were deprecated and moved to
      \Drupal\blazy\BlazyApi since 3.0.18.
    • Core services are accessed via the $core property.

@blazy.manager Deprecations

Before (3.x)

BlazyManager::getBlazy(...);

After (4.x)

BlazyManager::view(...);

@blazy.base and @blazy.config Deprecations

  • Deprecated in 3.0.18 and 4.0.0.
  • Removed in 4.0.0 or 5.0.0 at the latest.
  • If extending @blazy.base, use @blazy.manager.base instead.
  • If calling @blazy.config, use @blazy instead.

Methods were moved into and aliased through:

  • BlazyInterface
  • ContextInterface
  • WithInterface

This reduces inheritance complexity and avoids circular references,
particularly relevant to Drupal 11 hook argument handling. Classes are now
marked final to enforce architectural intent.

Duplicate Method Removal

Within BlazyManagerBaseInterface, prefer:

$this->core->method();
$this->context->method();
$this->with->method();

Or within procedural function blazy(), prefer:

blazy()->core()->method();
blazy()->context()->method();
blazy()->with()->method();

Instead of legacy shorthand:

$this->method();

or:

blazy()->method();

Non-essential duplicate methods (including those retained for 4.x BC in
BlazyBase and BlazyBaseInterface) are deprecated and
will be removed in favor of:

  • ::core()
  • ::context()
  • ::with()

2. Media Component Service Deprecations

Media component services were deprecated in 3.0.18 and will be removed in
4.0.0 or 5.0.0 at the latest.

3.x Service 4.x Replacement
@blazy.file @blazy.file_renderer
@blazy.svg @blazy.svg_renderer
@blazy.media @blazy.media_renderer
@blazy.oembed @blazy.oembed_renderer
@blazy.entity @blazy.entity_renderer

Public access in 4.x is coordinated through @blazy.media_render.
Direct access to deprecated services may result in runtime errors.

3. Namespace & Property Deprecations

Namespace Reorganization

3.x Namespace 4.x Namespace
Drupal\blazy\Asset Drupal\blazy\Infra
Drupal\blazy\Config Drupal\blazy\Infra\Config
Drupal\blazy\Field Drupal\blazy\Infra\Field
Drupal\blazy\Views Drupal\blazy\Infra\Views
Drupal\blazy\Form Drupal\blazy\Infra\Form

Deprecated Properties → $core Accessors

3.x Property 4.x Equivalent
$root $core->root()
$cache $core->cache()
$configFactory $core->configFactory()
$entityRepository $core->entityRepository()
$entityTypeManager $core->entityTypeManager()
$languageManager $core->languageManager()
$moduleHandler $core->moduleHandler()
$renderer $core->renderer()
$libraries $with->libraries()

4. Settings Handling Change

The settings array is now cloned into BlazySettings::config for
safer and more convenient customization and operations without mutating the original settings directly. See
href="https://git.drupalcode.org/project/blazy/blob/4.0.x/blazy.api.php">blazy.api.php
for more details.

5. Deprecated hook_alter

Blazy 4.x schedules the removal of some not-so-useful hook_alters not currently
being used in sub-modules. See href="https://git.drupalcode.org/project/blazy/blob/4.0.x/blazy.api.php">blazy.api.php for more details.

  • hook_blazy_build_alter, blazy_lightbox and hook_blazy_alter => hook_blazy_settings_alter or hook_blazy_element_alter to avoid implementing
    unnecessary TrustedCallbackInterface.
  • blazy_presettings, blazy_filter_settings => hook_blazy_settings_alter
  • blazy_is_view => hook_preprocess_views_view
  • blazy_media_switch_form_element => blazy_form_element
  • blazy_form_element_definition => blazy_form_element
  • blazy_base_form_element => blazy_form_element
  • blazy_third_party_formatters => no replacement
  • blazy_build_entity => no replacement
  • blazy_views_field_options => no replacement
  • blazy_preblazy => no replacement
  • blazy_container => no replacement
  • blazy_container_grid => no replacement

"No replacement" means it can be done one way or another, not used anywhere, or not worth keeping.
The remaining hook_alters will finally be deprecated in 4.0.0, or so. Use a custom
processor class instead. Steps:

  1. Create a class, says \Drupal\my_module\Blazy\Processor\MyProcessor.php
  2. Follow the sample, inject any required services, and limit to the supported hooks:
  3. For the non-converted-yet hook_alters, use regular procedural functions, or Hook attribute until further deprecation notices.

Blazy 4.x is moving away from procedural or typed hook_alters into pipeline components for phased alterations. Blazy doesn't use the more familiar event-based services since it is all about pipeline transformation, not lifecycle notification. So event is the wrong abstraction. Processor phase is the correct one.

Deprecated 3.x Methods and Their 4.x Replacements

Core Service Accessors

Before (3.x) After (4.x)
root() ::core->root()
cache() ::core->cache()
configFactory() ::core->configFactory()
entityRepository() ::core->entityRepository()
entityTypeManager() ::core->entityTypeManager()
languageManager() ::core->languageManager()
routeMatch() ::core->routeMatch()
getPath() ::core->path()
getStorage() ::core->storage()
moduleHandler() ::core->moduleHandler()
moduleExists() ::core->moduleExists()
renderer() ::core->renderer()
renderInIsolation() ::core->renderInIsolation()
import() ::core->import()
load() ::core->load()
loadMultiple() ::core->loadMultiple()
loadByProperties() ::core->loadByProperties()
loadByProperty() ::core->loadByProperty()
loadByUuid() ::core->loadByUuid()
myConfig() ::core->config()
myConfigMultiple() ::core->configMultiple()
service() ::core->service()
getTranslatedEntity() ::core->translatedEntity()

Context Operations

Context Operations → ::context
Grid and media-related helpers were moved behind the explicit ContextInterface.

Before (3.x) After (4.x)
containerAttributes() ::context->containerAttributes()
isBlazy() ::context->workflow()->isBlazy()
getThumbnail() ::context->getThumbnail()
gridAttributes() ::context->grid()
gridCheckAttributes() ::context->grid()
gridItemAttributes() ::context->grid()
initGrid() ::context->grid()
toGrid() ::context->grid()
setAttachments() ::context->phaseBuild()

With Utilities

With Utilities → ::with
Configuration helpers, caching utilities, and data transformation helpers are
now accessed explicitly via WithInterface.

Before (3.x) After (4.x)
getCachedData() ::with->cachedData()
getCachedOptions() ::with->cachedOptions()
getBlazies() ::with->blazies()
getIoSettings() ::with->ioSettings()
getImageEffects() ::with->imageEffects()
getLibrariesPath() ::with->librariesPath()
getStyles() ::with->styles()
getCacheMetadata() ::with->cacheMetadata()
markdown() ::with->markdown()
imageStyles() ::with->fields()->imageStyles()
getEntityAsOptions() ::with->options()->fromEntity()
toOptions() ::with->options()->safeOptions()

Interop / Presentation Helpers

Interop / Presentation Helpers → ::with->it()
Presentation and surface-layer helpers are now explicitly accessed via
with->it().

Before (3.x) After (4.x)
denied() ::with->it()->denied()
toHtml() ::with->it()->toHtml()
view() ::with->it()->view()
hashtag() $param["#$key"], e.g.: $build['#settings']
toHashtag() $param["#$key"]
withHashtag() $param["#$key"]
getHtmlId() ::with->id()
merge() ::with->it()->merge()
mergeSettings() ::with->it()->mergeSettings()
settings() ::with->it()->initBlazies()
toSettings() ::with->it()->toSettings()

JavaScript

dBlazy.once is a wrapper for core/once for BigPipe compatibility. The dollar $ sign below is not jQuery, it is just internally an alias for dBlazy, similar to $ for jQuery.

Before (3.x):
$.once returns elements like core/once.
var els = $.once(...)
Or with a loop:
$.once(...).forEach(process)

After (4.x):
$.once remains intact.
Two new functions are available:
1. $.hydration is identical to $.once, only with a Promise return.

$.hydration(process, ...).then(function (data) {
  // Only if required, do more works, or finish it all with callback, remove then().
});

2. $.rehydration(callback) is a gate for BigPipe only if requiring stable operations before calling $.once inside the callback. The signature is only callback function.

CSS Classes Migration

Before (3.x) After (4.x)
blazy--grid b-grid (now a generic grid class)
b-column b-columns
b-grid (old Grid Foundation) b-foundation (new Grid Foundation)
blazy--nojs b-nojs
blazy--field b-field
blazy--view b-view
blazy--lightbox b-gallery (inline gallery displays)
blazy--LIGHTBOX-NAME b-LIGHTBOX-NAME

New in 4.x

New Class Purpose
b-lightbox Generic lightbox utility class shared across lightbox implementations.
Enables common interoperability features such as autoplay/pause for
native media and custom media players.

Examples:

b-lightbox — shared utility class for actual lightbox containers (#colorbox, .splidebox, .slick-lightbox, etc.).

#colorbox.b-lightbox
.splidebox.b-lightbox
.slick-lightbox.b-lightbox

Reason for Changes

  • Closer alignment with JavaScript class naming.
  • Reduced CSS payload through shorter class names.
  • More compact, unique, and less verbose naming.

What Changed

  • All proxy/helper methods previously exposed by BlazyBase have
    been removed in Blazy 4.x.
  • Consumers must now explicitly access:
    • ::core for infrastructure and Drupal service access
    • ::context for rendering, grid, and media coordination
    • ::with for configuration, libraries, markdown, caching, and data
      utilities
    • ::with->it() for presentation, user settings, HTML and
      surface-layer helpers
  • Render-array hashtag helpers (hashtag(),
    toHashtag(), withHashtag()) were removed in favor
    of direct usage like $param["#$key"], e.g.:
    $build["#settings"].

Why This Change Was Made

1. Eliminate “God Object” Behavior

In 3.x, BlazyBase acted as a large façade exposing dozens of thin
proxy methods.
While making operations convenient, this apparently increased the public API
surface and blurred responsibility boundaries. Blazy 4.x removes these
convenient proxies to enforce clearer architectural separation. Clarity and
efficiency over convenience is the direction of 4.x onward.

2. Improve Architectural Clarity

Blazy 4.x introduces explicit layering:

Layer Responsibility
core Drupal service access and infrastructure operations
context Media, grid, and rendering orchestration
with Configuration helpers, libraries, caching, and data utilities
with->it() Surface-layer, user settings, HTML and presentation helpers for
"CR-zero" consideration.

This makes dependencies explicit and prevents accidental cross-layer coupling.

3. Improve Static Analysis and Type Safety

Removing proxy methods:

  • Reduces indirection
  • Improves IDE auto-completion accuracy
  • Improves PHPStan precision
  • Eliminates duplicated method signatures

4. Reduce API Surface and Maintenance Overhead

Although proxy methods are lightweight, removing them:

  • Reduces the size of the public API
  • Prevents method shadowing and ambiguity
  • Makes future refactoring safer and easier

Upgrade Path Summary

Before (3.x) After (4.x) Notes
$this->root(); $this->core->root(); Core helper methods moved under core.
$this->gridAttributes(...); $this->context->grid(...); Grid helpers consolidated under context.
$this->getCachedData(...); $this->with->cachedData(...); Data access delegated to the fluent with helper.
$this->markdown(...); $this->with->markdown(...); A markdown helper for Help page.
$this->toHtml(...); $this->with->it()->toHtml(...); HTML rendering is now accessed through the fluent API.
BlazyManager::getBlazy(...); BlazyManager::view(...); Simplified static rendering API.
Impacts: 
Site builders, administrators, editors
Module developers
Themers
Site templates, recipes and distribution developers