Working With Assets via PHP API

Pimcore provides an object orientated PHP API to work with Assets.

CRUD Operations

Following lines of code show simple CRUD operations for Assets.

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

With Asset\Listing lists of assets can be retrieved and filtered. The most important methods are setCondition, setOffset, setLimit, setOrderKey, setOrder.

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

Please also have a look at object listings and document listings.

Custom Settings

Custom Settings/Properties can be added programmatically to every asset. This is mostly used for plugins or something similar.

$asset = Asset::getById(2345);
$settings = $asset->getCustomSettings();
$settings["mySetting"] = "this is my value this can be everythin also an array or an object not only a string";
$asset->setCustomSettings($settings);
$asset->save();

Using (localized) Asset Metadata

Asset Metadata allow you to attach localized metadata to assets within Pimcore. These Medata can be accessed via API and therefore used on all output channels.

Examples

Getting Data

Metadata for an asset can be fetched using getMetadata method of Asset class. It can take the following optional parameters:

1. $name (string) when passed it returns the metadata with the given name, otherwise it lists all.
2. $language (string) with this parameter you can filter out the metadata of a specific language.
3. $strictMatchLanguage (boolean) if true tries to get only the metadata which exactly matches the requested language without considering the fallback.
4. $raw (boolean) if true, it will also return extra information like name, data, language and input type of the metadata.

To know the expected return values, you can look into the tests inside 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 this will be 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. ie: 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

There may be predefined and default fields on an Asset. That means that these fields have a special meaning and will be used somewhere else.

Image asset

There are 3 default fields, namely title, alt and copyright. The contents of this fields will be used as default alt and title attribute on any <img> tag generated by Pimcore for the corresponding image.

This includes for example:

// 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 will be appended to every title and alt attribute separated by |.

---