Cache e minificazione

Tre esigenze di produzione si presentano alla fine della pipeline: evitare di ricompilare input identici, evitare il costo di creare un compilatore a ogni richiesta e ridurre il CSS generato. Tutte e tre sono funzioni di supporto lato PHP intorno al compilatore.

Memorizzazione nella cache

La generazione di CSS esegue l'intera pipeline a ogni chiamata. Per i contenuti che non cambiano tra una richiesta e l'altra, la cache basata su file salva il risultato su disco e lo restituisce alle chiamate successive.

Passate cache a tw::generate(): true per la directory predefinita oppure una stringa con il percorso per sceglierne una personalizzata:

use TailwindPHP\tw;

// Cache to the default directory: sys_get_temp_dir() . '/tailwindphp'
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
]);

// Cache to a custom directory
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => '/path/to/cache',
]);

// With a time-to-live (seconds)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
    'cacheTtl' => 3600, // expire after 1 hour
]);

La directory della cache viene creata automaticamente se non esiste.

Chiave della cache

La chiave deriva dal contenuto, dalla configurazione CSS e dal flag minify; questi elementi vengono sottoposti a hash nel nome del file tailwind_<hash>.css. Qualsiasi modifica al markup, all'input CSS o all'impostazione della minificazione genera una chiave diversa e quindi un file diverso.

La configurazione CSS inclusa nella chiave è costituita dall'css inline e dal contenuto dei file indicati in importPaths. Due input non sono inclusi: i file importati tramite un @import annidato in quei file e la versione di TailwindPHP. Svuotate la cache dopo aver modificato un import annidato o aggiornato il pacchetto, altrimenti continuerà a essere restituito il vecchio output.

Durata della cache

cacheTtl è una durata espressa in secondi. Quando si trova un risultato nella cache, l'ora di modifica del file viene confrontata con l'ora corrente; se il file è più vecchio di cacheTtl, viene considerato un risultato mancante e ricompilato. Se cacheTtl non è impostato, le voci non scadono mai: cancellatele manualmente.

Svuotare la cache

tw::clearCache() (o la funzione clearCache()) elimina i file tailwind_*.css da una directory della cache e restituisce il numero di file eliminati.

use TailwindPHP\tw;
use function TailwindPHP\clearCache;

$deleted = tw::clearCache();                  // default directory
$deleted = tw::clearCache('/path/to/cache');  // custom directory
clearCache('/path/to/cache');                 // function form

Cache dello stato del compilatore

La cache di output è utile solo quando torna lo stesso contenuto. Quando il contenuto cambia a ogni chiamata, la parte costosa è la creazione del compilatore: risolvere @import "tailwindcss", analizzare le risorse incluse e accumulare il tema. Questa fase dipende solo dall'input CSS, quindi può essere salvata e riutilizzata.

Passate stateCacheFile a tw::compile() (o a new TailwindCompiler($css, $options)):

use TailwindPHP\tw;

$compiler = tw::compile($themeCss, [
    'stateCacheFile' => __DIR__ . '/cache/tailwind-state.php',
]);

$css = $compiler->generateExact($html, true);

Alla prima creazione, lo stato viene scritto in quel percorso come file PHP semplice, che OPcache può condividere tra le richieste; le creazioni successive lo caricano invece di analizzarlo di nuovo. L'output è identico byte per byte a quello di un compilatore senza cache.

• Il file viene convalidato rispetto a un'impronta del motore (dimensione e mtime dei sorgenti e delle risorse di TailwindPHP), a una chiave derivata dall'input CSS e dalle opzioni base e importSearchPaths, nonché a dimensione e mtime di ogni file importato dall'input. Se qualcosa non corrisponde, viene ricostruito e riscritto: non serve alcun intervento manuale dopo aver aggiornato TailwindPHP o modificato un file importato.
• Il percorso è a vostra scelta: usate un file per ogni input CSS distinto, in una directory in cui il server web possa scrivere. Le scritture sono atomiche (file temporaneo più rename()).
• Gli input che usano un importResolver personalizzato ignorano la cache, perché non è possibile calcolare l'impronta del comportamento del resolver.
• La stessa cache è disponibile per l'array compile() di livello inferiore API come TailwindPHP\StateCache\compileCssCached($css, $cacheFile, $options).

tw::generate() non accetta stateCacheFile: crea un nuovo compilatore a ogni chiamata. Se il costo di creazione è rilevante, usate un'istanza del compilatore.

Minimizzazione

La minificazione riduce l'output per la produzione. Il flag minify genera direttamente CSS minificato durante la serializzazione, quindi è il metodo più rapido e preciso; tw::minify() esegue il minificatore basato su stringhe (src/_tailwindphp/CssMinifier.php) su una stringa CSS esistente:

use TailwindPHP\tw;

// Minify during generation (serializer path, preferred)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'minify' => true,
]);

// Or minify an existing string (string-based post-pass)
$css = tw::generate('<div class="flex p-4">Hello</div>');
$minified = tw::minify($css);

I due metodi producono una struttura equivalente, ma non byte identici. Il metodo del serializzatore mantiene i selettori :not() discendenti che il passaggio sulle stringhe accorpa; quindi, per l'output generato, preferite il flag minify e riservate tw::minify() a CSS che arrivano come stringa.

Cosa fa

Entrambi i metodi applicano lo stesso insieme di riduzioni delle dimensioni:

Per scelta progettuale non unisce i selettori duplicati né combina le proprietà shorthand: entrambe le operazioni rendono più difficile il debug e possono influire sulla cascata.

CLI: --minify rispetto a --optimize

CLI espone il metodo di minificazione del serializzatore tramite due flag:

# Optimize and minify (smallest output)
tailwindphp -i ./src/app.css -o ./dist/styles.css --minify   # or -m

# Meant to optimize without minifying
tailwindphp -i ./src/app.css -o ./dist/styles.css --optimize

Nella versione attuale, anche --optimize esegue la minificazione, quindi entrambi i comandi scrivono gli stessi byte (#9). Le trasformazioni equivalenti a lightningcss vengono eseguite a ogni build in entrambi i casi, quindi l'output semplice (senza flag) è già ottimizzato e leggibile.

Per il resto dell'API pubblico — tw::generate(), tw::compile(), metodi di ispezione e formati di input — consultate il riferimento API.