2. 开发
    3. 19 0 0
【在线阅读】Xiuno PHP 4.0开发手册 清扫版本 - 在Xiuno BBS中新定义的全局变量与函数
Tillreetree 14小时前

在Xiuno BBS中新定义的全局变量与函数

图片函数

image_ext()

说明

function image_ext(string $filename): string

获取文件扩展名(不包含点号),返回小写的扩展名。

【推荐】可以使用 PHP 内置的 pathinfo($filename, PATHINFO_EXTENSION) 获取扩展名

参数

  • $filename:文件名或文件路径

返回值

  • 返回小写的文件扩展名(不包含点号)
  • 如果文件名中没有扩展名,返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 获取图片扩展名
$ext = image_ext('photo.jpg');      // 返回: "jpg"
$ext = image_ext('avatar.PNG');     // 返回: "png"
$ext = image_ext('/path/to/image.GIF'); // 返回: "gif"

// 检查是否为允许的图片格式
$allowed = ['jpg', 'jpeg', 'png', 'gif'];
if (in_array(image_ext($_FILES['file']['name']), $allowed)) {
    echo "允许上传";
}

image_safe_name

说明

function image_safe_name(string $filename, string $dir): string

获取安全的文件名,如果文件存在,则加时间戳和随机数,避免重复。

此函数会将文件名中的特殊字符替换为下划线,只保留最后一个点号作为扩展名分隔符。

参数

  • $filename:原始文件名
  • $dir:目标目录路径,用于检查文件是否已存在

返回值

  • 返回安全的文件名
  • 如果文件已存在,返回带时间戳和随机数的文件名

示例

<?php
include './xiunophp/xiunophp.php';

// 获取安全文件名
$safeName = image_safe_name('user avatar.jpg', './upload/');
// 返回: "user_avatar.jpg" 或 "user_avatar1234567890_123.jpg"(如果文件已存在)

// 处理特殊字符
$safeName = image_safe_name('photo@2024.png', './upload/');
// 返回: "photo_2024.png"

// 用于文件上传
$uploadDir = './upload/avatar/';
$safeName = image_safe_name($_FILES['avatar']['name'], $uploadDir);
move_uploaded_file($_FILES['avatar']['tmp_name'], $uploadDir . $safeName);

image_thumb_name

说明

function image_thumb_name(string $filename): string

生成缩略图的文件名,在原文件名(不含扩展名)后添加 _thumb 后缀。

参数

  • $filename:原始文件名

返回值

  • 返回缩略图文件名,格式为 原文件名_thumb.扩展名

示例

<?php
include './xiunophp/xiunophp.php';

// 生成缩略图文件名
$thumbName = image_thumb_name('avatar.jpg');
// 返回: "avatar_thumb.jpg"

$thumbName = image_thumb_name('photo.png');
// 返回: "photo_thumb.png"

// 配合 image_thumb() 使用
$sourceFile = './upload/avatar.jpg';
$thumbFile = './upload/' . image_thumb_name('avatar.jpg');
$result = image_thumb($sourceFile, $thumbFile, 100, 100);

image_rand_name

说明

function image_rand_name(int $k): string

生成随机文件名,格式为 时间戳_随机数_k。

参数

  • $k:附加的标识数字,通常用于区分不同用途的文件

返回值

  • 返回随机文件名,格式为 时间戳_10位随机数_k

示例

<?php
include './xiunophp/xiunophp.php';

// 生成随机文件名
$randName = image_rand_name(1);
// 返回类似: "1234567890_1234567890_1"

// 用于上传文件
$ext = image_ext($_FILES['file']['name']);
$randName = image_rand_name(1) . '.' . $ext;
// 返回: "1234567890_1234567890_1.jpg"

// 推荐的现代写法
$randName = bin2hex(random_bytes(16)) . '.' . $ext;
// 返回: "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.jpg"

image_set_dir

说明

function image_set_dir(int $id, string $dir): string

根据 ID 创建分级目录结构,用于分散存储大量文件,避免单个目录下文件过多。

目录格式为 000/000/ 到 999/999/,支持最多十亿个文件(每个子目录最多 1000 个文件)。

参数

  • $id:文件/数据的 ID,会被格式化为 9 位数字
  • $dir:基础目录路径

返回值

  • 返回创建的相对路径,如 000/001

示例

<?php
include './xiunophp/xiunophp.php';

// 创建分级目录
$subdir = image_set_dir(123, './upload');
// 创建目录: ./upload/000/000/
// 返回: "000/000"

$subdir = image_set_dir(1000, './upload');
// 创建目录: ./upload/000/001/
// 返回: "000/001"

// 保存文件到分级目录
$id = 12345;
$subdir = image_set_dir($id, './upload/avatar');
$filepath = './upload/avatar/' . $subdir . '/' . $id . '.jpg';
move_uploaded_file($_FILES['avatar']['tmp_name'], $filepath);

image_get_dir

说明

function image_get_dir(int $id): string

根据 ID 获取分级目录路径(不创建目录)。

此函数与 image_set_dir() 功能相似,但不会创建目录,仅返回路径。用于访问已存储的文件。

参数

  • $id:文件/数据的 ID,会被格式化为 9 位数字

返回值

  • 返回相对路径,如 000/001

示例

<?php
include './xiunophp/xiunophp.php';

// 获取分级目录路径
$path = image_get_dir(123);
// 返回: "000/000"

$path = image_get_dir(1000);
// 返回: "000/001"

// 获取已存储文件的路径
$id = 12345;
$subdir = image_get_dir($id);
$filepath = './upload/avatar/' . $subdir . '/' . $id . '.jpg';

if (file_exists($filepath)) {
    // 文件存在,可以读取或删除
    $imageData = file_get_contents($filepath);
}

// 删除文件
$filepath = './upload/' . image_get_dir($id) . '/' . $id . '.jpg';
if (is_file($filepath)) {
    unlink($filepath);
}

image_thumb

说明

function image_thumb(string $sourcefile, string $destfile, int $forcedwidth = 80, int $forcedheight = 80): array

生成图片缩略图,按比例缩放图片到指定尺寸范围内。

此函数会保持图片的宽高比例,将图片缩放到不超过指定的宽度和高度。支持 JPEG、GIF、PNG、BMP 格式。

参数

  • $sourcefile:源图片路径
  • $destfile:目标图片路径
  • $forcedwidth:最大宽度,默认为 80
  • $forcedheight:最大高度,默认为 80

返回值

  • 返回关联数组:
    • filesize:缩略图文件大小(字节)
    • width:缩略图宽度
    • height:缩略图高度
  • 如果失败,返回 ['filesize'=>0, 'width'=>0, 'height'=>0]

示例

<?php
include './xiunophp/xiunophp.php';

// 生成缩略图
$result = image_thumb('./upload/avatar.jpg', './upload/avatar_thumb.jpg', 100, 100);
// 返回: ['filesize'=>12345, 'width'=>100, 'height'=>75]

