Transloadit
Última actualización:

Filtrado eficiente de archivos en PHP con código abierto

Kevin van Zonneveld
Kevin van Zonneveld
Cofundador · Ámsterdam, Países Bajos ·

El filtrado y el saneamiento de las entradas son aspectos críticos de la seguridad y la integridad de los datos en las aplicaciones web. En PHP, varias excelentes bibliotecas de código abierto simplifican estas tareas y ofrecen soluciones robustas frente a amenazas de seguridad comunes como el cross-site scripting (XSS) y las subidas de archivos maliciosos. Veamos algunas bibliotecas potentes y con mantenimiento activo que pueden dotar a tus proyectos de PHP de capacidades de filtrado eficaces.

Por qué importa el filtrado de entradas

El filtrado comprueba si los datos cumplen los requisitos de tu aplicación. No demuestra que un archivo sea inofensivo ni sustituye a las sentencias SQL preparadas. Sin un filtrado y un saneamiento adecuados, tu aplicación podría ser vulnerable a ataques como XSS, inyección de SQL o el procesamiento de subidas de archivos dañinos. Un filtrado eficaz ayuda a mantener la integridad de los datos, protege a tus usuarios y evita brechas de seguridad.

HTML Purifier para contenido HTML seguro

Cuando trabajas con HTML enviado por los usuarios (como comentarios o contenido de un editor de texto enriquecido), HTML Purifier es una herramienta esencial. Está diseñado específicamente para sanear contenido HTML, de modo que cumpla los estándares y esté a salvo de ataques XSS al eliminar el código malicioso. La biblioteca cuenta con mantenimiento activo, es compatible con las versiones modernas de PHP (incluido PHP 8.x) y es altamente configurable.

Instalación de HTML Purifier

La forma recomendada de instalar HTML Purifier es mediante Composer:

composer require ezyang/htmlpurifier:^4.19

Uso de HTML Purifier

Este es un ejemplo básico de cómo sanear una entrada HTML:

<?php
require_once 'vendor/autoload.php';

$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.Allowed', 'p');
$purifier = new HTMLPurifier($config);

$dirty_html = '<script>alert("XSS Attack!");</script><p style="color: blue;" onclick="alert(\'another attack\')">This is safe content.</p>';
$clean_html = $purifier->purify($dirty_html);

echo $clean_html; // Outputs: <p>This is safe content.</p>
// The allowlist removes scripts, event handlers, and styles.
?>

Configuración avanzada

HTML Purifier ofrece amplias opciones de configuración para adaptar las reglas de filtrado a tus necesidades concretas:

<?php
require_once 'vendor/autoload.php';

$config = HTMLPurifier_Config::createDefault();

// Allow only specific HTML elements and attributes
$config->set('HTML.Allowed', 'p[style],b,i,em,strong,a[href|title],ul,ol,li,br');

// Ensure links open in a new tab and add rel="noopener noreferrer"
$config->set('HTML.TargetBlank', true);
$config->set('HTML.Nofollow', true); // Adds rel="nofollow"
$config->set('HTML.TargetNoreferrer', true); // Adds rel="noreferrer"
$config->set('HTML.TargetNoopener', true); // Adds rel="noopener"


// Allow specific CSS properties (e.g., text-align)
$config->set('CSS.AllowedProperties', 'text-align');

// Create custom definitions if needed (advanced)
// $def = $config->getHTMLDefinition(true);
// $def->addAttribute('a', 'data-custom', 'Text'); // Example: Allow a custom data attribute

$purifier = new HTMLPurifier($config);

$dirty_html = '<a href="http://example.com" onclick="badJs()" title="Example">Click Me</a><p style="text-align:center; color:red;">Centered text</p>';
$clean_html = $purifier->purify($dirty_html);

// Outputs something like:
// <a href="http://example.com" title="Example" target="_blank" rel="nofollow noopener noreferrer">Click Me</a><p style="text-align:center;">Centered text</p>
echo $clean_html;
?>

Bibliotecas modernas de validación para PHP

