Laravel Barangay Search

A Laravel Livewire component for searching Philippine Barangays with optional Mary UI support. This package uses the GIS.PH PHP SDK to interact with the official GIS.PH API.

GitHub Repository: YahaayLabs/laravel-barangay-search

Features

• 🔍 Autocomplete Search - Real-time Barangay Search with debouncing.
• 🎨 Mary UI Support - Pre-styled components using Mary UI (optional).
• 💾 Caching - Intelligent caching to reduce API calls.
• 🎯 Filtering - Filter by municipality, city, or province.
• 🔧 Customizable - Fully customizable UI and behavior.

Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• Livewire 3.x
• GIS.PH API Key

Installation

1. Install via Composer

composer require yahaaylabs/laravel-barangay-search

2. Publish Configuration (Optional)

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

3. Publish Views (Optional)

If you want to customize the component views:

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

4. Set Your API Key

Add your GIS.PH API key to your .env file:

GISPH_API_KEY=your_api_key_here

Get your API key from the GIS.PH Dashboard.

Usage

Basic Usage

<livewire:barangay-search
    wire:model="selectedBarangay"
    label="Select Barangay"
    placeholder="Search for a barangay..."
/>

With Form Integration (e.g. Mary UI Form)

<x-form wire:submit="save">
    <x-input label="Name" wire:model="name" />

    <livewire:barangay-search
        wire:model="form.barangay"
        label="Barangay"
        :required="true"
        hint="Start typing to search"
    />

    <x-slot:actions>
        <x-button label="Cancel" link="/dashboard" />
        <x-button label="Save" type="submit" spinner="save" />
    </x-slot:actions>
</x-form>

Listening to Livewire Events

<livewire:barangay-search wire:model="barangay" />

@script
<script>
    $wire.on('barangay-selected', (event) => {
        console.log('Selected:', event.barangay);
        // Do something with the selected barangay object
    });

    $wire.on('barangay-cleared', () => {
        console.log('Selection cleared');
    });

    $wire.on('barangay-search-error', (event) => {
        console.error('Search error:', event.error);
    });
</script>
@endscript

Component Props

Prop	Type	Default	Description
wire:model	mixed	null	Bind the selected barangay.
label	string	''	Label text above the input.
placeholder	string	Config value	Placeholder text for the input.
required	boolean	false	Mark field as required.
clearable	boolean	true	Show clear button.
hint	string	''	Helper text below the input.
municipalityCode	string	null	Filter results by municipality code.
cityCode	string	null	Filter results by city code.
provinceCode	string	null	Filter results by province code.
containerClass	string	''	Additional CSS classes for container.
inputClass	string	''	Additional CSS classes for input.

Advanced Customizations

Filtering by Municipality / Province

<!-- Filter by Province Code -->
<livewire:barangay-search
    wire:model="barangay"
    :province-code="$selectedProvinceCode"
    label="Select Barangay"
/>

Disabling Mary UI Styling

If you prefer to style the component using vanilla Tailwind CSS/CSS instead of Mary UI components, disable it in config/barangay-search.php:

config/barangay-search.php

'ui' => [
    'use_mary_ui' => false,
],

Response Format

When a barangay is selected, the component binds an array structure:

[
    'code' => '0701201001',
    'name' => 'Bahi',
    'municipality' => 'Alburquerque',
    'municipality_code' => '0701201000',
    'city' => null,
    'city_code' => null,
    'province' => 'Bohol',
    'province_code' => '0701200000',
    'region' => 'Central Visayas',
    'region_code' => '0700000000',
    'full_address' => 'Bahi, Alburquerque, Bohol',
]

Caching

To optimize and speed up requests, the package caches query results. You can clear cached queries using the service:

use YahaayLabs\LaravelBarangaySearch\Services\BarangayService;

app(BarangayService::class)->clearCache();