Download the PHP package bestyii/yii2-tabler without Composer

bestyii/yii2-tabler

bestyii/yii2-tabler 是一个面向 Yii2 后台、运营平台和数据管理界面的 Tabler 组件包。 它不是单纯的 CSS 主题封装，而是把 Tabler 的视觉语言、常见后台部件和前端插件整合成可复用的 Yii2 Widget 与 Asset Bundle。 从产品目标上，它不应只是一个“Tabler 版补充包”，而应逐步成为 yiisoft/yii2-bootstrap5 的上位替代：既覆盖 Bootstrap 常用能力，也提供更丰富的后台组件和更优的视觉表达。

产品定位

这个包解决的是 Yii2 后台项目里最常见的三个问题：

1. 设计系统已经选定 Tabler，但团队不希望在视图里手写大量碎片化 HTML。
2. 项目需要的不只是按钮、弹窗、导航，还包括图表、地图、富文本、拖拽上传、分段导航、状态指示、时间线、运营型表格等后台高频组件。
3. 团队希望把前端插件接入、资源发布、组件文档和测试门禁，统一收敛在包级别，而不是散落在每个业务应用里。

因此，bestyii/yii2-tabler 的目标不是替代 Yii2 本身，而是为 Yii2 提供一层偏产品化、偏后台场景的 Tabler 组件基座，并逐步补齐 yii2-bootstrap5 已有的核心能力。

当前交付面

基于当前仓库快照，这个包已经提供：

• 62 个顶层类，覆盖 Bootstrap 常用组件、Tabler 后台组件和表单基座。
• 31 个 Asset Bundle，用于统一管理 Tabler 及其配套前端依赖。
• 59 篇组件文档，位于 docs/components。
• 包级 phpunit、phpstan、ecs 三条质量门禁。

代表性组件包括：

• Bootstrap 核心层：ActiveForm、ActiveField、Breadcrumbs、ButtonDropdown、ButtonToolbar、LinkPager、NavBar、Popover、ToggleButtonGroup
• 基础界面：Button、Alert、Badge、Card、Modal、Offcanvas、Tabs、Toast
• 导航与页头：Nav、Dropdown、DropdownMenu、PageHeader、Pagination、NavSegmented
• 状态与运营表达：Status、StatusDot、StatusIndicator、Ribbon、Steps、Timeline、Tracking、Trending
• 内容与后台块：Avatar、AvatarList、EmptyState、Payment、Tag
• 数据与交互：Table、AdvancedTable、Range、Rating
• 插件型组件：Chart、Datepicker、Dropzone、Fullcalendar、Select、Signature、Typed、VectorMap、Wysiwyg

适合什么项目

适合：

• SaaS 后台
• CRM / ERP / OA
• 数据分析与运营平台
• 需要较强视觉完成度的内部管理系统
• 已经采用 Tabler 作为统一视觉系统的 Yii2 项目

不适合：

• 只需要最基础 Bootstrap 组件的轻量页面
• 主要面向营销落地页而非后台工作台的项目
• 必须严格沿用 yiisoft/yii2-bootstrap5 既有命名、示例和资源层约定，不接受迁移适配的项目

和应用的边界

这个包当前聚焦在“组件层”和“资源层”：

• 提供 Widget、Asset Bundle、组件文档和测试
• 不内置应用级模块、站点路由或布局系统
• 不伪装成完整后台脚手架

也就是说，它更像一个可持续维护的 UI 组件包，而不是一个整站模板。

安装

当前要求：

• PHP 8.2 - 8.4
• Yii2 ~2.0.32

官方支持策略和兼容承诺见 docs/support-policy.md。

快速开始

1. 渲染一个按钮

2. 渲染一个标准页头

对于高频场景，组件现在提供了更易写的静态 helper，例如 Badge::secondary('Draft')、Button::primary('Save')、Alert::success('Done')、Progress::success(72, label: '72%')。底层的 ::widget([...]) API 仍然保留，适合更完整的配置数组。

如果颜色或类型是在业务代码里动态算出来的，可以进一步使用类型化的 make()：

当前已支持语法糖的组件和预设范围如下：

• Badge：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Button：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Alert：primary、secondary、success、info、warning、danger
• Progress：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Tag：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Status：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• StatusDot：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• StatusIndicator：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Ribbon：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Spinner：border、grow
• ButtonDropdown：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Offcanvas：left、right、top、bottom
• Popover：auto、top、bottom、left、right

3. 渲染一个后台表格卡片

组件契约

为了让组件在复杂后台页面里可长期维护，这个包现在遵循一套统一内容契约：

