Ti Ext Local Laravel Package

Product Decisions This Supports

• Geospatial Feature Expansion: Enables rapid development of location-aware functionalities (e.g., "Find Nearest Store," delivery zone validation, or proximity-based promotions) without heavy custom development. Ideal for e-commerce, food delivery, or local service platforms.
• Order-Ahead, Booking & Reservation Reliability: The v4.3.1 fix removes a real revenue risk — locations that are open could transiently report no available timeslots, particularly when future orders are disabled and a weekly closing day falls inside the schedule's two-day lookback window. Anyone shipping pickup slots, table reservations, or delivery windows should treat timeslot resolution as a first-class product capability, not a nice-to-have.
• Strategic "Buy vs. Build": Eliminates the need to invest in building a custom geocoding system, reducing time-to-market for location-based features. Aligns with Laravel's ecosystem, leveraging existing Eloquent models and service providers.
• Roadmap for Hyper-Localization: Supports future-proofing for features like dynamic pricing by location, region-specific inventory, or geofenced marketing campaigns.
• Performance Optimization: Database indexes (v4.1.0) and eager loading (v4.0.11) improve query performance for location-heavy applications, critical for scaling.
• Customer Trust Signals: Location reviews (v4.0.7) and opening hours (v4.0.8) enhance user experience by providing transparent, real-time location data. Schedule correctness (v4.3.1) is what makes those trust signals actually accurate at day boundaries.

When to Consider This Package

• Adopt if:

  • Your product requires geocoding, distance calculations, or location-based filtering (e.g., "Show me stores within 10 miles").
  • You're building a multi-location business platform (e.g., restaurants, retail, healthcare) where delivery zones or service areas are core to the value proposition.
  • Your roadmap includes timeslot-based ordering, pickup scheduling, or reservations — the schedule/timeslot engine (now hardened in v4.3.1) is a meaningful head start over rolling your own availability logic.
  • Your team lacks geospatial database expertise (e.g., PostGIS) or wants to avoid the complexity of implementing custom geocoding logic.
  • You need integrated location reviews and opening hours to improve customer trust and operational clarity.
  • Your stack is Laravel-based, and you want to minimize custom code for location management.

• Look elsewhere if:

  • You need advanced geospatial analytics (e.g., heatmaps, complex polygon intersections) beyond basic distance queries—consider PostGIS or dedicated GIS tools like Mapbox or Google Maps Platform.
  • Your application requires real-time traffic routing or dynamic pathfinding (e.g., ride-sharing, logistics optimization)—this package focuses on static geocoding, not dynamic navigation.
  • You need enterprise-grade workforce/scheduling (shifts, capacity planning, SLA-aware slot allocation) — the package's scheduling is location-availability oriented, not a booking engine.
  • You're not using Laravel/Eloquent or need a solution for a non-PHP backend (e.g., Node.js, Python).
  • Your project has strict legacy constraints (e.g., PHP 7.x without type hints) that conflict with the package's modern PHP 8.x+ features.
  • You require offline geocoding or support for non-standard coordinate systems (e.g., UTM)—this package assumes standard latitude/longitude inputs.

• Upgrade trigger regardless of adoption status: If you are already on the package, on a version below v4.3.1, and you rely on opening hours with future orders disabled or weekly closing days, schedule this upgrade — the bug silently zeroes out availability rather than throwing, so it will not surface in error monitoring.

How to Pitch It (Stakeholders)

For Executives: "This package lets us launch location-based features—like 'Find the Nearest Store' or 'Delivery Zone Validation'—in weeks instead of months. For example, if we're expanding [Product X] into new markets, we can instantly enable hyper-local targeting without hiring specialized GIS engineers. The latest release (v4.3.1) fixes a bug where a location that was genuinely open could show no available timeslots — the kind of silent glitch that quietly costs orders and erodes trust in our availability promises. For [use case, e.g., 'expanding our pickup and delivery windows'], this protects [specific metric, e.g., 'conversion on the slot-selection screen' or 'support tickets about "your site says you're closed"'] with minimal dev overhead."

For Engineering: *"The package provides:

• Turnkey geocoding: Supports multiple drivers (Google Maps, OpenStreetMap) out of the box, with Laravel Eloquent integration for location data.
• Correct schedule resolution (v4.3.1): The timeslot window search now uses its own search budget, independent of the future-order day allowance. Previously, with future orders disabled, a weekly closing day falling inside the two-day lookback window could make isOpen-style checks return an empty slot set while the location was open — a boundary condition that "self-healed" at midnight and was therefore nearly impossible to reproduce in QA.
• Type-safe models: v4.3.1 adds further type-safety improvements on Location methods (following the checkDistance() return-type work in v4.1.3), reducing runtime errors and improving IDE support.
• Performance optimizations: Database indexes (v4.1.0) and eager loading (v4.0.11) speed up location queries, critical for scaling.
• Low maintenance: The team handles driver updates and edge cases (e.g., invalid coordinates, schedule boundaries), so we focus on business logic. Tradeoffs:
• Not a full GIS solution—if you need advanced spatial operations (e.g., polygon intersections), you'll still need PostGIS or a dedicated tool.
• Requires Laravel; standalone PHP projects may need adapters.
• Minor adjustments needed if your code uses fully qualified namespace references (e.g., \App\Models\Location), as the package now prefers short class names.
• The schedule fix is behavioral, not just cosmetic — if you wrote tests or workarounds that encoded the buggy empty-timeslot behavior, expect them to fail after upgrading, and audit any custom code that widened the lookback window or manipulated future-order settings as a mitigation. Recommendation: Prioritize this for location-heavy features. Add a regression test covering weekly closing day + future orders disabled + two-day lookback, then validate in staging against your geocoder drivers and custom Location model extensions before rolling wide."*

For Design/Product: *"This package enables us to:

• Surface location data intuitively: For example, a 'Nearest Store' map with opening hours and reviews (v4.0.7) could replace a static 'Contact Us' page.
• Trust the availability UI we ship: The v4.3.1 fix means the timeslot picker no longer contradicts the "Open now" badge around weekly closing days — a mismatch users notice immediately and rarely forgive.
• Improve operational workflows: Delivery zones (v4.0.6) can auto-validate addresses during checkout, reducing support tickets. Schedule correctness removes a whole class of "I couldn't book even though you're open" tickets.
• A/B test location-based features: Dynamic pricing or promotions by region could be tested without custom dev work. Example: For a food delivery app, we could show users their nearest restaurant and its current wait time (via opening hours) in one view, increasing conversions — and now that view stays accurate the day before a scheduled closure, instead of silently offering nothing."*