Laravel Location Kit Laravel Package

Product Decisions This Supports

• Global User Onboarding: Accelerate sign-up flows with pre-populated country/state/city dropdowns (e.g., "Select your region" forms).
• Multi-Regional E-Commerce: Enable currency auto-switching, localized pricing, and region-specific shipping rules (e.g., VAT calculations, international tax compliance).
• Phone Number Validation: Reduce fraud and improve UX with country-specific phone masking, dial-code prepending, and input validation (e.g., +91 98765 43210 for India).
• Timezone-Aware Features: Power dynamic content (e.g., "Show support hours in user’s local timezone") or scheduling tools (e.g., calendar events with timezone offsets).
• Admin Dashboards: Add region-based filters (e.g., "Users in Europe," "Orders from Asia") without manual data entry.
• API-First Strategy: Expose location data to mobile apps or third-party services via Laravel’s facade or Inertia’s shared props.
• Internationalization (i18n): Standardize currency symbols, number formatting, and regional address structures (e.g., ₹1,000 vs. $1,000).
• Build vs. Buy: Avoid reinventing location data infrastructure; leverage a maintained, open-source dataset with Laravel-native integration.
• Roadmap Priorities:
  • Short-Term: Integrate into user profiles and checkout flows (MVP).
  • Mid-Term: Extend to shipping/payment APIs (e.g., currency conversion, regional tax rules).
  • Long-Term: Enable dynamic timezone-based features (e.g., live chat routing, event scheduling).

When to Consider This Package

• Adopt If:

  • Your app targets global users and needs structured location data (countries, states, cities) with minimal maintenance.
  • You’re using Laravel 10+ and want seamless Inertia/Vue/React integration for location-aware UIs.
  • Phone number handling (validation, masking, dial codes) is a critical UX or compliance requirement (e.g., GDPR, fraud prevention).
  • You need currency/timezone data for financial or scheduling features (e.g., invoicing, calendars).
  • Your team lacks dedicated geolocation data engineers but requires reliable, up-to-date datasets.
  • You want to override default data (e.g., custom city names, dial codes) without modifying vendor files.

• Look Elsewhere If:

  • You require real-time geocoding (e.g., address autocomplete, Google Maps integration).
  • Your use case demands postal codes or granular regional data (e.g., US ZIP codes, UK postcodes).
  • You’re using Laravel <10 or a non-PHP backend (e.g., Node.js, Ruby).
  • You need class-based custom data models (currently JSON-only; planned for future versions).
  • Your app serves highly specialized regions (e.g., military bases, remote territories) not covered by the default dataset.
  • You require audit logs or historical tracking of location data changes (package lacks built-in versioning).

How to Pitch It (Stakeholders)

For Executives:

*"This package eliminates technical debt for global location data, saving our team [X] months of development time. It enables faster market expansion by providing:

• Pre-built datasets for 246 countries, 48K+ cities, and 162 currencies—no manual updates required.
• Seamless integration with our Laravel/Inertia stack, reducing frontend-backend friction.
• Critical UX improvements: Phone number masking (e.g., +91 98765 43210) and currency auto-switching, which can reduce cart abandonment by [Y]%.
• Compliance-ready: Built-in timezone and dial-code support for GDPR, tax regulations, and international shipping.

Cost: Free (MIT license) with no ongoing fees. ROI: Faster feature delivery, lower maintenance costs, and scalability for global markets."*

Key Ask: "Approve integration for Phase 1 (user profiles + checkout) with a budget for [Z] dev-hours to customize data overrides (e.g., regional dial codes)."

For Engineering:

*"This is a drop-in solution for location data in Laravel. Here’s why it’s a win: Pros:

• Facade/API: Clean methods like LocationKit::states('india')—no raw JSON parsing.
• Frontend-Ready: Vue/React composables for phone masking, timezone lookups, and dynamic dropdowns (e.g., useLocationKit()).
• Blade Directives: @locationCountries for quick template rendering.
• Inertia Support: Share location data globally via page.props.locationKit (zero extra API calls).
• Customization: Override default data via storage/app/location/ (e.g., add a custom city or dial code).
• Performance: Cache support and lazy-loading (cities disabled by default to avoid bloat).

Trade-offs:

• No real-time geocoding: Use Google Maps API if you need address autocomplete.
• Postal codes missing: Supplement with a dedicated package (e.g., spatie/laravel-postcode).
• Future roadmap: Class-based custom data is coming (track GitHub).

Proposed Implementation:

1. Install: composer require erag/laravel-location-kit + php artisan erag:install-location-kit.
2. Configure: Enable Inertia sharing and override data in storage/app/location/.
3. Integrate:
   • Backend: Use LocationKit::countryOptions() in controllers.
   • Frontend: Use useLocationKit() in Vue/React for phone masking and dropdowns.
4. Test: Validate phone masking (e.g., maskPhone('india', '9876543210') → +91 98765 43210).

Risks:

• Data Accuracy: Default dataset is comprehensive but may need overrides for niche regions.
• Frontend Bloat: Cities are large; keep them disabled unless needed.

Next Steps:

• Review customization docs.
• Plan data overrides for [List of Regions].
• Schedule a spike to test Inertia/Vue integration."*