PHPackages                             mgamadeus/ddd-common-political - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mgamadeus/ddd-common-political

ActiveLibrary[Utility & Helpers](/categories/utility)

mgamadeus/ddd-common-political
==============================

Countries, languages, locales, political regions, states, localities for mgamadeus/ddd

1.0.12(1mo ago)0145↓25%2MITPHP

Since Apr 14Pushed 1mo agoCompare

[ Source](https://github.com/mgamadeus/ddd-political)[ Packagist](https://packagist.org/packages/mgamadeus/ddd-common-political)[ RSS](/packages/mgamadeus-ddd-common-political/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (14)Used By (2)

mgamadeus/ddd-common-political
==============================

[](#mgamadeusddd-common-political)

Countries, languages, locales, political regions, states, and localities for the [mgamadeus/ddd](https://github.com/mgamadeus/ddd) framework.

Installation
------------

[](#installation)

```
composer require mgamadeus/ddd-common-political
```

What it does
------------

[](#what-it-does)

Reference data entities for political geography and localization:

- **Country** — 236 countries with multilingual names, ISO codes, TLD, phone prefix, address formatting, political region mapping
- **PoliticalRegion** — hierarchical regions (6 continents → 15 sub-regions) with UN M49 codes
- **State** — administrative area level 1 with geocoding support
- **Locality** — city/town with GeoPoint, placeId, proximity search
- **Language** — 66 languages (ISO 639-1/3, text direction, script codes)
- **Locale** — 312 language+country combinations with date/time formats
- **County / SubCounty** — administrative levels 2 and 3 (value objects)

Configuration (seed data)
-------------------------

[](#configuration-seed-data)

The module ships with comprehensive seed data in `config/app/Common/Political/`:

FileContents`Countries.php`236 countries with multilingual names (20+ translations each), ISO codes, political region mapping, address settings`Languages.php`66 languages across 5 tiers with multilingual names, script codes`Locales.php`312 locale entries with date/time format rules`PoliticalRegions.php`6 continents + 15 sub-regions with UN M49 codes### Overriding config

[](#overriding-config)

Place a file at the same path in your project's `config/app/Common/Political/` to override. Project config is searched before module config.

For example, to add a custom country or change an existing entry, create `config/app/Common/Political/Countries.php` in your project with the full array — it replaces the module's version entirely.

Service registration
--------------------

[](#service-registration)

Add to your project's `services.yaml`:

```
# DDD Module: ddd-common-political
DDD\Domain\Common\Services\PoliticalEntities\:
    resource: '%kernel.project_dir%/vendor/mgamadeus/ddd-common-political/src/Domain/Common/Services/PoliticalEntities/*'
    public: true

DDD\Domain\Common\Services\Languages\:
    resource: '%kernel.project_dir%/vendor/mgamadeus/ddd-common-political/src/Domain/Common/Services/Languages/*'
    public: true
```

Importing seed data
-------------------

[](#importing-seed-data)

The module provides services with `importFromConfig()` methods. Create admin endpoints in your app that call these services:

```
// Import political regions (must run first — countries reference them)
$politicalRegionsService = PoliticalRegion::getService();
$regions = $politicalRegionsService->importPoliticalRegionsFromConfig();

// Import countries (resolves political region slugs to IDs)
$countriesService = Country::getService();
$countries = $countriesService->importCountriesFromConfig($politicalRegionsService);

// Import languages
$languagesService = Language::getService();
$languages = $languagesService->importLanguagesFromConfig();

// Import locales (resolves languageId and countryId)
$localesService = Locale::getService();
$locales = $localesService->importLocalesFromConfig($languagesService, $countriesService);
```

### Import order

[](#import-order)

1. **PoliticalRegions** first (countries reference them)
2. **Countries** second (locales reference them)
3. **Languages** third (locales reference them)
4. **Locales** last (references both countries and languages)

Geocoding (via Argus)
---------------------

[](#geocoding-via-argus)

States and localities can be geocoded via the Argus API:

- `ArgusState` — `POST:/common/geodata/geocodeState` (1-month cache)
- `ArgusLocality` — `POST:/common/geodata/geocodeCity` (1-month cache)

These require `ARGUS_API_ENDPOINT` to be configured (see [ddd-argus](https://github.com/mgamadeus/ddd-argus)).

Overriding entities
-------------------

[](#overriding-entities)

Extend any entity in your project using the standard DDD override mechanism:

```
// App\Domain\Common\Entities\PoliticalEntities\Countries\Country
namespace App\Domain\Common\Entities\PoliticalEntities\Countries;

use DDD\Domain\Common\Entities\PoliticalEntities\Countries\Country as BaseCountry;

class Country extends BaseCountry
{
    public bool $requiresEnhancedVerification = false;
}
```

No `services.yaml` entry needed — the `DDD\ → App\` fallback resolves it automatically.

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance92

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

13

Last Release

40d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2896811?v=4)[mgamadeus](/maintainers/mgamadeus)[@mgamadeus](https://github.com/mgamadeus)

---

Top Contributors

[![mgamadeus](https://avatars.githubusercontent.com/u/2896811?v=4)](https://github.com/mgamadeus "mgamadeus (14 commits)")

### Embed Badge

![Health badge](/badges/mgamadeus-ddd-common-political/health.svg)

```
[![Health](https://phpackages.com/badges/mgamadeus-ddd-common-political/health.svg)](https://phpackages.com/packages/mgamadeus-ddd-common-political)
```

###  Alternatives

[vespakoen/menu

Managing menus the easy way.

27187.0k5](/packages/vespakoen-menu)[laravel-enso/menus

Menu management for Laravel Enso

1643.5k22](/packages/laravel-enso-menus)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)