# `naisi_file_cache_write`

使用原子临时文件替换方式写入 DATA 或 RAW 文件缓存。

## 函数签名

```php
function naisi_file_cache_write(string $cache_path, mixed $data, int $ttl = 0, int $type = NAISI_FILE_CACHE_DATA): bool
```

## 调用前提

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

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

## 参数

### `$cache_path`

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

由 naisi_file_cache_path() 生成的完整缓存路径；拒绝其他路径格式。

### `$data`

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

DATA 支持 null、布尔、整数、浮点、二进制字符串、list 和关联数组；RAW 只接受字符串。

### `$ttl`

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

DATA 缓存有效秒数；0 表示永不过期，负数非法。RAW 只允许 0。

### `$type`

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

NAISI_FILE_CACHE_DATA 或 NAISI_FILE_CACHE_RAW；默认写入带完整性校验和轻量二进制扰码的 DATA。

## 返回值

类型：`bool`

同一请求已建立许可路径策略，且目录创建、完整写入、刷新和原子替换全部成功时返回 true；类型、TTL、路径、授权、序列化或文件操作失败时返回 false。

## 关联常量

- [`NAISI_FILE_CACHE_DATA`](/web/developers/naisilib/const#naisi-file-cache-data) = `0` — 普通数据文件缓存类型。 写入 Naisi 序列化数据、固定 Header、CRC32 和轻量二进制扰码；读取时自动校验并反序列化。
- [`NAISI_FILE_CACHE_RAW`](/web/developers/naisilib/const#naisi-file-cache-raw) = `1` — 原始文件缓存类型。 只接受字符串和零 TTL，按原始字节写入，不增加 Header、序列化、CRC 或扰码。

## 调用示例

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

```php
$cache_path = 'C:/WINDOWS/TEMP/naisi_fun_test/4O/LX0Y4LfjeiUGz9tL9j1S.dat';
$data = 'Hello Naisi';
$ttl = 0;
$type = 0;

$result = naisi_file_cache_write($cache_path, $data, $ttl, $type);
var_dump($result);
```

## 版本信息

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