Ecodev GraphQL Upload

https://github.com/ecodev/graphql-upload
Admin
Ecodev GraphQL Upload is a PSR-15 middleware library that implements the multipart request...
Tokens:15,019
Snippets:220
Trust Score:8.7
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/ecodev/graphql-upload/blob/master/README.md

Command to add the library to your project dependencies.

```sh
composer require ecodev/graphql-upload
```

--------------------------------

### Middleware Usage Example

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

Demonstrates integrating the middleware into a pipeline and manual invocation within a handler.

```php
use GraphQL\Upload\UploadMiddleware;
use Laminas\Diactoros\ServerRequest;
use Laminas\Diactoros\UploadedFile;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Http\Message\ResponseInterface;

$middleware = new UploadMiddleware();

// In a middleware pipeline (Mezzio example):
$app->post('/graphql', [
    BodyParamsMiddleware::class,    // Parses multipart form data
    UploadMiddleware::class,         // Transforms it for GraphQL
    GraphQLAction::class,            // Handles GraphQL execution
], 'graphql');

// Within a handler:
$response = $middleware->process($request, $nextHandler);
```

--------------------------------

### Define Multiple File Mappings

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Example structure for mapping multiple file keys to specific variable locations.

```php
$map = [
    '1' => ['variables.avatar'],
    '2' => ['variables.documents.0'],
    '3' => ['variables.documents.1'],
];
```

--------------------------------

### HTTP 413 Size Check Failure Example

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

An example of the HTTP response returned when a request exceeds the configured post_max_size.

```http
Client sends: Content-Length: 500000000 (476 MiB)
Server config: post_max_size = 256M
Result: HTTP 413, JSON error response

HTTP/1.1 413 Payload Too Large
Content-Type: application/json

{"message":"The server `post_max_size` is configured to accept 256.00 MiB, but received 476.84 MiB"}
```

--------------------------------

### Serialize GraphQL Response

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Example of the resolver return value and the resulting JSON serialization.

```php
// Resolver returns result
return ['id' => 'profile_123'];

// GraphQL serializes to JSON response
{
    "data": {
        "updateProfile": {
            "id": "profile_123"
        }
    }
}
```

--------------------------------

### Minimal multipart request structure

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Example of a compliant multipart/form-data request containing operations, map, and file data.

```http
POST /graphql HTTP/1.1
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="operations"

{"query":"mutation($file:Upload){upload(file:$file){id}}","variables":{"file":null}}
------Boundary
Content-Disposition: form-data; name="map"

{"1":["variables.file"]}
------Boundary
Content-Disposition: form-data; name="1"; filename="document.pdf"
Content-Type: application/pdf

[binary file data]
------Boundary--
```

--------------------------------

### Multipart Request Format

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-type.md

Example of the multipart/form-data request structure required by the graphql-multipart-request-spec.

```http
POST /graphql HTTP/1.1
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="operations"

{"query":"mutation($file:Upload){uploadFile(file:$file){success}}","variables":{"file":null}}
------Boundary
Content-Disposition: form-data; name="map"

{"1":["variables.file"]}
------Boundary
Content-Disposition: form-data; name="1"; filename="document.pdf"
Content-Type: application/pdf

[binary file content]
------Boundary--
```

--------------------------------

### Example Decoded Values Structure

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Represents the expected structure of the operations and map arrays after successful decoding.

```php
$operations = [
    'query' => 'mutation($avatar:Upload){updateProfile(avatar:$avatar){id}}',
    'variables' => ['avatar' => null],
    'operationName' => 'UpdateProfile',
];

$map = [
    '1' => ['variables.avatar'],
];
```

--------------------------------

### GraphQL Error Response Format

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-error.md

Example of the JSON structure returned in a GraphQL response when an UploadError is thrown.

```json
{
  "errors": [
    {
      "message": "File upload: The file exceeds the `upload_max_filesize` of 128.00 MiB",
      "locations": [
        {
          "line": 1,
          "column": 10
        }
      ],
      "path": ["uploadFile"]
    }
  ]
}
```

--------------------------------

### HTTP 413 Payload Too Large Response

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Example of the server response when the post_max_size limit is exceeded.

```http
POST /graphql HTTP/1.1
Content-Length: 300000000

HTTP/1.1 413 Payload Too Large

{
    "message": "The server `post_max_size` is configured to accept 256.00 MiB, but received 286.10 MiB"
}
```

--------------------------------

### HTTP 413 Payload Too Large Response

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/errors.md

Example of the JSON response body returned when a request exceeds the server's post_max_size configuration.

```json
{
    "message": "The server `post_max_size` is configured to accept X.XX MiB, but received Y.YY MiB"
}
```

--------------------------------

### HTTP 413 Payload Too Large Request and Response

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/errors.md

Example of an HTTP request exceeding size limits and the resulting 413 error response.

```http
POST /graphql HTTP/1.1
Content-Length: 1000000000

HTTP/1.1 413 Payload Too Large
Content-Type: application/json

{
    "message": "The server `post_max_size` is configured to accept 32.00 MiB, but received 953.67 MiB"
}
```

--------------------------------

### Constructor Definition

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

Initializes the middleware with default configuration.

```php
public function __construct()
```

--------------------------------

### Instantiate UploadMiddleware

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

The middleware requires no constructor arguments.

