Download the PHP package denprog/meridian without Composer

Meridian is a comprehensive Open-Source package for Laravel (11.x, 12.x) designed to provide developers with intuitive tools and structured data for working with countries, continents, currencies (including exchange rates), and languages. Simplify internationalization, localization, and geo-dependent features in your applications with an elegant API and a well-thought-out architecture.

Requirements

• PHP 8.3+
• Laravel 11.x or 12.x

Compatibility Matrix

Installation & Setup

1. Install via Composer

2. Run the Install Command

This command publishes the configuration file and migrations.

3. Install Core Data

This one-time command seeds the database with essential data for countries, currencies, and languages.

4. Configure Your Environment

After publishing, the main configuration file is config/meridian.php. For GeoIP lookups, you must get a free MaxMind account and add your credentials to your .env file:

5. Schedule Data Updates

To keep your data current, define the schedule in your application's routes/console.php file.

Alternatively, you can define the schedule in your bootstrap/app.php file:

Artisan Commands

Meridian provides several Artisan commands to manage your data:

Exchange Rate Command Options:

• --base - Specify the base currency code (default: from config)
• --targets - Specify target currencies (can be used multiple times)
• --date - Fetch rates for a specific date (format: YYYY-MM-DD)
• --dry-run - Validate and print execution plan without updating rates
• --retries - Number of retries for failed update attempts
• --retry-delay - Delay (ms) between retries
• --lock-seconds - Lock lifetime to prevent overlapping runs

GeoIP Command Options:

• --dry-run - Validate configuration and show execution plan only
• --retries - Number of retries for archive download
• --retry-delay - Delay (ms) between retries
• --lock-seconds - Lock lifetime to prevent overlapping runs

Usage

Meridian provides a simple and elegant API through facades and global helper functions.

Country Data

Geolocation

Currency Management

Currency Conversion

Updating Exchange Rates Manually

While it's recommended to update rates via the scheduled Artisan command, you can also trigger an update manually using the MeridianUpdateExchangeRate facade. This will fetch and save the latest rates for all active currencies defined in your config/meridian.php file.

Language Management

Global Helper Functions

The package also includes lightweight global helpers.

Troubleshooting

• meridian:doctor reports missing base/default entities:
  • Run php artisan meridian:install-data and verify config/meridian.php values.
• GeoIP update fails with authentication/configuration errors:
  • Check MAXMIND_ACCOUNT_ID, MAXMIND_LICENSE_KEY, and optional MERIDIAN_GEOIP_DB_SHA256.
• GeoIP update says lock is already acquired:
  • Wait for the running task to finish or reduce lock time in meridian.commands.update_geoip_db.lock_seconds.
• Exchange rate update keeps failing:
  • Run with --dry-run, then increase retries (--retries, --retry-delay) and verify provider URL.
• CI security audit fails:
  • Run composer security:audit locally and update vulnerable dependencies.