The province model is based on the ISO 3166-2 standard. The purpose of the standard is to define codes for identifying the subdivisions (e.g., provinces or states) of countries.

Although the name of the model/table is Province it actually supports multiple types of country subdivisions like states, counties, territories, municipalities, etc. See Province Types for a list of predefined types.

Database Table Fields

Table name: provinces

Name Type Details
id autoinc
country_id char(2) fk -> countries
parent_id int fk -> self
type enum, ProvinceType
code string(16) ISO 3166-2 Code
name string -


Name Type Returns
country Country The country the province belongs to
parent Province|null The parent province (if any)
children Collection Collection of child provinces (if any)

Retrieving Models

Locate by Country and Code

The findByCountryAndCode static method returns a single province by country and the province's code:

$brasov = Province::findByCountryAndCode('RO', 'BV');
// or
$romania = Country::find('RO');
$brasov = Province::findByCountryAndCode($romania, 'BV');

If no results are found, null is returned:

$zdish = Province::findByCountryAndCode('DE', 'XY');

Locate by Country

The predefined byCountry scope can fetch provinces by country:

$statesOfGermany = Province::byCountry('DE')->get();

// Can also pass a country model:
$holland = Country::find('NL');
$provincesOfHolland = Province::byCountry($holland)->get();

Locate by Type

The predefined byType scope can fetch provinces by type:

$counties = Province::byType('county')->get();

// Can also pass a ProvinceType enum object:
$states = Province::byType(ProvinceType::STATE())->get();

// Scopes can be combined:
$regionsOfBelgium = Province::byCountry('BE')->byType('region')->get();

Parents and Children

Countries can be divided into subdivisions of subdivisions, like:

  • Counties within States (eg. USA)
  • Provinces within Geographical units (eg. Indonesia)
  • Provinces within Regions (eg. Belgium)

To support these, provinces can optionally have a single parent and/or one or more children. Parent & Children are also the same Province type models.

Specifying Parent Province

$jawa = Province::create([
    'country_id' => 'ID',
    'name' => 'Jawa',
    'type' => ProvinceType::UNIT()

$banten = Province::create([
    'country_id' => 'ID',
    'name' => 'Banten',
    'type' => ProvinceType::PROVINCE(),
    'parent_id' => $jawa->id

echo $banten->parent->name;
// Jawa

// bool(false)

Other than setting the parent_id field directly, it is also possible to call the setter method:


To dissociate the parent use:



Child Provinces

Provinces can have multiple children.

The children property returns a Collection of child provinces.

$flanders = Province::findByCountryAndCode('BE', 'VLG');

foreach ($flanders->children as $flemishRegion) {
    echo "{$flemishRegion->name}\n";
// Antwerp
// East Flanders
// Flemish Brabant
// Limburg
// West Flanders


The package contains several province/state seeders for various countries.

For more details refer to the seeders section for more details.