image validation

VERSIONLOG.md

@@ -1,4 +1,5 @@
 ## 0.7.11
+* Added IsImage.
 
 ## 0.7.10 2026-01-13
 

composer.json

@@ -21,5 +21,10 @@
         "psr-4": {
             "Neuron\\": "src/"
         }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Tests\\": "tests/"
+        }
     }
 }

src/Validation/IsImage.php

@@ -0,0 +1,283 @@
+<?php
+
+namespace Neuron\Validation;
+
+/**
+ * Validates image data, supporting base64 encoded images with optional MIME type and size constraints.
+ */
+class IsImage extends Base
+{
+	private array $allowedMimeTypes;
+	private ?int $maxSize;
+	private bool $checkImageData;
+	private bool $allowSvg;
+
+	/**
+	 * @param array $allowedMimeTypes List of allowed MIME types (e.g., ['image/jpeg', 'image/png'])
+	 * @param int|null $maxSize Maximum file size in bytes (null for no limit)
+	 * @param bool $checkImageData Whether to validate the actual image data (requires decoding)
+	 * @param bool $allowSvg Whether to allow SVG images (default: false for security - SVG can contain scripts)
+	 */
+	public function __construct(
+		array $allowedMimeTypes = [ 'image/jpeg', 'image/png', 'image/gif', 'image/webp' ],
+		?int $maxSize = null,
+		bool $checkImageData = true,
+		bool $allowSvg = false
+	)
+	{
+		parent::__construct();
+		$this->allowedMimeTypes = $allowedMimeTypes;
+		$this->maxSize = $maxSize;
+		$this->checkImageData = $checkImageData;
+		$this->allowSvg = $allowSvg;
+
+		// If SVG is explicitly allowed AND we have MIME type restrictions, add SVG to allowed list
+		// Don't add if allowedMimeTypes is empty (meaning allow all types)
+		if( $this->allowSvg && !empty( $this->allowedMimeTypes ) && !in_array( 'image/svg+xml', $this->allowedMimeTypes, true ) )
+		{
+			$this->allowedMimeTypes[] = 'image/svg+xml';
+		}
+	}
+
+	/**
+	 * @param mixed $value
+	 * @return bool
+	 */
+	protected function validate( mixed $value ) : bool
+	{
+		if( !is_string( $value ) )
+		{
+			return false;
+		}
+
+		// Empty string is not a valid image
+		if( $value === '' )
+		{
+			return false;
+		}
+
+		// Check if it's a data URI
+		if( strpos( $value, 'data:' ) === 0 )
+		{
+			return $this->validateDataUri( $value );
+		}
+
+		// Otherwise, treat it as base64 encoded image data
+		return $this->validateBase64Image( $value );
+	}
+
+	/**
+	 * Validates a data URI formatted image.
+	 *
+	 * @param string $dataUri
+	 * @return bool
+	 */
+	private function validateDataUri( string $dataUri ) : bool
+	{
+		// Parse data URI: data:[<mediatype>][;base64],<data>
+		// Use 's' modifier to allow . to match newlines in base64 data
+		$pattern = '/^data:([a-zA-Z0-9][a-zA-Z0-9\/+\-]*);base64,(.+)$/s';
+
+		if( !preg_match( $pattern, $dataUri, $matches ) )
+		{
+			return false;
+		}
+
+		$mimeType = strtolower( $matches[1] ); // Normalize to lowercase per RFC 2045
+		$base64Data = $matches[2];
+
+		// Check MIME type (case-insensitive per RFC 2045)
+		if( !empty( $this->allowedMimeTypes ) && !$this->isMimeTypeAllowed( $mimeType ) )
+		{
+			return false;
+		}
+
+		// Validate base64 data
+		return $this->validateBase64Image( $base64Data );
+	}
+
+	/**
+	 * Validates base64 encoded image data.
+	 *
+	 * @param string $base64Data
+	 * @return bool
+	 */
+	private function validateBase64Image( string $base64Data ) : bool
+	{
+		// Remove any whitespace
+		$cleanData = preg_replace( '/\s+/', '', $base64Data );
+
+		// Attempt to decode
+		$decoded = base64_decode( $cleanData, true );
+
+		if( $decoded === false )
+		{
+			return false;
+		}
+
+		// Check size constraint
+		if( $this->maxSize !== null && strlen( $decoded ) > $this->maxSize )
+		{
+			return false;
+		}
+
+		// Always validate image data to check MIME type restrictions
+		// Even when checkImageData is false, we need to detect the type for MIME validation
+		// but we can skip the more expensive image content validation
+		if( !empty( $this->allowedMimeTypes ) )
+		{
+			// Detect the image type from signatures
+			$detectedType = $this->detectImageType( $decoded );
+
+			// Check for SVG if:
+			// 1. allowSvg is true (general SVG support enabled), OR
+			// 2. 'image/svg+xml' is explicitly in allowedMimeTypes
+			$svgExplicitlyAllowed = $this->isMimeTypeAllowed( 'image/svg+xml' );
+			if( $detectedType === null && ( $this->allowSvg || $svgExplicitlyAllowed ) )
+			{
+				$detectedType = $this->detectSvg( $decoded );
+			}
+
+			// If we couldn't detect a type, it's not a valid image
+			if( $detectedType === null )
+			{
+				return false;
+			}
+
+			// Check if detected type is allowed
+			if( !$this->isMimeTypeAllowed( $detectedType ) )
+			{
+				return false;
+			}
+		}
+		elseif( $this->checkImageData )
+		{
+			// No MIME restrictions but need to check if it's a recognizable image
+			return $this->isRecognizableImage( $decoded );
+		}
+
+		return true;
+	}
+
+	/**
+	 * Detects image type from binary data signatures.
+	 *
+	 * @param string $imageData
+	 * @return string|null Returns MIME type if detected, null otherwise
+	 */
+	private function detectImageType( string $imageData ) : ?string
+	{
+		// Check for common image file signatures (magic numbers)
+		$signatures = [
+			// JPEG
+			"\xFF\xD8\xFF" => 'image/jpeg',
+			// PNG
+			"\x89\x50\x4E\x47\x0D\x0A\x1A\x0A" => 'image/png',
+			// GIF
+			"GIF87a" => 'image/gif',
+			"GIF89a" => 'image/gif',
+			// WebP
+			"RIFF" => 'image/webp', // Note: WebP also needs WEBP at offset 8
+		];
+
+		$dataStart = substr( $imageData, 0, 20 );
+
+		// Check for image signatures
+		foreach( $signatures as $signature => $mimeType )
+		{
+			if( strpos( $dataStart, $signature ) === 0 )
+			{
+				// Special handling for WebP
+				if( $signature === 'RIFF' && substr( $imageData, 8, 4 ) !== 'WEBP' )
+				{
+					continue;
+				}
+
+				return $mimeType;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Checks if the decoded data is a recognizable image format.
+	 * This method only validates that the data contains valid image signatures,
+	 * without checking MIME type restrictions (caller's responsibility).
+	 *
+	 * @param string $imageData
+	 * @return bool
+	 */
+	private function isRecognizableImage( string $imageData ) : bool
+	{
+		// Use the extracted method to detect image type
+		$detectedType = $this->detectImageType( $imageData );
+
+		// Check for SVG if:
+		// 1. allowSvg is true (general SVG support enabled), OR
+		// 2. 'image/svg+xml' is explicitly in allowedMimeTypes (if any restrictions exist)
+		$svgExplicitlyAllowed = !empty( $this->allowedMimeTypes ) && $this->isMimeTypeAllowed( 'image/svg+xml' );
+		if( $detectedType === null && ( $this->allowSvg || $svgExplicitlyAllowed ) )
+		{
+			$detectedType = $this->detectSvg( $imageData );
+		}
+
+		// Return true if we recognized any valid image format
+		return $detectedType !== null;
+	}
+
+	/**
+	 * Checks if a MIME type is in the allowed list (case-insensitive per RFC 2045).
+	 *
+	 * @param string $mimeType
+	 * @return bool
+	 */
+	private function isMimeTypeAllowed( string $mimeType ) : bool
+	{
+		$normalizedMimeType = strtolower( $mimeType );
+		foreach( $this->allowedMimeTypes as $allowed )
+		{
+			if( strtolower( $allowed ) === $normalizedMimeType )
+			{
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * Detects if the data is a valid SVG image.
+	 * SVG detection is more permissive but requires explicit opt-in for security.
+	 *
+	 * @param string $imageData
+	 * @return string|null Returns 'image/svg+xml' if valid SVG, null otherwise
+	 */
+	private function detectSvg( string $imageData ) : ?string
+	{
+		// Only check first 1KB for performance
+		$dataToCheck = substr( $imageData, 0, 1024 );
+
+		// Remove UTF-8 BOM if present (exact 3-byte sequence)
+		if( substr( $dataToCheck, 0, 3 ) === "\xEF\xBB\xBF" )
+		{
+			$dataToCheck = substr( $dataToCheck, 3 );
+		}
+
+		// Case-insensitive check for <svg tag with proper namespace
+		// Must find an actual SVG element with namespace declaration
+		// This regex ensures xmlns is an attribute, not just text content
+		if( preg_match( '/<svg\b[^>]*xmlns\s*=\s*["\']http:\/\/www\.w3\.org\/2000\/svg["\'][^>]*>/i', $dataToCheck ) )
+		{
+			// Valid SVG with proper namespace declaration
+			return 'image/svg+xml';
+		}
+
+		// Also check for xmlns:svg pattern (less common but valid)
+		if( preg_match( '/<svg\b[^>]*xmlns:svg\s*=\s*["\']http:\/\/www\.w3\.org\/2000\/svg["\'][^>]*>/i', $dataToCheck ) )
+		{
+			return 'image/svg+xml';
+		}
+
+		return null;
+	}
+}