<?php
namespace Zadex\Admin;

defined('ABSPATH') || exit;

/**
 * Reads one `$_FILES` entry field by field with a sanitizer per field, so upload handlers never touch the raw
 * superglobal. Works for single inputs (`name="kit"`) and for nested inputs (`name="font_files[0][woff2]"`,
 * where every field is an array of the same shape). Callers must check the capability first and
 * still validate the file itself (extension, MIME sniffing, is_uploaded_file) before storing it.
 */
final class UploadedFile
{
    /**
     * @return array{name: mixed, type: mixed, tmp_name: mixed, error: mixed, size: mixed}|null
     */
    public static function from_request(string $field, string $nonce_action): ?array
    {
        // Callers check the capability and the nonce first; the nonce is verified again here so a file entry is
        // never read without it. WordPress does not slash $_FILES, so no wp_unslash().
        check_admin_referer($nonce_action);
        if (!isset($_FILES[$field]['name'], $_FILES[$field]['tmp_name'])) {
            return null;
        }
        return [
            'name'     => is_array($_FILES[$field]['name']) ? map_deep($_FILES[$field]['name'], 'sanitize_file_name') : sanitize_file_name((string) $_FILES[$field]['name']),
            'type'     => isset($_FILES[$field]['type']) ? (is_array($_FILES[$field]['type']) ? map_deep($_FILES[$field]['type'], 'sanitize_mime_type') : sanitize_mime_type((string) $_FILES[$field]['type'])) : '',
            'tmp_name' => is_array($_FILES[$field]['tmp_name']) ? map_deep($_FILES[$field]['tmp_name'], 'sanitize_text_field') : sanitize_text_field((string) $_FILES[$field]['tmp_name']),
            'error'    => isset($_FILES[$field]['error']) ? (is_array($_FILES[$field]['error']) ? map_deep($_FILES[$field]['error'], 'absint') : absint($_FILES[$field]['error'])) : 4,
            'size'     => isset($_FILES[$field]['size']) ? (is_array($_FILES[$field]['size']) ? map_deep($_FILES[$field]['size'], 'absint') : absint($_FILES[$field]['size'])) : 0,
        ];
    }
}