World Laravel Package

Product Decisions This Supports

• Geospatial Features: Enables rapid development of location-based applications (e.g., multi-country e-commerce, global logistics, or travel platforms) by eliminating manual data management for countries, states, cities, currencies, and timezones.
• Regulatory Compliance: Simplifies adherence to regional requirements (e.g., tax rules, currency formatting, or address validation) by providing standardized data.
• Build vs. Buy: Justifies buying this package over custom development for teams lacking geospatial expertise or resources to maintain up-to-date location data.
• Roadmap Prioritization:
  • MVP Acceleration: Quickly prototype features like country-specific pricing, localized content, or timezone-aware scheduling.
  • Scalability: Avoids technical debt from hardcoding or scraping geospatial data as user bases grow globally.
  • API-Driven Features: Supports future integrations with payment gateways (e.g., Stripe for multi-currency), mapping services (Google Maps, Mapbox), or compliance tools (e.g., GDPR regional data handling).
• Use Cases:
  • Marketplaces: Filter products by country/region, enforce regional shipping rules.
  • SaaS Platforms: Offer location-aware features (e.g., time zone settings, currency conversion).
  • Government/Nonprofits: Manage grants, aid distribution, or voter registration by region.
  • Travel/Booking: Validate destinations, calculate local taxes, or display city-specific amenities.

When to Consider This Package

• Adopt When:

  • Your product requires real-time, accurate geospatial data (e.g., >50 countries/states/cities) without manual maintenance.
  • You need consistent, normalized data for APIs, forms, or reports (e.g., avoiding typos in country names or inconsistent currency codes).
  • Your team lacks dedicated data engineers to curate and update location datasets.
  • You’re building features tied to regional compliance (e.g., VAT rates, data sovereignty laws) or localization (e.g., language/currency support).
  • You want to reduce frontend complexity by offloading geospatial logic to the backend (e.g., pre-filtering valid cities for a dropdown).

• Look Elsewhere If:

  • You need highly customized geospatial queries (e.g., polygon-based searches, distance calculations) → Consider PostGIS or dedicated GIS packages.
  • Your app requires real-time updates (e.g., political boundary changes) → Evaluate APIs like GeoNames or RESTCountries.
  • You’re building a global enterprise system with niche regions (e.g., territories, disputed areas) → This package may lack granularity; supplement with custom data.
  • Your stack isn’t Laravel-based → Assess alternatives like country-list (JavaScript) or pycountry (Python).
  • You need reverse geocoding (coordinates → location) or geocoding (address → coordinates) → Use Google Maps API, OpenStreetMap, or dedicated GIS tools.

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

"This package lets us build global features without hiring a data team or spending months cleaning location data. For example:

• Launch a multi-country store in 2 weeks instead of 2 months by auto-populating regions, currencies, and tax rules.
• Avoid costly errors like mislabeled addresses or incorrect VAT calculations by using a maintained, standardized dataset.
• Scale effortlessly—whether we add 10 or 100 countries, the data stays accurate and consistent. It’s like plugging in a ‘Google Maps for our backend’—saving dev time while future-proofing for expansion. The MIT license means no hidden costs, and the active development (last release: Oct 2025) ensures long-term reliability."

For Engineering/Technical Stakeholders:

*"Problem: Managing geospatial data (countries, states, cities, currencies) is error-prone, time-consuming, and scales poorly. Solutions like hardcoding or scraping lead to:

• Inconsistent data (e.g., ‘USA’ vs. ‘United States’).
• Maintenance overhead (updating when borders or currencies change).
• Poor performance (joining large tables or API calls per request).

Solution: sewidan/world provides:

• Pre-seeded, normalized data for 200+ countries, 30k+ cities, and 160+ currencies—ready to query via Eloquent or API routes.
• Flexible configuration:
  • Filter countries via allowed_countries/disallowed_countries in config (e.g., restrict to EU markets).
  • Customize table names or disable unused fields (e.g., skip timezones if irrelevant).
  • Search functionality (e.g., City::where('name', 'like', '%Paris%')).
• Zero API limits: Data is self-hosted; no rate restrictions or vendor lock-in.
• Laravel-native: Integrates seamlessly with migrations, seeders, and facades (e.g., World::countries()).

Implementation:

1. Install: composer require sewidan/world.
2. Publish assets: php artisan vendor:publish --tag=world.
3. Seed data: php artisan db:seed --class=WorldSeeder (one-time, ~5 min).
4. Query: Use Eloquent (Country::with('states.cities')->find(1)) or API routes (/api/countries).

Trade-offs:

• Not a GIS tool: Avoid for complex spatial queries (e.g., ‘find cities within 50km of a point’).
• MIT license: No SLAs, but active maintenance (last release Oct 2025) mitigates risk.
• Storage: ~10MB DB overhead (negligible for most apps).

Recommendation: Adopt for MVP/geospatial-heavy features; pair with a lightweight caching layer (e.g., Redis) if query performance is critical. Example use cases:

• Dynamic country/state/city dropdowns in forms.
• Regional pricing or currency conversion logic.
• Compliance checks (e.g., ‘Is this user in a GDPR-covered region?’).
• Analytics dashboards with geospatial segmentation."*