// 检查是否成功
if ($result['filesize'] > 0) {
    echo "缩略图生成成功";
    echo "尺寸: {$result['width']} x {$result['height']}";
    echo "大小: " . round($result['filesize'] / 1024, 2) . " KB";
}

// 生成不同尺寸的缩略图
image_thumb('./upload/photo.jpg', './upload/photo_small.jpg', 80, 80);
image_thumb('./upload/photo.jpg', './upload/photo_medium.jpg', 200, 200);
image_thumb('./upload/photo.jpg', './upload/photo_large.jpg', 400, 400);

image_clip

说明

function image_clip(string $sourcefile, string $destfile, int $clipx, int $clipy, int $clipwidth, int $clipheight): int

图片裁切,从源图片的指定位置裁切指定尺寸的区域。

此函数用于从图片中裁切出特定区域,常用于头像裁切、图片编辑等场景。

参数

  • $sourcefile:源图片路径
  • $destfile:裁切后保存的目标路径
  • $clipx:裁切起始点的 X 坐标(左上角)
  • $clipy:裁切起始点的 Y 坐标(左上角)
  • $clipwidth:裁切区域的宽度
  • $clipheight:裁切区域的高度

返回值

  • 返回裁切后图片的文件大小(字节)
  • 如果失败,返回 0

示例

<?php
include './xiunophp/xiunophp.php';

// 从图片中心裁切 100x100 的区域
$sourceFile = './upload/photo.jpg';
$imgInfo = getimagesize($sourceFile);
$centerX = ($imgInfo[0] - 100) / 2;
$centerY = ($imgInfo[1] - 100) / 2;

$filesize = image_clip($sourceFile, './upload/avatar.jpg', $centerX, $centerY, 100, 100);

if ($filesize > 0) {
    echo "裁切成功,文件大小: " . round($filesize / 1024, 2) . " KB";
}

// 从左上角裁切
image_clip('./upload/photo.jpg', './upload/cropped.jpg', 0, 0, 200, 150);

// 用户头像裁切(从前端获取裁切坐标)
$clipX = intval($_POST['x']);
$clipY = intval($_POST['y']);
$clipWidth = intval($_POST['width']);
$clipHeight = intval($_POST['height']);
image_clip('./upload/temp.jpg', './upload/avatar.jpg', $clipX, $clipY, $clipWidth, $clipHeight);

image_clip_thumb

说明

function image_clip_thumb(string $sourcefile, string $destfile, int $forcedwidth = 80, int $forcedheight = 80): int

先裁切后缩略,生成固定尺寸的缩略图。

此函数会先从图片中心裁切出符合目标宽高比的区域,然后再缩放到指定尺寸。与 image_thumb() 不同,此函数会生成精确的指定尺寸,不保持原宽高比。

参数

  • $sourcefile:源图片路径
  • $destfile:目标图片路径
  • $forcedwidth:目标宽度,默认为 80
  • $forcedheight:目标高度,默认为 80

返回值

  • 返回缩略图文件大小(字节)
  • 如果失败,返回 0

示例

<?php
include './xiunophp/xiunophp.php';

// 生成固定尺寸的头像缩略图
$filesize = image_clip_thumb('./upload/photo.jpg', './upload/avatar_thumb.jpg', 100, 100);

if ($filesize > 0) {
    echo "缩略图生成成功,大小: " . round($filesize / 1024, 2) . " KB";
}

// 生成不同尺寸的固定缩略图
image_clip_thumb('./upload/photo.jpg', './upload/thumb_small.jpg', 50, 50);
image_clip_thumb('./upload/photo.jpg', './upload/thumb_medium.jpg', 150, 150);
image_clip_thumb('./upload/photo.jpg', './upload/thumb_large.jpg', 300, 300);

// 用于用户头像上传
$sourceFile = $_FILES['avatar']['tmp_name'];
$destFile = './upload/avatar/' . $uid . '_thumb.jpg';
image_clip_thumb($sourceFile, $destFile, 200, 200);

image_safe_thumb

说明

function image_safe_thumb(string $sourcefile, int $id, string $ext, string $dir1, int $forcedwidth, int $forcedheight, int $randomname = 0): array

安全缩略图生成函数,自动创建分级目录并生成缩略图。

这是一个综合性的图片处理函数,集成了目录创建、文件命名、缩略图生成等功能。适用于用户头像、附件等需要按 ID 分级存储的场景。

参数

  • $sourcefile:源图片路径
  • $id:文件 ID,用于生成分级目录和文件名
  • $ext:文件扩展名(包含点号,如 .jpg)
  • $dir1:基础目录路径
  • $forcedwidth:缩略图最大宽度
  • $forcedheight:缩略图最大高度
  • $randomname:是否使用随机文件名,默认为 0(使用 ID 作为文件名)

返回值

  • 返回关联数组:
    • filesize:缩略图文件大小(字节)
    • width:缩略图宽度
    • height:缩略图高度
    • fileurl:相对文件 URL,如 000/001/123.jpg

示例

<?php
include './xiunophp/xiunophp.php';

// 用户上传头像
$uid = 12345;
$sourceFile = $_FILES['avatar']['tmp_name'];
$ext = '.' . image_ext($_FILES['avatar']['name']);

$result = image_safe_thumb($sourceFile, $uid, $ext, './upload/avatar/', 200, 200);

if ($result['filesize'] > 0) {
    echo "头像上传成功";
    echo "文件路径: " . $result['fileurl'];
    echo "尺寸: {$result['width']} x {$result['height']}";
    echo "大小: " . round($result['filesize'] / 1024, 2) . " KB";
}

// 使用随机文件名
$result = image_safe_thumb($sourceFile, $uid, $ext, './upload/photo/', 800, 600, 1);
// 文件名类似: 000/001/a1b2c3d4e5f6.jpg

// 附件上传
$aid = 67890;
$result = image_safe_thumb($_FILES['attachment']['tmp_name'], $aid, '.png', './upload/attach/', 1024, 768);

拼音函数

pinyin()

说明

function pinyin($s, $sep = ' '): string

最全的PHP汉字转拼音函数 （共25961字，包括 20902基本字 + 5059生僻字）

作者：wuzhaohuan kongphp@gmail.com

参数

  • s：待转换的字符串
  • sep：分隔符，默认为空格

返回值

  • 将汉字转换成拼音后的字符串

示例

var_dump(pinyin('最全的PHP汉字转拼音库，比百度词典还全（dict.baidu.com）'));

杂项函数

xn_log_post_data()

说明

function xn_log_post_data(): void

将POST数据记录到日志文件中。

不会记录键为password、password_new、password_old的POST数据。

参数

  • 无

    返回值

  • 无

    示例

    <?php
include './xiunophp/xiunophp.php';
xn_log_post_data();

    error_handle()

说明

function error_handle(int $errno, string $errstr, string $errfile, int $errline): bool

