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, όλη αυτή η πολυπλοκότητα εξαφανίζεται:

{* Everything automated - URL, versioning, dimensions *}
<img n:asset="images/logo.png">
<link n:asset="css/style.css">

{* Or just *}
{asset 'css/style.css'}

Αυτό είναι όλο! Η βιβλιοθήκη αυτόματα:

• Προσθέτει παραμέτρους έκδοσης με βάση την ώρα τροποποίησης του αρχείου
• Ανιχνεύει τις διαστάσεις της εικόνας και τις συμπεριλαμβάνει στο HTML
• Δημιουργεί το σωστό στοιχείο HTML για κάθε τύπο αρχείου
• Χειρίζεται τόσο το περιβάλλον ανάπτυξης όσο και το περιβάλλον παραγωγής

Εγκατάσταση

Εγκαταστήστε το Nette Assets χρησιμοποιώντας το Composer:

composer require nette/assets

Απαιτεί PHP 8.1 ή νεότερο και λειτουργεί τέλεια με το Nette Framework, αλλά μπορεί επίσης να χρησιμοποιηθεί αυτόνομα.

Πρώτα Βήματα

Το Nette Assets λειτουργεί άμεσα χωρίς καμία ρύθμιση. Τοποθετήστε τα στατικά σας αρχεία στον κατάλογο www/assets/ και αρχίστε να τα χρησιμοποιείτε:

{* Display an image with automatic dimensions *}
{asset 'logo.png'}

{* Include a stylesheet with versioning *}
{asset 'style.css'}

{* Load a JavaScript module *}
{asset 'app.js'}

Για περισσότερο έλεγχο στο παραγόμενο HTML, χρησιμοποιήστε το χαρακτηριστικό n:asset ή τη συνάρτηση asset().

Πώς Λειτουργεί

Το Nette Assets βασίζεται σε τρεις βασικές έννοιες που το καθιστούν ισχυρό αλλά απλό στη χρήση:

Assets – Τα Αρχεία σας Έγιναν Έξυπνα

Ένα asset αντιπροσωπεύει οποιοδήποτε στατικό αρχείο στην εφαρμογή σας. Κάθε αρχείο γίνεται ένα αντικείμενο με χρήσιμες ιδιότητες μόνο για ανάγνωση:

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

Διαφορετικοί τύποι αρχείων παρέχουν διαφορετικές ιδιότητες:

• Εικόνες: πλάτος, ύψος, εναλλακτικό κείμενο, lazy loading
• Σενάρια: τύπος ενότητας (module), hashes ακεραιότητας, crossorigin
• Φύλλα στυλ: media queries, ακεραιότητα
• Ήχος/Βίντεο: διάρκεια, διαστάσεις
• Γραμματοσειρές: σωστή προφόρτωση με CORS

Η βιβλιοθήκη ανιχνεύει αυτόματα τους τύπους αρχείων και δημιουργεί την κατάλληλη κλάση asset.

Mappers – Από Πού Προέρχονται τα Αρχεία

Ένας mapper γνωρίζει πώς να βρίσκει αρχεία και να δημιουργεί διευθύνσεις URL για αυτά. Μπορείτε να έχετε πολλούς mappers για διαφορετικούς σκοπούς – τοπικά αρχεία, CDN, αποθήκευση στο cloud ή εργαλεία δημιουργίας (το καθένα από αυτά έχει ένα όνομα). Ο ενσωματωμένος FilesystemMapper χειρίζεται τα τοπικά αρχεία, ενώ ο ViteMapper ενσωματώνεται με σύγχρονα εργαλεία δημιουργίας.

Οι mappers ορίζονται στην Διαμόρφωση.

Registry – Η Κύρια Διεπαφή σας

Το registry διαχειρίζεται όλους τους mappers και παρέχει το κύριο API:

// Inject the registry in your service
public function __construct(
	private Nette\Assets\Registry $assets
) {}

// Get assets from different mappers
$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper
$app = $this->assets->getAsset('app:main.js'); // 'app' mapper
$style = $this->assets->getAsset('style.css'); // uses default mapper

Το registry επιλέγει αυτόματα τον σωστό mapper και αποθηκεύει τα αποτελέσματα στην κρυφή μνήμη για καλύτερη απόδοση.

Εργασία με Assets σε PHP

Το Registry παρέχει δύο μεθόδους για την ανάκτηση assets:

// Throws Nette\Assets\AssetNotFoundException if file doesn't exist
$logo = $assets->getAsset('logo.png');

// Returns null if file doesn't exist
$banner = $assets->tryGetAsset('banner.jpg');
if ($banner) {
	echo $banner->url;
}

Καθορισμός Mappers

Μπορείτε να επιλέξετε ρητά ποιον mapper θα χρησιμοποιήσετε:

// Use default mapper
$file = $assets->getAsset('document.pdf');

// Use specific mapper with prefix
$image = $assets->getAsset('images:photo.jpg');

