Nette Assets

Защо Nette Assets?

Работата със статични файлове често означава повтарящ се, податлив на грешки код. Ръчно конструирате URL адреси, добавяте параметри за версии за кеш изчистване и обработвате различни типове файлове по различен начин. Това води до код като:

<img src="/images/logo.png?v=1699123456" width="200" height="100" alt="Logo">
<link rel="stylesheet" href="/css/style.css?v=2">

С Nette Assets цялата тази сложност изчезва:

{* Всичко автоматизирано - URL, версииране, размери *}
<img n:asset="images/logo.png">
<link n:asset="css/style.css">

{* Или просто *}
{asset 'css/style.css'}

Това е! Библиотеката автоматично:

• Добавя параметри за версии въз основа на времето на последна модификация на файла
• Открива размерите на изображението и ги включва в HTML
• Генерира правилния HTML елемент за всеки тип файл
• Обработва както развойна, така и продукционна среда

Инсталация

Инсталирайте Nette Assets с помощта на Composer:

composer require nette/assets

Изисква PHP 8.1 или по-нова и работи перфектно с Nette Framework, но може да се използва и самостоятелно.

Първи стъпки

Nette Assets работи веднага без никаква конфигурация. Поставете статичните си файлове в директорията www/assets/ и започнете да ги използвате:

{* Показва изображение с автоматични размери *}
{asset 'logo.png'}

{* Включва стилова таблица с версииране *}
{asset 'style.css'}

{* Зарежда JavaScript модул *}
{asset 'app.js'}

За повече контрол върху генерирания HTML, използвайте атрибута n:asset или функцията asset().

Как работи

Nette Assets е изграден около три основни концепции, които го правят мощен, но лесен за използване:

Активи – Вашите файлове стават интелигентни

Актив представлява всеки статичен файл във вашето приложение. Всеки файл става обект с полезни свойства само за четене:

$image = $assets->getAsset('photo.jpg');
echo $image->url;      // '/assets/photo.jpg?v=1699123456'
echo $image->width;    // 1920
echo $image->height;   // 1080
echo $image->mimeType; // 'image/jpeg'

Различните типове файлове предоставят различни свойства:

• Изображения: ширина, височина, алтернативен текст, лениво зареждане
• Скриптове: тип модул, хешове за цялост, crossorigin
• Стилови таблици: медийни заявки, цялост
• Аудио/Видео: продължителност, размери
• Шрифтове: правилно предварително зареждане с CORS

Библиотеката автоматично открива типовете файлове и създава подходящия клас актив.

Мапъри – Откъде идват файловете

Мапърът знае как да намира файлове и да създава URL адреси за тях. Можете да имате множество мапъри за различни цели – локални файлове, CDN, облачно хранилище или инструменти за изграждане (всеки от тях има име). Вграденият FilesystemMapper обработва локални файлове, докато ViteMapper се интегрира с модерни инструменти за изграждане.

Мапърите се дефинират в Конфигурация.

Регистър – Вашият основен интерфейс

Регистърът управлява всички мапъри и предоставя основния API:

// Инжектирайте регистъра във вашата услуга
public function __construct(
	private Nette\Assets\Registry $assets
) {}

// Вземете активи от различни мапъри
$logo = $this->assets->getAsset('images:logo.png'); // мапър 'image'
$app = $this->assets->getAsset('app:main.js'); // мапър 'app'
$style = $this->assets->getAsset('style.css'); // използва мапъра по подразбиране

Регистърът автоматично избира правилния мапър и кешира резултатите за производителност.

Работа с активи в PHP

Регистърът предоставя два метода за извличане на активи:

// Хвърля Nette\Assets\AssetNotFoundException, ако файлът не съществува
$logo = $assets->getAsset('logo.png');

// Връща null, ако файлът не съществува
$banner = $assets->tryGetAsset('banner.jpg');
if ($banner) {
	echo $banner->url;
}

Указване на мапъри

Можете изрично да изберете кой мапър да използвате:

// Използвайте мапъра по подразбиране
$file = $assets->getAsset('document.pdf');

// Използвайте конкретен мапър с префикс
$image = $assets->getAsset('images:photo.jpg');

// Използвайте конкретен мапър със синтаксис на масив
$script = $assets->getAsset(['scripts', 'app.js']);

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

Всеки тип актив предоставя съответните свойства само за четене:

// Свойства на изображение
$image = $assets->getAsset('photo.jpg');
echo $image->width;     // 1920
echo $image->height;    // 1080
echo $image->mimeType;  // 'image/jpeg'

// Свойства на скрипт
$script = $assets->getAsset('app.js');
echo $script->type;     // 'module' или null

// Свойства на аудио
$audio = $assets->getAsset('song.mp3');
echo $audio->duration;  // продължителност в секунди

// Всички активи могат да бъдат преобразувани в низ (връща URL)
$url = (string) $assets->getAsset('document.pdf');

Свойства като размери или продължителност се зареждат лениво само при достъп, поддържайки библиотеката бърза.

Използване на активи в Latte шаблони

Nette Assets предоставя интуитивна Latte интеграция с тагове и функции.

{asset}

Тагът {asset} рендира пълни HTML елементи:

