Skip to main content
Version: 2026.3

Working with Assets via PHP API

Pimcore provides an object-oriented PHP API to work with assets.

CRUD Operations​

//creating and saving new asset
$newAsset = new \Pimcore\Model\Asset();
$newAsset->setFilename("myAsset.png");
$newAsset->setData(file_get_contents("some-file.png"));
$newAsset->setParent(\Pimcore\Model\Asset::getByPath("/"));

// the optional parameter allows you to provide additional info
// currently supported:
// * versionNote: note added to the version (see version tab)
$newAsset->save(["versionNote" => "my new version"]);

//getting assets
$asset1 = \Pimcore\Model\Asset::getById(3456);
$asset2 = \Pimcore\Model\Asset::getByPath("/my-assets/sample.png");

//updating assets
$asset1->setData(file_get_contents("some-updated-file.png"));
$asset1->save();

//deleting assets
$asset2->delete();

Asset Listings​

Use Asset\Listing to retrieve and filter lists of assets. The most important methods are setCondition, setOffset, setLimit, setOrderKey, and setOrder.

$list = new \Pimcore\Model\Asset\Listing();
$list->setCondition("...");
$list->setOrderKey("filename");
$list->setOrder("DESC");
$list->load();

Also see Object Listings and Document Listings.

Custom Settings​

Custom settings are key-value pairs that you can attach programmatically to any asset. They are typically used by bundles or application-specific logic.

Note: Custom settings are different from properties. Properties are user-facing, support inheritance through the tree hierarchy, and are editable in Pimcore Studio. Custom settings are developer-facing, stored directly on the asset, and can hold any serializable value.

$asset = Asset::getById(2345);
$settings = $asset->getCustomSettings();
$settings["mySetting"] = "this can be anything - a string, array, or object";
$asset->setCustomSettings($settings);
$asset->save();

Using (Localized) Asset Metadata​

Asset metadata lets you attach localized metadata to assets within Pimcore. These metadata values can be accessed via the API and used across all output channels.

Getting Data​

Retrieve metadata using the getMetadata method of the Asset class. It accepts the following optional parameters:

  1. $name (string) - when passed, returns the metadata with the given name; otherwise returns all metadata.
  2. $language (string) - filters metadata for a specific language.
  3. $strictMatchLanguage (boolean) - if true, returns only metadata that exactly matches the requested language without considering fallback.
  4. $raw (boolean) - if true, returns extra information including name, data, language, and input type of the metadata.

For expected return values, see the tests in tests/Model/Asset/Metadata/NormalizerTest::testLocalizedMetaData.

$asset = Asset::getById(123);

// get the title for the current language (request attribute `_locale`)
$asset->getMetadata("title");

// get the English title
$asset->getMetadata("title", "en");
// if there's no title for "en" but one without a language, the unlocalized value is returned (fallback mechanism)

// get all available metadata
$asset->getMetadata();

// get all available metadata for a specific language along with metadata which have no language assigned
$asset->getMetadata(null, 'en');

// get exclusively all the metadata that have a specific language
$asset->getMetadata(null, 'en', true);

// get metadata in raw format (including metadata input type, language, value, and name)
$asset->getMetadata('title', null, true, true);

Setting Data​

// Set the English title
$asset->addMetadata("title", "input", "the new title", "en");

Removing Data​

// Remove the English title
$asset->removeMetadata("title", "en");

// Remove the title in all languages
$asset->removeMetadata("title", "*");

Predefined System Metadata​

Some fields on an asset have special meaning and are used by the system.

Image Assets​

There are 3 default fields: title, alt, and copyright. These are used as default alt and title attributes on any <img> tag generated by Pimcore for the corresponding image.

This includes:

{# image editable on documents #}
{{ pimcore_image("myImage", {"thumbnail": "xyz"}) }}
{# thumbnail html generator #}
{{ asset.getThumbnail("xyz").getHtml()|raw }}
{{ object.getMyImage().getThumbnail("xyz").getHtml()|raw }}

The copyright field is appended to every title and alt attribute, separated by |.