为xiuno bbs设计的全局错误处理函数。

参数

  • $errno：错误号
  • $errstr：错误信息
  • $errfile：错误文件名
  • $errline：错误行号

返回值

  • 无

示例

param_word()

说明

function param_word(string $key, int $len = 32): string

安全获取单词类参数，仅保留 [a-zA-Z0-9_] 字符。

此函数用于过滤用户输入中的特殊字符，适合用于获取用户名、标识符等场景。

参数

  • $key：$_REQUEST 中的键名
  • $len：最大长度，默认为 32

返回值

  • 返回过滤后的安全字符串，仅包含字母、数字和下划线

示例

<?php
include './xiunophp/xiunophp.php';

// 假设 URL 为: ?username=admin123&tag=test_tag
$username = param_word('username');  // 返回 "admin123"
$tag = param_word('tag', 10);        // 返回 "test_tag"，最大10字符

// 如果输入包含特殊字符，会被过滤
// URL: ?name=user@#$%name
$name = param_word('name');          // 返回 "username"

param_base64()

说明

function param_base64(string $key, int $len = 0): string

获取并解码 Base64 编码的参数数据，支持 Data URL 格式（如 data:image/png;base64,xxxxx）。

此函数常用于处理前端上传的 Base64 图片数据。

【推荐】若要上传文件，请务必使用enctype="multipart/form-data"而不是enctype="application/x-www-form-urlencoded"然后把数据通过base64编码，这样会导致你多传输了三分之一的数据量，得不偿失啊。

参数

  • $key：$_REQUEST 中的键名
  • $len：返回数据的最大长度，默认为 0（不限制）

返回值

  • 返回解码后的原始二进制数据字符串
  • 如果参数为空，返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 假设前端通过 AJAX 发送 Base64 图片数据
// POST: image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEA...
$imageData = param_base64('image');

// 限制数据长度为 1MB
$imageData = param_base64('image', 1048576);

// 保存为文件
if ($imageData) {
    file_put_contents('./upload/image.png', $imageData);
}

param_json()

说明

function param_json(string $key): array|string

获取并解码 JSON 格式的参数数据。

【推荐】使用json_decode(param($key,''),true)而不是使用本函数来确保输入内容是字符串再进行解码。

参数

  • $key：$_REQUEST 中的键名

返回值

  • 返回解码后的数组或字符串
  • 如果参数为空或解码失败，返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 假设 URL 为: ?data={"name":"John","age":30}
$data = param_json('data');
// 返回: ['name' => 'John', 'age' => 30]

if (is_array($data)) {
    echo $data['name'];  // 输出: John
    echo $data['age'];   // 输出: 30
}

param_url()

说明

function param_url(string $key): string

获取并解码 URL 编码的参数数据。使用 XiunoPHP 自定义的 xn_urldecode() 函数进行解码。

【推荐】此函数用于处理 XiunoPHP 特殊编码格式的 URL 数据。对于标准 URL 编码，建议直接使用 PHP 内置的 urldecode() 函数。

参数

  • $key：$_REQUEST 中的键名

返回值

  • 返回解码后的字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 假设 URL 为: ?redirect=http_3a_2f_2fexample_2ecom_2fpath
// XiunoPHP 使用 _ 替代 % 的特殊编码格式
$url = param_url('redirect');
// 返回解码后的 URL

xn_safe_word()

说明

function xn_safe_word(string $s, int $len): string

安全过滤字符串，仅保留 [a-zA-Z0-9_] 字符（即 \w 匹配的字符）。

你可以直接使用 preg_replace('/\W+/', '', $s) 或 preg_replace('/[^a-zA-Z0-9_]/', '', $s) 实现相同效果。

参数

  • $s：待过滤的字符串
  • $len：返回字符串的最大长度

返回值

  • 返回过滤后的安全字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 过滤特殊字符
$safe = xn_safe_word('user@#$%name_123', 20);
// 返回: "username_123"

// 限制长度
$safe = xn_safe_word('very_long_username_here', 10);
// 返回: "very_long_" (前10个字符)

// 用于生成安全的文件名或标识符
$filename = xn_safe_word($_POST['filename'], 50);

param_force()

说明

function param_force(mixed $val, mixed $defval, bool $htmlspecialchars = TRUE, bool $addslashes = FALSE): mixed

强制类型转换和安全处理参数值。支持字符串和一维数组的处理。这是param函数的内部实现逻辑，被抽离成了独立函数。

参数

  • $val：待处理的值
  • $defval：默认值，用于确定返回类型。如果是数组，则处理数组类型
  • $htmlspecialchars：是否进行 HTML 实体转义，默认为 TRUE
  • $addslashes：是否添加斜杠转义，默认为 FALSE

返回值

  • 根据 $defval 的类型返回相应类型的值
  • 如果 $defval 是字符串，返回处理后的字符串
  • 如果 $defval 是整数，返回整数值
  • 如果 $defval 是数组，返回处理后的数组

示例

<?php
include './xiunophp/xiunophp.php';

// 字符串类型处理
$val = param_force($_POST['name'], '', true, false);
// 返回 HTML 转义后的字符串

// 整数类型处理
$id = param_force($_POST['id'], 0);
// 返回整数值

// 数组类型处理
$ids = param_force($_POST['ids'], array(0));
// 返回整数数组

// 不进行 HTML 转义
$content = param_force($_POST['content'], '', false);

jump()

说明

function jump(string $message, string $url = '', int $delay = 3): string

生成跳转链接和自动跳转脚本。用于message函数的“页面提示后自动跳转”。

如果不需要这么花哨的话，也可以使用 HTTP 重定向 header('Location: url')。

参数

  • $message：显示的提示消息
  • $url：跳转目标 URL，如果为 back 则返回上一页；该参数不可被字符串拼接攻击手段绕过（已经测试，无法用该参数实现刷新页面自身）
  • $delay：延迟跳转时间（秒），默认为 3 秒

返回值

  • 返回包含链接和自动跳转脚本的 HTML 字符串
  • 如果是 AJAX 请求，仅返回消息文本

示例

<?php
include './xiunophp/xiunophp.php';

// 3秒后跳转到首页
echo jump('操作成功，正在跳转...', './', 3);

// 返回上一页
echo jump('操作失败，点击返回', 'back');

// 自定义跳转
echo jump('登录成功', 'user-profile.htm', 2);

xn_json_number_array_to_string()

说明

function xn_json_number_array_to_string(array $arr): string

将数字索引数组转换为 JSON 字符串。

【已弃用】此函数在源码中已被注释掉，不再使用。请直接使用 PHP 内置的 json_encode() 函数。

参数

  • $arr：数字索引数组

返回值

  • 返回 JSON 格式的字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用 json_encode() 替代
$arr = [1, 2, 3, 4, 5];
$json = json_encode($arr);  // 返回: "[1,2,3,4,5]"

xn_json_assoc_array_to_string()

说明

