Upload Class

categoryAPI edit_calendar31 Mar 2026

File Ingestion & Upload Class

The Upload class is the primary interface for handling secure file ingestion into GeniXCMS. It provides an abstraction layer over PHP's native move_uploaded_file system, adding critical features like strict extension filtering, automatic filename sanitization, and unique storage path generation.

⚡ Content Ingestion Method

`Upload::go(string $name, ...)`

Processes a single file upload from an HTML form.

Parameter	Type	Default	Description
`$name`	`string`	Required	The `name` attribute of the `<input type="file">` field.
`$path`	`string`	Required	Destination folder relative to `GX_PATH` (e.g., `assets/uploads/`).
`$allowed`	`array`	`[]`	List of permitted extensions (e.g., `['jpg', 'png']`).
`$unique`	`bool`	`false`	If `true`, creates a cryptographically unique filename.

Returns: array (Result/Metadata) or string (Error message if failed).

// Example: Processing a site logo upload
$valid_ext = ['jpg', 'png', 'svg', 'webp'];
$result = Upload::go('site_logo', 'assets/images/', $valid_ext, true);

if (isset($result['error'])) {
    System::alert(['alertDanger' => [$result['error']]]);
} else {
    $logo_url = $result['fileurl'];
}

📦 Result Metadata Schema

Upon a successful upload, the engine returns a detailed metadata object for immediate use or database persistence:

filename: The final, sanitized name of the file (including any unique prefixes).
filesize: The exact volume in bytes.
path: The relative storage path (e.g., assets/images/logo.png).
filepath: The absolute server filesystem path.
fileurl: The derived public-facing URL resolved via the Url Class.

🛡️ Integrated Security Features

Protection is baked into every phase of the upload lifecycle:

Strict Whitelisting: The system ignores MIME types provided by the client and relies exclusively on your provided $allowed extensions list.
Naming Sanitization: Filenames are processed through Typo::slugify() and Typo::cleanX() to remove spaces, special characters, and potential script injection points.
Unique Collisions: Enabling $unique prevents overwriting existing files and makes user-uploaded assets unguessable for external scanners.
Directory Integrity: The system automatically attempts to create the target $path if it does not already exist.

priority_high

ImportantServer Limits: File uploads are subject to your PHP upload_max_filesize and post_max_size configuration. If a large file disappears during upload, check these settings in your php.ini.

warning

CautionExtension Spoofing: Always include your own server-side validation. While the GeniXCMS Upload class checks extensions, for high-security environments, consider the Files Class to verify actual file headers and content integrity.