Address Laravel Package

Product Decisions This Supports

• Build vs. buy (adopt) for the geo + party data model. The package supplies an opinionated Eloquent schema for countries → provinces → cities, plus addresses, organizations, people and locations. Choosing it is a decision to not hand-roll that schema, and instead invest engineering time in the differentiated parts of the product (checkout, onboarding, routing, billing).
• How to model "who and where" in the domain. It pushes a polymorphic address model — an address can belong to a person, an organization, or a location — rather than flat address_line_1 columns on users. That is a durable modeling decision affecting CRM, billing, shipping, and multi-address support for years. Worth an explicit architecture sign-off.
• International expansion roadmap. Country/province/city as first-class records (rather than free-text strings) unlocks localized checkout, tax jurisdiction by state/province, serviceability rules by city, and reporting by region. This is the schema prerequisite for any "expand beyond one country" milestone.
• B2B vs. B2C product shape. The Organization + Person entities signal a B2B-capable model (companies with multiple contacts and multiple addresses). If the roadmap includes accounts, teams, or a customer directory, this maps directly; if the product is strictly consumer, half the package is dead weight.
• MVP scoping and prototyping. For an admin back office, internal ops tool, or a first-pass customer directory, it collapses days of migration-and-model work into an install. Good for validating a workflow before committing to a proprietary design.
• Data sourcing as a separate decision. The package provides structure, not content. Populating countries/provinces/cities is a downstream decision (bundled seeders vs. GeoNames vs. a paid provider like Google Places, Loqate, or Smarty). Flagging this early prevents a "we installed it, where are the cities?" surprise in sprint planning.
• Roadmap deferral. Address validation, normalization, geocoding, and deliverability scoring are explicitly out of scope here. Knowing this lets you schedule those as distinct epics with their own vendor evaluation instead of assuming they come free.

When to Consider This Package

Consider it when:

• The stack is Laravel/PHP with Eloquent, and there is no appetite to design a geo/address schema from scratch.
• You need the hierarchy (country/province/city) and polymorphic addressability in the same model — e.g., a company has a billing address, a person has a contact address, a location has an operating address.
• The near-term need is internal tooling, admin panels, back-office CRUD, or an MVP where shipping speed beats long-term dependency hygiene.
• Engineering is willing to vendor or fork the code and own it. At 20 stars and zero dependents, treat it as source code you are adopting, not a vendor you are relying on.
• You want a reference implementation to critique before writing your own migrations — reading it is cheaper than a design doc workshop.

Look elsewhere when:

• You need authoritative, current, worldwide postal data. Use a dedicated dataset or API; this package does not ship a maintained one.
• You need address validation, standardization, autocomplete, or geocoding. That is a different product category (Loqate, Smarty, Google Places, Melissa).
• The system is high-scale and production-critical with no engineer allocated to maintain a low-adoption dependency. Zero dependents means zero community safety net and unproven upgrade paths across Laravel major versions.
• The team is not on Laravel, or is standardizing on a mature geo package with an active maintainer and test coverage you can inspect.
• Compliance or billing accuracy depends on verified addresses — do not let a storage-layer package imply a verification capability.
• You need multi-tenant, audit-trailed, or soft-deleted address history with strict data-residency rules; you will be extending heavily anyway, so build deliberately.

Adoption gate (recommended): a one-to-two day spike — install, run migrations, seed a small country set, model one real use case end to end, and inspect test coverage and last-commit recency. Decide fork-vs-build on the spike output, not on the README.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a candidate open-source component, MIT-licensed and free, that provides the data model for countries, regions, cities, addresses, companies and people in our Laravel stack. It removes roughly a sprint of undifferentiated schema work from any feature involving customer addresses, international expansion, or a B2B account directory, and it imposes a clean structure that supports tax jurisdiction and regional reporting later. The trade-off is maturity: the project is small — about twenty stars and no downstream dependents — so we should treat it as code we adopt and own rather than a vendor relationship. Recommendation: fund a short technical spike; if it passes, use it to accelerate the next address-dependent release, with engineering owning a fork. It reduces time-to-market at effectively zero license cost; the real cost is a modest, bounded maintenance commitment.

For engineering (summary): Laravel package exposing Eloquent models and migrations for Country, Province, City, Address, Organization, Person, and Location, with addresses attachable polymorphically to people, organizations, and locations. No validation, geocoding, or maintained geo dataset — plan seeding separately. Low adoption means we should fork into our own namespace, pin it, add tests around the relations we depend on, and treat upgrades as manual merges. Evaluate it as a schema accelerator and a reference design; reject it only if the spike shows the polymorphic model fights our existing access patterns.