function xn_json_assoc_array_to_string(array $arr): string

将关联数组转换为 JSON 字符串。

【已弃用】此函数在源码中已被注释掉，不再使用。请直接使用 PHP 内置的 json_encode() 函数。

参数

  • $arr：关联数组

返回值

  • 返回 JSON 格式的字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用 json_encode() 替代
$arr = ['name' => 'John', 'age' => 30];
$json = json_encode($arr);  // 返回: '{"name":"John","age":30}'

is_number_array()

说明

function is_number_array(array $arr): bool

判断数组是否为数字索引数组（从 0 开始连续递增）。

【已弃用】此函数在源码中已被注释掉。在 PHP 8 中，可以使用 array_is_list() 函数（PHP 8.1+）或 array_keys($arr) === range(0, count($arr) - 1) 实现。

参数

  • $arr：待检测的数组

返回值

  • 如果是数字索引数组返回 TRUE，否则返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// PHP 8.1+ 推荐使用
$arr1 = [1, 2, 3, 4];
$isList = array_is_list($arr1);  // true

$arr2 = ['name' => 'John', 'age' => 30];
$isList = array_is_list($arr2);  // false

// 兼容写法
function is_number_array($arr) {
    return array_keys($arr) === range(0, count($arr) - 1);
}

ucs2_to_utf8()

说明

function ucs2_to_utf8(string $s): string

将 UCS-2 编码的字符串转换为 UTF-8 编码。

【已弃用】此函数在源码中已被注释掉。在 PHP 8 中，请使用 iconv('UCS-2', 'UTF-8', $s) 或 mb_convert_encoding($s, 'UTF-8', 'UCS-2') 实现。

参数

  • $s：UCS-2 编码的字符串

返回值

  • 返回 UTF-8 编码的字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用 iconv 或 mb_convert_encoding
$ucs2String = "\x4E\x2D\x65\x87";  // UCS-2 编码的"中文"
$utf8String = iconv('UCS-2', 'UTF-8', $ucs2String);

// 或使用 mbstring
$utf8String = mb_convert_encoding($ucs2String, 'UTF-8', 'UCS-2');

pagination()

说明

function pagination(string $url, int $totalnum, int $page, int $pagesize = 20): string

生成 Bootstrap 风格的分页 HTML 代码。

参数

  • $url：分页链接模板，使用 {page} 作为页码占位符
  • $totalnum：总记录数
  • $page：当前页码
  • $pagesize：每页显示数量，默认为 20

返回值

  • 返回 Bootstrap 风格的分页 HTML 字符串
  • 如果总页数小于 2，返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 生成分页
$total = 150;  // 总记录数
$page = 3;     // 当前页
$url = 'thread-list-{page}.htm';

$html = pagination($url, $total, $page, 20);
echo '<ul class="pagination">' . $html . '</ul>';

// 输出示例:
// <li class="page-item"><a href="thread-list-2.htm" class="page-link">◀</a></li>
// <li class="page-item"><a href="thread-list-1.htm" class="page-link">1</a></li>
// <li class="page-item active"><a href="thread-list-3.htm" class="page-link">3</a></li>
// ...

pager()

说明

function pager(string $url, int $totalnum, int $page, int $pagesize = 20): string

生成简单的上一页/下一页分页 HTML 代码。比 pagination() 更省资源，不需要 count() 查询。

【推荐】此函数适用于大数据量场景，避免了 COUNT(*) 查询的开销。在现代项目中，建议使用前端框架的分页组件。

参数

  • $url：分页链接模板，使用 {page} 作为页码占位符
  • $totalnum：总记录数
  • $page：当前页码
  • $pagesize：每页显示数量，默认为 20

返回值

  • 返回简单的分页 HTML 字符串，包含上一页、当前页/总页数、下一页
  • 如果总页数小于 2，返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 生成简单分页
$total = 150;
$page = 3;
$url = 'thread-list-{page}.htm';

echo pager($url, $total, $page, 20);
// 输出: <li><a href="thread-list-2.htm">上一页</a></li> 3 / 8 <li><a href="thread-list-4.htm">下一页</a></li>

pages()

说明

function pages(string $url, int $totalnum, int $page, int $pagesize = 20): string

生成分页 HTML 代码（非 Bootstrap 风格）。

【已弃用】此函数在源码中已被注释掉。请使用 pagination() 函数替代。

参数

  • $url：分页链接模板，使用 {page} 作为页码占位符
  • $totalnum：总记录数
  • $page：当前页码
  • $pagesize：每页显示数量，默认为 20

返回值

  • 返回分页 HTML 字符串
  • 如果总页数小于 2，返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用 pagination() 替代
$total = 150;
$page = 3;
$url = 'thread-list-{page}.htm';

echo '<ul class="pagination">' . pagination($url, $total, $page, 20) . '</ul>';

simple_pages()

说明

function simple_pages(string $url, int $totalnum, int $page, int $pagesize = 20): string

生成简单的上一页/下一页分页 HTML 代码。

【已弃用】此函数在源码中已被注释掉。请使用 pager() 函数替代。

参数

  • $url：分页链接模板，使用 {page} 作为页码占位符
  • $totalnum：总记录数
  • $page：当前页码
  • $pagesize：每页显示数量，默认为 20

返回值

  • 返回简单的分页 HTML 字符串
  • 如果总页数小于 2，返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用 pager() 替代
$total = 150;
$page = 3;
$url = 'thread-list-{page}.htm';

echo pager($url, $total, $page, 20);

page()

说明

function page(int $page, int $n, int $pagesize): int

计算并返回合法的页码，确保页码在有效范围内。

【已弃用】此函数在源码中已被注释掉。请使用 mid() 函数替代，或直接使用 max(1, min($page, $totalPages))。

参数

  • $page：当前页码
  • $n：总记录数
  • $pagesize：每页显示数量

返回值

  • 返回合法的页码（1 到总页数之间）

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用 mid() 替代
$page = 10;
$total = 50;
$pagesize = 20;
$totalPages = ceil($total / $pagesize);  // 3

// 确保页码在有效范围内
$validPage = mid($page, 1, $totalPages);  // 返回 3

mid()

说明

function mid(int $n, int $min, int $max): int

将数值限制在指定范围内（类似 clamp 函数）。

参数

  • $n：待限制的数值
  • $min：最小值
  • $max：最大值

返回值

  • 返回限制在 $min 和 $max 之间的值

示例

<?php
include './xiunophp/xiunophp.php';

// 限制页码范围
$page = mid($_GET['page'], 1, 100);  // 确保页码在 1-100 之间

// 限制年龄范围
$age = mid(150, 0, 120);  // 返回 120

// 限制评分范围
$score = mid(-5, 0, 100);  // 返回 0

ip()

说明

function ip(): string

获取客户端 IP 地址。支持从 CDN 获取真实 IP。

【注意】此函数在开启 CDN 时可能存在 IP 伪造风险。在生产环境中可能需要自行实现更安全的 IP 获取方式。

