YwxAppThink/ywxapp/library/TemplateInstaller.php

<?php
/**
 * 模板皮肤安装器（后台「安装模板」/ appmall 下载后部署的接入点）。
 *
 * 模板包 zip 由 scripts/package_template.php 产出，内部两段前缀：
 *   - templates/<name>/...    → 部署到 <root>/templates/<name>/
 *   - static/...               → 部署到 <root>/public/static/templates/<name>/
 *
 * 模板不携带 DB 迁移，安装即文件落地；与插件(Addon)的 importsql 机制解耦。
 */
namespace ywxapp\library;

use ZipArchive;

class TemplateInstaller
{
    /**
     * 从 zip 部署模板到项目。
     *
     * @param string $zipPath  模板包 zip 绝对路径
     * @param string $rootDir  项目根目录（含 templates/ 与 public/）
     * @return array 部署后的清单 ['name','version','target_addon','tpl_dir','static_dir']
     * @throws \RuntimeException
     */
    public static function install(string $zipPath, string $rootDir): array
    {
        if (!is_file($zipPath)) {
            throw new \RuntimeException("模板包不存在: {$zipPath}");
        }
        if (!class_exists('ZipArchive')) {
            throw new \RuntimeException('ZipArchive 扩展不可用');
        }

        $zip = new ZipArchive();
        if ($zip->open($zipPath) !== true) {
            throw new \RuntimeException("无法打开模板包: {$zipPath}");
        }

        // 先探测模板名（templates/<name>/ 前缀）
        $name = '';
        for ($i = 0; $i < $zip->numFiles; $i++) {
            $entry = $zip->getNameIndex($i);
            if (preg_match('#^templates/([^/]+)/#', $entry, $m)) {
                $name = $m[1];
                break;
            }
        }
        if ($name === '') {
            $zip->close();
            throw new \RuntimeException('zip 中未找到 templates/<name>/ 结构，可能不是合法模板包');
        }

        // Zip Slip 防护第一道闸：模板名必须是「纯目录名」。
        // 原实现只要求匹配 templates/<name>/，而 [<^/]+> 可以是 '..'，
        // 于是 templates/../../public/x 也能命中，后面拼路径就直接越出了安装目录。
        if (! preg_match('/^[A-Za-z0-9_\-]{1,64}$/', $name)) {
            $zip->close();
            throw new \RuntimeException("模板名不合法（只允许字母数字与 - _）：{$name}");
        }

        $tplTarget    = rtrim($rootDir, '/\\') . '/templates/' . $name . '/';
        $staticTarget = rtrim($rootDir, '/\\') . '/public/static/templates/' . $name . '/';

        for ($i = 0; $i < $zip->numFiles; $i++) {
            $entry = $zip->getNameIndex($i);
            if ($entry === '' || $entry === null) {
                continue;
            }
            $prefix = 'templates/' . $name . '/';
            if (strpos($entry, $prefix) === 0) {
                $rel = substr($entry, strlen($prefix));
                self::assertSafeRelPath($rel, $entry);
                self::writeEntry($zip, $entry, $tplTarget . $rel, $tplTarget);
            } elseif (strpos($entry, 'static/') === 0) {
                $rel = substr($entry, strlen('static/'));
                if ($rel === '') {
                    continue;
                }
                self::assertSafeRelPath($rel, $entry);
                self::writeEntry($zip, $entry, $staticTarget . $rel, $staticTarget);
            }
        }
        $zip->close();

        $metaFile = $tplTarget . 'template.json';
        $meta     = is_file($metaFile) ? (json_decode(file_get_contents($metaFile), true) ?? []) : [];

        return [
            'name'          => $name,
            'version'       => $meta['version'] ?? '',
            'title'         => $meta['title'] ?? $name,
            'target_addon' => $meta['target_addon'] ?? [],
            'tpl_dir'       => $tplTarget,
            'static_dir'    => $staticTarget,
        ];
    }

