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

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

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

For more information about Asset Metadata also have a look at the User Documentation.

[comment]: #(TODO add links)