Subida de archivos e imágenes

Tipos de campo de change_type() para subir archivos e imágenes, además de gallery() para un campo multi-imagen con reordenación por arrastre.

Subida de archivos simples

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

change_type($field, 'file', '', $extra) convierte un campo en una zona de arrastre de archivos. Sus opciones $extra:

Opción	Tipo	Predeterminado	Descripción
`not_rename`	bool	`false`	Conserva el nombre original del archivo subido en lugar de generar uno seguro. El nombre se sigue saneando (se eliminan separadores de ruta/traversal) incluso con esto activado - simplemente no se aleatoriza.
`preview`	false\|true\|'download'\|'modal'\|'edit'	`false`	Qué ocurre al hacer clic en el nombre del archivo. `false`/`'download'` - un simple enlace de descarga. `true`/`'modal'` - abre una ventana modal de vista previa dentro de la app (un iframe sobre el archivo) con un botón de descarga al lado. `'edit'` - abre en su lugar el propio formulario de edición de esa fila, útil cuando el propósito real del campo es "el registro al que está adjunto este archivo".

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

Subida de imágenes

change_type($field, 'image', '', $extra) añade procesamiento de redimensionado/recorte/marca de agua/miniatura por encima de una subida simple:

Opción	Tipo	Predeterminado	Descripción
`width` / `height`	int	-	Objetivo de redimensionado automático. Ambos + `crop`=true rellena exactamente el recuadro (se conserva la proporción, se recorta el exceso); solo uno, o ambos sin crop, ajusta dentro del recuadro (se conserva la proporción, sin recorte).
`crop`	bool	`false`	Ver arriba - rellena el recuadro en lugar de solo ajustar dentro de él.
`manual_crop`	bool	`false`	Muestra una interfaz interactiva de recorte por arrastre (Cropper.js) justo después de elegir un archivo, antes de guardarlo. Se combina con `width`/`height`/`crop` en lugar de sustituirlos - `manual_crop` controla qué se conserva, los demás se siguen aplicando después al resultado recortado.
`ratio`	float	-	Con `manual_crop`, fija el recuadro de recorte a esta proporción ancho/alto (p. ej. `0.5` = siempre el doble de alto que de ancho) en lugar de dejar que el visitante elija cualquier rectángulo.
`watermark`	string	-	Ruta a un PNG, relativa a la raíz del proyecto, superpuesto sobre la imagen guardada.
`watermark_position`	[x%, y%]	`[95, 95]`	Dónde cae la esquina superior izquierda de la marca de agua, como porcentaje del propio ancho/alto de la imagen.
`thumbs`	array	`[]`	Imágenes derivadas adicionales con nombre, guardadas junto a la principal - cada elemento: `width`/`height`/`crop`/`marker` (sufijo del nombre de archivo)/`folder`/`watermark`. Cada miniatura se redimensiona de forma independiente a partir del original, no se encadenan entre sí.

// 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'],
    ],
]);

Configuración del almacenamiento de subidas

Estos ajustes viven en XcrudConfig, no por campo:

Ajuste	Tipo	Predeterminado	Descripción
`$uploadDir`	string	`'media/'`	Dónde se escriben realmente los archivos subidos.
`$uploadMaxSize`	int	10 MB (`10 * 1024 * 1024`)	Tamaño máximo de subida en bytes, aplicado del lado de la aplicación además del propio `upload_max_filesize` de PHP.
`$uploadAllowedImageExt`	array	`['jpg', 'jpeg', 'png', 'gif', 'webp']`	Extensiones permitidas para campos de imagen.
`$uploadAllowedFileExt`	array	una lista seleccionada de tipos comunes de documento/archivo comprimido	Extensiones permitidas para campos de archivo simples. Añade a esta lista solo tipos genuinamente seguros que realmente necesites.

Consulta la Referencia de XcrudConfig para el resto de ajustes.

gallery(): un campo multi-imagen

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

A diferencia de change_type('image'), gallery() es un campo de arrastrar y soltar para muchas imágenes a la vez, cada una guardada como su propia fila en $childTable - no una columna de la tabla actual. Aquí $field es un nombre virtual, así que no se incluye en ->columns(). $childTable debe ser en sí misma una tabla real y accesible, con como mínimo un id autoincremental, la columna de clave foránea nombrada en fk, una columna filename, una columna name (un título por imagen), una columna size y una columna sort_order en la que persiste la reordenación por arrastre.

Opción	Tipo	Predeterminado	Descripción
`fk`	string	obligatorio	La propia columna de clave foránea de la tabla hija que hace referencia a la clave primaria de esta tabla.
`folder`	string	nombre del campo	Subdirectorio de `$uploadDir` en el que se guardan las imágenes de esta galería.
`layout`	'grid'\|'list'	`'grid'`	`'grid'` - una cuadrícula ajustable de miniaturas cuadradas. `'list'` - una fila por imagen con una miniatura, título editable, tamaño de archivo y botones de vista previa/eliminar. La reordenación por arrastre funciona igual en ambos casos.
`width` / `height` / `crop` / `watermark` / `watermark_position` / `thumbs`	-	-	El mismo significado que las propias opciones de `change_type('image')`, aplicado de forma independiente a cada imagen subida a esta galería.
`max_files`	int	-	Limita cuántas imágenes puede contener esta galería en total; las subidas adicionales se rechazan al alcanzar el límite.

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

Una fila recién creada y nunca guardada todavía no tiene id al que puedan hacer referencia las imágenes de la galería - el campo muestra un marcador de posición deshabilitado de "guarda primero este registro" hasta que la fila realmente exista.