- Can I install fsi/teryt-database-bundle in a Laravel application?
- Not as a drop-in dependency. This is a Symfony bundle with a DI extension, Doctrine entities, and Symfony console commands, so Composer may install it but Laravel will not wire its services or commands automatically. Treat it as a reference implementation and fork it if you need TERYT data in Laravel.
- What does fsi/teryt-database-bundle actually provide?
- It provides Doctrine ORM entities for Polish administrative units: voivodeships, counties (powiaty), communes (gminy), localities (SIMC), streets (ULIC), and related postal data. It also ships database migrations, import commands for GUS TERYT datasets, and Symfony bundle configuration for wiring the model into an application.
- How do I install and configure the bundle in a Symfony project?
- You install it with Composer, register the bundle in your Symfony kernel or bundles configuration, and ensure your Doctrine connection and migrations are configured. Then you run the provided migrations and execute the import command against downloaded GUS TERYT files. Check the Polish-language README for the exact command names and configuration keys, since they are not fully documented in English.
- Does the package include the official GUS TERYT data files?
- No, the package ships the schema, entities, and import tooling, but the official GUS data files are obtained separately from GUS sources. That means availability, licensing, and update cadence sit outside the package and must be managed by your team. Plan for a download step and a validation step before running imports.
- Which Symfony, PHP, and Doctrine versions are supported?
- The exact constraints are not clearly documented in the overview, so inspect the package composer.json and test against your target stack before committing. Recent release activity suggests maintenance intent, but version tags alone do not prove Symfony 7, Doctrine 3, PHP 8.3, or PostgreSQL support in practice. Verify with a spike rather than assuming compatibility.
- Is there a Laravel or Eloquent version of TERYT?
- There is no official Laravel package for this TERYT model. The practical options are to fork the repository and re-express the entities and migrations as Eloquent models, or to run TERYT as an isolated reference service behind a repository interface. Budget the Laravel port as a two-to-three-week build, not a dependency addition.
- How do I import TERYT data and how long does a full reload take?
- The bundle parses fixed-format GUS text or CSV files and upserts them into dictionary tables for TERC administrative units, SIMC localities, and ULIC streets. Expected volumes are roughly 16 voivodeships, 314 powiaty, 2,500 gminy, and over 100,000 localities and streets, so a full truncate-and-reload is typically minutes rather than hours. Incremental diffing is not clearly documented, so assume full reloads until you verify otherwise.
- How should I use TERYT for Polish address and postal validation?
- Use TERYT identifiers as the canonical lookup layer for administrative units and validate free-text addresses against them rather than replacing your address model outright. Build a mapping table from existing free-text addresses to TERYT IDs, populate it in shadow mode, and measure the match rate before enforcing constraints. Introduce write constraints requiring valid TERYT IDs only after the read paths are proven.
- What are the production risks of depending on this bundle?
- The package has low adoption, no dependents, and single-vendor origin from FSI Open, so there is little community pressure to keep it current. GUS file layouts have changed over time without loud versioning, and a silent column shift can produce a green import with corrupt records. Pin or vendor the code, validate record counts against published GUS totals, and monitor for upstream data changes.
- How do I test and maintain a TERYT integration in Laravel?
- Test the import parsers with fixture files and assert record counts against published GUS totals for voivodeships, counties, communes, and localities. Keep lookups behind a repository interface so you can swap the data source and cache reads without touching business logic. Handle retired SIMC and ULIC identifiers explicitly, and schedule refreshes independently from application deploys.