<?php

declare(strict_types=1);

namespace Acms\Services\Asset;

/**
 * アセットのURL(src)からファイルシステム上の実体パスを導出する純粋関数群。
 *
 * a-blog cms のローカルアセットは「/{DIR_OFFSET}相対パス」というURLで公開され、
 * 実体は「{SCRIPT_DIR}相対パス」に置かれる（DIR_OFFSET は setPath() が定義する、
 * ドキュメントルートからインストール先までのオフセット）。この対応関係のみを扱う。
 * 外部URL・プロトコル相対URLはファイルシステム上の実体を持たないため null を返す。
 *
 * $dirOffset・$scriptDir を引数で受け取る（DIR_OFFSET / SCRIPT_DIR 定数を直接読まない）ことで、
 * 定数未定義の単体テスト環境でも検証できるようにしている。
 */
final class AssetPathResolver
{
    public static function toRealPath(string $src, string $dirOffset, string $scriptDir): ?string
    {
        if (str_starts_with($src, '//') || str_contains($src, '://')) {
            return null;
        }

        $prefix = '/' . $dirOffset;
        if (!str_starts_with($src, $prefix)) {
            return null;
        }

        $relative = substr($src, strlen($prefix));
        return rtrim($scriptDir, '/') . '/' . ltrim($relative, '/');
    }
}
