PathStrategy.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Storage - PathStrategy
 *
 * @package Italix\Storage
 */

declare(strict_types=1);

namespace Italix\Storage;

/**
 * Where inside the store a file goes.
 *
 * The store decides *whether* a file may be stored — that is the safety model
 * and it is not negotiable. This decides only *where*, which is a sizing and
 * housekeeping question with genuinely different right answers:
 *
 * - a few hundred files: no sharding at all, `HashedPath(0)`
 * - one big corpus: `HashedPath(2)`, 65,536 leaves
 * - many tenants: `BucketedPath(new HashedPath(1))`, so the parent directory
 *   holding the tenants does not itself grow without limit
 * - archives read by date: `DatePath(new HashedPath(1))`
 *
 * A strategy returns a path *relative to the store root*. It cannot escape it:
 * the store validates whatever comes back before touching the filesystem, so a
 * third-party strategy is a layout decision, never a security decision.
 *
 * **Changing strategy is not a migration.** Every read takes the stored path as
 * an argument and never recomputes it, so files already written keep resolving.
 * Only new writes land in the new shape.
 */
interface PathStrategy
{
    /**
     * @param string $folder      already validated by the store: `[A-Za-z0-9._/-]`, no `..`, may be ''
     * @param string $sha256_c    64 lowercase hex characters
     * @param string $extension_c from the sniffed type, never from the upload
     *
     * @return string a path relative to the store root
     */
    public function path_for(string $folder, string $sha256_c, string $extension_c): string;

    /**
     * One line, for a CLI probe. e.g. `{folder}/{ab}/{cd}/{sha256}.{ext}`
     */
    public function describe(): string;
}