Mcpro Laravel Package

Product Decisions This Supports

• Address capture as a first-class product surface. Any PH-facing flow that touches a physical location — checkout, KYC/onboarding, delivery estimation, branch/store locator, technician dispatch, insurance quoting, BIR-compliant receipts — needs a canonical region → province → city/municipality hierarchy. This package supplies that hierarchy as Laravel models + migrations + seeders, which lets you ship a compliant cascading address form without inventing your own taxonomy.
• Serviceability and coverage gating. Territory rows make it trivial to answer "can we deliver/serve/onboard here?" early in the funnel (pre-quote, pre-signup) rather than at fulfillment, which is where support tickets and refunds accumulate.
• Territory & org design. Sales territories, franchise areas, field-ops zones, and pricing/tax jurisdiction rules all key off province/city. Deciding to model territory as a FK to a PSGC-coded row (vs. free-text strings) is a schema decision that is expensive to reverse later — this package pushes you toward the correct one.
• Build vs. buy, scoped correctly. Buying here buys you ~1–2 weeks of schema/seed/relationship work, not the durable asset. The durable asset is the PSGC dataset and its update cadence, which you still own. Treat the package as scaffolding, not as the source of truth.
• Roadmap sequencing. If regional expansion (ID, TH, VN) is on the roadmap within 12–18 months, adopt now only if you wrap the package behind an internal AddressProvider/LocationRepository interface so a second country can be added without rewriting forms, validators, and reporting.
• Analytics & segmentation. Stable numeric codes enable clean regional cohorting, CAC/LTV by island group, and cohort joins that survive a municipality being reclassified as a city — something free-text city names never survive.

When to Consider This Package

Consider it when:

• You are on Laravel/PHP and need province + city/municipality coverage now, with Eloquent relationships rather than hand-rolled arrays.
• Your address needs stop at city/municipality, or you're willing to source barangay/postal data separately.
• The team is small and 23 stars / 0 dependents is acceptable because you intend to fork and vendor it, not because you expect upstream support.
• You want a starting schema and seeder you can diff against the official PSA PSGC release, rather than a SaaS dependency with per-lookup pricing.

Look elsewhere when:

• You need verified currency. PSGC is reissued periodically (barangay splits, municipality→city conversions, new provinces). A low-activity package is unlikely to track this on schedule. Any serious deployment needs an owner and a semiannual reconciliation job against the PSA source, or a commercial data provider.
• You need more than names and codes. Geocoding, coordinates, polygons, postal/ZIP mapping, multilingual or legacy/alias names (e.g., renamed or merged LGUs, "Metro Manila" vs. NCR), and fuzzy autocomplete are out of scope. That pushes you toward Google Places / HERE / Loqate for the search UX and this package (or a materialized table) for the canonical key.
• Compatibility is unproven. Verify PHP and Laravel version constraints against your stack (Laravel 10/11, PHP 8.2+) before it lands in a sprint; a stale composer.json can mean a fork-and-patch tax.
• Seeder scale is a testing hazard. Tens of thousands of rows should be loaded once into a reference table (or a read-only connection), never in test fixtures, and ideally behind a chunked, idempotent import command.
• You need SLAs, support, or indemnity — a 23-star community package is a supply-chain risk for anything regulated.

How to Pitch It (Stakeholders)

To executives: Every PH customer interaction ends in an address, and right now that address is either free text (unreliable, un-analyzable, error-prone at fulfillment) or a per-lookup vendor bill. This package gives us the official Philippine geographic hierarchy — regions, provinces, cities and municipalities — as native application data at effectively zero licensing cost. It shortens the address-capture build, reduces form abandonment at checkout and onboarding, makes serviceability decisions automatic instead of manual, and gives finance and growth a stable key for tax jurisdiction and regional reporting. The adoption cost is small and reversible; the risk is not the package but the data, which we should own: one named owner, a semiannual refresh against the PSA PSGC release, and a fork kept in-house so we're never blocked by an unmaintained dependency.

To engineering: This is a models + migrations + seeders package, not a service. Import the schema, fork the repo, and put the geography data behind our own repository interface so we can swap in a maintained dataset or a second country without touching form code. Do not run the seeder in tests — load a fixture subset. Do not join user-facing text fields directly; store the code and resolve the label. Budget roughly a day to validate Laravel/PHP compatibility and another to build an idempotent import command plus a diff script against the PSA release. The win is a normalized address key we can join, validate, and segment on for years; the cost is one owned data pipeline.