Nette Assets

Neden Nette Assets?

Statik dosyalarla çalışmak genellikle tekrarlayan, hataya açık kod anlamına gelir. URL'leri manuel olarak oluşturur, önbelleği temizlemek için sürüm parametreleri eklersiniz ve farklı dosya türlerini farklı şekilde ele alırsınız. Bu, şöyle bir koda yol açar:

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

Nette Assets ile tüm bu karmaşıklık ortadan kalkar:

{* Her şey otomatik - URL, sürümleme, boyutlar *}
<img n:asset="images/logo.png">
<link n:asset="css/style.css">

{* Veya sadece *}
{asset 'css/style.css'}

Hepsi bu kadar! Kütüphane otomatik olarak:

• Dosya değiştirme zamanına göre sürüm parametreleri ekler
• Görsel boyutlarını algılar ve bunları HTML'ye dahil eder
• Her dosya türü için doğru HTML öğesini oluşturur
• Hem geliştirme hem de üretim ortamlarını yönetir

Kurulum

Nette Assets'i Composer kullanarak kurun:

composer require nette/assets

PHP 8.1 veya daha yüksek bir sürüm gerektirir ve Nette Framework ile mükemmel çalışır, ancak bağımsız olarak da kullanılabilir.

İlk Adımlar

Nette Assets, sıfır yapılandırmayla kutudan çıktığı gibi çalışır. Statik dosyalarınızı www/assets/ dizinine yerleştirin ve kullanmaya başlayın:

{* Otomatik boyutlarla bir görseli göster *}
{asset 'logo.png'}

{* Sürümlemeli bir stil sayfası dahil et *}
{asset 'style.css'}

{* Bir JavaScript modülünü yükle *}
{asset 'app.js'}

Oluşturulan HTML üzerinde daha fazla kontrol için n:asset niteliğini veya asset() fonksiyonunu kullanın.

Nasıl Çalışır

Nette Assets, güçlü ama kullanımı basit olmasını sağlayan üç temel konsept üzerine kuruludur:

Varlıklar (Assets) – Dosyalarınız Akıllandı

Bir varlık (asset), uygulamanızdaki herhangi bir statik dosyayı temsil eder. Her dosya, kullanışlı salt okunur özelliklere sahip bir nesne haline gelir:

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

Farklı dosya türleri farklı özellikler sağlar:

• Görseller: genişlik, yükseklik, alternatif metin, tembel yükleme
• Betikler: modül türü, bütünlük hash'leri, crossorigin
• Stil sayfaları: medya sorguları, bütünlük
• Ses/Video: süre, boyutlar
• Fontlar: uygun CORS ile ön yükleme

Kütüphane, dosya türlerini otomatik olarak algılar ve uygun varlık sınıfını oluşturur.

Eşleştiriciler (Mappers) – Dosyalar Nereden Geliyor

Bir eşleştirici (mapper), dosyaları nasıl bulacağını ve onlar için URL'leri nasıl oluşturacağını bilir. Farklı amaçlar için birden fazla eşleştiriciniz olabilir – yerel dosyalar, CDN, bulut depolama veya derleme araçları (her birinin bir adı vardır). Yerleşik FilesystemMapper yerel dosyaları yönetirken, ViteMapper modern derleme araçlarıyla entegre olur.

Eşleştiriciler yapılandırma içinde tanımlanır.

Kayıt Defteri (Registry) – Ana Arayüzünüz

Kayıt defteri (registry), tüm eşleştiricileri yönetir ve ana API'yi sağlar:

// Kayıt defterini servisinizde enjekte edin
public function __construct(
	private Nette\Assets\Registry $assets
) {}

// Farklı eşleştiricilerden varlıkları al
$logo = $this->assets->getAsset('images:logo.png'); // 'image' eşleştiricisi
$app = $this->assets->getAsset('app:main.js'); // 'app' eşleştiricisi
$style = $this->assets->getAsset('style.css'); // varsayılan eşleştiriciyi kullanır

Kayıt defteri, doğru eşleştiriciyi otomatik olarak seçer ve performans için sonuçları önbelleğe alır.

PHP'de Varlıklarla Çalışma

Kayıt Defteri, varlıkları almak için iki metot sağlar:

// Dosya yoksa Nette\Assets\AssetNotFoundException fırlatır
$logo = $assets->getAsset('logo.png');

// Dosya yoksa null döndürür
$banner = $assets->tryGetAsset('banner.jpg');
if ($banner) {
	echo $banner->url;
}

Eşleştiricileri Belirtme

Hangi eşleştiricinin kullanılacağını açıkça seçebilirsiniz:

// Varsayılan eşleştiriciyi kullan
$file = $assets->getAsset('document.pdf');

// Önekle belirli bir eşleştiriciyi kullan
$image = $assets->getAsset('images:photo.jpg');

// Dizi sözdizimiyle belirli bir eşleştiriciyi kullan
$script = $assets->getAsset(['scripts', 'app.js']);

Varlık Özellikleri ve Türleri

