织梦使用加载上传类-织梦建站-盈思创科技

织梦的文件上传功能封装得很好，通过调用其核心类，可以轻松实现各种文件的上传，并自动处理文件重命名、路径保存、权限设置等，下面我将分步进行说明,并提供最常用场景的代码示例。

核心上传类

织梦的文件上传功能主要涉及两个核心文件：

include/helpers/upload.helper.php: 这是上传功能的核心PHP类文件，定义了 DedeUpload 类。
include/dialog/select_postframe.php: 这是后台文件选择器（弹出窗口）的入口文件,它会调用上传类。

我们主要需要关注和使用的是 DedeUpload 类。

加载上传类

要在你的自定义PHP页面中使用上传功能，首先必须加载这个类文件，我们使用织梦的全局函数 include_once() 来引入。

<?php
require_once(dirname(__FILE__) . '/../../include/common.inc.php'); // 加载织梦核心环境
require_once(DEDEINC . '/helpers/upload.helper.php'); // 加载上传类
// ... 你的代码 ...
?>

代码解释：

dirname(__FILE__): 获取当前文件所在的目录。
/../../include/common.inc.php: 这是从你的插件或自定义模块文件位置，回到网站根目录，再进入 include 文件夹来加载 common.inc.php，这个文件是织梦的入口文件，负责初始化所有环境变量、数据库连接等。
DEDEINC: 这是织梦定义的一个全局常量，指向 include 目录。DEDEINC . '/helpers/upload.helper.php' include/helpers/upload.helper.php 的完整路径,使用常量是更规范的做法。

使用上传类（核心步骤）

加载类之后，就可以通过实例化 DedeUpload 类并调用其方法来完成上传,以下是基本步骤和参数说明。

实例化上传类

$upload = new DedeUpload();

设置上传参数

这是最关键的一步，DedeUpload 类提供了多个参数来控制上传行为，你可以在实例化后，通过 -> 逐个设置,也可以在实例化时通过数组一次性传入。

常用参数列表：

参数名	类型	默认值	说明
`mimes`	字符串	''	允许的文件类型。`'jpg,jpeg,gif,png'`，留空表示允许所有类型，但受限于 `safe` 模式。
`maxsize`	整数	`2048`	允许上传的文件大小，单位是 KB。
`uploaddir`	字符串	`/uploads/`	上传文件的相对路径（相对于网站根目录）。必须确保此目录存在且可写。
`nameformat`	字符串	`'yyyyMMdd'`	文件名命名格式，可以是 `'yyyyMMdd'`（按日期）、`'hash'`（哈希值）或 `'custom'`（自定义）。
`customname`	字符串		当 `nameformat` 为 `'custom'` 时，自定义的文件名，可以包含占位符，如 `{filename}_{time}`。
`israndname`	布尔值	`true`	是否在文件名后添加随机数，如果为 `true`，文件名会变成 `原文件名_随机数.扩展名`。
`watermarkenable`	布尔值	`false`	是否启用水印。
`watermark`	字符串	`'text'`	水印类型，`'text'` 为文字水印，`'img'` 为图片水印。
`watermarktext`	字符串	`'织梦CMS'`	水印文字内容。
`watermarkpos`	字符串	`'1'`	水印位置，`1`-9 分别代表九个位置。
`isreplaced`	布尔值	`false`	如果目标文件已存在，是否覆盖。

设置示例：

$upload = new DedeUpload('jpg,jpeg,png,gif', 500, '/uploads/images/', 'hash', '', true, false, 'text', '我的水印', '9');

或者分步设置（更清晰）：

$upload = new DedeUpload();
$upload->SetMimes('jpg,jpeg,png,gif'); // 允许的文件类型
$upload->SetMaxsize(500); // 最大500KB
$upload->SetUploaddir('/uploads/mytest/'); // 上传到这个目录
$upload->SetIsrandname(true); // 文件名添加随机数
$upload->SetWatermarkenable(false); // 不使用水印

执行上传

设置好参数后，调用 Upload() 方法来执行上传，这个方法需要一个参数，即HTML表单中文件输入框的 name 属性值。