• 文本属性默认安全。像 title、label、subtitle 这类字段，默认按文本处理。
• 原始 HTML 要显式表达。新代码优先使用 contentHtml、headerHtml、footerHtml 这类命名，而不是模糊地把 HTML 放进普通字符串属性。
• 列表和表格用 format 明确语义。Table 与 AdvancedTable 的列配置优先使用 format => Table::FORMAT_TEXT|FORMAT_HTML，旧的 encode 仅作为兼容桥保留。
• 缓冲式 begin()/end() 输出视为 HTML 插槽，因为这类用法本身就是为了拼接 widget 或标记。

详细约定见 docs/component-contracts.md。

资源策略

bestyii/yii2-tabler 采用的是“组件 + 资源包”双层模型：

• TablerAsset 负责注册 Tabler 核心样式与脚本
• 插件组件各自依赖对应 Asset Bundle，例如 ApexChartsAsset、DropzoneAsset、FullcalendarAsset
• 包内统一处理资源路径、发布行为和依赖声明，业务应用只关心 Widget 调用

扩展资源现在按最小边界拆分：

• Flag 会自动注册 TablerFlagsAsset
• Payment 会自动注册 TablerPaymentsAsset
• 如果你直接在页面里使用原始 Tabler 扩展 class，而不是通过 widget 输出，请显式注册对应资源包：
  • TablerSocialsAsset
  • TablerMarketingAsset
  • TablerThemeAsset

例如：

如果主题切换器是应用级能力，而不是单个 widget 的局部交互，优先在 layout 里注册 TablerThemeAsset；像社交图标这类页面级 class，则只在实际使用该 class 的视图里注册对应资源。

TablerExtrasAsset 仍然保留为兼容聚合包，但新代码应优先注册最小匹配的资源，而不是一次性加载全部 extras。

这让项目可以在保留 Yii2 视图体系的同时，把前端插件接入成本控制在组件包内部。

产品目标

从长期方向看，bestyii/yii2-tabler 应该满足两层目标：

• 第一层，用 Tabler 风格完整承接 yii2-bootstrap5 的核心用户态组件能力。当前这一层已经覆盖到 ActiveForm、ActiveField、NavBar、ButtonDropdown、ButtonToolbar、LinkPager、Popover、ToggleButtonGroup 等高频部件。
• 第二层，在此基础上继续提供 Card、PageHeader、AdvancedTable、Chart、Dropzone、VectorMap、Wysiwyg 等更偏后台产品场景的组件。

换句话说，yii2-tabler 的定位不是“和 yii2-bootstrap5 做功能切分”，而是“以 Tabler 风格重做并扩展 Yii2 的 Bootstrap 组件层”。

稳定性与兼容原则

• 包的官方支持线是 PHP 8.2 - 8.4，面向现代 Yii2 团队，而不是极旧环境。
• 与 yii2-bootstrap5 高度同构的组件优先追求稳定和一致性，不做为了“更优雅”而引入的新概念拆分。
• 更强的内容契约、资产归属和后台产品能力，优先落在 Card、AdvancedTable、Popover 这类产品层组件里。

详细规则见 docs/support-policy.md。

质量与可维护性

当前包级交付标准包括：

• 组件文档与源码同仓维护
• PHPUnit 验证渲染结果与资产发布
• PHPUnit 覆盖率配置已启用，CI 会在单独的 coverage job 里产出 runtime/coverage 报告工件
• PHPStan 验证静态分析
• ECS 保持代码风格一致

本地常用命令：

说明：

• composer tests 默认带 --no-coverage，用于日常快速回归。
• composer coverage 需要 pcov 或 Xdebug 覆盖率驱动；如果使用 Xdebug，请显式带上 XDEBUG_MODE=coverage。
• 覆盖率报告会写入 runtime/coverage/，其中包含 clover.xml、cobertura.xml 和 HTML 报告。

最近一次补强还加入了 Asset Bundle 一致性测试，用于直接检查：

• sourcePath 是否有效
• 本地资源文件是否真实存在
• 资源是否能被 Yii 的 AssetManager 正常发布

这类测试的目的，是避免“组件渲染测试通过，但前端资源实际上不可发布”的隐性回归。

文档入口

• 包级文档索引：docs/index.md
• 支持策略：docs/support-policy.md
• Bootstrap parity policy：docs/parity-policy.md
• 1.0 roadmap：docs/roadmap-1.0.md
• 组件契约：docs/component-contracts.md
• 组件文档目录：docs/components
• 选型参考：docs/compare-with-yii2-bootstrap5.md
• 贡献说明：CONTRIBUTING.md
• 安全说明：SECURITY.md

选型结论

从产品方向上，bestyii/yii2-tabler 应该是 yiisoft/yii2-bootstrap5 的超集，而不是平行替代。

当前如果你的项目目标是“用 Tabler 风格统一后台界面，并把 Bootstrap 常用基础能力也收进同一个组件层”，bestyii/yii2-tabler 已经可以作为主包承接。更细的覆盖矩阵与选型参考，见 docs/compare-with-yii2-bootstrap5.md。