Countries Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require pragmarx/countries
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Fetch all countries with their ISO codes and names:

   use Pragmarx\Countries\Countries;
   
   $countries = Countries::all();
   // Returns a collection of Country objects with properties like `name`, `iso2`, `iso3`, etc.
   

3. Where to Look First:

   • API Reference: Documentation (check the README for methods like all(), get(), where(), etc.).
   • Country Object: Inspect the Country class structure (e.g., $country->iso2, $country->currencies).
   • Examples: The Usage section in the README.

Implementation Patterns

Core Workflows

1. Fetching Data:

   • All Countries:

     $countries = Countries::all(); // Collection of Country objects
     

   • Single Country by ISO Code:

     $country = Countries::get('US'); // Returns a Country object for the US
     

   • Filtering:

     $europeanCountries = Countries::where('continent', 'Europe')->get();
     

2. Integration with Laravel:

   • Service Provider Binding (optional, for reusable access):

     // In AppServiceProvider@boot()
     $this->app->singleton('countries', function () {
         return new \Pragmarx\Countries\Countries();
     });
     

     Then inject via constructor or resolve:

     $countries = app('countries')->get('BR');
     

3. Common Use Cases:

   • Dropdown Lists:

     $options = Countries::all()->pluck('name', 'iso2')->toArray();
     

   • Validation Rules:

     use Illuminate\Validation\Rule;
     
     $validator->addRules([
         'country_code' => ['required', Rule::in(Countries::all()->pluck('iso2')->toArray())],
     ]);
     

   • Localization:

     $country = Countries::get('JP');
     $locale = $country->locale; // e.g., 'ja_JP'
     

4. Lazy Loading: Use get() for single countries or where() for filtered subsets to avoid loading all data unnecessarily.

Gotchas and Tips

Pitfalls

1. Case Sensitivity:

   • ISO codes (e.g., 'US', 'us') are case-sensitive in get(). Always use uppercase:

     $country = Countries::get('US'); // Correct
     $country = Countries::get('us'); // Returns null
     

2. Data Mutability:

   • The Country objects are immutable by default. Avoid modifying properties directly (e.g., $country->name = 'New Name'). Use methods like setName() if available (check the API).

3. Memory Usage:

   • Countries::all() loads all 250+ countries into memory. For large applications, cache the result:

     $countries = Cache::remember('all_countries', now()->addDays(30), function () {
         return Countries::all();
     });
     

4. Deprecated Methods:

   • Some older versions used Countries::iso() or Countries::name(). Prefer Countries::get('ISO') for clarity.

Debugging Tips

1. Verify ISO Codes:

   • Use Countries::all()->pluck('iso2') to list all valid codes before debugging missing data.

2. Check for Updates:

   • The package is actively maintained. Run composer update pragmarx/countries if you encounter missing countries/currencies.

3. Custom Data:

   • Extend the Country class or use traits to add custom properties:

     class ExtendedCountry extends \Pragmarx\Countries\Country {
         public function getPhoneCode() {
             return $this->phone_code ?? 'N/A';
         }
     }
     

     Then override the factory or use composition.

Extension Points

1. Add Custom Fields:

   • Override the Country class or use a wrapper:

     class CustomCountry {
         public function __construct(private \Pragmarx\Countries\Country $country) {}
     
         public function getRegion() {
             return $this->country->subregion ?? 'N/A';
         }
     }
     

2. Local Overrides:

   • Replace the package’s data file (countries.php) in vendor/pragmarx/countries/src/Data/ (not recommended for production; use a fork instead).

3. Testing:

   • Mock the Countries class in tests:

     $mockCountries = Mockery::mock(\Pragmarx\Countries\Countries::class);
     $mockCountries->shouldReceive('get')->with('BR')->andReturn(new Country(['iso2' => 'BR']));
     $this->app->instance(\Pragmarx\Countries\Countries::class, $mockCountries);
     

4. Performance:

   • For read-heavy apps, serialize the data to a database table or cache:

     // One-time setup
     Countries::all()->each(function ($country) {
         \App\Models\Country::updateOrCreate(
             ['iso2' => $country->iso2],
             ['name' => $country->name]
         );
     });