参数

  • 无

返回值

  • 返回客户端 IP 地址字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 获取客户端 IP
$clientIp = ip();
echo "客户端 IP: " . $clientIp;

// 用于日志记录
xn_log("用户登录，IP: " . ip(), 'login');

// 用于访问限制
if (ip() === '192.168.1.100') {
    // 管理员操作
}

get__browser()

说明

function get__browser(): array

获取客户端浏览器信息，包括设备类型、浏览器名称和版本。

【推荐】此函数效果极差，但却是那个时代能做到的最佳选择。建议使用专门的 User Agent 解析库如 mobiledetect/mobiledetectlib。

参数

  • 无

返回值

  • 返回包含浏览器信息的数组：
    • device：设备类型（pc|mobile|pad）
    • name：浏览器名称（chrome|firefox|ie|opera|robot）
    • version：浏览器版本号

示例

<?php
include './xiunophp/xiunophp.php';

$browser = get__browser();

// 检测设备类型
if ($browser['device'] === 'mobile') {
    // 移动端适配
}

// 检测 IE 浏览器
if ($browser['name'] === 'ie' && $browser['version'] < 9) {
    // 提示用户升级浏览器
}

// 检测爬虫
if ($browser['name'] === 'robot') {
    // 爬虫处理逻辑
}

备注

参考：
各种旧浏览器的User Agent样本
IE
  • Mozilla/4.0 (compatible; MSIE 5.0; Windows NT)
  • Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)
  • Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.2)
  • Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)

Win7+ie9：

  • Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Win64; x64; Trident/5.0; .NET CLR 2.0.50727; SLCC2; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; InfoPath.3; .NET4.0C; Tablet PC 2.0; .NET4.0E)

win7+ie11，模拟 78910 头是一样的 mozilla/5.0 (windows nt 6.1; wow64; trident/7.0; rv:11.0) like gecko

Win7+ie8： Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.1; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; InfoPath.3)

WinXP+ie8： Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 5.1; Trident/4.0; GTB7.0)

WinXP+ie7： Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1)

WinXP+ie6： Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)

傲游3.1.7在Win7+ie9,高速模式: Mozilla/5.0 (Windows; U; Windows NT 6.1; ) AppleWebKit/534.12 (KHTML, like Gecko) Maxthon/3.0 Safari/534.12

傲游3.1.7在Win7+ie9,IE内核兼容模式: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; WOW64; Trident/5.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; InfoPath.3; .NET4.0C; .NET4.0E)

搜狗

搜狗3.0在Win7+ie9,IE内核兼容模式: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; WOW64; Trident/5.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; InfoPath.3; .NET4.0C; .NET4.0E; SE 2.X MetaSr 1.0)

搜狗3.0在Win7+ie9,高速模式: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US) AppleWebKit/534.3 (KHTML, like Gecko) Chrome/6.0.472.33 Safari/534.3 SE 2.X MetaSr 1.0

360

360浏览器3.0在Win7+ie9: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; InfoPath.3; .NET4.0C; .NET4.0E)

QQ 浏览器

QQ 浏览器6.9(11079)在Win7+ie9,极速模式: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/13.0.782.41 Safari/535.1 QQBrowser/6.9.11079.201

QQ浏览器6.9(11079)在Win7+ie9,IE内核兼容模式: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.1; WOW64; Trident/5.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; InfoPath.3; .NET4.0C; .NET4.0E) QQBrowser/6.9.11079.201

阿云浏览器

阿云浏览器 1.3.0.1724 Beta 在Win7+ie9: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)

MIUI V5

Mozilla/5.0 (Linux; U; Android ; ; Build/) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30 XiaoMi/MiuiBrowser/1.0

check_browser()

说明

function check_browser(array $browser): void

检查浏览器兼容性，如果不兼容则显示提示页面并退出。

【已弃用】现在没人用IE浏览器了

参数

  • $browser：浏览器信息数组，由 get__browser() 返回

返回值

  • 无返回值，如果不兼容则直接退出程序

示例

<?php
include './xiunophp/xiunophp.php';

$browser = get__browser();
check_browser($browser);  // 如果是 IE8 以下，显示提示页面并退出

// 继续执行正常逻辑
echo "欢迎使用本系统";

browser_lang()

说明

function browser_lang(): string

获取浏览器首选语言。

【推荐】此函数仅支持有限的几种语言。在现代项目中，建议使用 Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']) 或解析 Accept-Language 头获取更完整的语言信息。

参数

  • 无

返回值

  • 返回浏览器语言代码，如 zh-cn、ko-kr

示例

<?php
include './xiunophp/xiunophp.php';

$lang = browser_lang();
echo "浏览器语言: " . $lang;  // 输出: zh-cn

// 根据语言加载不同的语言包
if ($lang === 'ko-kr') {
    include './lang/ko.php';
} else {
    include './lang/zh-cn.php';
}

file_backname()

说明

function file_backname(string $filepath): string

生成备份文件名。在原文件名和扩展名之间添加 .backup。

参数

  • $filepath：原文件路径

返回值

  • 返回备份文件名

示例

<?php
include './xiunophp/xiunophp.php';

$backupName = file_backname('config/config.php');
// 返回: config/config.backup.php

$backupName = file_backname('data/settings.json');
// 返回: data/settings.backup.json

is_backfile()

说明

function is_backfile(string $filepath): bool

判断文件是否为备份文件（文件名中包含 .backup.）。

参数

  • $filepath：文件路径

返回值

  • 如果是备份文件返回 TRUE，否则返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

is_backfile('config/config.backup.php');  // 返回 true
is_backfile('config/config.php');         // 返回 false

// 用于过滤备份文件
$files = glob('config/*.php');
foreach ($files as $file) {
    if (!is_backfile($file)) {
        // 处理非备份文件
    }
}

file_backup()

说明

function file_backup(string $filepath): bool

创建文件备份。如果备份已存在，则不重复创建。

参数

  • $filepath：要备份的文件路径

返回值

  • 备份成功返回 TRUE，失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 备份配置文件
if (file_backup('config/config.php')) {
    echo "备份成功";
    // 备份文件: config/config.backup.php
}

// 修改配置前先备份
file_backup('conf/conf.php');
file_put_contents('conf/conf.php', $newContent);

file_backup_restore()

说明

function file_backup_restore(string $filepath): bool

从备份文件还原。将备份文件复制回原文件，并删除备份。

参数

  • $filepath：原文件路径

返回值

  • 还原成功返回 TRUE，失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 如果修改失败，还原备份
if (!file_put_contents('config/config.php', $newContent)) {
    file_backup_restore('config/config.php');
    echo "还原成功";
}

// 手动还原配置
file_backup_restore('conf/conf.php');

file_backup_unlink()

说明

function file_backup_unlink(string $filepath): bool

删除备份文件。

参数

  • $filepath：原文件路径

