PHPackages                             responsiv/currency-plugin - 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. responsiv/currency-plugin

ActiveOctober-plugin[Utility & Helpers](/categories/utility)

responsiv/currency-plugin
=========================

Currency plugin for October CMS

v2.2.0(1mo ago)171.3k23[6 issues](https://github.com/responsiv/currency-plugin/issues)1PHPPHP >=5.5.9

Since Mar 27Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/responsiv/currency-plugin)[ Packagist](https://packagist.org/packages/responsiv/currency-plugin)[ Docs](https://octobercms.com/plugin/responsiv-currency)[ RSS](/packages/responsiv-currency-plugin/feed)WikiDiscussions master Synced 1mo ago

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

Currency plugin
===============

[](#currency-plugin)

Tools for dealing with currency display and conversions. You can configure currencies and converters via the Settings page.

- Settings → Currencies
- Settings → Exchange Rates

Get Started
-----------

[](#get-started)

A quick start guide for this plugin can be found at the following link:

- [Announcing the Release of the Currency Plugin v2.0 ](https://octobercms.com/blog/post/announcing-release-currency-plugin-v2)

Official Documentation
----------------------

[](#official-documentation)

This plugin is partially documented in the official October CMS documentation.

ArticlePurpose[Currency Twig Filter](https://docs.octobercms.com/3.x/markup/filter/currency.html)Formatting Currency in Twig markup[Currency Form Widget](https://docs.octobercms.com/3.x/element/form/widget-currency.html)Displaying currency as an input field[Currency List Column](https://docs.octobercms.com/3.x/element/lists/column-currency.html)Displaying currency in a list columnUnderstanding Currency Definitions
----------------------------------

[](#understanding-currency-definitions)

There are multiple currency definition types that are important to operating the Currency plugin. Each definition type is described in more detail below.

### Default Currency

[](#default-currency)

The default currency is the global anchor — all prices are stored in this currency. It is used when there is no site context or when no other currency is configured. In the currency form widget, if the model does not implement the multisite feature, the value is stored in the default currency.

> **Note**: The default currency is set by opening the **Settings → Currencies** page and checking the **Default** checkbox on a currency listed on this page.

### Base Currency (Site Group)

[](#base-currency-site-group)

The base currency can be set on a **Site Group** to override the stored currency for all sites in that group. This is an edge case for installations where different groups of sites store prices in different currencies (e.g. a US group stores in USD while a UK group stores in GBP).

When no base currency is set on the site group, the global default currency is used.

> **Note**: The base currency is set by opening the **Settings → Site Groups** page and selecting a currency in the **Base Currency** dropdown.

### Site Currency

[](#site-currency)

The site currency defines what currency is displayed to users visiting that site. When set, the currency filter automatically converts from the base currency to the site currency using exchange rates.

The site currency is available in Twig as `this.site.currency` and `this.site.currency_code`.

```
{{ this.site.currency_code }}
```

For example, if a value is stored in the default currency as USD and the site has a currency of AUD, the `site` option handles conversion automatically.

```
{{ product.price|currency({ site: true }) }}
```

> **Note**: The site currency is set by opening the **Settings → Site Definitions** page and selecting a currency in the **Currency** dropdown.

Currencyable Trait
------------------

[](#currencyable-trait)

The `Currencyable` trait allows models to store explicit per-currency price overrides in a sidecar table. It uses attribute interception (similar to the Translatable trait) so the model's `$attributes` always hold primary currency values. When a non-primary currency is active, reads return the explicit override if one exists, or fall back to exchange-rate conversion automatically.

### Setup

[](#setup)

Add the trait and define which attributes support currency overrides:

```
class Product extends Model
{
    use \Responsiv\Currency\Traits\Currencyable;

    public $currencyable = ['price', 'cost'];
}
```

### How It Works

[](#how-it-works)

1. **Attribute interception**: `getAttribute()` and `setAttribute()` are overridden. When the active currency differs from the primary, reads and writes are redirected to the sidecar cache instead of `$attributes`.
2. **Exchange-rate fallback**: When no explicit override exists for a currency, `getCurrencyOverride()` automatically converts the base value using `Currency::convert()`.
3. **Before save**: `syncCurrencyableAttributes()` persists any dirty sidecar data and restores the original primary-currency values on the model so the main table is never written with override values.
4. **Clearing overrides**: Setting a currency override to null or empty deletes the sidecar row, reverting the attribute to automatic exchange-rate conversion.

### Storage

[](#storage)

Overrides are stored in the `responsiv_currency_attributes` table:

ColumnPurpose`model_type`Morph type (model class)`model_id`Foreign key to the model`currency_code`Currency code (e.g. `EUR`, `GBP`)`attribute`Attribute name (e.g. `price`)`value`Override value### Reading Overrides

[](#reading-overrides)

```
// Get override for a specific currency (falls back to exchange-rate conversion)
$eurPrice = $product->getCurrencyOverride('price', 'EUR');

// Get override without fallback (returns null if no override)
$eurPrice = $product->getCurrencyOverride('price', 'EUR', false);

// Check if an explicit override exists (not exchange-rate converted)
if ($product->hasCurrencyOverride('price', 'EUR')) {
    // ...
}

// Get all stored currency values for an attribute
$allPrices = $product->getCurrencyOverrides('price');
// Returns: ['USD' => 1000, 'EUR' => 950, 'GBP' => 800]

// Get the primary-currency value (always reads from $attributes)
$basePrice = $product->getCurrencyableBaseValue('price');
```

### Writing Overrides

[](#writing-overrides)

```
// Set a single override
$product->setCurrencyOverride('price', 'EUR', 950);

// Set multiple currencies at once
$product->setCurrencyOverrides('price', [
    'EUR' => 950,
    'GBP' => 800,
]);

// Remove an override (reverts to exchange rate conversion)
$product->forgetCurrencyOverride('price', 'EUR');

// Remove all overrides for an attribute
$product->forgetCurrencyOverrides('price');

// Remove all overrides for a currency
$product->forgetAllCurrencyOverrides('EUR');
```

### Context Switching

[](#context-switching)

```
// Override the currency context for a model instance
$product->setCurrency('EUR');
echo $product->price; // Returns EUR override or exchange-rate converted value

// Get the active currency code
$code = $product->getCurrency();
```

### Query Scopes

[](#query-scopes)

```
// Filter by currency override value
Product::whereCurrencyOverride('price', 'EUR', 950)->get();

// Eager load overrides for the active currency
Product::withCurrencyOverride()->get();

// Eager load overrides for a specific currency
Product::withCurrencyOverride('EUR')->get();

// Eager load all currency overrides
Product::withCurrencyOverrides()->get();
```

### Currency Resolution

[](#currency-resolution)

The trait resolves currencies through the `CurrencyManager`:

MethodReturnsPurpose`getCurrencyableDefault()`Base currency codeSite group's base currency, or global default`getCurrencyableContext()`Active currency codeSite's currency, or falls back to base`shouldConvertCurrency()``bool``true` when active differs from base### Enabling / Disabling

[](#enabling--disabling)

The trait is enabled by default. Override `isCurrencyableEnabled()` in the model to disable it conditionally:

```
public function isCurrencyableEnabled()
{
    return false; // Disable currency overrides for this model
}
```

### License

[](#license)

This plugin is an official extension of the October CMS platform and is free to use if you have a platform license. See [EULA license](LICENSE.md) for more details.

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance81

Actively maintained with recent releases

Popularity30

Limited adoption so far

Community24

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 88.1% 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 ~165 days

Recently: every ~145 days

Total

12

Last Release

59d ago

Major Versions

v1.0.8 → v2.0.02024-08-03

### Community

Maintainers

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

---

Top Contributors

[![daftspunk](https://avatars.githubusercontent.com/u/1392869?v=4)](https://github.com/daftspunk "daftspunk (140 commits)")[![acasar](https://avatars.githubusercontent.com/u/6329543?v=4)](https://github.com/acasar "acasar (5 commits)")[![gpasztor87](https://avatars.githubusercontent.com/u/3843377?v=4)](https://github.com/gpasztor87 "gpasztor87 (4 commits)")[![verenaroe](https://avatars.githubusercontent.com/u/49275087?v=4)](https://github.com/verenaroe "verenaroe (3 commits)")[![joseph-d](https://avatars.githubusercontent.com/u/1070155?v=4)](https://github.com/joseph-d "joseph-d (2 commits)")[![Eoler](https://avatars.githubusercontent.com/u/680032?v=4)](https://github.com/Eoler "Eoler (1 commits)")[![gergo85](https://avatars.githubusercontent.com/u/2959112?v=4)](https://github.com/gergo85 "gergo85 (1 commits)")[![dzapek](https://avatars.githubusercontent.com/u/54842490?v=4)](https://github.com/dzapek "dzapek (1 commits)")[![samgeorges](https://avatars.githubusercontent.com/u/4927493?v=4)](https://github.com/samgeorges "samgeorges (1 commits)")[![alxy](https://avatars.githubusercontent.com/u/2057062?v=4)](https://github.com/alxy "alxy (1 commits)")

---

Tags

currencycmsoctoberresponsiv

### Embed Badge

![Health badge](/badges/responsiv-currency-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/responsiv-currency-plugin/health.svg)](https://phpackages.com/packages/responsiv-currency-plugin)
```

###  Alternatives

[rainlab/blog-plugin

Blog plugin for October CMS

17257.7k](/packages/rainlab-blog-plugin)[rainlab/builder-plugin

Builder plugin for October CMS

17147.2k1](/packages/rainlab-builder-plugin)[martin/forms-plugin

Create easy (and almost magic) AJAX forms

601.3k](/packages/martin-forms-plugin)[winter/wn-seo-plugin

Winter CMS plugin for managing SEO tags

106.3k](/packages/winter-wn-seo-plugin)[winter/wn-sitemap-plugin

Sitemap plugin for Winter CMS

1042.6k1](/packages/winter-wn-sitemap-plugin)

PHPackages © 2026

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