Datei- & Bild-Uploads

change_type()-Feldtypen für Datei- und Bild-Uploads, plus gallery() für ein Mehrbild-Feld mit Drag-to-Reorder.

Einfache Datei-Uploads

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

change_type($field, 'file', '', $extra) macht aus einem Feld eine Datei-Dropzone. Die $extra-Optionen dazu:

Option	Typ	Standard	Beschreibung
`not_rename`	bool	`false`	Behält den Originalnamen der hochgeladenen Datei, statt einen generierten, sicheren Namen zu vergeben. Der Name wird auch bei aktivierter Option weiterhin bereinigt (Pfadtrenner/Traversal werden entfernt) - er wird lediglich nicht randomisiert.
`preview`	false\|true\|'download'\|'modal'\|'edit'	`false`	Was ein Klick auf den Dateinamen bewirkt. `false`/`'download'` - ein einfacher Download-Link. `true`/`'modal'` - öffnet ein In-App-Vorschau-Modal (ein iframe auf die Datei) mit einer zusätzlichen Download-Schaltfläche. `'edit'` - öffnet stattdessen das Bearbeiten-Formular dieser Zeile, nützlich wenn der eigentliche Zweck des Felds "der Datensatz, an dem diese Datei hängt" ist.

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

Bild-Uploads

change_type($field, 'image', '', $extra) fügt einem einfachen Upload zusätzlich Resize-/Crop-/Wasserzeichen-/Thumbnail-Verarbeitung hinzu:

Option	Typ	Standard	Beschreibung
`width` / `height`	int	-	Ziel für die automatische Größenänderung. Beide zusammen + `crop`=true füllen exakt den vorgegebenen Rahmen (Seitenverhältnis erhalten, Überschuss abgeschnitten); nur einer allein, oder beide ohne crop, passen sich in den Rahmen ein (Seitenverhältnis erhalten, kein Zuschnitt).
`crop`	bool	`false`	Siehe oben - füllt den Rahmen komplett aus, statt nur hineinzupassen.
`manual_crop`	bool	`false`	Zeigt direkt nach der Dateiauswahl, noch vor dem Speichern, eine interaktive Zuschneiden-per-Drag-Oberfläche (Cropper.js). Kombiniert sich mit `width`/`height`/`crop`, statt sie zu ersetzen - `manual_crop` bestimmt, was behalten wird, die anderen Optionen wirken danach weiterhin auf das zugeschnittene Ergebnis.
`ratio`	float	-	Bindet zusammen mit `manual_crop` den Zuschneide-Rahmen an dieses Breite/Höhe-Verhältnis (z. B. `0.5` = immer doppelt so hoch wie breit), statt dem Besucher ein beliebiges Rechteck wählen zu lassen.
`watermark`	string	-	Pfad zu einer PNG-Datei, relativ zum Projektstamm, die über das gespeicherte Bild gelegt wird.
`watermark_position`	[x%, y%]	`[95, 95]`	Wo die obere linke Ecke des Wasserzeichens landet, als Prozentsatz der eigenen Breite/Höhe des Bildes.
`thumbs`	array	`[]`	Benannte, zusätzliche abgeleitete Bilder, die zusammen mit dem Hauptbild gespeichert werden - je Eintrag: `width`/`height`/`crop`/`marker` (Dateinamens-Suffix)/`folder`/`watermark`. Jeder Thumbnail wird unabhängig aus dem Original berechnet, nicht aneinander verkettet.

// Fits within 200x200, no cropping
$xcrud->change_type('auto_resize', 'image', '', ['width' => 200, 'height' => 200]);

// Fills 200x200 exactly, excess cropped
$xcrud->change_type('auto_crop', 'image', '', ['width' => 200, 'height' => 200, 'crop' => true]);

// Interactive drag-to-crop, then resized to 200x200
$xcrud->change_type('manual_crop_2', 'image', '', ['width' => 200, 'height' => 200, 'manual_crop' => true]);

// Two derived thumbnails, one watermarked, one cropped into a subfolder
$xcrud->change_type('image_with_thumbs', 'image', '', [
    'thumbs' => [
        ['width' => 300, 'marker' => '_th', 'watermark' => 'assets/watermark.png'],
        ['width' => 100, 'height' => 100, 'crop' => true, 'folder' => 'thumbs'],
    ],
]);

Konfiguration des Upload-Speicherorts

Diese Einstellungen leben in XcrudConfig, nicht pro Feld:

Einstellung	Typ	Standard	Beschreibung
`$uploadDir`	string	`'media/'`	Wohin hochgeladene Dateien tatsächlich geschrieben werden.
`$uploadMaxSize`	int	10 MB (`10 * 1024 * 1024`)	Maximale Upload-Größe in Bytes, anwendungsseitig durchgesetzt, zusätzlich zu PHPs eigenem `upload_max_filesize`.
`$uploadAllowedImageExt`	array	`['jpg', 'jpeg', 'png', 'gif', 'webp']`	Erlaubte Dateiendungen für Bild-Felder.
`$uploadAllowedFileExt`	array	eine kuratierte Liste gängiger Dokument-/Archivtypen	Erlaubte Dateiendungen für einfache Datei-Felder. Ergänzen Sie diese Liste nur um tatsächlich sichere Typen, die Sie wirklich benötigen.

Alle weiteren Einstellungen finden Sie in der XcrudConfig-Referenz.

gallery(): ein Mehrbild-Feld

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

Anders als change_type('image') ist gallery() ein Drag-Drop-Feld für viele Bilder gleichzeitig, von denen jedes als eigene Zeile in $childTable gespeichert wird - nicht als Spalte der aktuellen Tabelle. $field ist hier ein virtueller Name und gehört daher nicht in ->columns(). $childTable muss selbst eine echte, erreichbare Tabelle sein, mit mindestens einer Auto-Increment-ID, der in fk benannten Fremdschlüsselspalte, einer filename-Spalte, einer name-Spalte (eine Bildunterschrift pro Bild), einer size-Spalte und einer sort_order-Spalte, in der Drag-to-Reorder die Reihenfolge speichert.

Option	Typ	Standard	Beschreibung
`fk`	string	erforderlich	Die eigene Fremdschlüsselspalte der Kindtabelle, die auf den Primärschlüssel dieser Tabelle verweist.
`folder`	string	Feldname	Unterverzeichnis von `$uploadDir`, in das die Bilder dieser Galerie gespeichert werden.
`layout`	'grid'\|'list'	`'grid'`	`'grid'` - ein umbrechendes Raster quadratischer Thumbnails. `'list'` - eine Zeile pro Bild mit Thumbnail, bearbeitbarer Bildunterschrift, Dateigröße sowie Vorschau-/Entfernen-Schaltflächen. Drag-to-Reorder funktioniert in beiden Fällen identisch.
`width` / `height` / `crop` / `watermark` / `watermark_position` / `thumbs`	-	-	Gleiche Bedeutung wie die entsprechenden Optionen von `change_type('image')`, unabhängig auf jedes in diese Galerie hochgeladene Bild angewendet.
`max_files`	int	-	Begrenzt, wie viele Bilder diese Galerie insgesamt fassen kann; weitere Uploads werden abgelehnt, sobald das Limit erreicht ist.

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

Eine brandneue, noch nie gespeicherte Zeile hat noch keine ID, auf die Galeriebilder verweisen könnten - das Feld zeigt so lange einen deaktivierten Platzhalter "diesen Datensatz zuerst speichern" an, bis die Zeile tatsächlich existiert.