Ti Ext Local Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require tastyigniter/ti-ext-local
   

   Publish the extension’s assets and configurations:

   php artisan vendor:publish --provider="TastyIgniter\Local\LocalServiceProvider"
   

2. First Use Case:

   • Find Nearest Location: Use the Location model’s built-in query scopes:

     use TastyIgniter\Local\Models\Location;
     
     $nearestLocation = Location::nearBy($latitude, $longitude, $distanceInKm)
         ->where('status', 'active')
         ->first();
     

   • Delivery Area Check: Validate if a customer’s address falls within a location’s delivery zone:

     $location = Location::find($locationId);
     $isInDeliveryArea = $location->isInDeliveryArea($customerLatitude, $customerLongitude);
     

3. Where to Look First:

   • Documentation: TastyIgniter Local Docs for setup and API references.
   • Models: app/Models/TastyIgniter/Local/Location.php for core functionality (e.g., nearBy(), isInDeliveryArea()).
   • Migrations: Check database/migrations/ for schema changes (e.g., delivery area boundaries, opening hours).

Implementation Patterns

Usage Patterns

1. Location-Based Queries:

   • Nearby Locations: Use the nearBy() scope with optional filters:

     Location::nearBy($lat, $lng, 10) // 10km radius
         ->with(['reviews', 'deliveryAreas']) // Eager load relationships
         ->get();
     

   • Delivery Area Validation: Integrate with checkout logic:

     $cart = Cart::with('items')->find($cartId);
     foreach ($cart->items as $item) {
         $location = $item->location;
         if (!$location->isInDeliveryArea($customerLat, $customerLng)) {
             throw new \Exception("Item not available for delivery in this area.");
         }
     }
     

2. Opening Hours Logic:

   • Check if a location is open during a specific time:

     $location = Location::find($id);
     $isOpen = $location->isOpenNow(); // Uses Carbon for time comparison
     

   • Customize business hours per day:

     $location->openingHours()->update([
         'monday_open' => '09:00',
         'monday_close' => '18:00',
         // ... other days
     ]);
     

3. Geocoder Integration:

   • Configure geocoding drivers in .env:

     LOCAL_GEOCODE_DRIVER=google // or 'osm'
     GOOGLE_MAPS_API_KEY=your_key_here
     

   • Reverse geocode an address:

     $geocoder = app(\TastyIgniter\Local\Services\Geocoder::class);
     $result = $geocoder->geocode('1600 Amphitheatre Parkway, Mountain View');
     

4. Custom Location Fields:

   • Extend the Location model with custom attributes:

     // In a service provider or model observer
     Location::created(function ($location) {
         $location->custom_fields = json_encode([
             'has_wifi' => true,
             'parking_available' => false,
         ]);
         $location->save();
     });
     

Workflows

1. Admin Workflow:

   • Use the SettingsEditor to configure location-specific settings (e.g., delivery fees, opening hours) via the TastyIgniter admin panel.
   • Define delivery areas using the LocationArea model:

     $location->deliveryAreas()->create([
         'name' => 'Downtown Zone',
         'radius' => 5, // km
         'fee' => 2.99,
         'color' => '#FF0000', // For UI visualization
     ]);
     

2. Frontend Integration:

   • Nearby Locations Map: Use Laravel Blade to render a map with markers:

     @foreach($nearbyLocations as $location)
         <div data-lat="{{ $location->latitude }}" data-lng="{{ $location->longitude }}">
             {{ $location->name }}
         </div>
     @endforeach
     

   • JavaScript: Use Leaflet.js or Google Maps API to visualize locations:

     const locations = @json($nearbyLocations);
     locations.forEach(loc => {
         L.marker([loc.latitude, loc.longitude]).addTo(map)
             .bindPopup(`<b>${loc.name}</b><br>Distance: ${loc.distance} km`);
     });
     

3. Performance Optimization:

   • Eager Loading: Avoid N+1 queries for related data:

     Location::with(['reviews', 'deliveryAreas'])->nearBy($lat, $lng, 20)->get();
     

   • Database Indexes: Leverage the package’s added indexes (e.g., latitude, longitude) for faster geospatial queries.

Integration Tips

1. Event Listeners:

   • Listen for location updates to trigger notifications or sync external services:

     Location::updated(function ($location) {
         if ($location->isDirty('opening_hours')) {
             event(new \TastyIgniter\Local\Events\OpeningHoursUpdated($location));
         }
     });
     

2. API Endpoints:

   • Create a dedicated route for location searches:

     Route::get('/api/locations/nearby', function (Request $request) {
         $lat = $request->query('lat');
         $lng = $request->query('lng');
         $distance = $request->query('distance', 10);
     
         return Location::nearBy($lat, $lng, $distance)->get();
     });
     

3. Testing:

   • Mock geocoding responses in tests:

     $this->partialMock(\TastyIgniter\Local\Services\Geocoder::class, function ($mock) {
         $mock->shouldReceive('geocode')
             ->once()
             ->andReturn(['lat' => 37.422, 'lng' => -122.084]);
     });
     

4. Caching:

   • Cache frequent geocoding results or nearby location queries:

     $nearby = Cache::remember("nearby_locations_{$lat}_{$lng}", now()->addHours(1), function () use ($lat, $lng) {
         return Location::nearBy($lat, $lng, 10)->get();
     });
     

Gotchas and Tips

Pitfalls

1. Namespace References:

   • Issue: The v4.1.3 release changed Location model references to use short class names (e.g., Location instead of \App\Models\Location). If your code explicitly uses fully qualified namespaces, it may break.
   • Fix: Update references to use short class names:

     // Before (may break)
     $location = new \App\Models\Location;
     
     // After (recommended)
     $location = new \TastyIgniter\Local\Models\Location;
     

2. Geocoder Driver Configuration:

   • Issue: If the LOCAL_GEOCODE_DRIVER is not set in .env, the package will throw an exception. Ensure the driver (e.g., google, osm) and corresponding API keys are configured.
   • Fix: Add to .env:

     LOCAL_GEOCODE_DRIVER=google
     GOOGLE_MAPS_API_KEY=your_api_key_here
     

3. Delivery Area Validation:

   • Issue: The isInDeliveryArea() method may return false positives if the geocoding service (e.g., Google Maps) provides imprecise coordinates.
   • Fix: Use a buffer distance or log discrepancies for review:

     $isInArea = $location->isInDeliveryArea($lat, $lng, 0.1); // Add 100m buffer
     

4. Opening Hours Edge Cases:

   • Issue: The isOpenNow() method assumes 24-hour time format and may fail if opening_hours data is malformed (e.g., missing values for certain days).
   • Fix: Validate opening hours data before use:

     if (!$location->openingHours->isFilled()) {
         throw new \InvalidArgumentException("Opening hours not fully configured.");
     }
     

5. Custom Fields Serialization:

   • Issue: Custom fields stored as JSON may cause serialization errors if the data structure changes unexpectedly.
   • Fix: Use a dedicated model or cast the attribute:

     protected $casts = [
         'custom_fields' => 'array',
     ];
     

Debugging

1. Geocoding Failures:
   • Enable debug mode for the geocoder:

     $ge