Download the PHP package manguithre/faker-madagascar without Composer

Faker Madagascar

Generate realistic Madagascar-specific test data for Laravel and PHP applications.

Faker Madagascar provides Malagasy names, structured geographical addresses, operator-aware mobile phone numbers and CIN-formatted values.

The package includes:

• 23 regions.
• 119 districts.
• 1,704 communes.
• 20,688 fokontany names.

If you already know FakerPHP's fake() helper, you can start using this package immediately.

Generated data is intended for development, testing and database seeding. It does not represent real individuals or officially issued documents.

Features

• Malagasy first names, last names and full names.
• Hierarchical addresses: region, district, commune and fokontany.
• 23 regions, 119 districts, 1,704 communes and 20,688 fokontany names.
• Malagasy mobile numbers using supported operator prefixes.
• CIN-formatted values with 12 digits.
• Laravel validation rules for phone numbers and CIN values.
• Laravel factories and seeders integration.
• FakerPHP integration through fake()->malagasy*().
• Artisan preview command.
• JSON and CSV export.
• Region filtering through configuration.
• Standalone PHP support without Laravel.
• Case-insensitive region lookup.

Requirements

• PHP 8.2 or higher.
• Laravel 11, 12 or 13.
• FakerPHP ^1.21 only if you want to use the fake()->malagasy*() integration.

In a standard Laravel application, FakerPHP is usually already installed.

Installation

Install the package with Composer:

The service provider and the FakerMg facade alias are registered through Laravel package discovery. No manual registration is required.

The fakerMg() helper is available immediately after installation.

Quick start

After installing the package, use the fakerMg() helper anywhere in your Laravel application:

Usage styles

All usage styles resolve to the same Faker Madagascar service inside Laravel.

Using the fakerMg() helper

The helper is the recommended usage style:

The helper works in:

• Routes.
• Controllers.
• Models and factories.
• Seeders.
• Artisan commands.
• Tinker.
• Console applications.

Using the facade

Laravel registers the facade alias automatically when package discovery is enabled.

Using dependency injection

Using FakerPHP

If FakerPHP is installed, the package registers a provider on Laravel's Faker generator. This allows you to mix standard FakerPHP data with Madagascar-specific data in the same call chain:

Note: The malagasy*() methods are available when Faker's generator is resolved through Laravel's container, for example with fake() or app(Faker\Generator::class). A generator created directly with Faker\Factory::create() does not automatically include this provider.

Example:

API reference

Return types shown above should match the actual public API of the installed package version.

Generating addresses

Random address

The address object can be converted to a string:

It can also be converted to an array:

Force a region

The district, commune and fokontany are selected consistently from the specified region.

Region names are case-insensitive:

These values refer to the same region.

Force a district

Force a commune

Region names are resolved case-insensitively. District and commune names must match the names available in the dataset.

For example:

is valid, while this value may not be valid if exact matching is required:

Unknown regions, districts or communes throw:

Browse the geographical hierarchy

Address object

The address() method returns a structured address object.

Typical properties:

Convert the object to an array:

Convert the object to a formatted string:

The formatted string follows this structure:

Generating names

Names are generated from curated Malagasy name lists. They are intended to look natural for testing and development purposes.

Generated names are not guaranteed to correspond to real people.

Generating contact data

Phone numbers

You can optionally select an operator:

Supported prefixes:

The currently supported prefixes are:

Phone prefixes were checked against the ARTEC national numbering plan, international numbering tables and available operator announcements.

The prefix dataset may need to be updated when the Malagasy numbering plan changes.

Phone numbers generated by this package are intended for testing and seeding. They should not be used to contact real people.

CIN values

The generated value contains 12 digits without separators.

CIN generation is intended for testing only. The package does not verify whether a CIN was officially issued or belongs to a real person.

Laravel factories and seeders

The package can be used directly inside Laravel factories:

Create 100 employees:

Important factory note

Generate values inside the factory definition so that every row receives fresh data.

Avoid calculating values once and reusing them:

The factory definition or a loop in a seeder should call fakerMg() for each record.

Seeder example

Validation rules

The package provides Laravel validation rules for Malagasy phone numbers and CIN values.

MalagasyPhoneNumber

The phone validation rule accepts formats such as:

It validates the Malagasy mobile format and supported operator prefixes.

MalagasyCin

The CIN validation rule accepts a 12-digit Malagasy CIN format.

Separators are tolerated and stripped before validation:

The rule validates the format only. It does not verify whether the CIN belongs to a real person or was officially issued.

Artisan command

The package includes an Artisan command for previewing generated data.

Generate random addresses

Generate random persons

Generate contact data

Export to JSON

Export to CSV

Export files are written to the system temporary directory. The command displays the generated file path after the export is completed.

Configuration

Publish the configuration file:

The configuration file is:

Restrict random generation to selected regions

With this configuration, random address generation only uses the selected regions:

Forcing an inactive region throws an exception:

Region names in the configuration are case-insensitive:

Using the package outside Laravel

The core service can also be used in a plain PHP application:

When Laravel is not available, the helper falls back to a standalone FakerMadagascar instance.

You can also instantiate the service directly:

Testing the package in a fresh Laravel application

Create a fresh Laravel application:

If you are testing a local checkout of the package, configure the local Composer repository:

Install the local development version:

Then add a test route in routes/web.php:

Start the development server:

Open the displayed local URL and visit:

Testing

Run the test suite with:

You can also run the package tests directly if the project provides a PHPUnit configuration:

Data sources

The package includes the following geographical data:

• 23 regions.
• 119 districts.
• 1,704 communes.
• 20,688 fokontany names.

The geographical dataset is sourced from julkwel/madagascar-map, released under the MIT License.

After updating the source geography files, rebuild the generated dataset with:

Phone prefixes are maintained using information from the ARTEC national numbering plan and other available Malagasy operator and numbering references.

Contributing

Contributions, corrections and improvements are welcome.

Before opening a pull request:

When contributing geographical data, please include the source and explain the reason for the change.

For new public methods, include:

• Tests.
• PHPDoc or README documentation.
• A usage example.
• Any relevant backward-compatibility considerations.

Versioning

This package follows semantic versioning whenever possible.

Breaking changes may require a major version update. Check the changelog and release notes before upgrading between major versions.

Credits

• Geographical data from julkwel/madagascar-map, released under the MIT License.
• Phone prefix references from ARTEC and Malagasy telecom resources.
• FakerPHP for the original Faker provider concept and ecosystem.

License

This package is open-sourced software licensed under the MIT License.

See the LICENSE file for more information.