Location Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require bulutyazilim/location-bundle
   

   Publish the migrations and config:

   php artisan vendor:publish --provider="Bulutyazilim\LocationBundle\LocationBundleServiceProvider"
   

   Run migrations:

   php artisan migrate
   

2. First Use Case Access the Country and City models directly:

   use Bulutyazilim\LocationBundle\Entity\Country;
   use Bulutyazilim\LocationBundle\Entity\City;
   
   $countries = Country::all();
   $cities = City::where('country_id', 1)->get();
   

3. Where to Look First

   • Entities: src/Entity/Country.php and src/Entity/City.php for model structure.
   • Migrations: database/migrations/ for schema details.
   • Service Provider: LocationBundleServiceProvider.php for bootstrapping logic.

Implementation Patterns

Basic Workflows

1. Data Retrieval Fetch countries with eager-loaded cities:

   $countries = Country::with('cities')->get();
   

2. Form Integration Use in Laravel Collective or Livewire forms:

   // Example for Laravel Collective
   <select name="country_id">
       @foreach(Country::all() as $country)
           <option value="{{ $country->id }}">{{ $country->name }}</option>
       @endforeach
   </select>
   

3. API Responses Return structured location data:

   return response()->json([
       'countries' => Country::with('cities')->get()
   ]);
   

Integration Tips

• Validation: Use custom rules for country/city IDs:

  use Illuminate\Validation\Rule;
  
  $validator = Validator::make($request->all(), [
      'country_id' => ['required', Rule::exists('countries', 'id')],
      'city_id' => ['required', Rule::exists('cities', 'id')->where('country_id', $request->country_id)],
  ]);
  

• Caching: Cache country/city lists if static:

  $countries = Cache::remember('location.countries', 60*24, function() {
      return Country::all();
  });
  

• Localization: Extend entities for multilingual support:

  // Add translatable fields (e.g., name_en, name_tr) and handle in models.
  

Gotchas and Tips

Pitfalls

1. Outdated Codebase

   • Last release in 2016; test thoroughly for Laravel 5.x/6.x compatibility.
   • Potential issues with Eloquent conventions (e.g., created_at vs. date_created).

2. Missing Features

   • No built-in search/filtering for locations. Implement manually:

     Country::where('name', 'like', '%USA%')->get();
     

   • No geolocation or distance calculations. Use a separate package (e.g., spatie/laravel-geolocation) if needed.

3. Database Schema

   • Assumes cities table has country_id foreign key. Verify migrations match your needs.

Debugging

• Model Not Found: Ensure the LocationBundleServiceProvider is registered in config/app.php.
• Migration Errors: Check for reserved keywords (e.g., order as a column name). Rename if conflicts arise.

Extension Points

1. Custom Fields Extend entities via traits or inheritance:

   namespace App\Models;
   
   use Bulutyazilim\LocationBundle\Entity\Country as BaseCountry;
   
   class Country extends BaseCountry {
       protected $table = 'custom_countries';
   }
   

2. API Resources Create custom resources for API responses:

   php artisan make:resource CountryResource
   

3. Seeding Seed initial data via DatabaseSeeder:

   $this->call([
       Bulutyazilim\LocationBundle\Database\Seeders\CountrySeeder::class,
       Bulutyazilim\LocationBundle\Database\Seeders\CitySeeder::class,
   ]);
   

Configuration Quirks

• No Config File: Bundle uses default table names (countries, cities). Override in AppServiceProvider:

  Country::setTable('my_custom_countries');