```php
use GraphQL\Upload\UploadMiddleware;

$middleware = new UploadMiddleware();
```

--------------------------------

### Configure Middleware in Slim

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Add the middleware to the Slim application instance.

```php
use Slim\Slim;
use GraphQL\Upload\UploadMiddleware;

$app = new Slim();
$app->add(new UploadMiddleware());
$app->post('/graphql', GraphQLAction::class);
```

--------------------------------

### Search documentation via command line

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/MANIFEST.md

Use these grep and cat commands to locate specific methods, error codes, or configuration settings within the documentation files.

```bash
# View the main index
cat index.md

# Search for a method
grep -r "parseValue" .

# Search for error messages
grep -r "UPLOAD_ERR" errors.md

# Find configuration options
grep -r "post_max_size" .
```

--------------------------------

### Project Directory Structure

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/index.md

The file structure of the graphql-upload package, highlighting core source files and test suites.

```text
graphql-upload/
├── src/
│   ├── UploadMiddleware.php      # PSR-15 middleware
│   ├── UploadType.php             # GraphQL scalar type
│   ├── UploadError.php            # Upload error exception
│   └── Utility.php                # Internal utilities
├── tests/
│   ├── UploadMiddlewareTest.php
│   └── UploadTypeTest.php
├── composer.json                  # Package metadata
└── README.md                       # Quick start
```

--------------------------------

### Visualize the Processing Pipeline

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/README.md

The request lifecycle from raw HTTP input to GraphQL execution.

```text
HTTP Request → BodyParamsMiddleware → UploadMiddleware → GraphQL Handler
     (raw)           (parsed)           (injected files)      (executed)
```

--------------------------------

### Configure PSR-15 Middleware Pipeline

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Shows the required order for piping middleware in a Mezzio application to ensure multipart parsing and upload processing occur before GraphQL execution.

```php
// config/pipeline.php in Mezzio

use Mezzio\\Helper\\BodyParams\\BodyParamsMiddleware;
use GraphQL\\Upload\\UploadMiddleware;
use GraphQLServer\\GraphQLAction;
use Monolog\\Middleware\\LoggingMiddleware;

$app->pipe(LoggingMiddleware::class);           // 1. Logging
$app->pipe(BodyParamsMiddleware::class);        // 2. Parse multipart/form-data
$app->pipe(UploadMiddleware::class);            // 3. Process GraphQL uploads
$app->pipe(GraphQLAction::class);               // 4. Execute GraphQL
```

--------------------------------

### Utility Methods

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/index.md

Helper methods for retrieving server configuration limits related to file uploads.

```APIDOC
## Utility Methods

### getPostMaxSize()
Returns the server's `post_max_size` configuration in bytes.

### getUploadMaxFilesize()
Returns the server's `upload_max_filesize` configuration in bytes.

### toMebibyte(string|int $value)
Converts a size value to a formatted mebibyte string.
```

--------------------------------

### Access and Process Uploaded Files

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

Demonstrates retrieving file metadata, moving files to storage, and reading stream contents from an UploadedFileInterface instance.

```php
use Psr\\\Http\\\Message\\\UploadedFileInterface;

$file = $args['file'];  // UploadedFileInterface

// Read file info
$filename = $file->getClientFilename();      // "document.pdf"
$mimeType = $file->getClientMediaType();     // "application/pdf"
$size = $file->getSize();                    // 1024000
$error = $file->getError();                  // UPLOAD_ERR_OK (0)

// Move to permanent storage
$uploadDir = '/var/uploads';
$targetPath = $uploadDir . '/' . $filename;
$file->moveTo($targetPath);

// Or read the stream
$stream = $file->getStream();
$contents = $stream->getContents();
```

--------------------------------

### Configure Middleware in Laminas Mezzio

Source: https://github.com/ecodev/graphql-upload/blob/master/README.md

Register the UploadMiddleware in your route configuration to process multipart requests before the GraphQL action.

```php
use Application\Action\GraphQLAction;
use Mezzio\Helper\BodyParams\BodyParamsMiddleware;
use GraphQL\Upload\UploadMiddleware;

$app->post('/graphql', [
    BodyParamsMiddleware::class, 
    UploadMiddleware::class, // This is the magic
    GraphQLAction::class,
], 'graphql');
```

--------------------------------

### Handle Files in Resolver

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/README.md

Access the uploaded file from arguments and move it to a destination directory.

```php
$file = $args['file'];
$file->moveTo('/uploads/' . $file->getClientFilename());
```

--------------------------------

### Configure Middleware in Mezzio

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Register the middleware in the route pipeline to handle multipart form-data before the GraphQL action.

```php
// config/routes.php
use Application\Action\GraphQLAction;
use Mezzio\Helper\BodyParams\BodyParamsMiddleware;
use GraphQL\Upload\UploadMiddleware;

$app->post('/graphql', [
    BodyParamsMiddleware::class,      // Parses multipart form-data
    UploadMiddleware::class,           // Handles file uploads
    GraphQLAction::class,              // Executes GraphQL
], 'graphql');
```

--------------------------------

### Configure PHP upload directory

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Sets the temporary directory for file uploads in php.ini. Ensure the directory has appropriate write permissions.

