PHPackages vormia-folks/atu-multi-currency - 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. vormia-folks/atu-multi-currency ActiveLibrary vormia-folks/atu-multi-currency =============================== ATU Multi Currency - A package for Laravel that provides multi currency support for your e-commerce website. v1.0.2(4mo ago)069↓100%MITPHPPHP ^8.2 Since Jan 8Pushed 2mo agoCompare [ Source](https://github.com/vormia-folks/atu-multi-currency)[ Packagist](https://packagist.org/packages/vormia-folks/atu-multi-currency)[ RSS](/packages/vormia-folks-atu-multi-currency/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (6)Dependencies (4)Versions (8)Used By (0) ATU Multi-Currency ================== [](#atu-multi-currency) Laravel 12 package that provides currency normalization, conversion, display, and reporting support for A2 Commerce. This package extends A2Commerce functionality while keeping A2 core tables simple and authoritative. Introduction ------------ [](#introduction) ATU Multi-Currency is a comprehensive Laravel package designed to provide multi-currency support for e-commerce applications built on A2Commerce. The package acts as a projection layer that converts, decorates, logs, and reports currency conversions without mutating the core A2Commerce data. The package follows a core principle: **A2 Commerce owns truth** - all prices stored in A2Commerce tables remain in the base system currency, while ATU Multi-Currency handles all conversion complexity, rate management, and reporting. Features -------- [](#features) - **Currency Management** - Support for multiple currencies with automatic or manual rate management - **Flexible Currency Codes** - Support for 3-4 character currency codes (ISO 4217 compatible, e.g., USD, EUR, ZAR) - **Currency Name Support** - Optional full descriptive names for currencies (e.g., "South African Rand", "United States Dollar") - **Smart Fallback Logic** - Automatic fallback between currency code and symbol if one is empty - **Conversion Logging** - Immutable audit trail of all currency conversions - **Rate History** - Track historical exchange rates for accurate reporting - **Fee Configuration** - Optional per-currency conversion fees - **Base Currency Seeding** - Automatic seeding from A2Commerce settings - **Projection Layer** - Convert and display prices without mutating core data - **Reporting Support** - Multi-currency financial reporting capabilities - **Event-Driven** - Integrates seamlessly with A2Commerce event system Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 12.x - Vormia 4.2+ (must be installed first) - A2Commerce 0.1.6+ (must be installed first) Dependencies ------------ [](#dependencies) ### Required Dependencies [](#required-dependencies) - **vormiaphp/vormia**: Required for core functionality and database structure - Used for user management, taxonomies, and meta data handling - See [Vormia installation guide](https://github.com/vormiaphp/vormia) for installation instructions - **a2-atu/a2commerce**: Required for e-commerce functionality - Provides the base commerce system that this package extends - See [A2Commerce installation guide](https://github.com/a2-atu/a2commerce) for installation instructions The package will automatically check for required dependencies during installation and provide helpful error messages if they're missing. Installation ------------ [](#installation) Before installing ATU Multi-Currency, ensure you have Laravel, Vormia, and A2Commerce installed. See the [A2Commerce installation guide](https://github.com/a2-atu/a2commerce) for detailed instructions on installing A2Commerce and its dependencies. ### Step 1: Install ATU Multi-Currency [](#step-1-install-atu-multi-currency) ``` composer require vormia-folks/atu-multi-currency ``` ### Step 2: Run ATU Multi-Currency Installation [](#step-2-run-atu-multi-currency-installation) ``` php artisan atumulticurrency:install ``` This will automatically install ATU Multi-Currency with all files and configurations: **Automatically Installed:** - ✅ All migration files copied to `database/migrations` - ✅ Seeder file copied to `database/seeders` - ✅ Configuration file copied to `config/atu-multi-currency.php` - ✅ Environment variables added to `.env` and `.env.example` - ✅ Currency routes (commented out) added to `routes/api.php` **Installation Options:** - `--no-overwrite`: Keep existing files instead of replacing them - `--skip-env`: Leave `.env` files untouched **Example:** ``` # Install without overwriting existing files php artisan atumulticurrency:install --no-overwrite # Install without modifying .env files php artisan atumulticurrency:install --skip-env ``` ### Step 3: Run Migrations and Seeders [](#step-3-run-migrations-and-seeders) The installation command will prompt you to run migrations and seeders. You can also run them manually: ``` # Run migrations php artisan migrate # Run seeders to create base currency php artisan db:seed --class=ATUMultiCurrencySeeder ``` The seeder will automatically read the base currency from `a2_ec_settings` table and create the default currency with a rate of 1.00000000. Available Commands ------------------ [](#available-commands) ### Install Command [](#install-command) Install the package with all necessary files and configurations: ``` php artisan atumulticurrency:install ``` **Options:** - `--skip-env`: Do not modify .env files - `--no-overwrite`: Skip existing files instead of replacing ### Refresh Command [](#refresh-command) Refresh migrations and seeders, clear caches: ``` php artisan atumulticurrency:refresh ``` **Options:** - `--force`: Skip confirmation prompts - `--seed`: Force re-seeding This command will: - Rollback and re-run migrations for `atu_multicurrency_*` tables - Re-run seeders to restore base currency - Clear all application caches ### Uninstall Command [](#uninstall-command) Remove all package files and configurations: ``` php artisan atumulticurrency:uninstall ``` **Options:** - `--keep-env`: Preserve environment variables - `--force`: Skip confirmation prompts **⚠️ Warning:** This will remove all ATU Multi-Currency files and optionally drop database tables. A backup will be created in `storage/app/atumulticurrency-final-backup-{timestamp}/`. ### Help Command [](#help-command) Display help information and usage examples: ``` php artisan atumulticurrency:help ``` Configuration ------------- [](#configuration) After installation, you can configure the package in `config/atu-multi-currency.php`: ``` return [ 'default_currency' => env('A2_CURRENCY', 'USD'), 'api' => [ 'key' => env('ATU_CURRENCY_API_KEY', ''), 'update_frequency' => env('ATU_CURRENCY_UPDATE_FREQUENCY', 'daily'), ], 'conversion' => [ 'apply_fees' => true, 'log_conversions' => true, 'round_precision' => 2, ], 'table_prefix' => 'atu_multicurrency_', ]; ``` Environment Variables --------------------- [](#environment-variables) The following environment variables are added to your `.env` file during installation: ``` # ATU Multi-Currency Configuration ATU_CURRENCY_API_KEY= ATU_CURRENCY_UPDATE_FREQUENCY=daily ATU_CURRENCY_SETTINGS_SOURCE=database ``` - `ATU_CURRENCY_API_KEY`: API key for automatic currency rate updates (optional) - `ATU_CURRENCY_UPDATE_FREQUENCY`: How often to update currency rates (daily, weekly, etc.) - `ATU_CURRENCY_SETTINGS_SOURCE`: Settings storage source - `database` (recommended) or `file` (config file). Set to `database` to enable database settings management. Database Tables --------------- [](#database-tables) The package creates three database tables with the `atu_multicurrency_` prefix: ### `atu_multicurrency_currencies` [](#atu_multicurrency_currencies) Holds supported currencies and conversion rules: - Currency code (ISO 4217, 3-4 characters: USD, EUR, ZAR) - Currency symbol (e.g., $, €, R) - Currency name (optional full descriptive name, e.g., "South African Rand") - Exchange rate - Fee configuration - Default currency flag - Active status **Note:** Currency code and symbol support automatic fallback - if one is empty, it will use the other automatically. ### `atu_multicurrency_currency_rates_log` [](#atu_multicurrency_currency_rates_log) Tracks historical exchange rates: - Currency reference - Rate value - Source (manual or API) - Timestamp ### `atu_multicurrency_currency_conversion_log` [](#atu_multicurrency_currency_conversion_log) Immutable audit trail of all conversions: - Entity type and ID - Conversion context - Base and target currencies - Amounts and rates used - Fees applied - User and timestamp Core Principles --------------- [](#core-principles) 1. **A2 Commerce owns truth** - Prices in A2Commerce tables are always in base currency 2. **ATU is a projection layer** - Converts, decorates, logs, and reports without mutating core data 3. **All complexity lives inside ATU** - Conversion history, rates, fees, and reporting 4. **Logs are immutable** - Never update conversion logs, always insert new rows Usage ----- [](#usage) ### Seeding Base Currency [](#seeding-base-currency) The package automatically seeds the base currency from A2Commerce settings during installation. The seeder reads: - `currency_code` from `a2_ec_settings` → `atu_multicurrency_currencies.code` - `currency_symbol` from `a2_ec_settings` → `atu_multicurrency_currencies.symbol` If `a2_ec_settings` doesn't exist, it defaults to USD/$. ### Default Currency Synchronization [](#default-currency-synchronization) The package automatically synchronizes the default currency with the `a2_ec_settings` table: - When you update the default currency's code or symbol in the admin panel, it automatically updates `a2_ec_settings.currency_code` and `a2_ec_settings.currency_symbol` - The default currency code must always match `a2_ec_settings.currency_code` - The default currency rate is always locked at 1.0 and cannot be changed - Only one currency can be set as default at any time **Important:** The default currency cannot be deleted or deactivated. To change the default currency, you must first set another currency as default, then update the previous default currency. ### Adding Additional Currencies [](#adding-additional-currencies) You can add additional currencies by inserting records into the `atu_multicurrency_currencies` table: ``` DB::table('atu_multicurrency_currencies')->insert([ 'code' => 'ZAR', // 3-4 character currency code (ISO 4217) 'symbol' => 'R', // Currency symbol 'name' => 'South African Rand', // Optional full descriptive name 'rate' => '130.50000000', 'is_auto' => true, 'fee' => null, 'is_default' => false, 'is_active' => true, 'created_at' => now(), 'updated_at' => now(), ]); ``` **Currency Code and Symbol:** - Currency codes support 3-4 characters (e.g., USD, EUR, ZAR) - If currency code is empty, the symbol will be used as the code automatically - If currency symbol is empty, the code will be used as the symbol automatically - At least one of code or symbol must be provided **Currency Name:** - Optional field for full descriptive names - Useful for display purposes and better user experience - Examples: "United States Dollar", "South African Rand", "Kenyan Shilling" UI Installation --------------- [](#ui-installation) After installing the base package, you can install the UI components: ``` php artisan atumulticurrency:ui-install ``` This will automatically: - Copy UI view files to `resources/views/livewire/admin/atu/` - Attempt to inject routes into `routes/web.php` - Attempt to inject sidebar menu items into `resources/views/components/layouts/app/sidebar.blade.php` - Clear application caches ### Manual Route Setup [](#manual-route-setup) If automatic route injection fails, manually add the following routes to `routes/web.php` inside the `Route::middleware(['auth'])->group(function () { ... })` block: ``` use Livewire\Volt\Volt; Route::prefix('admin/atu/currencies')->name('admin.atu.currencies.')->group(function () { // Currencies Volt::route('/', 'admin.atu.currencies.index')->name('index'); Volt::route('create', 'admin.atu.currencies.create')->name('create'); Volt::route('edit/{id}', 'admin.atu.currencies.edit')->name('edit'); Volt::route('settings', 'admin.atu.currencies.settings')->name('settings'); Volt::route('logs', 'admin.atu.currencies.logs')->name('logs'); }); ``` **Note:** If you have configured your own starterkit, make sure to add `use Livewire\Volt\Volt;` at the top of your `routes/web.php` file. ### Manual Sidebar Menu Setup [](#manual-sidebar-menu-setup) If automatic sidebar menu injection fails, manually add the following menu items to `resources/views/components/layouts/app/sidebar.blade.php` after the Platform group closing tag (``): ``` @if (auth()->user()?->isAdminOrSuperAdmin()) {{-- Currencies Menu Item --}} {{ __('Currencies') }} {{-- Currency Logs Menu Item --}} {{ __('Currency Logs') }} {{-- Currency Settings Menu Item --}} {{ __('Currency Settings') }} @endif ``` **Reference Files:** - Routes: `vendor/vormiaphp/atu-multicurrency/src/stubs/reference/routes-to-add.php` - Sidebar Menu: `vendor/vormiaphp/atu-multicurrency/src/stubs/reference/sidebar-menu-to-add.blade.php` Documentation ------------- [](#documentation) For detailed implementation guides and architecture documentation, see: - **Build Guide**: `docs/build-guide.md` - Authoritative implementation guide - **UI Build Guide**: `docs/build-ui-guide.md` - UI controls and admin settings guide - **A2Commerce Documentation**: See [A2Commerce GitHub repository](https://github.com/a2-atu/a2commerce) for installation and usage documentation Uninstallation -------------- [](#uninstallation) To completely remove the package: ``` # Uninstall package files and optionally drop tables php artisan atumulticurrency:uninstall # Remove from composer composer remove vormia-folks/atu-multi-currency ``` **Note:** The uninstall command will: - Remove all copied files and stubs - Remove routes from `routes/api.php` - Optionally drop database tables (with confirmation) - Optionally remove environment variables - Create a backup before removal Troubleshooting --------------- [](#troubleshooting) ### Seeder Fails [](#seeder-fails) If the seeder fails because `a2_ec_settings` table doesn't exist: - Ensure A2Commerce is installed and migrations have been run - The seeder will fallback to USD/$ if the table is missing ### Migration Errors [](#migration-errors) If migrations fail: - Ensure all A2Commerce migrations have been run first - Check that the database connection is configured correctly - Verify foreign key constraints are supported ### Currency Not Found [](#currency-not-found) If base currency is not found: - Run the seeder manually: `php artisan db:seed --class=ATUMultiCurrencySeeder` - Check that `a2_ec_settings` table exists and has currency data Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. License ------- [](#license) This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). Support ------- [](#support) For issues, questions, or contributions: - Check the documentation in `docs/build-guide.md` - Review [A2Commerce documentation](https://github.com/a2-atu/a2commerce) for base functionality - Open an issue on the package repository Versioning and Git Tags ----------------------- [](#versioning-and-git-tags) This package follows [Semantic Versioning](https://semver.org/) and uses git tags to mark releases. Each release is tagged with a version number (e.g., `v1.0.0`, `v1.0.1`). ### Available Versions [](#available-versions) The following versions are available: - **v1.0.2** - Latest stable release - **v1.0.1** - Previous release - **v1.0.0** - Stable release with full feature set - **v0.2.1** - Previous release - **v0.2.0** - Previous release - **v0.1.0** - Initial release ### Installing Specific Versions [](#installing-specific-versions) You can install a specific version using Composer: ``` # Install latest stable version composer require vormia-folks/atu-multi-currency # Install specific version composer require vormia-folks/atu-multi-currency:^1.0.1 # Install from git tag (development) composer require vormia-folks/atu-multi-currency:dev-main ``` ### Checking Out a Specific Git Tag [](#checking-out-a-specific-git-tag) If you're working with the source code directly: ``` # List all available tags git tag --list # Checkout a specific version git checkout v1.0.1 # Or checkout the latest tag git checkout $(git describe --tags --abbrev=0) ``` Release Notes ------------- [](#release-notes) For detailed release notes and changelog, see: - [RELEASE\_NOTES\_v1.0.2.md](RELEASE_NOTES_v1.0.2.md) - Latest release (v1.0.2) - [RELEASE\_NOTES\_v1.0.0.md](RELEASE_NOTES_v1.0.0.md) - v1.0.0 stable release - [RELEASE\_NOTES\_v0.1.1.md](RELEASE_NOTES_v0.1.1.md) - v0.1.1 release ### Latest Release [](#latest-release) **Current version: v1.0.2** The latest release (v1.0.2) includes: - Enhanced currency data access using Eloquent models - Improved code readability and maintainability - Streamlined currency creation and editing logic - Better error handling across components - Comprehensive git tag versioning documentation - Updated README with version management information For detailed information about each release, check the release notes files or view the git tags: ``` # View release information for a specific tag git show v1.0.1 --no-patch # View all commits for a specific version git log v1.0.0..v1.0.1 --oneline ``` --- **Built with ❤️ for the A2 Commerce ecosystem** ### Health Score 40 — FairBetter than 88% of packages Maintenance80 Actively maintained with recent releases Popularity11 Limited adoption so far Community6 Small or concentrated contributor base Maturity51 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 ~0 days Total 6 Last Release 123d ago Major Versions v0.2.1 → v1.0.02026-01-09 ### Community Maintainers ![](https://www.gravatar.com/avatar/f69b40bdd7f381ee33360299b1d574f9d9d0af369f7e3d925f7ac2e5d70403aa?d=identicon)[joshlminga](/maintainers/joshlminga) --- Top Contributors [![joshlminga](https://avatars.githubusercontent.com/u/7943555?v=4)](https://github.com/joshlminga "joshlminga (22 commits)") --- Tags phplaravelvormiaa2commerceatuatu-multi-currency ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/vormia-folks-atu-multi-currency/health.svg) ``` [![Health](https://phpackages.com/badges/vormia-folks-atu-multi-currency/health.svg)](https://phpackages.com/packages/vormia-folks-atu-multi-currency) ``` ### Alternatives [laracraft-tech/laravel-xhprof Easy XHProf setup to profile your laravel application! 235321.4k](/packages/laracraft-tech-laravel-xhprof)[kompo/kompo Laravel & Vue.js FullStack Components for Rapid Application Development 11812.4k21](/packages/kompo-kompo)[bavix/laravel-xhprof Quick profiling of your code for Laravel 22156.6k](/packages/bavix-laravel-xhprof) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)