feuerwerk/api/lib/OriginalName.php

<?php
declare(strict_types=1);

/**
 * The name a file had when it was uploaded, kept beside it as `{file}.json`.
 *
 * A stored file is named after the hash of its bytes, which says nothing to a human: the image
 * picker could only caption a file it already knew as an asset, and a picked one became "Texture 2".
 * The sidecar gives every file a caption and every asset made from it a sensible name.
 *
 * It is deliberately not part of the file itself and never authoritative: a missing, unreadable or
 * empty sidecar simply means "no name known", which is what every file uploaded before this
 * existed looks like.
 *
 * **The last upload wins** (user's decision 2026-09-13): re-uploading the same bytes under a new
 * name renames what the picker shows. An upload that carries no name at all (a pasted image has
 * none) leaves an existing sidecar alone rather than erasing it.
 */
final class OriginalName
{
    /** Long enough for any real file name; the cap is against a crafted one, not against users. */
    private const MAX_LENGTH = 120;

    /**
     * The name as it is safe to store: no path, no control characters, valid UTF-8, bounded.
     * Returns '' for anything that is left with nothing – the caller then stores no sidecar.
     */
    public static function sanitize(string $raw): string
    {
        // Checked first: the /u flag below makes preg_replace return null on invalid bytes, which
        // would turn "bad encoding" into "empty" by accident rather than on purpose.
        if (!mb_check_encoding($raw, 'UTF-8')) {
            return '';
        }
        // A Windows client sends backslashes, which basename() does not treat as separators here.
        $name = basename(str_replace('\\', '/', $raw));
        $name = trim((string) preg_replace('/[\x00-\x1F\x7F]/u', '', $name));
        if ($name === '' || $name === '.' || $name === '..') {
            return '';
        }
        return mb_strlen($name) > self::MAX_LENGTH ? mb_substr($name, 0, self::MAX_LENGTH) : $name;
    }

    /**
     * The stored name, or '' when nothing is known about this file – which is the normal case for
     * everything uploaded before sidecars existed.
     *
     * The absence is checked rather than suppressed with `@`: index.php installs an error handler
     * that turns every warning into an exception, and it does not consult `error_reporting()`, so
     * `@` does not silence it. A missing sidecar would otherwise fail the whole listing.
     */
    public static function read(string $dir, string $file): string
    {
        $path = $dir . '/' . $file . '.json';
        if (!is_file($path)) {
            return '';
        }
        $raw = file_get_contents($path);
        if ($raw === false) {
            return '';
        }
        $data = json_decode($raw, true);
        return is_array($data) && is_string($data['name'] ?? null) ? self::sanitize($data['name']) : '';
    }

    /** Writes the sidecar; an empty name writes nothing and removes nothing. */
    public static function write(string $dir, string $file, string $name): void
    {
        $clean = self::sanitize($name);
        if ($clean === '') {
            return;
        }
        $json = json_encode(['name' => $clean], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
        if ($json === false) {
            return;
        }
        try {
            AtomicFile::write($dir . '/' . $file . '.json', $json, AtomicFile::SERVED, 'name file');
        } catch (RuntimeException) {
            // A nameless file is a small loss; failing the upload over it would be worse.
        }
    }

    /** Removing a file that has no sidecar is the normal case, not a failure. */
    public static function delete(string $dir, string $file): void
    {
        $path = $dir . '/' . $file . '.json';
        if (is_file($path)) {
            unlink($path);
        }
    }
}