```ini
# php.ini
; Default behavior - files go to sys_get_temp_dir()
upload_tmp_dir = /var/tmp/php-uploads

; If using custom temp dir, ensure write permissions:
; chmod 1777 /var/tmp/php-uploads
```

--------------------------------

### Configure GraphQL Upload Middleware and Schema

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/index.md

Integrate the middleware into your PSR-15 pipeline and define the Upload scalar type within your GraphQL schema.

```php
// 1. Add middleware to pipeline (Mezzio example)
$app->post('/graphql', [
    BodyParamsMiddleware::class,
    UploadMiddleware::class,
    GraphQLActionClass,
], 'graphql');

// 2. Define Upload type in GraphQL schema
$schema = new Schema([
    'mutation' => new ObjectType([
        'name' => 'Mutation',
        'fields' => [
            'uploadFile' => [
                'type' => Type::string(),
                'args' => [
                    'file' => new UploadType(),
                ],
                'resolve' => function ($root, array $args) {
                    $file = $args['file'];  // PSR-7 UploadedFileInterface
                    $file->moveTo('/uploads/' . $file->getClientFilename());
                    return 'Success';
                },
            ],
        ],
    ]),
]);

// 3. Clients send multipart requests with operations and map fields
```

--------------------------------

### Integrate Middleware in Mezzio

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/README.md

Register the required middleware stack in a Mezzio application route.

```php
$app->post('/graphql', [
    BodyParamsMiddleware::class,
    UploadMiddleware::class,
    GraphQLAction::class,
], 'graphql');
```

--------------------------------

### Handle Missing Body Parser Error

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Occurs when the BodyParamsMiddleware is absent from the pipeline, resulting in a null parsed body.

```text
UploadMiddleware receives request with:
$request->getParsedBody() = null

Throws: InvariantViolation(
    'PSR-7 request is expected to provide parsed body for "multipart/form-data" requests but got null'
)
```

--------------------------------

### Execute Resolver for Uploaded Files

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Accessing the validated file within the resolver and moving it to a permanent location.

```php
// The resolver function receives the validated file
'resolve' => function ($root, array $args) {
    $file = $args['avatar'];  // UploadedFileInterface, validated and error-free
    
    // Do something with the file
    $filename = $file->getClientFilename();
    $mimeType = $file->getClientMediaType();
    $size = $file->getSize();
    
    // Persist to disk
    $file->moveTo('/uploads/' . $filename);
    
    return ['id' => 'profile_123'];
}
```

--------------------------------

### Process Method Signature

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

The primary entry point for processing HTTP requests and transforming them for GraphQL execution.

```php
public function process(
    ServerRequestInterface $request,
    RequestHandlerInterface $handler
): ResponseInterface
```

--------------------------------

### process(ServerRequestInterface $request, RequestHandlerInterface $handler)

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

Processes an incoming HTTP request, detects multipart/form-data uploads, transforms the request body to include uploaded files, and passes it to the next handler.

```APIDOC
## process(ServerRequestInterface $request, RequestHandlerInterface $handler)

### Description
Processes the HTTP request, detects multipart/form-data uploads, and transforms the request before passing to the next handler. If the content type is not multipart/form-data, the request is passed through unchanged.

### Parameters
- **$request** (Psr\Http\Message\ServerRequestInterface) - Required - The HTTP request to process
- **$handler** (Psr\Http\Server\RequestHandlerInterface) - Required - The next request handler in the middleware chain

### Returns
- **ResponseInterface** - The response from the handler, or an error response if validation fails.

### Throws
- **GraphQL\Error\InvariantViolation** - Multipart request body is null or empty array
- **GraphQL\Server\RequestError** - Invalid JSON in operations or map field, missing required fields, or file declared in map but not provided
```

--------------------------------

### Retrieve post_max_size configuration

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-utility.md

Returns the server's post_max_size configuration value in bytes.

```php
public static function getPostMaxSize(): int
```

```php
use GraphQL\Upload\Utility;

$maxSize = Utility::getPostMaxSize();
// Returns: 33554432 (typically 32 MiB)

$message = "Maximum upload size is " . Utility::toMebibyte($maxSize);
// Output: "Maximum upload size is 32.00 MiB"
```

--------------------------------

### Retrieve upload_max_filesize configuration

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-utility.md

Returns the server's upload_max_filesize configuration value in bytes.

```php
public static function getUploadMaxFilesize(): int
```

```php
use GraphQL\Upload\Utility;

$maxFileSize = Utility::getUploadMaxFilesize();
// Returns: 268435456 (typically 256 MiB)
```

--------------------------------

### Configure upload_max_filesize in php.ini

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Set the maximum size for a single uploaded file, ensuring it is less than or equal to post_max_size.

```ini
# php.ini
upload_max_filesize = 256M
post_max_size = 512M  # Should be larger than upload_max_filesize
```

--------------------------------

### Middleware Pipeline Order

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

The required sequence of middleware components for processing multipart GraphQL requests.

```text
1. BodyParamsMiddleware           // Parses multipart/form-data
   ↓
2. UploadMiddleware               // Processes uploaded files
   ↓
3. GraphQL Handler                // Executes GraphQL
```

--------------------------------

### Configure memory_limit in php.ini

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Set the memory limit for PHP, which may need to be increased for large file uploads.

```ini
# php.ini
memory_limit = 512M
```

--------------------------------

