Laravel Barangay Search Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

   composer require yahaaylabs/laravel-barangay-search
   

   Ensure your composer.json meets the requirements (PHP 8.1+, Laravel 10/11, Livewire 3).

2. Set Up API Key Register for a GIS.PH API key and add it to your .env:

   GIS_PH_API_KEY=your_api_key_here
   

3. Basic Livewire Integration In a Livewire component (e.g., BarangaySearchComponent.php), include the component:

   use YahaayLabs\BarangaySearch\BarangaySearch;
   
   public function render()
   {
       return view('livewire.barangay-search-component', [
           'barangaySearch' => BarangaySearch::make()
               ->debounce(500) // Optional: Adjust debounce time (ms)
               ->cacheFor(60) // Optional: Cache results for 60 minutes
       ]);
   }
   

4. Render the Component in Blade

   @livewire('barangay-search-component')
   

5. Handle Selected Barangay Extend the component to capture selections:

   public function selected(Barangay $barangay)
   {
       $this->dispatch('barangay-selected', barangay: $barangay);
   }
   

Implementation Patterns

Core Workflows

1. Autocomplete Search

   • Debounced Input: The component automatically debounces API calls (default: 500ms) to avoid excessive requests.
   • Filtering: Narrow results by province, city, or municipality:

     BarangaySearch::make()
         ->filterByProvince('Laguna')
         ->filterByCity('Calamba')
     

2. Mary UI Integration (Optional)

   • Enable pre-styled components by publishing views:

     php artisan vendor:publish --tag=barangay-search-views
     

   • Customize styles by overriding published views or using inline styles.

3. Caching Strategy

   • Cache API responses to reduce calls:

     BarangaySearch::make()->cacheFor(3600); // Cache for 1 hour
     

   • Clear cache manually if needed:

     BarangaySearch::flushCache();
     

4. Event Handling

   • Listen for selections in your Livewire component:

     protected $listeners = ['barangay-selected' => 'handleBarangaySelection'];
     
     public function handleBarangaySelection($event)
     {
         $this->barangay = $event['barangay'];
     }
     

5. Custom UI

   • Override the search template by publishing views and modifying:

     @livewire('barangay-search-component', [
         'barangaySearch' => BarangaySearch::make()->customView('path.to.your.view')
     ])
     

Integration Tips

• Form Integration: Pair with Laravel Forms or Livewire Forms for seamless validation:

  public function rules()
  {
      return [
          'barangay' => 'required|string',
      ];
  }
  

• API Rate Limiting: Monitor API usage in config/barangay-search.php to adjust max_retries or timeout.
• Fallback Data: For offline use, combine with a local database backup of barangay data.

Gotchas and Tips

Pitfalls

1. API Key Validation

   • Issue: Missing or invalid GIS_PH_API_KEY in .env causes silent failures.
   • Fix: Verify the key and check Laravel logs for GisPhSdkException.

2. Caching Conflicts

   • Issue: Stale cached data if the GIS.PH API updates its dataset.
   • Fix: Implement a cache versioning system or manually flush cache:

     BarangaySearch::flushCache();
     

3. Livewire Component Naming

   • Issue: Naming conflicts if multiple components use the same class name.
   • Fix: Use unique Livewire component names (e.g., BarangaySearchComponent vs. LocationPicker).

4. Debounce Delays

   • Issue: Slow responses due to high debounce values (e.g., 1000ms) in low-latency apps.
   • Fix: Adjust debounce time dynamically:

     BarangaySearch::make()->debounce($this->isMobile() ? 300 : 500);
     

5. Mary UI Dependencies

   • Issue: Missing Mary UI assets if not properly installed.
   • Fix: Ensure Mary UI is installed and published:

     npm install mary-ui
     npm run dev
     

Debugging

• Log API Responses: Enable debug mode in config/barangay-search.php:

  'debug' => env('BARANGAY_SEARCH_DEBUG', false),
  

• Check Network Requests: Use browser dev tools to verify API calls to https://gis.ph/api/barangays.

Extension Points

1. Custom Data Mapping

   • Extend the Barangay model to add custom fields:

     use YahaayLabs\BarangaySearch\Models\Barangay as BaseBarangay;
     
     class Barangay extends BaseBarangay
     {
         protected $appends = ['full_address'];
         public function getFullAddressAttribute()
         {
             return "{$this->barangay}, {$this->municipality}, {$this->province}";
         }
     }
     

2. Batch Processing

   • Fetch multiple barangays at once for bulk operations:

     $barangays = BarangaySearch::make()->search('Calamba')->getBarangays();
     

3. Geocoding Integration

   • Combine with Laravel Geocoder for reverse geocoding:

     use Geocoder\Geocoder;
     $geocoder = new Geocoder();
     $coordinates = $geocoder->geocode($barangay->full_address);
     

4. Localization

   • Override labels in the config:

     'labels' => [
         'search_placeholder' => 'Search for a barangay...',
         'no_results' => 'No barangays found.',
     ],