Работа с ассетами через PHP API

Pimcore предоставляет объектно-ориентированный PHP API для работы с ассетами.

Операции CRUD

Ниже приведены строки кода, показывающие простые операции CRUD для ассетов.

//создание и сохранение нового ассета  
$newAsset = new \Pimcore\Model\Asset();  
$newAsset->setFilename("myAsset.png");  
$newAsset->setData(file_get_contents("some-file.png"));  
$newAsset->setParent(\Pimcore\Model\Asset::getByPath("/"));  
  
// необязательный параметр позволяет передать дополнительную информацию  
// в настоящее время поддерживается:  
//      * versionNote: заметка, добавляемая к версии (см. вкладку версий) 
$newAsset->save(["versionNote" => "my new version"]);  
  
//получение ассетов  
$asset1 = \Pimcore\Model\Asset::getById(3456);  
$asset2 = \Pimcore\Model\Asset::getByPath("/my-assets/sample.png");  
  
//обновление ассетов  
$asset1->setData(file_get_contents("some-updated-file.png"));  
$asset1->save();  
  
//удаление ассетов  
$asset2->delete();  

Списки ассетов

С помощью Asset\Listing можно получать и фильтровать списки ассетов. Наиболее важные методы: setCondition, setOffset, setLimit, setOrderKey, setOrder.

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

Также обратите внимание на списки объектов и списки документов.

Пользовательские настройки

Пользовательские настройки/свойства могут быть добавлены программно к любому ассету. Это в основном используется для плагинов или аналогичных случаев.

$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();  

Использование (локализованных) метаданных ассетов

Метаданные ассетов позволяют прикреплять локализованные метаданные к ассетам в Pimcore. Эти метаданные могут быть доступны через API и, следовательно, использованы на всех каналах вывода.

Примеры

Получение данных

Метаданные для ассета можно получить, используя метод getMetadata класса Asset. Он может принимать следующие необязательные параметры:

1. $name (string) если передан, возвращает метаданные с указанным именем, иначе возвращает все метаданные.
2. $language (string) с этим параметром можно отфильтровать метаданные по конкретному языку.
3. $strictMatchLanguage (boolean) если true, пытается получить только метаданные, которые точно соответствуют запрошенному языку без учёта механизма fallback.
4. $raw (boolean) если true, также вернёт дополнительную информацию, такую как имя, данные, язык и тип ввода метаданных.

Чтобы узнать ожидаемые возвращаемые значения, можно посмотреть тесты внутри tests/Model/Asset/Metadata/NormalizerTest::testLocalizedMetaData

$asset = Asset::getById(123);  
  
// получить заголовок для текущего языка (атрибут запроса `_locale`)  
$asset->getMetadata("title");  
  
// получить английский заголовок  
$asset->getMetadata("title", "en");  
// если для "en" нет заголовка, но есть заголовок без языка, он будет возвращён (механизм fallback).  
  
// получить все доступные метаданные
$asset->getMetadata();  
  
// получить все доступные метаданные для конкретного языка вместе с метаданными, у которых язык не задан
$asset->getMetadata(null, 'en');  
  
// получить исключительно все метаданные, имеющие конкретный язык
$asset->getMetadata(null, 'en', true);  
  
// получить метаданные в сыром формате, т.е. включая тип ввода метаданных, язык, значение и имя
$asset->getMetadata('title', null, true, true);  

Установка данных

// Установить английский заголовок
$asset->addMetadata("title", "input", "the new title", "en");  

Удаление данных

// Удалить английский заголовок
$asset->removeMetadata("title", "en");  
  
// Удалить заголовок во всех языках
$asset->removeMetadata("title", "*");  

Предопределённые системные метаданные

На ассете могут быть предопределённые и поля по умолчанию. Это значит, что эти поля имеют специальное значение и будут использованы в других местах.

Изображение (image asset)

Существуют 3 поля по умолчанию: title, alt и copyright. Содержимое этих полей будет использовано как значения по умолчанию для атрибутов alt и title в любом теге <img>, генерируемом Pimcore для соответствующего изображения.

Это включает, например:

// встраиваемое изображение в документах  
{{ pimcore_image("myImage", {"thumbnail": "xyz"}) }}  

{# генератор HTML миниатюр #}  
{{ asset.getThumbnail("xyz").getHtml()|raw }}  
{{ object.getMyImage().getThumbnail("xyz").getHtml()|raw }}  

Поле copyright будет добавлено ко всем атрибутам title и alt, разделённое символом |.

---