Caricamento di File e Immagini

I tipi di campo change_type() per il caricamento di file e immagini, più gallery() per un campo multi-immagine con riordino tramite trascinamento.

Caricamento di file semplice

public function change_type(string $field, string $type, string $length = '', array $extra = []): self

change_type($field, 'file', '', $extra) trasforma un campo in una zona di rilascio (dropzone) per file. Le sue opzioni $extra:

Opzione	Tipo	Predefinito	Descrizione
`not_rename`	bool	`false`	Mantiene il nome originale del file caricato invece di generarne uno sicuro. Il nome viene comunque sanificato (separatori di percorso/traversal rimossi) anche con questa opzione attiva - semplicemente non viene reso casuale.
`preview`	false\|true\|'download'\|'modal'\|'edit'	`false`	Cosa fa il click sul nome del file. `false`/`'download'` - un semplice link di download. `true`/`'modal'` - apre una finestra modale di anteprima interna all'app (un iframe sul file) con un pulsante Download accanto. `'edit'` - apre invece il modulo di modifica di quella riga, utile quando lo scopo reale del campo è "il record a cui questo file è allegato".

$xcrud->change_type('simple_upload', 'file', '', ['not_rename' => true, 'preview' => 'modal']);

Caricamento di immagini

change_type($field, 'image', '', $extra) aggiunge l'elaborazione di ridimensionamento/ritaglio/filigrana/miniatura sopra un caricamento semplice:

Opzione	Tipo	Predefinito	Descrizione
`width` / `height`	int	-	Dimensione target per il ridimensionamento automatico. Entrambe + `crop`=true riempiono esattamente il riquadro (proporzioni mantenute, l'eccesso viene ritagliato); una sola delle due, oppure entrambe senza crop, adattano l'immagine entro il riquadro (proporzioni mantenute, nessun ritaglio).
`crop`	bool	`false`	Vedi sopra - riempie il riquadro invece di limitarsi ad adattarvisi.
`manual_crop`	bool	`false`	Mostra un'interfaccia interattiva di ritaglio tramite trascinamento (Cropper.js) subito dopo la scelta di un file, prima che venga salvato. Si combina con `width`/`height`/`crop` invece di sostituirli - `manual_crop` controlla cosa viene mantenuto, gli altri si applicano comunque al risultato ritagliato in seguito.
`ratio`	float	-	Con `manual_crop`, blocca il riquadro di ritaglio a questo rapporto larghezza/altezza (es. `0.5` = sempre due volte più alto che largo) invece di lasciare che il visitatore scelga un rettangolo qualsiasi.
`watermark`	string	-	Percorso di un PNG, relativo alla radice del progetto, sovrapposto all'immagine salvata.
`watermark_position`	[x%, y%]	`[95, 95]`	Dove atterra l'angolo superiore sinistro della filigrana, come percentuale della larghezza/altezza propria dell'immagine.
`thumbs`	array	`[]`	Immagini derivate aggiuntive con nome, salvate accanto a quella principale - ogni elemento: `width`/`height`/`crop`/`marker` (suffisso del nome file)/`folder`/`watermark`. Ogni miniatura viene ridimensionata in modo indipendente a partire dall'originale, non concatenata alle altre.

// Adatta entro 200x200, senza ritaglio
$xcrud->change_type('auto_resize', 'image', '', ['width' => 200, 'height' => 200]);

// Riempie esattamente 200x200, l'eccesso viene ritagliato
$xcrud->change_type('auto_crop', 'image', '', ['width' => 200, 'height' => 200, 'crop' => true]);

// Ritaglio interattivo tramite trascinamento, poi ridimensionato a 200x200
$xcrud->change_type('manual_crop_2', 'image', '', ['width' => 200, 'height' => 200, 'manual_crop' => true]);

// Due miniature derivate, una con filigrana, una ritagliata in una sottocartella
$xcrud->change_type('image_with_thumbs', 'image', '', [
    'thumbs' => [
        ['width' => 300, 'marker' => '_th', 'watermark' => 'assets/watermark.png'],
        ['width' => 100, 'height' => 100, 'crop' => true, 'folder' => 'thumbs'],
    ],
]);

Configurazione dell'archiviazione dei caricamenti

Queste impostazioni si trovano in XcrudConfig, non per singolo campo:

Impostazione	Tipo	Predefinito	Descrizione
`$uploadDir`	string	`'media/'`	Dove vengono effettivamente scritti i file caricati.
`$uploadMaxSize`	int	10 MB (`10 * 1024 * 1024`)	Dimensione massima di caricamento in byte, imposta lato applicazione oltre al proprio `upload_max_filesize` di PHP.
`$uploadAllowedImageExt`	array	`['jpg', 'jpeg', 'png', 'gif', 'webp']`	Estensioni consentite per i campi immagine.
`$uploadAllowedFileExt`	array	un elenco curato di tipi comuni di documenti/archivi	Estensioni consentite per i campi file semplici. Aggiungi a questo elenco solo tipi genuinamente sicuri di cui hai effettivamente bisogno.

Vedi la Guida di riferimento a XcrudConfig per tutte le altre impostazioni.

gallery(): un campo multi-immagine

public function gallery(string $field, string $childTable, array $options = []): self

A differenza di change_type('image'), gallery() è un campo a trascinamento per molte immagini contemporaneamente, ciascuna salvata come propria riga in $childTable - non una colonna della tabella corrente. $field, qui, è un nome virtuale, quindi non va inserito in ->columns(). $childTable deve essere essa stessa una tabella reale e raggiungibile, con almeno un id auto-incrementante, la colonna di chiave esterna indicata in fk, una colonna filename, una colonna name (una didascalia per immagine), una colonna size e una colonna sort_order in cui il riordino tramite trascinamento viene salvato in modo persistente.

Opzione	Tipo	Predefinito	Descrizione
`fk`	string	obbligatorio	La colonna di chiave esterna propria della tabella figlio che fa riferimento alla chiave primaria di questa tabella.
`folder`	string	nome del campo	Sottodirectory di `$uploadDir` in cui vengono salvate le immagini di questa galleria.
`layout`	'grid'\|'list'	`'grid'`	`'grid'` - una griglia a scorrimento di miniature quadrate. `'list'` - una riga per immagine con miniatura, didascalia modificabile, dimensione del file e pulsanti Anteprima/Rimuovi. Il riordino tramite trascinamento funziona in modo identico in entrambi i casi.
`width` / `height` / `crop` / `watermark` / `watermark_position` / `thumbs`	-	-	Stesso significato delle opzioni proprie di `change_type('image')`, applicate in modo indipendente a ogni immagine caricata in questa galleria.
`max_files`	int	-	Limita il numero totale di immagini che questa galleria può contenere; i caricamenti successivi vengono rifiutati una volta raggiunto il limite.

$xcrud->gallery('gallery', 'uploads_gallery', [
    'fk'     => 'upload_id',
    'width'  => 1600,
    'height' => 1600,
]);

Una riga appena creata, mai salvata, non ha ancora un id a cui le immagini della galleria possano fare riferimento - il campo mostra un segnaposto disabilitato "salva prima questo record" finché la riga non esiste effettivamente.