# `naisi_file_signature`

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

## 函数签名

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

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/naisi-is-ext-license-valid) 并确认返回 `true`。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

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

## 参数

### `$file_name`

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

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

### `$extension`

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

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

## 返回值

类型：`string|false`

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

## 调用示例

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

```php
// $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`