    /**
     * 相对路径安全性校验（Zip Slip 第一道闸）
     *
     * 任何一个条目只要可能出现目录穿越迹象就拒绝安装：
     *  - 绝对路径（以 / 或 Windows 盘符开头）
     *  - 含 '..' 段
     *  - 含控制字符或空字节
     */
    protected static function assertSafeRelPath(string $rel, string $entry): void
    {
        if ($rel === '' || $rel === '.' ) {
            return;
        }
        if (strpos($rel, "\0") !== false || preg_match('/[\x00-\x1F]/', $rel)) {
            throw new \RuntimeException("模板包含非法条目名：{$entry}");
        }
        if ($rel[0] === '/' || $rel[0] === '\\' || preg_match('#^[A-Za-z]:#', $rel)) {
            throw new \RuntimeException("模板包含绝对路径条目：{$entry}");
        }
        foreach (explode('/', str_replace('\\', '/', $rel)) as $seg) {
            if ($seg === '..') {
                throw new \RuntimeException("模板包含目录穿越条目（Zip Slip）：{$entry}");
            }
        }
    }

    /**
     * 将 zip 内单个条目写出到目标路径（目录建目录，文件写内容）。
     *
     * @param ZipArchive $zip
     * @param string     $entry   zip 内条目名
     * @param string     $target  目标绝对路径
     * @param string     $baseDir 允许写入的根目录（Zip Slip 第二道闸）
     */
    protected static function writeEntry(ZipArchive $zip, string $entry, string $target, string $baseDir = ''): void
    {
        if (substr($entry, -1) === '/') {
            // 先校验再建目录：否则非法目录已经落到磁盘上才报错
            self::assertInside($target, $baseDir, $entry);
            if (!is_dir($target)) {
                @mkdir($target, 0755, true);
            }
            return;
        }
        $dir = dirname($target);
        // 归一化后再确认没有跑出基准目录：realpath 能解开 ../ 与符号链接
        self::assertInside($dir, $baseDir, $entry);
        if (!is_dir($dir)) {
            @mkdir($dir, 0755, true);
        }
        $content = $zip->getFromName($entry);
        if ($content === false) {
            return;
        }
        file_put_contents($target, $content);
    }

    /**
     * 把一个（可能还不存在的）绝对路径规范化为可比较形式
     *
     * realpath() 对不存在的路径返回 false，而安装时目标目录往往尚未创建，
     * 因此逐级向上找到第一个真实存在的祖先，再把未存在的尾部拼回去，同时折叠 `.` / `..`。
     */
    protected static function normalizeAbs(string $abs): string
    {
        $abs  = str_replace('\\', '/', rtrim($abs, '/'));
        $real = realpath($abs);
        if ($real !== false) {
            return str_replace('\\', '/', rtrim($real, '/'));
        }
        $tail = [];
        $cur  = $abs;
        $real = false;
        while (true) {
            $pos = strrpos($cur, '/');
            if ($pos === false) {
                break;
            }
            $tail[] = substr($cur, $pos + 1);
            $cur    = substr($cur, 0, $pos);
            if ($cur === '') {
                $cur = '/';
            }
            $real = realpath($cur);
            if ($real !== false) {
                break;
            }
            // Windows 盘符根 / POSIX 根，再往上没有了
            if (strlen($cur) <= 3) {
                break;
            }
        }
        if ($real === false) {
            return $abs;
        }
        $out = str_replace('\\', '/', rtrim($real, '/'));
        foreach (array_reverse($tail) as $seg) {
            $out .= '/' . $seg;
        }
        // 折叠 . 与 ..
        $parts = [];
        foreach (explode('/', $out) as $seg) {
            if ($seg === '.' || $seg === '') {
                continue;
            }
            if ($seg === '..') {
                array_pop($parts);
                continue;
            }
            $parts[] = $seg;
        }

        return '/' . implode('/', $parts);
    }

    /**
     * 确认 $path（文件或目录）确实位于 $baseDir 之内
     */
    protected static function assertInside(string $path, string $baseDir, string $entry): void
    {
        if ($baseDir === '') {
            return;
        }
        $target = self::normalizeAbs($path);
        $base   = self::normalizeAbs($baseDir);
        if (strcasecmp($target, $base) !== 0 && stripos($target . '/', $base . '/') !== 0) {
            throw new \RuntimeException("模板包试图写入安装目录之外的路径（Zip Slip）：{$entry}");
        }
    }
}