返回值

  • 删除成功返回 TRUE，失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 确认修改成功后删除备份
if (file_put_contents('config/config.php', $newContent)) {
    file_backup_unlink('config/config.php');
}

// 清理所有备份文件
$files = glob('config/*.backup.php');
foreach ($files as $file) {
    unlink($file);
}

move_upload_file()

说明

function move_upload_file(string $srcfile, string $destfile): bool

移动上传的文件到目标位置。内部使用 xn_copy() 实现。

【推荐】建议直接使用 move_uploaded_file() 函数，它有额外的安全检查，确保文件确实是通过 HTTP POST 上传的。

参数

  • $srcfile：源文件路径（临时文件）
  • $destfile：目标文件路径

返回值

  • 移动成功返回 TRUE，失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 处理文件上传
if (!empty($_FILES['avatar'])) {
    $tmpName = $_FILES['avatar']['tmp_name'];
    $destFile = './upload/avatar/' . $_FILES['avatar']['name'];

    if (move_upload_file($tmpName, $destFile)) {
        echo "上传成功";
    }
}

// 推荐使用 PHP 内置函数
if (is_uploaded_file($tmpName)) {
    move_uploaded_file($tmpName, $destFile);
}

t()

说明

function t(string $name = ''): void

在 HTTP 响应头中发送调试计时信息。

【已弃用】此函数在源码中已被注释掉。

参数

  • $name：计时标记名称

返回值

  • 无

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用现代性能分析工具
$startTime = microtime(true);

// ... 执行代码 ...

$endTime = microtime(true);
echo "执行时间: " . ($endTime - $startTime) . " 秒";

xn_url_parse()

说明

function xn_url_parse(string $request_url): array

解析 Xiuno BBS 特殊格式的 URL。支持多种 URL 格式：

  • http://domain.com/user-login.htm?a=b&c=d
  • http://domain.com/?user-login.htm?a=b&c=d
  • http://domain.com/user/login?a=b&c=d

参数

  • $request_url：请求的 URL 路径

返回值

  • 返回解析后的数组：
    • 数字索引：路径段（如 user、login，参考param函数的文档）
    • 字符串索引：URL 参数

示例

<?php
include './xiunophp/xiunophp.php';

// 解析 URL
$arr = xn_url_parse('user-login.htm?id=123');
// 返回: ['user', 'login', 'id' => 123]

$arr = xn_url_parse('thread-list-1.htm');
// 返回: ['thread', 'list', '1']

// 获取控制器和动作
$controller = $arr[0] ?? 'index';  // user
$action = $arr[1] ?? 'index';      // login

xn_url_add_arg()

说明

function xn_url_add_arg(string $url, string $k, mixed $v): string

向 URL 添加参数。支持 Xiuno BBS 的特殊 URL 格式。

参数

  • $url：原始 URL
  • $k：参数名
  • $v：参数值

返回值

  • 返回添加参数后的 URL

示例

<?php
include './xiunophp/xiunophp.php';

// 向 .htm 格式 URL 添加参数
$url = xn_url_add_arg('user-login.htm', 'id', 123);
// 返回: user-login-123.htm

// 向普通 URL 添加参数
$url = xn_url_add_arg('list.php', 'page', 2);
// 返回: list.php?page=2

// 向已有参数的 URL 添加参数
$url = xn_url_add_arg('list.php?type=new', 'page', 2);
// 返回: list.php?type=new&page=2

xn_url_parse_path_format()

说明

function xn_url_parse_path_format(string $s): array

解析路径格式的 URL（如 /user/login?a=1&b=2）。

参数

  • $s：URL 路径字符串

返回值

  • 返回解析后的数组：
    • 数字索引：路径段（如 user、login）
    • 其他键值对：查询参数

示例

<?php
include './xiunophp/xiunophp.php';

$arr = xn_url_parse_path_format('/user/login?a=1&b=2');
// 返回: ['user', 'login', 'a' => '1', 'b' => '2']

$arr = xn_url_parse_path_format('/thread/123');
// 返回: ['thread', '123']

// 用于 RESTful 风格路由
$controller = $arr[0] ?? 'index';
$action = $arr[1] ?? 'index';
$id = $arr[2] ?? null;

xn_copy()

说明

function xn_copy(string $src, string $dest): bool

复制文件。仅支持文件复制，不支持目录。

【推荐】可以直接使用 copy() 函数。此函数仅是对 copy() 的简单封装。

参数

  • $src：源文件路径
  • $dest：目标文件路径

返回值

  • 复制成功返回 TRUE，失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 复制文件
if (xn_copy('upload/temp.jpg', 'upload/avatar.jpg')) {
    echo "复制成功";
}

// 复制配置文件
xn_copy('config/config.php', 'config/config.bak.php');

xn_mkdir()

说明

function xn_mkdir(string $dir, ?int $mod = NULL, ?bool $recusive = NULL): bool

创建目录。

【推荐】建议直接使用 mkdir($dir, 0755, true) 创建递归目录。

参数

  • $dir：目录路径
  • $mod：目录权限，默认为 NULL（使用系统默认）
  • $recusive：是否递归创建，默认为 NULL

返回值

  • 创建成功返回 TRUE，目录已存在或创建失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 创建目录
xn_mkdir('upload/avatar', 0755, true);

// 推荐使用 PHP 内置函数
mkdir('upload/avatar', 0755, true);

xn_rmdir()

说明

function xn_rmdir(string $dir): bool

删除空目录。

【推荐】建议直接使用 rmdir() 函数。

【注意】此函数只能删除空目录。

参数

  • $dir：目录路径

返回值

  • 删除成功返回 TRUE，失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 删除空目录
if (xn_rmdir('upload/temp')) {
    echo "删除成功";
}

// 删除非空目录需要先清空
// 推荐使用 rmdir_recusive() 函数

xn_unlink()

说明

function xn_unlink(string $file): bool

删除文件。

【推荐】建议直接使用 unlink() 函数。此函数仅是对 unlink() 的简单封装。

参数

  • $file：文件路径

返回值

  • 删除成功返回 TRUE，文件不存在或删除失败返回 FALSE

示例

<?php
include './xiunophp/xiunophp.php';

// 删除文件
if (xn_unlink('upload/temp.jpg')) {
    echo "删除成功";
}

// 删除临时文件
xn_unlink('temp/cache.tmp');

xn_filemtime()

说明

function xn_filemtime(string $file): int

获取文件的修改时间。

【推荐】建议直接使用 filemtime() 函数。此函数仅是对 filemtime() 的简单封装，增加了文件存在性检查。

参数

  • $file：文件路径

返回值

  • 返回文件的修改时间戳
  • 如果文件不存在，返回 0

示例

<?php
include './xiunophp/xiunophp.php';

// 获取文件修改时间
$mtime = xn_filemtime('config/config.php');
echo "修改时间: " . date('Y-m-d H:i:s', $mtime);

