Nette Assets

Prečo Nette Assets?

Práca so statickými súbormi často znamená opakujúci sa kód náchylný na chyby. Manuálne konštruujete URL adresy, pridávate parametre verzie pre cache busting a rôzne typy súborov spracovávate odlišne. To vedie ku kódu ako:

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

S Nette Assets všetka táto zložitosť zmizne:

{* Všetko automatizované - URL, verzovanie, rozmery *}
<img n:asset="images/logo.png">
<link n:asset="css/style.css">

{* Alebo len *}
{asset 'css/style.css'}

To je všetko! Knižnica automaticky:

• Pridáva parametre verzie na základe času poslednej úpravy súboru
• Detekuje rozmery obrázka a zahrnie ich do HTML
• Generuje správny HTML element pre každý typ súboru
• Spracováva vývojové aj produkčné prostredia

Inštalácia

Nainštalujte Nette Assets pomocou Composer:

composer require nette/assets

Vyžaduje PHP 8.1 alebo vyššie a funguje perfektne s Nette Frameworkom, ale môže byť použitá aj samostatne.

Prvé kroky

Nette Assets funguje hneď po vybalení bez akejkoľvek konfigurácie. Umiestnite svoje statické súbory do adresára www/assets/ a začnite ich používať:

{* Zobrazí obrázok s automatickými rozmermi *}
{asset 'logo.png'}

{* Zahrnie štýl s verzovaním *}
{asset 'style.css'}

{* Načíta JavaScript modul *}
{asset 'app.js'}

Pre väčšiu kontrolu nad generovaným HTML použite atribút n:asset alebo funkciu asset().

Ako to funguje

Nette Assets je postavený na troch základných konceptoch, ktoré ho robia výkonným a zároveň jednoduchým na používanie:

Assets – Vaše súbory sú inteligentné

Asset predstavuje akýkoľvek statický súbor vo vašej aplikácii. Každý súbor sa stáva objektom s užitočnými readonly vlastnosťami:

$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'

Rôzne typy súborov poskytujú rôzne vlastnosti:

• Obrázky: šírka, výška, alternatívny text, lazy loading
• Skripty: typ modulu, integrity hashe, crossorigin
• Štýly: media queries, integrity
• Audio/Video: trvanie, rozmery
• Fonty: správne preloading s CORS

Knižnica automaticky detekuje typy súborov a vytvára príslušnú triedu assetu.

Mappery – Odkiaľ súbory pochádzajú

Mapper vie, ako nájsť súbory a vytvoriť pre ne URL adresy. Môžete mať viacero mapperov na rôzne účely – lokálne súbory, CDN, cloudové úložisko alebo build nástroje (každý z nich má názov). Vstavaný FilesystemMapper spracováva lokálne súbory, zatiaľ čo ViteMapper sa integruje s modernými build nástrojmi.

Mappery sú definované v konfigurácii.

Registry – Vaše hlavné rozhranie

Registry spravuje všetky mappery a poskytuje hlavné API:

// Vložte registry do vašej služby
public function __construct(
	private Nette\Assets\Registry $assets
) {}

// Získajte assets z rôznych mapperov
$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper
$app = $this->assets->getAsset('app:main.js'); // 'app' mapper
$style = $this->assets->getAsset('style.css'); // používa predvolený mapper

Registry automaticky vyberie správny mapper a cachuje výsledky pre výkon.

Práca s Assets v PHP

Registry poskytuje dve metódy na získanie assetov:

// Vyhodí Nette\Assets\AssetNotFoundException, ak súbor neexistuje
$logo = $assets->getAsset('logo.png');

// Vráti null, ak súbor neexistuje
$banner = $assets->tryGetAsset('banner.jpg');
if ($banner) {
	echo $banner->url;
}

Špecifikácia Mapperov

Môžete explicitne zvoliť, ktorý mapper použiť:

// Použite predvolený mapper
$file = $assets->getAsset('document.pdf');

// Použite špecifický mapper s prefixom
$image = $assets->getAsset('images:photo.jpg');

// Použite špecifický mapper so syntaxou poľa
$script = $assets->getAsset(['scripts', 'app.js']);

Vlastnosti a typy Assetov

Každý typ assetu poskytuje relevantné readonly vlastnosti:

// Vlastnosti obrázka
$image = $assets->getAsset('photo.jpg');
echo $image->width;     // 1920
echo $image->height;    // 1080
echo $image->mimeType;  // 'image/jpeg'

// Vlastnosti skriptu
$script = $assets->getAsset('app.js');
echo $script->type;     // 'module' alebo null

// Vlastnosti audia
$audio = $assets->getAsset('song.mp3');
echo $audio->duration;  // trvanie v sekundách

