Teryt Database Bundle Laravel Package

Product Decisions This Supports

• Market-entry scoping for Poland. TERYT is the official Polish register of territorial division (voivodeships → counties → municipalities → localities → streets), maintained by GUS. This package is the plumbing that lets the product speak that language: canonical TERC/SIMC/ULIC codes rather than free-text city names. That directly informs whether "launch in PL" is a quarter-sized effort or a year-sized one.
• Build vs. buy on address data. The alternative is owning a TERYT import pipeline ourselves — parsing the periodic GUS XML/CSV dumps (TERC, SIMC, ULIC, WMRODZ), handling schema drift, and re-importing on every registry update. This bundle is MIT-licensed and already models that import. The decision is "adopt an integration" versus "own a data pipeline," not "buy a SaaS."
• Feature roadmap for address capture. Cascading selects (voivodeship → county → municipality → city → street), server-side validation against official codes, and normalized storage. This is the unglamorous prerequisite for checkout shipping/billing forms, customer address books, CRM records, and invoicing data that has to reconcile with Polish fiscal requirements.
• Segmentation and reporting. Because records carry official administrative identifiers, we can roll up orders, customers, or claims by county/voivodeship without fuzzy matching. That unlocks territory-based pricing, delivery-zone rules, sales-territory assignment, and clean joins to public GUS statistics.
• Public-sector and regulated-buyer fit. Polish e-government, healthcare, and utility tenders frequently specify TERYT codes as a hard requirement. Having this integrated is a checkbox we can claim in an RFP response rather than a scramble mid-procurement.
• Prioritization signal, honestly stated. 5 stars and 0 dependents is a low adoption signal. That doesn't make it wrong, but it means "adopt the package" and "adopt the idea, vendor the data ourselves" are both on the table and should be costed against each other.

When to Consider This Package

Consider it when all of the following hold:

• We are building for the Polish market and need administrative division data (not just a hardcoded list of 20 biggest cities).
• The stack is Symfony, or we have engineering appetite to port/de-vendor the underlying logic into a Laravel service. This is a Symfony bundle — despite being grouped under "Laravel/PHP" packages, it is not a Laravel package and will not drop into a Laravel app cleanly. That's a real integration cost, not a footnote.
• We want official codes for validation and reporting, not just display labels.
• We are comfortable with low community redundancy: 5 stars, 0 dependents, maintained by a single commercial sponsor (FSI Open). Recent releases (latest tagged April 2026) suggest it isn't abandoned, but the bus factor is effectively one organization.
• We have a refresh plan — TERYT data changes (municipal mergers, street renames, new localities). Whoever owns the import cadence owns a recurring chore.

Look elsewhere when:

• We need multi-country address handling — this is Poland-only by design.
• We need geocoding, reverse geocoding, or address autocomplete — TERYT gives administrative structure, not coordinates or fuzzy matching. Pair with a commercial provider or a separate geocoder.
• We only need a static dropdown of major cities — a seeded fixture table is cheaper than a dependency.
• The team is Laravel-first and dependency-averse — importing the TERYT dumps into our own tables (a day or two of work) may beat carrying an unmaintained-by-others Symfony bundle.
• We need SLAs or vendor support — MIT and a 5-star repo mean no support contract exists.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed integration that supplies official Polish address and territorial data — the same registry the Polish government and GUS use. It is the difference between a checkout form that accepts "Warszawa" as free text and one that stores a validated, reportable administrative code. Cost is near zero in licensing; the real investment is a few engineering days plus an ongoing data-refresh habit. The upside is faster, more credible entry into the Polish market and a stronger position in public-sector and regulated tenders that specify TERYT codes.

The caveat to state plainly: adoption is tiny (5 GitHub stars, no known dependents) and it is a Symfony bundle, not a Laravel package — so we should treat it as a reference implementation to adopt or fork, not a vetted third-party dependency. Recommendation: run a short spike, and decide between (a) using it directly if we're on Symfony, or (b) lifting the TERYT import logic into our own codebase to remove the maintenance risk. Either way, the strategic call — we will support Polish administrative data properly — is the one worth approving now; the packaging question is an engineering detail we can settle in the spike.