Countries (الدول)

Countries are read-only reference data seeded into the system. Each country includes a phone code and can contain multiple governorates (states/provinces). Countries are used throughout the system for address management, phone number formatting, and regional configuration.

Purpose

• Provide standardized country reference data for the entire system
• Support bilingual names (English and Arabic) for the target markets
• Include phone codes for phone number validation and formatting
• Organize governorates (sub-regions) under each country

---

Entity Attributes

Country

Field	Type	Description
id	integer	Primary key
code	string	ISO country code (e.g., KW, EG)
name	string	Country name (English)
name_ar	string	Country name (Arabic)
phone_code	string	International dialing code (e.g., +965)
is_active	boolean	Active status
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Governorate

Field	Type	Description
id	integer	Primary key
country_id	FK	Parent country
name	string	Governorate name (English)
name_ar	string	Governorate name (Arabic)
code	string	Governorate code
is_active	boolean	Active status
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Relationships

API Endpoints

Method	Path	Description
GET	/api/core/countries	List all countries with governorates
GET	/api/core/countries/{country}	Get a country with its governorates

Query Parameters for GET /api/core/countries

Parameter	Type	Description
active	boolean	Filter by active status

Request/Response Examples

List Countries

curl

curl -X GET "/api/core/countries?active=true" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Dart

final response = await dio.get('/api/core/countries', queryParameters: {
  'active': true,
});

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "code": "KW",
      "name": "Kuwait",
      "name_en": "Kuwait",
      "name_ar": "الكويت",
      "phone_code": "+965",
      "is_active": true,
      "governorates": [
        {
          "id": 1,
          "country_id": 1,
          "name": "Al Asimah",
          "name_en": "Al Asimah",
          "name_ar": "العاصمة",
          "code": "KW-KU",
          "is_active": true
        },
        {
          "id": 2,
          "country_id": 1,
          "name": "Hawalli",
          "name_en": "Hawalli",
          "name_ar": "حولي",
          "code": "KW-HA",
          "is_active": true
        }
      ],
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z"
    },
    {
      "id": 2,
      "code": "EG",
      "name": "Egypt",
      "name_en": "Egypt",
      "name_ar": "مصر",
      "phone_code": "+20",
      "is_active": true,
      "governorates": [
        {
          "id": 10,
          "country_id": 2,
          "name": "Cairo",
          "name_en": "Cairo",
          "name_ar": "القاهرة",
          "code": "EG-C",
          "is_active": true
        }
      ],
      "created_at": "2026-01-01T00:00:00.000000Z",
      "updated_at": "2026-01-01T00:00:00.000000Z"
    }
  ]
}

Get Single Country

curl

curl -X GET /api/core/countries/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Dart

final response = await dio.get('/api/core/countries/1');

Response 200 OK

{
  "data": {
    "id": 1,
    "code": "KW",
    "name": "Kuwait",
    "name_en": "Kuwait",
    "name_ar": "الكويت",
    "phone_code": "+965",
    "is_active": true,
    "governorates": [
      {
        "id": 1,
        "country_id": 1,
        "name": "Al Asimah",
        "name_en": "Al Asimah",
        "name_ar": "العاصمة",
        "code": "KW-KU",
        "is_active": true
      }
    ],
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  }
}

Business Rules

1. Read-only -- countries are seeded reference data. There are no create, update, or delete endpoints. Data is managed via database seeders.
2. Governorates included -- both the list and show endpoints eagerly load governorates for each country.
3. Localized names -- the name field in the response returns the locale-appropriate name (Arabic or English). name_en and name_ar are always included for explicit access.
4. Active filter -- pass active=true to filter to only active countries. Without the filter, all countries are returned.
5. Not paginated -- the list endpoint returns all countries as a flat collection (not paginated), since the dataset is small and static.
6. Ordered by name -- countries are returned sorted alphabetically by English name.
7. No authentication required for data -- while the endpoint requires authentication (Sanctum), no specific permission is enforced since this is public reference data.