// Všetky assets môžu byť pretypované na string (vráti URL)
$url = (string) $assets->getAsset('document.pdf');

Vlastnosti ako rozmery alebo trvanie sú načítané len lenivo, keď sú prvýkrát prístupné, čo udržuje knižnicu rýchlu.

Používanie Assets v Latte šablónach

Nette Assets poskytuje intuitívnu Latte integráciu s tagmi a funkciami.

{asset}

Tag {asset} vykresľuje kompletné HTML elementy:

{* Vykreslí: <img src="/assets/hero.jpg?v=123" width="1920" height="1080"> *}
{asset 'hero.jpg'}

{* Vykreslí: <script src="/assets/app.js?v=456" type="module"></script> *}
{asset 'app.js'}

{* Vykreslí: <link rel="stylesheet" href="/assets/style.css?v=789"> *}
{asset 'style.css'}

Tag automaticky:

• Detekuje typ assetu a generuje príslušné HTML
• Zahrnie verzovanie pre cache busting
• Pridá rozmery pre obrázky
• Nastaví správne atribúty (typ, media atď.)

Pri použití vo vnútri HTML atribútov výstupom je len URL:

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

n:asset

Pre úplnú kontrolu nad HTML atribútmi:

{* Atribút n:asset dopĺňa src, rozmery atď. *}
<img n:asset="product.jpg" alt="Produkt" class="rounded">

{* Funguje s akýmkoľvek relevantným elementom *}
<script n:asset="analytics.js" defer></script>
<link n:asset="print.css" media="print">
<audio n:asset="podcast.mp3" controls></audio>

Použite premenné a mappery:

{* Premenné fungujú prirodzene *}
<img n:asset="$product->image">

{* Špecifikujte mapper s kučeravými zátvorkami *}
<img n:asset="images:{$product->image}">

{* Špecifikujte mapper s notáciou poľa *}
<img n:asset="[images, $product->image]">

asset()

Pre maximálnu flexibilitu použite funkciu asset():

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

{* Alebo priamo *}
<img src={asset('logo.png')} alt="Logo">

Voliteľné Assets

Spracujte chýbajúce assets elegantne pomocou {asset?}, n:asset? a tryAsset():

{* Voliteľný tag - nevykreslí nič, ak asset chýba *}
{asset? 'optional-banner.jpg'}

{* Voliteľný atribút - preskočí, ak asset chýba *}
<img n:asset?="user-avatar.jpg" alt="Avatar" class="avatar">

{* S fallbackom *}
{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')}
<img n:asset=$avatar alt="Avatar">

{preload}

Zlepšite výkon načítania stránky:

{* Vo vašej <head> sekcii *}
{preload 'critical.css'}
{preload 'important-font.woff2'}
{preload 'hero-image.jpg'}

Generuje príslušné preload odkazy:

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

Pokročilé funkcie

Automatická detekcia prípon

Automaticky spracujte viacero formátov:

assets:
	mapping:
		images:
			path: img
			extension: [webp, jpg, png]  # Skúšajte v poradí

Teraz môžete požiadať bez prípony:

{* Automaticky nájde logo.webp, logo.jpg alebo logo.png *}
{asset 'images:logo'}

Ideálne pre progresívne vylepšenie s modernými formátmi.

Inteligentné verzovanie

Súbory sú automaticky verzované na základe času poslednej úpravy:

{asset 'style.css'}
{* Výstup: <link rel="stylesheet" href="/assets/style.css?v=1699123456"> *}

Keď aktualizujete súbor, časová pečiatka sa zmení, čo vynúti obnovenie cache prehliadača.

Kontrola verzovania pre jednotlivé assets:

// Zakázať verzovanie pre konkrétny asset
$asset = $assets->getAsset('style.css', ['version' => false]);

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

Font Assets

Fonty dostávajú špeciálne zaobchádzanie so správnym CORS:

{* Správne preload s crossorigin *}
{preload 'fonts:OpenSans-Regular.woff2'}

{* Použite v CSS *}
<style>
@font-face {
	font-family: 'Open Sans';
	src: url('{asset 'fonts:OpenSans-Regular.woff2'}') format('woff2');
	font-display: swap;
}
</style>

Vlastné Mappery

Vytvorte vlastné mappery pre špeciálne potreby, ako je cloudové úložisko alebo dynamické generovanie:

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);
	}
}

Zaregistrujte v konfigurácii:

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

Použite ako akýkoľvek iný mapper:

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

Metóda Helpers::createAssetFromUrl() automaticky vytvorí správny typ assetu na základe prípony súboru.

Nadaljnje branje

• Nette Assets: Končno poenoten API za vse, od slik do Vite