### Handle File Size Limit Exceeded Error

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Occurs when an individual file exceeds the PHP upload_max_filesize configuration.

```text
$file = UploadedFileInterface with error = UPLOAD_ERR_INI_SIZE

Throws: UploadError(UPLOAD_ERR_INI_SIZE)
// Message: "File upload: The file exceeds the `upload_max_filesize` of 256.00 MiB"
```

--------------------------------

### Increase File Size Limits

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/README.md

Configure PHP ini settings to allow larger file uploads.

```ini
; php.ini
upload_max_filesize = 256M
post_max_size = 512M
```

--------------------------------

### View Exception Hierarchy

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/index.md

The inheritance structure for exceptions thrown by the library.

```text
Exception
├── GraphQL\Error\Error
│   ├── GraphQL\Error\InvariantViolation
│   ├── GraphQL\Server\RequestError
│   └── GraphQL\Upload\UploadError
└── UnexpectedValueException
```

--------------------------------

### Request Transformation Comparison

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Visual representation of the request state before and after the content-type transformation.

```php
// Before
$request->getHeader('content-type') = ['multipart/form-data; boundary=...']
$request->getParsedBody() = ['operations' => '...', 'map' => '...']

// After
$request->getHeader('content-type') = ['application/json']
$request->getParsedBody() = [
    'query' => 'mutation($avatar:Upload)...',
    'variables' => ['avatar' => UploadedFileInterface],
    'operationName' => 'UpdateProfile',
]
```

--------------------------------

### RequestError Scenario for Missing File

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/errors.md

Demonstrates a server error response when a file referenced in the map is missing from the multipart request.

```php
// Client sends this multipart request:
POST /graphql HTTP/1.1
Content-Type: multipart/form-data; boundary=----Boundary

------Boundary
Content-Disposition: form-data; name="operations"

{"query":"mutation($file:Upload){...}","variables":{"file":null}}
------Boundary
Content-Disposition: form-data; name="map"

{"1":["variables.file"]}
// File field "1" is NOT included!
------Boundary--

// Server responds:
{
    "errors": [{
        "message": "GraphQL query declared an upload in `variables.file`, but no corresponding file were actually uploaded"
    }]
}
```

--------------------------------

### Instantiate UploadType

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

The UploadType class requires no constructor arguments.

```php
use GraphQL\Upload\UploadType;

$uploadType = new UploadType();
```

--------------------------------

### Configure max_file_uploads in php.ini

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Set the maximum number of files allowed in a single request.

```ini
# php.ini
max_file_uploads = 50
```

--------------------------------

### Persist uploaded files in resolver

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Ensure the file is moved from the temporary location to a permanent directory within the resolver.

```php
'resolve' => function ($root, array $args) {
    $file = $args['file'];
    $file->moveTo('/uploads/' . $file->getClientFilename());  // Persist
    return ['id' => 'uploaded'];
}
```

--------------------------------

### Private Method Signatures

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

Internal helper methods for parsing files, validating bodies, decoding JSON fields, and checking upload size limits.

```php
private function parseUploadedFiles(ServerRequestInterface $request): ServerRequestInterface
```

```php
private function validateParsedBody(ServerRequestInterface $request): void
```

```php
private function decodeArray(array $bodyParams, string $key): array
```

```php
private function postMaxSizeError(ServerRequestInterface $request): ?ResponseInterface
```

--------------------------------

### Configure post_max_size in php.ini

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Set the maximum size of an entire POST request body.

```ini
# php.ini
post_max_size = 256M
```

--------------------------------

### Parse and Validate GraphQL Request

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Initial parsing of the query and variables containing uploaded files.

```php
// GraphQL parses the query and variables from the request
$query = 'mutation($avatar:Upload){updateProfile(avatar:$avatar){id}}';
$variables = ['avatar' => UploadedFileInterface];
```

--------------------------------

### UploadMiddleware::process

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/index.md

Processes a PSR-7 request to handle multipart file uploads, ensuring the request is correctly parsed before reaching the GraphQL action.

```APIDOC
## process(ServerRequestInterface $request, RequestHandlerInterface $handler)

### Description
Processes the incoming PSR-7 request to handle multipart file uploads. This middleware should be placed in the pipeline before the GraphQL action.

### Signature
`(ServerRequestInterface, RequestHandlerInterface): ResponseInterface`

### Parameters
- **$request** (ServerRequestInterface) - Required - The incoming PSR-7 request.
- **$handler** (RequestHandlerInterface) - Required - The request handler to delegate to after processing.
```

--------------------------------

### Define MiddlewareInterface

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

The standard PSR-15 interface for middleware components.

```php
interface Psr\\\Http\\\Server\\\MiddlewareInterface
```

--------------------------------

### Handle Missing Uploaded File Error

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Occurs when the map references a file key that is not present in the uploaded files collection.

```text
$map = ['1' => ['variables.avatar']]
$uploadedFiles = []  // File "1" missing

Throws: RequestError(
    'GraphQL query declared an upload in `variables.avatar`, but no corresponding file were actually uploaded'
)
```

--------------------------------

### Handle file upload errors in GraphQL resolvers

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/errors.md

Demonstrates how to process uploaded files in a resolver. Note that validation errors are handled automatically by UploadType before the resolver executes.