Her varlık türü ilgili salt okunur özellikler sağlar:

// Görsel özellikleri
$image = $assets->getAsset('photo.jpg');
echo $image->width;     // 1920
echo $image->height;    // 1080
echo $image->mimeType;  // 'image/jpeg'

// Betik özellikleri
$script = $assets->getAsset('app.js');
echo $script->type;     // 'module' veya null

// Ses özellikleri
$audio = $assets->getAsset('song.mp3');
echo $audio->duration;  // saniye cinsinden süre

// Tüm varlıklar dizeye dönüştürülebilir (URL döndürür)
$url = (string) $assets->getAsset('document.pdf');

Boyutlar veya süre gibi özellikler, kütüphaneyi hızlı tutmak için yalnızca erişildiğinde tembelce yüklenir.

Latte Şablonlarında Varlıkları Kullanma

Nette Assets, etiketler ve fonksiyonlarla sezgisel Latte entegrasyonu sağlar.

{asset}

{asset} etiketi, eksiksiz HTML öğeleri oluşturur:

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

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

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

Etiket otomatik olarak:

• Varlık türünü algılar ve uygun HTML'yi oluşturur
• Önbellek temizleme için sürümlemeyi dahil eder
• Görseller için boyutları ekler
• Doğru nitelikleri (tür, medya vb.) ayarlar

HTML nitelikleri içinde kullanıldığında, yalnızca URL'yi çıktı verir:

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

n:asset

HTML nitelikleri üzerinde tam kontrol için:

{* n:asset niteliği src, boyutlar vb. doldurur. *}
<img n:asset="product.jpg" alt="Ürün" class="rounded">

{* İlgili herhangi bir öğeyle çalışır *}
<script n:asset="analytics.js" defer></script>
<link n:asset="print.css" media="print">
<audio n:asset="podcast.mp3" controls></audio>

Değişkenleri ve eşleştiricileri kullanın:

{* Değişkenler doğal olarak çalışır *}
<img n:asset="$product->image">

{* Süslü parantezlerle eşleştiriciyi belirt *}
<img n:asset="images:{$product->image}">

{* Dizi gösterimiyle eşleştiriciyi belirt *}
<img n:asset="[images, $product->image]">

asset()

Maksimum esneklik için asset() fonksiyonunu kullanın:

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

{* Veya doğrudan *}
<img src={asset('logo.png')} alt="Logo">

İsteğe Bağlı Varlıklar

Eksik varlıkları {asset?}, n:asset? ve tryAsset() ile zarifçe ele alın:

{* İsteğe bağlı etiket - varlık eksikse hiçbir şey oluşturmaz *}
{asset? 'optional-banner.jpg'}

{* İsteğe bağlı nitelik - varlık eksikse atlar *}
<img n:asset?="user-avatar.jpg" alt="Avatar" class="avatar">

{* Geri dönüş ile *}
{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')}
<img n:asset=$avatar alt="Avatar">

{preload}

Sayfa yükleme performansını iyileştirin:

{* <head> bölümünüzde *}
{preload 'critical.css'}
{preload 'important-font.woff2'}
{preload 'hero-image.jpg'}

Uygun ön yükleme bağlantılarını oluşturur:

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

Gelişmiş Özellikler

Uzantı Otomatik Algılama

Birden çok formatı otomatik olarak yönetin:

assets:
	mapping:
		images:
			path: img
			extension: [webp, jpg, png]  # Sırayla dene

Şimdi uzantısız olarak isteyebilirsiniz:

{* logo.webp, logo.jpg veya logo.png'yi otomatik olarak bulur *}
{asset 'images:logo'}

Modern formatlarla aşamalı geliştirme için mükemmeldir.

Akıllı Sürümleme

Dosyalar, değiştirme zamanına göre otomatik olarak sürümlenir:

{asset 'style.css'}
{* Çıktı: <link rel="stylesheet" href="/assets/style.css?v=1699123456"> *}

Dosyayı güncellediğinizde, zaman damgası değişir ve tarayıcı önbelleğinin yenilenmesini zorlar.

Varlık başına sürümlemeyi kontrol edin:

// Belirli bir varlık için sürümlemeyi devre dışı bırak
$asset = $assets->getAsset('style.css', ['version' => false]);

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

Font Varlıkları

Fontlar, uygun CORS ile özel muamele görür:

{* crossorigin ile uygun ön yükleme *}
{preload 'fonts:OpenSans-Regular.woff2'}

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

Özel Eşleştiriciler (Custom Mappers)

Bulut depolama veya dinamik üretim gibi özel ihtiyaçlar için özel eşleştiriciler oluşturun:

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("Varlık '$reference' bulunamadı");
		}

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

Yapılandırmada kaydolun:

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

Diğer eşleştiriciler gibi kullanın:

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

Helpers::createAssetFromUrl() metodu, dosya uzantısına göre doğru varlık türünü otomatik olarak oluşturur.

Daha Fazla Okuma

• Nette Varlıkları: Nihayet görüntülerden Vite'a kadar her şey için birleşik API