# TailwindPHP

TailwindPHP 是 **1:1 移植版：将 TailwindCSS 4.x 移植到 PHP**。它会解析你的 CSS，扫描标记中的类名，并生成 TailwindCSS v4.3.3 所生成的工具 CSS——完全使用 PHP，无需 Node.js，也无需构建步骤。

- **纯 PHP** — 以 Composer 包的形式发布，可在 PHP 8.2+ 上运行，使用标准的 `ctype` 和 `mbstring` 扩展。无需 `exec`、FFI 或本机构建工具。
- **通过 TailwindCSS 验证** — 工具、变体、指令和 CSS 函数均与 TailwindCSS v4.3.3 保持同步。输出会根据 Tailwind 自带的测试套件进行验证；测试套件从 TypeScript 源码中提取，并在每次推送时重新运行（4,400+ 项测试）。已知差异（少数不会影响级联的序列化细节，以及未解决的问题）列于[兼容性与升级](https://tailwindphp.inline0.dev/zh/docs/advanced/compatibility)。
- **完整功能集** — 完整的 TailwindCSS v4.3.3 工具集（包括 `container`、滚动条工具、`zoom-*` 和 `tab-*`）、所有变体（悬停、焦点、响应式、暗色模式、容器查询、任意值），以及完整的指令集：`@import`、`@theme`、`@apply`、`@utility`、`@variant`、`@custom-variant`、`@layer`、`@plugin` 和 `@source`。
- **开箱即用** — `cn()`、`merge()`、`join()` 和 `variants()` 打包了 clsx、PHP、tailwind-merge 和 CVA 的移植版本，因此每个 Tailwind 项目都会用到的配套库都已内置。
- **插件** — `@tailwindcss/typography` 和 `@tailwindcss/forms` 已完整移植，且提供 PHP 插件 API，让你可以编写自己的插件。

## TailwindPHP为何存在

TailwindCSS 使用 TypeScript 编写，可在 Node.js 上运行。对于任何想要使用 Tailwind 的 PHP 项目来说，这都是硬性要求：需要第二个运行时、安装 npm，并在 CI 和 Docker 中加入构建步骤。许多 PHP 应用都不愿承担这些额外负担。

TailwindPHP 消除了这些负担。你的 PHP 代码可以直接编译为 Tailwind CSS，只使用标准库。这让一些在 JavaScript 工具链中难以实现或无法实现的事情成为可能：

- **WordPress 和 PHP 框架** — 发布由 Tailwind 驱动的主题和插件，无需让用户安装 Node.js 或运行构建。只需 `composer require` 即可开始使用。请参阅 [TailwindWP](https://github.com/dnnsjsk/tailwindwp)，这是一个示例 WordPress 插件，可使用 TailwindPHP 生成区块编辑器 CSS。
- **运行时 CSS** — 根据用户输入、数据库内容或模板变量即时生成工具 CSS，而不是在构建时生成。
- **简化部署** — 生产环境无需 Node.js，CI 无需构建步骤，Docker 镜像中也无需 npm。

这正是 [scssphp](https://github.com/scssphp/scssphp) 为 SCSS 带来的理念——在 PHP 中运行完整编译器。

## 功能说明

- 根据内容中找到的类名编译 TailwindCSS v4.3.3 工具集、变体和任意值。
- 解析完整的指令集：`@import`（包括 `tailwindcss` 和 `tailwindcss/utilities` 等虚拟模块，以及 `reference` 导入）、`@theme`、`@apply`、`@utility`、`@variant`、`@custom-variant`、`@layer`、`@plugin` 和 `@source`。
- 实现 Tailwind 的 CSS 函数——`theme()`、`--theme()`、`--spacing()` 和 `--alpha()`——以及 `color-mix()` → `oklab()` 转换，并支持 TailwindCSS 委托给 LightningCSS 的 CSS 转换。
- 从文件系统解析 `@import`，支持嵌套导入、去重和自定义解析器；也可从内联 CSS 字符串解析。
- 内置 Preflight（Tailwind 的基础重置样式）、前缀支持、`@property` 回退、供应商前缀以及关键帧提升。
- 打包 `cn()`、`merge()`、`join()` 和 `variants()`/`compose()`，用于构建类名、解决冲突和定义组件变体。
- 包含排版和表单插件，以及用于自定义插件的插件 API（`addUtilities`、`matchUtilities`、`addComponents`、`addVariant`、`theme`、…）。
- 提供带有 `@tailwindcss/cli` 构建选项的 CLI（`bin/tailwindphp`），以及基于文件的输出缓存、持久编译器状态缓存和用于生产环境的 CSS 压缩器。

## 它不是什么

TailwindPHP 是一个 CSS 编译器，而不是编辑器工具链。它有意省略了 Tailwind 生态系统中面向 IDE 的部分——IntelliSense、自动补全、类名排序和源映射——因为这些属于编辑器功能，而非 CSS 生成的一部分。所有用于生成 CSS 的内容都在支持范围内；驱动编辑器的功能则不在其中。

## 从这里开始

- [入门](https://tailwindphp.inline0.dev/zh/docs/getting-started) — 安装软件包并生成你的第一个样式表。
- [用法](https://tailwindphp.inline0.dev/zh/docs/usage) — 扫描内容、自定义主题并使用 Tailwind 的指令。
- [类工具](https://tailwindphp.inline0.dev/zh/docs/class-utilities) — `cn()`、`merge()`、`join()` 和 `variants()`。
- [插件](https://tailwindphp.inline0.dev/zh/docs/plugins) — 排版、表单以及编写自己的插件。
- [API](https://tailwindphp.inline0.dev/zh/docs/api) — 完整的 `tw` 指令集和 `TailwindCompiler` 实例。
- [CLI](https://tailwindphp.inline0.dev/zh/docs/cli) — 用于基于文件的构建和监视模式的 `bin/tailwindphp`。
- [进阶](https://tailwindphp.inline0.dev/zh/docs/advanced) — 架构、缓存、性能和兼容性说明。