money-rails 1.15.0 → 3.0.0

data/README.md

@@ -1,16 +1,15 @@
 # RubyMoney - Money-Rails
 
-[![Gem Version](https://badge.fury.io/rb/money-rails.svg)](http://badge.fury.io/rb/money-rails)
-[![Build Status](https://secure.travis-ci.org/RubyMoney/money-rails.svg?branch=master)](http://travis-ci.org/RubyMoney/money-rails)
-[![Code Climate](https://codeclimate.com/github/RubyMoney/money-rails.svg)](https://codeclimate.com/github/RubyMoney/money-rails)
-[![License](http://img.shields.io/:license-mit-green.svg?style=flat)](http://opensource.org/licenses/MIT)
+[![Gem Version](https://badge.fury.io/rb/money-rails.svg)](https://rubygems.org/gems/money-rails)
+[![Ruby](https://github.com/RubyMoney/money-rails/actions/workflows/ruby.yml/badge.svg)](https://github.com/RubyMoney/money-rails/actions/workflows/ruby.yml)
+[![License](https://img.shields.io/:license-mit-green.svg?style=flat)](https://opensource.org/licenses/MIT)
 
 ## Introduction
 
-This library provides integration of the [money](http://github.com/Rubymoney/money) gem with Rails.
+This library provides integration of the [money](https://github.com/Rubymoney/money) gem with Rails.
 
-Use 'monetize' to specify which fields you want to be backed by
-Money objects and helpers provided by the [money](http://github.com/Rubymoney/money)
+Use `monetize` to specify which fields you want to be backed by
+Money objects and helpers provided by the [money](https://github.com/Rubymoney/money)
 gem.
 
 Currently, this library is in active development mode, so if you would
@@ -20,26 +19,26 @@ welcome to contribute to the project.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add it to your application’s Gemfile using:
 
-    gem 'money-rails', '~>1.12'
-
-And then execute:
-
-    $ bundle
+```sh
+bundle add money-rails
+```
 
 Or install it yourself using:
 
-    $ gem install money-rails
+```sh
+$ gem install money-rails
+```
 
 You can also use the money configuration initializer:
 
-```
-$ rails g money_rails:initializer
+```sh
+$ bin/rails generate money_rails:initializer
 ```
 
 There, you can define the default currency value and set other
-configuration parameters for the rails app.
+configuration parameters for the Rails app.
 
 Without Rails in rack-based applications, call during initialization:
 
@@ -58,47 +57,44 @@ For example, we create a Product model which has an integer column called
 
 ```ruby
 class Product < ActiveRecord::Base
-
   monetize :price_cents
-
 end
 ```
 
-Now each Product object will also have an attribute called ```price``` which
+Now each Product object will also have an attribute called `price` which
 is a `Money` object, and can be used for money comparisons, conversions etc.
 
 In this case the name of the money attribute is created automagically by removing the
-```_cents``` suffix from the column name.
+`_cents` suffix from the column name.
 
-If you are using another db column name, or you prefer another name for the
-money attribute, then you can provide an ```as``` argument with a string
-value to the ```monetize``` macro:
+If you are using another database column name, or you prefer another name for the
+money attribute, then you can provide an `as` argument with a string value to the
+`monetize` macro:
 
 ```ruby
 monetize :discount_subunit, as: "discount"
 ```
 
-Now the model objects will have a ```discount``` attribute which is a `Money`
-object, wrapping the value of the ```discount_subunit``` column with a Money
+Now the model objects will have a `discount` attribute which is a `Money`
+object, wrapping the value of the `discount_subunit` column with a Money
 instance.
 
 #### Migration helpers
 
-If you want to add a money field to a product model you can use the ```add_money``` helper. This
-helper can be customized inside a ```MoneyRails.configure``` block. You should customize the
-```add_money``` helper to match the most common use case and utilize it across all migrations.
+If you want to add a money field to a product model you can use the `add_monetize` helper.
+This helper can be customized inside a `MoneyRails.configure` block. You should customize
+the `add_monetize` helper to match the most common use case and utilize it across all
+migrations.
 
 ```ruby
 class MonetizeProduct < ActiveRecord::Migration
   def change
-    add_money :products, :price    # Rails 3
-    add_monetize :products, :price # Rails 4x and above
+    add_monetize :products, :price
 
     # OR
 
     change_table :products do |t|
-      t.money :price    # Rails 3
-      t.monetize :price # Rails 4x and above
+      t.monetize :price
     end
   end
 end
@@ -109,28 +105,23 @@ Another example, where the currency column is not included:
 ```ruby
 class MonetizeItem < ActiveRecord::Migration
   def change
-    add_money :items, :price, currency: { present: false }
+    add_monetize :items, :price, currency: { present: false }
   end
 end
 ```
 
-Notice. Default value of currency field, generated by migration's helper, is USD. To override these defaults, you need change default_currency in money initializer and run migrations.
-
-The ```add_money``` helper is reversible, so you can use it inside ```change```
-migrations.  If you're writing separate ```up``` and ```down``` methods, you
-can use the ```remove_money``` helper.
+Notice: Default value of currency field, generated by migration’s helper, is
+USD. To override these defaults, you need change the `default_currency` in an
+initializer and run migrations.
 
-##### Notice for Rails >= 4.2 and PG adapter
-
-Due to the addition of the `money` column type for PostgreSQL in Rails 4.2, you
-will need to use `add_monetize` instead of `add_money` column. If you're adding
-the column within a `create_table` block, use `t.monetize`, and use
-`remove_monetize` to remove the column.
+The `add_monetize` helper is reversible, so you can use it inside `change`
+migrations.  If you’re writing separate `up` and `down` methods, you can use the
+`remove_monetize` helper.
 
 #### Allow nil values
 
-If you want to allow nil and/or blank values to a specific
-monetized field, you can use the `:allow_nil` parameter:
+If you want to allow `nil` and/or blank values to a specific monetized field,
+you can use the `:allow_nil` parameter:
 
 ```ruby
 # in Product model
@@ -138,7 +129,10 @@ monetize :optional_price_cents, allow_nil: true
 
 # in Migration
 def change
-  add_money :products, :optional_price, amount: { null: true, default: nil }
+  add_monetize :products,
+    :optional_price,
+    amount: { null: true, default: nil },
+    currency: { null: true, default: nil }
 end
 
 # now blank assignments are permitted
@@ -150,7 +144,8 @@ product.optional_price_cents # => nil
 
 #### Allow large numbers
 
-If you foresee that you will be saving large values (range is -2147483648 to +2147483647 for Postgres), increase your integer column limit to bigint:
+If you foresee that you will be saving large values (range is -2147483648 to
++2147483647 for Postgres), increase your integer column limit to `bigint`:
 
 ```ruby
 def change
@@ -161,19 +156,21 @@ end
 #### Numericality validation options
 
 You can also pass along
-[numericality validation options](http://guides.rubyonrails.org/active_record_validations.html#numericality)
+[numericality validation options](https://guides.rubyonrails.org/active_record_validations.html#numericality)
 such as this:
 
 ```ruby
-monetize :price_in_a_range_cents, allow_nil: true,
+monetize :price_in_a_range_cents,
+  allow_nil: true,
   numericality: {
     greater_than_or_equal_to: 0,
     less_than_or_equal_to: 10000
   }
 ```
 
-Or, if you prefer, you can skip validations entirely for the attribute. This is useful if chosen attributes
-are aggregate methods and you wish to avoid executing them on every record save.
+Or, if you prefer, you can skip validations entirely for the attribute. This is
+useful if chosen attributes are aggregate methods and you wish to avoid executing
+them on every record save.
 
 ```ruby
 monetize :price_in_a_range_cents, disable_validation: true
@@ -186,7 +183,18 @@ to the validation you are willing to skip, like this:
 monetize :price_in_a_range_cents, numericality: false
 ```
 
-### Mongoid 2.x and 3.x
+And you can also use `subunit_numericality` for subunit:
+
+```ruby
+monetize :price_in_a_range_cents,
+  allow_nil: true,
+  subunit_numericality: {
+    greater_than_or_equal_to: 0,
+    less_than_or_equal_to: 100_00
+  }
+```
+
+### Mongoid
 
 `Money` is available as a field type to supply during a field definition:
 
@@ -231,18 +239,17 @@ Method return values can be monetized in the same way attributes are monetized.
 
 ```ruby
 class Transaction < ActiveRecord::Base
-
   monetize :price_cents
   monetize :tax_cents
   monetize :total_cents
+
   def total_cents
-    return price_cents + tax_cents
+    price_cents + tax_cents
   end
-
 end
 ```
 
-Now each Transaction object has a method called `total` which returns a `Money` object.
+Now each `Transaction` object has a method called `total` which returns a `Money` object.
 
 ### Currencies
 
@@ -254,14 +261,12 @@ initializer of money-rails:
 ```ruby
 # config/initializers/money.rb
 MoneyRails.configure do |config|
-
   # set the default currency
   config.default_currency = :usd
-
 end
 ```
-For complete list of available currency: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
 
+For a complete list of available currencies: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
 
 If you need to set the default currency on a per-request basis, such as in a
 multi-tenant application, you may use a lambda to lazy-load the default currency
@@ -269,10 +274,11 @@ from a field in a configuration model called `Tenant` in this example:
 
 ```ruby
 # config/initializers/money.rb
-MoneyRails.configure do |config|
-
-  # set the default currency based on client configuration
-  config.default_currency = -> { Tenant.current.default_currency }
+ActiveSupport::Reloader.to_prepare do
+  MoneyRails.configure do |config|
+    # set the default currency based on client configuration
+    config.default_currency = -> { Tenant.current.default_currency }
+  end
 end
 ```
 
@@ -282,53 +288,56 @@ meet your needs.
 #### Model Currency
 
 You can override the global default currency within a specific ActiveRecord
-model using the ```register_currency``` macro:
+model using the `register_currency` macro:
 
 ```ruby
 # app/models/product.rb
 class Product < ActiveRecord::Base
-
   # Use EUR as model level currency
   register_currency :eur
 
   monetize :discount_subunit, as: "discount"
   monetize :bonus_cents
-
 end
 ```
 
-Now ```product.discount``` and ```product.bonus``` will return a `Money`
-object using EUR as their currency, instead of the default USD.
+Now `product.discount` and `product.bonus` will return a `Money` object using
+EUR as their currency, instead of the default USD.
 
-(This is not available in  Mongoid).
+(This is not available in Mongoid).
 
-#### Attribute Currency (:with_currency)
+#### Attribute Currency (`:with_currency`)
 
-By passing the option ```:with_currency``` to the ```monetize``` macro call,
-with a currency code (symbol or string) or a callable object (object that responds to the method ```call```) that returns a currency code, as its value, you can define a currency in a more granular
-way. This will let you attach the given currency only to the specified monetized model
-attribute (allowing you to, for example, monetize different attributes of the same model with different currencies.).
+By passing the option `:with_currency` to the `monetize` macro call,
+with a currency code (symbol or string) or a callable object (object that responds
+to the `call` method) that returns a currency code, as its value, you can define
+a currency in a more granular way. This will let you attach the given currency
+only to the specified monetized model attribute (allowing you to, for example,
+monetize different attributes of the same model with different currencies).
 
-This allows you to override both the model level and the global
-default currencies:
+This allows you to override both the model level and the global default
+currencies:
 
 ```ruby
 # app/models/product.rb
 class Product < ActiveRecord::Base
-
   # Use EUR as the model level currency
   register_currency :eur
 
   monetize :discount_subunit, as: "discount"
   monetize :bonus_cents, with_currency: :gbp
-
 end
 ```
 
-In this case ```product.bonus``` will return a Money object with GBP as its
-currency, whereas ```product.discount.currency.to_s # => EUR ```
+In this case `product.bonus` will return a Money object with GBP as its
+currency, whereas `product.discount.currency.to_s # => EUR`
 
-As mentioned earlier you can use an object that responds to the method ```call``` and accepts the model instance as a parameter. That means you can use a ```Proc``` or ```lambda``` (we would recommend ```lambda``` over ```Proc``` because of their [different control flow characteristics](https://stackoverflow.com/questions/1740046/whats-the-difference-between-a-proc-and-a-lambda-in-ruby)) or even define a separate ```class``` with an instance or class method (maybe even a ```module```) to return the currency code:
+As mentioned earlier you can use an object that responds to the method `call`
+and accepts the model instance as a parameter. That means you can use a `Proc`
+or `lambda` (we would recommend `lambda` over `Proc` because of their
+[different control flow characteristics](https://stackoverflow.com/questions/1740046/whats-the-difference-between-a-proc-and-a-lambda-in-ruby))
+or even define a separate `class` with an instance or class method (maybe even a
+`module`) to return the currency code:
 
 ```ruby
 class DeliveryFee
@@ -343,9 +352,7 @@ module OptionalPrice
   end
 end
 
-# app/models/product.rb
 class Product < ActiveRecord::Base
-
   monetize :price_cents, with_currency: ->(_product) { :gbp }
   monetize :delivery_fee_cents, with_currency: DeliveryFee.new
   monetize :optional_price_cents, with_currency: OptionalPrice
@@ -356,9 +363,9 @@ end
 
 All the previous options do not require any extra model fields to hold
 the currency values. If the currency of a field will vary from
-one model instance to another, then you should add a column called ```currency```
-to your database table and pass the option ```with_model_currency```
-to the ```monetize``` macro.
+one model instance to another, then you should add a column called `currency`
+to your database table and pass the option `with_model_currency`
+to the `monetize` macro.
 
 money-rails will use this knowledge to override the model level and global
 default values. Non-nil instance currency values also override attribute
@@ -366,16 +373,11 @@ currency values, so they have the highest precedence.
 
 ```ruby
 class Transaction < ActiveRecord::Base
-
-  # This model has a separate currency column
-  attr_accessible :amount_cents, :currency, :tax_cents
-
   # Use model level currency
   register_currency :gbp
 
   monetize :amount_cents, with_model_currency: :currency
   monetize :tax_cents, with_model_currency: :currency
-
 end
 
 # Now instantiating with a specific currency overrides
@@ -386,11 +388,10 @@ t.amount == Money.new(2500, "CAD") # true
 
 ### Configuration parameters
 
-You can handle a bunch of configuration params through ```money.rb``` initializer:
+You can handle a bunch of configuration params through `money.rb` initializer:
 
 ```ruby
 MoneyRails.configure do |config|
-
   # To set the default currency
   #
   # config.default_currency = :usd
@@ -414,37 +415,39 @@ MoneyRails.configure do |config|
 
   # Default ActiveRecord migration configuration values for columns:
   #
-  # config.amount_column = { prefix: '',           # column name prefix
-  #                          postfix: '_cents',    # column name  postfix
-  #                          column_name: nil,     # full column name (overrides prefix, postfix and accessor name)
-  #                          type: :integer,       # column type
-  #                          present: true,        # column will be created
-  #                          null: false,          # other options will be treated as column options
-  #                          default: 0
-  #                        }
+  # config.amount_column = {
+  #   prefix: '',           # column name prefix
+  #   postfix: '_cents',    # column name  postfix
+  #   column_name: nil,     # full column name (overrides prefix, postfix and accessor name)
+  #   type: :integer,       # column type
+  #   present: true,        # column will be created
+  #   null: false,          # other options will be treated as column options
+  #   default: 0
+  # }
   #
-  # config.currency_column = { prefix: '',
-  #                            postfix: '_currency',
-  #                            column_name: nil,
-  #                            type: :string,
-  #                            present: true,
-  #                            null: false,
-  #                            default: 'USD'
-  #                          }
+  # config.currency_column = {
+  #   prefix: '',
+  #   postfix: '_currency',
+  #   column_name: nil,
+  #   type: :string,
+  #   present: true,
+  #   null: false,
+  #   default: 'USD'
+  # }
 
   # Register a custom currency
   #
   # Example:
   # config.register_currency = {
-  #   priority:            1,
-  #   iso_code:            "EU4",
-  #   name:                "Euro with subunit of 4 digits",
-  #   symbol:              "€",
-  #   symbol_first:        true,
-  #   subunit:             "Subcent",
-  #   subunit_to_unit:     10000,
+  #   priority: 1,
+  #   iso_code: "EU4",
+  #   name: "Euro with subunit of 4 digits",
+  #   symbol: "€",
+  #   symbol_first: true,
+  #   subunit: "Subcent",
+  #   subunit_to_unit: 10000,
   #   thousands_separator: ".",
-  #   decimal_mark:        ","
+  #   decimal_mark: ","
   # }
 
   # Specify a rounding mode
@@ -471,25 +474,32 @@ MoneyRails.configure do |config|
   #   symbol: nil,
   #   sign_before_symbol: nil
   # }
+
+  # Set whether an error should be raised when parsing money values
+  # This includes assigning to a monetized field with the wrong currency
+  # Default value is false
+  #
+  # config.raise_error_on_money_parsing = true
 end
 ```
 
-* ```default_currency```: Set the default (application wide) currency (USD is the default)
-* ```include_validations```: Permit the inclusion of a ```validates_numericality_of```
+* `default_currency`: Set the default (application wide) currency (USD is the default)
+* `include_validations`: Permit the inclusion of a `validates_numericality_of`
   validation for each monetized field (the default is true)
-* ```register_currency```: Register one custom currency. This option can be
+* `register_currency`: Register one custom currency. This option can be
   used more than once to set more custom currencies. The value should be
-  a hash of all the necessary key/value pairs (important keys: ```:priority```, ```:iso_code```,
-  ```:name```, ```:symbol```, ```:symbol_first```, ```:subunit```, ```:subunit_to_unit```,
-  ```:thousands_separator```, ```:decimal_mark```).
-* ```add_rate```: Provide custom exchange rate for currencies in one direction
-  only! This rate is added to the attached bank object.
-* ```default_bank```: The default bank object holding exchange rates etc.
+  a hash of all the necessary key/value pairs (important keys: `:priority`, `:iso_code`,
+  `:name`, `:symbol`, `:symbol_first`, `:subunit`, `:subunit_to_unit`,
+  `:thousands_separator`, `:decimal_mark`).
+* `add_rate`: Provide custom exchange rate for currencies in one direction only! This
+  rate is added to the attached bank object.
+* `default_bank`: The default bank object holding exchange rates etc.
   (https://github.com/RubyMoney/money#currency-exchange)
-* ```default_format```: Force `Money#format` to use these options for formatting.
-* ```amount_column```: Provide values for the amount column (holding the fractional part of a money object).
-* ```currency_column```: Provide default values or even disable (`present: false`) the currency column.
-* ```rounding_mode```: Set Money.rounding_mode to one of the BigDecimal constants
+* `default_format`: Force `Money#format` to use these options for formatting.
+* `amount_column`: Provide values for the amount column (holding the fractional part of a money object).
+* `currency_column`: Provide default values or even disable (`present: false`) the currency column.
+* `rounding_mode`: Set `Money.rounding_mode` to one of the BigDecimal constants.
+* `raise_error_on_money_parsing`: Set whether errors should be raised when parsing money values
 
 ### Helpers
 
@@ -504,7 +514,7 @@ _For examples below, `@money_object == <Money fractional:650 currency:USD>`_
 | `money_without_cents_and_with_symbol @money_object`   | $6                                        |
 | `money_only_cents @money_object`                      | 50                                        |
 
-#### `no_cents_if_whole`
+#### `no_cents_if_whole` configuration param
 
 `humanized_money` and `humanized_money_with_symbol` will not render the cents part if it contains only zeros, unless `config.no_cents_if_whole` is set to `false` in the `money.rb` configuration (default: true).
 Note that the `config.default_format` will be overwritten by `config.no_cents_if_whole`.
@@ -512,24 +522,53 @@ So `humanized_money` will ignore `config.default_format = { no_cents_if_whole: f
 
 ### Testing
 
-If you use Rspec there is a test helper implementation.
-Just write `require "money-rails/test_helpers"` in spec_helper.rb.
+The test helpers work with both RSpec and Minitest.
+
+#### RSpec
 
-* the `monetize` matcher
+If you use RSpec, just require the test helpers in `spec_helper.rb`:
+
+```ruby
+require "money-rails/test_helpers"
+```
+
+The helpers will automatically be included in your RSpec tests.
+
+#### Minitest
+
+If you use Minitest, require the test helpers and include them in your test class:
+
+```ruby
+require "money-rails/test_helpers"
+
+class ProductTest < Minitest::Test
+  include MoneyRails::TestHelpers
+
+  def test_monetizes_price
+    matcher = monetize(:price_cents)
+    assert matcher.matches?(Product)
+  end
+end
+```
+
+#### The `monetize` matcher
 
 ```ruby
 is_expected.to monetize(:price)
 ```
+
 This will ensure that a column called `price_cents` is being monetized.
 
 ```ruby
 is_expected.to monetize(:price).allow_nil
 ```
+
 By using `allow_nil` you can specify money attributes that accept nil values.
 
 ```ruby
 is_expected.to monetize(:price).as(:discount_value)
 ```
+
 By using `as` chain you can specify the exact name to which a monetized
 column is being mapped.
 
@@ -552,14 +591,15 @@ For examples on using the test_helpers look at
 
 ## Supported ORMs/ODMs
 
-* ActiveRecord (>= 3.x)
-* Mongoid (>= 2.x)
+* ActiveRecord (>= 7.0)
+* Mongoid (>= 7.x)
 
 ## Supported Ruby interpreters
 
-* MRI Ruby >= 1.9.2
+* MRI Ruby >= 3.1
 
-You can see a full list of the currently supported interpreters in [travis.yml](http://github.com/RubyMoney/money-rails/blob/master/.travis.yml)
+You can see a full list of the currently supported interpreters in
+[ruby.yml](https://github.com/RubyMoney/money-rails/blob/main/.github/workflows/ruby.yml)
 
 ## Contributing
 
@@ -573,18 +613,8 @@ You can see a full list of the currently supported interpreters in [travis.yml](
 
 ### How to run the tests
 
-Our tests are executed with several ORMs - see `Rakefile` for details. To install all required gems run `rake spec:all` That command will take care of installing all required gems for all the different Gemfiles and then running the test suite with the installed bundle.
+Our tests are executed with several ORMs - see `Rakefile` for details. To install all required gems run `rake spec:all`. That command will take care of installing all required gems for all the different Gemfiles and then running the test suite with the installed bundle.
 
 You can also run the test suite against a specific ORM or Rails version, `rake -T` will give you an idea of the possible task (take a look at the tasks under the spec: namespace).
 
-If you are testing against mongoid, make sure to have the mongod process running before executing the suite,  (E.g. `sudo mongod --quiet`)
-
-## Maintainers
-
-* Andreas Loupasakis (https://github.com/alup)
-* Shane Emmons (https://github.com/semmons99)
-* Simone Carletti (https://github.com/weppos)
-
-## License
-
-MIT License. Copyright 2021 RubyMoney.
+If you are testing against mongoid, make sure to have the mongod process running before executing the suite. (E.g. `sudo mongod --quiet`)

data/config/locales/money.pt.yml

@@ -0,0 +1,4 @@
+pt:
+  errors:
+    messages:
+      invalid_currency: tem um formato inválido (deve ser '100', '5%{decimal}24', ou '123%{thousands}456%{decimal}78'). Recebido %{currency}

data/lib/money-rails/active_job/money_serializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MoneyRails
+  module ActiveJob
+    class MoneySerializer < ::ActiveJob::Serializers::ObjectSerializer
+      def serialize?(argument)
+        argument.is_a?(Money)
+      end
+
+      def serialize(money)
+        super("cents" => money.cents, "currency" => money.currency.to_s)
+      end
+
+      def deserialize(hash)
+        Money.new(hash["cents"], hash["currency"])
+      end
+
+      def klass
+        Money
+      end
+    end
+  end
+end