Para la validación y el filtrado de datos en general, más allá del contenido HTML (por ejemplo, validar entradas de formularios, parámetros de API o subidas de archivos), PHP ofrece varias bibliotecas modernas y con mantenimiento activo.

Respect\Validation

Respect\Validation es una biblioteca de validación popular y potente, conocida por su interfaz fluida y encadenable, que hace que las reglas de validación sean fáciles de leer y de escribir.

Instalación

composer require respect/validation:^2.4

Uso básico

<?php
require_once 'vendor/autoload.php';
use Respect\Validation\Validator as v;
use Respect\Validation\Exceptions\NestedValidationException;

// Basic string validation
$username = 'johndoe123';
try {
    v::alnum()->noWhitespace()->length(3, 15)->assert($username);
    echo "Username is valid.\n";
} catch (NestedValidationException $exception) {
    echo "Username validation failed: " . $exception->getFullMessage() . "\n";
}

// Email validation
$email = 'invalid-email';
if (v::email()->validate($email)) {
    echo "Email is valid.\n";
} else {
    echo "Email is invalid.\n";
}

// Numeric validation with range
$age = 17;
if (v::numericVal()->positive()->between(18, 99)->validate($age)) {
    echo "Age is valid.\n";
} else {
    echo "Age is invalid (must be between 18 and 99).\n";
}

// Basic file property validation (checks if path exists and is a file)
$filePath = '/path/to/your/file.txt'; // Replace with an actual path for testing
if (v::file()->validate($filePath)) {
    echo "File path points to a file.\n";
} else {
    echo "File path is not a valid file.\n";
}

// More specific file validation (e.g., check extension, mimetype, size)
// Note: These often require checking properties from $_FILES in a web context
$allowedExtensions = ['jpg', 'png', 'gif'];
$fileExtension = 'jpg';
if (v::in($allowedExtensions)->validate($fileExtension)) {
    echo "File extension is allowed.\n";
}
?>

Filtrado de arrays de datos

Respect\Validation destaca en la validación de datos estructurados como los arrays (por ejemplo, datos de $_POST).

<?php
require_once 'vendor/autoload.php';
use Respect\Validation\Validator as v;
use Respect\Validation\Exceptions\NestedValidationException;

$userData = [
    'username' => 'john_doe',
    'email' => 'john@example.com',
    'age' => 28,
    'homepage' => 'invalid-url'
];

$userValidator = v::key('username', v::stringType()->length(3, 32))
                  ->key('email', v::email())
                  ->key('age', v::numericVal()->between(18, 99))
                  ->keyNested('homepage', v::url(), false); // 'false' makes homepage optional

try {
    $userValidator->assert($userData);
    echo "User data is valid!\n";
} catch (NestedValidationException $exception) {
    echo "User data validation failed:\n";
    // Get specific error messages
    print_r($exception->getMessages());
    /* Example Output:
    Array
    (
        [homepage] => "invalid-url" must be a valid URL
    )
    */
}
?>

Componente Symfony Validator

El componente Symfony Validator ofrece un framework de validación robusto y flexible, especialmente adecuado para las aplicaciones orientadas a objetos y para las que ya usan el ecosistema de Symfony. Admite la validación mediante atributos (PHP 8+), anotaciones, YAML o XML.

Instalación

composer require symfony/validator:^7.4 symfony/mime:^7.4

Uso básico con atributos (PHP 8.2+)

<?php
require_once 'vendor/autoload.php';

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Validation;

class User
{
    #[Assert\NotBlank(message: "Username cannot be blank.")]
    #[Assert\Length(min: 3, max: 32, minMessage: "Username must be at least {{ limit }} characters long.")]
    private string $username = '';

    #[Assert\NotBlank]
    #[Assert\Email(message: "The email '{{ value }}' is not a valid email.")]
    private string $email = '';

    #[Assert\Range(min: 18, max: 99, notInRangeMessage: "Age must be between {{ min }} and {{ max }}.")]
    private ?int $age = null; // Use nullable type for optional fields

