naisi_file_signature

最多读取受控文件头部 4 字节并识别格式代码；不受文件总大小限制，$extension 仅作为辅助信息。

函数签名

function naisi_file_signature(string $file_name, string $extension = ''): string|false

调用前提

应用入口先调用 naisi_is_ext_license_valid 并确认返回 true。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：LOCAL_FILE_METADATA；执行模式：PROOF。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

参数

$file_name

• 类型：string
• 必填：是
• 默认值：无
• 方向：输入参数。

许可授权目录或当前环境临时目录内的绝对普通文件路径；拒绝相对路径以及 .、.. 路径段。函数最多读取头部 4 字节，不受文件总大小限制。

$extension

• 类型：string
• 必填：否
• 默认值：''
• 方向：输入参数。

文件扩展名提示，仅用于辅助识别文件格式，不能替代内容检查。

返回值

类型：string|false

成功时返回根据头部最多 4 字节和扩展名提示生成的格式代码；文件不存在、不是普通文件、路径越界、头部不足或读取失败时返回 false。

调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

// $file_name 为已存在、位于许可授权目录或系统临时目录的普通文件。
// 示例文件内容为 Hello Naisi（至少四字节）。
$file_name = sys_get_temp_dir() . '/naisi-doc-example.txt';
$extension = 'txt';
$result = naisi_file_signature($file_name, $extension);
var_export($result);

固定返回值与格式

• JPEG 文件头 FF D8：返回 255216。
• PNG 文件头 89 50：返回 13780。
• GIF 文件头 47 49：返回 7173。
• 前 4 字节均为可打印文本，且扩展名为 key、md、js、html、css 或 txt：返回对应的小写扩展名。
• 其他至少有 4 字节的文件：返回前 4 字节逐字节转换并拼接的小写十六进制文本。
• 文件不足 2 字节、路径或文件无效、读取失败时返回 false。

版本信息

• 自版本：1.0.6
• 实现模块：filesystem
• 授权类别：LOCAL_FILE_METADATA / PROOF
• 失败回退：false
• 文档同步：2026-10-18