{* Рендира: <img src="/assets/hero.jpg?v=123" width="1920" height="1080"> *}
{asset 'hero.jpg'}

{* Рендира: <script src="/assets/app.js?v=456" type="module"></script> *}
{asset 'app.js'}

{* Рендира: <link rel="stylesheet" href="/assets/style.css?v=789"> *}
{asset 'style.css'}

Тагът автоматично:

• Открива типа актив и генерира подходящ HTML
• Включва версииране за кеш изчистване
• Добавя размери за изображения
• Задава правилни атрибути (тип, медия и т.н.)

Когато се използва вътре в HTML атрибути, той извежда само URL адреса:

<div style="background-image: url({asset 'bg.jpg'})">
<img srcset="{asset 'logo@2x.png'} 2x">

n:asset

За пълен контрол върху HTML атрибутите:

{* Атрибутът n:asset попълва src, размери и т.н. *}
<img n:asset="product.jpg" alt="Product" class="rounded">

{* Работи с всеки подходящ елемент *}
<script n:asset="analytics.js" defer></script>
<link n:asset="print.css" media="print">
<audio n:asset="podcast.mp3" controls></audio>

Използвайте променливи и мапъри:

{* Променливите работят естествено *}
<img n:asset="$product->image">

{* Укажете мапър с къдрави скоби *}
<img n:asset="images:{$product->image}">

{* Укажете мапър с нотация на масив *}
<img n:asset="[images, $product->image]">

asset()

За максимална гъвкавост, използвайте функцията asset():

{var $logo = asset('logo.png')}
<img src={$logo} width={$logo->width} height={$logo->height}>

{* Или директно *}
<img src={asset('logo.png')} alt="Logo">

Опционални активи

Обработвайте липсващи активи елегантно с {asset?}, n:asset? и tryAsset():

{* Опционален таг - не рендира нищо, ако активът липсва *}
{asset? 'optional-banner.jpg'}

{* Опционален атрибут - пропуска, ако активът липсва *}
<img n:asset?="user-avatar.jpg" alt="Avatar" class="avatar">

{* С резервен вариант *}
{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')}
<img n:asset=$avatar alt="Avatar">

{preload}

Подобрете производителността на зареждане на страницата:

{* Във вашата <head> секция *}
{preload 'critical.css'}
{preload 'important-font.woff2'}
{preload 'hero-image.jpg'}

Генерира подходящи preload връзки:

<link rel="preload" href="/assets/critical.css?v=123" as="style">
<link rel="preload" href="/assets/important-font.woff2" as="font" crossorigin>
<link rel="preload" href="/assets/hero-image.jpg" as="image">

Разширени функции

Автоматично откриване на разширения

Автоматично обработвайте множество формати:

assets:
	mapping:
		images:
			path: img
			extension: [webp, jpg, png]  # Опитайте по ред

Сега можете да изисквате без разширение:

{* Намира logo.webp, logo.jpg или logo.png автоматично *}
{asset 'images:logo'}

Перфектно за прогресивно подобрение с модерни формати.

Интелигентно версииране

Файловете автоматично се версиират въз основа на времето на модификация:

{asset 'style.css'}
{* Изход: <link rel="stylesheet" href="/assets/style.css?v=1699123456"> *}

Когато актуализирате файла, времевият печат се променя, принуждавайки опресняване на кеша на браузъра.

Контролирайте версиирането за всеки актив:

// Деактивирайте версиирането за конкретен актив
$asset = $assets->getAsset('style.css', ['version' => false]);

// В Latte
{asset 'style.css', version: false}

Шрифтови активи

Шрифтовете получават специално отношение с правилен CORS:

{* Правилно предварително зареждане с crossorigin *}
{preload 'fonts:OpenSans-Regular.woff2'}

{* Използвайте в CSS *}
<style>
@font-face {
	font-family: 'Open Sans';
	src: url('{asset 'fonts:OpenSans-Regular.woff2'}') format('woff2');
	font-display: swap;
}
</style>

Персонализирани мапъри

Създайте персонализирани мапъри за специални нужди като облачно хранилище или динамично генериране:

use Nette\Assets\Mapper;
use Nette\Assets\Asset;
use Nette\Assets\Helpers;

class CloudStorageMapper implements Mapper
{
	public function __construct(
		private CloudClient $client,
		private string $bucket,
	) {}

	public function getAsset(string $reference, array $options = []): Asset
	{
		if (!$this->client->exists($this->bucket, $reference)) {
			throw new Nette\Assets\AssetNotFoundException("Asset '$reference' not found");
		}

		$url = $this->client->getPublicUrl($this->bucket, $reference);
		return Helpers::createAssetFromUrl($url);
	}
}

Регистрирайте в конфигурацията:

assets:
	mapping:
		cloud: CloudStorageMapper(@cloudClient, 'my-bucket')

Използвайте като всеки друг мапър:

{asset 'cloud:user-uploads/photo.jpg'}

Методът Helpers::createAssetFromUrl() автоматично създава правилния тип актив въз основа на разширението на файла.

Допълнително четене

• Нетни активи: Най-накрая унифициран API за всичко – от изображения до Vite