    // --- Getters and Setters ---
    public function getUsername(): string { return $this->username; }
    public function setUsername(string $username): void { $this->username = $username; }
    public function getEmail(): string { return $this->email; }
    public function setEmail(string $email): void { $this->email = $email; }
    public function getAge(): ?int { return $this->age; }
    public function setAge(?int $age): void { $this->age = $age; }
}

// Create validator instance
$validator = Validation::createValidatorBuilder()
    ->enableAttributeMapping()
    ->getValidator();

$user = new User();
$user->setUsername('jo'); // Too short
$user->setEmail('invalid-email');
$user->setAge(15); // Too young

$violations = $validator->validate($user);

if (count($violations) > 0) {
    echo "Validation failed:\n";
    foreach ($violations as $violation) {
        echo "- Property '{$violation->getPropertyPath()}': {$violation->getMessage()}\n";
    }
} else {
    echo "User object is valid!\n";
}
?>

Validación de subidas de archivos

Symfony Validator también puede validar archivos subidos (que normalmente se representan como objetos Symfony\Component\HttpFoundation\File\UploadedFile cuando se usa con el framework, aunque las restricciones también pueden aplicarse a rutas de archivo o a objetos SplFileInfo).

<?php
require_once 'vendor/autoload.php';

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\Validation;

// Assume $file is an instance of UploadedFile from a request
// For standalone usage, you might validate SplFileInfo objects or paths directly
class Document
{
    #[Assert\File(
        maxSize: '5M', // 5 Megabytes
        mimeTypes: ['application/pdf', 'application/x-pdf'],
        mimeTypesMessage: 'Please upload a valid PDF document (max 5MB).'
    )]
    // In a real app, this would likely be an UploadedFile object or SplFileInfo
    public $file;
}

$validator = Validation::createValidatorBuilder()
    ->enableAttributeMapping()
    ->getValidator();

$doc = new Document();
// Simulate an invalid file (e.g., wrong type or too large)
// In a real scenario, you'd pass the actual UploadedFile object or SplFileInfo
// For demonstration, let's validate a path to a non-PDF file:
$doc->file = new \SplFileInfo(__FILE__); // Using this script file as an example

$violations = $validator->validate($doc);

if (count($violations) > 0) {
    echo "File validation failed:\n";
    foreach ($violations as $violation) {
        echo "- Property '{$violation->getPropertyPath()}': {$violation->getMessage()}\n";
    }
} else {
    echo "File is valid!\n";
}
?>

Cuándo usar cada biblioteca

  • HTML Purifier: la opción de referencia específicamente para sanear contenido HTML generado por los usuarios y prevenir ataques XSS. Úsalo para procesar la entrada de editores de texto enriquecido, de comentarios o de cualquier campo donde los usuarios puedan enviar HTML.
  • Respect\Validation: excelente para la validación de entradas de propósito general (cadenas, números, emails, arrays, etc.) con una API clara y fluida. Ideal para validar datos de formularios, parámetros de solicitudes de API y propiedades básicas de los archivos.
  • Symfony Validator: idóneo para aplicaciones construidas con un enfoque orientado a objetos, en especial las que usan el framework Symfony o las que quieren una validación robusta integrada con objetos y atributos/anotaciones. Ofrece funciones potentes para escenarios de validación complejos, incluidos los grupos de validación y las restricciones personalizadas.

Casos de uso prácticos

Validación segura de subidas de archivos (con Respect\Validation)

Este ejemplo valida el tamaño real y el tipo MIME detectado de una imagen subida. Los campos type, size y el nombre de archivo original no son prueba de que el contenido sea seguro. Devuelve una extensión elegida por el servidor o null cuando la validación falle. Las comprobaciones del tipo de contenido aún deben combinarse con una decodificación de imágenes, un análisis y unos controles de acceso adecuados.

<?php
require_once 'vendor/autoload.php';
use Respect\Validation\Validator as v;
use Respect\Validation\Exceptions\NestedValidationException;