// 检查缓存是否过期
$cacheTime = xn_filemtime('cache/data.json');
if (time() - $cacheTime > 3600) {
    // 缓存过期，重新生成
}

xn_set_dir()

说明

function xn_set_dir(int $id, string $dir = './'): string

根据 ID 创建分级目录结构。目录格式为 000/000/ 到 999/999/。

此函数用于将大量文件分散存储，避免单个目录下文件过多。

参数

  • $id：文件/数据的 ID
  • $dir：基础目录路径，默认为当前目录

返回值

  • 返回创建的相对路径，如 000/001

示例

<?php
include './xiunophp/xiunophp.php';

// 创建分级目录
$path = xn_set_dir(123, './upload');
// 创建目录: ./upload/000/000/
// 返回: 000/000

$path = xn_set_dir(1000, './upload');
// 创建目录: ./upload/000/001/
// 返回: 000/001

// 保存文件到分级目录
$id = 12345;
$subdir = xn_set_dir($id, './upload');
$filepath = './upload/' . $subdir . '/' . $id . '.jpg';
file_put_contents($filepath, $imageData);

xn_get_dir()

说明

function xn_get_dir(int $id): string

根据 ID 获取分级目录路径（不创建目录）。

参数

  • $id：文件/数据的 ID

返回值

  • 返回相对路径，如 000/001

示例

<?php
include './xiunophp/xiunophp.php';

// 获取分级目录路径
$path = xn_get_dir(123);
// 返回: 000/000

$path = xn_get_dir(1000);
// 返回: 000/001

// 获取已存储文件的路径
$id = 12345;
$subdir = xn_get_dir($id);
$filepath = './upload/' . $subdir . '/' . $id . '.jpg';

if (file_exists($filepath)) {
    // 文件存在
}

copy_recusive()

说明

function copy_recusive(string $src, string $dst): void

递归复制目录及其内容。

参数

  • $src：源目录路径
  • $dst：目标目录路径

返回值

  • 无

示例

<?php
include './xiunophp/xiunophp.php';

// 递归复制目录
copy_recusive('./template/default', './template/custom');

// 备份整个插件目录
copy_recusive('./plugin/myplugin', './backup/myplugin');

xn_shutdown_handle()

说明

function xn_shutdown_handle(): void

脚本结束时的回调函数。当前为空函数，可自定义扩展。

参数

  • 无

返回值

  • 无

示例

<?php
include './xiunophp/xiunophp.php';

// 注册关闭函数
register_shutdown_function('xn_shutdown_handle');

// 或自定义关闭处理
register_shutdown_function(function() {
    // 清理临时文件
    // 记录日志
    // 关闭资源
});

xn_debug_info()

说明

function xn_debug_info(): string

获取调试信息，包括执行时间、SQL 语句、请求参数等。

用途：仅在 DEBUG 模式下输出调试信息，用于开发调试。

参数

  • 无

返回值

  • 返回调试信息 HTML 字符串
  • 如果 DEBUG 级别小于 2，返回空字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 在页面底部输出调试信息
echo xn_debug_info();

// 调试信息包括：
// - 处理时间
// - 执行的 SQL 语句
// - $_REQUEST 内容
// - $_SESSION 内容

base64_decode_file_data()

说明

function base64_decode_file_data(string $data): string

解码 Base64 编码的文件数据，支持 Data URL 格式。

用途：用于处理前端通过 Canvas 或 FileReader 生成的 Base64 图片数据。

【推荐】上传文件时要用enctype="multipart/form-data"而不是enctype="application/x-www-form-urlencoded"然后把文件用base64编码后上传。

参数

  • $data：Base64 编码的数据，可包含 data:image/png;base64, 前缀

返回值

  • 返回解码后的原始二进制数据

示例

<?php
include './xiunophp/xiunophp.php';

// 处理前端上传的 Base64 图片
$base64Data = $_POST['image'];  // data:image/png;base64,iVBORw0KGgo...
$imageData = base64_decode_file_data($base64Data);

// 保存为文件
file_put_contents('./upload/avatar.png', $imageData);

// 或直接输出
header('Content-Type: image/png');
echo $imageData;

http_404()

说明

function http_404(): void

输出 404 错误页面并终止脚本。

参数

  • 无

返回值

  • 无，直接输出并退出

示例

<?php
include './xiunophp/xiunophp.php';

// 检查资源是否存在
$thread = thread_read($tid);
if (empty($thread)) {
    http_404();  // 输出 404 并退出
}

// 继续处理
echo "帖子内容...";

http_403()

说明

function http_403(): void

输出 403 禁止访问页面并终止脚本。

参数

  • 无

返回值

  • 无，直接输出并退出

示例

<?php
include './xiunophp/xiunophp.php';

// 检查用户权限
if (!$user['is_admin']) {
    http_403();  // 无权限，输出 403 并退出
}

// 继续处理管理员操作
echo "管理面板...";

http_location()

说明

function http_location(string $url): void

发送 HTTP 重定向头并终止脚本。

参数

  • $url：重定向目标 URL

返回值

  • 无，直接重定向并退出

示例

<?php
include './xiunophp/xiunophp.php';

// 登录成功后跳转
if ($login_success) {
    http_location('user-profile.htm');
}

// 跳转到外部链接
http_location('https://example.com');

http_referer()

说明

function http_referer(): string

获取安全的来源页面 URL。只返回站内 URL，防止开放重定向攻击。

此函数会过滤登录、登出、注册等页面，防止敏感操作后被重定向回这些页面。

参数

  • 无

返回值

  • 返回安全的来源 URL
  • 如果来源不安全或为空，返回 ./

示例

<?php
include './xiunophp/xiunophp.php';

// 获取来源页面
$referer = http_referer();

// 操作完成后跳回
echo '<a href="' . $referer . '">返回</a>';

// 或用于表单隐藏字段
echo '<input type="hidden" name="referer" value="' . $referer . '">';

str_push()

说明

function str_push(string $str, string $v, string $sep = '_'): string

向字符串追加值，使用分隔符连接。如果值已存在则不重复添加。

参数

  • $str：原字符串
  • $v：要追加的值
  • $sep：分隔符，默认为 _

返回值

  • 返回追加后的字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 追加标签
$tags = 'php';
$tags = str_push($tags, 'mysql');    // 返回: "php_mysql"
$tags = str_push($tags, 'php');      // 不重复，返回: "php_mysql"

// 使用其他分隔符
$list = '1,2,3';
$list = str_push($list, '4', ',');   // 返回: "1,2,3,4"

y2f()

说明

function y2f(float $rmb): int

将元转换为分（点券单位转换）。

用途：用于金额计算（两位小数定点数），避免浮点数精度问题。

参数

  • $rmb：金额（元）

返回值

  • 返回金额（分）

示例

<?php
include './xiunophp/xiunophp.php';

// 元转分
$fen = y2f(1.23);    // 返回: 123
$fen = y2f(100.00);  // 返回: 10000