```php
use GraphQL\Upload\UploadType;
use GraphQL\Upload\UploadError;
use Psr\Http\Message\UploadedFileInterface;

$mutation = [
    'uploadFile' => [
        'type' => Type::string(),
        'args' => [
            'file' => new UploadType(),
        ],
        'resolve' => function ($root, array $args): string {
            // If file has an error, UploadType::parseValue() throws UploadError
            // before this resolve() function is called. No try/catch needed here.
            
            /** @var UploadedFileInterface $file */
            $file = $args['file'];  // Already validated and error-free
            
            try {
                $file->moveTo('/uploads/' . $file->getClientFilename());
                return 'Success';
            } catch (Exception $e) {
                // Handle file system errors
                return 'Failed: ' . $e->getMessage();
            }
        },
    ],
];
```

--------------------------------

### Handle Request Size Limit Exceeded Error

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Occurs when the total request size exceeds the PHP post_max_size configuration, resulting in a 413 response.

```text
Content-Length: 500000000
post_max_size: 256M

Returns: JsonResponse(
    ['message' => "The server `post_max_size` is configured to accept 256.00 MiB, but received 476.84 MiB"],
    413
)
```

--------------------------------

### Catch errors in UploadMiddleware integration

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/errors.md

Shows how to catch multipart parsing errors and PSR-7 contract violations when using UploadMiddleware.

```php
use GraphQL\Upload\UploadMiddleware;
use GraphQL\Server\RequestError;

$middleware = new UploadMiddleware();

try {
    $response = $middleware->process($request, $handler);
} catch (RequestError $e) {
    // Handle multipart parsing errors
    echo $e->getMessage();
} catch (InvariantViolation $e) {
    // Handle PSR-7 contract violations
    echo $e->getMessage();
}
```

--------------------------------

### Define Error exception class

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

Base exception class for GraphQL errors, providing AST node context and source location.

```php
class GraphQL\Error\Error extends Exception
```

--------------------------------

### Override post_max_size via .htaccess

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Configure the post_max_size directive using an Apache .htaccess file.

```apache
php_value post_max_size 256M
```

--------------------------------

### Format bytes to mebibytes

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-utility.md

Converts a byte value to a formatted mebibyte string with two decimal places and a single-quote thousands separator.

```php
public static function toMebibyte(string|int $value): string
```

```php
use GraphQL\Upload\Utility;

echo Utility::toMebibyte(33554432);      // "32.00 MiB"
echo Utility::toMebibyte(1073741824);    // "1'024.00 MiB"
echo Utility::toMebibyte(268435456);     // "256.00 MiB"
echo Utility::toMebibyte("512");         // "0.00 MiB"

// With thousands separator (locale-dependent)
echo Utility::toMebibyte(5368709120);    // "5'120.00 MiB"
```

--------------------------------

### Optimize PHP memory for concurrent uploads

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

Adjusts memory limits and FPM worker settings in php.ini to handle large concurrent file uploads.

```ini
# php.ini
memory_limit = 512M         # Per-request memory
max_children = 20           # FPM workers (if using FPM)
request_terminate_timeout = 300  # Timeout for large uploads
```

--------------------------------

### Multipart Request Structure

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

The middleware expects a multipart/form-data request containing specific fields to map files to GraphQL variables.

```APIDOC
## Multipart Request Structure

### Description
The middleware processes multipart/form-data requests to extract files and inject them into GraphQL variables.

### Request Fields
- **operations** (string) - Required - JSON string containing `{ query: "...", variables: {...}, operationName: "..." }`
- **map** (string) - Required - JSON string containing `{ "fileKey1": ["variables.path.to.file"], "fileKey2": [...] }`
- **[fileKey]** (file) - Required - File fields named according to keys defined in the map.
```

--------------------------------

### Content-Type Detection in UploadMiddleware

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Logic to verify if the request content type is multipart/form-data before proceeding with upload processing.

```php
public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
{
    $contentType = $request->getHeader('content-type')[0] ?? '';
    
    if (mb_stripos($contentType, 'multipart/form-data') !== false) {
        // Proceed with upload processing
    } else {
        // Pass through unchanged
        return $handler->handle($request);
    }
}
```

--------------------------------

### Pass Request to Next Handler

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Forwards the fully transformed request to the next middleware in the pipeline.

```php
return $handler->handle($request);
```

--------------------------------

### Constructing UploadError

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-error.md

Instantiate UploadError with specific PHP upload error constants to generate descriptive error messages.

```php
use GraphQL\Upload\UploadError;

// When a file exceeds upload_max_filesize
$error = new UploadError(UPLOAD_ERR_INI_SIZE);
// Message: "File upload: The file exceeds the `upload_max_filesize` of X.XX MiB"

// When no file was uploaded
$error = new UploadError(UPLOAD_ERR_NO_FILE);
// Message: "File upload: No file was uploaded"
```

--------------------------------

### Request State After BodyParamsMiddleware

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

The structure of parsed body and uploaded files after the BodyParamsMiddleware has processed the request.

```php
$request->getParsedBody() = [
    'operations' => '{"query":"mutation($avatar:Upload)...","variables":{"avatar":null}}',
    'map' => '{"1":["variables.avatar"]}',
];

$request->getUploadedFiles() = [
    '1' => UploadedFileInterface(filename: 'profile.jpg', error: UPLOAD_ERR_OK),
];
```

--------------------------------