function validateUploadedFile(array $file): ?string {
    // Basic checks for upload errors and existence
    if (($file['error'] ?? null) !== UPLOAD_ERR_OK
        || !is_string($file['tmp_name'] ?? null)
        || !is_uploaded_file($file['tmp_name'])) {
        return null;
    }

    $validator = v::key('tmp_name', v::file()->readable());

    try {
        $validator->assert($file);
        v::intType()->positive()->max(5 * 1024 * 1024)->assert(filesize($file['tmp_name']));
        $mime = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
        $extensions = ['image/jpeg' => 'jpg', 'image/png' => 'png', 'image/gif' => 'gif'];
        return $extensions[$mime] ?? null;
    } catch (NestedValidationException $exception) {
        error_log('Invalid uploaded file properties');
        return null;
    } catch (\Throwable $e) {
        error_log('File validation failed');
        return null;
    }
}

// --- Example Usage ---
// Simulate a POST request with a file upload
// In a real script, you'd use $_FILES directly.
/*
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['upload'])) {
    $extension = validateUploadedFile($_FILES['upload']);
    if ($extension !== null) {
        // Provision this private directory outside the webroot, writable only by the app.
        $directory = '/var/lib/myapp/uploads';
        $safe_filename = bin2hex(random_bytes(16)) . '.' . $extension;
        $destination = $directory . '/' . $safe_filename;
        if (move_uploaded_file($_FILES['upload']['tmp_name'], $destination)) {
            echo 'File uploaded successfully.';
        } else {
            error_log("Failed to move uploaded file '{$_FILES['upload']['tmp_name']}' to '$destination'");
            echo "Error processing file upload.";
        }
    } else {
        echo "Invalid file upload detected.";
    }
} else {
     // Handle cases where the form wasn't submitted correctly or file wasn't uploaded
     // echo "No file uploaded or invalid request.";
}
*/
?>

Saneamiento de las entradas del usuario para su almacenamiento en la base de datos

Normaliza el texto antes de validarlo y, después, sanea el HTML permitido. Usa siempre sentencias preparadas al almacenar estos valores; el saneamiento de HTML no hace que la interpolación de cadenas en SQL sea segura.

<?php
require_once 'vendor/autoload.php';
use Respect\Validation\Validator as v;
use Respect\Validation\Exceptions\NestedValidationException;

// Setup HTML Purifier
$config = HTMLPurifier_Config::createDefault();
$config->set('HTML.Allowed', 'p,b,i,em,strong,br'); // Allow only basic formatting
$purifier = new HTMLPurifier($config);

// Simulate POST data
$postData = [
    'username' => ' test_user ', // Contains extra whitespace
    'email' => 'test@example.com',
    'bio' => '<script>alert("bad")</script>This is a <strong>bio</strong> with <a href="#">link</a>.'
];

// Define validation rules
$validator = v::keySet(
    v::key('username', v::stringType()->alnum('_-')->noWhitespace()->length(3, 20)),
    v::key('email', v::email()),
    v::key('bio', v::stringType()->length(0, 500)) // Validate length before sanitizing
);

try {
    $postData['username'] = trim($postData['username']);
    // Validate the normalized input.
    $validator->assert($postData);

    // 2. Sanitize/Normalize data after validation passes
    $validatedData = [
        'username' => trim($postData['username']), // Trim whitespace
        'email' => $postData['email'], // Already validated format
        'bio' => $purifier->purify($postData['bio']) // Sanitize HTML
    ];

    // Store with prepared statements, and escape plain text when rendering it.
    echo "User data validated and sanitized successfully!\n";
    print_r($validatedData);
    // Example: $db->insert('users', $validatedData);

} catch (NestedValidationException $exception) {
    echo "Invalid user data:\n";
    // Log the detailed errors for debugging, show generic message to user
    error_log("Validation errors: " . $exception->getFullMessage());
}
?>