// 假设你的表单是 <input type="file" name="myfile" />
$re = $upload->Upload('myfile');
if ($re == '0') {
    // 上传成功
    $file_info = $upload->GetFileInfo(); // 获取上传成功后的文件信息
    echo "上传成功！<br>";
    echo "文件名: " . $file_info['name'] . "<br>";
    echo "原始文件名: " . $file_info['oldname'] . "<br>";
    echo "文件路径: " . $file_info['url'] . "<br>";
    echo "文件大小: " . $file_info['size'] . " KB<br>";
} else {
    // 上传失败
    echo "上传失败！错误信息：" . $upload->GetError();
}

Upload() 方法的返回值：

'0': 上传成功。
非 '0' 的字符串: 上传失败,字符串内容为具体的错误信息。

GetFileInfo() 方法返回的数组信息：

name: 服务器端保存的文件名。
oldname: 用户上传的原始文件名。
url: 文件的完整访问路径（如 /uploads/mytest/xxx_123.jpg）。
path: 文件的物理路径（如 /home/wwwroot/your_site/uploads/mytest/xxx_123.jpg）。
size: 文件大小（单位：KB）。
mime: 文件的MIME类型。

完整代码示例

下面是一个完整的、可以直接运行的PHP页面示例,它包含一个表单和上传处理逻辑。

<?php
// 1. 加载织梦核心环境和上传类
require_once(dirname(__FILE__) . '/../../include/common.inc.php');
require_once(DEDEINC . '/helpers/upload.helper.php');
// 定义上传目录
$upload_dir = '/uploads/demo/';
// 确保上传目录存在
if (!is_dir(DEDEROOT . $upload_dir)) {
    @mkdir(DEDEROOT . $upload_dir, 0777, true);
}
// 2. 处理上传逻辑
if (isset($_POST['submit'])) {
    // 实例化上传类
    $upload = new DedeUpload();
    // 设置上传参数
    $upload->SetMimes('jpg,jpeg,png,gif'); // 允许的图片类型
    $upload->SetMaxsize(1024); // 最大1MB
    $upload->SetUploaddir($upload_dir); // 设置上传目录
    $upload->SetIsrandname(true); // 文件名添加随机数
    // 执行上传
    $re = $upload->Upload('userfile'); // 'userfile' 是表单中input的name
    // 3. 显示结果
    if ($re == '0') {
        $file_info = $upload->GetFileInfo();
        echo "<div style='color:green;'>";
        echo "<h3>上传成功！</h3>";
        echo "<p>原始文件名: " . htmlspecialchars($file_info['oldname']) . "</p>";
        echo "<p>保存文件名: " . htmlspecialchars($file_info['name']) . "</p>";
        echo "<p>访问地址: <a href='" . $file_info['url'] . "' target='_blank'>" . $file_info['url'] . "</a></p>";
        echo "</div>";
    } else {
        echo "<div style='color:red;'>";
        echo "<h3>上传失败！</h3>";
        echo "<p>错误信息: " . $upload->GetError() . "</p>";
        echo "</div>";
    }
}
?>
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">织梦上传类测试</title>
</head>
<body>
    <h1>织梦文件上传测试</h1>
    <form action="" method="post" enctype="multipart/form-data">
        <p>
            <label for="userfile">选择文件 (仅支持jpg, png, gif):</label>
            <input type="file" name="userfile" id="userfile" required>
        </p>
        <p>
            <input type="submit" name="submit" value="开始上传">
        </p>
    </form>
</body>
</html>

重要注意事项

目录权限：SetUploaddir() 设置的目录（如 /uploads/demo/）必须存在，并且Web服务器（如Apache、Nginx）的用户对该目录有写入权限，如果目录不存在，代码中最好有创建目录的逻辑（如示例中的 mkdir）。
safe 模式：如果开启了织梦的 safe 模式，上传功能会受到更严格的限制，例如只能上传到指定目录,且可能无法使用某些参数。
安全考虑：虽然织梦的类做了封装，但在生产环境中，仍建议对上传的文件类型、大小、内容进行二次校验，以防止上传恶意文件（如Webshell）。
common.inc.php 的依赖：如果你的页面非常简单，不想加载整个织梦环境，可以尝试直接引入 upload.helper.php，但这样可能会缺少一些必要的全局变量和函数，可能导致不可预知的错误，推荐始终通过 common.inc.php 加载。

织梦使用加载上传类