Téléversements de fichiers et d'images

Les types de champ de change_type() pour les téléversements de fichiers et d'images, ainsi que gallery() pour un champ multi-images avec réorganisation par glisser-déposer.

Téléversements de fichiers simples

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

change_type($field, 'file', '', $extra) transforme un champ en zone de dépôt de fichiers. Ses options $extra :

Option	Type	Défaut	Description
`not_rename`	bool	`false`	Conserve le nom d'origine du fichier téléversé au lieu d'un nom sûr généré automatiquement. Le nom est tout de même assaini (séparateurs de chemin/traversée de répertoires supprimés) même avec cette option activée - il n'est simplement pas rendu aléatoire.
`preview`	false\|true\|'download'\|'modal'\|'edit'	`false`	Ce que fait un clic sur le nom du fichier. `false`/`'download'` - un simple lien de téléchargement. `true`/`'modal'` - ouvre une fenêtre modale de prévisualisation intégrée (une iframe sur le fichier) avec un bouton Télécharger à côté. `'edit'` - ouvre le formulaire d'édition de cette ligne à la place, utile lorsque le vrai rôle du champ est "l'enregistrement auquel ce fichier est rattaché".

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

Téléversements d'images

change_type($field, 'image', '', $extra) ajoute un traitement de redimensionnement/recadrage/filigrane/miniature en plus d'un téléversement simple :

Option	Type	Défaut	Description
`width` / `height`	int	-	Cible de redimensionnement automatique. Les deux + `crop`=true remplit exactement la zone (rapport d'aspect conservé, excédent recadré) ; l'un des deux seul, ou les deux sans crop, s'ajuste à l'intérieur de la zone (rapport d'aspect conservé, sans recadrage).
`crop`	bool	`false`	Voir ci-dessus - remplit la zone au lieu de simplement s'y ajuster.
`manual_crop`	bool	`false`	Affiche une interface interactive de recadrage par glisser (Cropper.js) juste après le choix d'un fichier, avant son enregistrement. Se combine avec `width`/`height`/`crop` plutôt que de les remplacer - `manual_crop` détermine ce qui est conservé, les autres options continuent de s'appliquer ensuite au résultat recadré.
`ratio`	float	-	Avec `manual_crop`, verrouille la zone de recadrage à ce rapport largeur/hauteur (ex. `0.5` = toujours deux fois plus haute que large) au lieu de laisser le visiteur choisir un rectangle libre.
`watermark`	string	-	Chemin vers un PNG, relatif à la racine du projet, superposé à l'image enregistrée.
`watermark_position`	[x%, y%]	`[95, 95]`	Où atterrit le coin supérieur gauche du filigrane, en pourcentage de la largeur/hauteur propre de l'image.
`thumbs`	array	`[]`	Images dérivées supplémentaires nommées, enregistrées à côté de l'image principale - chaque élément : `width`/`height`/`crop`/`marker` (suffixe de nom de fichier)/`folder`/`watermark`. Chaque miniature est redimensionnée indépendamment à partir de l'original, sans être chaînée aux autres.

// S'ajuste dans 200x200, sans recadrage
$xcrud->change_type('auto_resize', 'image', '', ['width' => 200, 'height' => 200]);

// Remplit exactement 200x200, excédent recadré
$xcrud->change_type('auto_crop', 'image', '', ['width' => 200, 'height' => 200, 'crop' => true]);

// Recadrage interactif par glisser, puis redimensionné en 200x200
$xcrud->change_type('manual_crop_2', 'image', '', ['width' => 200, 'height' => 200, 'manual_crop' => true]);

// Deux miniatures dérivées, l'une avec filigrane, l'autre recadrée dans un sous-dossier
$xcrud->change_type('image_with_thumbs', 'image', '', [
    'thumbs' => [
        ['width' => 300, 'marker' => '_th', 'watermark' => 'assets/watermark.png'],
        ['width' => 100, 'height' => 100, 'crop' => true, 'folder' => 'thumbs'],
    ],
]);

Configuration du stockage des téléversements

Ces réglages se trouvent dans XcrudConfig, pas par champ :

Réglage	Type	Défaut	Description
`$uploadDir`	string	`'media/'`	Où les fichiers téléversés sont réellement écrits.
`$uploadMaxSize`	int	10 Mo (`10 * 1024 * 1024`)	Taille maximale de téléversement en octets, appliquée côté application en plus du propre `upload_max_filesize` de PHP.
`$uploadAllowedImageExt`	array	`['jpg', 'jpeg', 'png', 'gif', 'webp']`	Extensions autorisées pour les champs image.
`$uploadAllowedFileExt`	array	une liste sélectionnée de types de documents/archives courants	Extensions autorisées pour les champs de fichier simples. N'ajoutez à cette liste que des types réellement sûrs et réellement nécessaires.

Voir la Référence XcrudConfig pour tous les autres réglages.

gallery() : un champ multi-images

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

Contrairement à change_type('image'), gallery() est un champ glisser-déposer pour plusieurs images à la fois, chacune enregistrée comme sa propre ligne dans $childTable - et non comme une colonne de la table courante. $field est ici un nom virtuel, il ne figure donc pas dans ->columns(). $childTable doit elle-même être une table réelle et accessible, avec au minimum un id auto-incrémenté, la colonne de clé étrangère nommée dans fk, une colonne filename, une colonne name (une légende par image), une colonne size, et une colonne sort_order dans laquelle le glisser-déposer persiste l'ordre.

Option	Type	Défaut	Description
`fk`	string	requis	La colonne de clé étrangère de la table enfant référençant la clé primaire de cette table.
`folder`	string	nom du champ	Sous-répertoire de `$uploadDir` dans lequel les images de cette galerie sont enregistrées.
`layout`	'grid'\|'list'	`'grid'`	`'grid'` - une grille de miniatures carrées à la ligne. `'list'` - une ligne par image avec une miniature, une légende modifiable, la taille du fichier, et des boutons Aperçu/Supprimer. Le glisser-déposer fonctionne de manière identique dans les deux cas.
`width` / `height` / `crop` / `watermark` / `watermark_position` / `thumbs`	-	-	Même signification que les options équivalentes de `change_type('image')`, appliquées indépendamment à chaque image téléversée dans cette galerie.
`max_files`	int	-	Plafonne le nombre total d'images que cette galerie peut contenir ; les téléversements suivants sont rejetés une fois la limite atteinte.

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

Une nouvelle ligne jamais encore enregistrée n'a pas encore d'id auquel les images de la galerie pourraient se référer - le champ affiche un espace réservé désactivé "enregistrez d'abord cet enregistrement" tant que la ligne n'existe pas réellement.