Download the PHP package kerimkaralic/pimcore-asset-bundle without Composer

TsfAssetBundle

Automatically sort assets referenced by DataObjects and Documents in Pimcore 11.x, 12.x, and 2026.x.

• Composer package: kerimkaralic/pimcore-asset-bundle
• Namespace: Tsf\AssetBundle
• Bundle class: Tsf\AssetBundle\TsfAssetBundle
• Config alias: tsf_asset
• License: MIT

Requirements

The effective PHP and Symfony versions are determined by the selected Pimcore line:

The bundle uses Pimcore model events and has no dependency on either the Classic Admin or Studio UI, so the same sorting implementation is used on all supported lines.

Installation

Register the bundle in config/bundles.php:

Then install it:

The package declares extra.pimcore.bundles, so Pimcore discovers it as an available pimcore-bundle; config/bundles.php is what actually enables it in the kernel.

What it does

When a DataObject or a Pimcore Document is saved, every asset it references is moved into a folder structure generated from a configurable path pattern. Assets already sitting in their target folder are left alone, so re-saving an element is a no-op.

Configuration

All options live under the tsf_asset key. Run bin/console debug:config tsf_asset for the resolved configuration. A ready-to-copy version is available in docs/configuration.example.yaml.

When a switch is false the listener returns immediately and the save continues untouched.

Partial and environment overrides

Symfony merges repeated bundle configuration, so an override only needs to contain the keys that change. For example, disable DataObject sorting in development without repeating any paths:

Or retarget only Product while preserving the other class and asset-type rules:

Per class rules

sorting.data_objects.classes is keyed by DataObject class name. Classes are runtime data in Pimcore, so they cannot be enumerated at compile time — list only the classes that need their own rule and everything else falls back to sorting.data_objects.path. A class rule inherits the section path when its own path is null, and its asset_types are merged over the section ones.

Path tokens

Patterns must be absolute. Unknown tokens are rejected when the container is compiled, so a typo fails fast instead of silently producing a wrong folder. Run bin/console tsf:asset:path-tokens for this table:

A token that resolves to an empty value aborts the move for that asset and logs a warning — an object with no SKU will not dump its images into a shared folder. {char:N} is exempt and falls back to _. Every resolved segment is passed through Element\Service::getValidKey(), and segments that sanitise to nothing are dropped.

Asset type overrides

asset_types is keyed by the value of Asset::getType(), so a PDF (Pimcore\Model\Asset\Document, type document) can land somewhere different from an image referenced by the same element. Falls back to path for any type not listed.

What gets collected

From DataObjects — every field value that is or contains an Asset: single asset relations, image galleries, hotspot images, advanced relations carrying ElementMetadata, and plain arrays of any of those. Asset folders are ignored.

From Documents — the image, video, pdf, relation and relations editables of any PageSnippet, including editables nested inside areablocks and blocks. Documents without editables (links, folders, hardlinks) are skipped.

Sorting runs on postAdd and preUpdate for both element types, so a newly created element is sorted on its first save.

Not traversed: localized fields, field collections and object bricks. Their container values are returned by get() but are not unwrapped, so assets nested inside them are left where they are.

Layout

Everything under src/ is auto-registered as a private, autowired service. Installer is excluded from that sweep and declared explicitly as public — Pimcore fetches it from the container.

Extending

• Services / listeners / subscribers / commands: drop the class in src/; autoconfigure tags it. No YAML edit needed for EventSubscriberInterface, Command, etc.
• Controllers: add src/Controller/, then ship a config/routes.yaml and load it from the extension (or have the consuming project import it).
• Config options: extend Configuration::getConfigTreeBuilder().
• Migrations: add src/Migrations/, then return the last migration class name from Installer::getLastMigrationVersionClassName() so install/uninstall marks them correctly.

Local development inside a Pimcore project

The bundle is consumed through a composer path repository so the working copy is symlinked into vendor/:

vendor/kerimkaralic/pimcore-asset-bundle is a symlink to the working copy, so edits apply immediately — only bin/console cache:clear is needed. Adding new classes needs no dump-autoload, since the package's own PSR-4 mapping covers src/.

Tests

Codeception, mirroring how the Pimcore core bundles are tested. The unit suite needs no database, no OpenSearch and no booted Pimcore kernel — tests/_bootstrap.php installs a stub kernel that only provides the event dispatcher Pimcore\Model\Element\Service reaches for.

Standalone:

The GitHub Actions workflow runs the same command against Pimcore 11.x, 12.x, and 2026.x.

From inside a Pimcore project that consumes the bundle as a path package (no composer install in the bundle needed — the bootstrap falls back to the project autoloader):

What is covered:

Not covered by the unit suite: AssetStructureSorter::moveAsset() and getUniqueFilename(), which go through Pimcore\Model\Asset\Service::createFolderByPath() and Asset::save() and therefore need a real installation. Those belong in a functional suite run against a test database.

Versioning

getVersion() reads the installed version from composer metadata, so it reports whatever git tag was resolved (dev-main while developing from a path repository). Tag releases with vX.Y.Z.

Commands

In this Docker-based project prefix each with docker compose exec -T php php.

License

MIT — see LICENSE.