us-tariff-lookup PHP 包 Composer 教程
Invoice × Tariff 编辑部
适用对象要把离线 HTS 查询与关税变动追踪接进 Laravel/Symfony 应用、CLI 和内部工具的 PHP 开发者。
composer require invoicetariff/us-tariff-lookup 即可安装——零依赖 PHP 7.4+ 包,版本化规则快照随包内置。TariffLookup::search() 做英文/中文 HTS 搜索,TariffLookup::meta() 报快照版本,TariffLookup::changelog() 给机器可读规则变更。完全离线、MIT 许可;v1 只含查询面——落地成本计算在 npm 包与网页计算器里。
这个包是什么
invoicetariff/us-tariff-lookup 是驱动本站计算器与 npm 包的同一份版本化快照的 PHP(Composer/Packagist)形态:数据随包内置、零依赖、无需 API Key、无网络请求。一切都在一个静态门面 InvoiceTariff\UsTariffLookup\TariffLookup 背后——没有配置项、没有要装配的服务。每个答案对固定的 release 都是确定的——每条结果都带 rulesetVersion 与 dataAsOf 日期。
MIT 许可。v1 提供查询面:HTS 搜索、规则集 meta 与机器可读变更日志。叠加落地成本计算有意不在这个包里——文末详述。
安装
需要 PHP 7.4 或更新版本,外加几乎无处不在的 ext-json——依赖清单到此为止。
composer require invoicetariff/us-tariff-lookup
没有 Composer?克隆(或下载)仓库直接用——没有东西需要安装:本库没有 vendor 依赖,直接引 src/TariffLookup.php 就能跑。composer install 只是为了把 us-tariff 命令行工具暴露到 PATH。
第一个程序:meta、search、changelog
一个脚本跑完整套 API 面:
<?php
require 'vendor/autoload.php';
use InvoiceTariff\UsTariffLookup\TariffLookup;
// 你手里是哪份快照——展示任何数字时都把这两个字段带上。
$meta = TariffLookup::meta();
echo $meta['rulesetVersion'], ' ', $meta['dataAsOf'], PHP_EOL; // 0.3.4 2026-10-07(每月重建)
// HTS 搜索:编码前缀、英文描述或中文关键词。
// 多词查询按 AND 分词;matchedBy 告诉你命中的是哪个面。
foreach (TariffLookup::search('cotton t-shirt', 5) as $hit) {
echo $hit['entry']['hts8'], ' ', $hit['entry']['general'], ' (', $hit['matchedBy'], ')', PHP_EOL;
// 61091000 16.5% (en)
}
// 规则变更,日期从新到旧(published + upcoming + historical)。
foreach (array_slice(TariffLookup::changelog(), 0, 5) as $e) {
echo $e['date'], ' ', $e['layer'], ' ', $e['status'], ' ', $e['titleEn'], PHP_EOL;
}
第一行搜索就是黄金测试用例:cotton t-shirt 命中 HTS 61091000,带官方 USITC 普通税率。中文同理——TariffLookup::search('保温杯', 5) 通过内置的中文描述与关键词找到保温杯条目(96170010,10%),matchedBy 返回 "zh"。包自带的 tests/GoldenTest.php 把两个用例都钉死了,保证每个 release 与 npm、Go、PyPI 发行版保持一致。
CLI:三条命令
包自带零依赖 CLI,接流水线、定时任务和 LLM 工具都方便:
php bin/us-tariff meta # 包里有什么 / 当前数据版本
php bin/us-tariff search "steel screws" # EN / 中文 / 编码前缀,可带条数
php bin/us-tariff search 保温杯 20
php bin/us-tariff changelog 5 # 近期规则变更,新的在前
checkout 直跑即可——不需要 composer install。所有命令输出 JSON,信封含 rulesetVersion、dataAsOf 与 disclaimer,载荷在 result 下——可以直接接 jq。
读懂结果字段
搜索命中 = 精选 MFN 条目 + 命中面:
$hit['entry']['hts8']/['description']/['descriptionZh']——8 位编码与双语描述。$hit['entry']['general']——官方 USITC 第一栏普通税率,形如"16.5%"的字符串。$hit['matchedBy']——"code"、"en"或"zh"。多词查询的每个词都必须命中同一个面(全部落在编码里、全部落在英文描述里、或全部落在中文里);matchedBy告诉你哪个面命中。查询保持单语言——"cotton 保温杯"这种混语言查询不会有命中,因为没有任何一个面同时含两个词。$hit['entry']['sample']——为true表示该税率行尚未逐行对照 Federal Register 原文核实:规划级,不是核定的报关数据。- 结果按快照的精选顺序返回,不是相关性打分;
$limit <= 0回落为 10,空查询返回空数组。
变更条目是关联数组,带 date、layer、status("published" = 已生效、"upcoming" = 未来生效、"historical" = 已被接替、供退税查询保留的历史层)、titleEn/ title、summaryEn/ summary,以及含 Federal Register 文号的 affectedHts、changes 与 sources。changelog(null) 返回全部;传 int 截断条数。
错误处理与限频——如实盘点
设计上几乎无需处理:
- 无网络,因此没有超时、没有重试、没有限频、没有 API Key。 JSON 每进程从包内文件解析一次;查询方法都是纯函数。CI、内网隔离环境、常驻 worker 池都能放心用。
- 唯一会抛的异常是捆绑数据文件不可读或损坏时的
RuntimeException——数据随 release 一起分发,实际不会发生。 - 真正的风险是版本漂移,不是失败。 在
composer.json里钉住版本约束(裸composer require解析最新 release;放开跑composer update会让你的数字在两次构建之间变动)。每个结果都回显TariffLookup::meta()的rulesetVersion/dataAsOf,并把TariffLookup::DISCLAIMER常量透传给终端用户。
保持数据新鲜
规则快照每月重建(重大政策落地时临时加更),来源是开放的税率数据仓;本包随每份快照重新发版——用 composer update invoicetariff/us-tariff-lookup 升级。版本之间动了什么,读 TariffLookup::changelog()(或 php bin/us-tariff changelog)。带新旧值的实时 feed 在关税雷达,附 RSS,方便你自动化响应。
包内规则快照一览
下表数字对应当前 release(快照 v0.3.4,截至 2026-10-07)——跑一下 TariffLookup::meta() 看你自己构建里的值:
| 数据面 | 数量 | 说明 |
|---|---|---|
| 精选 MFN 编码 | 484 | 高频 HTS 8 位码,带官方 USITC 普通税率(英文+中文) |
| 对华 Section 301 行 | 25 | 清单 2/3/4A + 2026 四年复审新增 |
| 全球 301 档位 | 60 | 2026 全球 Section 301 计划档位 |
| Section 232 措施 | 8 | 钢铝 / 铜 / 汽车 / 家具 / 药品 / 半导体 / 木材 |
| 变更条目 | 57 | published + upcoming + historical,每条带官方来源 |
需要包没有建模的层?TariffLookup::rulesetSeedRaw() 与 TariffLookup::changelogRaw() 以字符串返回完整的内置 JSON(规费表、232 措施、IEEPA 历史、逐条来源 URL),json_decode() 之后自行处理。内置搜索覆盖精选高频码,不是全部 5,689 条 HTS——全量表在 hs-codes-database 仓与 HTS 搜索页。
v1 没有落地成本计算——请用 npm 包或网页计算器
这个包有意只做查询面。叠加税层、从量/复合税率、MPF/HMF 规费与单件落地成本在 us-tariff-lookup npm 包(同一快照,TypeScript,Node 可用)和本站关税计算器里——后者完全不用写代码。混合技术栈的常见组合拳:PHP 侧查码、追规则变动,再用 npm 包按同一 rulesetVersion 给这条线计价,两边逐位一致。
常见问题
- PHP 包能像 npm 包那样算落地成本吗?
- v1 不能。invoicetariff/us-tariff-lookup 只提供查询面——HTS 搜索、规则集 meta 与变更日志。叠加计算(MFN + 301 + 232 + MPF/HMF、单件落地成本)在 us-tariff-lookup npm 包与网页计算器里,跑的是同一份快照,可以对齐同一个 rulesetVersion 搭配使用。
- 需要哪个 PHP 版本?要装什么扩展?
- PHP 7.4 或更新版本,加 ext-json——几乎所有 PHP 构建都默认启用。没有其他扩展要求、没有 vendor 依赖:虚拟主机、Docker 镜像、Laravel/Symfony 应用、甚至不装 Composer 的裸 checkout 都能跑。
- 它会调 API 吗?需要 API Key 吗?
- 都不需要。规则 JSON 随包内置,零依赖,运行期不碰网络。因此没有密钥、没有配额、没有超时——CI、内网隔离环境、serverless 函数都能用。
- 在 Laravel 或 Symfony 里怎么用?
- 它是纯 PSR-4 库(InvoiceTariff\UsTariffLookup\TariffLookup),全静态方法,Composer autoload 之后控制器、队列任务、Artisan/Console 命令里随处可用,不需要写 service provider。想要依赖注入的话,包一层单类 service 转发到静态门面即可——顺带也留出了按 release 缓存 meta() 输出的口子。
- 数据有多新?怎么更新?
- 快照每月从开放的 us-tariff-rates-2026 数据仓重建,包随每份快照重新发版。跑 TariffLookup::meta()(或 php bin/us-tariff meta)看你内置的版本与 data-as-of 日期,然后 composer update invoicetariff/us-tariff-lookup 升级。TariffLookup::changelog() 列出变动内容。
- search() 为什么找不到我的产品?
- 内置搜索覆盖精选高频码(当前 release 484 条),不是全部 5,689 条 HTS 8 位码——全量表在 hs-codes-database 仓或 HTS 搜索页。另外查询要保持单语言:每个词都必须命中同一个面(编码、英文描述或中文),混语言的 "cotton 保温杯" 不会有命中。包没解析的税层,用 rulesetSeedRaw() 拿完整 JSON 自己解析。
MIT 许可、PHP 7.4+、零依赖。源码仓、发布版本与姊妹 npm / Go 包都见开源项目页。