### HTTP Success Response

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Standard HTTP response structure for a successful GraphQL mutation.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "data": {
        "updateProfile": {
            "id": "profile_123"
        }
    }
}
```

--------------------------------

### Generate upload error messages

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-utility.md

Demonstrates using utility methods to compare request content length against server limits and generate user-friendly error responses.

```php
use GraphQL\Upload\Utility;
use Laminas\Diactoros\Response\JsonResponse;

$contentLength = $request->getServerParams()['CONTENT_LENGTH'] ?? 0;
$postMaxSize = Utility::getPostMaxSize();

if ($contentLength > $postMaxSize) {
    $contentLengthFormatted = Utility::toMebibyte($contentLength);
    $postMaxSizeFormatted = Utility::toMebibyte($postMaxSize);
    
    return new JsonResponse(
        ['message' => "The server `post_max_size` is configured to accept $postMaxSizeFormatted, but received $contentLengthFormatted"],
        413,
    );
}
```

--------------------------------

### Define UnexpectedValueException class

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

Standard PHP exception used for handling unexpected values.

```php
class UnexpectedValueException extends Exception
```

--------------------------------

### Define ResponseInterface

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

The standard PSR-7 interface representing an HTTP response.

```php
interface Psr\\\Http\\\Message\\\ResponseInterface
```

--------------------------------

### UploadType::__construct

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-type.md

Initializes a new instance of the Upload scalar type for use in GraphQL schema definitions.

```APIDOC
## public function __construct()

### Description
Creates a new Upload scalar type for use in GraphQL schema definitions. No parameters required.

### Properties
- **name** (string) - Default: 'Upload' - The GraphQL type name exposed in the schema
- **description** (string) - Description shown in introspection, explaining it implements graphql-multipart-request-spec
```

--------------------------------

### Handle Missing Operations Field Error

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Occurs when the client fails to include the required operations field in the multipart form data.

```text
$request->getParsedBody() = ['map' => '...']

Throws: RequestError('The request must define a `operations`')
```

--------------------------------

### Serialize UploadType

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-type.md

Demonstrates that the serialize method is not supported and will throw an InvariantViolation.

```php
$type = new UploadType();
$type->serialize($someFile);  // Throws InvariantViolation
```

--------------------------------

### Define Upload Mutation in Schema

Source: https://github.com/ecodev/graphql-upload/blob/master/README.md

Use the UploadType in your mutation arguments to handle incoming files as UploadedFileInterface instances.

```php
<?php

use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Schema;
use GraphQL\Upload\UploadType;
use Psr\Http\Message\UploadedFileInterface;

// Build your Schema
$schema = new Schema([
    'query' => new ObjectType([
        'name' => 'Query',
        'fields' => [],
    ]),
    'mutation' => new ObjectType([
        'name' => 'Mutation',
        'fields' => [
            'testUpload' => [
                'type' => Type::string(),
                'args' => [
                    'text' => Type::string(),
                    'file' => new UploadType(),
                ],
                'resolve' => function ($root, array $args): string {
                    /** @var UploadedFileInterface $file */
                    $file = $args['file'];

                    // Do something with the file
                    $file->moveTo('some/folder/in/my/project');

                    return 'Uploaded file was ' . $file->getClientFilename() . ' (' . $file->getClientMediaType() . ') with description: ' . $args['text'];
                },
            ],
        ],
    ]),
]);
```

--------------------------------

### Catch Upload Errors

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/README.md

Wrap value parsing in a try-catch block to handle specific UploadError exceptions.

```php
try {
    $type->parseValue($file);
} catch (UploadError $e) {
    // Handle error
}
```

--------------------------------

### UnexpectedValueException Scenario for Invalid File Type

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/errors.md

Demonstrates the error response when a non-UploadedFileInterface value is provided for an Upload-type field.

```php
// If middleware is misconfigured and files are not injected:
$variables = ['file' => 'string-instead-of-file'];

// Results in:
{
    "errors": [{
        "message": "Could not get uploaded file, be sure to conform to GraphQL multipart request specification. Instead got: \"string-instead-of-file\""
    }]
}
```

--------------------------------

### Define RequestHandlerInterface

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

The standard PSR-15 interface for request handlers.

```php
interface Psr\\\Http\\\Server\\\RequestHandlerInterface
```

--------------------------------

### Define UploadedFileInterface

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

The standard PSR-7 interface representing an uploaded file.

```php
interface Psr\\\Http\\\Message\\\UploadedFileInterface
```

--------------------------------

### Define ServerRequestInterface

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

The standard PSR-7 interface representing an incoming HTTP request.

```php
interface Psr\\\Http\\\Message\\\ServerRequestInterface
```

--------------------------------

### Inject Uploaded Files into Request

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Parses the request body for file maps and operations, then injects the corresponding uploaded files into the nested variable structure.

```php
private function parseUploadedFiles(ServerRequestInterface $request): ServerRequestInterface
{
    $bodyParams = $request->getParsedBody();
    $map = $this->decodeArray($bodyParams, 'map');
    $result = $this->decodeArray($bodyParams, 'operations');
    $uploadedFiles = $request->getUploadedFiles();
    
    // For each file key in the map
    foreach ($map as $fileKey => $locations) {
        // For each variable location where this file should be injected
        foreach ($locations as $location) {
            // Navigate the variables path using dot notation
            $items = &$result;
            foreach (explode('.', $location) as $key) {
                if (!isset($items[$key]) || !is_array($items[$key])) {
                    $items[$key] = [];
                }
                $items = &$items[$key];
            }
            
            // Verify file exists
            if (!array_key_exists($fileKey, $uploadedFiles)) {
                throw new RequestError(
                    "GraphQL query declared an upload in `$location`, but no corresponding file were actually uploaded",
                );
            }
            
            // Inject the file
            $items = $uploadedFiles[$fileKey];
        }
    }
    
    // Return modified request with updated content-type and body
    return $request
        ->withHeader('content-type', 'application/json')
        ->withParsedBody($result);
}
```

--------------------------------

### ParseLiteral UploadType

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-type.md

Illustrates that hardcoding an upload value in a GraphQL query results in an error.

```php
$type = new UploadType();
// In GraphQL query: mutation { upload(file: "path/to/file") }
// Results in error: `Upload` cannot be hardcoded in query
```

--------------------------------

### Define RequestError exception class

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

Exception used for errors occurring during GraphQL request processing.

```php
class GraphQL\Server\RequestError extends Error
```

--------------------------------

### Error Response (413)

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

The format of the error response when the request exceeds the configured server limits.

```APIDOC
## HTTP 413 Error Response

