us-tariff-lookup PHP Composer Tutorial

Invoice × Tariff editorial

Who this is forPHP developers embedding offline HTS lookup and tariff-change tracking into Laravel/Symfony apps, CLIs and internal tools.

Install with composer require invoicetariff/us-tariff-lookup — a zero-dependency PHP 7.4+ package with the versioned ruleset bundled. Call TariffLookup::search() for English/Chinese HTS search, TariffLookup::meta() for the snapshot version, and TariffLookup::changelog() for machine-readable rule changes. Fully offline, MIT licensed; v1 is query-only — landed-cost math lives in the npm package and the web calculator.

What the package is

invoicetariff/us-tariff-lookup is the PHP (Composer/Packagist) distribution of the same versioned snapshot that powers this site's calculators and the npm package: data bundled in the package, zero dependencies, no API key, no network calls. Require it with Composer and every answer is deterministic against a pinned release — each one carries a rulesetVersion and a dataAsOf date.

Everything lives behind one static facade, InvoiceTariff\UsTariffLookup\TariffLookup, so there is nothing to configure and no services to wire up. MIT licensed. v1 ships the query surface: HTS search, ruleset meta and a machine-readable changelog. The stacked landed-cost calculation is intentionally not in this package — more on that at the end.

Install

Requires PHP 7.4 or newer with the ubiquitous ext-json — that's the whole dependency list.

composer require invoicetariff/us-tariff-lookup

No Composer in the picture? Clone (or download) the repo and use it directly — there is nothing to install: the library has no vendor dependencies, so including src/TariffLookup.php straight away works. composer install is only needed to expose the us-tariff bin on your PATH.

Your first program: meta, search, changelog

One script that touches the whole API surface:

<?php
require 'vendor/autoload.php';

use InvoiceTariff\UsTariffLookup\TariffLookup;

// Which snapshot you have — surface these two fields next to any number you show.
$meta = TariffLookup::meta();
echo $meta['rulesetVersion'], ' ', $meta['dataAsOf'], PHP_EOL; // 0.3.4 2026-10-07 (monthly rebuilds)

// HTS search: code prefix, English description or Chinese keyword.
// Multi-word queries are AND-tokenized; matchedBy says which surface matched.
foreach (TariffLookup::search('cotton t-shirt', 5) as $hit) {
    echo $hit['entry']['hts8'], ' ', $hit['entry']['general'], ' (', $hit['matchedBy'], ')', PHP_EOL;
    // 61091000 16.5% (en)
}

// Rule changes, newest first (published + upcoming + historical).
foreach (array_slice(TariffLookup::changelog(), 0, 5) as $e) {
    echo $e['date'], ' ', $e['layer'], ' ', $e['status'], ' ', $e['titleEn'], PHP_EOL;
}

That first search line is the golden test case: cotton t-shirt lands on HTS 61091000 with its official USITC general rate. Chinese works the same way — TariffLookup::search('保温杯', 5) finds the insulated-bottle line (96170010, 10%) through the bundled 中文 descriptions and keywords, with matchedBy reporting "zh". The package's own tests/GoldenTest.php pins both cases so every release stays aligned with the npm, Go and PyPI distributions.

The CLI: three commands

The package ships a zero-dependency CLI, handy for pipelines, cron jobs and LLM tooling:

php bin/us-tariff meta                    # what's inside / which data version
php bin/us-tariff search "steel screws"   # EN / 中文 / code prefix, optional limit
php bin/us-tariff search 保温杯 20
php bin/us-tariff changelog 5             # recent rule changes, newest first

It runs straight from a repo checkout — no composer install needed. Every command prints JSON with an envelope of rulesetVersion, dataAsOf and disclaimer, plus the payload under result — pipe it straight into jq.

Reading the results

Search hits pair a curated MFN entry with the surface that matched:

  • $hit['entry']['hts8'] / ['description'] / ['descriptionZh'] — the 8-digit code and both descriptions.
  • $hit['entry']['general'] — the official USITC Column 1 general rate, as a string like "16.5%".
  • $hit['matchedBy'] — "code", "en" or "zh". Every token of a multi-word query must match on the same surface (all-in-the-code, all-in-the-English-description, or all-in-the-中文); matchedBy tells you which one won. Keep queries single-language — "cotton 保温杯" matches nothing because no single surface contains both tokens.
  • $hit['entry']['sample'] — true means the rate line is not yet verified line-by-line against the Federal Register text: planning-grade, not certified entry data.
  • Results keep the snapshot's curation order, not a relevance score; $limit <= 0 falls back to 10 and an empty query returns an empty array.

Changelog entries are associative arrays with date, layer, status ("published" = in force, "upcoming" = future effective date, "historical" = superseded layer kept for refund lookups), titleEn/ title, summaryEn/ summary, plus affectedHts, changes and sources with the Federal Register citations. changelog(null) returns everything; pass an int to cap it.

