Geography Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for entity/metadata mapping. This package separates entity definitions (YAML) from PHP code. That is the deciding factor if your roadmap includes configuration-driven domain models: multi-tenant schema variants, per-environment overrides, or mapping onto a legacy database you cannot reshape. If your entities are hand-written PHP classes with no variation, a bespoke solution is cheaper.
• Roadmap sequencing and upgrade budgeting. Release 0.2 contains two breaking changes. Treat the 0.x line as unstable: no minor upgrade should ship without a migration ticket, and no customer-facing milestone should hard-depend on this package until a 1.0 exists or your team accepts owning a fork.
• Feature scoping: does configuration become a product surface? Moving entities to YAML means entity definitions can be edited by people who do not write PHP. That is either a deliberate capability (ops/implementation engineers, per-tenant customization, self-serve configuration) or an accidental one that creates a second, unvalidated schema language. Decide explicitly, and budget for YAML schema validation, linting, and CI checks if you expose it.
• Architecture: explicit service wiring. "Services are not launched by default" shifts the package from auto-discovery toward opt-in registration. That supports decisions on boot-time cost, predictable side effects in tests/CLI/queue workers, and a reviewable dependency graph. It also means every existing integration must now declare its services, so this becomes migration scope, not a detail.
• Use cases this fits: modular monoliths with per-module entity sets; products where persistence shape differs per customer or environment; teams migrating off annotation-based mapping (annotations are effectively legacy across the PHP ecosystem, so this removes a decaying dependency).

When to Consider This Package

• Consider it when: entity or persistence metadata genuinely varies across environments, tenants, or modules; you want that metadata reviewable in diffs and editable without a PHP deploy; you are already on Laravel and want the container to wire things for you; and you can absorb a breaking change per minor release for the next several months.
• Look elsewhere when: you need a stable API today (pre-1.0 with breaking changes at 0.2 is disqualifying for a committed delivery date unless you pin the version and accept frozen dependencies); your team relies on IDE autocompletion, static analysis, and refactoring tools over entity fields, which YAML will not give you; entity definitions are stable and hand-maintained, where YAML adds a parsing layer and a drift risk for no benefit; or you cannot invest in validation tooling, in which case malformed YAML fails at runtime rather than at build time.
• Required diligence before adoption: confirm the YAML format is versioned and validated (schema, error messages, cache invalidation on change); confirm how services are now registered and what happens to silently unregistered services; and get a benchmark of boot time and entity-resolution cost against your current approach. None of that is answered by the release notes alone.

How to Pitch It (Stakeholders)

For executives: This is a small, pre-1.0 open-source package that lets entity and service configuration live in files rather than code. The upside is flexibility — the same codebase can serve differently shaped customers and environments, and configuration changes do not require a PHP developer. The cost is maturity: version 0.2 changed how entities are defined and how services start, both breaking. Recommendation: prototype it behind a flag for one non-critical workflow, pin the exact version, and do not put it on a committed roadmap until it reaches 1.0 or we decide to own it.

For engineering: Two breaking changes in 0.2. Entity definitions moved from annotations to YAML, which removes a runtime reflection/parsing dependency and makes entity shape configurable and cacheable — but it also removes IDE and static-analysis support over entity fields, so we must add YAML schema validation and a CI lint step or we will trade compile-time errors for production ones. Services are no longer auto-launched; registration is explicit, which improves boot cost and test predictability but will silently break any code assuming auto-wiring. Plan one migration pass to convert annotations to YAML, audit service registration, and add a config-cache invalidation test. Pin the version; expect further breaks before 1.0.