FacturaScripts

UploadedFile
in package

FinalYes

Representa un fichero subido por el cliente a través de un formulario multipart/form-data.

Esta clase es el equivalente interno de FacturaScripts a la UploadedFile de Symfony: envuelve una entrada de $_FILES y añade utilidades de validación (extensiones bloqueadas, comprobación de MIME real, verificación de imágenes mediante GD) y de movimiento del fichero temporal a su destino final.

Por seguridad bloquea de raíz cualquier extensión asociada a ejecución de PHP en el servidor (php, phar, phtml, etc.), incluso si el upload en sí es correcto: isValid() devolverá false para esos ficheros y getErrorMessage() mostrará un mensaje específico.

El flag $test permite usar la clase en tests sin pasar por is_uploaded_file() ni move_uploaded_file() (que requieren un upload HTTP real): cuando está activo se usan rename() y se asume que el fichero es válido a efectos de subida.

Table of Contents

Constants

BLOCKED_EXTENSIONS  : mixed = ['htaccess', 'htm', 'html', 'phar', 'php', 'php...
Extensiones bloqueadas para evitar la ejecución de código PHP servido desde uploads.
IMAGE_EXTENSIONS  : mixed = ['gif', 'jpeg', 'jpg', 'png', 'webp']
Extensiones admitidas como imagen válida en `isValidImage()`.
IMAGE_MIME_TYPES  : mixed = ['image/gif', 'image/jpeg', 'image/png', 'image...
Tipos MIME admitidos como imagen válida en `isValidImage()`.

Properties

$error  : int
Código de error de la subida. Coincide con las constantes UPLOAD_ERR_* de PHP (UPLOAD_ERR_OK, UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_NO_FILE, etc.).
$name  : mixed
Nombre original del fichero tal y como lo envió el cliente (no se debe confiar en él).
$size  : mixed
Tamaño del fichero en bytes según lo reportado por PHP.
$test  : bool
Si es true, la instancia se trata como un upload simulado: se omite la comprobación `is_uploaded_file()` y los movimientos se hacen con `rename()`. Pensado solo para tests.
$tmp_name  : mixed
Ruta temporal donde PHP ha guardado el fichero subido.
$type  : mixed
Tipo MIME declarado por el cliente (no fiable; usar `getMimeType()` para el real).

Methods

__construct()  : mixed
Construye la instancia a partir de un array compatible con una entrada de `$_FILES`.
extension()  : string
Devuelve la extensión del nombre original del fichero (sin el punto), o cadena vacía si no hay nombre.
getClientMimeType()  : string
Tipo MIME declarado por el cliente en la cabecera del formulario.
getClientOriginalExtension()  : string
getClientOriginalName()  : string
Nombre original normalizado sin componentes de ruta, o cadena vacía si no hay.
getErrorMessage()  : string
Devuelve un mensaje legible describiendo el estado de la subida.
getMaxFilesize()  : int
Tamaño máximo de subida permitido por la configuración de PHP, en bytes.
getMimeType()  : string
Tipo MIME real del fichero, detectado leyendo el contenido del fichero temporal con `mime_content_type()`. Devuelve cadena vacía si no hay fichero temporal o no se puede leer.
getPathname()  : string
Ruta del fichero temporal donde PHP guardó el upload, o cadena vacía si no hay.
getRealPath()  : string
Alias de `getPathname()` por compatibilidad con la API de Symfony.
getSize()  : int
Tamaño del fichero en bytes según lo reportado por PHP en la subida.
isUploaded()  : bool
Indica si el fichero proviene realmente de un upload HTTP.
isValid()  : bool
Comprueba que el fichero es seguro y se ha subido correctamente.
isValidImage()  : bool
Comprueba si el fichero es una imagen válida y segura.
move()  : bool
Mueve el fichero subido al directorio `$destiny` con el nombre `$destinyName`.
moveTo()  : bool
Mueve el fichero subido a la ruta completa `$targetPath` (incluyendo nombre de fichero).
hasBlockedExtension()  : bool
Indica si la extensión del fichero está en la lista negra de extensiones ejecutables como PHP.
hasParentDirectorySegment()  : bool
parseFilesize()  : int
Convierte un valor de configuración tipo `post_max_size` ("8M", "1G", "512K", etc.) a bytes.
sanitizeFileName()  : string

Constants

BLOCKED_EXTENSIONS

Extensiones bloqueadas para evitar la ejecución de código PHP servido desde uploads.

private mixed BLOCKED_EXTENSIONS = ['htaccess', 'htm', 'html', 'phar', 'php', 'php3', 'php4', 'php5', 'php7', 'php8', 'pht', 'phtm', 'phtml', 'phps', 'shtml']

IMAGE_EXTENSIONS

Extensiones admitidas como imagen válida en `isValidImage()`.

private mixed IMAGE_EXTENSIONS = ['gif', 'jpeg', 'jpg', 'png', 'webp']

IMAGE_MIME_TYPES

Tipos MIME admitidos como imagen válida en `isValidImage()`.

private mixed IMAGE_MIME_TYPES = ['image/gif', 'image/jpeg', 'image/png', 'image/webp']

Properties

$error

Código de error de la subida. Coincide con las constantes UPLOAD_ERR_* de PHP (UPLOAD_ERR_OK, UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_NO_FILE, etc.).

public int $error

$name

Nombre original del fichero tal y como lo envió el cliente (no se debe confiar en él).

public mixed $name

@var string

$size

Tamaño del fichero en bytes según lo reportado por PHP.

public mixed $size

@var int

$test

Si es true, la instancia se trata como un upload simulado: se omite la comprobación `is_uploaded_file()` y los movimientos se hacen con `rename()`. Pensado solo para tests.

public bool $test = false

$tmp_name

Ruta temporal donde PHP ha guardado el fichero subido.

public mixed $tmp_name

@var string

$type

Tipo MIME declarado por el cliente (no fiable; usar `getMimeType()` para el real).

public mixed $type

@var string

Methods

__construct()

Construye la instancia a partir de un array compatible con una entrada de `$_FILES`.

public __construct([array<string|int, mixed> $data = [] ]) : mixed

Solo se asignan claves que coincidan con propiedades públicas existentes; el resto se ignoran. Si un valor llega como array (caso típico de uploads múltiples donde PHP entrega arrays paralelos), se toma el primer elemento, de modo que la instancia siempre representa un único fichero.

Parameters
$data : array<string|int, mixed> = []

datos en formato $_FILES['campo'] (o un subárbol equivalente)

extension()

Devuelve la extensión del nombre original del fichero (sin el punto), o cadena vacía si no hay nombre.

public extension() : string

Se obtiene del nombre proporcionado por el cliente, por lo que no garantiza que el contenido real coincida con esa extensión. Para validar que un fichero es realmente una imagen usar isValidImage(), que combina extensión, MIME real y decodificación con GD.

Return values
string

getClientMimeType()

Tipo MIME declarado por el cliente en la cabecera del formulario.

public getClientMimeType() : string

No es fiable: el cliente puede manipularlo. Usar getMimeType() para obtener el MIME detectado a partir del contenido real del fichero.

Return values
string

getClientOriginalExtension()

public getClientOriginalExtension() : string

replaced by extension() method

Return values
string

getClientOriginalName()

Nombre original normalizado sin componentes de ruta, o cadena vacía si no hay.

public getClientOriginalName() : string
Return values
string

getErrorMessage()

Devuelve un mensaje legible describiendo el estado de la subida.

public getErrorMessage() : string

Si el fichero tiene una extensión bloqueada, se devuelve un mensaje específico aunque la subida en sí no haya tenido errores: la comprobación de extensión bloqueada tiene prioridad sobre el código UPLOAD_ERR_*.

Return values
string

getMaxFilesize()

Tamaño máximo de subida permitido por la configuración de PHP, en bytes.

public static getMaxFilesize() : int

Es el menor entre post_max_size y upload_max_filesize. Si alguna de las dos directivas está vacía o a 0 (ilimitado), se sustituye por PHP_INT_MAX para que no haga ganar a la comparación incorrectamente. El valor devuelto siempre es un entero.

Return values
int

getMimeType()

Tipo MIME real del fichero, detectado leyendo el contenido del fichero temporal con `mime_content_type()`. Devuelve cadena vacía si no hay fichero temporal o no se puede leer.

public getMimeType() : string

A diferencia de getClientMimeType(), este valor no se puede falsificar desde el cliente.

Return values
string

getPathname()

Ruta del fichero temporal donde PHP guardó el upload, o cadena vacía si no hay.

public getPathname() : string
Return values
string

getRealPath()

Alias de `getPathname()` por compatibilidad con la API de Symfony.

public getRealPath() : string
Return values
string

getSize()

Tamaño del fichero en bytes según lo reportado por PHP en la subida.

public getSize() : int
Return values
int

isUploaded()

Indica si el fichero proviene realmente de un upload HTTP.

public isUploaded() : bool

En modo $test siempre devuelve true, lo que permite simular subidas en pruebas unitarias sin necesidad de que el fichero haya pasado por el SAPI de PHP.

Return values
bool

isValid()

Comprueba que el fichero es seguro y se ha subido correctamente.

public isValid() : bool

Para ser válido debe cumplir las tres condiciones: extensión no bloqueada, código de error UPLOAD_ERR_OK y haber sido realmente subido (isUploaded()).

Return values
bool

isValidImage()

Comprueba si el fichero es una imagen válida y segura.

public isValidImage() : bool

La validación es estricta y se hace en cuatro pasos: subida correcta (isValid()), extensión en la lista blanca, MIME real (no el del cliente) en la lista blanca y, si la extensión GD está disponible, decodificación con imagecreatefromstring() para confirmar que el contenido es realmente una imagen procesable. Si GD no está cargada, se acepta la imagen tras superar las validaciones previas.

Return values
bool

move()

Mueve el fichero subido al directorio `$destiny` con el nombre `$destinyName`.

public move(string $destiny, string $destinyName) : bool

Devuelve false si el fichero no es válido (isValid()), sin tocar nada. Si $destiny no termina en separador de directorio se añade uno, de modo que el llamador no necesita preocuparse por la barra final. En modo $test se usa rename(); en producción se usa move_uploaded_file(), que solo acepta ficheros realmente subidos vía HTTP.

Parameters
$destiny : string

directorio destino (con o sin separador final)

$destinyName : string

nombre que tendrá el fichero en destino

Return values
bool —

true si el movimiento se realizó correctamente

moveTo()

Mueve el fichero subido a la ruta completa `$targetPath` (incluyendo nombre de fichero).

public moveTo(string $targetPath) : bool

Devuelve false si el fichero no es válido. En modo $test usa rename(); en producción usa move_uploaded_file(). A diferencia de move(), aquí el llamador es responsable de construir la ruta completa.

Parameters
$targetPath : string
Return values
bool

hasBlockedExtension()

Indica si la extensión del fichero está en la lista negra de extensiones ejecutables como PHP.

private hasBlockedExtension() : bool
Return values
bool

hasParentDirectorySegment()

private static hasParentDirectorySegment(string $path) : bool
Parameters
$path : string
Return values
bool

parseFilesize()

Convierte un valor de configuración tipo `post_max_size` ("8M", "1G", "512K", etc.) a bytes.

private static parseFilesize(string $size) : int

Replica la lógica de PHP para parsear estos valores: la parte numérica admite prefijos de base (0x para hex, 0 para octal) y el sufijo final (k/m/g/t) se aplica como múltiplo de 1024 acumulativo mediante caída en cascada del switch. Devuelve 0 si la cadena está vacía.

Parameters
$size : string
Return values
int

sanitizeFileName()

private static sanitizeFileName(string $fileName) : string
Parameters
$fileName : string
Return values
string
On this page

Search results