// 用于金额计算
$price = y2f(19.99);  // 1999 分
$quantity = 3;
$total = $price * $quantity;  // 5997 分 = 59.97 元

f2y()

说明

function f2y(int $rmb, string $round = 'float'): float|int

将分转换为元（点券单位转换）。

用途：用于显示金额（两位小数定点数），将存储的分转换为用户友好的元。

参数

  • $rmb：金额（分）
  • $round：舍入方式，可选值：
    • float：返回浮点数（默认）
    • round：四舍五入
    • ceil：向上取整
    • floor：向下取整

返回值

  • 返回金额（元）

示例

<?php
include './xiunophp/xiunophp.php';

// 分转元
$yuan = f2y(123);        // 返回: 1.23
$yuan = f2y(10000);      // 返回: 100.00

// 不同的舍入方式
$yuan = f2y(123, 'float');  // 返回: 1.23
$yuan = f2y(123, 'round');  // 返回: 1
$yuan = f2y(123, 'ceil');   // 返回: 2
$yuan = f2y(123, 'floor');  // 返回: 1

array_to_sqladd()

说明

function array_to_sqladd(array $arr): string

将数组转换为 SQL UPDATE 语句的 SET 部分。

【已弃用】此函数在源码中已被注释掉。请使用db系列函数。

参数

  • $arr：关联数组，键为字段名，值为字段值

返回值

  • 返回 SQL SET 语句字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用预处理语句
$data = ['name' => 'John', 'age' => 30];
$pdo = new PDO('mysql:host=localhost;dbname=test', 'user', 'pass');
$stmt = $pdo->prepare('UPDATE users SET name = ?, age = ? WHERE id = ?');
$stmt->execute([$data['name'], $data['age'], 1]);

cond_to_sqladd()

说明

function cond_to_sqladd(array $cond): string

将条件数组转换为 SQL WHERE 语句。

【已弃用】此函数在源码中已被注释掉。请使用db系列函数。

参数

  • $cond：条件数组，键为字段名，值为条件值

返回值

  • 返回 SQL WHERE 语句字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用预处理语句
$cond = ['status' => 1, 'type' => 'post'];
$pdo = new PDO('mysql:host=localhost;dbname=test', 'user', 'pass');
$stmt = $pdo->prepare('SELECT * FROM content WHERE status = ? AND type = ?');
$stmt->execute([$cond['status'], $cond['type']]);

orderby_to_sqladd()

说明

function orderby_to_sqladd(array $orderby): string

将排序数组转换为 SQL ORDER BY 语句。

【已弃用】此函数在源码中已被注释掉。请使用db系列函数。

参数

  • $orderby：排序数组，键为字段名，值为排序方向（ASC 或 DESC）

返回值

  • 返回 SQL ORDER BY 语句字符串

示例

<?php
include './xiunophp/xiunophp.php';

// 推荐使用白名单验证排序字段
$allowedFields = ['id', 'create_time', 'views'];
$orderby = [];
foreach ($_GET['sort'] as $field => $direction) {
    if (in_array($field, $allowedFields)) {
        $orderby[$field] = strtoupper($direction) === 'DESC' ? 'DESC' : 'ASC';
    }
}

杂项函数第二部分

check_runlevel()

说明

function check_runlevel()

检测站点的运行级别，根据不同级别执行相应的限制。

参数

无

返回值

无

示例

// 在页面初始化时调用
check_runlevel();

xn_lock_start()

说明

function xn_lock_start($lockname = '', $life = 10)

创建文件锁，防止并发操作。

参数

  • $lockname：锁名称
  • $life：锁的生命周期（秒），超过此时间自动删除锁

返回值

  • 成功返回写入的字节数，失败返回 FALSE

示例

// 创建锁
if(xn_lock_start('update_thread', 5)) {
    // 执行需要锁定的操作
    // ...
    // 操作完成后删除锁
    xn_lock_end('update_thread');
} else {
    // 锁定失败，可能有其他进程正在执行
    message(1, '操作正在进行中，请稍后再试');
}

xn_lock_end()

说明

function xn_lock_end($lockname = '')

删除文件锁。

参数

  • $lockname：锁名称

返回值

无

示例

// 操作完成后删除锁
xn_lock_end('update_thread');

xn_html_safe()

说明

function xn_html_safe($doc, $arg = array())

过滤HTML内容，防止XSS攻击。

参数

  • $doc：HTML文档内容
  • $arg：配置参数数组，如 array('table_max_width' => 746)

返回值

  • 返回过滤后的安全HTML内容

示例

// 过滤用户输入的HTML
$safe_html = xn_html_safe($user_input);

// 自定义表格最大宽度
$safe_html = xn_html_safe($user_input, array('table_max_width' => 800));

杂项变量

$get_magic_quotes_gpc

说明

bool $get_magic_quotes_gpc = get_magic_quotes_gpc();

是否开启了magic quotes gpc。

【已弃用】请尽你最大努力避免使用。 get_magic_quotes_gpc()函数于PHP 8.0.0删除。如果你发现xiunophp.php中按以上签名定义了它的话，请及时替换成false，如：

$get_magic_quotes_gpc = false;

其附近还有:

version_compare(PHP_VERSION, '5.3.0', '<') AND set_magic_quotes_runtime(0);

也应一并删除。

其他使用的库

  • XML_HTMLSax3
    • 位置：./xiunophp/xn_html_safe.func.php
    • 用途：用于xn_html_safe函数处理HTML内容，防止XSS攻击。
    • 仓库：https://github.com/pear/XML_HTMLSax3
    • 许可证：未知
  • PHPMailer 5.2.1
    • 位置：./xiunophp/xn_send_mail.func.php
    • 用途：用于发送邮件。
    • 仓库：https://github.com/PHPMailer/PHPMailer
    • 许可证：LGPL
  • php_zip
    • 位置：./xiunophp/xn_zip_old.func.php
    • 用途：用于在PHP不支持ZipArchive扩展时，使用php_zip库压缩文件。
    • 仓库：无
    • 许可证：未知
    • 原作者写的备注：该类库收集于互联网，版权未知，由 axiuno@gmail.com 修正了部分64位下的 bug, 如果谁知道请麻烦告知作者。
上传的附件：
收藏的用户（0） X
正在加载信息~
相关帖子
最新回复 (0)
全部楼主
返回
Tillreetree
版主
177
主题数 		1425
帖子数
  作者最近主题   
  Xiuno BBS 数据库表结构详解
   【在线阅读】Xiuno PHP 4.0开发手册 清扫版本 - 在Xiuno BBS中新定义的全局变量与函数
   【在线阅读】Xiuno PHP 4.0开发手册 清扫版本
   【开发必备】Xiuno PHP 4.0 开发手册清扫版发布 — 从此写代码不用猜函数用法了
   Retro - 如果Xiuno BBS是在1986年开发的 - 更加复古风味的主题，兼具可用性
扫码访问