Laravel States Col Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require anvargear/laravel-states-col
   

   For Laravel 5.5+, no manual app.php edits are needed. For older versions, add the provider and alias as shown in the README.

2. Publish Config (Optional):

   php artisan vendor:publish --provider="AnvaGear\States\StatesServiceProvider"
   

   This generates a migration and config file (default table name: Colstates).

3. Run Migration:

   php artisan migrate
   

4. First Use Case: Fetch all departments or cities:

   use StatesCol;
   
   // Get all departments (states)
   $departments = StatesCol::departments();
   
   // Get all cities for a department (e.g., Bogotá's department code: 11)
   $cities = StatesCol::cities(11);
   

Implementation Patterns

Core Workflows

1. Data Retrieval:

   • Departments: Fetch all departments with their codes, names, and capitals.

     $departments = StatesCol::departments();
     

   • Cities by Department: Retrieve cities for a specific department (using dane_code).

     $cities = StatesCol::cities($departmentDaneCode);
     

   • Single Department: Get a single department by dane_code.

     $department = StatesCol::department($departmentDaneCode);
     

   • Single City: Get a single city by dane_code.

     $city = StatesCol::city($cityDaneCode);
     

2. Integration with Eloquent Models: Add a relationship to your model (e.g., User, Company):

   public function department()
   {
       return $this->belongsTo(Department::class, 'department_id');
   }
   

   Use the facade to populate dropdowns or validate inputs:

   $departmentOptions = StatesCol::departments()->pluck('name', 'dane_code');
   

3. Form Validation: Validate department/city codes or names:

   use Illuminate\Support\Facades\Validator;
   
   $validator = Validator::make($request->all(), [
       'department_code' => 'required|exists:Colstates,dane_code',
       'city_code' => 'required|exists:Colstates,dane_code',
   ]);
   

4. Caching: Cache department/city data for performance (e.g., in AppServiceProvider):

   public function boot()
   {
       Cache::remember('colombia_states', now()->addDays(30), function () {
           return StatesCol::departments();
       });
   }
   

Advanced Patterns

1. Custom Queries: Extend the facade or service provider to add custom queries (e.g., search by name):

   // In a service class or facade extension
   public static function searchDepartments($query)
   {
       return self::departments()->where('name', 'like', "%{$query}%");
   }
   

2. API Responses: Return standardized responses for APIs:

   return response()->json([
       'data' => StatesCol::departments(),
       'meta' => ['count' => StatesCol::departments()->count()]
   ]);
   

3. Localization: Use the data for localized content (e.g., region-specific features):

   $currentDepartment = StatesCol::department($user->department_id);
   return view('welcome', ['region' => $currentDepartment->name]);
   

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If the default table name (Colstates) conflicts with existing tables, rename it via config after publishing:

     // config/states.php
     'table' => 'custom_col_states',
     

   • Run php artisan migrate:fresh if the table already exists.

2. Data Accuracy:

   • The package provides "almost ISO 3166-3" data. Verify critical codes (e.g., dane_code) against official sources (e.g., DANE Colombia).
   • Example: Bogotá’s dane_code is 11 (correct), but cross-check other regions.

3. Facade vs. Service Container:

   • Avoid instantiating the service directly; use the StatesCol facade for consistency:

     // Bad: Direct instantiation
     $service = app('states');
     
     // Good: Facade
     $departments = StatesCol::departments();
     

4. Laravel Version Compatibility:

   • The package is labeled dev-master and lacks Laravel version constraints. Test thoroughly in your Laravel version (e.g., 8/9/10). For older versions (<5.5), manual app.php edits are required.

Debugging Tips

1. Check Published Files:

   • After publishing, verify database/migrations/ and config/states.php for customizations.

2. Query Logs:

   • Enable query logging to debug slow or missing data:

     DB::enableQueryLog();
     $departments = StatesCol::departments();
     dd(DB::getQueryLog());
     

3. Data Dumps:

   • Dump raw data to inspect structure:

     dd(StatesCol::departments()->first()->toArray());
     

Extension Points

1. Custom Attributes: Add computed attributes to models (e.g., full department name with code):

   // In Department model
   public function getFullNameAttribute()
   {
       return "{$this->dane_code} - {$this->name}";
   }
   

2. Service Provider Extensions: Bind additional methods to the service container in StatesServiceProvider:

   $this->app->bind('states', function () {
       return new StatesManager(); // Custom class
   });
   

3. Testing: Mock the facade in tests:

   StatesCol::shouldReceive('departments')->once()->andReturn(collect([...]));
   

4. Seeding: Seed the Colstates table manually if needed:

   // database/seeds/ColstatesSeeder.php
   public function run()
   {
       DB::table('Colstates')->insert([...]);
   }