// Use specific mapper with array syntax
$script = $assets->getAsset(['scripts', 'app.js']);

Ιδιότητες και Τύποι Asset

Κάθε τύπος asset παρέχει σχετικές ιδιότητες μόνο για ανάγνωση:

// Image properties
$image = $assets->getAsset('photo.jpg');
echo $image->width;     // 1920
echo $image->height;    // 1080
echo $image->mimeType;  // 'image/jpeg'

// Script properties
$script = $assets->getAsset('app.js');
echo $script->type;     // 'module' or null

// Audio properties
$audio = $assets->getAsset('song.mp3');
echo $audio->duration;  // duration in seconds

// All assets can be cast to string (returns URL)
$url = (string) $assets->getAsset('document.pdf');

Ιδιότητες όπως διαστάσεις ή διάρκεια φορτώνονται με lazy loading μόνο όταν προσπελαστούν, διατηρώντας τη βιβλιοθήκη γρήγορη.

Χρήση Assets σε Πρότυπα Latte

Το Nette Assets παρέχει διαισθητική ενσωμάτωση Latte με ετικέτες και συναρτήσεις.

{asset}

Η ετικέτα {asset} αποδίδει πλήρη στοιχεία HTML:

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

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

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

Η ετικέτα αυτόματα:

• Ανιχνεύει τον τύπο asset και δημιουργεί το κατάλληλο HTML
• Περιλαμβάνει έκδοση για την εκκαθάριση της κρυφής μνήμης
• Προσθέτει διαστάσεις για εικόνες
• Ορίζει τα σωστά χαρακτηριστικά (type, media, κ.λπ.)

Όταν χρησιμοποιείται μέσα σε χαρακτηριστικά HTML, εξάγει μόνο τη διεύθυνση URL:

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

n:asset

Για πλήρη έλεγχο των χαρακτηριστικών HTML:

{* The n:asset attribute fills in src, dimensions, etc. *}
<img n:asset="product.jpg" alt="Product" class="rounded">

{* Works with any relevant element *}
<script n:asset="analytics.js" defer></script>
<link n:asset="print.css" media="print">
<audio n:asset="podcast.mp3" controls></audio>

Χρησιμοποιήστε μεταβλητές και mappers:

{* Variables work naturally *}
<img n:asset="$product->image">

{* Specify mapper with curly brackets *}
<img n:asset="images:{$product->image}">

{* Specify mapper with array notation *}
<img n:asset="[images, $product->image]">

asset()

Για μέγιστη ευελιξία, χρησιμοποιήστε τη συνάρτηση asset():

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

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

Προαιρετικά Assets

Χειριστείτε τα ελλείποντα assets με χάρη με {asset?}, n:asset? και tryAsset():

{* Optional tag - renders nothing if asset missing *}
{asset? 'optional-banner.jpg'}

{* Optional attribute - skips if asset missing *}
<img n:asset?="user-avatar.jpg" alt="Avatar" class="avatar">

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

{preload}

Βελτιώστε την απόδοση φόρτωσης σελίδας:

{* In your <head> section *}
{preload 'critical.css'}
{preload 'important-font.woff2'}
{preload 'hero-image.jpg'}

Δημιουργεί κατάλληλους συνδέσμους προφόρτωσης:

<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]  # Try in order

Τώρα μπορείτε να ζητήσετε χωρίς επέκταση:

{* Finds logo.webp, logo.jpg, or logo.png automatically *}
{asset 'images:logo'}

Ιδανικό για προοδευτική βελτίωση με σύγχρονες μορφές.

Έξυπνη Έκδοση

Τα αρχεία εκδίδονται αυτόματα με βάση την ώρα τροποποίησης:

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

Όταν ενημερώνετε το αρχείο, η χρονοσφραγίδα αλλάζει, αναγκάζοντας την ανανέωση της κρυφής μνήμης του προγράμματος περιήγησης.

Έλεγχος έκδοσης ανά asset:

// Disable versioning for specific asset
$asset = $assets->getAsset('style.css', ['version' => false]);

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

Assets Γραμματοσειρών

Οι γραμματοσειρές λαμβάνουν ειδική μεταχείριση με σωστό CORS:

{* Proper preload with crossorigin *}
{preload 'fonts:OpenSans-Regular.woff2'}

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

Προσαρμοσμένοι Mappers

Δημιουργήστε προσαρμοσμένους mappers για ειδικές ανάλογες ανάγκες όπως αποθήκευση στο cloud ή δυναμική δημιουργία:

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

Χρησιμοποιήστε όπως οποιονδήποτε άλλο mapper:

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

Η μέθοδος Helpers::createAssetFromUrl() δημιουργεί αυτόματα τον σωστό τύπο asset με βάση την επέκταση αρχείου.

Περαιτέρω ανάγνωση

• Nette Assets: για τα πάντα, από εικόνες έως Vite