Search by

hryvinskyi / magento2-banner-slider-api

hryvinskyi

Banner Slider API module - service contracts, data interfaces and value objects

Package info

github.com/hryvinskyi/magento2-banner-slider-api

Type:magento2-module

pkg:composer/hryvinskyi/magento2-banner-slider-api

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 242

Dependents: 5

Suggesters: 0

Stars: 0

Open Issues: 0

2.1.0 2026-09-25 08:19 UTC

Requires

  • php: ~8.3.0||~8.4.0
  • magento/framework: ^103.0.7
  • psr/clock: ^1.0

Requires (Dev)

None

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT 2e2100132633abb9324c98a1f94ebd868f4dd627

  • Volodymyr Hryvinskyi <volodymyr.woop@hryvinskyi.com>

Published on Packagist.org on 2026-09-25 08:23 UTC

This package is auto-updated.

Last update: 2026-09-25 08:23:13 UTC

README

Service contracts, data interfaces and value objects of the Banner Slider.

Part of hryvinskyi/magento2-banner-slider-pack - Complete Banner Slider solution for Magento 2

What this package is

The innermost ring of the Banner Slider. It holds only contracts: no implementation, no database schema, no configuration and no templates. It depends on magento/framework and psr/clock, nothing else.

hryvinskyi/magento2-banner-slider-api          contracts, data interfaces, value objects   (this package)
        ^
hryvinskyi/magento2-banner-slider              implementations, persistence, media, config defaults, CLI, cron
        ^                         ^
magento2-banner-slider-admin-ui   magento2-banner-slider-frontend-ui

Every arrow points inward. The admin and the storefront packages call only the interfaces in this package, and never each other. Classes of the implementation package are never imported by PHP code outside it.

Contents

All types are @api.

Namespace Contents
Api\Data SliderInterface, BannerInterface, BreakpointInterface, ResponsiveCropInterface (extensible entities), CropVariantInterface (immutable variant of a crop), the four *SearchResultsInterface
Api SliderRepositoryInterface, BannerRepositoryInterface, BreakpointRepositoryInterface, ResponsiveCropRepositoryInterface (single-entity persistence)
Api\Slider SliderLocatorInterface (the slider a storefront visitor sees), SliderEditorInterface (save a slider with its breakpoints atomically)
Api\Banner VisibleBannersProviderInterface (a slider's banners at a moment), BannerEditorInterface (save a banner with its crops atomically)
Api\Picture PictureSourcesProviderInterface (ready-to-render <picture> sources per banner)
Api\ResponsiveCrop CropRegeneratorInterface (re-encode stored crops on the server)
Api\Media ImageUploadInterface, VideoUploadInterface, MediaUrlResolverInterface
Api\Image ImageFormatRegistryInterface (open set of image formats and crop variant formats)
Api\Config ImageConfigInterface, VideoConfigInterface
Api\Video ProviderInterface (a video source: parse, embed URL and attributes), ProviderResolverInterface
Api\Validation one validator per entity; repositories run them on save and throw ValidationException with every error
Api\Value value objects and enums (below)

Value objects

Domain concepts are value objects, not strings and integers: ActiveWindow, Visibility, LocationCode, AspectRatio, Dimensions, CropRect, ResponsiveItem, ImageFormat, BreakpointSpec, PictureSource, ImageFile, StorefrontContext, UploadedFile, StoredMedia, VideoData, EmbedOptions, FormatRequest, EncodedImage, CropInput, BreakpointInput, and the enums BannerType, SlideEffect, EmbedKind.

The rules they follow:

  • Valid by construction. The constructor checks every rule and throws \InvalidArgumentException naming the field and the rule. An invalid instance cannot exist.
  • Immutable. Getters only; no setters, no public properties.
  • Constructors only. There are no static methods: no named constructors, no static helpers. Enums map stored values with the built-in tryFrom(), for example SlideEffect::tryFrom($value ?? '') ?? SlideEffect::SLIDE. Text such as 16:9 is parsed with the stateless AspectRatioParser. EmbedOptions is built with named arguments.
  • Equality by value through equals() where comparing makes sense.
  • Time is UTC. ActiveWindow and StorefrontContext convert what they receive to UTC. new ActiveWindow(null, null) means "always". The current moment comes from Psr\Clock\ClockInterface, which the implementation package binds.

Messages of these exceptions are for developers and are not translated. Callers that show them to people turn them into their own translated messages.

Trust levels

  • Banner content is trusted admin HTML and is rendered through the CMS template filter.
  • Slider custom CSS is plain CSS; a value containing < is rejected.
  • Banner link URLs accept http:, https:, mailto:, tel: and relative URLs; video URLs accept http: and https: only.
  • Image and video paths are relative to the media directory.
  • EncodedImage bytes and UploadedFile client names are untrusted input.

Web API

These contracts are for PHP callers. Value objects and the upload contracts are not serialisable by the Magento web API, and the package declares no webapi.xml.

Requirements

  • PHP 8.3 or 8.4
  • Magento 2.4.7 or later (magento/framework 103.0.7+)

Installation

This module is normally installed as part of the hryvinskyi/magento2-banner-slider-pack metapackage:

composer require hryvinskyi/magento2-banner-slider-pack
php bin/magento module:enable Hryvinskyi_BannerSliderApi
php bin/magento setup:upgrade
php bin/magento cache:flush

Upgrading from 1.x

2.0 is a breaking release; see CHANGELOG.md for every removed and changed contract.

Author

Volodymyr Hryvinskyi

License

MIT