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 |.