Error handling and rate limits — the honest inventory

There is almost nothing to handle, by design:

  • No network, so no timeouts, no retries, no rate limits, no API keys. The JSON is parsed once per process from files inside the package; the query methods are pure. Safe in CI, air-gapped deployments and long-running worker pools.
  • The one exception it can throw is a RuntimeException if a bundled data file is unreadable or corrupt — which in practice never happens, because the data ships inside the release.
  • The one real risk is version drift, not failure. Pin the constraint in composer.json (a plain composer require resolves the latest release; a floating composer update can move your numbers between builds). Echo TariffLookup::meta()'s rulesetVersion/dataAsOf with every result, and pass the TariffLookup::DISCLAIMER constant to your end users.

Keep the data fresh

The snapshot is rebuilt monthly (and ad-hoc when major actions land) from the open rates repo, and this package is re-released with each snapshot — move up with composer update invoicetariff/us-tariff-lookup. To see what moved between versions, read TariffLookup::changelog() (or php bin/us-tariff changelog). The live feed with old → new values is the Tariff Radar, with an RSS feed if you want to automate reactions.

What's inside the bundled snapshot

Counts below are for the current release (snapshot v0.3.4, as of 2026-10-07) — run TariffLookup::meta() to see them for your own build:

Surface Count Notes
Curated MFN codes 484 High-frequency HTS 8-digit codes with official USITC general rates (EN + 中文)
China Section 301 lines 25 Lists 2/3/4A + 2026 four-year-review additions
Global 301 tiers 60 The 2026 global Section 301 program tiers
Section 232 measures 8 steel / aluminium / copper / autos / furniture / pharma / semiconductors / timber
Changelog entries 57 published + upcoming + historical, each sourced officially

Need layers the package does not model? TariffLookup::rulesetSeedRaw() and TariffLookup::changelogRaw() return the full bundled JSON as strings (fees, 232 measures, IEEPA history, per-entry source URLs) — json_decode() them and take it from there. The bundled search covers curated high-frequency codes, not the full 5,689-line HTS — the complete table lives in the hs-codes-database repo and on the HTS search page.

No landed-cost math in v1 — use the npm package or the web calculator

This package intentionally ships only the query surface. Stacked duty layers, specific/compound rates, MPF/HMF entry fees and per-unit landed cost live in the us-tariff-lookup npm package (same snapshot, TypeScript, works in Node) and on this site's tariff calculator — no code at all. A common pattern in mixed stacks: look codes up and track rule changes in PHP, then price the line through the npm package with the same rulesetVersion so both sides agree digit for digit.

Frequently asked questions

Does the PHP package calculate landed cost like the npm package?
Not in v1. invoicetariff/us-tariff-lookup ships the query surface — HTS search, ruleset meta and the changelog. The stacked calculation (MFN + 301 + 232 + MPF/HMF, per-unit landed cost) lives in the us-tariff-lookup npm package and the web calculator, which run the identical snapshot, so you can combine the two against one rulesetVersion.
Which PHP version do I need, and what extensions?
PHP 7.4 or newer with ext-json — which is enabled by default in virtually every PHP build. There are no other extension requirements and no vendor dependencies: the package works on shared hosting, in Docker images, inside Laravel and Symfony apps, and from a plain checkout without Composer at all.
Does it call any API, and does it need an API key?
No and no. The ruleset JSON ships inside the package, there are zero dependencies, and nothing touches the network at runtime. That means no keys, no quotas, no timeouts — it works in CI, air-gapped environments and serverless functions.
How do I use it in Laravel or Symfony?
It is a plain PSR-4 library (InvoiceTariff\UsTariffLookup\TariffLookup) with static methods, so Composer's autoload makes it available everywhere — controllers, jobs, Artisan commands, no service-provider wiring required. If you prefer dependency injection, wrap it in a one-class service that forwards to the static facade; that also gives you a seam for caching meta() output per release.
How current is the data, and how do I update it?
The snapshot is rebuilt monthly from the open us-tariff-rates-2026 repo, and the package is re-released with each snapshot. Run TariffLookup::meta() (or php bin/us-tariff meta) to see your bundled version and data-as-of date, then composer update invoicetariff/us-tariff-lookup to move up. TariffLookup::changelog() lists what changed.
Why can't search() find my product?
The bundled search covers a curated set of high-frequency codes (484 in the current release), not all 5,689 HTS 8-digit lines — check the full table in the hs-codes-database repo or the HTS search page. Also keep queries single-language: every token must match on one surface (code, English description or 中文), so a mixed "cotton 保温杯" query matches nothing. For layered rules the package does not parse, rulesetSeedRaw() hands you the complete JSON.
invoicetariff/us-tariff-lookup on Packagist

MIT licensed, PHP 7.4+, zero dependencies. Source repo, releases and the sibling npm / Go packages are linked from the open source page.