### Description
Returned when the uploaded file size exceeds the server's `post_max_size` configuration.

### Response
- **message** (string) - Description of the configured limit versus the received size.

### Response Example
```json
{
  "message": "The server `post_max_size` is configured to accept X.XX MiB, but received Y.YY MiB"
}
```
```

--------------------------------

### HTTP 413 Error Response Format

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-middleware.md

The JSON structure returned when an upload exceeds the configured post_max_size limit.

```json
{
  "message": "The server `post_max_size` is configured to accept X.XX MiB, but received Y.YY MiB"
}
```

--------------------------------

### Define InvariantViolation exception class

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

Exception used for internal API contract violations.

```php
class GraphQL\Error\InvariantViolation extends Error
```

--------------------------------

### Handling UploadError in UploadType

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-error.md

Demonstrates how UploadType throws an UploadError when parsing a file with an error status.

```php
use GraphQL\Upload\UploadType;
use Laminas\Diactoros\UploadedFile;

$type = new UploadType();

// Create a file with an error
$file = new UploadedFile('/tmp/partial.tmp', 0, UPLOAD_ERR_PARTIAL);

try {
    $type->parseValue($file);
} catch (UploadError $e) {
    echo $e->getMessage();
    // Output: "File upload: The file was only partially uploaded"
}
```

--------------------------------

### Define ScalarType base class

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

Base class for defining custom GraphQL scalar types.

```php
class GraphQL\Type\Definition\ScalarType
```

--------------------------------

### Post Size Validation Logic

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Validates the request content length against the server's post_max_size configuration to prevent payload overflow.

```php
private function postMaxSizeError(ServerRequestInterface $request): ?ResponseInterface
{
    $contentLength = $request->getServerParams()['CONTENT_LENGTH'] ?? 0;
    $postMaxSize = Utility::getPostMaxSize();  // Read php.ini post_max_size
    
    if ($contentLength && $contentLength > $postMaxSize) {
        // Return HTTP 413 error
        return new JsonResponse(
            ['message' => "The server `post_max_size` is configured to accept $postMaxSize, but received $contentLength"],
            413,
        );
    }
    return null;
}
```

--------------------------------

### Transform Request Content-Type

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Updates the request headers and body to reflect the transition from multipart/form-data to standard JSON.

```php
return $request
    ->withHeader('content-type', 'application/json')
    ->withParsedBody($result);
```

--------------------------------

### Integrating UploadType in Schema

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-error.md

Shows the usage of UploadType within a GraphQL mutation field definition.

```php
$schema = new Schema([
    'mutation' => new ObjectType([
        'name' => 'Mutation',
        'fields' => [
            'uploadFile' => [
                'type' => Type::string(),
                'args' => [
                    'file' => new UploadType(),
                ],
                'resolve' => function ($root, array $args): string {
                    // If $args['file'] has an error, UploadType::parseValue()
                    // throws UploadError before this resolve function is called
                    $file = $args['file'];
                    return "File: " . $file->getClientFilename();
                },
            ],
        ],
    ]),
]);
```

--------------------------------

### Implement UploadType Coercion

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Custom scalar type implementation to validate UploadedFileInterface and check for upload errors.

```php
// For the $avatar variable of type Upload
class UploadType extends ScalarType
{
    public function parseValue(mixed $value): UploadedFileInterface
    {
        // Validate it's an UploadedFileInterface
        if (!$value instanceof UploadedFileInterface) {
            throw new UnexpectedValueException(...);
        }
        
        // Check for upload errors
        $error = $value->getError();
        if ($error !== UPLOAD_ERR_OK) {
            throw new UploadError($error);  // Maps error code to message
        }
        
        return $value;  // Validated and error-free
    }
}
```

--------------------------------

### UploadError Message Format

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/configuration.md

The error message format when a file exceeds the upload_max_filesize limit.

```text
File upload: The file exceeds the `upload_max_filesize` of X.XX MiB
```

--------------------------------

### Avoid Hardcoded Upload Values in GraphQL

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/errors.md

Use GraphQL variables instead of hardcoded literals to prevent Upload type errors.

```graphql
# WRONG - Hardcoded value
mutation {
    uploadFile(file: "path/to/file") {
        success
    }
}

