diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index 9838acc..b56028c 100644
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -7,7 +7,14 @@
       "Bash(./vendor/bin/phpunit:*)",
       "Bash(./vendor/bin/phpmd:*)",
       "Bash(vendor/bin/phpunit:*)",
-      "Bash(XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text --coverage-filter src/)"
+      "Bash(XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text --coverage-filter src/)",
+      "Bash(find:*)",
+      "mcp__ide__getDiagnostics",
+      "Bash(XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text --coverage-filter=src/)",
+      "Bash(XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text --coverage-filter=src/ --colors=never)",
+      "Bash(XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage-report --coverage-filter=src/)",
+      "Bash(ls:*)",
+      "Bash(grep:*)"
     ],
     "deny": []
   }
diff --git a/README.md b/README.md
index 05f1203..1c5329a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,10 @@
 # Ray.InputQuery
 
-Structured input objects from HTTP.
+[![Continuous Integration](https://github.com/ray-di/Ray.InputQuery/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/ray-di/Ray.InputQuery/actions/workflows/continuous-integration.yml)
+[![Type Coverage](https://shepherd.dev/github/ray-di/Ray.InputQuery/coverage.svg)](https://shepherd.dev/github/ray-di/Ray.InputQuery)
+[![codecov](https://codecov.io/gh/ray-di/Ray.InputQuery/branch/main/graph/badge.svg)](https://codecov.io/gh/ray-di/Ray.InputQuery)
+
+Structured input objects from HTTP with 100% test coverage.
 
 ## Overview
 
@@ -44,10 +48,28 @@ public function createTodo(TodoInput $input) {
 composer require ray/input-query
 ```
 
+## Demo
+
+To see file upload integration in action:
+
+```bash
+php -S localhost:8080 -t demo/
+```
+
+Then visit [http://localhost:8080](http://localhost:8080) in your browser.
+
 ## Documentation
 
 Comprehensive documentation including design philosophy, AI prompts for development assistance, and sample data examples can be found in the [docs/](docs/) directory.
 
+### Framework Integration
+
+For framework-specific integration examples, see the **[Framework Integration Guide](docs/framework_integration.md)** which covers:
+
+- Laravel, Symfony, CakePHP, Yii Framework 1.x, BEAR.Sunday, and Slim Framework
+- Three usage patterns (Reflection, Direct Object Creation, Spread Operator)
+- Testing examples and best practices
+
 ## Usage
 
 Ray.InputQuery converts flat query data into typed PHP objects automatically.
@@ -89,11 +111,11 @@ echo $user->email; // john@example.com
 // Method argument resolution from $_POST
 $method = new ReflectionMethod(UserController::class, 'register');
 $args = $inputQuery->getArguments($method, $_POST);
-$controller->register(...$args);
+$result = $method->invokeArgs($controller, $args);
 
-// Or with PSR-7 Request
+ // Or with PSR-7 Request
 $args = $inputQuery->getArguments($method, $request->getParsedBody());
-$controller->register(...$args);
+$result = $method->invokeArgs($controller, $args);
 ```
 
 ### Nested Objects
@@ -185,8 +207,8 @@ $data = [
     ]
 ];
 
-$args = $inputQuery->getArguments($method, $data);
-// $args[0] will be an array of UserInput objects
+$result = $method->invokeArgs($controller, $inputQuery->getArguments($method, $data));
+// Arguments automatically resolved as UserInput objects
 ```
 
 #### Simple array values (e.g., checkboxes)
@@ -286,6 +308,125 @@ All query keys are normalized to camelCase:
 - `user-name` → `userName`
 - `UserName` → `userName`
 
+## File Upload Integration
+
+Ray.InputQuery provides comprehensive file upload support through integration with [Koriym.FileUpload](https://github.com/koriym/Koriym.FileUpload):
+
+```bash
+composer require koriym/file-upload
+```
+
+### Using #[InputFile] Attribute
+
+For file uploads, use the dedicated `#[InputFile]` attribute which provides validation options:
+
+```php
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class UserProfileInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[Input] public readonly string $email,
+        #[InputFile(
+            maxSize: 5 * 1024 * 1024,  // 5MB
+            allowedTypes: ['image/jpeg', 'image/png'],
+            allowedExtensions: ['jpg', 'jpeg', 'png']
+        )] 
+        public readonly FileUpload|ErrorFileUpload $avatar,
+        #[InputFile] public readonly FileUpload|ErrorFileUpload|null $banner = null,
+    ) {}
+}
+```
+
+// Method usage example - Direct attribute approach
+
+### Test-Friendly Design
+
+File upload handling is designed to be test-friendly:
+
+- **Production** - FileUpload library handles file uploads automatically
+- **Testing** - Direct FileUpload object injection for easy mocking
+
+```php
+// Production usage - FileUpload library handles file uploads automatically
+$input = $inputQuery->create(UserProfileInput::class, $_POST);
+// FileUpload objects are created automatically from uploaded files
+
+// Testing usage - inject mock FileUpload objects directly for easy testing
+$mockAvatar = FileUpload::create([
+    'name' => 'test.jpg',
+    'type' => 'image/jpeg', 
+    'size' => 1024,
+    'tmp_name' => '/tmp/test',
+    'error' => UPLOAD_ERR_OK,
+]);
+
+$input = $inputQuery->create(UserProfileInput::class, [
+    'name' => 'Test User',
+    'email' => 'test@example.com', 
+    'avatar' => $mockAvatar,
+    'banner' => null
+]);
+```
+
+### Multiple File Uploads
+
+Support for multiple file uploads using array types with validation:
+
+```php
+final class GalleryInput
+{
+    /**
+     * @param list<FileUpload|ErrorFileUpload> $images
+     */
+    public function __construct(
+        #[Input] public readonly string $title,
+        #[InputFile(
+            maxSize: 10 * 1024 * 1024,  // 10MB per file
+            allowedTypes: ['image/*']
+        )] 
+        public readonly array $images,
+    ) {}
+}
+
+// Method usage example
+class GalleryController
+{
+    public function createGallery(GalleryInput $input): void
+    {
+        $savedImages = [];
+        foreach ($input->images as $image) {
+            if ($image instanceof FileUpload) {
+                $savedImages[] = $this->saveFile($image, 'gallery/');
+            } elseif ($image instanceof ErrorFileUpload) {
+                // Log error but continue with other images
+                $this->logger->warning('Image upload failed: ' . $image->message);
+            }
+        }
+        
+        $this->galleryService->create($input->title, $savedImages);
+    }
+}
+
+// Production usage - FileUpload library handles multiple files automatically
+$input = $inputQuery->create(GalleryInput::class, $_POST);
+// Array of FileUpload objects created automatically from uploaded files
+
+// Testing usage - inject array of mock FileUpload objects for easy testing
+$mockImages = [
+    FileUpload::create(['name' => 'image1.jpg', ...]),
+    FileUpload::create(['name' => 'image2.png', ...])
+];
+
+$input = $inputQuery->create(GalleryInput::class, [
+    'title' => 'My Gallery',
+    'images' => $mockImages
+]);
+```
+
 ## Integration
 
 Ray.InputQuery is designed as a foundation library to be used by:
@@ -293,6 +434,15 @@ Ray.InputQuery is designed as a foundation library to be used by:
 - [Ray.MediaQuery](https://github.com/ray-di/Ray.MediaQuery) - For database query integration
 - [BEAR.Resource](https://github.com/bearsunday/BEAR.Resource) - For REST resource integration
 
+## Project Quality
+
+This project maintains high quality standards:
+
+- **100% Code Coverage** - Achieved through public interface tests only
+- **Static Analysis** - Psalm and PHPStan at maximum levels
+- **Test Design** - No private method tests, ensuring maintainability
+- **Type Safety** - Comprehensive Psalm type annotations
+
 ## Requirements
 
 - PHP 8.1+
diff --git a/composer-require-checker.json b/composer-require-checker.json
index d2a08fc..c53e62a 100644
--- a/composer-require-checker.json
+++ b/composer-require-checker.json
@@ -1,5 +1,8 @@
 {
-    "symbol-whitelist" : [],
+    "symbol-whitelist" : [
+        "Koriym\\FileUpload\\FileUpload",
+        "Koriym\\FileUpload\\ErrorFileUpload"
+    ],
     "php-core-extensions" : [
         "Core",
         "date",
diff --git a/composer.json b/composer.json
index c6fe1a8..350ff02 100644
--- a/composer.json
+++ b/composer.json
@@ -12,9 +12,13 @@
         "php": "^8.1",
         "ray/di": "^2.18"
     },
+    "suggest": {
+        "koriym/file-upload": "For file upload handling integration"
+    },
     "require-dev": {
         "bamarni/composer-bin-plugin": "^1.8",
-        "phpunit/phpunit": "^10.5"
+        "phpunit/phpunit": "^10.5",
+        "koriym/file-upload": "^0.2.0"
     },
     "autoload": {
         "psr-4": {
diff --git a/demo/index.php b/demo/index.php
new file mode 100644
index 0000000..b77a186
--- /dev/null
+++ b/demo/index.php
@@ -0,0 +1,417 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\Di\Injector;
+use Ray\InputQuery\InputQuery;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+// Note: In a production environment, the FileUpload library would handle
+// file uploads based on the environment (traditional PHP, Swoole, etc.)
+// This demo shows how to use InputQuery with FileUpload objects.
+
+// No Input classes needed - using method parameters directly
+
+// Demo controller
+final class FileUploadController
+{
+    public function __construct()
+    {
+        // Create uploads directory if it doesn't exist
+        $uploadsDir = __DIR__ . '/uploads';
+        if (!is_dir($uploadsDir)) {
+            mkdir($uploadsDir, 0755, true);
+        }
+    }
+    
+    public function handleUserProfile(
+        #[Input] string $name,
+        #[Input] string $email,
+        #[InputFile(
+            maxSize: 2 * 1024 * 1024,  // 2MB
+            allowedTypes: ['image/jpeg', 'image/png', 'image/gif']
+        )] FileUpload|ErrorFileUpload $avatar,
+        #[InputFile] FileUpload|ErrorFileUpload|null $banner = null,
+    ): array {
+        try {
+            $results = [
+                'name' => $name,
+                'email' => $email,
+                'success' => true
+            ];
+            
+            // Handle avatar upload
+            if ($avatar instanceof FileUpload) {
+                $avatarPath = 'uploads/avatar_' . time() . '_' . $avatar->name;
+                if ($avatar->move(__DIR__ . '/' . $avatarPath)) {
+                    $results['avatar'] = $avatarPath;
+                } else {
+                    $results['avatar_error'] = 'Failed to save avatar';
+                }
+            } elseif ($avatar instanceof ErrorFileUpload) {
+                $results['avatar_error'] = $avatar->message;
+            }
+            
+            // Handle optional banner upload
+            if ($banner instanceof FileUpload) {
+                $bannerPath = 'uploads/banner_' . time() . '_' . $banner->name;
+                if ($banner->move(__DIR__ . '/' . $bannerPath)) {
+                    $results['banner'] = $bannerPath;
+                } else {
+                    $results['banner_error'] = 'Failed to save banner';
+                }
+            } elseif ($banner instanceof ErrorFileUpload) {
+                $results['banner_error'] = $banner->message;
+            }
+            
+            return $results;
+            
+        } catch (Exception $e) {
+            return ['error' => $e->getMessage()];
+        }
+    }
+    
+    public function handleGallery(
+        #[Input] string $title,
+        #[InputFile(
+            maxSize: 1 * 1024 * 1024,  // 1MB per file
+            allowedTypes: ['image/jpeg', 'image/png']
+        )] array $images,
+    ): array {
+        try {
+            $results = [
+                'title' => $title,
+                'images' => [],
+                'errors' => []
+            ];
+            
+            foreach ($images as $index => $image) {
+                if ($image instanceof FileUpload) {
+                    $imagePath = 'uploads/gallery_' . $index . '_' . time() . '_' . $image->name;
+                    if ($image->move(__DIR__ . '/' . $imagePath)) {
+                        $results['images'][] = $imagePath;
+                    } else {
+                        $results['errors'][] = "Image {$index}: Failed to save file";
+                    }
+                } elseif ($image instanceof ErrorFileUpload) {
+                    $results['errors'][] = "Image {$index}: " . $image->message;
+                }
+            }
+            
+            $results['success'] = true;
+            return $results;
+            
+        } catch (Exception $e) {
+            return ['error' => $e->getMessage()];
+        }
+    }
+    
+}
+
+// Handle form submissions
+$controller = new FileUploadController();
+$result = null;
+
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    if (isset($_POST['action'])) {
+        try {
+            switch ($_POST['action']) {
+                case 'profile':
+                    $inputQuery = new InputQuery(new Injector());
+                    $method = new ReflectionMethod($controller, 'handleUserProfile');
+                    $args = $inputQuery->getArguments($method, $_POST);
+                    $result = $method->invokeArgs($controller, $args);
+                    break;
+                    
+                case 'gallery':
+                    // Using invokeArgs() method
+                    $inputQuery = new InputQuery(new Injector());
+                    $method = new ReflectionMethod($controller, 'handleGallery');
+                    $args = $inputQuery->getArguments($method, $_POST);
+                    $result = $method->invokeArgs($controller, $args);
+                    break;
+            }
+        } catch (Exception $e) {
+            $result = ['error' => $e->getMessage()];
+        }
+    }
+}
+
+?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Ray.InputQuery File Upload Demo</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 20px;
+            background-color: #f5f5f5;
+        }
+        
+        .container {
+            background: white;
+            border-radius: 8px;
+            padding: 30px;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+            margin-bottom: 30px;
+        }
+        
+        h1 {
+            color: #333;
+            text-align: center;
+            margin-bottom: 10px;
+        }
+        
+        .subtitle {
+            text-align: center;
+            color: #666;
+            margin-bottom: 30px;
+        }
+        
+        h2 {
+            color: #444;
+            border-bottom: 2px solid #007bff;
+            padding-bottom: 10px;
+        }
+        
+        .form-group {
+            margin-bottom: 20px;
+        }
+        
+        label {
+            display: block;
+            margin-bottom: 5px;
+            font-weight: 600;
+            color: #333;
+        }
+        
+        input[type="text"], input[type="email"] {
+            width: 100%;
+            padding: 10px;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            font-size: 16px;
+        }
+        
+        input[type="file"] {
+            width: 100%;
+            padding: 10px;
+            border: 2px dashed #ddd;
+            border-radius: 4px;
+            background: #fafafa;
+        }
+        
+        button {
+            background: #007bff;
+            color: white;
+            padding: 12px 24px;
+            border: none;
+            border-radius: 4px;
+            font-size: 16px;
+            cursor: pointer;
+            transition: background 0.2s;
+        }
+        
+        button:hover {
+            background: #0056b3;
+        }
+        
+        .result {
+            background: #d4edda;
+            border: 1px solid #c3e6cb;
+            border-radius: 4px;
+            padding: 15px;
+            margin-top: 20px;
+        }
+        
+        .result.error {
+            background: #f8d7da;
+            border-color: #f5c6cb;
+        }
+        
+        .file-info {
+            font-size: 14px;
+            color: #666;
+            margin-top: 5px;
+        }
+        
+        .uploaded-file {
+            background: #e9ecef;
+            padding: 10px;
+            border-radius: 4px;
+            margin: 5px 0;
+        }
+        
+        .code-example {
+            background: #f8f9fa;
+            border: 1px solid #e9ecef;
+            border-radius: 4px;
+            padding: 15px;
+            margin: 20px 0;
+            overflow-x: auto;
+        }
+        
+        .code-example pre {
+            margin: 0;
+            font-size: 14px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>Ray.InputQuery File Upload Demo</h1>
+        <p class="subtitle">File upload integration with Koriym.FileUpload</p>
+        
+        <?php if ($_SERVER['REQUEST_METHOD'] === 'POST'): ?>
+            <div class="result">
+                <strong>Debug Info:</strong>
+                <pre>$_POST: <?= htmlspecialchars(json_encode($_POST, JSON_PRETTY_PRINT)) ?></pre>
+                <pre>$_FILES: <?= htmlspecialchars(json_encode($_FILES, JSON_PRETTY_PRINT)) ?></pre>
+                
+                <?php 
+                // Capture any error logs during processing
+                ob_start();
+                ?>
+                <strong>Processing Debug:</strong>
+                <pre id="debug-log"></pre>
+            </div>
+        <?php endif; ?>
+        
+        <?php if ($result): ?>
+            <div class="result <?= isset($result['error']) ? 'error' : '' ?>">
+                <?php if (isset($result['error'])): ?>
+                    <strong>Error:</strong> <?= htmlspecialchars($result['error']) ?>
+                <?php elseif (isset($result['success'])): ?>
+                    <strong>Success!</strong> Files uploaded successfully.
+                    <pre><?= htmlspecialchars(json_encode($result, JSON_PRETTY_PRINT)) ?></pre>
+                <?php endif; ?>
+            </div>
+        <?php endif; ?>
+    </div>
+
+    <div class="container">
+        <h2>User Profile Upload</h2>
+        <p>Upload avatar (required) and banner (optional).</p>
+        
+        <form method="post" enctype="multipart/form-data">
+            <input type="hidden" name="action" value="profile">
+            
+            <div class="form-group">
+                <label for="name">Name:</label>
+                <input type="text" id="name" name="name" required value="Jingu">
+            </div>
+            
+            <div class="form-group">
+                <label for="email">Email:</label>
+                <input type="email" id="email" name="email" required value="jingu@example.com">
+            </div>
+            
+            <div class="form-group">
+                <label for="avatar">Avatar (Required):</label>
+                <input type="file" id="avatar" name="avatar" accept="image/*" required>
+                <div class="file-info">Max 2MB, JPEG/PNG/GIF only</div>
+            </div>
+            
+            <div class="form-group">
+                <label for="banner">Banner (Optional):</label>
+                <input type="file" id="banner" name="banner" accept="image/*">
+                <div class="file-info">Max 2MB, JPEG/PNG/GIF only</div>
+            </div>
+            
+            <button type="submit">Upload Profile</button>
+        </form>
+        
+        <div class="code-example">
+            <strong>Input Class:</strong>
+            <pre><code>final class UserProfileInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[Input] public readonly string $email,
+        #[InputFile(
+            maxSize: 2 * 1024 * 1024,  // 2MB
+            allowedTypes: ['image/jpeg', 'image/png', 'image/gif']
+        )] public readonly FileUpload|ErrorFileUpload $avatar,
+        #[InputFile] public readonly FileUpload|ErrorFileUpload|null $banner = null,
+    ) {}
+}</code></pre>
+        </div>
+    </div>
+
+    <div class="container">
+        <h2>Gallery Upload</h2>
+        <p>Upload multiple images.</p>
+        
+        <form method="post" enctype="multipart/form-data">
+            <input type="hidden" name="action" value="gallery">
+            
+            <div class="form-group">
+                <label for="title">Gallery Title:</label>
+                <input type="text" id="title" name="title" required value="My Photo Gallery">
+            </div>
+            
+            <div class="form-group">
+                <label for="images">Images:</label>
+                <input type="file" id="images" name="images[]" accept="image/*" multiple required>
+                <div class="file-info">Max 1MB per image, JPEG/PNG only, multiple files allowed</div>
+            </div>
+            
+            <button type="submit">Upload Gallery</button>
+        </form>
+        
+        <div class="code-example">
+            <strong>Input Class:</strong>
+            <pre><code>final class GalleryInput
+{
+    /**
+     * @param list&lt;FileUpload|ErrorFileUpload&gt; $images
+     */
+    public function __construct(
+        #[Input] public readonly string $title,
+        #[InputFile(
+            maxSize: 1 * 1024 * 1024,  // 1MB per file
+            allowedTypes: ['image/jpeg', 'image/png']
+        )] public readonly array $images,
+    ) {}
+}</code></pre>
+        </div>
+    </div>
+    
+    <div class="container">
+        <h2>How It Works</h2>
+        <p>Features demonstrated:</p>
+        <ul>
+            <li><strong>Type Safety:</strong> FileUpload objects created automatically</li>
+            <li><strong>Validation:</strong> File size and type validation</li>
+            <li><strong>Error Handling:</strong> Graceful error handling</li>
+            <li><strong>Array Support:</strong> Multiple file uploads</li>
+            <li><strong>Optional Files:</strong> Nullable parameters</li>
+        </ul>
+        
+        <div class="code-example">
+            <strong>Two Usage Patterns:</strong>
+            <pre><code>// Method 1: getArguments() + spread operator
+$inputQuery = new InputQuery(new Injector());
+$method = new ReflectionMethod($controller, 'handleUserProfile');
+$args = $inputQuery->getArguments($method, $_POST);
+$result = $controller->handleUserProfile(...$args);
+
+// Method 2: invokeArgs() for more dynamic calls
+$result = $method->invokeArgs($controller, $args);
+
+// Method 3: Direct object creation
+$input = $inputQuery->create(UserProfileInput::class, $_POST);</code></pre>
+        </div>
+    </div>
+</body>
+</html>
\ No newline at end of file
diff --git a/demo/uploads/avatar_1751562653_AkihitoKoriyama.jpg b/demo/uploads/avatar_1751562653_AkihitoKoriyama.jpg
new file mode 100644
index 0000000..daec47b
Binary files /dev/null and b/demo/uploads/avatar_1751562653_AkihitoKoriyama.jpg differ
diff --git a/demo/uploads/avatar_1751562679_AkihitoKoriyama.jpg b/demo/uploads/avatar_1751562679_AkihitoKoriyama.jpg
new file mode 100644
index 0000000..daec47b
Binary files /dev/null and b/demo/uploads/avatar_1751562679_AkihitoKoriyama.jpg differ
diff --git a/demo/uploads/avatar_1751562776_AkihitoKoriyama.jpg b/demo/uploads/avatar_1751562776_AkihitoKoriyama.jpg
new file mode 100644
index 0000000..daec47b
Binary files /dev/null and b/demo/uploads/avatar_1751562776_AkihitoKoriyama.jpg differ
diff --git a/demo/uploads/avatar_1751568523_hb2u.jpeg b/demo/uploads/avatar_1751568523_hb2u.jpeg
new file mode 100644
index 0000000..a0d3633
Binary files /dev/null and b/demo/uploads/avatar_1751568523_hb2u.jpeg differ
diff --git a/demo/uploads/banner_1751562679_AkihitoKoriyama.jpg b/demo/uploads/banner_1751562679_AkihitoKoriyama.jpg
new file mode 100644
index 0000000..daec47b
Binary files /dev/null and b/demo/uploads/banner_1751562679_AkihitoKoriyama.jpg differ
diff --git a/demo/uploads/gallery_0_1751562994_#11191597.JPG b/demo/uploads/gallery_0_1751562994_#11191597.JPG
new file mode 100644
index 0000000..2fa27b0
Binary files /dev/null and b/demo/uploads/gallery_0_1751562994_#11191597.JPG differ
diff --git a/demo/uploads/gallery_0_1751563002_hb2u.jpeg b/demo/uploads/gallery_0_1751563002_hb2u.jpeg
new file mode 100644
index 0000000..a0d3633
Binary files /dev/null and b/demo/uploads/gallery_0_1751563002_hb2u.jpeg differ
diff --git a/demo/uploads/gallery_0_1751563070_#11191597.JPG b/demo/uploads/gallery_0_1751563070_#11191597.JPG
new file mode 100644
index 0000000..2fa27b0
Binary files /dev/null and b/demo/uploads/gallery_0_1751563070_#11191597.JPG differ
diff --git a/demo/uploads/gallery_0_1751568545_#11191597.JPG b/demo/uploads/gallery_0_1751568545_#11191597.JPG
new file mode 100644
index 0000000..2fa27b0
Binary files /dev/null and b/demo/uploads/gallery_0_1751568545_#11191597.JPG differ
diff --git a/demo/uploads/gallery_1_1751562994_F1000046.JPG b/demo/uploads/gallery_1_1751562994_F1000046.JPG
new file mode 100644
index 0000000..80b7460
Binary files /dev/null and b/demo/uploads/gallery_1_1751562994_F1000046.JPG differ
diff --git a/demo/uploads/gallery_1_1751563070_F1000046.JPG b/demo/uploads/gallery_1_1751563070_F1000046.JPG
new file mode 100644
index 0000000..80b7460
Binary files /dev/null and b/demo/uploads/gallery_1_1751563070_F1000046.JPG differ
diff --git a/demo/uploads/gallery_1_1751568545_F1000046.JPG b/demo/uploads/gallery_1_1751568545_F1000046.JPG
new file mode 100644
index 0000000..80b7460
Binary files /dev/null and b/demo/uploads/gallery_1_1751568545_F1000046.JPG differ
diff --git a/demo/uploads/gallery_2_1751563070_hb2u.jpeg b/demo/uploads/gallery_2_1751563070_hb2u.jpeg
new file mode 100644
index 0000000..a0d3633
Binary files /dev/null and b/demo/uploads/gallery_2_1751563070_hb2u.jpeg differ
diff --git a/docs/design/file-upload-integration.md b/docs/design/file-upload-integration.md
new file mode 100644
index 0000000..3881099
--- /dev/null
+++ b/docs/design/file-upload-integration.md
@@ -0,0 +1,362 @@
+# File Upload Integration Design
+
+## Overview
+
+This document outlines the design for integrating Koriym.FileUpload with Ray.InputQuery to provide seamless file upload handling alongside form data processing. The goal is to enable declarative file upload handling using the same `#[Input]` attribute pattern.
+
+## Problem Statement
+
+Currently, Ray.InputQuery handles flat key-value data transformation but does not process `$_FILES` directly. File uploads require separate handling, breaking the unified declarative approach that Ray.InputQuery provides for other form data.
+
+## Proposed Solution
+
+### Vision
+
+```php
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\Input;
+
+final class UserProfileInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[Input] public readonly string $email,
+        #[Input(fileOptions: [
+            'maxSize' => 5 * 1024 * 1024,
+            'allowedTypes' => ['image/jpeg', 'image/png']
+        ])] public readonly FileUpload $avatar,
+        #[Input] public readonly ?FileUpload $banner = null  // Optional file
+    ) {}
+}
+
+// Usage
+$inputQuery = new InputQuery($injector, $_FILES);  // Pass $_FILES
+$input = $inputQuery->create(UserProfileInput::class, $_POST);
+```
+
+### HTML Form Structure
+
+```html
+<form method="post" enctype="multipart/form-data">
+    <input name="name" value="Jingu">
+    <input name="email" value="jingu@example.com">
+    <input name="avatar" type="file" accept="image/*" required>
+    <input name="banner" type="file" accept="image/*">
+    <button type="submit">Submit</button>
+</form>
+```
+
+## Implementation Design
+
+### 1. Enhanced Input Attribute
+
+```php
+#[Attribute(Attribute::TARGET_PARAMETER)]
+final class Input
+{
+    public function __construct(
+        public readonly string|null $item = null,
+        public readonly array|null $fileOptions = null,
+    ) {}
+}
+```
+
+### 2. InputQuery Constructor Enhancement
+
+```php
+final class InputQuery implements InputQueryInterface
+{
+    public function __construct(
+        private InjectorInterface $injector,
+        private array $files = [],  // $_FILES data
+    ) {}
+}
+```
+
+### 3. File Upload Detection Logic
+
+```php
+private function resolveObjectType(
+    ReflectionParameter $param, 
+    array $query, 
+    array $inputAttributes, 
+    ReflectionNamedType $type
+): mixed {
+    $paramName = $param->getName();
+    $className = $type->getName();
+    
+    // Check for FileUpload type
+    if ($className === FileUpload::class || is_subclass_of($className, FileUpload::class)) {
+        return $this->resolveFileUpload($param, $inputAttributes);
+    }
+    
+    // Existing object resolution logic...
+}
+
+private function resolveFileUpload(
+    ReflectionParameter $param, 
+    array $inputAttributes
+): FileUpload|ErrorFileUpload {
+    $paramName = $param->getName();
+    
+    if (!array_key_exists($paramName, $this->files)) {
+        if ($param->allowsNull() || $param->isDefaultValueAvailable()) {
+            return $param->getDefaultValue();
+        }
+        throw new InvalidArgumentException("Required file parameter '{$paramName}' is missing");
+    }
+    
+    $fileData = $this->files[$paramName];
+    $inputAttribute = $inputAttributes[0]->newInstance();
+    $fileOptions = $inputAttribute->fileOptions ?? [];
+    
+    return FileUpload::create($fileData, $fileOptions);
+}
+```
+
+### 4. Array File Upload Support
+
+```php
+/**
+ * @param list<FileUpload> $images
+ */
+public function uploadGallery(
+    #[Input(item: FileUpload::class, fileOptions: [
+        'maxSize' => 2 * 1024 * 1024,
+        'allowedTypes' => ['image/jpeg', 'image/png']
+    ])] array $images
+) {
+    foreach ($images as $image) {
+        $image->move('./uploads/' . $image->name);
+    }
+}
+```
+
+HTML:
+```html
+<form method="post" enctype="multipart/form-data">
+    <input name="images[]" type="file" multiple accept="image/*">
+    <button type="submit">Upload Gallery</button>
+</form>
+```
+
+## Implementation Considerations
+
+### 1. Dependency Management
+
+- Add `koriym/file-upload` as an optional dependency
+- Use interface detection to enable FileUpload features only when the library is available
+- Provide graceful degradation when FileUpload is not installed
+
+```php
+private function isFileUploadAvailable(): bool
+{
+    return class_exists(FileUpload::class);
+}
+```
+
+### 2. Error Handling
+
+```php
+// Return ErrorFileUpload for validation failures
+if ($upload instanceof ErrorFileUpload) {
+    if ($param->allowsNull()) {
+        return null;
+    }
+    throw new InvalidArgumentException("File upload error: " . $upload->message);
+}
+```
+
+### 3. Testing Strategy
+
+```php
+// In tests, use FileUpload::fromFile() for easy testing
+$upload = FileUpload::fromFile(__DIR__ . '/fixtures/test-image.jpg');
+$input = $inputQuery->create(UserProfileInput::class, [
+    'name' => 'Test User',
+    'email' => 'test@example.com'
+], ['avatar' => $upload->toArray()]);
+```
+
+### 4. Backward Compatibility
+
+- Maintain existing constructor signature by making `$files` parameter optional
+- Existing code without file uploads continues to work unchanged
+- New file upload features are opt-in
+
+## Benefits
+
+### 1. Unified Declarative Approach
+- File uploads use the same `#[Input]` attribute pattern
+- Consistent validation and error handling
+- Type-safe file handling
+
+### 2. Enhanced Developer Experience
+- No need to manually process `$_FILES`
+- Built-in validation through fileOptions
+- Seamless integration with existing form processing
+
+### 3. Framework Integration
+- Works naturally with BEAR.Resource
+- Maintains Ray.InputQuery's design philosophy
+- Leverages existing DI and attribute infrastructure
+
+## Migration Path
+
+### Phase 1: Core Integration
+1. Add optional FileUpload dependency
+2. Enhance Input attribute with fileOptions
+3. Implement basic FileUpload resolution
+4. Add comprehensive tests
+
+### Phase 2: Advanced Features
+1. Array file upload support
+2. Custom FileUpload subclass support
+3. Enhanced error handling and validation
+4. Performance optimizations
+
+### Phase 3: Documentation and Examples
+1. Update README with file upload examples
+2. Create demo applications
+3. Add to sample data generators
+4. Integration guides for BEAR.Resource
+
+## Technical Challenges
+
+### 1. Multiple Data Sources
+- Handling both `$_POST` and `$_FILES` data
+- Maintaining separation of concerns
+- Consistent parameter resolution
+
+### 2. Validation Timing
+- FileUpload validation occurs during object creation
+- May need to delay validation for better error reporting
+- Integration with form validation frameworks
+
+### 3. Memory Management
+- Large file uploads and memory usage
+- Streaming capabilities for large files
+- Cleanup of temporary files
+
+## Alternative Approaches Considered
+
+### 1. Separate FileInputQuery Class
+- **Pros**: Clear separation, no API changes
+- **Cons**: Breaks unified approach, requires separate handling
+
+### 2. FileUpload as Regular Objects
+- **Pros**: Simple implementation
+- **Cons**: Loses FileUpload's validation and security features
+
+### 3. Custom File Attribute
+- **Pros**: Dedicated file handling
+- **Cons**: Inconsistent with existing Input attribute pattern
+
+## Koriym.FileUpload Quality Assessment
+
+### Code Quality Evaluation: **A+**
+
+After thorough analysis of the Koriym.FileUpload source code, the library demonstrates exceptional quality and architectural alignment with Ray.InputQuery.
+
+#### Strengths
+
+**1. Type Safety Excellence**
+- Comprehensive Psalm type annotations (`@psalm-type UploadedFile`, `@psalm-immutable`)
+- Strict type checking with `declare(strict_types=1)`
+- Static analysis optimized codebase
+
+**2. Immutable Design Philosophy**
+- `@psalm-immutable` annotations ensure side-effect-free operations
+- Predictable behavior and thread safety
+- Aligns perfectly with Ray.InputQuery's philosophy
+
+**3. Robust Factory Pattern**
+- `FileUpload::create()` provides controlled object instantiation
+- Returns `ErrorFileUpload` on validation failure instead of throwing exceptions
+- Consistent error handling through return values
+
+**4. Environment Adaptability**
+- Web environment: `move_uploaded_file()` for security
+- CLI environment: `rename()` for testing compatibility
+- `fromFile()` method specifically designed for test scenarios
+
+**5. Comprehensive Error Handling**
+- Proper handling of PHP's standard upload error codes
+- Human-readable error messages
+- Unified error representation through `ErrorFileUpload`
+
+#### Integration Compatibility
+
+**1. Architectural Harmony**
+- ✅ Shared immutable design philosophy
+- ✅ Type safety as core principle  
+- ✅ Error handling through return values vs exceptions
+- ✅ Factory pattern usage
+
+**2. Seamless Integration Points**
+```php
+// Type detection in Ray.InputQuery
+if ($className === FileUpload::class) {
+    return FileUpload::create($this->files[$paramName], $fileOptions);
+}
+
+// Unified error handling
+if ($upload instanceof ErrorFileUpload) {
+    // Handle validation errors consistently
+}
+```
+
+**3. Testing Integration**
+```php
+// Natural testing approach
+$testUpload = FileUpload::fromFile(__DIR__ . '/fixtures/test.jpg');
+$input = $inputQuery->create(UserInput::class, $_POST, [
+    'avatar' => $testUpload->toArray()
+]);
+```
+
+#### Integration Benefits
+
+**1. Consistent Developer Experience**
+- Same quality standards as Ray.InputQuery
+- Identical design principles (immutable, type-safe)
+- Matching error handling patterns
+
+**2. Implementation Simplicity**
+- Natural integration with existing code patterns
+- No complex transformation layers required
+- Concise test code
+
+**3. Security by Design**
+- Proper `move_uploaded_file()` usage
+- Built-in validation capabilities
+- Type safety prevents unexpected behaviors
+
+### Technical Recommendations
+
+**Implementation Priority**
+```php
+// High Priority: Basic integration
+#[Input] public readonly FileUpload $avatar
+
+// Medium Priority: Validation options
+#[Input(fileOptions: ['maxSize' => 1024*1024])] 
+public readonly FileUpload $avatar
+
+// Lower Priority: Array support
+#[Input(item: FileUpload::class)] 
+public readonly array $images
+```
+
+**Potential Enhancements**
+- Helper methods for array upload processing
+- Enhanced validation option integration with Ray.InputQuery
+- Custom FileUpload subclass support optimization
+
+## Conclusion
+
+The proposed integration maintains Ray.InputQuery's declarative philosophy while adding powerful file upload capabilities. By leveraging Koriym.FileUpload's type-safe approach and Ray.InputQuery's attribute-based design, developers can handle complex forms with both regular data and file uploads using a unified, declarative interface.
+
+**Quality Assessment Conclusion**: Koriym.FileUpload exceeds expectations with exceptional code quality, making it an ideal integration candidate. The architectural alignment between both libraries ensures that the proposed integration will deliver a groundbreaking developer experience for PHP file upload processing.
+
+This design preserves backward compatibility while opening up new possibilities for web application development in the Ray ecosystem.
\ No newline at end of file
diff --git a/docs/framework-comparison.md b/docs/framework-comparison.md
new file mode 100644
index 0000000..dc56bb4
--- /dev/null
+++ b/docs/framework-comparison.md
@@ -0,0 +1,163 @@
+# Framework Comparison
+
+A comparison of HTTP input handling approaches across popular PHP frameworks.
+
+## The Problem
+
+All web frameworks face the same challenge: transforming flat HTTP data into structured, type-safe PHP objects.
+
+## Native PHP
+
+```php
+// Controller
+public function updateProfile()
+{
+    $name = $_POST['name'] ?? '';           // Manual extraction - no validation
+    $email = $_POST['email'] ?? '';         // Manual extraction - no validation
+    
+    // Manual file handling with error checking
+    $avatar = null;
+    if (isset($_FILES['avatar']) && $_FILES['avatar']['error'] === UPLOAD_ERR_OK) {
+        $avatar = $_FILES['avatar'];         // Raw array - no type safety
+        // Manual validation: size, type, etc.
+        if ($avatar['size'] > 2048000) {
+            throw new Exception('File too large');
+        }
+    }
+    
+    $banner = null;
+    if (isset($_FILES['banner']) && $_FILES['banner']['error'] === UPLOAD_ERR_OK) {
+        $banner = $_FILES['banner'];         // Raw array - no type safety
+    }
+    
+    // Manual validation for all fields
+    if (empty($name)) {
+        throw new Exception('Name is required');
+    }
+    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
+        throw new Exception('Invalid email');
+    }
+}
+
+// Framework integration
+$result = $controller->updateProfile();
+```
+
+## Laravel
+
+```php
+// Request class
+class extends FormRequest
+{
+    public function rules()
+    {
+        return [
+            'name' => 'required|string',        // String-based rules - no IDE support
+            'email' => 'required|email',        // Typos not caught at compile time
+            'avatar' => 'required|file|image|max:2048',  // Complex string parsing
+            'banner' => 'nullable|file|image|max:2048',  // Runtime validation only
+        ];
+    }
+}
+
+// Controller
+public function updateProfile(UpdateProfileRequest $request)
+{
+    $name = $request->name;      // Magic property - PHPStan sees as mixed
+    $email = $request->email;    // Magic property - PHPStan sees as mixed
+    $avatar = $request->file('avatar');  // Returns UploadedFile|null
+    $banner = $request->file('banner');  // Returns UploadedFile|null
+    
+    // Manual file handling and null checks required
+    if ($avatar) {
+        $avatarPath = $avatar->store('avatars');
+    }
+}
+
+// Framework integration
+$request = UpdateProfileRequest::createFromGlobals();
+$request->validate();
+$result = $controller->updateProfile($request);
+```
+
+## Symfony
+
+```php
+// Form type
+class ProfileType extends AbstractType
+{
+    public function buildForm(FormBuilderInterface $builder, array $options)
+    {
+        $builder
+            ->add('name', TextType::class)     // String field names - no IDE support
+            ->add('email', EmailType::class)   // String field names - no IDE support
+            ->add('avatar', FileType::class, [ // String field names - no IDE support
+                'constraints' => [new File(['maxSize' => '2M'])]
+            ])
+            ->add('banner', FileType::class, ['required' => false]); // String field names - no IDE support
+    }
+}
+
+// Controller
+public function updateProfile(Request $request)
+{
+    $form = $this->createForm(ProfileType::class);
+    $form->handleRequest($request);
+    
+    if ($form->isValid()) {
+        $data = $form->getData();  // Returns mixed array - no IDE support
+        $name = $data['name'];     // Array key unknown to IDE - no autocompletion
+        $email = $data['email'];   // Array key unknown to IDE - no autocompletion
+        $avatar = $form->get('avatar')->getData(); // String field names - no IDE support
+    }
+}
+
+// Framework integration
+$form = $this->createForm(ProfileType::class);
+$form->handleRequest($request);
+$data = $form->getData();
+$result = $controller->updateProfile($data);
+```
+
+## Ray.InputQuery
+
+```php
+// Controller method
+public function updateProfile(
+    #[Input] string $name,
+    #[Input] string $email,
+    #[Input] FileUpload|ErrorFileUpload $avatar,
+    #[Input] FileUpload|ErrorFileUpload|null $banner = null,
+): void {
+    // File objects are ready to use
+    if ($avatar instanceof FileUpload) {
+        $avatar->move('/path/to/avatars/' . $avatar->name);
+    }
+}
+
+// Framework integration (4 lines)
+$inputQuery = new InputQuery(new Injector());
+$method = new ReflectionMethod($controller, 'updateProfile');
+$args = $inputQuery->getArguments($method, $_POST);
+$result = $method->invokeArgs($controller, $args);
+```
+
+## Key Differences
+
+| Aspect | Native PHP | Laravel | Symfony | Ray.InputQuery |
+|--------|------------|---------|---------|----------------|
+| **Declaration** | Manual $_POST/$_FILES | Separate class | Separate class | Method signature |
+| **Type Safety** | None | Runtime validation | Runtime validation | Compile-time types |
+| **File Handling** | Raw arrays | Manual methods | Manual extraction | Automatic objects |
+| **Boilerplate** | Very High | High | High | Minimal |
+| **IDE Support** | None | Limited | Limited | Full type hints |
+
+## Design Philosophy
+
+**Native PHP**: Manual extraction and validation of HTTP data.
+
+**Laravel/Symfony**: Validation-first approach with separate request classes.
+
+**Ray.InputQuery**: Type-first approach using PHP's native type system and dependency injection.
+
+The code speaks for itself.
diff --git a/docs/framework_integration.md b/docs/framework_integration.md
new file mode 100644
index 0000000..a9db750
--- /dev/null
+++ b/docs/framework_integration.md
@@ -0,0 +1,573 @@
+# Framework Integration Guide
+
+This guide shows how to integrate Ray.InputQuery with popular PHP frameworks.
+
+## Laravel Integration
+
+### Basic Setup
+
+```php
+// app/Http/Controllers/UserController.php
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+use Ray\Di\Injector;
+use Ray\InputQuery\InputQuery;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+
+final class UserController extends Controller
+{
+    public function store(Request $request)
+    {
+        $injector = new Injector();
+        $inputQuery = new InputQuery($injector);
+        
+        $method = new \ReflectionMethod($this, 'createUser');
+        $args = $inputQuery->getArguments($method, $request->all());
+        
+        return $this->createUser(...$args);
+    }
+    
+    public function createUser(
+        #[Input] string $name,
+        #[Input] string $email,
+        #[InputFile(
+            maxSize: 5 * 1024 * 1024,
+            allowedTypes: ['image/jpeg', 'image/png']
+        )] FileUpload|ErrorFileUpload $avatar,
+    ): array {
+        if ($avatar instanceof ErrorFileUpload) {
+            throw new \InvalidArgumentException($avatar->message);
+        }
+        
+        $avatarPath = $avatar->move(storage_path('app/public/avatars'));
+        
+        // Create user logic here
+        return ['success' => true, 'avatar' => $avatarPath];
+    }
+}
+```
+
+### Laravel Service Provider
+
+```php
+// app/Providers/InputQueryServiceProvider.php
+<?php
+
+namespace App\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use Ray\Di\Injector;
+use Ray\InputQuery\InputQuery;
+use Ray\InputQuery\InputQueryInterface;
+
+class InputQueryServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->app->singleton(InputQueryInterface::class, function () {
+            return new InputQuery(new Injector());
+        });
+    }
+}
+```
+
+## Symfony Integration
+
+### Basic Setup
+
+```php
+// src/Controller/UserController.php
+<?php
+
+namespace App\Controller;
+
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Ray\Di\Injector;
+use Ray\InputQuery\InputQuery;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+
+class UserController extends AbstractController
+{
+    public function create(Request $request): JsonResponse
+    {
+        $injector = new Injector();
+        $inputQuery = new InputQuery($injector);
+        
+        $method = new \ReflectionMethod($this, 'handleUserCreation');
+        $args = $inputQuery->getArguments($method, $request->request->all());
+        
+        $result = $this->handleUserCreation(...$args);
+        
+        return new JsonResponse($result);
+    }
+    
+    public function handleUserCreation(
+        #[Input] string $name,
+        #[Input] string $email,
+        #[InputFile(maxSize: 5 * 1024 * 1024)] FileUpload|ErrorFileUpload|null $avatar = null,
+    ): array {
+        if ($avatar instanceof ErrorFileUpload) {
+            throw new \InvalidArgumentException($avatar->message);
+        }
+        
+        $avatarPath = null;
+        if ($avatar instanceof FileUpload) {
+            $avatarPath = $avatar->move($this->getParameter('upload_directory'));
+        }
+        
+        // User creation logic
+        return ['success' => true, 'avatar' => $avatarPath];
+    }
+}
+```
+
+### Symfony Service Configuration
+
+```yaml
+# config/services.yaml
+services:
+    Ray\InputQuery\InputQueryInterface:
+        class: Ray\InputQuery\InputQuery
+        arguments:
+            - '@ray.di.injector'
+    
+    ray.di.injector:
+        class: Ray\Di\Injector
+```
+
+## CakePHP Integration
+
+### Basic Setup
+
+```php
+// src/Controller/UsersController.php
+<?php
+
+namespace App\Controller;
+
+use Cake\Controller\Controller;
+use Ray\Di\Injector;
+use Ray\InputQuery\InputQuery;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+
+class UsersController extends Controller
+{
+    public function add()
+    {
+        if ($this->request->is('post')) {
+            $injector = new Injector();
+            $inputQuery = new InputQuery($injector);
+            
+            $method = new \ReflectionMethod($this, 'processUserData');
+            $args = $inputQuery->getArguments($method, $this->request->getData());
+            
+            $result = $this->processUserData(...$args);
+            
+            $this->set(['result' => $result]);
+            $this->viewBuilder()->setOption('serialize', ['result']);
+        }
+    }
+    
+    public function processUserData(
+        #[Input] string $name,
+        #[Input] string $email,
+        #[InputFile] FileUpload|ErrorFileUpload|null $profile_picture = null,
+    ): array {
+        if ($profile_picture instanceof ErrorFileUpload) {
+            throw new \InvalidArgumentException($profile_picture->message);
+        }
+        
+        $picturePath = null;
+        if ($profile_picture instanceof FileUpload) {
+            $picturePath = $profile_picture->move(WWW_ROOT . 'img' . DS . 'uploads');
+        }
+        
+        // Process user data
+        return ['success' => true, 'picture' => $picturePath];
+    }
+}
+```
+
+## BEAR.Sunday Integration
+
+### Resource Class
+
+```php
+// src/Resource/App/User.php
+<?php
+
+namespace MyApp\Resource\App;
+
+use BEAR\Resource\ResourceObject;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+
+class User extends ResourceObject
+{
+    public function onPost(
+        #[Input] string $name,
+        #[Input] string $email,
+        #[InputFile(
+            maxSize: 5 * 1024 * 1024,
+            allowedTypes: ['image/jpeg', 'image/png']
+        )] FileUpload|ErrorFileUpload $avatar,
+    ): static {
+        if ($avatar instanceof ErrorFileUpload) {
+            $this->code = 400;
+            $this->body = ['error' => $avatar->message];
+            return $this;
+        }
+        
+        $avatarPath = $avatar->move('/path/to/uploads');
+        
+        // User creation logic
+        $this->body = [
+            'name' => $name,
+            'email' => $email,
+            'avatar' => $avatarPath
+        ];
+        
+        return $this;
+    }
+}
+```
+
+## Yii Framework 1.x Integration
+
+### Basic Setup
+
+```php
+// protected/controllers/UserController.php
+<?php
+
+class UserController extends CController
+{
+    public function actionCreate()
+    {
+        if (Yii::app()->request->isPostRequest) {
+            $injector = new Ray\Di\Injector();
+            $inputQuery = new Ray\InputQuery\InputQuery($injector);
+            
+            $method = new ReflectionMethod($this, 'handleUserCreation');
+            $postData = array_merge($_POST, $_FILES);
+            $args = $inputQuery->getArguments($method, $postData);
+            
+            $result = $this->handleUserCreation(...$args);
+            
+            $this->renderJSON($result);
+        }
+    }
+    
+    public function handleUserCreation(
+        #[Ray\InputQuery\Attribute\Input] string $name,
+        #[Ray\InputQuery\Attribute\Input] string $email,
+        #[Ray\InputQuery\Attribute\InputFile(
+            maxSize: 5 * 1024 * 1024,
+            allowedTypes: ['image/jpeg', 'image/png']
+        )] Koriym\FileUpload\FileUpload|Koriym\FileUpload\ErrorFileUpload $avatar,
+    ): array {
+        if ($avatar instanceof Koriym\FileUpload\ErrorFileUpload) {
+            throw new CHttpException(400, $avatar->message);
+        }
+        
+        $uploadPath = Yii::getPathOfAlias('webroot.uploads');
+        $avatarPath = $avatar->move($uploadPath);
+        
+        // User creation logic
+        $user = new User();
+        $user->name = $name;
+        $user->email = $email;
+        $user->avatar = $avatarPath;
+        $user->save();
+        
+        return [
+            'success' => true,
+            'user' => $user->attributes,
+            'avatar' => $avatarPath
+        ];
+    }
+    
+    private function renderJSON($data)
+    {
+        header('Content-Type: application/json');
+        echo CJSON::encode($data);
+        Yii::app()->end();
+    }
+}
+```
+
+### Component Configuration
+
+```php
+// protected/config/main.php
+return array(
+    'components' => array(
+        'inputQuery' => array(
+            'class' => 'application.extensions.inputquery.InputQueryComponent',
+        ),
+        // ... other components
+    ),
+);
+```
+
+### Custom Component Class
+
+```php
+// protected/extensions/inputquery/InputQueryComponent.php
+<?php
+
+class InputQueryComponent extends CComponent
+{
+    private $inputQuery;
+    
+    public function init()
+    {
+        parent::init();
+        $injector = new Ray\Di\Injector();
+        $this->inputQuery = new Ray\InputQuery\InputQuery($injector);
+    }
+    
+    public function createInput($className, $data)
+    {
+        return $this->inputQuery->create($className, $data);
+    }
+    
+    public function getMethodArguments($controller, $method, $data)
+    {
+        $reflection = new ReflectionMethod($controller, $method);
+        return $this->inputQuery->getArguments($reflection, $data);
+    }
+}
+```
+
+### Form Helper Usage
+
+```php
+// protected/views/user/create.php
+<?php echo CHtml::beginForm('', 'post', array('enctype' => 'multipart/form-data')); ?>
+
+<div class="form-group">
+    <?php echo CHtml::label('Name', 'name'); ?>
+    <?php echo CHtml::textField('name', '', array('class' => 'form-control')); ?>
+</div>
+
+<div class="form-group">
+    <?php echo CHtml::label('Email', 'email'); ?>
+    <?php echo CHtml::emailField('email', '', array('class' => 'form-control')); ?>
+</div>
+
+<div class="form-group">
+    <?php echo CHtml::label('Avatar', 'avatar'); ?>
+    <?php echo CHtml::fileField('avatar', '', array('accept' => 'image/*')); ?>
+    <small class="form-text text-muted">Max 5MB, JPEG/PNG only</small>
+</div>
+
+<?php echo CHtml::submitButton('Create User', array('class' => 'btn btn-primary')); ?>
+<?php echo CHtml::endForm(); ?>
+```
+
+### Error Handling
+
+```php
+// protected/controllers/UserController.php
+public function actionCreate()
+{
+    if (Yii::app()->request->isPostRequest) {
+        try {
+            $injector = new Ray\Di\Injector();
+            $inputQuery = new Ray\InputQuery\InputQuery($injector);
+            
+            $method = new ReflectionMethod($this, 'handleUserCreation');
+            $args = $inputQuery->getArguments($method, $_POST);
+            
+            $result = $this->handleUserCreation(...$args);
+            
+            $this->renderJSON($result);
+        } catch (Exception $e) {
+            $this->renderJSON([
+                'success' => false,
+                'error' => $e->getMessage()
+            ]);
+        }
+    }
+}
+```
+
+## Slim Framework Integration
+
+### Basic Setup
+
+```php
+// src/Controller/UserController.php
+<?php
+
+use Psr\Http\Message\ResponseInterface as Response;
+use Psr\Http\Message\ServerRequestInterface as Request;
+use Ray\Di\Injector;
+use Ray\InputQuery\InputQuery;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+
+class UserController
+{
+    public function create(Request $request, Response $response): Response
+    {
+        $injector = new Injector();
+        $inputQuery = new InputQuery($injector);
+        
+        $method = new \ReflectionMethod($this, 'handleUserCreation');
+        $args = $inputQuery->getArguments($method, $request->getParsedBody() ?? []);
+        
+        $result = $this->handleUserCreation(...$args);
+        
+        $response->getBody()->write(json_encode($result));
+        return $response->withHeader('Content-Type', 'application/json');
+    }
+    
+    public function handleUserCreation(
+        #[Input] string $name,
+        #[Input] string $email,
+        #[InputFile] FileUpload|ErrorFileUpload|null $avatar = null,
+    ): array {
+        if ($avatar instanceof ErrorFileUpload) {
+            throw new \InvalidArgumentException($avatar->message);
+        }
+        
+        $avatarPath = null;
+        if ($avatar instanceof FileUpload) {
+            $avatarPath = $avatar->move(__DIR__ . '/../../uploads');
+        }
+        
+        return [
+            'success' => true,
+            'user' => ['name' => $name, 'email' => $email],
+            'avatar' => $avatarPath
+        ];
+    }
+}
+```
+
+## Testing Examples
+
+### PHPUnit Test for Framework Integration
+
+```php
+// tests/Integration/UserControllerTest.php
+<?php
+
+use PHPUnit\Framework\TestCase;
+use Ray\Di\Injector;
+use Ray\InputQuery\InputQuery;
+use Koriym\FileUpload\FileUpload;
+
+class UserControllerTest extends TestCase
+{
+    private InputQuery $inputQuery;
+    
+    protected function setUp(): void
+    {
+        $this->inputQuery = new InputQuery(new Injector());
+    }
+    
+    public function testUserCreationWithFileUpload(): void
+    {
+        $controller = new UserController();
+        $method = new \ReflectionMethod($controller, 'handleUserCreation');
+        
+        $mockAvatar = FileUpload::fromFile(__DIR__ . '/fixtures/test.jpg');
+        
+        $data = [
+            'name' => 'John Doe',
+            'email' => 'john@example.com',
+            'avatar' => $mockAvatar
+        ];
+        
+        $args = $this->inputQuery->getArguments($method, $data);
+        $result = $method->invokeArgs($controller, $args);
+        
+        $this->assertTrue($result['success']);
+        $this->assertEquals('John Doe', $result['user']['name']);
+    }
+}
+```
+
+## Common Patterns
+
+### 1. Method Reflection Pattern
+
+```php
+$method = new \ReflectionMethod($controller, 'methodName');
+$args = $inputQuery->getArguments($method, $requestData);
+$result = $method->invokeArgs($controller, $args);
+```
+
+### 2. Direct Object Creation Pattern
+
+```php
+$input = $inputQuery->create(UserInput::class, $requestData);
+$result = $controller->handleUser($input);
+```
+
+### 3. Spread Operator Pattern
+
+```php
+$args = $inputQuery->getArguments($method, $requestData);
+$result = $controller->methodName(...$args);
+```
+
+## Framework-Specific Considerations
+
+### Laravel
+- Use `$request->all()` for form data
+- Leverage Laravel's service container for InputQuery injection
+- Handle file uploads with Laravel's storage system
+
+### Symfony
+- Use `$request->request->all()` for POST data
+- Configure services in `services.yaml`
+- Integrate with Symfony's file handling
+
+### CakePHP
+- Use `$this->request->getData()` for request data
+- Follow CakePHP's controller conventions
+- Use CakePHP's file upload helpers
+
+### BEAR.Sunday
+- Ray.InputQuery works natively with BEAR.Sunday
+- Use directly in resource methods
+- Leverage BEAR's built-in DI container
+
+### Slim
+- Use `$request->getParsedBody()` for form data
+- Handle JSON responses appropriately
+- Configure DI container for InputQuery
+
+## Best Practices
+
+1. **Validation First**: Always check for `ErrorFileUpload` instances before processing
+2. **Type Safety**: Leverage union types for proper error handling
+3. **DI Integration**: Use framework-specific DI containers when possible
+4. **Testing**: Create mock `FileUpload` objects for unit tests
+5. **Error Handling**: Implement consistent error responses across frameworks
+
+---
+
+> **Note**: This document was generated with AI assistance. If you find any errors or have suggestions for improvements, please feel free to open an issue or submit a pull request. We welcome community feedback to make this documentation more accurate and helpful.
diff --git a/src/Attribute/Input.php b/src/Attribute/Input.php
index 709383e..954a51b 100644
--- a/src/Attribute/Input.php
+++ b/src/Attribute/Input.php
@@ -9,6 +9,7 @@
 #[Attribute(Attribute::TARGET_PARAMETER)]
 final class Input
 {
+    /** @param string|null $item Class name for array items */
     public function __construct(
         public readonly string|null $item = null,
     ) {
diff --git a/src/Attribute/InputFile.php b/src/Attribute/InputFile.php
new file mode 100644
index 0000000..3b8b2bc
--- /dev/null
+++ b/src/Attribute/InputFile.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PARAMETER)]
+final class InputFile
+{
+    /**
+     * @param int|null          $maxSize           Maximum file size in bytes
+     * @param list<string>|null $allowedTypes      Allowed MIME types
+     * @param list<string>|null $allowedExtensions Allowed file extensions
+     * @param bool              $required          Whether the file is required
+     *
+     * @SuppressWarnings("PHPMD.BooleanArgumentFlag") - Boolean flags are acceptable in attribute/configuration classes,
+     *                                                      as they represent configuration options, not behavioral flags
+     */
+    public function __construct(
+        public readonly int|null $maxSize = null,
+        public readonly array|null $allowedTypes = null,
+        public readonly array|null $allowedExtensions = null,
+        public readonly bool $required = true,
+    ) {
+    }
+}
diff --git a/src/Exception/InvalidFileUploadAttributeException.php b/src/Exception/InvalidFileUploadAttributeException.php
new file mode 100644
index 0000000..3ffb7c8
--- /dev/null
+++ b/src/Exception/InvalidFileUploadAttributeException.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Exception;
+
+use InvalidArgumentException;
+
+/**
+ * Exception thrown when FileUpload type parameters are incorrectly decorated with #[Input] instead of #[InputFile].
+ *
+ * File upload parameters must use the #[InputFile] attribute to properly handle validation options
+ * such as maxSize, allowedTypes, and allowedExtensions. Using #[Input] with FileUpload types
+ * bypasses these important validation features and is not allowed.
+ *
+ * Correct usage:
+ * - #[InputFile(maxSize: 5242880, allowedTypes: ['image/jpeg', 'image/png'])] FileUpload $avatar
+ * - #[InputFile] FileUpload $document
+ * - #[InputFile(item: FileUpload::class)] array $files
+ *
+ * Incorrect usage (will throw this exception):
+ * - #[Input] FileUpload $file
+ * - #[Input(item: FileUpload::class)] array $uploads
+ */
+final class InvalidFileUploadAttributeException extends InvalidArgumentException
+{
+}
diff --git a/src/FileUploadFactory.php b/src/FileUploadFactory.php
new file mode 100644
index 0000000..c4f2d23
--- /dev/null
+++ b/src/FileUploadFactory.php
@@ -0,0 +1,362 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery;
+
+use InvalidArgumentException;
+use Koriym\FileUpload\ErrorFileUpload;
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\InputFile;
+use ReflectionNamedType;
+use ReflectionParameter;
+use ReflectionUnionType;
+
+use function array_key_exists;
+use function count;
+use function is_array;
+use function is_subclass_of;
+use function sprintf;
+
+use const UPLOAD_ERR_NO_FILE;
+
+/**
+ * Factory for creating FileUpload objects with validation
+ *
+ * This class follows SRP (Single Responsibility Principle) and is responsible
+ * only for creating FileUpload objects from various data sources.
+ * It can be used independently from InputQuery in other contexts like BEAR.Resource.
+ *
+ * Uses service locator pattern for testability:
+ * - Production: Creates FileUpload from $_FILES data
+ * - Testing: Uses pre-created FileUpload objects from $query parameter
+ *
+ * @psalm-import-type Query from InputQueryInterface
+ * @psalm-import-type FileData from InputQuery
+ * @psalm-import-type MultipleFileData from InputQuery
+ * @psalm-import-type ValidationOptions from InputQuery
+ * @psalm-import-type FileUploadArray from InputQuery
+ * @psalm-import-type InputFileAttributes from InputQuery
+ */
+final class FileUploadFactory
+{
+    /**
+     * Create FileUpload from InputFile attribute and query data
+     *
+     * Primary method for InputQuery integration
+     *
+     * @param ReflectionParameter $param               Parameter metadata for file upload
+     * @param Query               $query               Service locator for pre-created FileUpload objects (testing) or empty array (production)
+     * @param InputFileAttributes $inputFileAttributes InputFile attribute instances containing validation options
+     */
+    public function create(ReflectionParameter $param, array $query, array $inputFileAttributes): mixed
+    {
+        // Validate that only one InputFile attribute is present
+        if (count($inputFileAttributes) > 1) {
+            throw new InvalidArgumentException(
+                'Only one #[InputFile] attribute is allowed per parameter',
+            );
+        }
+
+        $type = $param->getType();
+
+        // Handle union types (e.g., FileUpload|ErrorFileUpload|null)
+        if ($type instanceof ReflectionUnionType) {
+            if (! $this->isValidFileUploadUnion($type)) {
+                throw new InvalidArgumentException(
+                    'Unsupported union type for file upload parameter',
+                );
+            }
+
+            return $this->createWithValidation($param, $query, $inputFileAttributes);
+        }
+
+        // Handle single FileUpload type
+        if ($type instanceof ReflectionNamedType) {
+            if ($this->isFileUploadType($type->getName())) {
+                return $this->createWithValidation($param, $query, $inputFileAttributes);
+            }
+
+            // Handle array of FileUpload
+            if ($type->getName() === 'array') {
+                return $this->createArray($param->getName(), $query, $inputFileAttributes);
+            }
+        }
+
+        // Handle mixed type (no type hint) with InputFile attribute
+        if ($type === null) {
+            return $this->createWithValidation($param, $query, $inputFileAttributes);
+        }
+
+        throw new InvalidArgumentException(
+            sprintf('Parameter %s is not a valid file upload parameter', $param->getName()),
+        );
+    }
+
+    /**
+     * Create FileUpload directly from file data
+     *
+     * For use outside InputQuery context (e.g., BEAR.Resource, CLI tools)
+     *
+     * @param array<string, mixed> $filesData         $_FILES format data
+     * @param ValidationOptions    $validationOptions
+     */
+    public function createFromFiles(ReflectionParameter $param, array $filesData, array $validationOptions = []): mixed
+    {
+        return $this->resolveFileUpload($param, [], $validationOptions, $filesData);
+    }
+
+    /**
+     * Create array of FileUploads from InputFile attribute and query data
+     *
+     * @param Query               $query
+     * @param InputFileAttributes $inputFileAttributes
+     *
+     * @return FileUploadArray
+     */
+    public function createArray(string $paramName, array $query, array $inputFileAttributes): array
+    {
+        $validationOptions = $this->extractValidationOptions($inputFileAttributes);
+
+        return $this->createArrayOfFileUploads($paramName, $query, $validationOptions);
+    }
+
+    /**
+     * Check if this is a valid FileUpload union type for resolveUnionType
+     *
+     * @param Query $query
+     */
+    public function resolveFileUploadUnionType(ReflectionParameter $param, array $query, ReflectionUnionType $type): mixed
+    {
+        if (! $this->isValidFileUploadUnion($type)) {
+            return null; // Not a file upload union type
+        }
+
+        // This is a valid FileUpload union, handle as file upload
+        $inputFileAttrs = $param->getAttributes(InputFile::class);
+        $validationOptions = $this->extractValidationOptions($inputFileAttrs);
+
+        return $this->resolveFileUpload($param, $query, $validationOptions);
+    }
+
+    /**
+     * Check if a class name represents a FileUpload type
+     */
+    public function isFileUploadType(string $className): bool
+    {
+        if ($className === FileUpload::class || $className === ErrorFileUpload::class) {
+            return true;
+        }
+
+        return is_subclass_of($className, FileUpload::class) || is_subclass_of($className, ErrorFileUpload::class);
+    }
+
+    /**
+     * Check if union type is valid for file uploads
+     */
+    private function isValidFileUploadUnion(ReflectionUnionType $type): bool
+    {
+        $unionTypes = $type->getTypes();
+
+        foreach ($unionTypes as $unionType) {
+            if (! $unionType instanceof ReflectionNamedType) {
+                // @codeCoverageIgnoreStart
+                // This case occurs with PHP 8.2+ intersection types in union types like (A&B)|C
+                // Cannot be tested in PHP < 8.2 due to syntax errors
+                return false;
+                // @codeCoverageIgnoreEnd
+            }
+
+            $typeName = $unionType->getName();
+            // Allow FileUpload types (with or without namespace) and null
+            if (! $this->isFileUploadType($typeName) && $typeName !== 'null') {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Create FileUpload with validation from InputFile attributes
+     *
+     * @param Query               $query
+     * @param InputFileAttributes $inputFileAttributes
+     */
+    private function createWithValidation(ReflectionParameter $param, array $query, array $inputFileAttributes): mixed
+    {
+        $validationOptions = $this->extractValidationOptions($inputFileAttributes);
+
+        return $this->resolveFileUpload($param, $query, $validationOptions);
+    }
+
+    /**
+     * Extract validation options from InputFile attributes
+     *
+     * @param InputFileAttributes $inputFileAttributes
+     *
+     * @return ValidationOptions
+     */
+    private function extractValidationOptions(array $inputFileAttributes): array
+    {
+        if (empty($inputFileAttributes)) {
+            return [];
+        }
+
+        $inputFile = $inputFileAttributes[0]->newInstance();
+        $options = [];
+
+        if ($inputFile->maxSize !== null && $inputFile->maxSize > 0) {
+            $options['maxSize'] = $inputFile->maxSize;
+        }
+
+        if ($inputFile->allowedTypes !== null) {
+            $options['allowedTypes'] = $inputFile->allowedTypes;
+        }
+
+        if ($inputFile->allowedExtensions !== null) {
+            $options['allowedExtensions'] = $inputFile->allowedExtensions;
+        }
+
+        return $options;
+    }
+
+    /**
+     * Core file upload resolution logic
+     *
+     * Uses service locator pattern: checks $query first for pre-created FileUpload objects (testing),
+     * then falls back to $_FILES or custom $filesData (production).
+     *
+     * @param ReflectionParameter       $param             Parameter metadata
+     * @param Query                     $query             Service locator for pre-created FileUpload objects
+     * @param ValidationOptions         $validationOptions Validation rules for file upload
+     * @param array<string, mixed>|null $filesData         Custom files data (for createFromFiles)
+     */
+    private function resolveFileUpload(ReflectionParameter $param, array $query, array $validationOptions = [], array|null $filesData = null): mixed
+    {
+        $paramName = $param->getName();
+
+        // Service locator: check if FileUpload is already provided (for testing/mocking)
+        if (array_key_exists($paramName, $query)) {
+            return $query[$paramName];
+        }
+
+        // Use provided files data or $_FILES
+        $files = $filesData ?? $_FILES;
+
+        // Try to create from file data
+        if (isset($files[$paramName])) {
+            /** @var FileData $fileData */
+            $fileData = $files[$paramName];
+
+            // Check if no file was uploaded (UPLOAD_ERR_NO_FILE)
+            if ($fileData['error'] === UPLOAD_ERR_NO_FILE) {
+                return $this->getDefaultValueOrThrow($param, "Required file parameter '{$paramName}' is missing");
+            }
+
+            return FileUpload::create($fileData, $validationOptions);
+        }
+
+        // No file found
+        return $this->getDefaultValueOrThrow($param, "Required file parameter '{$paramName}' is missing");
+    }
+
+    /**
+     * Create array of FileUploads from various data sources
+     *
+     * @param Query             $query
+     * @param ValidationOptions $validationOptions
+     *
+     * @return FileUploadArray
+     */
+    private function createArrayOfFileUploads(string $paramName, array $query, array $validationOptions = []): array
+    {
+        // Check if FileUpload array is provided in query (for testing)
+        if (array_key_exists($paramName, $query) && is_array($query[$paramName])) {
+            /** @var FileUploadArray $result */
+            $result = $query[$paramName];
+
+            return $result;
+        }
+
+        // Try to create from $_FILES
+        if (! isset($_FILES[$paramName])) {
+            return [];
+        }
+
+        /** @var array<string, mixed> $arrayData */
+        $arrayData = $_FILES[$paramName];
+
+        // Check if this is HTML multiple file upload format
+        if (isset($arrayData['name']) && is_array($arrayData['name'])) {
+            /** @var MultipleFileData $arrayData */
+            return $this->convertMultipleFileFormat($arrayData, $validationOptions);
+        }
+
+        // Handle regular array format (each element is a complete file array)
+        $result = [];
+
+        /** @var FileData $fileData */
+        foreach ($arrayData as $key => $fileData) {
+            // Skip files that weren't uploaded
+            if ($fileData['error'] === UPLOAD_ERR_NO_FILE) {
+                continue;
+            }
+
+            $result[$key] = FileUpload::create($fileData, $validationOptions);
+        }
+
+        return $result;
+    }
+
+    /**
+     * Convert multiple file format to individual FileUpload objects
+     *
+     * @param MultipleFileData  $multipleFileData
+     * @param ValidationOptions $validationOptions
+     *
+     * @return FileUploadArray
+     */
+    private function convertMultipleFileFormat(array $multipleFileData, array $validationOptions = []): array
+    {
+        /** @var MultipleFileData $multipleFileData */
+
+        $result = [];
+        $fileCount = count($multipleFileData['name']);
+
+        for ($i = 0; $i < $fileCount; $i++) {
+            $fileData = [
+                'name' => $multipleFileData['name'][$i] ?? '',
+                'type' => $multipleFileData['type'][$i] ?? '',
+                'size' => $multipleFileData['size'][$i] ?? 0,
+                'tmp_name' => $multipleFileData['tmp_name'][$i] ?? '',
+                'error' => $multipleFileData['error'][$i] ?? UPLOAD_ERR_NO_FILE,
+            ];
+
+            // Skip files that weren't uploaded
+            if ($fileData['error'] === UPLOAD_ERR_NO_FILE) {
+                continue;
+            }
+
+            $result[$i] = FileUpload::create($fileData, $validationOptions);
+        }
+
+        return $result;
+    }
+
+    /**
+     * Helper method to get default value or throw exception
+     */
+    private function getDefaultValueOrThrow(ReflectionParameter $param, string $message): mixed
+    {
+        if ($param->isDefaultValueAvailable()) {
+            return $param->getDefaultValue();
+        }
+
+        if ($param->allowsNull()) {
+            return null;
+        }
+
+        throw new InvalidArgumentException($message);
+    }
+}
diff --git a/src/InputQuery.php b/src/InputQuery.php
index d10d90a..0ac189b 100644
--- a/src/InputQuery.php
+++ b/src/InputQuery.php
@@ -6,17 +6,22 @@
 
 use ArrayObject;
 use InvalidArgumentException;
+use Koriym\FileUpload\ErrorFileUpload;
+use Koriym\FileUpload\FileUpload;
 use Override;
 use Ray\Di\Di\Named;
 use Ray\Di\Di\Qualifier;
 use Ray\Di\Exception\Unbound;
 use Ray\Di\InjectorInterface;
 use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+use Ray\InputQuery\Exception\InvalidFileUploadAttributeException;
 use ReflectionAttribute;
 use ReflectionClass;
 use ReflectionMethod;
 use ReflectionNamedType;
 use ReflectionParameter;
+use ReflectionUnionType;
 
 use function array_key_exists;
 use function assert;
@@ -42,12 +47,30 @@
 /**
  * @template T of object
  * @implements InputQueryInterface<T>
+ * @psalm-import-type Query from InputQueryInterface
+ * @psalm-type FileData = array{name: string, type: string, size: int, tmp_name: string, error: int}
+ * @psalm-type FileNameArray = array<int, string>
+ * @psalm-type FileTypeArray = array<int, string>
+ * @psalm-type FileSizeArray = array<int, int>
+ * @psalm-type FileTmpNameArray = array<int, string>
+ * @psalm-type FileErrorArray = array<int, int>
+ * @psalm-type MultipleFileData = array{name: FileNameArray, type: FileTypeArray, size: FileSizeArray, tmp_name: FileTmpNameArray, error: FileErrorArray}
+ * @psalm-type ValidationOptions = array{maxSize?: int<1, max>, allowedTypes?: list<string>, allowedExtensions?: list<string>}
+ * @psalm-type FileUploadArray = array<array-key, FileUpload|ErrorFileUpload>
+ * @psalm-type NestedQuery = array<string, mixed>
+ * @psalm-type InputArray = array<int, mixed>
+ * @psalm-type ParameterValue = scalar|array<array-key, mixed>|object|null
+ * @psalm-type InputAttributes = array<ReflectionAttribute<Input>>
+ * @psalm-type InputFileAttributes = array<ReflectionAttribute<InputFile>>
  */
 final class InputQuery implements InputQueryInterface
 {
+    private FileUploadFactory $fileUploadFactory;
+
     public function __construct(
         private InjectorInterface $injector,
     ) {
+        $this->fileUploadFactory = new FileUploadFactory();
     }
 
     /**
@@ -66,8 +89,8 @@ public function getArguments(ReflectionMethod $method, array $query): array
     }
 
     /**
-     * @param class-string<T>      $class
-     * @param array<string, mixed> $query
+     * @param class-string<T> $class
+     * @param Query           $query
      *
      * @return T
      */
@@ -86,29 +109,58 @@ public function create(string $class, array $query): object
         return $reflection->newInstanceArgs($args);
     }
 
-    /** @param array<string, mixed> $query */
+    /** @param Query $query */
     private function resolveParameter(ReflectionParameter $param, array $query): mixed
     {
         $inputAttributes = $param->getAttributes(Input::class);
+        $inputFileAttributes = $param->getAttributes(InputFile::class);
         $hasInputAttribute = ! empty($inputAttributes);
+        $hasInputFileAttribute = ! empty($inputFileAttributes);
+
+        if ($hasInputAttribute && $hasInputFileAttribute) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Parameter $%s cannot have both #[Input] and #[InputFile] attributes at the same time.',
+                    $param->getName(),
+                ),
+            );
+        }
 
-        if (! $hasInputAttribute) {
-            // No #[Input] attribute - get from DI
+        if (! $hasInputAttribute && ! $hasInputFileAttribute) {
+            // No #[Input] or #[InputFile] attribute - get from DI
             return $this->resolveFromDI($param);
         }
 
+        if ($hasInputFileAttribute) {
+            return $this->resolveInputFileParameter($param, $query, $inputFileAttributes);
+        }
+
         return $this->resolveInputParameter($param, $query, $inputAttributes);
     }
 
     /**
-     * @param array<string, mixed>              $query
-     * @param array<ReflectionAttribute<Input>> $inputAttributes
+     * @param Query               $query
+     * @param InputFileAttributes $inputFileAttributes
+     */
+    private function resolveInputFileParameter(ReflectionParameter $param, array $query, array $inputFileAttributes): mixed
+    {
+        return $this->fileUploadFactory->create($param, $query, $inputFileAttributes);
+    }
+
+    /**
+     * @param Query           $query
+     * @param InputAttributes $inputAttributes
      */
     private function resolveInputParameter(ReflectionParameter $param, array $query, array $inputAttributes): mixed
     {
         $type = $param->getType();
         $paramName = $param->getName();
 
+        // Handle union types (e.g., FileUpload|ErrorFileUpload)
+        if ($type instanceof ReflectionUnionType) {
+            return $this->resolveUnionType($param, $query, $type);
+        }
+
         if (! $type instanceof ReflectionNamedType) {
             return $query[$paramName] ?? $this->getDefaultValue($param);
         }
@@ -121,8 +173,8 @@ private function resolveInputParameter(ReflectionParameter $param, array $query,
     }
 
     /**
-     * @param array<string, mixed>              $query
-     * @param array<ReflectionAttribute<Input>> $inputAttributes
+     * @param Query           $query
+     * @param InputAttributes $inputAttributes
      */
     private function resolveBuiltinType(ReflectionParameter $param, array $query, array $inputAttributes, ReflectionNamedType $type): mixed
     {
@@ -134,6 +186,13 @@ private function resolveBuiltinType(ReflectionParameter $param, array $query, ar
                 assert(class_exists($inputAttribute->item));
                 $itemClass = $inputAttribute->item;
 
+                // Check if array items are FileUpload types
+                if ($this->fileUploadFactory->isFileUploadType($itemClass)) {
+                    throw new InvalidFileUploadAttributeException(
+                        sprintf('FileUpload array parameter "%s" must use #[InputFile] attribute, not #[Input]', $paramName),
+                    );
+                }
+
                 /** @var class-string<T> $itemClass */
                 return $this->createArrayOfInputs($paramName, $query, $itemClass);
             }
@@ -147,14 +206,21 @@ private function resolveBuiltinType(ReflectionParameter $param, array $query, ar
     }
 
     /**
-     * @param array<string, mixed>              $query
-     * @param array<ReflectionAttribute<Input>> $inputAttributes
+     * @param Query           $query
+     * @param InputAttributes $inputAttributes
      */
     private function resolveObjectType(ReflectionParameter $param, array $query, array $inputAttributes, ReflectionNamedType $type): mixed
     {
         $paramName = $param->getName();
         $className = $type->getName();
 
+        // Check for FileUpload types - must use #[InputFile] not #[Input]
+        if ($this->fileUploadFactory->isFileUploadType($className)) {
+            throw new InvalidFileUploadAttributeException(
+                sprintf('FileUpload parameter "%s" must use #[InputFile] attribute, not #[Input]', $paramName),
+            );
+        }
+
         // Check for ArrayObject types with item specification
         $arrayObjectResult = $this->resolveArrayObjectType($paramName, $query, $inputAttributes, $className);
         if ($arrayObjectResult !== null) {
@@ -176,8 +242,8 @@ private function resolveObjectType(ReflectionParameter $param, array $query, arr
     }
 
     /**
-     * @param array<string, mixed>              $query
-     * @param array<ReflectionAttribute<Input>> $inputAttributes
+     * @param Query           $query
+     * @param InputAttributes $inputAttributes
      */
     private function resolveArrayObjectType(string $paramName, array $query, array $inputAttributes, string $className): mixed
     {
@@ -269,15 +335,26 @@ private function getQualifier(ReflectionParameter $param): string
 
     private function getDefaultValue(ReflectionParameter $param): mixed
     {
+        return $this->getDefaultValueOrThrow(
+            $param,
+            sprintf('Required parameter "%s" is missing and has no default value', $param->getName()),
+        );
+    }
+
+    /**
+     * Get the default value of a parameter or throw an exception with a custom message
+     */
+    private function getDefaultValueOrThrow(ReflectionParameter $param, string $message): mixed
+    {
+        if ($param->allowsNull()) {
+            return null;
+        }
+
         if ($param->isDefaultValueAvailable()) {
             return $param->getDefaultValue();
         }
 
-        // Required parameter without default value
-        throw new InvalidArgumentException(sprintf(
-            'Required parameter "%s" is missing and has no default value',
-            $param->getName(),
-        ));
+        throw new InvalidArgumentException($message);
     }
 
     private function convertScalar(mixed $value, ReflectionNamedType $type): mixed
@@ -296,9 +373,9 @@ private function convertScalar(mixed $value, ReflectionNamedType $type): mixed
     }
 
     /**
-     * @param array<string, mixed> $query
+     * @param Query $query
      *
-     * @return array<string, mixed>
+     * @return Query
      */
     private function extractNestedQuery(string $paramName, array $query): array
     {
@@ -333,8 +410,8 @@ private function toCamelCase(string $string): string
     }
 
     /**
-     * @param array<string, mixed> $query
-     * @param class-string<T>      $itemClass
+     * @param Query           $query
+     * @param class-string<T> $itemClass
      *
      * @return array<array-key, T>
      */
@@ -372,4 +449,19 @@ private function createArrayOfInputs(string $paramName, array $query, string $it
 
         return $result;
     }
+
+    /** @param Query $query */
+    private function resolveUnionType(ReflectionParameter $param, array $query, ReflectionUnionType $type): mixed
+    {
+        // Check if this is a file upload union type, delegate to FileUploadFactory
+        $fileUploadResult = $this->fileUploadFactory->resolveFileUploadUnionType($param, $query, $type);
+        if ($fileUploadResult !== null) {
+            return $fileUploadResult;
+        }
+
+        // Not a FileUpload union type, handle as regular parameter
+        $paramName = $param->getName();
+
+        return $query[$paramName] ?? $this->getDefaultValue($param);
+    }
 }
diff --git a/src/InputQueryInterface.php b/src/InputQueryInterface.php
index 5c8c4c1..016e696 100644
--- a/src/InputQueryInterface.php
+++ b/src/InputQueryInterface.php
@@ -6,13 +6,16 @@
 
 use ReflectionMethod;
 
-/** @template T of object */
+/**
+ * @template T of object
+ * @psalm-type Query = array<string, mixed>
+ */
 interface InputQueryInterface
 {
     /**
      * Get method arguments from query data
      *
-     * @param array<string, mixed> $query
+     * @param Query $query HTTP request data ($_POST, $_GET, etc.)
      *
      * @return array<mixed>
      */
@@ -21,8 +24,8 @@ public function getArguments(ReflectionMethod $method, array $query): array;
     /**
      * Create object from query data
      *
-     * @param class-string<T>      $class
-     * @param array<string, mixed> $query
+     * @param class-string<T> $class
+     * @param Query           $query HTTP request data ($_POST, $_GET, etc.)
      *
      * @return T
      */
diff --git a/tests/Fake/ArrayObjectController.php b/tests/Fake/ArrayObjectController.php
new file mode 100644
index 0000000..ac52c77
--- /dev/null
+++ b/tests/Fake/ArrayObjectController.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use ArrayObject;
+use Ray\InputQuery\Attribute\Input;
+
+final class ArrayObjectController
+{
+    /**
+     * Test ArrayObject creation
+     */
+    public function processArrayObject(#[Input(item: UserInput::class)] ArrayObject $users): void
+    {
+        // Test ArrayObject creation with item type
+    }
+
+    /**
+     * Test ArrayObject without item type
+     */
+    public function processArrayObjectNoItem(#[Input] ArrayObject $items): void
+    {
+        // Test ArrayObject without item type - should return null and fall back
+    }
+
+    /**
+     * Test custom ArrayObject subclass
+     */
+    public function processCustomArrayObject(#[Input(item: UserInput::class)] UserArrayObject $users): void
+    {
+        // Test custom ArrayObject subclass
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/ComplexInputController.php b/tests/Fake/ComplexInputController.php
new file mode 100644
index 0000000..add48b4
--- /dev/null
+++ b/tests/Fake/ComplexInputController.php
@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Ray\InputQuery\Attribute\Input;
+
+final class ComplexInputController
+{
+    /**
+     * Test union type parameter without Input attribute
+     */
+    public function processUnionTypeNoInput(string|int $value = 'default'): void
+    {
+        // Union type without #[Input] should use default value
+    }
+
+    /**
+     * Test nullable parameter with Input attribute
+     */
+    public function processNullableParam(#[Input] ?string $optional): void
+    {
+        // Nullable parameter handling
+    }
+
+    /**
+     * Test mixed parameters (no type hint)
+     */
+    public function processMixedType(#[Input] $data): void
+    {
+        // No type hint parameter
+    }
+
+    /**
+     * Test nested object extraction patterns
+     */
+    public function processNestedExtraction(#[Input] UserInput $user): void
+    {
+        // Should handle nested query extraction patterns like user_name -> UserInput->name
+    }
+
+    /**
+     * Test array with complex nested objects
+     */
+    public function processComplexArray(#[Input(item: UserInput::class)] array $users): void
+    {
+        // Array of complex objects
+    }
+
+    /**
+     * Test scalar conversions
+     */
+    public function processScalarConversions(
+        #[Input] string $text,
+        #[Input] int $number,
+        #[Input] float $decimal,
+        #[Input] bool $flag
+    ): void {
+        // Various scalar type conversions
+    }
+
+    /**
+     * Test string array processing
+     */
+    public function processStringArray(#[Input] array $items): void
+    {
+        // Test array of strings without item type specified
+    }
+
+    /**
+     * Test default parameter value extraction
+     */
+    public function processWithDefaults(
+        #[Input] string $required,
+        string $optional = 'default_value'
+    ): void {
+        // Test parameter with default but without Input attribute
+    }
+
+    /**
+     * Test int array processing without item type
+     */
+    public function processIntArray(#[Input] array $numbers): void
+    {
+        // Test array of primitive int types without item specification
+    }
+
+    /**
+     * Test parameter that requires default value
+     */
+    public function processRequiresDefault(string $param): void
+    {
+        // Test parameter without Input and without default - should get null
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/ConflictingAttributesInput.php b/tests/Fake/ConflictingAttributesInput.php
new file mode 100644
index 0000000..70a5218
--- /dev/null
+++ b/tests/Fake/ConflictingAttributesInput.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class ConflictingAttributesInput
+{
+    public function __construct(
+        #[Input]
+        #[InputFile]
+        public mixed $conflictingParam = null,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/DefaultFileInput.php b/tests/Fake/DefaultFileInput.php
new file mode 100644
index 0000000..f6c5640
--- /dev/null
+++ b/tests/Fake/DefaultFileInput.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class DefaultFileInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[InputFile] public readonly FileUpload|ErrorFileUpload|null $avatar = null,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/FileUploadArrayInput.php b/tests/Fake/FileUploadArrayInput.php
new file mode 100644
index 0000000..1f3529d
--- /dev/null
+++ b/tests/Fake/FileUploadArrayInput.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\Input;
+
+final class FileUploadArrayInput
+{
+    /**
+     * @param list<FileUpload> $images
+     */
+    public function __construct(
+        #[Input] public readonly string $title,
+        #[Input] public readonly array $images,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/FileUploadController.php b/tests/Fake/FileUploadController.php
new file mode 100644
index 0000000..670835a
--- /dev/null
+++ b/tests/Fake/FileUploadController.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class FileUploadController
+{
+    /**
+     * Test single file upload
+     */
+    public function uploadSingle(#[InputFile] FileUpload $file): void
+    {
+        // Single file upload
+    }
+
+    /**
+     * Test multiple file uploads  
+     */
+    public function uploadMultiple(#[InputFile] array $files): void
+    {
+        // Multiple file uploads
+    }
+
+    /**
+     * Test file upload with validation options
+     */
+    public function uploadWithValidation(
+        #[InputFile(maxSize: 1024, allowedTypes: ['image/jpeg'])] FileUpload $image
+    ): void {
+        // File upload with validation
+    }
+
+    /**
+     * Test multiple files with validation
+     */
+    public function uploadMultipleWithValidation(
+        #[InputFile(maxSize: 2048, allowedTypes: ['image/png', 'image/jpeg'])] array $images
+    ): void {
+        // Multiple files with validation
+    }
+
+    /**
+     * Test nullable file upload
+     */
+    public function uploadNullable(#[InputFile] ?FileUpload $file): void
+    {
+        // Nullable file upload
+    }
+
+    /**
+     * Test file upload with default value
+     */
+    public function uploadWithDefault(#[InputFile] ?FileUpload $file = null): void
+    {
+        // File upload with default value
+    }
+
+    /**
+     * Test required file upload (no default, not nullable)
+     */
+    public function uploadRequired(#[InputFile] FileUpload $file): void
+    {
+        // Required file upload - should throw exception if UPLOAD_ERR_NO_FILE
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/FileUploadInput.php b/tests/Fake/FileUploadInput.php
new file mode 100644
index 0000000..cb7bb97
--- /dev/null
+++ b/tests/Fake/FileUploadInput.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\ErrorFileUpload;
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\Input;
+
+final class FileUploadInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[Input] public readonly FileUpload|ErrorFileUpload $avatar,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/FileUploadWithOptionsInput.php b/tests/Fake/FileUploadWithOptionsInput.php
new file mode 100644
index 0000000..b7d8b22
--- /dev/null
+++ b/tests/Fake/FileUploadWithOptionsInput.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\ErrorFileUpload;
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\Input;
+
+final class FileUploadWithOptionsInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[Input] public readonly FileUpload|ErrorFileUpload $avatar,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/InputFileExtensionValidationInput.php b/tests/Fake/InputFileExtensionValidationInput.php
new file mode 100644
index 0000000..80aa93a
--- /dev/null
+++ b/tests/Fake/InputFileExtensionValidationInput.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class InputFileExtensionValidationInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[InputFile(
+            maxSize: 5 * 1024 * 1024,
+            allowedTypes: ['image/jpeg', 'image/png'],
+            allowedExtensions: ['jpg', 'jpeg', 'png']
+        )]
+        public readonly FileUpload|ErrorFileUpload $avatar,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/InputFileInput.php b/tests/Fake/InputFileInput.php
new file mode 100644
index 0000000..43af553
--- /dev/null
+++ b/tests/Fake/InputFileInput.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class InputFileInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[InputFile] public readonly FileUpload|ErrorFileUpload $avatar,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/InputFileValidationInput.php b/tests/Fake/InputFileValidationInput.php
new file mode 100644
index 0000000..b37c1e2
--- /dev/null
+++ b/tests/Fake/InputFileValidationInput.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class InputFileValidationInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[InputFile(maxSize: 1024, allowedTypes: ['image/jpeg', 'image/png'])]
+        public readonly FileUpload|ErrorFileUpload $avatar,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/InputFileWithOptionsInput.php b/tests/Fake/InputFileWithOptionsInput.php
new file mode 100644
index 0000000..bf7f3e4
--- /dev/null
+++ b/tests/Fake/InputFileWithOptionsInput.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class InputFileWithOptionsInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[InputFile(maxSize: 2048000, allowedTypes: ['image/jpeg', 'image/png'])] 
+        public readonly FileUpload|ErrorFileUpload $avatar,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/InvalidFileUploadController.php b/tests/Fake/InvalidFileUploadController.php
new file mode 100644
index 0000000..e55cd49
--- /dev/null
+++ b/tests/Fake/InvalidFileUploadController.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\Input;
+
+final class InvalidFileUploadController
+{
+    /**
+     * Invalid usage: #[Input] with FileUpload type
+     */
+    public function uploadWithWrongAttribute(
+        #[Input] FileUpload $file
+    ): void {
+        // This should throw InvalidFileUploadAttributeException
+    }
+
+    /**
+     * Invalid usage: #[Input] with FileUpload array
+     */
+    public function uploadArrayWithWrongAttribute(
+        #[Input(item: FileUpload::class)] array $files
+    ): void {
+        // This should throw InvalidFileUploadAttributeException
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/MixedFileController.php b/tests/Fake/MixedFileController.php
new file mode 100644
index 0000000..ac2b494
--- /dev/null
+++ b/tests/Fake/MixedFileController.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Ray\InputQuery\Attribute\InputFile;
+
+final class MixedFileController
+{
+    /**
+     * Test file upload with no type hint (mixed)
+     */
+    public function uploadMixed(#[InputFile] $file): void
+    {
+        // Mixed type parameter with InputFile attribute
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/MultipleInputFileAttributesInput.php b/tests/Fake/MultipleInputFileAttributesInput.php
new file mode 100644
index 0000000..6d64f23
--- /dev/null
+++ b/tests/Fake/MultipleInputFileAttributesInput.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Ray\InputQuery\Attribute\InputFile;
+
+final class MultipleInputFileAttributesInput
+{
+    public function __construct(
+        #[InputFile(maxSize: 1024)]
+        #[InputFile(allowedTypes: ['image/jpeg'])]
+        public mixed $file = null,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/NullableFileInput.php b/tests/Fake/NullableFileInput.php
new file mode 100644
index 0000000..a9b5387
--- /dev/null
+++ b/tests/Fake/NullableFileInput.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\FileUpload;
+use Koriym\FileUpload\ErrorFileUpload;
+use Ray\InputQuery\Attribute\Input;
+use Ray\InputQuery\Attribute\InputFile;
+
+final class NullableFileInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[InputFile] public readonly FileUpload|ErrorFileUpload|null $avatar,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/OptionalFileUploadInput.php b/tests/Fake/OptionalFileUploadInput.php
new file mode 100644
index 0000000..1437028
--- /dev/null
+++ b/tests/Fake/OptionalFileUploadInput.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use Koriym\FileUpload\ErrorFileUpload;
+use Koriym\FileUpload\FileUpload;
+use Ray\InputQuery\Attribute\Input;
+
+final class OptionalFileUploadInput
+{
+    public function __construct(
+        #[Input] public readonly string $name,
+        #[Input] public readonly FileUpload|ErrorFileUpload|null $banner = null,
+    ) {
+    }
+}
\ No newline at end of file
diff --git a/tests/Fake/UserArrayObject.php b/tests/Fake/UserArrayObject.php
new file mode 100644
index 0000000..0c602f1
--- /dev/null
+++ b/tests/Fake/UserArrayObject.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery\Fake;
+
+use ArrayObject;
+
+/**
+ * Custom ArrayObject subclass for testing
+ *
+ * @extends ArrayObject<int, UserInput>
+ */
+final class UserArrayObject extends ArrayObject
+{
+    /**
+     * @param array<UserInput> $array
+     */
+    public function __construct(array $array = [])
+    {
+        parent::__construct($array);
+    }
+}
\ No newline at end of file
diff --git a/tests/FileUploadFactoryTest.php b/tests/FileUploadFactoryTest.php
new file mode 100644
index 0000000..f02d750
--- /dev/null
+++ b/tests/FileUploadFactoryTest.php
@@ -0,0 +1,218 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery;
+
+use InvalidArgumentException;
+use Koriym\FileUpload\ErrorFileUpload;
+use Koriym\FileUpload\FileUpload;
+use PHPUnit\Framework\TestCase;
+use ReflectionMethod;
+use ReflectionUnionType;
+
+use const UPLOAD_ERR_NO_FILE;
+use const UPLOAD_ERR_OK;
+
+final class FileUploadFactoryTest extends TestCase
+{
+    private FileUploadFactory $factory;
+
+    protected function setUp(): void
+    {
+        $this->factory = new FileUploadFactory();
+    }
+
+    public function testCreateFromFiles(): void
+    {
+        $method = new ReflectionMethod($this, 'dummyMethodForFileUpload');
+        $param = $method->getParameters()[0];
+
+        $filesData = [
+            'upload' => [
+                'name' => 'test.txt',
+                'type' => 'text/plain',
+                'size' => 100,
+                'tmp_name' => '/tmp/test',
+                'error' => UPLOAD_ERR_OK,
+            ],
+        ];
+
+        $validationOptions = [
+            'maxSize' => 1024,
+            'allowedTypes' => ['text/plain'],
+        ];
+
+        $result = $this->factory->createFromFiles($param, $filesData, $validationOptions);
+
+        $this->assertInstanceOf(FileUpload::class, $result);
+    }
+
+    public function testCreateFromFilesWithMissingFile(): void
+    {
+        $method = new ReflectionMethod($this, 'dummyMethodForNullableFileUpload');
+        $param = $method->getParameters()[0];
+
+        $filesData = [];
+
+        $result = $this->factory->createFromFiles($param, $filesData);
+
+        $this->assertNull($result);
+    }
+
+    public function testCreateFromFilesWithErrorFile(): void
+    {
+        $method = new ReflectionMethod($this, 'dummyMethodForFileUpload');
+        $param = $method->getParameters()[0];
+
+        $filesData = [
+            'upload' => [
+                'name' => 'test.txt',
+                'type' => 'text/plain',
+                'size' => 100,
+                'tmp_name' => '/tmp/test',
+                'error' => UPLOAD_ERR_NO_FILE,
+            ],
+        ];
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("Required file parameter 'upload' is missing");
+
+        $this->factory->createFromFiles($param, $filesData);
+    }
+
+    public function testResolveFileUploadUnionTypeWithValidUnion(): void
+    {
+        $method = new ReflectionMethod($this, 'dummyMethodForUnionType');
+        $param = $method->getParameters()[0];
+        $unionType = $param->getType();
+
+        $this->assertInstanceOf(ReflectionUnionType::class, $unionType);
+
+        $query = [
+            'upload' => FileUpload::create([
+                'name' => 'test.txt',
+                'type' => 'text/plain',
+                'size' => 100,
+                'tmp_name' => '/tmp/test',
+                'error' => UPLOAD_ERR_OK,
+            ]),
+        ];
+
+        $result = $this->factory->resolveFileUploadUnionType($param, $query, $unionType);
+
+        $this->assertInstanceOf(FileUpload::class, $result);
+    }
+
+    public function testResolveFileUploadUnionTypeWithInvalidUnion(): void
+    {
+        $method = new ReflectionMethod($this, 'dummyMethodForInvalidUnionType');
+        $param = $method->getParameters()[0];
+        $unionType = $param->getType();
+
+        $this->assertInstanceOf(ReflectionUnionType::class, $unionType);
+
+        $query = [];
+
+        $result = $this->factory->resolveFileUploadUnionType($param, $query, $unionType);
+
+        $this->assertNull($result);
+    }
+
+    public function testIsFileUploadType(): void
+    {
+        $this->assertTrue($this->factory->isFileUploadType(FileUpload::class));
+        $this->assertTrue($this->factory->isFileUploadType(ErrorFileUpload::class));
+        $this->assertFalse($this->factory->isFileUploadType('stdClass'));
+        $this->assertFalse($this->factory->isFileUploadType('NonExistentClass'));
+    }
+
+    public function testCreateArrayWithEmptyQuery(): void
+    {
+        $inputFileAttributes = [];
+        $result = $this->factory->createArray('uploads', [], $inputFileAttributes);
+
+        $this->assertIsArray($result);
+        $this->assertEmpty($result);
+    }
+
+    public function testCreateArrayWithProvidedFileUploads(): void
+    {
+        $fileUploads = [
+            FileUpload::create([
+                'name' => 'test1.txt',
+                'type' => 'text/plain',
+                'size' => 100,
+                'tmp_name' => '/tmp/test1',
+                'error' => UPLOAD_ERR_OK,
+            ]),
+            FileUpload::create([
+                'name' => 'test2.txt',
+                'type' => 'text/plain',
+                'size' => 200,
+                'tmp_name' => '/tmp/test2',
+                'error' => UPLOAD_ERR_OK,
+            ]),
+        ];
+
+        $query = ['uploads' => $fileUploads];
+        $inputFileAttributes = [];
+
+        $result = $this->factory->createArray('uploads', $query, $inputFileAttributes);
+
+        $this->assertIsArray($result);
+        $this->assertCount(2, $result);
+        $this->assertSame($fileUploads, $result);
+    }
+
+    public function testCreateWithUnsupportedUnionType(): void
+    {
+        $method = new ReflectionMethod($this, 'dummyMethodForInvalidUnionType');
+        $param = $method->getParameters()[0];
+        $inputFileAttributes = [];
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Unsupported union type for file upload parameter');
+
+        $this->factory->create($param, [], $inputFileAttributes);
+    }
+
+    public function testCreateWithInvalidParameterType(): void
+    {
+        $method = new ReflectionMethod($this, 'dummyMethodForInvalidParameterType');
+        $param = $method->getParameters()[0];
+        $inputFileAttributes = [];
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Parameter invalidParam is not a valid file upload parameter');
+
+        $this->factory->create($param, [], $inputFileAttributes);
+    }
+
+    /**
+     * Dummy methods for reflection testing
+     */
+    public function dummyMethodForFileUpload(FileUpload $upload): void
+    {
+    }
+
+    public function dummyMethodForNullableFileUpload(FileUpload|null $upload): void
+    {
+    }
+
+    public function dummyMethodForUnionType(FileUpload|ErrorFileUpload|null $upload): void
+    {
+    }
+
+    public function dummyMethodForInvalidUnionType(string|int $value): void
+    {
+    }
+
+    public function dummyMethodForMixedType(mixed $upload): void
+    {
+    }
+
+    public function dummyMethodForInvalidParameterType(string $invalidParam): void
+    {
+    }
+}
diff --git a/tests/FileUploadTest.php b/tests/FileUploadTest.php
new file mode 100644
index 0000000..7389b55
--- /dev/null
+++ b/tests/FileUploadTest.php
@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery;
+
+use Koriym\FileUpload\FileUpload;
+use PHPUnit\Framework\TestCase;
+use Ray\Di\Injector;
+use Ray\InputQuery\Fake\FileUploadArrayInput;
+use Ray\InputQuery\Fake\FileUploadInput;
+use Ray\InputQuery\Fake\FileUploadWithOptionsInput;
+use Ray\InputQuery\Fake\OptionalFileUploadInput;
+
+use const UPLOAD_ERR_OK;
+
+class FileUploadTest extends TestCase
+{
+    private InputQuery $inputQuery;
+
+    protected function setUp(): void
+    {
+        $this->inputQuery = new InputQuery(new Injector());
+    }
+
+    public function testFileUploadIntegration(): void
+    {
+        // Create mock FileUpload
+        $mockAvatar = FileUpload::create([
+            'name' => 'test-avatar.jpg',
+            'type' => 'image/jpeg',
+            'size' => 1024,
+            'tmp_name' => '/tmp/php_upload_test',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+
+        // Pass FileUpload directly in query
+        $query = [
+            'name' => 'Jingu',
+            'avatar' => $mockAvatar,
+        ];
+
+        $result = $this->inputQuery->create(FileUploadInput::class, $query);
+
+        $this->assertSame('Jingu', $result->name);
+        $this->assertSame($mockAvatar, $result->avatar);
+        $this->assertSame('test-avatar.jpg', $result->avatar->name);
+        $this->assertSame('image/jpeg', $result->avatar->type);
+        $this->assertSame(1024, $result->avatar->size);
+    }
+
+    public function testFileUploadWithValidationOptions(): void
+    {
+        $mockAvatar = FileUpload::create([
+            'name' => 'test-image.png',
+            'type' => 'image/png',
+            'size' => 1500,
+            'tmp_name' => '/tmp/php_upload_test2',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+
+        $query = [
+            'name' => 'Horikawa',
+            'avatar' => $mockAvatar,
+        ];
+
+        $result = $this->inputQuery->create(FileUploadWithOptionsInput::class, $query);
+
+        $this->assertSame('Horikawa', $result->name);
+        $this->assertSame($mockAvatar, $result->avatar);
+        $this->assertSame('test-image.png', $result->avatar->name);
+    }
+
+    public function testOptionalFileUpload(): void
+    {
+        $query = [
+            'name' => 'Test User',
+            'banner' => null,
+        ];
+
+        $result = $this->inputQuery->create(OptionalFileUploadInput::class, $query);
+
+        $this->assertSame('Test User', $result->name);
+        $this->assertNull($result->banner);
+    }
+
+    public function testFileUploadArray(): void
+    {
+        $mockImage1 = FileUpload::create([
+            'name' => 'image1.jpg',
+            'type' => 'image/jpeg',
+            'size' => 1024,
+            'tmp_name' => '/tmp/php_upload_1',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+
+        $mockImage2 = FileUpload::create([
+            'name' => 'image2.png',
+            'type' => 'image/png',
+            'size' => 2048,
+            'tmp_name' => '/tmp/php_upload_2',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+
+        $query = [
+            'title' => 'Gallery',
+            'images' => [$mockImage1, $mockImage2],
+        ];
+
+        $result = $this->inputQuery->create(FileUploadArrayInput::class, $query);
+
+        $this->assertSame('Gallery', $result->title);
+        $this->assertCount(2, $result->images);
+        $this->assertSame($mockImage1, $result->images[0]);
+        $this->assertSame($mockImage2, $result->images[1]);
+        $this->assertSame('image1.jpg', $result->images[0]->name);
+        $this->assertSame('image2.png', $result->images[1]->name);
+    }
+}
diff --git a/tests/InputFileTest.php b/tests/InputFileTest.php
new file mode 100644
index 0000000..c4bd8a0
--- /dev/null
+++ b/tests/InputFileTest.php
@@ -0,0 +1,227 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\InputQuery;
+
+use InvalidArgumentException;
+use Koriym\FileUpload\ErrorFileUpload;
+use Koriym\FileUpload\FileUpload;
+use PHPUnit\Framework\TestCase;
+use Ray\Di\Injector;
+use Ray\InputQuery\Fake\ConflictingAttributesInput;
+use Ray\InputQuery\Fake\InputFileExtensionValidationInput;
+use Ray\InputQuery\Fake\InputFileInput;
+use Ray\InputQuery\Fake\InputFileValidationInput;
+use Ray\InputQuery\Fake\InputFileWithOptionsInput;
+use Ray\InputQuery\Fake\MultipleInputFileAttributesInput;
+
+use const UPLOAD_ERR_OK;
+
+final class InputFileTest extends TestCase
+{
+    private InputQuery $inputQuery;
+
+    protected function setUp(): void
+    {
+        $this->inputQuery = new InputQuery(new Injector());
+    }
+
+    public function testCreateFileInputFromQuery(): void
+    {
+        $fileUpload = FileUpload::create([
+            'name' => 'test.txt',
+            'type' => 'text/plain',
+            'size' => 100,
+            'tmp_name' => '/tmp/test',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $query = ['name' => 'test user', 'avatar' => $fileUpload];
+
+        $input = $this->inputQuery->create(InputFileInput::class, $query);
+
+        $this->assertInstanceOf(InputFileInput::class, $input);
+        $this->assertSame($fileUpload, $input->avatar);
+    }
+
+    public function testCreateFileInputWithOptionsFromQuery(): void
+    {
+        $fileUpload = FileUpload::create([
+            'name' => 'test.jpg',
+            'type' => 'image/jpeg',
+            'size' => 500,
+            'tmp_name' => '/tmp/test',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $query = ['name' => 'test user', 'avatar' => $fileUpload];
+
+        $input = $this->inputQuery->create(InputFileWithOptionsInput::class, $query);
+
+        $this->assertInstanceOf(InputFileWithOptionsInput::class, $input);
+        $this->assertSame($fileUpload, $input->avatar);
+    }
+
+    public function testCreateFileInputFromFiles(): void
+    {
+        // Simulate $_FILES data
+        $_FILES['avatar'] = [
+            'name' => 'test.txt',
+            'type' => 'text/plain',
+            'size' => 100,
+            'tmp_name' => '/tmp/test',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileInput::class, $query);
+
+        $this->assertInstanceOf(InputFileInput::class, $input);
+        $this->assertInstanceOf(FileUpload::class, $input->avatar);
+        $this->assertSame('test.txt', $input->avatar->name);
+        $this->assertSame('text/plain', $input->avatar->type);
+        $this->assertSame(100, $input->avatar->size);
+    }
+
+    public function testFileValidationMaxSizeError(): void
+    {
+        // Simulate $_FILES data with large file
+        $_FILES['avatar'] = [
+            'name' => 'large.jpg',
+            'type' => 'image/jpeg',
+            'size' => 2048, // 2KB, exceeds 1KB limit
+            'tmp_name' => '/tmp/large',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileValidationInput::class, $query);
+
+        $this->assertInstanceOf(InputFileValidationInput::class, $input);
+        $this->assertInstanceOf(ErrorFileUpload::class, $input->avatar);
+        $this->assertNotNull($input->avatar->message);
+        $this->assertStringContainsString('File size exceeds maximum allowed size', $input->avatar->message);
+    }
+
+    public function testFileValidationTypeError(): void
+    {
+        // Simulate $_FILES data with wrong type
+        $_FILES['avatar'] = [
+            'name' => 'document.pdf',
+            'type' => 'application/pdf',
+            'size' => 500,
+            'tmp_name' => '/tmp/document',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileValidationInput::class, $query);
+
+        $this->assertInstanceOf(InputFileValidationInput::class, $input);
+        $this->assertInstanceOf(ErrorFileUpload::class, $input->avatar);
+        $this->assertNotNull($input->avatar->message);
+        $this->assertStringContainsString('File type application/pdf is not allowed', $input->avatar->message);
+    }
+
+    public function testFileValidationSuccess(): void
+    {
+        // Simulate $_FILES data with valid file
+        $_FILES['avatar'] = [
+            'name' => 'small.jpg',
+            'type' => 'image/jpeg',
+            'size' => 500,
+            'tmp_name' => '/tmp/small',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileValidationInput::class, $query);
+
+        $this->assertInstanceOf(InputFileValidationInput::class, $input);
+        $this->assertInstanceOf(FileUpload::class, $input->avatar);
+        $this->assertSame('small.jpg', $input->avatar->name);
+        $this->assertSame(500, $input->avatar->size);
+    }
+
+    public function testFileValidationExtensionError(): void
+    {
+        // Simulate $_FILES data with invalid extension
+        $_FILES['avatar'] = [
+            'name' => 'document.pdf',
+            'type' => 'image/jpeg', // Valid type but invalid extension
+            'size' => 500,
+            'tmp_name' => '/tmp/document',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileExtensionValidationInput::class, $query);
+
+        $this->assertInstanceOf(InputFileExtensionValidationInput::class, $input);
+        $this->assertInstanceOf(ErrorFileUpload::class, $input->avatar);
+        $this->assertNotNull($input->avatar->message);
+        $this->assertStringContainsString('File extension pdf is not allowed', $input->avatar->message);
+    }
+
+    public function testFileValidationExtensionSuccess(): void
+    {
+        // Simulate $_FILES data with valid extension
+        $_FILES['avatar'] = [
+            'name' => 'image.jpg',
+            'type' => 'image/jpeg',
+            'size' => 500,
+            'tmp_name' => '/tmp/image',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileExtensionValidationInput::class, $query);
+
+        $this->assertInstanceOf(InputFileExtensionValidationInput::class, $input);
+        $this->assertInstanceOf(FileUpload::class, $input->avatar);
+        $this->assertSame('image.jpg', $input->avatar->name);
+    }
+
+    public function testFileValidationExtensionCaseInsensitive(): void
+    {
+        // Test uppercase extension
+        $_FILES['avatar'] = [
+            'name' => 'image.JPG', // Uppercase extension
+            'type' => 'image/jpeg',
+            'size' => 500,
+            'tmp_name' => '/tmp/image',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileExtensionValidationInput::class, $query);
+
+        $this->assertInstanceOf(InputFileExtensionValidationInput::class, $input);
+        // This should fail because pathinfo() is case-sensitive
+        $this->assertInstanceOf(ErrorFileUpload::class, $input->avatar);
+        $this->assertStringContainsString('File extension JPG is not allowed', $input->avatar->message);
+    }
+
+    public function testMultipleInputFileAttributesThrowsException(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Only one #[InputFile] attribute is allowed per parameter');
+
+        $query = ['name' => 'test user'];
+        $this->inputQuery->create(MultipleInputFileAttributesInput::class, $query);
+    }
+
+    public function testConflictingInputAndInputFileAttributesThrowsException(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Parameter $conflictingParam cannot have both #[Input] and #[InputFile] attributes at the same time.');
+
+        $query = ['name' => 'test user'];
+        $this->inputQuery->create(ConflictingAttributesInput::class, $query);
+    }
+
+    protected function tearDown(): void
+    {
+        // Clean up $_FILES
+        $_FILES = [];
+    }
+}
diff --git a/tests/InputQueryTest.php b/tests/InputQueryTest.php
index cc4b6ad..d413cec 100644
--- a/tests/InputQueryTest.php
+++ b/tests/InputQueryTest.php
@@ -4,18 +4,29 @@
 
 namespace Ray\InputQuery;
 
+use ArrayObject;
 use InvalidArgumentException;
+use Koriym\FileUpload\FileUpload;
 use PHPUnit\Framework\TestCase;
 use Ray\Di\AbstractModule;
 use Ray\Di\Injector;
+use Ray\InputQuery\Exception\InvalidFileUploadAttributeException;
+use Ray\InputQuery\Fake\ArrayObjectController;
 use Ray\InputQuery\Fake\AuthorInput;
+use Ray\InputQuery\Fake\ComplexInputController;
 use Ray\InputQuery\Fake\DatabaseService;
+use Ray\InputQuery\Fake\DefaultFileInput;
 use Ray\InputQuery\Fake\DefaultValuesInput;
 use Ray\InputQuery\Fake\DITestController;
+use Ray\InputQuery\Fake\FileUploadController;
+use Ray\InputQuery\Fake\InputFileInput;
+use Ray\InputQuery\Fake\InvalidFileUploadController;
+use Ray\InputQuery\Fake\MixedFileController;
 use Ray\InputQuery\Fake\MixedInput;
 use Ray\InputQuery\Fake\NoConstructorInput;
 use Ray\InputQuery\Fake\NonInputParameterController;
 use Ray\InputQuery\Fake\NonNamedTypeController;
+use Ray\InputQuery\Fake\NullableFileInput;
 use Ray\InputQuery\Fake\NullableInput;
 use Ray\InputQuery\Fake\Primary;
 use Ray\InputQuery\Fake\ScalarInput;
@@ -24,18 +35,30 @@
 use Ray\InputQuery\Fake\TodoController;
 use Ray\InputQuery\Fake\TodoInput;
 use Ray\InputQuery\Fake\UnionTypeInput;
+use Ray\InputQuery\Fake\UserArrayObject;
 use Ray\InputQuery\Fake\UserInput;
 use ReflectionClass;
 use ReflectionMethod;
 
+use function array_values;
 use function assert;
+use function count;
+
+use const UPLOAD_ERR_NO_FILE;
+use const UPLOAD_ERR_OK;
 
 final class InputQueryTest extends TestCase
 {
     private InputQueryInterface $inputQuery;
 
+    /** @var array<string, mixed> */
+    private array $originalFiles;
+
     protected function setUp(): void
     {
+        // $_FILESの元の状態を保存
+        $this->originalFiles = $_FILES;
+
         $injector = new Injector(new class extends AbstractModule {
             protected function configure(): void
             {
@@ -57,6 +80,12 @@ protected function configure(): void
         $this->inputQuery = new InputQuery($injector);
     }
 
+    protected function tearDown(): void
+    {
+        // $_FILESを元の状態に復元
+        $_FILES = $this->originalFiles;
+    }
+
     public function testCreateSimpleObject(): void
     {
         $query = [
@@ -525,4 +554,754 @@ public function testUnboundDIParameterException(): void
 
         $this->inputQuery->getArguments($method, $query);
     }
+
+    public function testInvalidFileUploadAttributeException(): void
+    {
+        // Test #[Input] with FileUpload type should throw exception
+        $method = new ReflectionMethod(InvalidFileUploadController::class, 'uploadWithWrongAttribute');
+        $query = [];
+
+        $this->expectException(InvalidFileUploadAttributeException::class);
+        $this->expectExceptionMessage('FileUpload parameter "file" must use #[InputFile] attribute, not #[Input]');
+
+        $this->inputQuery->getArguments($method, $query);
+    }
+
+    public function testInvalidFileUploadArrayAttributeException(): void
+    {
+        // Test #[Input] with FileUpload array should throw exception
+        $method = new ReflectionMethod(InvalidFileUploadController::class, 'uploadArrayWithWrongAttribute');
+        $query = [];
+
+        $this->expectException(InvalidFileUploadAttributeException::class);
+        $this->expectExceptionMessage('FileUpload array parameter "files" must use #[InputFile] attribute, not #[Input]');
+
+        $this->inputQuery->getArguments($method, $query);
+    }
+
+    public function testUnionTypeWithoutInputAttribute(): void
+    {
+        // Test union type parameter without #[Input] should get default value
+        $method = new ReflectionMethod(ComplexInputController::class, 'processUnionTypeNoInput');
+        $query = [];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertSame('default', $args[0]);
+    }
+
+    public function testNullableParameterHandling(): void
+    {
+        // Test nullable parameter handling - should use default value without DI
+        $method = new ReflectionMethod(ComplexInputController::class, 'processNullableParam');
+        $query = [];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertNull($args[0]); // nullable parameter gets null default
+    }
+
+    public function testMixedTypeParameter(): void
+    {
+        // Test parameter with no type hint
+        $method = new ReflectionMethod(ComplexInputController::class, 'processMixedType');
+        $query = ['data' => 'test-value'];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertSame('test-value', $args[0]);
+    }
+
+    public function testNestedObjectExtraction(): void
+    {
+        // Test nested query extraction patterns (user_name -> UserInput->name)
+        $method = new ReflectionMethod(ComplexInputController::class, 'processNestedExtraction');
+        $query = [
+            'user_name' => 'NestedUser',
+            'user_email' => 'nested@example.com',
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $userInput = $args[0];
+        $this->assertInstanceOf(UserInput::class, $userInput);
+        $this->assertSame('NestedUser', $userInput->name);
+        $this->assertSame('nested@example.com', $userInput->email);
+    }
+
+    public function testComplexArrayObjects(): void
+    {
+        // Test array of complex objects
+        $method = new ReflectionMethod(ComplexInputController::class, 'processComplexArray');
+        $query = [
+            'users' => [
+                ['name' => 'User1', 'email' => 'user1@example.com'],
+                ['name' => 'User2', 'email' => 'user2@example.com'],
+            ],
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $users = $args[0];
+        $this->assertIsArray($users);
+        $this->assertCount(2, $users);
+
+        $this->assertInstanceOf(UserInput::class, $users[0]);
+        $this->assertSame('User1', $users[0]->name);
+        $this->assertSame('user1@example.com', $users[0]->email);
+
+        $this->assertInstanceOf(UserInput::class, $users[1]);
+        $this->assertSame('User2', $users[1]->name);
+        $this->assertSame('user2@example.com', $users[1]->email);
+    }
+
+    public function testScalarConversions(): void
+    {
+        // Test various scalar type conversions
+        $method = new ReflectionMethod(ComplexInputController::class, 'processScalarConversions');
+        $query = [
+            'text' => 'sample text',
+            'number' => '42',
+            'decimal' => '3.14',
+            'flag' => 'true',
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(4, $args);
+        $this->assertSame('sample text', $args[0]);
+        $this->assertSame(42, $args[1]);
+        $this->assertSame(3.14, $args[2]);
+        $this->assertTrue($args[3]);
+    }
+
+    public function testParameterDefaultFromReflection(): void
+    {
+        // Test getting default values from parameter reflection
+        $method = new ReflectionMethod(ComplexInputController::class, 'processUnionTypeNoInput');
+        $query = [];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertSame('default', $args[0]); // Uses parameter default value
+    }
+
+    public function testStringArrayProcessing(): void
+    {
+        // Test array processing without item type
+        $method = new ReflectionMethod(ComplexInputController::class, 'processStringArray');
+        $query = [
+            'items' => ['item1', 'item2', 'item3'],
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertSame(['item1', 'item2', 'item3'], $args[0]);
+    }
+
+    public function testMixedInputAndNonInputParameters(): void
+    {
+        // Test method with both Input and non-Input parameters
+        $method = new ReflectionMethod(ComplexInputController::class, 'processWithDefaults');
+        $query = ['required' => 'test_value'];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(2, $args);
+        $this->assertSame('test_value', $args[0]); // Input parameter
+        $this->assertSame('default_value', $args[1]); // Non-Input with default
+    }
+
+    public function testIntArrayProcessing(): void
+    {
+        // Test array without item type - should pass through as-is
+        $method = new ReflectionMethod(ComplexInputController::class, 'processIntArray');
+        $query = [
+            'numbers' => ['1', '2', '3', '4', '5'],
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertSame(['1', '2', '3', '4', '5'], $args[0]); // strings remain as strings without item type
+    }
+
+    public function testParameterWithoutInputOrDefault(): void
+    {
+        // Test parameter without Input attribute and without default - should trigger DI exception
+        $method = new ReflectionMethod(ComplexInputController::class, 'processRequiresDefault');
+        $query = [];
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Parameter "param" of type ":" is not bound in the injector.');
+
+        $this->inputQuery->getArguments($method, $query);
+    }
+
+    public function testNullableStringConversion(): void
+    {
+        // Test nullable parameter with actual null value
+        $method = new ReflectionMethod(ComplexInputController::class, 'processNullableParam');
+        $query = ['optional' => null];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertNull($args[0]);
+    }
+
+    public function testNullableStringWithValue(): void
+    {
+        // Test nullable parameter with actual value
+        $method = new ReflectionMethod(ComplexInputController::class, 'processNullableParam');
+        $query = ['optional' => 'test_value'];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertSame('test_value', $args[0]);
+    }
+
+    public function testEmptyArrayProcessing(): void
+    {
+        // Test empty array processing
+        $method = new ReflectionMethod(ComplexInputController::class, 'processStringArray');
+        $query = ['items' => []];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertEmpty($args[0]);
+    }
+
+    public function testMixedArrayValues(): void
+    {
+        // Test array with mixed values (no item type specified)
+        $method = new ReflectionMethod(ComplexInputController::class, 'processStringArray');
+        $query = [
+            'items' => ['string', 123, true, null],
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertSame(['string', 123, true, null], $args[0]);
+    }
+
+    public function testArrayObjectCreation(): void
+    {
+        // Test ArrayObject creation with item type
+        $method = new ReflectionMethod(ArrayObjectController::class, 'processArrayObject');
+        $query = [
+            'users' => [
+                ['name' => 'User1', 'email' => 'user1@example.com'],
+                ['name' => 'User2', 'email' => 'user2@example.com'],
+            ],
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertInstanceOf(ArrayObject::class, $args[0]);
+        /** @var ArrayObject $arrayObject */
+        $arrayObject = $args[0];
+        $this->assertCount(2, $arrayObject);
+        $this->assertInstanceOf(UserInput::class, $arrayObject[0]);
+        $this->assertSame('User1', $arrayObject[0]->name);
+    }
+
+    public function testArrayObjectWithoutItemType(): void
+    {
+        // Test ArrayObject without item type - should create empty ArrayObject
+        $method = new ReflectionMethod(ArrayObjectController::class, 'processArrayObjectNoItem');
+        $query = ['items' => ['test']];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        // ArrayObject without item type creates empty ArrayObject via regular object creation
+        $this->assertInstanceOf(ArrayObject::class, $args[0]);
+        /** @var ArrayObject $arrayObject */
+        $arrayObject = $args[0];
+        $this->assertCount(0, $arrayObject); // Empty because no constructor parameters matched
+    }
+
+    public function testCustomArrayObjectSubclass(): void
+    {
+        // Test custom ArrayObject subclass
+        $method = new ReflectionMethod(ArrayObjectController::class, 'processCustomArrayObject');
+        $query = [
+            'users' => [
+                ['name' => 'User1', 'email' => 'user1@example.com'],
+                ['name' => 'User2', 'email' => 'user2@example.com'],
+            ],
+        ];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertInstanceOf(UserArrayObject::class, $args[0]);
+        /** @var UserArrayObject $userArrayObject */
+        $userArrayObject = $args[0];
+        $this->assertCount(2, $userArrayObject);
+        $this->assertInstanceOf(UserInput::class, $userArrayObject[0]);
+        $this->assertSame('User1', $userArrayObject[0]->name);
+    }
+
+    public function testSingleFileUpload(): void
+    {
+        // Test single file upload with #[InputFile]
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadSingle');
+        $fileUpload = FileUpload::create([
+            'name' => 'test.txt',
+            'type' => 'text/plain',
+            'size' => 100,
+            'tmp_name' => '/tmp/test',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $query = ['file' => $fileUpload];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertSame($fileUpload, $args[0]);
+    }
+
+    public function testMultipleFileUpload(): void
+    {
+        // Test multiple file upload with array
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadMultiple');
+        $file1 = FileUpload::create([
+            'name' => 'test1.txt',
+            'type' => 'text/plain',
+            'size' => 100,
+            'tmp_name' => '/tmp/test1',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $file2 = FileUpload::create([
+            'name' => 'test2.txt',
+            'type' => 'text/plain',
+            'size' => 200,
+            'tmp_name' => '/tmp/test2',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $query = ['files' => [$file1, $file2]];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertCount(2, $args[0]);
+        $this->assertSame($file1, $args[0][0]);
+        $this->assertSame($file2, $args[0][1]);
+    }
+
+    public function testFileUploadWithValidation(): void
+    {
+        // Test file upload with validation options
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadWithValidation');
+        $fileUpload = FileUpload::create([
+            'name' => 'image.jpg',
+            'type' => 'image/jpeg',
+            'size' => 500,
+            'tmp_name' => '/tmp/image',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $query = ['image' => $fileUpload];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertSame($fileUpload, $args[0]);
+    }
+
+    public function testMultipleFileUploadWithValidation(): void
+    {
+        // Test multiple file upload with validation
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadMultipleWithValidation');
+        $file1 = FileUpload::create([
+            'name' => 'image1.png',
+            'type' => 'image/png',
+            'size' => 1000,
+            'tmp_name' => '/tmp/image1',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $file2 = FileUpload::create([
+            'name' => 'image2.jpg',
+            'type' => 'image/jpeg',
+            'size' => 1500,
+            'tmp_name' => '/tmp/image2',
+            'error' => UPLOAD_ERR_OK,
+        ]);
+        $query = ['images' => [$file1, $file2]];
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertCount(2, $args[0]);
+        $this->assertSame($file1, $args[0][0]);
+        $this->assertSame($file2, $args[0][1]);
+    }
+
+    public function testInputFileParameterFromFiles(): void
+    {
+        // Test resolveInputFileParameter using $_FILES - covers single file processing
+        $_FILES['file'] = [
+            'name' => 'test.txt',
+            'type' => 'text/plain',
+            'size' => 100,
+            'tmp_name' => '/tmp/test',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadSingle');
+        $query = []; // Empty query, should get from $_FILES
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertInstanceOf(FileUpload::class, $args[0]);
+        $this->assertSame('test.txt', $args[0]->name);
+    }
+
+    public function testInputFileArrayFromFiles(): void
+    {
+        // Test createArrayOfFileUploadsWithValidation using $_FILES array
+        $_FILES['files'] = [
+            [
+                'name' => 'file1.txt',
+                'type' => 'text/plain',
+                'size' => 100,
+                'tmp_name' => '/tmp/file1',
+                'error' => UPLOAD_ERR_OK,
+            ],
+            [
+                'name' => 'file2.txt',
+                'type' => 'text/plain',
+                'size' => 200,
+                'tmp_name' => '/tmp/file2',
+                'error' => UPLOAD_ERR_OK,
+            ],
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadMultiple');
+        $query = []; // Empty query, should get from $_FILES
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertCount(2, $args[0]);
+        $this->assertInstanceOf(FileUpload::class, $args[0][0]);
+        $this->assertInstanceOf(FileUpload::class, $args[0][1]);
+    }
+
+    public function testConvertMultipleFileFormat(): void
+    {
+        // Test convertMultipleFileFormat using PHP $_FILES multiple format
+        $_FILES['files'] = [
+            'name' => ['file1.txt', 'file2.txt'],
+            'type' => ['text/plain', 'text/plain'],
+            'tmp_name' => ['/tmp/file1', '/tmp/file2'],
+            'size' => [100, 200],
+            'error' => [0, 0],
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadMultiple');
+        $query = []; // Empty query, should get from $_FILES
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertGreaterThan(0, count($args[0]));
+        foreach ($args[0] as $file) {
+            $this->assertInstanceOf(FileUpload::class, $file);
+        }
+    }
+
+    public function testInputFileCreateMethod(): void
+    {
+        // Test using create() method like existing InputFileTest
+        $_FILES['avatar'] = [
+            'name' => 'test.txt',
+            'type' => 'text/plain',
+            'size' => 100,
+            'tmp_name' => '/tmp/test',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        // Use existing InputFileInput class that has #[InputFile] attribute
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(InputFileInput::class, $query);
+
+        $this->assertInstanceOf(InputFileInput::class, $input);
+        $this->assertInstanceOf(FileUpload::class, $input->avatar);
+        $this->assertSame('test.txt', $input->avatar->name);
+    }
+
+    public function testConvertMultipleFileFormatWithNoFile(): void
+    {
+        // Test convertMultipleFileFormat with UPLOAD_ERR_NO_FILE - covers continue statement
+        $_FILES['files'] = [
+            'name' => ['file1.txt', '', 'file3.txt'],
+            'type' => ['text/plain', '', 'text/plain'],
+            'tmp_name' => ['/tmp/file1', '', '/tmp/file3'],
+            'size' => [100, 0, 300],
+            'error' => [UPLOAD_ERR_OK, UPLOAD_ERR_NO_FILE, UPLOAD_ERR_OK],
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadMultiple');
+        $query = []; // Empty query, should get from $_FILES
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+
+        // Debug output
+        foreach ($args[0] as $key => $file) {
+            if ($file instanceof FileUpload) {
+                $this->assertInstanceOf(FileUpload::class, $file);
+            }
+        }
+
+        // The array should contain 2 files (skipping UPLOAD_ERR_NO_FILE)
+        $files = array_values($args[0]); // Re-index to ensure sequential keys
+        $this->assertCount(2, $files);
+        $this->assertInstanceOf(FileUpload::class, $files[0]);
+        $this->assertSame('file1.txt', $files[0]->name);
+        $this->assertInstanceOf(FileUpload::class, $files[1]);
+        $this->assertSame('file3.txt', $files[1]->name);
+    }
+
+    public function testFileUploadArrayEmptyFiles(): void
+    {
+        // Test createArrayOfFileUploads when $_FILES is not set - should return empty array
+        // Clear $_FILES to trigger the empty return path
+        unset($_FILES['files']);
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadMultiple');
+        $query = []; // Empty query
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertEmpty($args[0]); // Should be empty array
+    }
+
+    public function testNullableFileUploadWithNoFile(): void
+    {
+        // Test nullable file parameter with UPLOAD_ERR_NO_FILE
+        $_FILES['avatar'] = [
+            'name' => '',
+            'type' => '',
+            'size' => 0,
+            'tmp_name' => '',
+            'error' => UPLOAD_ERR_NO_FILE,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(NullableFileInput::class, $query);
+
+        $this->assertInstanceOf(NullableFileInput::class, $input);
+        $this->assertNull($input->avatar); // Should be null for nullable parameter
+    }
+
+    public function testDefaultFileUploadWithNoFile(): void
+    {
+        // Test file parameter with default value when UPLOAD_ERR_NO_FILE
+        $_FILES['avatar'] = [
+            'name' => '',
+            'type' => '',
+            'size' => 0,
+            'tmp_name' => '',
+            'error' => UPLOAD_ERR_NO_FILE,
+        ];
+
+        $query = ['name' => 'test user'];
+        $input = $this->inputQuery->create(DefaultFileInput::class, $query);
+
+        $this->assertInstanceOf(DefaultFileInput::class, $input);
+        $this->assertNull($input->avatar); // Should use default value (null)
+    }
+
+    public function testRequiredFileUploadWithNoFile(): void
+    {
+        // Test required file parameter with UPLOAD_ERR_NO_FILE - should throw exception
+        $_FILES['file'] = [
+            'name' => '',
+            'type' => '',
+            'size' => 0,
+            'tmp_name' => '',
+            'error' => UPLOAD_ERR_NO_FILE,
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadRequired');
+        $query = []; // Empty query
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("Required file parameter 'file' is missing");
+
+        $this->inputQuery->getArguments($method, $query);
+    }
+
+    public function testNullableFileUploadWithNoFileMethod(): void
+    {
+        // Test nullable file parameter in method with UPLOAD_ERR_NO_FILE
+        $_FILES['file'] = [
+            'name' => '',
+            'type' => '',
+            'size' => 0,
+            'tmp_name' => '',
+            'error' => UPLOAD_ERR_NO_FILE,
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadNullable');
+        $query = []; // Empty query
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertNull($args[0]); // Should be null for nullable parameter
+    }
+
+    public function testDefaultFileUploadWithNoFileMethod(): void
+    {
+        // Test file parameter with default value in method when UPLOAD_ERR_NO_FILE
+        $_FILES['file'] = [
+            'name' => '',
+            'type' => '',
+            'size' => 0,
+            'tmp_name' => '',
+            'error' => UPLOAD_ERR_NO_FILE,
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadWithDefault');
+        $query = []; // Empty query
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertNull($args[0]); // Should use default value (null)
+    }
+
+    public function testFileUploadMissingInFiles(): void
+    {
+        // Test when file is not in $_FILES at all (not even with UPLOAD_ERR_NO_FILE)
+        unset($_FILES['file']); // Make sure file key doesn't exist in $_FILES
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadNullable');
+        $query = []; // Empty query
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertNull($args[0]); // Should be null for nullable parameter
+    }
+
+    public function testFileUploadMissingInFilesWithDefault(): void
+    {
+        // Test when file is not in $_FILES and parameter has default value
+        unset($_FILES['file']); // Make sure file key doesn't exist in $_FILES
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadWithDefault');
+        $query = []; // Empty query
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertNull($args[0]); // Should use default value (null)
+    }
+
+    public function testFileUploadMissingInFilesRequired(): void
+    {
+        // Test when required file is not in $_FILES at all - should throw exception
+        unset($_FILES['file']); // Make sure file key doesn't exist in $_FILES
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadRequired');
+        $query = []; // Empty query
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("Required file parameter 'file' is missing");
+
+        $this->inputQuery->getArguments($method, $query);
+    }
+
+    public function testFileUploadArrayRegularFormatWithNoFile(): void
+    {
+        // Test regular array format with UPLOAD_ERR_NO_FILE - covers continue in foreach
+        $_FILES['files'] = [
+            0 => [
+                'name' => 'file1.txt',
+                'type' => 'text/plain',
+                'size' => 100,
+                'tmp_name' => '/tmp/file1',
+                'error' => UPLOAD_ERR_OK,
+            ],
+            1 => [
+                'name' => '',
+                'type' => '',
+                'size' => 0,
+                'tmp_name' => '',
+                'error' => UPLOAD_ERR_NO_FILE, // This should be skipped
+            ],
+            2 => [
+                'name' => 'file3.txt',
+                'type' => 'text/plain',
+                'size' => 300,
+                'tmp_name' => '/tmp/file3',
+                'error' => UPLOAD_ERR_OK,
+            ],
+        ];
+
+        $method = new ReflectionMethod(FileUploadController::class, 'uploadMultiple');
+        $query = []; // Empty query
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertIsArray($args[0]);
+        $this->assertCount(2, $args[0]); // Only 2 files (skipped the NO_FILE one)
+
+        $files = array_values($args[0]); // Re-index array
+        $this->assertInstanceOf(FileUpload::class, $files[0]);
+        $this->assertSame('file1.txt', $files[0]->name);
+        $this->assertInstanceOf(FileUpload::class, $files[1]);
+        $this->assertSame('file3.txt', $files[1]->name);
+    }
+
+    public function testMixedTypeFileUpload(): void
+    {
+        // Test file upload with mixed type (no type hint) - covers fallback in resolveInputFileParameter
+        $_FILES['file'] = [
+            'name' => 'test.txt',
+            'type' => 'text/plain',
+            'size' => 100,
+            'tmp_name' => '/tmp/test',
+            'error' => UPLOAD_ERR_OK,
+        ];
+
+        $method = new ReflectionMethod(MixedFileController::class, 'uploadMixed');
+        $query = []; // Empty query
+
+        $args = $this->inputQuery->getArguments($method, $query);
+
+        $this->assertCount(1, $args);
+        $this->assertInstanceOf(FileUpload::class, $args[0]);
+        $this->assertSame('test.txt', $args[0]->name);
+    }
 }