Mejores prácticas de filtrado y saneamiento en PHP

  1. Defensa en profundidad: combina varias capas de validación (del lado del cliente para la UX, del lado del servidor para la seguridad) y de saneamiento.
  2. Valida todo: trata toda entrada externa (POST, GET, cabeceras, cookies, subidas de archivos, datos de API) como no confiable.
  3. El lado del servidor es crucial: nunca dependas únicamente de la validación del lado del cliente; se puede eludir con facilidad.
  4. Usa listas de permitidos, no listas de bloqueados: especifica exactamente qué está permitido (por ejemplo, los caracteres o las etiquetas HTML admitidos) en lugar de intentar enumerar todo lo que no lo está.
  5. Escapado contextual de la salida: escapa siempre los datos de la forma adecuada al contexto donde se mostrarán (HTML, JavaScript, SQL, etc.) para prevenir XSS y otros ataques de inyección. Usa funciones como htmlspecialchars() en el contexto HTML. Usa sentencias preparadas para SQL.
  6. Usa bibliotecas consolidadas: aprovecha bibliotecas bien mantenidas como HTML Purifier, Respect\Validation o Symfony Validator en lugar de crear tu propia lógica de filtrado.
  7. Mantén las bibliotecas actualizadas: actualiza con regularidad tus dependencias (composer update) para parchear vulnerabilidades de seguridad.
  8. Usa declaraciones de tipos y tipado estricto: activa el tipado estricto de PHP (declare(strict_types=1);) y usa declaraciones de tipos en los argumentos de las funciones y en los tipos de retorno para detectar errores pronto.
  9. Gestiona los errores con elegancia: muestra mensajes de error claros a los usuarios cuando falle la validación, pero evita exponer detalles sensibles del sistema. Registra los errores detallados para los desarrolladores.
  10. Registra los fallos de validación: vigila los registros en busca de fallos de validación repetidos, que podrían indicar actividad maliciosa o errores en la aplicación.
  11. Protege las subidas de archivos: más allá de la validación básica, comprueba los tipos de archivo con herramientas del lado del servidor (como finfo), almacena los archivos subidos fuera del webroot si es posible, usa nombres de archivo no predecibles y establece los permisos adecuados.

El filtrado de archivos de Transloadit

Para flujos de trabajo complejos de procesamiento de archivos, incluido un filtrado robusto basado en metadatos antes de que comience el procesamiento, un servicio en la nube puede resultar beneficioso. Transloadit ofrece potentes capacidades de filtrado de archivos a través de su Robot 🤖 /file/filter. Puedes definir condiciones basadas en propiedades del archivo como el tipo MIME, el tamaño, las dimensiones y más dentro de una Assembly.

Este es un ejemplo de condiciones de filtrado dentro de un Assembly Step de Transloadit:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "filter_images": {
      "use": ":original",
      "robot": "/file/filter",
      "condition_type": "and",
      "accepts": [
        ["${file.mime}", "regex", "image"],
        ["${file.meta.width}", ">=", 100]
      ],
      "declines": [["${file.size}", ">", 10485760]]
    }
  }
}

Este filtro solo acepta archivos de imagen que tengan al menos 100 píxeles de ancho y rechaza cualquier archivo de más de 10 MiB (10 * 1024 * 1024 bytes).

Incluso puedes usar condiciones basadas en JavaScript para una lógica más compleja:

{
  "accepts": "${file.meta.width > file.meta.height && file.size < 500000}"
}

Esta condición coincidiría con los archivos más anchos que altos y de menos de 500.000 bytes.

Explora nuestro SDK de PHP para integrar fácilmente las capacidades de procesamiento y filtrado de archivos de Transloadit en tus aplicaciones de PHP.

#php#security#open-source#file-filtering-service

👩‍💻 Únete a más de 20k desarrolladores

Suscríbete a nuestro boletín mensual  (English) para recibir enlaces directos a 3 artículos exclusivos sobre tecnología y 2 actualizaciones de producto. Ni más ni menos.

Subida y encoding de archivos. Sin complicaciones.

Transloadit optimiza el manejo de archivos para desarrolladores, con la confianza de marcas como Coursera y The New York Times. Somos reconocidos por una API confiable, soporte de primer nivel y un firme compromiso con el código abierto, con proyectos como Uppy y el protocolo tus que marcan estándares en el procesamiento de archivos.

RegístrateAgenda una demo

No necesitas tarjeta de crédito

Cancela en cualquier momento