# CORRECT - Variable
mutation UploadFile($file: Upload) {
    uploadFile(file: $file) {
        success
    }
}
```

--------------------------------

### PHP File Upload Error Constants

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/types.md

These constants represent the standard PHP file upload error codes used to validate and report upload status.

```php
const UPLOAD_ERR_OK              = 0;  // No error
const UPLOAD_ERR_INI_SIZE        = 1;  // File exceeds upload_max_filesize
const UPLOAD_ERR_FORM_SIZE       = 2;  // File exceeds MAX_FILE_SIZE
const UPLOAD_ERR_PARTIAL         = 3;  // Partial upload
const UPLOAD_ERR_NO_FILE         = 4;  // No file uploaded
const UPLOAD_ERR_NO_TMP_DIR      = 6;  // Missing temp folder
const UPLOAD_ERR_CANT_WRITE      = 7;  // Disk write error
const UPLOAD_ERR_EXTENSION       = 8;  // Extension stopped upload
```

--------------------------------

### Handle Invalid JSON in Map Field Error

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Occurs when the map field contains malformed JSON data.

```text
$request->getParsedBody() = [
    'operations' => '...',
    'map' => 'not valid json',
]

Throws: RequestError('The `map` key must be a JSON encoded array')
```

--------------------------------

### Define Upload Field in Schema

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/README.md

Use the UploadType to define a file upload field within a GraphQL schema.

```php
'avatar' => new UploadType(),
```

--------------------------------

### HTTP Error Response

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Structure of an error response returned when an UploadError occurs.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "errors": [{
        "message": "File upload: The file exceeds the `upload_max_filesize` of 256.00 MiB",
        "path": ["updateProfile"],
        "locations": [{"line": 1, "column": 10}]
    }]
}
```

--------------------------------

### Validate Parsed Body in PHP

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Ensures the PSR-7 request body is non-null, an array, and not empty before proceeding with file processing.

```php
private function validateParsedBody(ServerRequestInterface $request): void
{
    $bodyParams = $request->getParsedBody();
    
    // Check 1: Not null
    if (null === $bodyParams) {
        throw new InvariantViolation(
            'PSR-7 request is expected to provide parsed body for "multipart/form-data" requests but got null',
        );
    }
    
    // Check 2: Is array
    if (!is_array($bodyParams)) {
        throw new RequestError(
            'GraphQL Server expects JSON object or array, but got ' . Utils::printSafeJson($bodyParams),
        );
    }
    
    // Check 3: Not empty
    if (empty($bodyParams)) {
        throw new InvariantViolation(
            'PSR-7 request is expected to provide parsed body for "multipart/form-data" requests but got empty array',
        );
    }
}
```

--------------------------------

### Decode Operations and Map Fields in PHP

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/request-processing-flow.md

Decodes JSON-encoded fields from the request body and validates their structure. Throws a RequestError if the required keys are missing or contain invalid JSON.

```php
private function decodeArray(array $bodyParams, string $key): array
{
    if (!isset($bodyParams[$key])) {
        throw new RequestError("The request must define a `$key`");
    }
    
    $value = json_decode($bodyParams[$key], true);
    if (!is_array($value)) {
        throw new RequestError("The `$key` key must be a JSON encoded array");
    }
    
    return $value;
}

// Called twice:
$map = $this->decodeArray($bodyParams, 'map');              // {"1": ["variables.avatar"]}
$operations = $this->decodeArray($bodyParams, 'operations'); // Full GraphQL operation
```

--------------------------------

### UploadType::parseValue

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-type.md

Parses and validates an externally provided file upload from a GraphQL variable.

```APIDOC
## public function parseValue(mixed $value)

### Description
Parses an externally provided value (a GraphQL variable) into an internal value. Validates that the value is a `UploadedFileInterface` instance with no upload errors.

### Parameters
- **$value** (mixed) - Required - The value provided as a GraphQL query variable (should be an UploadedFileInterface)

### Return Type
- **Psr\Http\Message\UploadedFileInterface** - The validated uploaded file instance.

### Throws
- **UnexpectedValueException** - Value is not an `UploadedFileInterface` instance
- **GraphQL\Upload\UploadError** - File was uploaded but an error occurred (error code is not `UPLOAD_ERR_OK`)
```

--------------------------------

### ParseValue UploadType

Source: https://github.com/ecodev/graphql-upload/blob/master/_autodocs/api-reference-upload-type.md

Shows successful validation of an UploadedFileInterface and handling of common error cases.

```php
use GraphQL\Upload\UploadType;
use Laminas\Diactoros\UploadedFile;

$type = new UploadType();

// Success case
$file = new UploadedFile('/tmp/upload123.tmp', 12345, UPLOAD_ERR_OK);
$validated = $type->parseValue($file);  // Returns $file

// Error cases
$type->parseValue("not a file");  // Throws UnexpectedValueException

$errorFile = new UploadedFile('/tmp/upload456.tmp', 0, UPLOAD_ERR_NO_FILE);
$type->parseValue($errorFile);  // Throws UploadError('No file was uploaded')
```
Tokens:
Raw