----
url: https://guides.rubyonrails.org/v8.1/active_support_core_extensions.html
----
***
## [1. How to Load Core Extensions](#how-to-load-core-extensions)
### [1.1. Stand-Alone Active Support](#stand-alone-active-support)
In order to have the smallest default footprint possible, Active Support loads the minimum dependencies by default. It is broken in small pieces so that only the desired extensions can be loaded. It also has some convenience entry points to load related extensions in one shot, even everything.
Thus, after a simple require like:
```
require "active_support"
```
only the extensions required by the Active Support framework are loaded.
#### [1.1.1. Cherry-picking a Definition](#cherry-picking-a-definition)
This example shows how to load [`Hash#with_indifferent_access`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-with_indifferent_access). This extension enables the conversion of a `Hash` into an [`ActiveSupport::HashWithIndifferentAccess`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/HashWithIndifferentAccess.html) which permits access to the keys as either strings or symbols.
```
{ a: 1 }.with_indifferent_access["a"] # => 1
```
For every single method defined as a core extension this guide has a note that says where such a method is defined. In the case of `with_indifferent_access` the note reads:
Defined in `active_support/core_ext/hash/indifferent_access.rb`.
That means that you can require it like this:
```
require "active_support"
require "active_support/core_ext/hash/indifferent_access"
```
Active Support has been carefully revised so that cherry-picking a file loads only strictly needed dependencies, if any.
#### [1.1.2. Loading Grouped Core Extensions](#loading-grouped-core-extensions)
The next level is to simply load all extensions to `Hash`. As a rule of thumb, extensions to `SomeClass` are available in one shot by loading `active_support/core_ext/some_class`.
Thus, to load all extensions to `Hash` (including `with_indifferent_access`):
```
require "active_support"
require "active_support/core_ext/hash"
```
#### [1.1.3. Loading All Core Extensions](#loading-all-core-extensions)
You may prefer just to load all core extensions, there is a file for that:
```
require "active_support"
require "active_support/core_ext"
```
#### [1.1.4. Loading All Active Support](#loading-all-active-support)
And finally, if you want to have all Active Support available just issue:
```
require "active_support/all"
```
That does not even put the entire Active Support in memory upfront indeed, some stuff is configured via `autoload`, so it is only loaded if used.
### [1.2. Active Support Within a Ruby on Rails Application](#active-support-within-a-ruby-on-rails-application)
A Ruby on Rails application loads all Active Support unless [`config.active_support.bare`](configuring.html#config-active-support-bare) is true. In that case, the application will only load what the framework itself cherry-picks for its own needs, and can still cherry-pick itself at any granularity level, as explained in the previous section.
## [2. Extensions to All Objects](#extensions-to-all-objects)
### [2.1. `blank?` and `present?`](#blank-questionmark-and-present-questionmark)
The following values are considered to be blank in a Rails application:
* `nil` and `false`,
* strings composed only of whitespace (see note below),
* empty arrays and hashes, and
* any other object that responds to `empty?` and is empty.
The predicate for strings uses the Unicode-aware character class `[:space:]`, so for example U+2029 (paragraph separator) is considered to be whitespace.
Note that numbers are not mentioned. In particular, 0 and 0.0 are **not** blank.
For example, this method from `ActionController::HttpAuthentication::Token::ControllerMethods` uses [`blank?`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-blank-3F) for checking whether a token is present:
```
def authenticate(controller, &login_procedure)
token, options = token_and_options(controller.request)
unless token.blank?
login_procedure.call(token, options)
end
end
```
The method [`present?`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-present-3F) is equivalent to `!blank?`. This example is taken from `ActionDispatch::Http::Cache::Response`:
```
def set_conditional_cache_control!
unless self["Cache-Control"].present?
# ...
end
end
```
Defined in `active_support/core_ext/object/blank.rb`.
### [2.2. `presence`](#presence)
The [`presence`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-presence) method returns its receiver if `present?`, and `nil` otherwise. It is useful for idioms like this:
```
host = config[:host].presence || "localhost"
```
Defined in `active_support/core_ext/object/blank.rb`.
### [2.3. `duplicable?`](#duplicable-questionmark)
As of Ruby 2.5, most objects can be duplicated via `dup` or `clone`:
```
"foo".dup # => "foo"
"".dup # => ""
Rational(1).dup # => (1/1)
Complex(0).dup # => (0+0i)
1.method(:+).dup # => TypeError (allocator undefined for Method)
```
Active Support provides [`duplicable?`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-duplicable-3F) to query an object about this:
```
"foo".duplicable? # => true
"".duplicable? # => true
Rational(1).duplicable? # => true
Complex(1).duplicable? # => true
1.method(:+).duplicable? # => false
```
Any class can disallow duplication by removing `dup` and `clone` or raising exceptions from them. Thus only `rescue` can tell whether a given arbitrary object is duplicable. `duplicable?` depends on the hard-coded list above, but it is much faster than `rescue`. Use it only if you know the hard-coded list is enough in your use case.
Defined in `active_support/core_ext/object/duplicable.rb`.
### [2.4. `deep_dup`](#deep-dup)
The [`deep_dup`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-deep_dup) method returns a deep copy of a given object. Normally, when you `dup` an object that contains other objects, Ruby does not `dup` them, so it creates a shallow copy of the object. If you have an array with a string, for example, it will look like this:
```
array = ["string"]
duplicate = array.dup
duplicate.push "another-string"
# the object was duplicated, so the element was added only to the duplicate
array # => ["string"]
duplicate # => ["string", "another-string"]
duplicate.first.gsub!("string", "foo")
# first element was not duplicated, it will be changed in both arrays
array # => ["foo"]
duplicate # => ["foo, "another-string"]
```
As you can see, after duplicating the `Array` instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since `dup` does not make a deep copy, the string inside the array is still the same object.
If you need a deep copy of an object, you should use `deep_dup`. Here is an example:
```
array = ["string"]
duplicate = array.deep_dup
duplicate.first.gsub!("string", "foo")
array # => ["string"]
duplicate # => ["foo"]
```
If the object is not duplicable, `deep_dup` will just return it:
```
number = 1
duplicate = number.deep_dup
number.object_id == duplicate.object_id # => true
```
Defined in `active_support/core_ext/object/deep_dup.rb`.
### [2.5. `try`](#try)
When you want to call a method on an object only if it is not `nil`, the simplest way to achieve it is with conditional statements, adding unnecessary clutter. The alternative is to use [`try`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-try). `try` is like `Object#public_send` except that it returns `nil` if sent to `nil`.
Here is an example:
```
# without try
unless @number.nil?
@number.next
end
# with try
@number.try(:next)
```
Another example is this code from `ActiveRecord::ConnectionAdapters::AbstractAdapter` where `@logger` could be `nil`. You can see that the code uses `try` and avoids an unnecessary check.
```
def log_info(sql, name, ms)
if @logger.try(:debug?)
name = "%s (%.1fms)" % [name || "SQL", ms]
@logger.debug(format_log_entry(name, sql.squeeze(" ")))
end
end
```
`try` can also be called without arguments but a block, which will only be executed if the object is not nil:
```
@person.try { |p| "#{p.first_name} #{p.last_name}" }
```
Note that `try` will swallow no-method errors, returning nil instead. If you want to protect against typos, use [`try!`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-try-21) instead:
```
@number.try(:nest) # => nil
@number.try!(:nest) # NoMethodError: undefined method `nest' for 1:Integer
```
Defined in `active_support/core_ext/object/try.rb`.
### [2.6. `class_eval(*args, &block)`](#class-eval-args-block)
You can evaluate code in the context of any object's singleton class using [`class_eval`](https://api.rubyonrails.org/v8.1.4/classes/Kernel.html#method-i-class_eval):
```
class Proc
def bind(object)
block, time = self, Time.current
object.class_eval do
method_name = "__bind_#{time.to_i}_#{time.usec}"
define_method(method_name, &block)
method = instance_method(method_name)
remove_method(method_name)
method
end.bind(object)
end
end
```
Defined in `active_support/core_ext/kernel/singleton_class.rb`.
### [2.7. `acts_like?(duck)`](#acts-like-questionmark-duck)
The method [`acts_like?`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-acts_like-3F) provides a way to check whether some class acts like some other class based on a simple convention: a class that provides the same interface as `String` defines
```
def acts_like_string?
end
```
which is only a marker, its body or return value are irrelevant. Then, client code can query for duck-type-safeness this way:
```
some_klass.acts_like?(:string)
```
Rails has classes that act like `Date` or `Time` and follow this contract.
Defined in `active_support/core_ext/object/acts_like.rb`.
### [2.8. `to_param`](#to-param)
All objects in Rails respond to the method [`to_param`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-to_param), which is meant to return something that represents them as values in a query string, or as URL fragments.
By default `to_param` just calls `to_s`:
```
7.to_param # => "7"
```
The return value of `to_param` should **not** be escaped:
```
"Tom & Jerry".to_param # => "Tom & Jerry"
```
Several classes in Rails overwrite this method.
For example `nil`, `true`, and `false` return themselves. [`Array#to_param`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-to_param) calls `to_param` on the elements and joins the result with "/":
```
[0, true, String].to_param # => "0/true/String"
```
Notably, the Rails routing system calls `to_param` on models to get a value for the `:id` placeholder. `ActiveRecord::Base#to_param` returns the `id` of a model, but you can redefine that method in your models. For example, given
```
class User
def to_param
"#{id}-#{name.parameterize}"
end
end
```
we get:
```
user_path(@user) # => "/users/357-john-smith"
```
Controllers need to be aware of any redefinition of `to_param` because when a request like that comes in "357-john-smith" is the value of `params[:id]`.
Defined in `active_support/core_ext/object/to_param.rb`.
### [2.9. `to_query`](#to-query)
The [`to_query`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-to_query) method constructs a query string that associates a given `key` with the return value of `to_param`. For example, with the following `to_param` definition:
```
class User
def to_param
"#{id}-#{name.parameterize}"
end
end
```
we get:
```
current_user.to_query("user") # => "user=357-john-smith"
```
This method escapes whatever is needed, both for the key and the value:
```
account.to_query("company[name]")
# => "company%5Bname%5D=Johnson+%26+Johnson"
```
so its output is ready to be used in a query string.
Arrays return the result of applying `to_query` to each element with `key[]` as key, and join the result with "&":
```
[3.4, -45.6].to_query("sample")
# => "sample%5B%5D=3.4&sample%5B%5D=-45.6"
```
Hashes also respond to `to_query` but with a different signature. If no argument is passed a call generates a sorted series of key/value assignments calling `to_query(key)` on its values. Then it joins the result with "&":
```
{ c: 3, b: 2, a: 1 }.to_query # => "a=1&b=2&c=3"
```
The method [`Hash#to_query`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-to_query) accepts an optional namespace for the keys:
```
{ id: 89, name: "John Smith" }.to_query("user")
# => "user%5Bid%5D=89&user%5Bname%5D=John+Smith"
```
Defined in `active_support/core_ext/object/to_query.rb`.
### [2.10. `with_options`](#with-options)
The method [`with_options`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-with_options) provides a way to factor out common options in a series of method calls.
Given a default options hash, `with_options` yields a proxy object to a block. Within the block, methods called on the proxy are forwarded to the receiver with their options merged. For example, you get rid of the duplication in:
```
class Account < ApplicationRecord
has_many :customers, dependent: :destroy
has_many :products, dependent: :destroy
has_many :invoices, dependent: :destroy
has_many :expenses, dependent: :destroy
end
```
this way:
```
class Account < ApplicationRecord
with_options dependent: :destroy do |assoc|
assoc.has_many :customers
assoc.has_many :products
assoc.has_many :invoices
assoc.has_many :expenses
end
end
```
That idiom may convey *grouping* to the reader as well. For example, say you want to send a newsletter whose language depends on the user. Somewhere in the mailer you could group locale-dependent bits like this:
```
I18n.with_options locale: user.locale, scope: "newsletter" do |i18n|
subject i18n.t :subject
body i18n.t :body, user_name: user.name
end
```
Since `with_options` forwards calls to its receiver they can be nested. Each nesting level will merge inherited defaults in addition to their own.
Defined in `active_support/core_ext/object/with_options.rb`.
### [2.11. JSON Support](#json-support)
Active Support provides a better implementation of `to_json` than the `json` gem ordinarily provides for Ruby objects. This is because some classes, like `Hash` and `Process::Status` need special handling in order to provide a proper JSON representation.
Defined in `active_support/core_ext/object/json.rb`.
### [2.12. Instance Variables](#instance-variables)
Active Support provides several methods to ease access to instance variables.
#### [2.12.1. `instance_values`](#instance-values)
The method [`instance_values`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-instance_values) returns a hash that maps instance variable names without "@" to their corresponding values. Keys are strings:
```
class C
def initialize(x, y)
@x, @y = x, y
end
end
C.new(0, 1).instance_values # => {"x" => 0, "y" => 1}
```
Defined in `active_support/core_ext/object/instance_variables.rb`.
#### [2.12.2. `instance_variable_names`](#instance-variable-names)
The method [`instance_variable_names`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-instance_variable_names) returns an array. Each name includes the "@" sign.
```
class C
def initialize(x, y)
@x, @y = x, y
end
end
C.new(0, 1).instance_variable_names # => ["@x", "@y"]
```
Defined in `active_support/core_ext/object/instance_variables.rb`.
### [2.13. Silencing Warnings and Exceptions](#silencing-warnings-and-exceptions)
The methods [`silence_warnings`](https://api.rubyonrails.org/v8.1.4/classes/Kernel.html#method-i-silence_warnings) and [`enable_warnings`](https://api.rubyonrails.org/v8.1.4/classes/Kernel.html#method-i-enable_warnings) change the value of `$VERBOSE` accordingly for the duration of their block, and reset it afterwards:
```
silence_warnings { Object.const_set "RAILS_DEFAULT_LOGGER", logger }
```
Silencing exceptions is also possible with [`suppress`](https://api.rubyonrails.org/v8.1.4/classes/Kernel.html#method-i-suppress). This method receives an arbitrary number of exception classes. If an exception is raised during the execution of the block and is `kind_of?` any of the arguments, `suppress` captures it and returns silently. Otherwise the exception is not captured:
```
# If the user is locked, the increment is lost, no big deal.
suppress(ActiveRecord::StaleObjectError) do
current_user.increment! :visits
end
```
Defined in `active_support/core_ext/kernel/reporting.rb`.
### [2.14. `in?`](#in-questionmark)
The predicate [`in?`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-in-3F) tests if an object is included in another object. An `ArgumentError` exception will be raised if the argument passed does not respond to `include?`.
Examples of `in?`:
```
1.in?([1, 2]) # => true
"lo".in?("hello") # => true
25.in?(30..50) # => false
1.in?(1) # => ArgumentError
```
Defined in `active_support/core_ext/object/inclusion.rb`.
## [3. Extensions to `Module`](#extensions-to-module)
### [3.1. Attributes](#attributes)
#### [3.1.1. `alias_attribute`](#alias-attribute)
Model attributes have a reader, a writer, and a predicate. You can alias a model attribute having the corresponding three methods all defined for you by using [`alias_attribute`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-alias_attribute). As in other aliasing methods, the new name is the first argument, and the old name is the second (one mnemonic is that they go in the same order as if you did an assignment):
```
class User < ApplicationRecord
# You can refer to the email column as "login".
# This can be meaningful for authentication code.
alias_attribute :login, :email
end
```
Defined in `active_support/core_ext/module/aliasing.rb`.
#### [3.1.2. Internal Attributes](#internal-attributes)
When you are defining an attribute in a class that is meant to be subclassed, name collisions are a risk. That's remarkably important for libraries.
Active Support defines the macros [`attr_internal_reader`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-attr_internal_reader), [`attr_internal_writer`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-attr_internal_writer), and [`attr_internal_accessor`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-attr_internal_accessor). They behave like their Ruby built-in `attr_*` counterparts, except they name the underlying instance variable in a way that makes collisions less likely.
The macro [`attr_internal`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-attr_internal) is a synonym for `attr_internal_accessor`:
```
# library
class ThirdPartyLibrary::Crawler
attr_internal :log_level
end
# client code
class MyCrawler < ThirdPartyLibrary::Crawler
attr_accessor :log_level
end
```
In the previous example it could be the case that `:log_level` does not belong to the public interface of the library and it is only used for development. The client code, unaware of the potential conflict, subclasses and defines its own `:log_level`. Thanks to `attr_internal` there's no collision.
By default the internal instance variable is named with a leading underscore, `@_log_level` in the example above. That's configurable via `Module.attr_internal_naming_format` though, you can pass any `sprintf`-like format string with a leading `@` and a `%s` somewhere, which is where the name will be placed. The default is `"@_%s"`.
Rails uses internal attributes in a few spots, for examples for views:
```
module ActionView
class Base
attr_internal :captures
attr_internal :request, :layout
attr_internal :controller, :template
end
end
```
Defined in `active_support/core_ext/module/attr_internal.rb`.
#### [3.1.3. Module Attributes](#module-attributes)
The macros [`mattr_reader`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-mattr_reader), [`mattr_writer`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-mattr_writer), and [`mattr_accessor`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-mattr_accessor) are the same as the `cattr_*` macros defined for class. In fact, the `cattr_*` macros are just aliases for the `mattr_*` macros. Check [Class Attributes](#class-attributes).
For example, the API for the logger of Active Storage is generated with `mattr_accessor`:
```
module ActiveStorage
mattr_accessor :logger
end
```
Defined in `active_support/core_ext/module/attribute_accessors.rb`.
### [3.2. Parents](#parents)
#### [3.2.1. `module_parent`](#module-parent)
The [`module_parent`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-module_parent) method on a nested named module returns the module that contains its corresponding constant:
```
module X
module Y
module Z
end
end
end
M = X::Y::Z
X::Y::Z.module_parent # => X::Y
M.module_parent # => X::Y
```
If the module is anonymous or belongs to the top-level, `module_parent` returns `Object`.
Note that in that case `module_parent_name` returns `nil`.
Defined in `active_support/core_ext/module/introspection.rb`.
#### [3.2.2. `module_parent_name`](#module-parent-name)
The [`module_parent_name`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-module_parent_name) method on a nested named module returns the fully qualified name of the module that contains its corresponding constant:
```
module X
module Y
module Z
end
end
end
M = X::Y::Z
X::Y::Z.module_parent_name # => "X::Y"
M.module_parent_name # => "X::Y"
```
For top-level or anonymous modules `module_parent_name` returns `nil`.
Note that in that case `module_parent` returns `Object`.
Defined in `active_support/core_ext/module/introspection.rb`.
#### [3.2.3. `module_parents`](#module-parents)
The method [`module_parents`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-module_parents) calls `module_parent` on the receiver and upwards until `Object` is reached. The chain is returned in an array, from bottom to top:
```
module X
module Y
module Z
end
end
end
M = X::Y::Z
X::Y::Z.module_parents # => [X::Y, X, Object]
M.module_parents # => [X::Y, X, Object]
```
Defined in `active_support/core_ext/module/introspection.rb`.
### [3.3. Anonymous](#anonymous)
A module may or may not have a name:
```
module M
end
M.name # => "M"
N = Module.new
N.name # => "N"
Module.new.name # => nil
```
You can check whether a module has a name with the predicate [`anonymous?`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-anonymous-3F):
```
module M
end
M.anonymous? # => false
Module.new.anonymous? # => true
```
Note that being unreachable does not imply being anonymous:
```
module M
end
m = Object.send(:remove_const, :M)
m.anonymous? # => false
```
though an anonymous module is unreachable by definition.
Defined in `active_support/core_ext/module/anonymous.rb`.
### [3.4. Method Delegation](#method-delegation)
#### [3.4.1. `delegate`](#delegate)
The macro [`delegate`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-delegate) offers an easy way to forward methods.
Let's imagine that users in some application have login information in the `User` model but name and other data in a separate `Profile` model:
```
class User < ApplicationRecord
has_one :profile
end
```
With that configuration you get a user's name via their profile, `user.profile.name`, but it could be handy to still be able to access such attribute directly:
```
class User < ApplicationRecord
has_one :profile
def name
profile.name
end
end
```
That is what `delegate` does for you:
```
class User < ApplicationRecord
has_one :profile
delegate :name, to: :profile
end
```
It is shorter, and the intention more obvious.
The method must be public in the target.
The `delegate` macro accepts several methods:
```
delegate :name, :age, :address, :twitter, to: :profile
```
When interpolated into a string, the `:to` option should become an expression that evaluates to the object the method is delegated to. Typically a string or symbol. Such an expression is evaluated in the context of the receiver:
```
# delegates to the Rails constant
delegate :logger, to: :Rails
# delegates to the receiver's class
delegate :table_name, to: :class
```
If the `:prefix` option is `true` this is less generic, see below.
By default, if the delegation raises `NoMethodError` and the target is `nil` the exception is propagated. You can ask that `nil` is returned instead with the `:allow_nil` option:
```
delegate :name, to: :profile, allow_nil: true
```
With `:allow_nil` the call `user.name` returns `nil` if the user has no profile.
The option `:prefix` adds a prefix to the name of the generated method. This may be handy for example to get a better name:
```
delegate :street, to: :address, prefix: true
```
The previous example generates `address_street` rather than `street`.
Since in this case the name of the generated method is composed of the target object and target method names, the `:to` option must be a method name.
A custom prefix may also be configured:
```
delegate :size, to: :attachment, prefix: :avatar
```
In the previous example the macro generates `avatar_size` rather than `size`.
The option `:private` changes methods scope:
```
delegate :date_of_birth, to: :profile, private: true
```
The delegated methods are public by default. Pass `private: true` to change that.
Defined in `active_support/core_ext/module/delegation.rb`.
#### [3.4.2. `delegate_missing_to`](#delegate-missing-to)
Imagine you would like to delegate everything missing from the `User` object, to the `Profile` one. The [`delegate_missing_to`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-delegate_missing_to) macro lets you implement this in a breeze:
```
class User < ApplicationRecord
has_one :profile
delegate_missing_to :profile
end
```
The target can be anything callable within the object, e.g. instance variables, methods, constants, etc. Only the public methods of the target are delegated.
Defined in `active_support/core_ext/module/delegation.rb`.
### [3.5. Redefining Methods](#redefining-methods)
There are cases where you need to define a method with `define_method`, but don't know whether a method with that name already exists. If it does, a warning is issued if they are enabled. No big deal, but not clean either.
The method [`redefine_method`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-redefine_method) prevents such a potential warning, removing the existing method before if needed.
You can also use [`silence_redefinition_of_method`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-silence_redefinition_of_method) if you need to define the replacement method yourself (because you're using `delegate`, for example).
Defined in `active_support/core_ext/module/redefine_method.rb`.
## [4. Extensions to `Class`](#extensions-to-class)
### [4.1. Class Attributes](#class-attributes)
#### [4.1.1. `class_attribute`](#class-attribute)
The method [`class_attribute`](https://api.rubyonrails.org/v8.1.4/classes/Class.html#method-i-class_attribute) declares one or more inheritable class attributes that can be overridden at any level down the hierarchy.
```
class A
class_attribute :x
end
class B < A; end
class C < B; end
A.x = :a
B.x # => :a
C.x # => :a
B.x = :b
A.x # => :a
C.x # => :b
C.x = :c
A.x # => :a
B.x # => :b
```
For example `ActionMailer::Base` defines:
```
class_attribute :default_params
self.default_params = {
mime_version: "1.0",
charset: "UTF-8",
content_type: "text/plain",
parts_order: [ "text/plain", "text/enriched", "text/html" ]
}.freeze
```
They can also be accessed and overridden at the instance level.
```
A.x = 1
a1 = A.new
a2 = A.new
a2.x = 2
a1.x # => 1, comes from A
a2.x # => 2, overridden in a2
```
The generation of the writer instance method can be prevented by setting the option `:instance_writer` to `false`.
```
module ActiveRecord
class Base
class_attribute :table_name_prefix, instance_writer: false, default: "my"
end
end
```
A model may find that option useful as a way to prevent mass-assignment from setting the attribute.
The generation of the reader instance method can be prevented by setting the option `:instance_reader` to `false`.
```
class A
class_attribute :x, instance_reader: false
end
A.new.x = 1
A.new.x # NoMethodError
```
For convenience `class_attribute` also defines an instance predicate which is the double negation of what the instance reader returns. In the examples above it would be called `x?`.
When `:instance_reader` is `false`, the instance predicate returns a `NoMethodError` just like the reader method.
If you do not want the instance predicate, pass `instance_predicate: false` and it will not be defined.
Defined in `active_support/core_ext/class/attribute.rb`.
#### [4.1.2. `cattr_reader`, `cattr_writer`, and `cattr_accessor`](#cattr-reader-cattr-writer-and-cattr-accessor)
The macros [`cattr_reader`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-cattr_reader), [`cattr_writer`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-cattr_writer), and [`cattr_accessor`](https://api.rubyonrails.org/v8.1.4/classes/Module.html#method-i-cattr_accessor) are analogous to their `attr_*` counterparts but for classes. They initialize a class variable to `nil` unless it already exists, and generate the corresponding class methods to access it:
```
class MysqlAdapter < AbstractAdapter
# Generates class methods to access @@emulate_booleans.
cattr_accessor :emulate_booleans
end
```
Also, you can pass a block to `cattr_*` to set up the attribute with a default value:
```
class MysqlAdapter < AbstractAdapter
# Generates class methods to access @@emulate_booleans with default value of true.
cattr_accessor :emulate_booleans, default: true
end
```
Instance methods are also created for convenience, but they are simply proxies to the internal value which is shared among the class. As a result, when an instance modifies the value, this affects the entire class hierarchy. This behavior is different than `class_attribute` (see above).
For example:
```
class Foo
cattr_accessor :bar
end
instance = Foo.new
Foo.bar = 1
instance.bar # => 1
instance.bar = 2
Foo.bar # => 2
```
The generation of the reader instance method can be prevented by setting `:instance_reader` to `false` and the generation of the writer instance method can be prevented by setting `:instance_writer` to `false`. Generation of both methods can be prevented by setting `:instance_accessor` to `false`. In all cases, the value must be exactly `false` and not any false value.
```
module A
class B
# No first_name instance reader is generated.
cattr_accessor :first_name, instance_reader: false
# No last_name= instance writer is generated.
cattr_accessor :last_name, instance_writer: false
# No surname instance reader or surname= writer is generated.
cattr_accessor :surname, instance_accessor: false
end
end
```
A model may find it useful to set `:instance_accessor` to `false` as a way to prevent mass-assignment from setting the attribute.
Defined in `active_support/core_ext/module/attribute_accessors.rb`.
### [4.2. Descendants](#extensions-to-class-descendants)
#### [4.2.1. `descendants`](#extensions-to-class-descendants-descendants)
The [`descendants`](https://api.rubyonrails.org/v8.1.4/classes/Class.html#method-i-descendants) method returns all classes that are `<` than its receiver:
```
class C; end
C.descendants # => []
class B < C; end
C.descendants # => [B]
class A < B; end
C.descendants # => [B, A]
class D < C; end
C.descendants # => [B, A, D]
```
The order in which these classes are returned is unspecified.
Defined in `active_support/core_ext/class/subclasses.rb`.
## [5. Extensions to `String`](#extensions-to-string)
### [5.1. Output Safety](#output-safety)
#### [5.1.1. Motivation](#motivation)
Inserting data into HTML templates needs extra care. For example, you can't just interpolate `@review.title` verbatim into an HTML page. For one thing, if the review title is "Flanagan & Matz rules!" the output won't be well-formed because an ampersand has to be escaped as "\&". What's more, depending on the application, that may be a big security hole because users can inject malicious HTML setting a hand-crafted review title. Check out the section about cross-site scripting in the [Security guide](security.html#cross-site-scripting-xss) for further information about the risks.
#### [5.1.2. Safe Strings](#safe-strings)
Active Support has the concept of *(html) safe* strings. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not.
Strings are considered to be *unsafe* by default:
```
"".html_safe? # => false
```
You can obtain a safe string from a given one with the [`html_safe`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-html_safe) method:
```
s = "".html_safe
s.html_safe? # => true
```
It is important to understand that `html_safe` performs no escaping whatsoever, it is just an assertion:
```
s = "".html_safe
s.html_safe? # => true
s # => ""
```
It is your responsibility to ensure calling `html_safe` on a particular string is fine.
If you append onto a safe string, either in-place with `concat`/`<<`, or with `+`, the result is a safe string. Unsafe arguments are escaped:
```
"".html_safe + "<" # => "<"
```
Safe arguments are directly appended:
```
"".html_safe + "<".html_safe # => "<"
```
These methods should not be used in ordinary views. Unsafe values are automatically escaped:
```
<%= @review.title %> <%# fine, escaped if needed %>
```
To insert something verbatim use the [`raw`](https://api.rubyonrails.org/v8.1.4/classes/ActionView/Helpers/OutputSafetyHelper.html#method-i-raw) helper rather than calling `html_safe`:
```
<%= raw @cms.current_template %> <%# inserts @cms.current_template as is %>
```
or, equivalently, use `<%==`:
```
<%== @cms.current_template %> <%# inserts @cms.current_template as is %>
```
The `raw` helper calls `html_safe` for you:
```
def raw(stringish)
stringish.to_s.html_safe
end
```
Defined in `active_support/core_ext/string/output_safety.rb`.
#### [5.1.3. Transformation](#transformation)
As a rule of thumb, except perhaps for concatenation as explained above, any method that may change a string gives you an unsafe string. These are `downcase`, `gsub`, `strip`, `chomp`, `underscore`, etc.
In the case of in-place transformations like `gsub!` the receiver itself becomes unsafe.
The safety bit is lost always, no matter whether the transformation actually changed something.
#### [5.1.4. Conversion and Coercion](#conversion-and-coercion)
Calling `to_s` on a safe string returns a safe string, but coercion with `to_str` returns an unsafe string.
#### [5.1.5. Copying](#copying)
Calling `dup` or `clone` on safe strings yields safe strings.
### [5.2. `remove`](#remove)
The method [`remove`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-remove) will remove all occurrences of the pattern:
```
"Hello World".remove(/Hello /) # => "World"
```
There's also the destructive version `String#remove!`.
Defined in `active_support/core_ext/string/filters.rb`.
### [5.3. `squish`](#squish)
The method [`squish`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-squish) strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each:
```
" \n foo\n\r \t bar \n".squish # => "foo bar"
```
There's also the destructive version `String#squish!`.
Note that it handles both ASCII and Unicode whitespace.
Defined in `active_support/core_ext/string/filters.rb`.
### [5.4. `truncate`](#truncate)
The method [`truncate`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-truncate) returns a copy of its receiver truncated after a given `length`:
```
"Oh dear! Oh dear! I shall be late!".truncate(20)
# => "Oh dear! Oh dear!..."
```
Ellipsis can be customized with the `:omission` option:
```
"Oh dear! Oh dear! I shall be late!".truncate(20, omission: "…")
# => "Oh dear! Oh …"
```
Note in particular that truncation takes into account the length of the omission string.
Pass a `:separator` to truncate the string at a natural break:
```
"Oh dear! Oh dear! I shall be late!".truncate(18)
# => "Oh dear! Oh dea..."
"Oh dear! Oh dear! I shall be late!".truncate(18, separator: " ")
# => "Oh dear! Oh..."
```
The option `:separator` can be a regexp:
```
"Oh dear! Oh dear! I shall be late!".truncate(18, separator: /\s/)
# => "Oh dear! Oh..."
```
In above examples "dear" gets cut first, but then `:separator` prevents it.
Defined in `active_support/core_ext/string/filters.rb`.
### [5.5. `truncate_bytes`](#truncate-bytes)
The method [`truncate_bytes`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-truncate_bytes) returns a copy of its receiver truncated to at most `bytesize` bytes:
```
"ππππ".truncate_bytes(15)
# => "πππβ¦"
```
Ellipsis can be customized with the `:omission` option:
```
"ππππ".truncate_bytes(15, omission: "π")
# => "πππ"
```
Defined in `active_support/core_ext/string/filters.rb`.
### [5.6. `truncate_words`](#truncate-words)
The method [`truncate_words`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-truncate_words) returns a copy of its receiver truncated after a given number of words:
```
"Oh dear! Oh dear! I shall be late!".truncate_words(4)
# => "Oh dear! Oh dear!..."
```
Ellipsis can be customized with the `:omission` option:
```
"Oh dear! Oh dear! I shall be late!".truncate_words(4, omission: "…")
# => "Oh dear! Oh dear!…"
```
Pass a `:separator` to truncate the string at a natural break:
```
"Oh dear! Oh dear! I shall be late!".truncate_words(3, separator: "!")
# => "Oh dear! Oh dear! I shall be late..."
```
The option `:separator` can be a regexp:
```
"Oh dear! Oh dear! I shall be late!".truncate_words(4, separator: /\s/)
# => "Oh dear! Oh dear!..."
```
Defined in `active_support/core_ext/string/filters.rb`.
### [5.7. `inquiry`](#inquiry)
The [`inquiry`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-inquiry) method converts a string into a `StringInquirer` object making equality checks prettier.
```
"production".inquiry.production? # => true
"active".inquiry.inactive? # => false
```
Defined in `active_support/core_ext/string/inquiry.rb`.
### [5.8. `starts_with?` and `ends_with?`](#extensions-to-string-starts-with-questionmark-and-ends-with-questionmark)
Active Support defines 3rd person aliases of `String#start_with?` and `String#end_with?`:
```
"foo".starts_with?("f") # => true
"foo".ends_with?("o") # => true
```
Defined in `active_support/core_ext/string/starts_ends_with.rb`.
### [5.9. `strip_heredoc`](#strip-heredoc)
The method [`strip_heredoc`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-strip_heredoc) strips indentation in heredocs.
For example in
```
if options[:usage]
puts <<-USAGE.strip_heredoc
This command does such and such.
Supported options are:
-h This message
...
USAGE
end
```
the user would see the usage message aligned against the left margin.
Technically, it looks for the least indented line in the whole string, and removes that amount of leading whitespace.
Defined in `active_support/core_ext/string/strip.rb`.
### [5.10. `indent`](#indent)
The [`indent`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-indent) method indents the lines in the receiver:
```
<
def some_method
some_code
end
```
The second argument, `indent_string`, specifies which indent string to use. The default is `nil`, which tells the method to make an educated guess peeking at the first indented line, and fallback to a space if there is none.
```
" foo".indent(2) # => " foo"
"foo\n\t\tbar".indent(2) # => "\t\tfoo\n\t\t\t\tbar"
"foo".indent(2, "\t") # => "\t\tfoo"
```
While `indent_string` is typically one space or tab, it may be any string.
The third argument, `indent_empty_lines`, is a flag that says whether empty lines should be indented. Default is false.
```
"foo\n\nbar".indent(2) # => " foo\n\n bar"
"foo\n\nbar".indent(2, nil, true) # => " foo\n \n bar"
```
The [`indent!`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-indent-21) method performs indentation in-place.
Defined in `active_support/core_ext/string/indent.rb`.
### [5.11. Access](#access)
#### [5.11.1. `at(position)`](#at-position)
The [`at`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-at) method returns the character of the string at position `position`:
```
"hello".at(0) # => "h"
"hello".at(4) # => "o"
"hello".at(-1) # => "o"
"hello".at(10) # => nil
```
Defined in `active_support/core_ext/string/access.rb`.
#### [5.11.2. `from(position)`](#from-position)
The [`from`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-from) method returns the substring of the string starting at position `position`:
```
"hello".from(0) # => "hello"
"hello".from(2) # => "llo"
"hello".from(-2) # => "lo"
"hello".from(10) # => nil
```
Defined in `active_support/core_ext/string/access.rb`.
#### [5.11.3. `to(position)`](#to-position)
The [`to`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-to) method returns the substring of the string up to position `position`:
```
"hello".to(0) # => "h"
"hello".to(2) # => "hel"
"hello".to(-2) # => "hell"
"hello".to(10) # => "hello"
```
Defined in `active_support/core_ext/string/access.rb`.
#### [5.11.4. `first(limit = 1)`](#first-limit-1)
The [`first`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-first) method returns a substring containing the first `limit` characters of the string.
The call `str.first(n)` is equivalent to `str.to(n-1)` if `n` > 0, and returns an empty string for `n` == 0.
Defined in `active_support/core_ext/string/access.rb`.
#### [5.11.5. `last(limit = 1)`](#last-limit-1)
The [`last`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-last) method returns a substring containing the last `limit` characters of the string.
The call `str.last(n)` is equivalent to `str.from(-n)` if `n` > 0, and returns an empty string for `n` == 0.
Defined in `active_support/core_ext/string/access.rb`.
### [5.12. Inflections](#inflections)
#### [5.12.1. `pluralize`](#pluralize)
The method [`pluralize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-pluralize) returns the plural of its receiver:
```
"table".pluralize # => "tables"
"ruby".pluralize # => "rubies"
"equipment".pluralize # => "equipment"
```
As the previous example shows, Active Support knows some irregular plurals and uncountable nouns. Built-in rules can be extended in `config/initializers/inflections.rb`. This file is generated by default, by the `rails new` command and has instructions in comments.
`pluralize` can also take an optional `count` parameter. If `count == 1` the singular form will be returned. For any other value of `count` the plural form will be returned:
```
"dude".pluralize(0) # => "dudes"
"dude".pluralize(1) # => "dude"
"dude".pluralize(2) # => "dudes"
```
Active Record uses this method to compute the default table name that corresponds to a model:
```
# active_record/model_schema.rb
def undecorated_table_name(model_name)
table_name = model_name.to_s.demodulize.underscore
pluralize_table_names ? table_name.pluralize : table_name
end
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.2. `singularize`](#singularize)
The [`singularize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-singularize) method is the inverse of `pluralize`:
```
"tables".singularize # => "table"
"rubies".singularize # => "ruby"
"equipment".singularize # => "equipment"
```
Associations compute the name of the corresponding default associated class using this method:
```
# active_record/reflection.rb
def derive_class_name
class_name = name.to_s.camelize
class_name = class_name.singularize if collection?
class_name
end
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.3. `camelize`](#camelize)
The method [`camelize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-camelize) returns its receiver in camel case:
```
"product".camelize # => "Product"
"admin_user".camelize # => "AdminUser"
```
As a rule of thumb you can think of this method as the one that transforms paths into Ruby class or module names, where slashes separate namespaces:
```
"backoffice/session".camelize # => "Backoffice::Session"
```
For example, Action Pack uses this method to load the class that provides a certain session store:
```
# action_controller/metal/session_management.rb
def session_store=(store)
@@session_store = store.is_a?(Symbol) ?
ActionDispatch::Session.const_get(store.to_s.camelize) :
store
end
```
`camelize` accepts an optional argument, it can be `:upper` (default), or `:lower`. With the latter the first letter becomes lowercase:
```
"visual_effect".camelize(:lower) # => "visualEffect"
```
That may be handy to compute method names in a language that follows that convention, for example JavaScript.
As a rule of thumb you can think of `camelize` as the inverse of `underscore`, though there are cases where that does not hold: `"SSLError".underscore.camelize` gives back `"SslError"`. To support cases such as this, Active Support allows you to specify acronyms in `config/initializers/inflections.rb`:
```
ActiveSupport::Inflector.inflections do |inflect|
inflect.acronym "SSL"
end
"SSLError".underscore.camelize # => "SSLError"
```
`camelize` is aliased to [`camelcase`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-camelcase).
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.4. `underscore`](#underscore)
The method [`underscore`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-underscore) goes the other way around, from camel case to paths:
```
"Product".underscore # => "product"
"AdminUser".underscore # => "admin_user"
```
Also converts "::" back to "/":
```
"Backoffice::Session".underscore # => "backoffice/session"
```
and understands strings that start with lowercase:
```
"visualEffect".underscore # => "visual_effect"
```
`underscore` accepts no argument though.
Rails uses `underscore` to get a lowercased name for controller classes:
```
# actionpack/lib/abstract_controller/base.rb
def controller_path
@controller_path ||= name.delete_suffix("Controller").underscore
end
```
For example, that value is the one you get in `params[:controller]`.
As a rule of thumb you can think of `underscore` as the inverse of `camelize`, though there are cases where that does not hold. For example, `"SSLError".underscore.camelize` gives back `"SslError"`.
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.5. `titleize`](#titleize)
The method [`titleize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-titleize) capitalizes the words in the receiver:
```
"alice in wonderland".titleize # => "Alice In Wonderland"
"fermat's enigma".titleize # => "Fermat's Enigma"
```
`titleize` is aliased to [`titlecase`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-titlecase).
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.6. `dasherize`](#dasherize)
The method [`dasherize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-dasherize) replaces the underscores in the receiver with dashes:
```
"name".dasherize # => "name"
"contact_data".dasherize # => "contact-data"
```
The XML serializer of models uses this method to dasherize node names:
```
# active_model/serializers/xml.rb
def reformat_name(name)
name = name.camelize if camelize?
dasherize? ? name.dasherize : name
end
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.7. `demodulize`](#demodulize)
Given a string with a qualified constant name, [`demodulize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-demodulize) returns the very constant name, that is, the rightmost part of it:
```
"Product".demodulize # => "Product"
"Backoffice::UsersController".demodulize # => "UsersController"
"Admin::Hotel::ReservationUtils".demodulize # => "ReservationUtils"
"::Inflections".demodulize # => "Inflections"
"".demodulize # => ""
```
Active Record for example uses this method to compute the name of a counter cache column:
```
# active_record/reflection.rb
def counter_cache_column
if options[:counter_cache] == true
"#{active_record.name.demodulize.underscore.pluralize}_count"
elsif options[:counter_cache]
options[:counter_cache]
end
end
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.8. `deconstantize`](#deconstantize)
Given a string with a qualified constant reference expression, [`deconstantize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-deconstantize) removes the rightmost segment, generally leaving the name of the constant's container:
```
"Product".deconstantize # => ""
"Backoffice::UsersController".deconstantize # => "Backoffice"
"Admin::Hotel::ReservationUtils".deconstantize # => "Admin::Hotel"
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.9. `parameterize`](#parameterize)
The method [`parameterize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-parameterize) normalizes its receiver in a way that can be used in pretty URLs.
```
"John Smith".parameterize # => "john-smith"
"Kurt GΓΆdel".parameterize # => "kurt-godel"
```
To preserve the case of the string, set the `preserve_case` argument to true. By default, `preserve_case` is set to false.
```
"John Smith".parameterize(preserve_case: true) # => "John-Smith"
"Kurt GΓΆdel".parameterize(preserve_case: true) # => "Kurt-Godel"
```
To use a custom separator, override the `separator` argument.
```
"John Smith".parameterize(separator: "_") # => "john_smith"
"Kurt GΓΆdel".parameterize(separator: "_") # => "kurt_godel"
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.10. `tableize`](#tableize)
The method [`tableize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-tableize) is `underscore` followed by `pluralize`.
```
"Person".tableize # => "people"
"Invoice".tableize # => "invoices"
"InvoiceLine".tableize # => "invoice_lines"
```
As a rule of thumb, `tableize` returns the table name that corresponds to a given model for simple cases. The actual implementation in Active Record is not straight `tableize` indeed, because it also demodulizes the class name and checks a few options that may affect the returned string.
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.11. `classify`](#classify)
The method [`classify`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-classify) is the inverse of `tableize`. It gives you the class name corresponding to a table name:
```
"people".classify # => "Person"
"invoices".classify # => "Invoice"
"invoice_lines".classify # => "InvoiceLine"
```
The method understands qualified table names:
```
"highrise_production.companies".classify # => "Company"
```
Note that `classify` returns a class name as a string. You can get the actual class object by invoking `constantize` on it, explained next.
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.12. `constantize`](#constantize)
The method [`constantize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-constantize) resolves the constant reference expression in its receiver:
```
"Integer".constantize # => Integer
module M
X = 1
end
"M::X".constantize # => 1
```
If the string evaluates to no known constant, or its content is not even a valid constant name, `constantize` raises `NameError`.
Constant name resolution by `constantize` starts always at the top-level `Object` even if there is no leading "::".
```
X = :in_Object
module M
X = :in_M
X # => :in_M
"::X".constantize # => :in_Object
"X".constantize # => :in_Object (!)
end
```
So, it is in general not equivalent to what Ruby would do in the same spot, had a real constant be evaluated.
Mailer test cases obtain the mailer being tested from the name of the test class using `constantize`:
```
# action_mailer/test_case.rb
def determine_default_mailer(name)
name.delete_suffix("Test").constantize
rescue NameError => e
raise NonInferrableMailerError.new(name)
end
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.13. `humanize`](#humanize)
The method [`humanize`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-humanize) tweaks an attribute name for display to end users.
Specifically, it performs these transformations:
* Applies human inflection rules to the argument.
* Deletes leading underscores, if any.
* Removes a "\_id" suffix if present.
* Replaces underscores with spaces, if any.
* Downcases all words except acronyms.
* Capitalizes the first word.
The capitalization of the first word can be turned off by setting the `:capitalize` option to false (default is true).
```
"name".humanize # => "Name"
"author_id".humanize # => "Author"
"author_id".humanize(capitalize: false) # => "author"
"comments_count".humanize # => "Comments count"
"_id".humanize # => "Id"
```
If "SSL" was defined to be an acronym:
```
"ssl_error".humanize # => "SSL error"
```
The helper method `full_messages` uses `humanize` as a fallback to include attribute names:
```
def full_messages
map { |attribute, message| full_message(attribute, message) }
end
def full_message
# ...
attr_name = attribute.to_s.tr(".", "_").humanize
attr_name = @base.class.human_attribute_name(attribute, default: attr_name)
# ...
end
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.14. `foreign_key`](#foreign-key)
The method [`foreign_key`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-foreign_key) gives a foreign key column name from a class name. To do so it demodulizes, underscores, and adds "\_id":
```
"User".foreign_key # => "user_id"
"InvoiceLine".foreign_key # => "invoice_line_id"
"Admin::Session".foreign_key # => "session_id"
```
Pass a false argument if you do not want the underscore in "\_id":
```
"User".foreign_key(false) # => "userid"
```
Associations use this method to infer foreign keys, for example `has_one` and `has_many` do this:
```
# active_record/associations.rb
foreign_key = options[:foreign_key] || reflection.active_record.name.foreign_key
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.15. `upcase_first`](#upcase-first)
The method [`upcase_first`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-upcase_first) capitalizes the first letter of the receiver:
```
"employee salary".upcase_first # => "Employee salary"
"".upcase_first # => ""
```
Defined in `active_support/core_ext/string/inflections.rb`.
#### [5.12.16. `downcase_first`](#downcase-first)
The method [`downcase_first`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-downcase_first) converts the first letter of the receiver to lowercase:
```
"If I had read Alice in Wonderland".downcase_first # => "if I had read Alice in Wonderland"
"".downcase_first # => ""
```
Defined in `active_support/core_ext/string/inflections.rb`.
### [5.13. Conversions](#extensions-to-string-conversions)
#### [5.13.1. `to_date`, `to_time`, `to_datetime`](#to-date-to-time-to-datetime)
The methods [`to_date`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-to_date), [`to_time`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-to_time), and [`to_datetime`](https://api.rubyonrails.org/v8.1.4/classes/String.html#method-i-to_datetime) are basically convenience wrappers around `Date._parse`:
```
"2010-07-27".to_date # => Tue, 27 Jul 2010
"2010-07-27 23:37:00".to_time # => 2010-07-27 23:37:00 +0200
"2010-07-27 23:37:00".to_datetime # => Tue, 27 Jul 2010 23:37:00 +0000
```
`to_time` receives an optional argument `:utc` or `:local`, to indicate which time zone you want the time in:
```
"2010-07-27 23:42:00".to_time(:utc) # => 2010-07-27 23:42:00 UTC
"2010-07-27 23:42:00".to_time(:local) # => 2010-07-27 23:42:00 +0200
```
Default is `:local`.
Please refer to the documentation of `Date._parse` for further details.
The three of them return `nil` for blank receivers.
Defined in `active_support/core_ext/string/conversions.rb`.
## [6. Extensions to `Symbol`](#extensions-to-symbol)
### [6.1. `starts_with?` and `ends_with?`](#extensions-to-symbol-starts-with-questionmark-and-ends-with-questionmark)
Active Support defines 3rd person aliases of `Symbol#start_with?` and `Symbol#end_with?`:
```
:foo.starts_with?("f") # => true
:foo.ends_with?("o") # => true
```
Defined in `active_support/core_ext/symbol/starts_ends_with.rb`.
## [7. Extensions to `Numeric`](#extensions-to-numeric)
### [7.1. Bytes](#bytes)
All numbers respond to these methods:
* [`bytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-bytes)
* [`kilobytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-kilobytes)
* [`megabytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-megabytes)
* [`gigabytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-gigabytes)
* [`terabytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-terabytes)
* [`petabytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-petabytes)
* [`exabytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-exabytes)
* [`zettabytes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-zettabytes)
They return the corresponding amount of bytes, using a conversion factor of 1024:
```
2.kilobytes # => 2048
3.megabytes # => 3145728
3.5.gigabytes # => 3758096384.0
-4.exabytes # => -4611686018427387904
```
Singular forms are aliased so you are able to say:
```
1.megabyte # => 1048576
```
Defined in `active_support/core_ext/numeric/bytes.rb`.
### [7.2. Time](#extensions-to-numeric-time)
The following methods:
* [`seconds`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-seconds)
* [`minutes`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-minutes)
* [`hours`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-hours)
* [`days`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-days)
* [`weeks`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-weeks)
* [`fortnights`](https://api.rubyonrails.org/v8.1.4/classes/Numeric.html#method-i-fortnights)
enable time declarations and calculations, like `45.minutes + 2.hours + 4.weeks`. Their return values can also be added to or subtracted from Time objects.
These methods can be combined with [`from_now`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/Duration.html#method-i-from_now), [`ago`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/Duration.html#method-i-ago), etc, for precise date calculations. For example:
```
# equivalent to Time.current.advance(days: 1)
1.day.from_now
# equivalent to Time.current.advance(weeks: 2)
2.weeks.from_now
# equivalent to Time.current.advance(days: 4, weeks: 5)
(4.days + 5.weeks).from_now
```
For other durations please refer to the time extensions to `Integer`.
Defined in `active_support/core_ext/numeric/time.rb`.
### [7.3. Formatting](#formatting)
Enables the formatting of numbers in a variety of ways.
Produce a string representation of a number as a telephone number:
```
5551234.to_fs(:phone)
# => 555-1234
1235551234.to_fs(:phone)
# => 123-555-1234
1235551234.to_fs(:phone, area_code: true)
# => (123) 555-1234
1235551234.to_fs(:phone, delimiter: " ")
# => 123 555 1234
1235551234.to_fs(:phone, area_code: true, extension: 555)
# => (123) 555-1234 x 555
1235551234.to_fs(:phone, country_code: 1)
# => +1-123-555-1234
```
Produce a string representation of a number as currency:
```
1234567890.50.to_fs(:currency) # => $1,234,567,890.50
1234567890.506.to_fs(:currency) # => $1,234,567,890.51
1234567890.506.to_fs(:currency, precision: 3) # => $1,234,567,890.506
```
Produce a string representation of a number as a percentage:
```
100.to_fs(:percentage)
# => 100.000%
100.to_fs(:percentage, precision: 0)
# => 100%
1000.to_fs(:percentage, delimiter: ".", separator: ",")
# => 1.000,000%
302.24398923423.to_fs(:percentage, precision: 5)
# => 302.24399%
```
Produce a string representation of a number in delimited form:
```
12345678.to_fs(:delimited) # => 12,345,678
12345678.05.to_fs(:delimited) # => 12,345,678.05
12345678.to_fs(:delimited, delimiter: ".") # => 12.345.678
12345678.to_fs(:delimited, delimiter: ",") # => 12,345,678
12345678.05.to_fs(:delimited, separator: " ") # => 12,345,678 05
```
Produce a string representation of a number rounded to a precision:
```
111.2345.to_fs(:rounded) # => 111.235
111.2345.to_fs(:rounded, precision: 2) # => 111.23
13.to_fs(:rounded, precision: 5) # => 13.00000
389.32314.to_fs(:rounded, precision: 0) # => 389
111.2345.to_fs(:rounded, significant: true) # => 111
```
Produce a string representation of a number as a human-readable number of bytes:
```
123.to_fs(:human_size) # => 123 Bytes
1234.to_fs(:human_size) # => 1.21 KB
12345.to_fs(:human_size) # => 12.1 KB
1234567.to_fs(:human_size) # => 1.18 MB
1234567890.to_fs(:human_size) # => 1.15 GB
1234567890123.to_fs(:human_size) # => 1.12 TB
1234567890123456.to_fs(:human_size) # => 1.1 PB
1234567890123456789.to_fs(:human_size) # => 1.07 EB
```
Produce a string representation of a number in human-readable words:
```
123.to_fs(:human) # => "123"
1234.to_fs(:human) # => "1.23 Thousand"
12345.to_fs(:human) # => "12.3 Thousand"
1234567.to_fs(:human) # => "1.23 Million"
1234567890.to_fs(:human) # => "1.23 Billion"
1234567890123.to_fs(:human) # => "1.23 Trillion"
1234567890123456.to_fs(:human) # => "1.23 Quadrillion"
```
Defined in `active_support/core_ext/numeric/conversions.rb`.
## [8. Extensions to `Integer`](#extensions-to-integer)
### [8.1. `multiple_of?`](#multiple-of-questionmark)
The method [`multiple_of?`](https://api.rubyonrails.org/v8.1.4/classes/Integer.html#method-i-multiple_of-3F) tests whether an integer is multiple of the argument:
```
2.multiple_of?(1) # => true
1.multiple_of?(2) # => false
```
Defined in `active_support/core_ext/integer/multiple.rb`.
### [8.2. `ordinal`](#ordinal)
The method [`ordinal`](https://api.rubyonrails.org/v8.1.4/classes/Integer.html#method-i-ordinal) returns the ordinal suffix string corresponding to the receiver integer:
```
1.ordinal # => "st"
2.ordinal # => "nd"
53.ordinal # => "rd"
2009.ordinal # => "th"
-21.ordinal # => "st"
-134.ordinal # => "th"
```
Defined in `active_support/core_ext/integer/inflections.rb`.
### [8.3. `ordinalize`](#ordinalize)
The method [`ordinalize`](https://api.rubyonrails.org/v8.1.4/classes/Integer.html#method-i-ordinalize) returns the ordinal string corresponding to the receiver integer. In comparison, note that the `ordinal` method returns **only** the suffix string.
```
1.ordinalize # => "1st"
2.ordinalize # => "2nd"
53.ordinalize # => "53rd"
2009.ordinalize # => "2009th"
-21.ordinalize # => "-21st"
-134.ordinalize # => "-134th"
```
Defined in `active_support/core_ext/integer/inflections.rb`.
### [8.4. Time](#extensions-to-integer-time)
The following methods:
* [`months`](https://api.rubyonrails.org/v8.1.4/classes/Integer.html#method-i-months)
* [`years`](https://api.rubyonrails.org/v8.1.4/classes/Integer.html#method-i-years)
enable time declarations and calculations, like `4.months + 5.years`. Their return values can also be added to or subtracted from Time objects.
These methods can be combined with [`from_now`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/Duration.html#method-i-from_now), [`ago`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/Duration.html#method-i-ago), etc, for precise date calculations. For example:
```
# equivalent to Time.current.advance(months: 1)
1.month.from_now
# equivalent to Time.current.advance(years: 2)
2.years.from_now
# equivalent to Time.current.advance(months: 4, years: 5)
(4.months + 5.years).from_now
```
For other durations please refer to the time extensions to `Numeric`.
Defined in `active_support/core_ext/integer/time.rb`.
## [9. Extensions to `BigDecimal`](#extensions-to-bigdecimal)
### [9.1. `to_s`](#to-s)
The method `to_s` provides a default specifier of "F". This means that a simple call to `to_s` will result in floating-point representation instead of scientific notation:
```
BigDecimal(5.00, 6).to_s # => "5.0"
```
Scientific notation is still supported:
```
BigDecimal(5.00, 6).to_s("e") # => "0.5E1"
```
## [10. Extensions to `Enumerable`](#extensions-to-enumerable)
### [10.1. `index_by`](#index-by)
The method [`index_by`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-index_by) generates a hash with the elements of an enumerable indexed by some key.
It iterates through the collection and passes each element to a block. The element will be keyed by the value returned by the block:
```
invoices.index_by(&:number)
# => {"2009-032" => , "2009-008" => , ...}
```
Keys should normally be unique. If the block returns the same value for different elements no collection is built for that key. The last item will win.
Defined in `active_support/core_ext/enumerable.rb`.
### [10.2. `index_with`](#index-with)
The method [`index_with`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-index_with) generates a hash with the elements of an enumerable as keys. The value is either a passed default or returned in a block.
```
post = Post.new(title: "hey there", body: "what's up?")
%i( title body ).index_with { |attr_name| post.public_send(attr_name) }
# => { title: "hey there", body: "what's up?" }
WEEKDAYS.index_with(Interval.all_day)
# => { monday: [ 0, 1440 ], β¦ }
```
Defined in `active_support/core_ext/enumerable.rb`.
### [10.3. `many?`](#many-questionmark)
The method [`many?`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-many-3F) is shorthand for `collection.size > 1`:
```
<% if pages.many? %>
<%= pagination_links %>
<% end %>
```
If an optional block is given, `many?` only takes into account those elements that return true:
```
@see_more = videos.many? { |video| video.category == params[:category] }
```
Defined in `active_support/core_ext/enumerable.rb`.
### [10.4. `exclude?`](#exclude-questionmark)
The predicate [`exclude?`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-exclude-3F) tests whether a given object does **not** belong to the collection. It is the negation of the built-in `include?`:
```
to_visit << node if visited.exclude?(node)
```
Defined in `active_support/core_ext/enumerable.rb`.
### [10.5. `including`](#including)
The method [`including`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-including) returns a new enumerable that includes the passed elements:
```
[ 1, 2, 3 ].including(4, 5) # => [ 1, 2, 3, 4, 5 ]
["David", "Rafael"].including %w[ Aaron Todd ] # => ["David", "Rafael", "Aaron", "Todd"]
```
Defined in `active_support/core_ext/enumerable.rb`.
### [10.6. `excluding`](#excluding)
The method [`excluding`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-excluding) returns a copy of an enumerable with the specified elements removed:
```
["David", "Rafael", "Aaron", "Todd"].excluding("Aaron", "Todd") # => ["David", "Rafael"]
```
`excluding` is aliased to [`without`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-without).
Defined in `active_support/core_ext/enumerable.rb`.
### [10.7. `pluck`](#pluck)
The method [`pluck`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-pluck) extracts the given key from each element:
```
[{ name: "David" }, { name: "Rafael" }, { name: "Aaron" }].pluck(:name) # => ["David", "Rafael", "Aaron"]
[{ id: 1, name: "David" }, { id: 2, name: "Rafael" }].pluck(:id, :name) # => [[1, "David"], [2, "Rafael"]]
```
Defined in `active_support/core_ext/enumerable.rb`.
### [10.8. `pick`](#pick)
The method [`pick`](https://api.rubyonrails.org/v8.1.4/classes/Enumerable.html#method-i-pick) extracts the given key from the first element:
```
[{ name: "David" }, { name: "Rafael" }, { name: "Aaron" }].pick(:name) # => "David"
[{ id: 1, name: "David" }, { id: 2, name: "Rafael" }].pick(:id, :name) # => [1, "David"]
```
Defined in `active_support/core_ext/enumerable.rb`.
## [11. Extensions to `Array`](#extensions-to-array)
### [11.1. Accessing](#accessing)
Active Support augments the API of arrays to ease certain ways of accessing them. For example, [`to`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-to) returns the subarray of elements up to the one at the passed index:
```
%w(a b c d).to(2) # => ["a", "b", "c"]
[].to(7) # => []
```
Similarly, [`from`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-from) returns the tail from the element at the passed index to the end. If the index is greater than the length of the array, it returns an empty array.
```
%w(a b c d).from(2) # => ["c", "d"]
%w(a b c d).from(10) # => []
[].from(0) # => []
```
The method [`including`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-including) returns a new array that includes the passed elements:
```
[ 1, 2, 3 ].including(4, 5) # => [ 1, 2, 3, 4, 5 ]
[ [ 0, 1 ] ].including([ [ 1, 0 ] ]) # => [ [ 0, 1 ], [ 1, 0 ] ]
```
The method [`excluding`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-excluding) returns a copy of the Array excluding the specified elements. This is an optimization of `Enumerable#excluding` that uses `Array#-` instead of `Array#reject` for performance reasons.
```
["David", "Rafael", "Aaron", "Todd"].excluding("Aaron", "Todd") # => ["David", "Rafael"]
[ [ 0, 1 ], [ 1, 0 ] ].excluding([ [ 1, 0 ] ]) # => [ [ 0, 1 ] ]
```
The methods [`second`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-second), [`third`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-third), [`fourth`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-fourth), and [`fifth`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-fifth) return the corresponding element, as do [`second_to_last`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-second_to_last) and [`third_to_last`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-third_to_last) (`first` and `last` are built-in). Thanks to social wisdom and positive constructiveness all around, [`forty_two`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-forty_two) is also available.
```
%w(a b c d).third # => "c"
%w(a b c d).fifth # => nil
```
Defined in `active_support/core_ext/array/access.rb`.
### [11.2. Extracting](#extensions-to-array-extracting)
The method [`extract!`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-extract-21) removes and returns the elements for which the block returns a true value. If no block is given, an Enumerator is returned instead.
```
numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
odd_numbers = numbers.extract! { |number| number.odd? } # => [1, 3, 5, 7, 9]
numbers # => [0, 2, 4, 6, 8]
```
Defined in `active_support/core_ext/array/extract.rb`.
### [11.3. Options Extraction](#options-extraction)
When the last argument in a method call is a hash, except perhaps for a `&block` argument, Ruby allows you to omit the brackets:
```
User.exists?(email: params[:email])
```
That syntactic sugar is used a lot in Rails to avoid positional arguments where there would be too many, offering instead interfaces that emulate named parameters. In particular it is very idiomatic to use a trailing hash for options.
If a method expects a variable number of arguments and uses `*` in its declaration, however, such an options hash ends up being an item of the array of arguments, where it loses its role.
In those cases, you may give an options hash a distinguished treatment with [`extract_options!`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-extract_options-21). This method checks the type of the last item of an array. If it is a hash it pops it and returns it, otherwise it returns an empty hash.
Let's see for example the definition of the `caches_action` controller macro:
```
def caches_action(*actions)
return unless cache_configured?
options = actions.extract_options!
# ...
end
```
This method receives an arbitrary number of action names, and an optional hash of options as last argument. With the call to `extract_options!` you obtain the options hash and remove it from `actions` in a simple and explicit way.
Defined in `active_support/core_ext/array/extract_options.rb`.
### [11.4. Conversions](#extensions-to-array-conversions)
#### [11.4.1. `to_sentence`](#to-sentence)
The method [`to_sentence`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-to_sentence) turns an array into a string containing a sentence that enumerates its items:
```
%w().to_sentence # => ""
%w(Earth).to_sentence # => "Earth"
%w(Earth Wind).to_sentence # => "Earth and Wind"
%w(Earth Wind Fire).to_sentence # => "Earth, Wind, and Fire"
```
This method accepts three options:
* `:two_words_connector`: What is used for arrays of length 2. Default is " and ".
* `:words_connector`: What is used to join the elements of arrays with 3 or more elements, except for the last two. Default is ", ".
* `:last_word_connector`: What is used to join the last items of an array with 3 or more elements. Default is ", and ".
The defaults for these options can be localized, their keys are:
| Option | I18n key |
| ---------------------- | ----------------------------------- |
| `:two_words_connector` | `support.array.two_words_connector` |
| `:words_connector` | `support.array.words_connector` |
| `:last_word_connector` | `support.array.last_word_connector` |
Defined in `active_support/core_ext/array/conversions.rb`.
#### [11.4.2. `to_fs`](#extensions-to-array-conversions-to-fs)
The method [`to_fs`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-to_fs) acts like `to_s` by default.
If the array contains items that respond to `id`, however, the symbol `:db` may be passed as argument. That's typically used with collections of Active Record objects. Returned strings are:
```
[].to_fs(:db) # => "null"
[user].to_fs(:db) # => "8456"
invoice.lines.to_fs(:db) # => "23,567,556,12"
```
Integers in the example above are supposed to come from the respective calls to `id`.
Defined in `active_support/core_ext/array/conversions.rb`.
#### [11.4.3. `to_xml`](#extensions-to-array-conversions-to-xml)
The method [`to_xml`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-to_xml) returns a string containing an XML representation of its receiver:
```
Contributor.limit(2).order(:rank).to_xml
# =>
#
#
#
# 4356
# Jeremy Kemper
# 1
# jeremy-kemper
#
#
# 4404
# David Heinemeier Hansson
# 2
# david-heinemeier-hansson
#
#
```
To do so it sends `to_xml` to every item in turn, and collects the results under a root node. All items must respond to `to_xml`, an exception is raised otherwise.
By default, the name of the root element is the underscored and dasherized plural of the name of the class of the first item, provided the rest of elements belong to that type (checked with `is_a?`) and they are not hashes. In the example above that's "contributors".
If there's any element that does not belong to the type of the first one the root node becomes "objects":
```
[Contributor.first, Commit.first].to_xml
# =>
#
#
#
#
#
```
If the receiver is an array of hashes the root element is by default also "objects":
```
[{ a: 1, b: 2 }, { c: 3 }].to_xml
# =>
#
#
#
#
#
```
If the collection is empty the root element is by default "nil-classes". That's a gotcha, for example the root element of the list of contributors above would not be "contributors" if the collection was empty, but "nil-classes". You may use the `:root` option to ensure a consistent root element.
The name of children nodes is by default the name of the root node singularized. In the examples above we've seen "contributor" and "object". The option `:children` allows you to set these node names.
The default XML builder is a fresh instance of `Builder::XmlMarkup`. You can configure your own builder via the `:builder` option. The method also accepts options like `:dasherize` and friends, they are forwarded to the builder:
```
Contributor.limit(2).order(:rank).to_xml(skip_types: true)
# =>
#
#
#
# 4356
# Jeremy Kemper
# 1
# jeremy-kemper
#
#
# 4404
# David Heinemeier Hansson
# 2
# david-heinemeier-hansson
#
#
```
Defined in `active_support/core_ext/array/conversions.rb`.
### [11.5. Wrapping](#wrapping)
The method [`Array.wrap`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-c-wrap) wraps its argument in an array unless it is already an array (or array-like).
Specifically:
* If the argument is `nil` an empty array is returned.
* Otherwise, if the argument responds to `to_ary` it is invoked, and if the value of `to_ary` is not `nil`, it is returned.
* Otherwise, an array with the argument as its single element is returned.
```
Array.wrap(nil) # => []
Array.wrap([1, 2, 3]) # => [1, 2, 3]
Array.wrap(0) # => [0]
```
This method is similar in purpose to `Kernel#Array`, but there are some differences:
* If the argument responds to `to_ary` the method is invoked. `Kernel#Array` moves on to try `to_a` if the returned value is `nil`, but `Array.wrap` returns an array with the argument as its single element right away.
* If the returned value from `to_ary` is neither `nil` nor an `Array` object, `Kernel#Array` raises an exception, while `Array.wrap` does not, it just returns the value.
* It does not call `to_a` on the argument, if the argument does not respond to `to_ary` it returns an array with the argument as its single element.
The last point is particularly worth comparing for some enumerables:
```
Array.wrap(foo: :bar) # => [{:foo=>:bar}]
Array(foo: :bar) # => [[:foo, :bar]]
```
There's also a related idiom that uses the splat operator:
```
[*object]
```
Defined in `active_support/core_ext/array/wrap.rb`.
### [11.6. Duplicating](#duplicating)
The method [`Array#deep_dup`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-deep_dup) duplicates itself and all objects inside recursively with the Active Support method `Object#deep_dup`. It works like `Array#map`, sending `deep_dup` method to each object inside.
```
array = [1, [2, 3]]
dup = array.deep_dup
dup[1][2] = 4
array[1][2] == nil # => true
```
Defined in `active_support/core_ext/object/deep_dup.rb`.
### [11.7. Grouping](#grouping)
#### [11.7.1. `in_groups_of(number, fill_with = nil)`](#in-groups-of-number-fill-with-nil)
The method [`in_groups_of`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-in_groups_of) splits an array into consecutive groups of a certain size. It returns an array with the groups:
```
[1, 2, 3].in_groups_of(2) # => [[1, 2], [3, nil]]
```
or yields them in turn if a block is passed:
```
<% sample.in_groups_of(3) do |a, b, c| %>
<%= a %>
<%= b %>
<%= c %>
<% end %>
```
The first example shows how `in_groups_of` fills the last group with as many `nil` elements as needed to have the requested size. You can change this padding value using the second optional argument:
```
[1, 2, 3].in_groups_of(2, 0) # => [[1, 2], [3, 0]]
```
And you can tell the method not to fill the last group by passing `false`:
```
[1, 2, 3].in_groups_of(2, false) # => [[1, 2], [3]]
```
As a consequence `false` can't be used as a padding value.
Defined in `active_support/core_ext/array/grouping.rb`.
#### [11.7.2. `in_groups(number, fill_with = nil)`](#in-groups-number-fill-with-nil)
The method [`in_groups`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-in_groups) splits an array into a certain number of groups. The method returns an array with the groups:
```
%w(1 2 3 4 5 6 7).in_groups(3)
# => [["1", "2", "3"], ["4", "5", nil], ["6", "7", nil]]
```
or yields them in turn if a block is passed:
```
%w(1 2 3 4 5 6 7).in_groups(3) { |group| p group }
["1", "2", "3"]
["4", "5", nil]
["6", "7", nil]
```
The examples above show that `in_groups` fills some groups with a trailing `nil` element as needed. A group can get at most one of these extra elements, the rightmost one if any. And the groups that have them are always the last ones.
You can change this padding value using the second optional argument:
```
%w(1 2 3 4 5 6 7).in_groups(3, "0")
# => [["1", "2", "3"], ["4", "5", "0"], ["6", "7", "0"]]
```
And you can tell the method not to fill the smaller groups by passing `false`:
```
%w(1 2 3 4 5 6 7).in_groups(3, false)
# => [["1", "2", "3"], ["4", "5"], ["6", "7"]]
```
As a consequence `false` can't be used as a padding value.
Defined in `active_support/core_ext/array/grouping.rb`.
#### [11.7.3. `split(value = nil)`](#split-value-nil)
The method [`split`](https://api.rubyonrails.org/v8.1.4/classes/Array.html#method-i-split) divides an array by a separator and returns the resulting chunks.
If a block is passed the separators are those elements of the array for which the block returns true:
```
(-5..5).to_a.split { |i| i.multiple_of?(4) }
# => [[-5], [-3, -2, -1], [1, 2, 3], [5]]
```
Otherwise, the value received as argument, which defaults to `nil`, is the separator:
```
[0, 1, -5, 1, 1, "foo", "bar"].split(1)
# => [[0], [-5], [], ["foo", "bar"]]
```
Observe in the previous example that consecutive separators result in empty arrays.
Defined in `active_support/core_ext/array/grouping.rb`.
## [12. Extensions to `Hash`](#extensions-to-hash)
### [12.1. Conversions](#conversions)
#### [12.1.1. `to_xml`](#conversions-to-xml)
The method [`to_xml`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-to_xml) returns a string containing an XML representation of its receiver:
```
{ foo: 1, bar: 2 }.to_xml
# =>
#
#
# 1
# 2
#
```
To do so, the method loops over the pairs and builds nodes that depend on the *values*. Given a pair `key`, `value`:
* If `value` is a hash there's a recursive call with `key` as `:root`.
* If `value` is an array there's a recursive call with `key` as `:root`, and `key` singularized as `:children`.
* If `value` is a callable object it must expect one or two arguments. Depending on the arity, the callable is invoked with the `options` hash as first argument with `key` as `:root`, and `key` singularized as second argument. Its return value becomes a new node.
* If `value` responds to `to_xml` the method is invoked with `key` as `:root`.
* Otherwise, a node with `key` as tag is created with a string representation of `value` as text node. If `value` is `nil` an attribute "nil" set to "true" is added. Unless the option `:skip_types` exists and is true, an attribute "type" is added as well according to the following mapping:
```
XML_TYPE_NAMES = {
"Symbol" => "symbol",
"Integer" => "integer",
"BigDecimal" => "decimal",
"Float" => "float",
"TrueClass" => "boolean",
"FalseClass" => "boolean",
"Date" => "date",
"DateTime" => "datetime",
"Time" => "datetime"
}
```
By default the root node is "hash", but that's configurable via the `:root` option.
The default XML builder is a fresh instance of `Builder::XmlMarkup`. You can configure your own builder with the `:builder` option. The method also accepts options like `:dasherize` and friends, they are forwarded to the builder.
Defined in `active_support/core_ext/hash/conversions.rb`.
### [12.2. Merging](#merging)
Ruby has a built-in method `Hash#merge` that merges two hashes:
```
{ a: 1, b: 1 }.merge(a: 0, c: 2)
# => {:a=>0, :b=>1, :c=>2}
```
Active Support defines a few more ways of merging hashes that may be convenient.
#### [12.2.1. `reverse_merge` and `reverse_merge!`](#reverse-merge-and-reverse-merge-bang)
In case of collision the key in the hash of the argument wins in `merge`. You can support option hashes with default values in a compact way with this idiom:
```
options = { length: 30, omission: "..." }.merge(options)
```
Active Support defines [`reverse_merge`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-reverse_merge) in case you prefer this alternative notation:
```
options = options.reverse_merge(length: 30, omission: "...")
```
And a bang version [`reverse_merge!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-reverse_merge-21) that performs the merge in place:
```
options.reverse_merge!(length: 30, omission: "...")
```
Take into account that `reverse_merge!` may change the hash in the caller, which may or may not be a good idea.
Defined in `active_support/core_ext/hash/reverse_merge.rb`.
#### [12.2.2. `reverse_update`](#reverse-update)
The method [`reverse_update`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-reverse_update) is an alias for `reverse_merge!`, explained above.
Note that `reverse_update` has no bang.
Defined in `active_support/core_ext/hash/reverse_merge.rb`.
#### [12.2.3. `deep_merge` and `deep_merge!`](#deep-merge-and-deep-merge-bang)
As you can see in the previous example if a key is found in both hashes the value in the one in the argument wins.
Active Support defines [`Hash#deep_merge`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_merge). In a deep merge, if a key is found in both hashes and their values are hashes in turn, then their *merge* becomes the value in the resulting hash:
```
{ a: { b: 1 } }.deep_merge(a: { c: 2 })
# => {:a=>{:b=>1, :c=>2}}
```
The method [`deep_merge!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_merge-21) performs a deep merge in place.
Defined in `active_support/core_ext/hash/deep_merge.rb`.
### [12.3. Deep Duplicating](#deep-duplicating)
The method [`Hash#deep_dup`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_dup) duplicates itself and all keys and values inside recursively with Active Support method `Object#deep_dup`. It works like `Enumerator#each_with_object` with sending `deep_dup` method to each pair inside.
```
hash = { a: 1, b: { c: 2, d: [3, 4] } }
dup = hash.deep_dup
dup[:b][:e] = 5
dup[:b][:d] << 5
hash[:b][:e] == nil # => true
hash[:b][:d] == [3, 4] # => true
```
Defined in `active_support/core_ext/object/deep_dup.rb`.
### [12.4. Working with Keys](#working-with-keys)
#### [12.4.1. `except!`](#except-bang)
The method [`except!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-except-21) is identical to the built-in `except` method but removes keys in place, returning `self`.
```
{ a: 1, b: 2 }.except!(:a) # => {:b=>2}
{ a: 1, b: 2 }.except!(:c) # => {:a=>1, :b=>2}
```
If the receiver responds to `convert_key`, the method is called on each of the arguments. This allows `except!` (and `except`) to play nice with hashes with indifferent access for instance:
```
{ a: 1 }.with_indifferent_access.except!(:a) # => {}
{ a: 1 }.with_indifferent_access.except!("a") # => {}
```
Defined in `active_support/core_ext/hash/except.rb`.
#### [12.4.2. `stringify_keys` and `stringify_keys!`](#stringify-keys-and-stringify-keys-bang)
The method [`stringify_keys`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-stringify_keys) returns a hash that has a stringified version of the keys in the receiver. It does so by sending `to_s` to them:
```
{ nil => nil, 1 => 1, a: :a }.stringify_keys
# => {"" => nil, "1" => 1, "a" => :a}
```
In case of key collision, the value will be the one most recently inserted into the hash:
```
{ "a" => 1, a: 2 }.stringify_keys
# The result will be
# => {"a"=>2}
```
This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionView::Helpers::FormHelper` defines:
```
def to_checkbox_tag(options = {}, checked_value = "1", unchecked_value = "0")
options = options.stringify_keys
options["type"] = "checkbox"
# ...
end
```
The second line can safely access the "type" key, and let the user to pass either `:type` or "type".
There's also the bang variant [`stringify_keys!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-stringify_keys-21) that stringifies keys in place.
Besides that, one can use [`deep_stringify_keys`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_stringify_keys) and [`deep_stringify_keys!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_stringify_keys-21) to stringify all the keys in the given hash and all the hashes nested in it. An example of the result is:
```
{ nil => nil, 1 => 1, nested: { a: 3, 5 => 5 } }.deep_stringify_keys
# => {""=>nil, "1"=>1, "nested"=>{"a"=>3, "5"=>5}}
```
Defined in `active_support/core_ext/hash/keys.rb`.
#### [12.4.3. `symbolize_keys` and `symbolize_keys!`](#symbolize-keys-and-symbolize-keys-bang)
The method [`symbolize_keys`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-symbolize_keys) returns a hash that has a symbolized version of the keys in the receiver, where possible. It does so by sending `to_sym` to them:
```
{ nil => nil, 1 => 1, "a" => "a" }.symbolize_keys
# => {nil=>nil, 1=>1, :a=>"a"}
```
Note in the previous example only one key was symbolized.
In case of key collision, the value will be the one most recently inserted into the hash:
```
{ "a" => 1, a: 2 }.symbolize_keys
# => {:a=>2}
```
This method may be useful for example to easily accept both symbols and strings as options. For instance `ActionText::TagHelper` defines
```
def rich_textarea_tag(name, value = nil, options = {})
options = options.symbolize_keys
options[:input] ||= "trix_input_#{ActionText::TagHelper.id += 1}"
# ...
end
```
The third line can safely access the `:input` key, and let the user to pass either `:input` or "input".
There's also the bang variant [`symbolize_keys!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-symbolize_keys-21) that symbolizes keys in place.
Besides that, one can use [`deep_symbolize_keys`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_symbolize_keys) and [`deep_symbolize_keys!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_symbolize_keys-21) to symbolize all the keys in the given hash and all the hashes nested in it. An example of the result is:
```
{ nil => nil, 1 => 1, "nested" => { "a" => 3, 5 => 5 } }.deep_symbolize_keys
# => {nil=>nil, 1=>1, nested:{a:3, 5=>5}}
```
Defined in `active_support/core_ext/hash/keys.rb`.
#### [12.4.4. `to_options` and `to_options!`](#to-options-and-to-options-bang)
The methods [`to_options`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-to_options) and [`to_options!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-to_options-21) are aliases of `symbolize_keys` and `symbolize_keys!`, respectively.
Defined in `active_support/core_ext/hash/keys.rb`.
#### [12.4.5. `assert_valid_keys`](#assert-valid-keys)
The method [`assert_valid_keys`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-assert_valid_keys) receives an arbitrary number of arguments, and checks whether the receiver has any key outside that list. If it does `ArgumentError` is raised.
```
{ a: 1 }.assert_valid_keys(:a) # passes
{ a: 1 }.assert_valid_keys("a") # ArgumentError
```
Active Record does not accept unknown options when building associations, for example. It implements that control via `assert_valid_keys`.
Defined in `active_support/core_ext/hash/keys.rb`.
### [12.5. Working with Values](#working-with-values)
#### [12.5.1. `deep_transform_values` and `deep_transform_values!`](#deep-transform-values-and-deep-transform-values-bang)
The method [`deep_transform_values`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_transform_values) returns a new hash with all values converted by the block operation. This includes the values from the root hash and from all nested hashes and arrays.
```
hash = { person: { name: "Rob", age: "28" } }
hash.deep_transform_values { |value| value.to_s.upcase }
# => {person: {name: "ROB", age: "28"}}
```
There's also the bang variant [`deep_transform_values!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-deep_transform_values-21) that destructively converts all values by using the block operation.
Defined in `active_support/core_ext/hash/deep_transform_values.rb`.
### [12.6. Slicing](#slicing)
The method [`slice!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-slice-21) replaces the hash with only the given keys and returns a hash containing the removed key/value pairs.
```
hash = { a: 1, b: 2 }
rest = hash.slice!(:a) # => {:b=>2}
hash # => {:a=>1}
```
Defined in `active_support/core_ext/hash/slice.rb`.
### [12.7. Extracting](#extensions-to-hash-extracting)
The method [`extract!`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-extract-21) removes and returns the key/value pairs matching the given keys.
```
hash = { a: 1, b: 2 }
rest = hash.extract!(:a) # => {:a=>1}
hash # => {:b=>2}
```
The method `extract!` returns the same subclass of Hash that the receiver is.
```
hash = { a: 1, b: 2 }.with_indifferent_access
rest = hash.extract!(:a).class
# => ActiveSupport::HashWithIndifferentAccess
```
Defined in `active_support/core_ext/hash/slice.rb`.
### [12.8. Indifferent Access](#indifferent-access)
The method [`with_indifferent_access`](https://api.rubyonrails.org/v8.1.4/classes/Hash.html#method-i-with_indifferent_access) returns an [`ActiveSupport::HashWithIndifferentAccess`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/HashWithIndifferentAccess.html) out of its receiver:
```
{ a: 1 }.with_indifferent_access["a"] # => 1
```
Defined in `active_support/core_ext/hash/indifferent_access.rb`.
## [13. Extensions to `Regexp`](#extensions-to-regexp)
### [13.1. `multiline?`](#multiline-questionmark)
The method [`multiline?`](https://api.rubyonrails.org/v8.1.4/classes/Regexp.html#method-i-multiline-3F) says whether a regexp has the `/m` flag set, that is, whether the dot matches newlines.
```
%r{.}.multiline? # => false
%r{.}m.multiline? # => true
Regexp.new(".").multiline? # => false
Regexp.new(".", Regexp::MULTILINE).multiline? # => true
```
Rails uses this method in a single place, also in the routing code. Multiline regexps are disallowed for route requirements and this flag eases enforcing that constraint.
```
def verify_regexp_requirements(requirements)
# ...
if requirement.multiline?
raise ArgumentError, "Regexp multiline option is not allowed in routing requirements: #{requirement.inspect}"
end
# ...
end
```
Defined in `active_support/core_ext/regexp.rb`.
## [14. Extensions to `Range`](#extensions-to-range)
### [14.1. `to_fs`](#extensions-to-range-to-fs)
Active Support defines `Range#to_fs` as an alternative to `to_s` that understands an optional format argument. As of this writing the only supported non-default format is `:db`:
```
(Date.today..Date.tomorrow).to_fs
# => "2009-10-25..2009-10-26"
(Date.today..Date.tomorrow).to_fs(:db)
# => "BETWEEN '2009-10-25' AND '2009-10-26'"
```
As the example depicts, the `:db` format generates a `BETWEEN` SQL clause. That is used by Active Record in its support for range values in conditions.
Defined in `active_support/core_ext/range/conversions.rb`.
### [14.2. `===` and `include?`](#and-include-questionmark)
The methods `Range#===` and `Range#include?` say whether some value falls between the ends of a given instance:
```
(2..3).include?(Math::E) # => true
```
Active Support extends these methods so that the argument may be another range in turn. In that case we test whether the ends of the argument range belong to the receiver themselves:
```
(1..10) === (3..7) # => true
(1..10) === (0..7) # => false
(1..10) === (3..11) # => false
(1...9) === (3..9) # => false
(1..10).include?(3..7) # => true
(1..10).include?(0..7) # => false
(1..10).include?(3..11) # => false
(1...9).include?(3..9) # => false
```
Defined in `active_support/core_ext/range/compare_range.rb`.
### [14.3. `overlap?`](#overlap-questionmark)
The method [`Range#overlap?`](https://api.rubyonrails.org/v8.1.4/classes/Range.html#method-i-overlaps-3F) says whether any two given ranges have non-void intersection:
```
(1..10).overlap?(7..11) # => true
(1..10).overlap?(0..7) # => true
(1..10).overlap?(11..27) # => false
```
Defined in `active_support/core_ext/range/overlap.rb`.
## [15. Extensions to `Date`](#extensions-to-date)
### [15.1. Calculations](#extensions-to-date-calculations)
The following calculation methods have edge cases in October 1582, since days 5..14 just do not exist. This guide does not document their behavior around those days for brevity, but it is enough to say that they do what you would expect. That is, `Date.new(1582, 10, 4).tomorrow` returns `Date.new(1582, 10, 15)` and so on. Please check `test/core_ext/date_ext_test.rb` in the Active Support test suite for expected behavior.
#### [15.1.1. `Date.current`](#date-current)
Active Support defines [`Date.current`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-c-current) to be today in the current time zone. That's like `Date.today`, except that it honors the user time zone, if defined. It also defines [`Date.yesterday`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-c-yesterday) and [`Date.tomorrow`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-c-tomorrow), and the instance predicates [`past?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-past-3F), [`today?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-today-3F), [`tomorrow?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-tomorrow-3F), [`next_day?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-next_day-3F), [`yesterday?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-yesterday-3F), [`prev_day?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-prev_day-3F), [`future?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-future-3F), [`on_weekday?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-on_weekday-3F) and [`on_weekend?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-on_weekend-3F), all of them relative to `Date.current`.
When making Date comparisons using methods which honor the user time zone, make sure to use `Date.current` and not `Date.today`. There are cases where the user time zone might be in the future compared to the system time zone, which `Date.today` uses by default. This means `Date.today` may equal `Date.yesterday`.
Defined in `active_support/core_ext/date/calculations.rb`.
#### [15.1.2. Named Dates](#named-dates)
##### [15.1.2.1. `beginning_of_week`, `end_of_week`](#beginning-of-week-end-of-week)
The methods [`beginning_of_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-beginning_of_week) and [`end_of_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-end_of_week) return the dates for the beginning and end of the week, respectively. Weeks are assumed to start on Monday, but that can be changed passing an argument, setting thread local `Date.beginning_of_week` or [`config.beginning_of_week`](configuring.html#config-beginning-of-week).
```
d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
d.beginning_of_week # => Mon, 03 May 2010
d.beginning_of_week(:sunday) # => Sun, 02 May 2010
d.end_of_week # => Sun, 09 May 2010
d.end_of_week(:sunday) # => Sat, 08 May 2010
```
`beginning_of_week` is aliased to [`at_beginning_of_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_beginning_of_week) and `end_of_week` is aliased to [`at_end_of_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_end_of_week).
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.2.2. `monday`, `sunday`](#monday-sunday)
The methods [`monday`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-monday) and [`sunday`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-sunday) return the dates for the previous Monday and next Sunday, respectively.
```
d = Date.new(2010, 5, 8) # => Sat, 08 May 2010
d.monday # => Mon, 03 May 2010
d.sunday # => Sun, 09 May 2010
d = Date.new(2012, 9, 10) # => Mon, 10 Sep 2012
d.monday # => Mon, 10 Sep 2012
d = Date.new(2012, 9, 16) # => Sun, 16 Sep 2012
d.sunday # => Sun, 16 Sep 2012
```
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.2.3. `prev_week`, `next_week`](#prev-week-next-week)
The method [`next_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-next_week) receives a symbol with a day name in English (default is the thread local [`Date.beginning_of_week`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-c-beginning_of_week), or [`config.beginning_of_week`](configuring.html#config-beginning-of-week), or `:monday`) and it returns the date corresponding to that day.
```
d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
d.next_week # => Mon, 10 May 2010
d.next_week(:saturday) # => Sat, 15 May 2010
```
The method [`prev_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-prev_week) is analogous:
```
d.prev_week # => Mon, 26 Apr 2010
d.prev_week(:saturday) # => Sat, 01 May 2010
d.prev_week(:friday) # => Fri, 30 Apr 2010
```
`prev_week` is aliased to [`last_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-last_week).
Both `next_week` and `prev_week` work as expected when `Date.beginning_of_week` or `config.beginning_of_week` are set.
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.2.4. `beginning_of_month`, `end_of_month`](#beginning-of-month-end-of-month)
The methods [`beginning_of_month`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-beginning_of_month) and [`end_of_month`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-end_of_month) return the dates for the beginning and end of the month:
```
d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
d.beginning_of_month # => Sat, 01 May 2010
d.end_of_month # => Mon, 31 May 2010
```
`beginning_of_month` is aliased to [`at_beginning_of_month`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_beginning_of_month), and `end_of_month` is aliased to [`at_end_of_month`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_end_of_month).
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.2.5. `quarter`, `beginning_of_quarter`, `end_of_quarter`](#quarter-beginning-of-quarter-end-of-quarter)
The method [`quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-quarter) returns the quarter of the receiver's calendar year:
```
d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
d.quarter # => 2
```
The methods [`beginning_of_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-beginning_of_quarter) and [`end_of_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-end_of_quarter) return the dates for the beginning and end of the quarter of the receiver's calendar year:
```
d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
d.beginning_of_quarter # => Thu, 01 Apr 2010
d.end_of_quarter # => Wed, 30 Jun 2010
```
`beginning_of_quarter` is aliased to [`at_beginning_of_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_beginning_of_quarter), and `end_of_quarter` is aliased to [`at_end_of_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_end_of_quarter).
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.2.6. `beginning_of_year`, `end_of_year`](#beginning-of-year-end-of-year)
The methods [`beginning_of_year`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-beginning_of_year) and [`end_of_year`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-end_of_year) return the dates for the beginning and end of the year:
```
d = Date.new(2010, 5, 9) # => Sun, 09 May 2010
d.beginning_of_year # => Fri, 01 Jan 2010
d.end_of_year # => Fri, 31 Dec 2010
```
`beginning_of_year` is aliased to [`at_beginning_of_year`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_beginning_of_year), and `end_of_year` is aliased to [`at_end_of_year`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-at_end_of_year).
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
#### [15.1.3. Other Date Computations](#other-date-computations)
##### [15.1.3.1. `years_ago`, `years_since`](#years-ago-years-since)
The method [`years_ago`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-years_ago) receives a number of years and returns the same date those many years ago:
```
date = Date.new(2010, 6, 7)
date.years_ago(10) # => Wed, 07 Jun 2000
```
[`years_since`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-years_since) moves forward in time:
```
date = Date.new(2010, 6, 7)
date.years_since(10) # => Sun, 07 Jun 2020
```
If such a day does not exist, the last day of the corresponding month is returned:
```
Date.new(2012, 2, 29).years_ago(3) # => Sat, 28 Feb 2009
Date.new(2012, 2, 29).years_since(3) # => Sat, 28 Feb 2015
```
[`last_year`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-last_year) is short-hand for `#years_ago(1)`.
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.3.2. `months_ago`, `months_since`](#months-ago-months-since)
The methods [`months_ago`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-months_ago) and [`months_since`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-months_since) work analogously for months:
```
Date.new(2010, 4, 30).months_ago(2) # => Sun, 28 Feb 2010
Date.new(2010, 4, 30).months_since(2) # => Wed, 30 Jun 2010
```
If such a day does not exist, the last day of the corresponding month is returned:
```
Date.new(2010, 4, 30).months_ago(2) # => Sun, 28 Feb 2010
Date.new(2009, 12, 31).months_since(2) # => Sun, 28 Feb 2010
```
[`last_month`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-last_month) is short-hand for `#months_ago(1)`.
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.3.3. `weeks_ago`, `weeks_since`](#weeks-ago-weeks-since)
The method [`weeks_ago`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-weeks_ago) and \[`weeks_since`]\[DateAndTime::Calculations#week\_since] work analogously for weeks:
```
Date.new(2010, 5, 24).weeks_ago(1) # => Mon, 17 May 2010
Date.new(2010, 5, 24).weeks_since(2) # => Mon, 07 Jun 2010
```
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
##### [15.1.3.4. `advance`](#other-date-computations-advance)
The most generic way to jump to other days is [`advance`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-advance). This method receives a hash with keys `:years`, `:months`, `:weeks`, `:days`, and returns a date advanced as much as the present keys indicate:
```
date = Date.new(2010, 6, 6)
date.advance(years: 1, weeks: 2) # => Mon, 20 Jun 2011
date.advance(months: 2, days: -2) # => Wed, 04 Aug 2010
```
Note in the previous example that increments may be negative.
Defined in `active_support/core_ext/date/calculations.rb`.
#### [15.1.4. Changing Components](#extensions-to-date-calculations-changing-components)
The method [`change`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-change) allows you to get a new date which is the same as the receiver except for the given year, month, or day:
```
Date.new(2010, 12, 23).change(year: 2011, month: 11)
# => Wed, 23 Nov 2011
```
This method is not tolerant to non-existing dates, if the change is invalid `ArgumentError` is raised:
```
Date.new(2010, 1, 31).change(month: 2)
# => ArgumentError: invalid date
```
Defined in `active_support/core_ext/date/calculations.rb`.
#### [15.1.5. Durations](#extensions-to-date-calculations-durations)
[`Duration`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/Duration.html) objects can be added to and subtracted from dates:
```
d = Date.current
# => Mon, 09 Aug 2010
d + 1.year
# => Tue, 09 Aug 2011
d - 3.hours
# => Sun, 08 Aug 2010 21:00:00 UTC +00:00
```
They translate to calls to `since` or `advance`. For example here we get the correct jump in the calendar reform:
```
Date.new(1582, 10, 4) + 1.day
# => Fri, 15 Oct 1582
```
#### [15.1.6. Timestamps](#timestamps)
The following methods return a `Time` object if possible, otherwise a `DateTime`. If set, they honor the user time zone.
##### [15.1.6.1. `beginning_of_day`, `end_of_day`](#beginning-of-day-end-of-day)
The method [`beginning_of_day`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-beginning_of_day) returns a timestamp at the beginning of the day (00:00:00):
```
date = Date.new(2010, 6, 7)
date.beginning_of_day # => Mon Jun 07 00:00:00 +0200 2010
```
The method [`end_of_day`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-end_of_day) returns a timestamp at the end of the day (23:59:59):
```
date = Date.new(2010, 6, 7)
date.end_of_day # => Mon Jun 07 23:59:59 +0200 2010
```
`beginning_of_day` is aliased to [`at_beginning_of_day`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-at_beginning_of_day), [`midnight`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-midnight), [`at_midnight`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-at_midnight).
Defined in `active_support/core_ext/date/calculations.rb`.
##### [15.1.6.2. `beginning_of_hour`, `end_of_hour`](#beginning-of-hour-end-of-hour)
The method [`beginning_of_hour`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-beginning_of_hour) returns a timestamp at the beginning of the hour (hh:00:00):
```
date = DateTime.new(2010, 6, 7, 19, 55, 25)
date.beginning_of_hour # => Mon Jun 07 19:00:00 +0200 2010
```
The method [`end_of_hour`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-end_of_hour) returns a timestamp at the end of the hour (hh:59:59):
```
date = DateTime.new(2010, 6, 7, 19, 55, 25)
date.end_of_hour # => Mon Jun 07 19:59:59 +0200 2010
```
`beginning_of_hour` is aliased to [`at_beginning_of_hour`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-at_beginning_of_hour).
Defined in `active_support/core_ext/date_time/calculations.rb`.
##### [15.1.6.3. `beginning_of_minute`, `end_of_minute`](#beginning-of-minute-end-of-minute)
The method [`beginning_of_minute`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-beginning_of_minute) returns a timestamp at the beginning of the minute (hh:mm:00):
```
date = DateTime.new(2010, 6, 7, 19, 55, 25)
date.beginning_of_minute # => Mon Jun 07 19:55:00 +0200 2010
```
The method [`end_of_minute`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-end_of_minute) returns a timestamp at the end of the minute (hh:mm:59):
```
date = DateTime.new(2010, 6, 7, 19, 55, 25)
date.end_of_minute # => Mon Jun 07 19:55:59 +0200 2010
```
`beginning_of_minute` is aliased to [`at_beginning_of_minute`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-at_beginning_of_minute).
`beginning_of_hour`, `end_of_hour`, `beginning_of_minute`, and `end_of_minute` are implemented for `Time` and `DateTime` but **not** `Date` as it does not make sense to request the beginning or end of an hour or minute on a `Date` instance.
Defined in `active_support/core_ext/date_time/calculations.rb`.
##### [15.1.6.4. `ago`, `since`](#ago-since)
The method [`ago`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-ago) receives a number of seconds as argument and returns a timestamp those many seconds ago from midnight:
```
date = Date.current # => Fri, 11 Jun 2010
date.ago(1) # => Thu, 10 Jun 2010 23:59:59 EDT -04:00
```
Similarly, [`since`](https://api.rubyonrails.org/v8.1.4/classes/Date.html#method-i-since) moves forward:
```
date = Date.current # => Fri, 11 Jun 2010
date.since(1) # => Fri, 11 Jun 2010 00:00:01 EDT -04:00
```
Defined in `active_support/core_ext/date/calculations.rb`.
## [16. Extensions to `DateTime`](#extensions-to-datetime)
`DateTime` is not aware of DST rules and so some of these methods have edge cases when a DST change is going on. For example [`seconds_since_midnight`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-seconds_since_midnight) might not return the real amount in such a day.
### [16.1. Calculations](#extensions-to-datetime-calculations)
The class `DateTime` is a subclass of `Date` so by loading `active_support/core_ext/date/calculations.rb` you inherit these methods and their aliases, except that they will always return datetimes.
The following methods are reimplemented so you do **not** need to load `active_support/core_ext/date/calculations.rb` for these ones:
* [`beginning_of_day`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-beginning_of_day) / [`midnight`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-midnight) / [`at_midnight`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-at_midnight) / [`at_beginning_of_day`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-at_beginning_of_day)
* [`end_of_day`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-end_of_day)
* [`ago`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-ago)
* [`since`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-since) / [`in`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-in)
On the other hand, [`advance`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-advance) and [`change`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-change) are also defined and support more options, they are documented below.
The following methods are only implemented in `active_support/core_ext/date_time/calculations.rb` as they only make sense when used with a `DateTime` instance:
* [`beginning_of_hour`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-beginning_of_hour) / [`at_beginning_of_hour`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-at_beginning_of_hour)
* [`end_of_hour`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-end_of_hour)
#### [16.1.1. Named Datetimes](#named-datetimes)
##### [16.1.1.1. `DateTime.current`](#datetime-current)
Active Support defines [`DateTime.current`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-c-current) to be like `Time.now.to_datetime`, except that it honors the user time zone, if defined. The instance predicates [`past?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-past-3F) and [`future?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-future-3F) are defined relative to `DateTime.current`.
Defined in `active_support/core_ext/date_time/calculations.rb`.
#### [16.1.2. Other Extensions](#other-extensions)
##### [16.1.2.1. `seconds_since_midnight`](#seconds-since-midnight)
The method [`seconds_since_midnight`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-seconds_since_midnight) returns the number of seconds since midnight:
```
now = DateTime.current # => Mon, 07 Jun 2010 20:26:36 +0000
now.seconds_since_midnight # => 73596
```
Defined in `active_support/core_ext/date_time/calculations.rb`.
##### [16.1.2.2. `utc`](#utc)
The method [`utc`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-utc) gives you the same datetime in the receiver expressed in UTC.
```
now = DateTime.current # => Mon, 07 Jun 2010 19:27:52 -0400
now.utc # => Mon, 07 Jun 2010 23:27:52 +0000
```
This method is also aliased as [`getutc`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-getutc).
Defined in `active_support/core_ext/date_time/calculations.rb`.
##### [16.1.2.3. `utc?`](#utc-questionmark)
The predicate [`utc?`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-utc-3F) says whether the receiver has UTC as its time zone:
```
now = DateTime.now # => Mon, 07 Jun 2010 19:30:47 -0400
now.utc? # => false
now.utc.utc? # => true
```
Defined in `active_support/core_ext/date_time/calculations.rb`.
##### [16.1.2.4. `advance`](#other-extensions-advance)
The most generic way to jump to another datetime is [`advance`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-advance). This method receives a hash with keys `:years`, `:months`, `:weeks`, `:days`, `:hours`, `:minutes`, and `:seconds`, and returns a datetime advanced as much as the present keys indicate.
```
d = DateTime.current
# => Thu, 05 Aug 2010 11:33:31 +0000
d.advance(years: 1, months: 1, days: 1, hours: 1, minutes: 1, seconds: 1)
# => Tue, 06 Sep 2011 12:34:32 +0000
```
This method first computes the destination date passing `:years`, `:months`, `:weeks`, and `:days` to `Date#advance` documented above. After that, it adjusts the time calling [`since`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-since) with the number of seconds to advance. This order is relevant, a different ordering would give different datetimes in some edge-cases. The example in `Date#advance` applies, and we can extend it to show order relevance related to the time bits.
If we first move the date bits (that have also a relative order of processing, as documented before), and then the time bits we get for example the following computation:
```
d = DateTime.new(2010, 2, 28, 23, 59, 59)
# => Sun, 28 Feb 2010 23:59:59 +0000
d.advance(months: 1, seconds: 1)
# => Mon, 29 Mar 2010 00:00:00 +0000
```
but if we computed them the other way around, the result would be different:
```
d.advance(seconds: 1).advance(months: 1)
# => Thu, 01 Apr 2010 00:00:00 +0000
```
Since `DateTime` is not DST-aware you can end up in a non-existing point in time with no warning or error telling you so.
Defined in `active_support/core_ext/date_time/calculations.rb`.
#### [16.1.3. Changing Components](#extensions-to-datetime-calculations-changing-components)
The method [`change`](https://api.rubyonrails.org/v8.1.4/classes/DateTime.html#method-i-change) allows you to get a new datetime which is the same as the receiver except for the given options, which may include `:year`, `:month`, `:day`, `:hour`, `:min`, `:sec`, `:offset`, `:start`:
```
now = DateTime.current
# => Tue, 08 Jun 2010 01:56:22 +0000
now.change(year: 2011, offset: Rational(-6, 24))
# => Wed, 08 Jun 2011 01:56:22 -0600
```
If hours are zeroed, then minutes and seconds are too (unless they have given values):
```
now.change(hour: 0)
# => Tue, 08 Jun 2010 00:00:00 +0000
```
Similarly, if minutes are zeroed, then seconds are too (unless it has given a value):
```
now.change(min: 0)
# => Tue, 08 Jun 2010 01:00:00 +0000
```
This method is not tolerant to non-existing dates, if the change is invalid `ArgumentError` is raised:
```
DateTime.current.change(month: 2, day: 30)
# => ArgumentError: invalid date
```
Defined in `active_support/core_ext/date_time/calculations.rb`.
#### [16.1.4. Durations](#extensions-to-datetime-calculations-durations)
[`Duration`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/Duration.html) objects can be added to and subtracted from datetimes:
```
now = DateTime.current
# => Mon, 09 Aug 2010 23:15:17 +0000
now + 1.year
# => Tue, 09 Aug 2011 23:15:17 +0000
now - 1.week
# => Mon, 02 Aug 2010 23:15:17 +0000
```
They translate to calls to `since` or `advance`. For example here we get the correct jump in the calendar reform:
```
DateTime.new(1582, 10, 4, 23) + 1.hour
# => Fri, 15 Oct 1582 00:00:00 +0000
```
## [17. Extensions to `Time`](#extensions-to-time)
### [17.1. Calculations](#calculations)
They are analogous. Please refer to their documentation above and take into account the following differences:
* [`change`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-change) accepts an additional `:usec` option.
* `Time` understands DST, so you get correct DST calculations as in
```
Time.zone_default
# => #
# In Barcelona, 2010/03/28 02:00 +0100 becomes 2010/03/28 03:00 +0200 due to DST.
t = Time.local(2010, 3, 28, 1, 59, 59)
# => Sun Mar 28 01:59:59 +0100 2010
t.advance(seconds: 1)
# => Sun Mar 28 03:00:00 +0200 2010
```
* If [`since`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-since) or [`ago`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-ago) jumps to a time that can't be expressed with `Time` a `DateTime` object is returned instead.
#### [17.1.1. `Time.current`](#time-current)
Active Support defines [`Time.current`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-c-current) to be today in the current time zone. That's like `Time.now`, except that it honors the user time zone, if defined. It also defines the instance predicates [`past?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-past-3F), [`today?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-today-3F), [`tomorrow?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-tomorrow-3F), [`next_day?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-next_day-3F), [`yesterday?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-yesterday-3F), [`prev_day?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-prev_day-3F) and [`future?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-future-3F), all of them relative to `Time.current`.
When making Time comparisons using methods which honor the user time zone, make sure to use `Time.current` instead of `Time.now`. There are cases where the user time zone might be in the future compared to the system time zone, which `Time.now` uses by default. This means `Time.now.to_date` may equal `Date.yesterday`.
Defined in `active_support/core_ext/time/calculations.rb`.
#### [17.1.2. `all_day`, `all_week`, `all_month`, `all_quarter`, and `all_year`](#all-day-all-week-all-month-all-quarter-and-all-year)
The method [`all_day`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-all_day) returns a range representing the whole day of the current time.
```
now = Time.current
# => Mon, 09 Aug 2010 23:20:05 UTC +00:00
now.all_day
# => Mon, 09 Aug 2010 00:00:00 UTC +00:00..Mon, 09 Aug 2010 23:59:59 UTC +00:00
```
Analogously, [`all_week`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-all_week), [`all_month`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-all_month), [`all_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-all_quarter) and [`all_year`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-all_year) all serve the purpose of generating time ranges.
```
now = Time.current
# => Mon, 09 Aug 2010 23:20:05 UTC +00:00
now.all_week
# => Mon, 09 Aug 2010 00:00:00 UTC +00:00..Sun, 15 Aug 2010 23:59:59 UTC +00:00
now.all_week(:sunday)
# => Sun, 16 Sep 2012 00:00:00 UTC +00:00..Sat, 22 Sep 2012 23:59:59 UTC +00:00
now.all_month
# => Sat, 01 Aug 2010 00:00:00 UTC +00:00..Tue, 31 Aug 2010 23:59:59 UTC +00:00
now.all_quarter
# => Thu, 01 Jul 2010 00:00:00 UTC +00:00..Thu, 30 Sep 2010 23:59:59 UTC +00:00
now.all_year
# => Fri, 01 Jan 2010 00:00:00 UTC +00:00..Fri, 31 Dec 2010 23:59:59 UTC +00:00
```
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
#### [17.1.3. `prev_day`, `next_day`](#prev-day-next-day)
[`prev_day`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-prev_day) and [`next_day`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-next_day) return the time in the last or next day:
```
t = Time.new(2010, 5, 8) # => 2010-05-08 00:00:00 +0900
t.prev_day # => 2010-05-07 00:00:00 +0900
t.next_day # => 2010-05-09 00:00:00 +0900
```
Defined in `active_support/core_ext/time/calculations.rb`.
#### [17.1.4. `prev_month`, `next_month`](#prev-month-next-month)
[`prev_month`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-prev_month) and [`next_month`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-next_month) return the time with the same day in the last or next month:
```
t = Time.new(2010, 5, 8) # => 2010-05-08 00:00:00 +0900
t.prev_month # => 2010-04-08 00:00:00 +0900
t.next_month # => 2010-06-08 00:00:00 +0900
```
If such a day does not exist, the last day of the corresponding month is returned:
```
Time.new(2000, 5, 31).prev_month # => 2000-04-30 00:00:00 +0900
Time.new(2000, 3, 31).prev_month # => 2000-02-29 00:00:00 +0900
Time.new(2000, 5, 31).next_month # => 2000-06-30 00:00:00 +0900
Time.new(2000, 1, 31).next_month # => 2000-02-29 00:00:00 +0900
```
Defined in `active_support/core_ext/time/calculations.rb`.
#### [17.1.5. `prev_year`, `next_year`](#prev-year-next-year)
[`prev_year`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-prev_year) and [`next_year`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-i-next_year) return a time with the same day/month in the last or next year:
```
t = Time.new(2010, 5, 8) # => 2010-05-08 00:00:00 +0900
t.prev_year # => 2009-05-08 00:00:00 +0900
t.next_year # => 2011-05-08 00:00:00 +0900
```
If date is the 29th of February of a leap year, you obtain the 28th:
```
t = Time.new(2000, 2, 29) # => 2000-02-29 00:00:00 +0900
t.prev_year # => 1999-02-28 00:00:00 +0900
t.next_year # => 2001-02-28 00:00:00 +0900
```
Defined in `active_support/core_ext/time/calculations.rb`.
#### [17.1.6. `prev_quarter`, `next_quarter`](#prev-quarter-next-quarter)
[`prev_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-prev_quarter) and [`next_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-next_quarter) return the date with the same day in the previous or next quarter:
```
t = Time.local(2010, 5, 8) # => 2010-05-08 00:00:00 +0300
t.prev_quarter # => 2010-02-08 00:00:00 +0200
t.next_quarter # => 2010-08-08 00:00:00 +0300
```
If such a day does not exist, the last day of the corresponding month is returned:
```
Time.local(2000, 7, 31).prev_quarter # => 2000-04-30 00:00:00 +0300
Time.local(2000, 5, 31).prev_quarter # => 2000-02-29 00:00:00 +0200
Time.local(2000, 10, 31).prev_quarter # => 2000-07-31 00:00:00 +0300
Time.local(2000, 11, 31).next_quarter # => 2001-03-01 00:00:00 +0200
```
`prev_quarter` is aliased to [`last_quarter`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-last_quarter).
Defined in `active_support/core_ext/date_and_time/calculations.rb`.
### [17.2. Time Constructors](#time-constructors)
Active Support defines [`Time.current`](https://api.rubyonrails.org/v8.1.4/classes/Time.html#method-c-current) to be `Time.zone.now` if there's a user time zone defined, with fallback to `Time.now`:
```
Time.zone_default
# => #
Time.current
# => Fri, 06 Aug 2010 17:11:58 CEST +02:00
```
Analogously to `DateTime`, the predicates [`past?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-past-3F), and [`future?`](https://api.rubyonrails.org/v8.1.4/classes/DateAndTime/Calculations.html#method-i-future-3F) are relative to `Time.current`.
If the time to be constructed lies beyond the range supported by `Time` in the runtime platform, usecs are discarded and a `DateTime` object is returned instead.
#### [17.2.1. Durations](#durations)
[`Duration`](https://api.rubyonrails.org/v8.1.4/classes/ActiveSupport/Duration.html) objects can be added to and subtracted from time objects:
```
now = Time.current
# => Mon, 09 Aug 2010 23:20:05 UTC +00:00
now + 1.year
# => Tue, 09 Aug 2011 23:21:11 UTC +00:00
now - 1.week
# => Mon, 02 Aug 2010 23:21:11 UTC +00:00
```
They translate to calls to `since` or `advance`. For example here we get the correct jump in the calendar reform:
```
Time.utc(1582, 10, 3) + 5.days
# => Mon Oct 18 00:00:00 UTC 1582
```
## [18. Extensions to `File`](#extensions-to-file)
### [18.1. `atomic_write`](#atomic-write)
With the class method [`File.atomic_write`](https://api.rubyonrails.org/v8.1.4/classes/File.html#method-c-atomic_write) you can write to a file in a way that will prevent any reader from seeing half-written content.
The name of the file is passed as an argument, and the method yields a file handle opened for writing. Once the block is done `atomic_write` closes the file handle and completes its job.
For example, Action Pack uses this method to write asset cache files like `all.css`:
```
File.atomic_write(joined_asset_path) do |cache|
cache.write(join_asset_file_contents(asset_paths))
end
```
To accomplish this `atomic_write` creates a temporary file. That's the file the code in the block actually writes to. On completion, the temporary file is renamed, which is an atomic operation on POSIX systems. If the target file exists `atomic_write` overwrites it and keeps owners and permissions. However there are a few cases where `atomic_write` cannot change the file ownership or permissions, this error is caught and skipped over trusting in the user/filesystem to ensure the file is accessible to the processes that need it.
Due to the chmod operation `atomic_write` performs, if the target file has an ACL set on it this ACL will be recalculated/modified.
Note you can't append with `atomic_write`.
The auxiliary file is written in a standard directory for temporary files, but you can pass a directory of your choice as second argument.
Defined in `active_support/core_ext/file/atomic.rb`.
## [19. Extensions to `NameError`](#extensions-to-nameerror)
Active Support adds [`missing_name?`](https://api.rubyonrails.org/v8.1.4/classes/NameError.html#method-i-missing_name-3F) to `NameError`, which tests whether the exception was raised because of the name passed as argument.
The name may be given as a symbol or string. A symbol is tested against the bare constant name, a string is against the fully qualified constant name.
A symbol can represent a fully qualified constant name as in `:"ActiveRecord::Base"`, so the behavior for symbols is defined for convenience, not because it has to be that way technically.
For example, when an action of `ArticlesController` is called Rails tries optimistically to use `ArticlesHelper`. It is OK that the helper module does not exist, so if an exception for that constant name is raised it should be silenced. But it could be the case that `articles_helper.rb` raises a `NameError` due to an actual unknown constant. That should be reraised. The method `missing_name?` provides a way to distinguish both cases:
```
def default_helper_module!
module_name = name.delete_suffix("Controller")
module_path = module_name.underscore
helper module_path
rescue LoadError => e
raise e unless e.is_missing? "helpers/#{module_path}_helper"
rescue NameError => e
raise e unless e.missing_name? "#{module_name}Helper"
end
```
Defined in `active_support/core_ext/name_error.rb`.
## [20. Extensions to `LoadError`](#extensions-to-loaderror)
Active Support adds [`is_missing?`](https://api.rubyonrails.org/v8.1.4/classes/LoadError.html#method-i-is_missing-3F) to `LoadError`.
Given a path name `is_missing?` tests whether the exception was raised due to that particular file (except perhaps for the ".rb" extension).
For example, when an action of `ArticlesController` is called Rails tries to load `articles_helper.rb`, but that file may not exist. That's fine, the helper module is not mandatory so Rails silences a load error. But it could be the case that the helper module does exist and in turn requires another library that is missing. In that case Rails must reraise the exception. The method `is_missing?` provides a way to distinguish both cases:
```
def default_helper_module!
module_name = name.delete_suffix("Controller")
module_path = module_name.underscore
helper module_path
rescue LoadError => e
raise e unless e.is_missing? "helpers/#{module_path}_helper"
rescue NameError => e
raise e unless e.missing_name? "#{module_name}Helper"
end
```
Defined in `active_support/core_ext/load_error.rb`.
## [21. Extensions to Pathname](#extensions-to-pathname)
### [21.1. `existence`](#existence)
The [`existence`](https://api.rubyonrails.org/v8.1.4/classes/Pathname.html#method-i-existence) method returns the receiver if the named file exists otherwise returns `nil`. It is useful for idioms like this:
```
content = Pathname.new("file").existence&.read
```
Defined in `active_support/core_ext/pathname/existence.rb`.
***
***
[Back to top](#main-skip-link)
----
url: https://guides.rubyonrails.org/v8.1/active_record_validations.html
----
***
## [1. Validations Overview](#validations-overview)
Here's an example of a very simple validation:
```
class Person < ApplicationRecord
validates :name, presence: true
end
```
```
irb> Person.new(name: "John Doe").valid?
=> true
irb> Person.new(name: nil).valid?
=> false
```
As you can see, the `Person` is not valid without a `name` attribute.
Before we dig into more details, let's talk about how validations fit into the big picture of your application.
### [1.1. Why Use Validations?](#why-use-validations-questionmark)
Validations are used to ensure that only valid data is saved into your database. For example, it may be important to your application to ensure that every user provides a valid email address and mailing address. Model-level validations are the best way to ensure that only valid data is saved into your database. They can be used with any database, cannot be bypassed by end users, and are convenient to test and maintain. Rails provides built-in helpers for common needs, and allows you to create your own validation methods as well.
### [1.2. Alternate Ways to Validate](#alternate-ways-to-validate)
There are several other ways to validate data before it is saved into your database, including native database constraints, client-side validations and controller-level validations. Here's a summary of the pros and cons:
* Database constraints and/or stored procedures make the validation mechanisms database-dependent and can make testing and maintenance more difficult. However, if your database is used by other applications, it may be a good idea to use some constraints at the database level. Additionally, database-level validations can safely handle some things (such as uniqueness in heavily-used tables) that can be difficult to implement otherwise.
* Client-side validations can be useful, but are generally unreliable if used alone. If they are implemented using JavaScript, they may be bypassed if JavaScript is turned off in the user's browser. However, if combined with other techniques, client-side validation can be a convenient way to provide users with immediate feedback as they use your site.
* Controller-level validations can be tempting to use, but often become unwieldy and difficult to test and maintain. Whenever possible, it's a good idea to keep your controllers simple, as it will make working with your application easier in the long run.
Rails recommends using model-level validations in most circumstances, however there may be specific cases where you want to complement them with alternate validations.
### [1.3. Validation Triggers](#validation-triggers)
There are two kinds of Active Record objects - those that correspond to a row inside your database and those that do not. When you instantiate a new object, using the `new` method, the object does not get saved in the database as yet. Once you call `save` on that object, it will be saved into the appropriate database table. Active Record uses an instance method called `persisted?` (and its inverse `new_record?`) to determine whether an object is already in the database or not. Consider the following Active Record class:
```
class Person < ApplicationRecord
end
```
We can see how it works by looking at some `bin/rails console` output:
```
irb> p = Person.new(name: "Jane Doe")
=> #
irb> p.new_record?
=> true
irb> p.persisted?
=> false
irb> p.save
=> true
irb> p.new_record?
=> false
irb> p.persisted?
=> true
```
Saving a new record will send an SQL `INSERT` operation to the database, whereas updating an existing record will send an SQL `UPDATE` operation. Validations are typically run before these commands are sent to the database. If any validations fail, the object will be marked as invalid and Active Record will not perform the `INSERT` or `UPDATE` operation. This helps to avoid storing an invalid object in the database. You can choose to have specific validations run when an object is created, saved, or updated.
While validations usually prevent invalid data from being saved to the database, it's important to be aware that not all methods in Rails trigger validations. Some methods allow changes to be made directly to the database without performing validations. As a result, if you're not careful, itβs possible to [bypass validations](#skipping-validations) and save an object in an invalid state.
The following methods trigger validations, and will save the object to the database only if the object is valid:
* [`create`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-create)
* [`create!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-create-21)
* [`save`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-save)
* [`save!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-save-21)
* [`update`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-update)
* [`update!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-update-21)
The bang versions (methods that end with an exclamation mark, like `save!`) raise an exception if the record is invalid. The non-bang versions - `save` and `update` returns `false`, and `create` returns the object.
### [1.4. Skipping Validations](#skipping-validations)
The following methods skip validations, and will save the object to the database regardless of its validity. They should be used with caution. Refer to the method documentation to learn more.
* [`decrement!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-decrement-21)
* [`decrement_counter`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/CounterCache/ClassMethods.html#method-i-decrement_counter)
* [`increment!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-increment-21)
* [`increment_counter`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/CounterCache/ClassMethods.html#method-i-increment_counter)
* [`insert`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-insert)
* [`insert!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-insert-21)
* [`insert_all`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-insert_all)
* [`insert_all!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-insert_all-21)
* [`toggle!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-toggle-21)
* [`touch`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-touch)
* [`touch_all`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-touch_all)
* [`update_all`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-update_all)
* [`update_attribute`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-update_attribute)
* [`update_attribute!`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-update_attribute-21)
* [`update_column`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-update_column)
* [`update_columns`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Persistence.html#method-i-update_columns)
* [`update_counters`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-update_counters)
* [`upsert`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-upsert)
* [`upsert_all`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Relation.html#method-i-upsert_all)
* `save(validate: false)`
`save` also has the ability to skip validations if `validate: false` is passed as an argument. This technique should be used with caution.
### [1.5. Checking Validity](#checking-validity)
Before saving an Active Record object, Rails runs your validations, and if these validations produce any validation errors, then Rails will not save the object.
You can also run the validations on your own. [`valid?`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Validations.html#method-i-valid-3F) triggers your validations and returns true if no errors are found in the object, and false otherwise. As you saw above:
```
class Person < ApplicationRecord
validates :name, presence: true
end
```
```
irb> Person.new(name: "John Doe").valid?
=> true
irb> Person.new(name: nil).valid?
=> false
```
After Active Record has performed validations, any failures can be accessed through the [`errors`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations.html#method-i-errors) instance method, which returns a collection of errors. By definition, an object is valid if the collection is empty after running validations.
An object instantiated with `new` will not report errors even if it's technically invalid, because validations are automatically run only when the object is saved, such as with the `create` or `save` methods.
```
class Person < ApplicationRecord
validates :name, presence: true
end
```
```
irb> person = Person.new
=> #
irb> person.errors.size
=> 0
irb> person.valid?
=> false
irb> person.errors.objects.first.full_message
=> "Name can't be blank"
irb> person.save
=> false
irb> person.save!
ActiveRecord::RecordInvalid: Validation failed: Name can't be blank
irb> Person.create!
ActiveRecord::RecordInvalid: Validation failed: Name can't be blank
```
[`invalid?`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations.html#method-i-invalid-3F) is the inverse of `valid?`. It triggers your validations, returning true if any errors were found in the object, and false otherwise.
### [1.6. Inspecting and Handling Errors](#inspecting-and-handling-errors)
To verify whether or not a particular attribute of an object is valid, you can use [`errors[:attribute]`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Errors.html#method-i-5B-5D). It returns an array of all the error messages for `:attribute`. If there are no errors on the specified attribute, an empty array is returned. This allows you to easily determine whether there are any validation issues with a specific attribute.
Hereβs an example illustrating how to check for errors on an attribute:
```
class Person < ApplicationRecord
validates :name, presence: true
end
```
```
irb> new_person = Person.new
irb> new_person.errors[:name]
=> [] # no errors since validations are not run until saved
irb> new_person.errors[:name].any?
=> false
irb> create_person = Person.create
irb> create_person.errors[:name]
=> ["can't be blank"] # validation error because `name` is required
irb> create_person.errors[:name].any?
=> true
```
Additionally, you can use the [`errors.add`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Errors.html#method-i-add) method to manually add error messages for specific attributes. This is particularly useful when defining custom validation scenarios.
```
class Person < ApplicationRecord
validate do |person|
errors.add :name, :too_short, message: "is not long enough"
end
end
```
To read about validation errors in greater depth refer to the [Working with Validation Errors](#working-with-validation-errors) section.
## [2. Validations](#validations)
Active Record offers many predefined validations that you can use directly inside your class definitions. These predefined validations provide common validation rules. Each time a validation fails, an error message is added to the object's `errors` collection, and this error is associated with the specific attribute being validated.
When a validation fails, the error message is stored in the `errors` collection under the attribute name that triggered the validation. This means you can easily access the errors related to any specific attribute. For instance, if you validate the `:name` attribute and the validation fails, you will find the error message under `errors[:name]`.
In modern Rails applications, the more concise validate syntax is commonly used, for example:
```
validates :name, presence: true
```
However, older versions of Rails used "helper" methods, such as:
```
validates_presence_of :name
```
Both notations perform the same function, but the newer form is recommended for its readability and alignment with Rails' conventions.
Each validation accepts an arbitrary number of attribute names, allowing you to apply the same type of validation to multiple attributes in a single line of code.
Additionally, all validations accept the `:on` and `:message` options. The `:on` option specifies when the validation should be triggered, with possible values being `:create` or `:update`. The `:message` option allows you to define a custom error message that will be added to the errors collection if the validation fails. If you do not specify a message, Rails will use a default error message for that validation.
To see a list of the available default helpers, take a look at [`ActiveModel::Validations::HelperMethods`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations/HelperMethods.html). This API section uses the older notation as described above.
Below we outline the most commonly used validations.
### [2.1. `absence`](#absence)
This validator validates that the specified attributes are absent. It uses the [`Object#present?`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-present-3F) method to check if the value is neither nil nor a blank string - that is, a string that is either empty or consists of whitespace only.
`#absence` is commonly used for conditional validations. For example:
```
class Person < ApplicationRecord
validates :phone_number, :address, absence: true, if: :invited?
end
```
```
irb> person = Person.new(name: "Jane Doe", invitation_sent_at: Time.current)
irb> person.valid?
=> true # absence validation passes
```
If you want to be sure that an association is absent, you'll need to test whether the associated object itself is absent, and not the foreign key used to map the association.
```
class LineItem < ApplicationRecord
belongs_to :order, optional: true
validates :order, absence: true
end
```
```
irb> line_item = LineItem.new
irb> line_item.valid?
=> true # absence validation passes
order = Order.create
irb> line_item_with_order = LineItem.new(order: order)
irb> line_item_with_order.valid?
=> false # absence validation fails
```
For `belongs_to` the association presence is validated by default. If you donβt want to have association presence validated, use `optional: true`.
Rails will usually infer the inverse association automatically. In cases where you use a custom `:foreign_key` or a `:through` association, it's important to explicitly set the `:inverse_of` option to optimize the association lookup. This helps avoid unnecessary database queries during validation.
For more details, check out the [Bi-directional Associations documentation](association_basics.html#bi-directional-associations).
If you want to ensure that the association is both present and valid, you also need to use `validates_associated`. More on that in the [validates\_associated section](#validates-associated).
If you validate the absence of an object associated via a [`has_one`](association_basics.html#has-one) or [`has_many`](association_basics.html#has-many) relationship, it will check that the object is neither `present?` nor `marked_for_destruction?`.
Since `false.present?` is false, if you want to validate the absence of a boolean field you should use:
```
validates :field_name, exclusion: { in: [true, false] }
```
The default error message is *"must be blank"*.
### [2.2. `acceptance`](#acceptance)
This method validates that a checkbox on the user interface was checked when a form was submitted. This is typically used when the user needs to agree to your application's terms of service, confirm that some text is read, or any similar concept.
```
class Person < ApplicationRecord
validates :terms_of_service, acceptance: true
end
```
This check is performed only if `terms_of_service` is not `nil`. The default error message for this validation is *"must be accepted"*. You can also pass in a custom message via the `message` option.
```
class Person < ApplicationRecord
validates :terms_of_service, acceptance: { message: "must be agreed to" }
end
```
It can also receive an `:accept` option, which determines the allowed values that will be considered as acceptable. It defaults to `['1', true]` and can be easily changed.
```
class Person < ApplicationRecord
validates :terms_of_service, acceptance: { accept: "yes" }
validates :eula, acceptance: { accept: ["TRUE", "accepted"] }
end
```
This validation is very specific to web applications and this 'acceptance' does not need to be recorded anywhere in your database. If you don't have a field for it, the validator will create a virtual attribute. If the field does exist in your database, the `accept` option must be set to or include `true` or else the validation will not run.
### [2.3. `confirmation`](#confirmation)
You should use this validator when you have two text fields that should receive exactly the same content. For example, you may want to confirm an email address or a password. This validation creates a virtual attribute whose name is the name of the field that has to be confirmed with "\_confirmation" appended.
```
class Person < ApplicationRecord
validates :email, confirmation: true
end
```
In your view template you could use something like
```
<%= text_field :person, :email %>
<%= text_field :person, :email_confirmation %>
```
This check is performed only if `email_confirmation` is not `nil`. To require confirmation, make sure to add a presence check for the confirmation attribute (we'll take a look at the [`presence`](#presence) check later on in this guide):
```
class Person < ApplicationRecord
validates :email, confirmation: true
validates :email_confirmation, presence: true
end
```
There is also a `:case_sensitive` option that you can use to define whether the confirmation constraint will be case sensitive or not. This option defaults to true.
```
class Person < ApplicationRecord
validates :email, confirmation: { case_sensitive: false }
end
```
The default error message for this validator is *"doesn't match confirmation"*. You can also pass in a custom message via the `message` option.
Generally when using this validator, you will want to combine it with the `:if` option to only validate the "\_confirmation" field when the initial field has changed and **not** every time you save the record. More on [conditional validations](#conditional-validations) later.
```
class Person < ApplicationRecord
validates :email, confirmation: true
validates :email_confirmation, presence: true, if: :email_changed?
end
```
### [2.4. `comparison`](#comparison)
This validator will validate a comparison between any two comparable values.
```
class Promotion < ApplicationRecord
validates :end_date, comparison: { greater_than: :start_date }
end
```
The default error message for this validator is *"failed comparison"*. You can also pass in a custom message via the `message` option.
These options are all supported:
| Option | Description | Default Error Message |
| --------------------------- | ------------------------------------------------------------------------ | ------------------------------------------- |
| `:greater_than` | Specifies the value must be greater than the supplied value. | "must be greater than %{count}" |
| `:greater_than_or_equal_to` | Specifies the value must be greater than or equal to the supplied value. | "must be greater than or equal to %{count}" |
| `:equal_to` | Specifies the value must be equal to the supplied value. | "must be equal to %{count}" |
| `:less_than` | Specifies the value must be less than the supplied value. | "must be less than %{count}" |
| `:less_than_or_equal_to` | Specifies the value must be less than or equal to the supplied value. | "must be less than or equal to %{count}" |
| `:other_than` | Specifies the value must be other than the supplied value. | "must be other than %{count}" |
The validator requires a compare option be supplied. Each option accepts a value, proc, or symbol. Any class that includes [Comparable](https://docs.ruby-lang.org/en/master/Comparable.html) can be compared.
### [2.5. `format`](#format)
This validator validates the attributes' values by testing whether they match a given regular expression, which is specified using the `:with` option.
```
class Product < ApplicationRecord
validates :legacy_code, format: { with: /\A[a-zA-Z]+\z/,
message: "only allows letters" }
end
```
Inversely, by using the `:without` option instead you can require that the specified attribute does *not* match the regular expression.
In either case, the provided `:with` or `:without` option must be a regular expression or a proc or lambda that returns one.
The default error message is *"is invalid"*.
Use `\A` and `\z` to match the start and end of the string, `^` and `$` match the start/end of a line. Due to frequent misuse of `^` and `$`, you need to pass the `multiline: true` option in case you use any of these two anchors in the provided regular expression. In most cases, you should be using `\A` and `\z`.
### [2.6. `inclusion` and `exclusion`](#inclusion-and-exclusion)
Both of these validators validate whether an attributeβs value is included or excluded from a given set. The set can be any enumerable object such as an array, range, or a dynamically generated collection using a proc, lambda, or symbol.
* **`inclusion`** ensures that the value is present in the set.
* **`exclusion`** ensures that the value is *not* present in the set.
In both cases, the option `:in` receives the set of values, and `:within` can be used as an alias. For full options on customizing error messages, see the [message documentation](#message).
If the enumerable is a numerical, time, or datetime range, the test is performed using `Range#cover?`, otherwise, it uses `include?`. When using a proc or lambda, the instance under validation is passed as an argument, allowing for dynamic validation.
#### [2.6.1. Examples](#examples)
For `inclusion`:
```
class Coffee < ApplicationRecord
validates :size, inclusion: { in: %w(small medium large),
message: "%{value} is not a valid size" }
end
```
For `exclusion`:
```
class Account < ApplicationRecord
validates :subdomain, exclusion: { in: %w(www us ca jp),
message: "%{value} is reserved." }
end
```
Both validators allow the use of dynamic validation through methods that return an enumerable. Hereβs an example using a proc for `inclusion`:
```
class Coffee < ApplicationRecord
validates :size, inclusion: { in: ->(coffee) { coffee.available_sizes } }
def available_sizes
%w(small medium large extra_large)
end
end
```
Similarly, for `exclusion`:
```
class Account < ApplicationRecord
validates :subdomain, exclusion: { in: ->(account) { account.reserved_subdomains } }
def reserved_subdomains
%w(www us ca jp admin)
end
end
```
### [2.7. `length`](#length)
This validator validates the length of the attributes' values. It provides a variety of options, so you can specify length constraints in different ways:
```
class Person < ApplicationRecord
validates :name, length: { minimum: 2 }
validates :bio, length: { maximum: 500 }
validates :password, length: { in: 6..20 }
validates :registration_number, length: { is: 6 }
end
```
The possible length constraint options are:
| Option | Description |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| `:minimum` | The attribute cannot have less than the specified length. |
| `:maximum` | The attribute cannot have more than the specified length. |
| `:in` | The attribute length must be included in a given interval. The value for this option must be a range. |
| `:is` | The attribute length must be equal to the given value. |
The default error messages depend on the type of length validation being performed. You can customize these messages using the `:wrong_length`, `:too_long`, and `:too_short` options and `%{count}` as a placeholder for the number corresponding to the length constraint being used. You can still use the `:message` option to specify an error message.
```
class Person < ApplicationRecord
validates :bio, length: { maximum: 1000,
too_long: "%{count} characters is the maximum allowed" }
end
```
The default error messages are plural (e.g. "is too short (minimum is %{count} characters)"). For this reason, when `:minimum` is 1 you should provide a custom message or use `presence: true` instead. Similarly, when `:in` or `:within` have a lower limit of 1, you should either provide a custom message or call `presence` prior to `length`. Only one constraint option can be used at a time apart from the `:minimum` and `:maximum` options which can be combined together.
### [2.8. `numericality`](#numericality)
This validator validates that your attributes have only numeric values. By default, it will match an optional sign followed by an integer or floating point number.
To specify that only integer numbers are allowed, set `:only_integer` to true. Then it will use the following regular expression to validate the attribute's value.
```
/\A[+-]?\d+\z/
```
Otherwise, it will try to convert the value to a number using `Float`. `Float`s are converted to `BigDecimal` using the column's precision value or a maximum of 15 digits.
```
class Player < ApplicationRecord
validates :points, numericality: true
validates :games_played, numericality: { only_integer: true }
end
```
The default error message for `:only_integer` is *"must be an integer"*.
Besides `:only_integer`, this validator also accepts the `:only_numeric` option which specifies the value must be an instance of `Numeric` and attempts to parse the value if it is a `String`.
By default, `numericality` doesn't allow `nil` values. You can use `allow_nil: true` option to permit it. For `Integer` and `Float` columns empty strings are converted to `nil`.
The default error message when no options are specified is *"is not a number"*.
There are also many options that can be used to add constraints to acceptable values:
| Option | Description | Default Error Message |
| --------------------------- | ------------------------------------------------------------------------ | ------------------------------------------- |
| `:greater_than` | Specifies the value must be greater than the supplied value. | "must be greater than %{count}" |
| `:greater_than_or_equal_to` | Specifies the value must be greater than or equal to the supplied value. | "must be greater than or equal to %{count}" |
| `:equal_to` | Specifies the value must be equal to the supplied value. | "must be equal to %{count}" |
| `:less_than` | Specifies the value must be less than the supplied value. | "must be less than %{count}" |
| `:less_than_or_equal_to` | Specifies the value must be less than or equal to the supplied value. | "must be less than or equal to %{count}" |
| `:other_than` | Specifies the value must be other than the supplied value. | "must be other than %{count}" |
| `:in` | Specifies the value must be in the supplied range. | "must be in %{count}" |
| `:odd` | Specifies the value must be an odd number. | "must be odd" |
| `:even` | Specifies the value must be an even number. | "must be even" |
### [2.9. `presence`](#presence)
This validator validates that the specified attributes are not empty. It uses the [`Object#blank?`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-blank-3F) method to check if the value is either `nil` or a blank string - that is, a string that is either empty or consists of whitespace.
```
class Person < ApplicationRecord
validates :name, :login, :email, presence: true
end
```
```
person = Person.new(name: "Alice", login: "alice123", email: "alice@example.com")
person.valid?
=> true # presence validation passes
invalid_person = Person.new(name: "", login: nil, email: "bob@example.com")
invalid_person.valid?
=> false # presence validation fails
```
To check that an association is present, you'll need to test that the associated object is present, and not the foreign key used to map the association. Testing the association will help you to determine that the foreign key is not empty and also that the referenced object exists.
```
class Supplier < ApplicationRecord
has_one :account
validates :account, presence: true
end
```
```
irb> account = Account.create(name: "Account A")
irb> supplier = Supplier.new(account: account)
irb> supplier.valid?
=> true # presence validation passes
irb> invalid_supplier = Supplier.new
irb> invalid_supplier.valid?
=> false # presence validation fails
```
In cases where you use a custom `:foreign_key` or a `:through` association, it's important to explicitly set the `:inverse_of` option to optimize the association lookup. This helps avoid unnecessary database queries during validation.
For more details, check out the [Bi-directional Associations documentation](association_basics.html#bi-directional-associations).
If you want to ensure that the association is both present and valid, you also need to use `validates_associated`. More on that [below](#validates-associated).
If you validate the presence of an object associated via a [`has_one`](association_basics.html#has-one) or [`has_many`](association_basics.html#has-many) relationship, it will check that the object is neither `blank?` nor `marked_for_destruction?`.
Since `false.blank?` is true, if you want to validate the presence of a boolean field you should use one of the following validations:
```
# Value _must_ be true or false
validates :boolean_field_name, inclusion: [true, false]
# Value _must not_ be nil, aka true or false
validates :boolean_field_name, exclusion: [nil]
```
By using one of these validations, you will ensure the value will NOT be `nil` which would result in a `NULL` value in most cases.
The default error message is *"can't be blank"*.
### [2.10. `uniqueness`](#uniqueness)
This validator validates that the attribute's value is unique right before the object gets saved.
```
class Account < ApplicationRecord
validates :email, uniqueness: true
end
```
The validation happens by performing an SQL query into the model's table, searching for an existing record with the same value in that attribute.
There is a `:scope` option that you can use to specify one or more attributes that are used to limit the uniqueness check:
```
class Holiday < ApplicationRecord
validates :name, uniqueness: { scope: :year,
message: "should happen once per year" }
end
```
This validation does not create a uniqueness constraint in the database, so a scenario can occur whereby two different database connections create two records with the same value for a column that you intended to be unique. To avoid this, you must create a unique index on that column in your database.
In order to add a uniqueness database constraint on your database, use the [`add_index`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_index) statement in a migration and include the `unique: true` option.
If you are using the `:scope` option in your uniqueness validation, and you wish to create a database constraint to prevent possible violations of the uniqueness validation, you must create a unique index on both columns in your database. See [the MySQL manual](https://dev.mysql.com/doc/refman/en/multiple-column-indexes.html) and [the MariaDB manual](https://mariadb.com/kb/en/compound-composite-indexes/) for more details about multiple column indexes, or [the PostgreSQL manual](https://www.postgresql.org/docs/current/static/ddl-constraints.html) for examples of unique constraints that refer to a group of columns.
There is also a `:case_sensitive` option that you can use to define whether the uniqueness constraint will be case sensitive, case insensitive, or if it should respect the default database collation. This option defaults to respecting the default database collation.
```
class Person < ApplicationRecord
validates :name, uniqueness: { case_sensitive: false }
end
```
Some databases are configured to perform case-insensitive searches anyway.
A `:conditions` option can be used to specify additional conditions as a `WHERE` SQL fragment to limit the uniqueness constraint lookup:
```
validates :name, uniqueness: { conditions: -> { where(status: "active") } }
```
The default error message is *"has already been taken"*.
See [`validates_uniqueness_of`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Validations/ClassMethods.html#method-i-validates_uniqueness_of) for more information.
### [2.11. `validates_associated`](#validates-associated)
You should use this validator when your model has associations that always need to be validated. Every time you try to save your object, `valid?` will be called on each one of the associated objects.
```
class Library < ApplicationRecord
has_many :books
validates_associated :books
end
```
This validation will work with all of the association types.
Don't use `validates_associated` on both ends of your associations. They would call each other in an infinite loop.
The default error message for [`validates_associated`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Validations/ClassMethods.html#method-i-validates_associated) is *"is invalid"*. Note that each associated object will contain its own `errors` collection; errors do not bubble up to the calling model.
[`validates_associated`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Validations/ClassMethods.html#method-i-validates_associated) can only be used with ActiveRecord objects, everything up until now can also be used on any object which includes [`ActiveModel::Validations`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations.html).
### [2.12. `validates_each`](#validates-each)
This validator validates attributes against a block. It doesn't have a predefined validation function. You should create one using a block, and every attribute passed to [`validates_each`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates_each) will be tested against it.
In the following example, we will reject names and surnames that begin with lowercase.
```
class Person < ApplicationRecord
validates_each :name, :surname do |record, attr, value|
record.errors.add(attr, "must start with upper case") if /\A[[:lower:]]/.match?(value)
end
end
```
The block receives the record, the attribute's name, and the attribute's value.
You can do anything you like to check for valid data within the block. If your validation fails, you should add an error to the model, therefore making it invalid.
### [2.13. `validates_with`](#validates-with)
This validator passes the record to a separate class for validation.
```
class AddressValidator < ActiveModel::Validator
def validate(record)
if record.house_number.blank?
record.errors.add :house_number, "is required"
end
if record.street.blank?
record.errors.add :street, "is required"
end
if record.postcode.blank?
record.errors.add :postcode, "is required"
end
end
end
class Invoice < ApplicationRecord
validates_with AddressValidator
end
```
There is no default error message for `validates_with`. You must manually add errors to the record's errors collection in the validator class.
Errors added to `record.errors[:base]` relate to the state of the record as a whole.
To implement the validate method, you must accept a `record` parameter in the method definition, which is the record to be validated.
If you want to add an error on a specific attribute, you can pass it as the first argument to the `add` method.
```
def validate(record)
if record.some_field != "acceptable"
record.errors.add :some_field, "this field is unacceptable"
end
end
```
We will cover [validation errors](#working-with-validation-errors) in greater detail later.
The [`validates_with`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations/ClassMethods.html#method-i-validates_with) validator takes a class, or a list of classes to use for validation.
```
class Person < ApplicationRecord
validates_with MyValidator, MyOtherValidator, on: :create
end
```
Like all other validations, `validates_with` takes the `:if`, `:unless` and `:on` options. If you pass any other options, it will send those options to the validator class as `options`:
```
class AddressValidator < ActiveModel::Validator
def validate(record)
options[:fields].each do |field|
if record.send(field).blank?
record.errors.add field, "is required"
end
end
end
end
class Invoice < ApplicationRecord
validates_with AddressValidator, fields: [:house_number, :street, :postcode, :country]
end
```
The validator will be initialized *only once* for the whole application life cycle, and not on each validation run, so be careful about using instance variables inside it.
If your validator is complex enough that you want instance variables, you can easily use a plain old Ruby object instead:
```
class Invoice < ApplicationRecord
validate do |invoice|
AddressValidator.new(invoice).validate
end
end
class AddressValidator
def initialize(invoice)
@invoice = invoice
end
def validate
validate_field(:house_number)
validate_field(:street)
validate_field(:postcode)
end
private
def validate_field(field)
if @invoice.send(field).blank?
@invoice.errors.add field, "#{field.to_s.humanize} is required"
end
end
end
```
We will cover [custom validations](#performing-custom-validations) more later.
## [3. Validation Options](#validation-options)
There are several common options supported by the validators. These options are:
* [`:allow_nil`](#allow-nil): Skip validation if the attribute is `nil`.
* [`:allow_blank`](#allow-blank): Skip validation if the attribute is blank.
* [`:message`](#message): Specify a custom error message.
* [`:on`](#on): Specify the contexts where this validation is active.
* [`:strict`](#strict-validations): Raise an exception when the validation fails.
* [`:if` and `:unless`](#conditional-validations): Specify when the validation should or should not occur.
Not all of these options are supported by every validator, please refer to the API documentation for [`ActiveModel::Validations`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations.html).
### [3.1. `:allow_nil`](#allow-nil)
The `:allow_nil` option skips the validation when the value being validated is `nil`.
```
class Coffee < ApplicationRecord
validates :size, inclusion: { in: %w(small medium large),
message: "%{value} is not a valid size" }, allow_nil: true
end
```
```
irb> Coffee.create(size: nil).valid?
=> true
irb> Coffee.create(size: "mega").valid?
=> false
```
For full options to the message argument please see the [message documentation](#message).
### [3.2. `:allow_blank`](#allow-blank)
The `:allow_blank` option is similar to the `:allow_nil` option. This option will let validation pass if the attribute's value is `blank?`, like `nil` or an empty string for example.
```
class Topic < ApplicationRecord
validates :title, length: { is: 6 }, allow_blank: true
end
```
```
irb> Topic.create(title: "").valid?
=> true
irb> Topic.create(title: nil).valid?
=> true
irb> Topic.create(title: "short").valid?
=> false # 'short' is not of length 6, so validation fails even though it's not blank
```
### [3.3. `:message`](#message)
As you've already seen, the `:message` option lets you specify the message that will be added to the `errors` collection when validation fails. When this option is not used, Active Record will use the respective default error message for each validation.
The `:message` option accepts either a `String` or `Proc` as its value.
A `String` `:message` value can optionally contain any/all of `%{value}`, `%{attribute}`, and `%{model}` which will be dynamically replaced when validation fails. This replacement is done using the [i18n gem](https://github.com/ruby-i18n/i18n), and the placeholders must match exactly, no spaces are allowed.
```
class Person < ApplicationRecord
# Hard-coded message
validates :name, presence: { message: "must be given please" }
# Message with dynamic attribute value. %{value} will be replaced
# with the actual value of the attribute. %{attribute} and %{model}
# are also available.
validates :age, numericality: { message: "%{value} seems wrong" }
end
```
A `Proc` `:message` value is given two arguments: the object being validated, and a hash with `:model`, `:attribute`, and `:value` key-value pairs.
```
class Person < ApplicationRecord
validates :username,
uniqueness: {
# object = person object being validated
# data = { model: "Person", attribute: "Username", value: }
message: ->(object, data) do
"Hey #{object.name}, #{data[:value]} is already taken."
end
}
end
```
To translate error messages, see the [I18n guide](i18n.html#error-message-scopes).
### [3.4. `:on`](#on)
The `:on` option lets you specify when the validation should happen. The default behavior for all the built-in validations is to be run on save (both when you're creating a new record and when you're updating it). If you want to change it, you can use `on: :create` to run the validation only when a new record is created or `on: :update` to run the validation only when a record is updated.
```
class Person < ApplicationRecord
# it will be possible to update email with a duplicated value
validates :email, uniqueness: true, on: :create
# it will be possible to create the record with a non-numerical age
validates :age, numericality: true, on: :update
# the default (validates on both create and update)
validates :name, presence: true
end
```
You can also use `:on` to define custom contexts. Custom contexts need to be triggered explicitly by passing the name of the context to `valid?`, `invalid?`, or `save`.
```
class Person < ApplicationRecord
validates :email, uniqueness: true, on: :account_setup
validates :age, numericality: true, on: :account_setup
end
```
```
irb> person = Person.new(age: 'thirty-three')
irb> person.valid?
=> true
irb> person.valid?(:account_setup)
=> false
irb> person.errors.messages
=> {:email=>["has already been taken"], :age=>["is not a number"]}
```
`person.valid?(:account_setup)` executes both the validations without saving the model. `person.save(context: :account_setup)` validates `person` in the `account_setup` context before saving.
Passing an array of symbols is also acceptable.
```
class Book
include ActiveModel::Validations
validates :title, presence: true, on: [:update, :ensure_title]
end
```
```
irb> book = Book.new(title: nil)
irb> book.valid?
=> true
irb> book.valid?(:ensure_title)
=> false
irb> book.errors.messages
=> {:title=>["can't be blank"]}
```
When triggered by an explicit context, validations are run for that context, as well as any validations *without* a context.
```
class Person < ApplicationRecord
validates :email, uniqueness: true, on: :account_setup
validates :age, numericality: true, on: :account_setup
validates :name, presence: true
end
```
```
irb> person = Person.new
irb> person.valid?(:account_setup)
=> false
irb> person.errors.messages
=> {:email=>["has already been taken"], :age=>["is not a number"], :name=>["can't be blank"]}
```
You can read more about use-cases for `:on` in the [Custom Contexts section](#custom-contexts).
## [4. Conditional Validations](#conditional-validations)
Sometimes it will make sense to validate an object only when a given condition is met. You can do that by using the `:if` and `:unless` options, which can take a symbol, a `Proc` or an `Array`. You may use the `:if` option when you want to specify when the validation **should** happen. Alternatively, if you want to specify when the validation **should not** happen, then you may use the `:unless` option.
### [4.1. Using a Symbol with `:if` and `:unless`](#using-a-symbol-with-if-and-unless)
You can associate the `:if` and `:unless` options with a symbol corresponding to the name of a method that will get called right before validation happens. This is the most commonly used option.
```
class Order < ApplicationRecord
validates :card_number, presence: true, if: :paid_with_card?
def paid_with_card?
payment_type == "card"
end
end
```
### [4.2. Using a Proc with `:if` and `:unless`](#using-a-proc-with-if-and-unless)
It is possible to associate `:if` and `:unless` with a `Proc` object which will be called. Using a `Proc` object gives you the ability to write an inline condition instead of a separate method. This option is best suited for one-liners.
```
class Account < ApplicationRecord
validates :password, confirmation: true,
unless: Proc.new { |a| a.password.blank? }
end
```
As `lambda` is a type of `Proc`, it can also be used to write inline conditions taking advantage of the shortened syntax.
```
validates :password, confirmation: true, unless: -> { password.blank? }
```
### [4.3. Grouping Conditional Validations](#grouping-conditional-validations)
Sometimes it is useful to have multiple validations use one condition. It can be easily achieved using [`with_options`](https://api.rubyonrails.org/v8.1.4/classes/Object.html#method-i-with_options).
```
class User < ApplicationRecord
with_options if: :is_admin? do |admin|
admin.validates :password, length: { minimum: 10 }
admin.validates :email, presence: true
end
end
```
All validations inside of the `with_options` block will automatically have `if: :is_admin?` merged into its options.
### [4.4. Combining Validation Conditions](#combining-validation-conditions)
On the other hand, when multiple conditions define whether or not a validation should happen, an `Array` can be used. Moreover, you can apply both `:if` and `:unless` to the same validation.
```
class Computer < ApplicationRecord
validates :mouse, presence: true,
if: [Proc.new { |c| c.market.retail? }, :desktop?],
unless: Proc.new { |c| c.trackpad.present? }
end
```
The validation only runs when all the `:if` conditions and none of the `:unless` conditions are evaluated to `true`.
## [5. Strict Validations](#strict-validations)
You can also specify validations to be strict and raise `ActiveModel::StrictValidationFailed` when the object is invalid.
```
class Person < ApplicationRecord
validates :name, presence: { strict: true }
end
```
```
irb> Person.new.valid?
=> ActiveModel::StrictValidationFailed: Name can't be blank
```
Strict validations ensure that an exception is raised immediately when validation fails, which can be useful in situations where you want to enforce immediate feedback or halt processing when invalid data is encountered. For example, you might use strict validations in a scenario where invalid input should prevent further operations, such as when processing critical transactions or performing data integrity checks.
There is also the ability to pass a custom exception to the `:strict` option.
```
class Person < ApplicationRecord
validates :token, presence: true, uniqueness: true, strict: TokenGenerationException
end
```
```
irb> Person.new.valid?
=> TokenGenerationException: Token can't be blank
```
## [6. Listing Validators](#listing-validators)
If you want to find out all of the validators for a given object, you can use `validators`.
For example, if we have the following model using a custom validator and a built-in validator:
```
class Person < ApplicationRecord
validates :name, presence: true, on: :create
validates :email, format: URI::MailTo::EMAIL_REGEXP
validates_with MyOtherValidator, strict: true
end
```
We can now use `validators` on the "Person" model to list all validators, or even check a specific field using `validators_on`.
```
irb> Person.validators
#=> [#:create}>,
#true}>,
#URI::MailTo::EMAIL_REGEXP}>]
#true}>]
irb> Person.validators_on(:name)
#=> [#]
```
## [7. Performing Custom Validations](#performing-custom-validations)
When the built-in validations are not enough for your needs, you can write your own validators or validation methods as you prefer.
### [7.1. Custom Validators](#custom-validators)
Custom validators are classes that inherit from [`ActiveModel::Validator`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validator.html). These classes must implement the `validate` method which takes a record as an argument and performs the validation on it. The custom validator is called using the `validates_with` method.
```
class MyValidator < ActiveModel::Validator
def validate(record)
unless record.name.start_with? "X"
record.errors.add :name, "Provide a name starting with X, please!"
end
end
end
class Person < ApplicationRecord
validates_with MyValidator
end
```
The easiest way to add custom validators for validating individual attributes is with the convenient [`ActiveModel::EachValidator`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/EachValidator.html). In this case, the custom validator class must implement a `validate_each` method which takes three arguments: record, attribute, and value. These correspond to the instance, the attribute to be validated, and the value of the attribute in the passed instance.
```
class EmailValidator < ActiveModel::EachValidator
def validate_each(record, attribute, value)
unless URI::MailTo::EMAIL_REGEXP.match?(value)
record.errors.add attribute, (options[:message] || "is not an email")
end
end
end
class Person < ApplicationRecord
validates :email, presence: true, email: true
end
```
As shown in the example, you can also combine standard validations with your own custom validators.
### [7.2. Custom Methods](#custom-methods)
You can also create methods that verify the state of your models and add errors to the `errors` collection when they are invalid. You must then register these methods by using the [`validate`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations/ClassMethods.html#method-i-validate) class method, passing in the symbols for the validation methods' names.
You can pass more than one symbol for each class method and the respective validations will be run in the same order as they were registered.
The `valid?` method will verify that the `errors` collection is empty, so your custom validation methods should add errors to it when you wish validation to fail:
```
class Invoice < ApplicationRecord
validate :expiration_date_cannot_be_in_the_past,
:discount_cannot_be_greater_than_total_value
def expiration_date_cannot_be_in_the_past
if expiration_date.present? && expiration_date < Date.today
errors.add(:expiration_date, "can't be in the past")
end
end
def discount_cannot_be_greater_than_total_value
if discount > total_value
errors.add(:discount, "can't be greater than total value")
end
end
end
```
By default, such validations will run every time you call `valid?` or save the object. But it is also possible to control when to run these custom validations by giving an `:on` option to the `validate` method, with either: `:create` or `:update`.
```
class Invoice < ApplicationRecord
validate :active_customer, on: :create
def active_customer
errors.add(:customer_id, "is not active") unless customer.active?
end
end
```
See the section above for more details about [`:on`](#on).
### [7.3. Custom Contexts](#custom-contexts)
You can define your own custom validation contexts for callbacks, which is useful when you want to perform validations based on specific scenarios or group certain callbacks together and run them in a specific context. A common scenario for custom contexts is when you have a multi-step form and want to perform validations per step.
For instance, you might define custom contexts for each step of the form:
```
class User < ApplicationRecord
validate :personal_information, on: :personal_info
validate :contact_information, on: :contact_info
validate :location_information, on: :location_info
private
def personal_information
errors.add(:base, "Name must be present") if first_name.blank?
errors.add(:base, "Age must be at least 18") if age && age < 18
end
def contact_information
errors.add(:base, "Email must be present") if email.blank?
errors.add(:base, "Phone number must be present") if phone.blank?
end
def location_information
errors.add(:base, "Address must be present") if address.blank?
errors.add(:base, "City must be present") if city.blank?
end
end
```
In these cases, you may be tempted to [skip callbacks](active_record_callbacks.html#skipping-callbacks) altogether, but defining a custom context can be a more structured approach. You will need to combine a context with the `:on` option to define a custom context for a callback.
Once you've defined the custom context, you can use it to trigger the validations:
```
irb> user = User.new(name: "John Doe", age: 17, email: "jane@example.com", phone: "1234567890", address: "123 Main St")
irb> user.valid?(:personal_info) # => false
irb> user.valid?(:contact_info) # => true
irb> user.valid?(:location_info) # => false
```
You can also use the custom contexts to trigger the validations on any method that supports callbacks. For example, you could use the custom context to trigger the validations on `save`:
```
irb> user = User.new(name: "John Doe", age: 17, email: "jane@example.com", phone: "1234567890", address: "123 Main St")
irb> user.save(context: :personal_info) # => false
irb> user.save(context: :contact_info) # => true
irb> user.save(context: :location_info) # => false
```
## [8. Working with Validation Errors](#working-with-validation-errors)
The [`valid?`](https://api.rubyonrails.org/v8.1.4/classes/ActiveRecord/Validations.html#method-i-valid-3F) and [`invalid?`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations.html#method-i-invalid-3F) methods only provide a summary status on validity. However you can dig deeper into each individual error by using various methods from the [`errors`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations.html#method-i-errors) collection.
The following is a list of the most commonly used methods. Please refer to the [`ActiveModel::Errors`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Errors.html) documentation for a list of all the available methods.
### [8.1. `errors`](#errors)
The [`errors`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Validations.html#method-i-errors) method is the starting point through which you can drill down into various details of each error.
This returns an instance of the class `ActiveModel::Errors` containing all errors, each error is represented by an [`ActiveModel::Error`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Error.html) object.
```
class Person < ApplicationRecord
validates :name, presence: true, length: { minimum: 3 }
end
```
```
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors.full_messages
=> ["Name can't be blank", "Name is too short (minimum is 3 characters)"]
irb> person = Person.new(name: "John Doe")
irb> person.valid?
=> true
irb> person.errors.full_messages
=> []
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors.first.details
=> {:error=>:too_short, :count=>3}
```
### [8.2. `errors[]`](#errors-squarebrackets)
[`errors[]`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Errors.html#method-i-5B-5D) is used when you want to check the error messages for a specific attribute. It returns an array of strings with all error messages for the given attribute, each string with one error message. If there are no errors related to the attribute, it returns an empty array.
This method is only useful *after* validations have been run, because it only inspects the `errors` collection and does not trigger validations itself. It's different from the `ActiveRecord::Base#invalid?` method explained above because it doesn't verify the validity of the object as a whole. `errors[]` only checks to see whether there are errors found on an individual attribute of the object.
```
class Person < ApplicationRecord
validates :name, presence: true, length: { minimum: 3 }
end
```
```
irb> person = Person.new(name: "John Doe")
irb> person.valid?
=> true
irb> person.errors[:name]
=> []
irb> person = Person.new(name: "JD")
irb> person.valid?
=> false
irb> person.errors[:name]
=> ["is too short (minimum is 3 characters)"]
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors[:name]
=> ["can't be blank", "is too short (minimum is 3 characters)"]
```
### [8.3. `errors.where` and Error Object](#errors-where-and-error-object)
Sometimes we may need more information about each error besides its message. Each error is encapsulated as an `ActiveModel::Error` object, and the [`where`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Errors.html#method-i-where) method is the most common way of access.
`where` returns an array of error objects filtered by various degrees of conditions.
Given the following validation:
```
class Person < ApplicationRecord
validates :name, presence: true, length: { minimum: 3 }
end
```
We can filter for just the `attribute` by passing it as the first parameter to `errors.where(:attr)`. The second parameter is used for filtering the `type` of error we want by calling `errors.where(:attr, :type)`.
```
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors.where(:name)
=> [ ... ] # all errors for :name attribute
irb> person.errors.where(:name, :too_short)
=> [ ... ] # :too_short errors for :name attribute
```
Lastly, we can filter by any `options` that may exist on the given type of error object.
```
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors.where(:name, :too_short, minimum: 3)
=> [ ... ] # all name errors being too short and minimum is 3
```
You can read various information from these error objects:
```
irb> error = person.errors.where(:name).last
irb> error.attribute
=> :name
irb> error.type
=> :too_short
irb> error.options[:count]
=> 3
```
You can also generate the error message:
```
irb> error.message
=> "is too short (minimum is 3 characters)"
irb> error.full_message
=> "Name is too short (minimum is 3 characters)"
```
The [`full_message`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Errors.html#method-i-full_message) method generates a more user-friendly message, with the capitalized attribute name prepended. (To customize the format that `full_message` uses, see the [I18n guide](i18n.html#active-model-methods).)
### [8.4. `errors.add`](#errors-add)
The [`add`](https://api.rubyonrails.org/v8.1.4/classes/ActiveModel/Errors.html#method-i-add) method creates the error object by taking the `attribute`, the error `type` and additional options hash. This is useful when writing your own validator, as it lets you define very specific error situations.
```
class Person < ApplicationRecord
validate do |person|
errors.add :name, :too_plain, message: "is not cool enough"
end
end
```
```
irb> person = Person.new
irb> person.errors.where(:name).first.type
=> :too_plain
irb> person.errors.where(:name).first.full_message
=> "Name is not cool enough"
```
### [8.5. `errors[:base]`](#errors-base)
You can add errors that are related to the object's state as a whole, instead of being related to a specific attribute. To do this you must use `:base` as the attribute when adding a new error.
```
class Person < ApplicationRecord
validate do |person|
errors.add :base, :invalid, message: "This person is invalid because ..."
end
end
```
```
irb> person = Person.new
irb> person.errors.where(:base).first.full_message
=> "This person is invalid because ..."
```
### [8.6. `errors.size`](#errors-size)
The `size` method returns the total number of errors for the object.
```
class Person < ApplicationRecord
validates :name, presence: true, length: { minimum: 3 }
end
```
```
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors.size
=> 2
irb> person = Person.new(name: "Andrea", email: "andrea@example.com")
irb> person.valid?
=> true
irb> person.errors.size
=> 0
```
### [8.7. `errors.clear`](#errors-clear)
The `clear` method is used when you intentionally want to clear the `errors` collection. Of course, calling `errors.clear` upon an invalid object won't actually make it valid: the `errors` collection will now be empty, but the next time you call `valid?` or any method that tries to save this object to the database, the validations will run again. If any of the validations fail, the `errors` collection will be filled again.
```
class Person < ApplicationRecord
validates :name, presence: true, length: { minimum: 3 }
end
```
```
irb> person = Person.new
irb> person.valid?
=> false
irb> person.errors.empty?
=> false
irb> person.errors.clear
irb> person.errors.empty?
=> true
irb> person.save
=> false
irb> person.errors.empty?
=> false
```
## [9. Displaying Validation Errors in Views](#displaying-validation-errors-in-views)
Once you've defined a model and added validations, you'll want to display an error message when a validation fails during the creation of that model via a web form.
Since every application handles displaying validation errors differently, Rails does not include any view helpers for generating these messages. However, Rails gives you a rich number of methods to interact with validations that you can use to build your own. In addition, when generating a scaffold, Rails will put some generated ERB into the `_form.html.erb` that displays the full list of errors on that model.
Assuming we have a model that's been saved in an instance variable named `@article`, it looks like this:
```
<% if @article.errors.any? %>
<%= pluralize(@article.errors.count, "error") %> prohibited this article from being saved:
<% @article.errors.each do |error| %>
<%= error.full_message %>
<% end %>
<% end %>
```
Furthermore, if you use the Rails form helpers to generate your forms, when a validation error occurs on a field, it will generate an extra `
` around the entry.
```
```
You can then style this div however you'd like. The default scaffold that Rails generates, for example, adds this CSS rule:
```
.field_with_errors {
padding: 2px;
background-color: red;
display: table;
}
```
This means that any field with an error ends up with a 2 pixel red border.
### [9.1. Customizing Error Field Wrapper](#customizing-error-field-wrapper)
Rails uses the `field_error_proc` configuration option to wrap fields with errors in HTML. By default, this option wraps the erroneous form fields in a `
` with a `field_with_errors` class, as seen in the example above:
```
config.action_view.field_error_proc = Proc.new { |html_tag, instance| content_tag :div, html_tag, class: "field_with_errors" }
```
You can customize this behavior by modifying the field\_error\_proc setting in your application configuration, allowing you to change how errors are presented in your forms. For more details, refer to the [Configuration Guide on field\_error\_proc](configuring.html#config-action-view-field-error-proc).
***
***
[Back to top](#main-skip-link)
----
url: https://guides.rubyonrails.org/v8.1/asset_pipeline.html
----
***
## [1. What is an Asset Pipeline?](#what-is-an-asset-pipeline-questionmark)
The Rails Asset Pipeline is a library designed for organizing, caching, and serving static assets, such as JavaScript, CSS, and image files. It streamlines and optimizes the management of these assets to enhance the performance and maintainability of the application.
The Rails Asset Pipeline is managed by [**Propshaft**](https://github.com/rails/propshaft). Propshaft is built for an era where transpilation, bundling and compression are less critical for basic applications, thanks to better browser support, faster networks and HTTP/2 capabilities.
Propshaft focuses on essential asset management tasks and leaves more complex tasks, such as JavaScript and CSS bundling and minification, to specialized tools like [`jsbundling-rails`](https://github.com/rails/jsbundling-rails) and [`cssbundling-rails`](https://github.com/rails/cssbundling-rails), which can be added separately to your application. Propshaft focuses on [fingerprinting](#fingerprinting-versioning-with-digest-based-urls) and emphasizes generating digest-based URLs for assets, allowing browsers to cache them, thus minimizing the need for intricate compilation and bundling.
The [Propshaft](https://github.com/rails/propshaft) gem is enabled by default in new applications. If, for some reason, you want to disable it during setup, you can use the `--skip-asset-pipeline` option:
```
$ rails new app_name --skip-asset-pipeline
```
Before Rails 8, the asset pipeline was powered by [Sprockets](https://github.com/rails/sprockets). You can read about the [Sprockets Asset Pipeline](https://guides.rubyonrails.org/v7.2/asset_pipeline.html) in previous versions of the Rails Guides. You can also explore the [evolution of asset management techniques](#evolution-of-asset-management-techniques) to see how the Rails Asset Pipeline has evolved over time.
## [2. Propshaft Features](#propshaft-features)
Propshaft expects that your assets are already in a browser-ready formatβlike plain CSS, JavaScript, or preprocessed images (like JPEGs or PNGs). Its job is to organize, version, and serve those assets efficiently. In this section, weβll cover the main features of Propshaft and how they work.
### [2.1. Asset Load Order](#asset-load-order)
With Propshaft, you can control the loading order of dependent files by specifying each file explicitly and organizing them manually or ensuring they are included in the correct sequence within your HTML or layout files. This ensures that dependencies are managed and loaded without relying on automated dependency management tools. Below are some strategies for managing dependencies:
1. Manually include assets in the correct order:
In your HTML layout (usually `application.html.erb` for Rails apps) you can specify the exact order for loading CSS and JavaScript files by including each file individually in a specific order. For example:
```
<%= stylesheet_link_tag "reset" %>
<%= stylesheet_link_tag "base" %>
<%= stylesheet_link_tag "main" %>
<%= javascript_include_tag "utilities" %>
<%= javascript_include_tag "main" %>
```
This is important if, for instance, `main.js` relies on `utilities.js` to be loaded first.
2. Use Modules in JavaScript (ES6)
If you have dependencies within JavaScript files, ES6 modules can help. By using import statements, you can explicitly control dependencies within JavaScript code. Just make sure your JavaScript files are set up as modules using `
```
This way, you can manage dependencies within JavaScript files without relying on Propshaft to understand them. By importing modules, you can control the order in which files are loaded and ensure dependencies are met.
3. Combine Files when necessary
If you have several JavaScript or CSS files that must always load together, you can combine them into a single file. For example, you could create a `combined.js` file that imports or copies code from other scripts. Then, just include `combined.js` in your layout to avoid dealing with individual file ordering. This can be useful for files that always load together, like a set of utility functions or a group of styles for a specific component. While this approach can work for small projects or simple use cases, it can become tedious and error-prone for larger applications.
4. Bundle your JavaScript or CSS using a bundler
If your project requires features like dependency chaining or CSS pre-processing, you may want to consider [advanced asset management](#advanced-asset-management) alongside Propshaft.
Tools like [`jsbundling-rails`](https://github.com/rails/jsbundling-rails) integrates [Bun](https://bun.sh/), [esbuild](https://esbuild.github.io/), [rollup.js](https://rollupjs.org/), or [Webpack](https://webpack.js.org/) into your Rails application, while [`cssbundling-rails`](https://github.com/rails/cssbundling-rails) can be used to process stylesheets that use [Tailwind CSS](https://tailwindcss.com/), [Bootstrap](https://getbootstrap.com/), [Bulma](https://bulma.io/), [PostCSS](https://postcss.org/), or [Dart Sass](https://sass-lang.com/).
These tools complement Propshaft by handling the complex processing, while Propshaft efficiently organizes and serves the final assets.
### [2.2. Asset Organization](#asset-organization)
Propshaft organizes assets within the `app/assets` directory, which includes subdirectories like `images`, `javascripts`, and `stylesheets`. You can place your JavaScript, CSS, image files, and other assets into these directories, and Propshaft will manage them during the precompilation process.
You can also specify additional asset paths for Propshaft to search by modifying `config.assets.paths` in your `config/initializers/assets.rb` file. For example:
```
# Add additional assets to the asset load path.
Rails.application.config.assets.paths << Emoji.images_path
```
Propshaft will make all assets from the configured paths available for serving. During the precompilation process, Propshaft copies these assets into the `public/assets` directory, ensuring they are ready for production use.
Assets can be [referenced through their logical paths](#digested-assets-in-views) using helpers like `asset_path`, `image_tag`, `javascript_include_tag`, and other asset helper tags. After running [assets:precompile in production](#production), these logical references are automatically converted into their fingerprinted paths using the [`.manifest.json` file](#manifest-files).
It is possible to exclude certain directories from this process, you can read more about it in the [Fingerprinting section](#fingerprinting-versioning-with-digest-based-urls).
### [2.3. Fingerprinting: Versioning with digest-based URLs](#fingerprinting-versioning-with-digest-based-urls)
In Rails, asset versioning uses fingerprinting to add unique identifiers to asset filenames.
Fingerprinting is a technique that makes the name of a file dependent on its content. A digest of the file's content is generated and appended to the filename. This ensures that when the file content changes, its digestβand consequently its filenameβalso changes. This mechanism is crucial for caching assets effectively, as the browser will always load the updated version of an asset when its content changes, thereby improving performance. For static or infrequently changed content, this provides an easy way to tell whether two versions of a file are identical, even across different servers or deployment dates.
#### [2.3.1. Asset Digesting](#asset-digesting)
As mentioned in the [Asset Organization section](#asset-organization), in Propshaft, all assets from the paths configured in `config.assets.paths` are available for serving and will be copied into the `public/assets` directory.
When fingerprinted, an asset filename like `styles.css` is renamed to `styles-a1b2c3d4e5f6.css`. This ensures that if `styles.css` is updated, the filename changes as well, compelling the browser to download the latest version instead of using a potentially outdated cached copy.
#### [2.3.2. Manifest Files](#manifest-files)
In Propshaft, the `.manifest.json` file is automatically generated during the asset precompilation process. This file maps original asset filenames to their fingerprinted versions, ensuring proper cache invalidation and efficient asset management. Located in the `public/assets` directory, the `.manifest.json` file helps Rails resolve asset paths at runtime, allowing it to reference the correct fingerprinted files.
The `.manifest.json` includes entries for main assets like `application.js` and `application.css` as well as other files, such as images. Here's an example of what the JSON might look like:
```
{
"application.css": "application-6d58c9e6e3b5d4a7c9a8e3.css",
"application.js": "application-2d4b9f6c5a7c8e2b8d9e6.js",
"logo.png": "logo-f3e8c9b2a6e5d4c8.png",
"favicon.ico": "favicon-d6c8e5a9f3b2c7.ico"
}
```
When a filename is unique and based on its content, HTTP headers can be set to encourage caches everywhere (whether at CDNs, at ISPs, in networking equipment, or in web browsers) to keep their own copy of the content. When the content is updated, the fingerprint will change. This will cause the remote clients to request a new copy of the content. This is generally known as cache busting.
#### [2.3.3. Digested Assets in Views](#digested-assets-in-views)
You can reference digested assets in your views using standard Rails asset helpers like `asset_path`, `image_tag`, `javascript_include_tag`, `stylesheet_link_tag` and others.
For example, in your layout file, you can include a stylesheet like this:
```
<%= stylesheet_link_tag "application", media: "all" %>
```
If you're using the [`turbo-rails`](https://github.com/hotwired/turbo-rails) gem (which is included by default in Rails), you can include the `data-turbo-track` option. This causes Turbo to check if an asset has been updated and, if so, reload it into the page:
```
<%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
```
You can access images in the `app/assets/images` directory like this:
```
<%= image_tag "rails.png" %>
```
When the asset pipeline is enabled, Propshaft will serve this file. If a file exists at `public/assets/rails.png`, it will be served by the web server.
Alternatively, if you are using fingerprinted assets (e.g., `rails-f90d8a84c707a8dc923fca1ca1895ae8ed0a09237f6992015fef1e11be77c023.png`), Propshaft will also serve these correctly. The fingerprint is automatically applied during the precompilation process.
Images can be organized into subdirectories, and you can reference them by specifying the directory in the tag:
```
<%= image_tag "icons/rails.png" %>
```
Finally, you can reference an image in your CSS like:
```
background: url("/bg/pattern.svg");
```
Propshaft will automatically convert this to:
```
background: url("/assets/bg/pattern-2169cbef.svg");
```
If you're precompiling your assets (see [the Production section](#production)), linking to an asset that doesn't exist will raise an exception in the calling page. This includes linking to a blank string. Be careful when using `image_tag` and other helpers with user-supplied data. This ensures that the browser always fetches the correct version of the asset.
#### [2.3.4. Digested Assets in JavaScript](#digested-assets-in-javascript)
In JavaScript, you need to manually trigger the asset transformation using the `RAILS_ASSET_URL` macro. Hereβs an example:
```
export default class extends Controller {
init() {
this.img = RAILS_ASSET_URL("/icons/trash.svg");
}
}
```
This will transform into:
```
export default class extends Controller {
init() {
this.img = "/assets/icons/trash-54g9cbef.svg";
}
}
```
This ensures that the correct, digested file is used in your JavaScript code.
If youβre using bundlers like [Webpack](https://webpack.js.org/) or [esbuild](https://esbuild.github.io/), you should let the bundlers handle the digesting process. If Propshaft detects that a file already has a digest in the filename (e.g., `script-2169cbef.js`), it will skip digesting the file again to avoid unnecessary reprocessing.
For managing assets with [Import Maps](#importmap-rails), Propshaft ensures that assets referenced in the import map are appropriately handled and mapped to their digested paths during the precompilation process.
#### [2.3.5. Bypassing the Digest Step](#bypassing-the-digest-step)
If you need to reference files that refer to each otherβlike a JavaScript file and its source mapβand want to avoid the digesting process, you can pre-digest these files manually. Propshaft recognizes files with the pattern `-[digest].digested.js` as files that have already been digested and will preserve their stable file names.
#### [2.3.6. Excluding Directories from Digestion](#excluding-directories-from-digestion)
You can exclude certain directories from the precompilation and digestion process by adding them to `config.assets.excluded_paths`. This is useful if, for example, youβre using `app/assets/stylesheets` as input to a compiler like [Dart Sass](https://sass-lang.com/), and you donβt want these files to be part of the asset load path.
```
config.assets.excluded_paths = [Rails.root.join("app/assets/stylesheets")]
```
This will prevent the specified directories from being processed by Propshaft while still allowing them to be part of the precompilation process.
## [3. Working with Propshaft](#working-with-propshaft)
From Rails 8 onwards, Propshaft is included by default. To use Propshaft, you need to configure it properly and organize your assets in a way that Rails can serve them efficiently.
### [3.1. Setup](#setup)
Follow these steps for setting up Propshaft in your Rails application:
1. Create a new Rails application:
```
$ rails new app_name
```
2. Organize your assets:
Propshaft expects your assets to be in the `app/assets` directory. You can organize your assets into subdirectories like `app/assets/javascripts` for JavaScript files, `app/assets/stylesheets` for CSS files, and `app/assets/images` for images.
For example, you can create a new JavaScript file in `app/assets/javascripts`:
```
// app/assets/javascripts/main.js
console.log("Hello, world!");
```
and a new CSS file in `app/assets/stylesheets`:
```
/* app/assets/stylesheets/main.css */
body {
background-color: red;
}
```
3. Link assets in your application layout
In your application layout file (usually `app/views/layouts/application.html.erb`), you can include your assets using the `stylesheet_link_tag` and `javascript_include_tag` helpers:
```
MyApp
<%= stylesheet_link_tag "main" %>
<%= yield %>
<%= javascript_include_tag "main" %>
```
This layout includes the `main.css` stylesheet and `main.js` JavaScript file in your application.
4. Start the Rails server:
```
$ bin/rails server
```
5. Preview your application:
Open your web browser and navigate to `http://localhost:3000`. You should see your Rails application with the included assets.
### [3.2. Development](#development)
Rails and Propshaft are configured differently in development than in production, to allow rapid iteration without manual intervention.
#### [3.2.1. No Caching](#no-caching)
In development, Rails is configured to bypass asset caching. This means that when you modify assets (e.g., CSS, JavaScript), Rails will serve the most up-to-date version directly from the file system. There's no need to worry about versioning or file renaming because caching is skipped entirely. Browsers will automatically pull in the latest version each time you reload the page.
#### [3.2.2. Automatic Reloading of Assets](#automatic-reloading-of-assets)
When using Propshaft on its own, it automatically checks for updates to assets like JavaScript, CSS, or images with every request. This means you can edit these files, reload the browser, and instantly see the changes without needing to restart the Rails server.
When using JavaScript bundlers such as [esbuild](https://esbuild.github.io/) or [Webpack](https://webpack.js.org/) alongside Propshaft, the workflow combines both tools effectively:
* The bundler watches for changes in your JavaScript and CSS files, compiles them into the appropriate build directory, and keeps the files up to date.
* Propshaft ensures that the latest compiled assets are served to the browser whenever a request is made.
For these setups, running `./bin/dev` starts both the Rails server and the asset bundler's development server.
In either case, Propshaft ensures that changes to your assets are reflected as soon as the browser page is reloaded, without requiring a server restart.
#### [3.2.3. Improving Performance with File Watchers](#improving-performance-with-file-watchers)
In development, Propshaft checks if any assets have been updated before each request, using the application's file watcher (by default, `ActiveSupport::FileUpdateChecker`). If you have a large number of assets, you can improve performance by using the `listen` gem and configuring the following setting in `config/environments/development.rb`:
```
config.file_watcher = ActiveSupport::EventedFileUpdateChecker
```
This will reduce the overhead of checking for file updates and improve performance during development.
### [3.3. Production](#production)
In production, Rails serves assets with caching enabled to optimize performance, ensuring that your application can handle high traffic efficiently.
#### [3.3.1. Asset Caching and Versioning in Production](#asset-caching-and-versioning-in-production)
As mentioned in the [Fingerprinting section](#fingerprinting-versioning-with-digest-based-urls) when the file content changes, its digest also changes, thus the browser uses the updated version of the file. Whereas, if the content remains the same, the browser will use the cached version.
#### [3.3.2. Precompiling Assets](#precompiling-assets)
In production, precompilation is typically run during deployment to ensure that the latest versions of the assets are served. Propshaft was explicitly not designed to provide full transpiler capabilities. However, it does offer an input -> output compiler setup that by default is used to translate `url(asset)` function calls in CSS to `url(digested-asset)` instead and source mapping comments likewise.
To manually run precompilation you can use the following command:
```
$ RAILS_ENV=production rails assets:precompile
```
After doing this, all assets in the load path will be copied (or compiled when using [advanced asset management](#advanced-asset-management)) in the precompilation step and stamped with a digest hash.
Additionally, you can set `ENV["SECRET_KEY_BASE_DUMMY"]` to trigger the use of a randomly generated `secret_key_base` thatβs stored in a temporary file. This is useful when precompiling assets for production as part of a build step that otherwise does not need access to the production secrets.
```
$ RAILS_ENV=production SECRET_KEY_BASE_DUMMY=1 rails assets:precompile
```
By default, assets are served from the `/assets` directory.
Running the precompile command in development generates a marker file named `.manifest.json`, which tells the application that it can serve the compiled assets. As a result, any changes you make to your source assets won't be reflected in the browser until the precompiled assets are updated. If your assets stop updating in development mode, the solution is to remove the `.manifest.json` file located in `public/assets/`. You can use the `rails assets:clobber` command to delete all your precompiled assets and the `.manifest.json` file. This will force Rails to recompile the assets on the fly, reflecting the latest changes.
Always ensure that the expected compiled filenames end with `.js` or `.css`.
##### [3.3.2.1. Far-future Expires Header](#far-future-expires-header)
Precompiled assets exist on the file system and are served directly by your web server. They do not have far-future headers by default, so to get the benefit of fingerprinting you'll have to update your server configuration to add those headers.
For Apache:
```
# The Expires* directives require the Apache module
# `mod_expires` to be enabled.
# Use of ETag is discouraged when Last-Modified is present
Header unset ETag
FileETag None
# RFC says only cache for 1 year
ExpiresActive On
ExpiresDefault "access plus 1 year"
```
For NGINX:
```
location ~ ^/assets/ {
expires 1y;
add_header Cache-Control public;
add_header ETag "";
}
```
#### [3.3.3. CDNs](#cdns)
CDN stands for [Content Delivery Network](https://en.wikipedia.org/wiki/Content_delivery_network), they are primarily designed to cache assets all over the world so that when a browser requests the asset, a cached copy will be geographically close to that browser. If you are serving assets directly from your Rails server in production, the best practice is to use a CDN in front of your application.
A common pattern for using a CDN is to set your production application as the "origin" server. This means when a browser requests an asset from the CDN and there is a cache miss, it will instead source the file from your server and then cache it. For example if you are running a Rails application on `example.com` and have a CDN configured at `mycdnsubdomain.fictional-cdn.com`, then when a request is made to `mycdnsubdomain.fictional-cdn.com/assets/smile.png`, the CDN will query your server once at `example.com/assets/smile.png` and cache the request. The next request to the CDN that comes in to the same URL will hit the cached copy. When the CDN can serve an asset directly the request never touches your Rails server. Since the assets from a CDN are geographically closer to the browser, the request is faster, and since your server doesn't need to spend time serving assets, it can focus on serving application code.
##### [3.3.3.1. Set up a CDN to Serve Static Assets](#set-up-a-cdn-to-serve-static-assets)
To set up CDN, your application needs to be running in production on the internet at a publicly available URL, for example `example.com`. Next you'll need to sign up for a CDN service from a cloud hosting provider. When you do this you need to configure the "origin" of the CDN to point back at your website `example.com`. Check your provider for documentation on configuring the origin server.
The CDN you provisioned should give you a custom subdomain for your application such as `mycdnsubdomain.fictional-cdn.com` (note fictional-cdn.com is not a valid CDN provider at the time of this writing). Now that you have configured your CDN server, you need to tell browsers to use your CDN to grab assets instead of your Rails server directly. You can do this by configuring Rails to set your CDN as the asset host instead of using a relative path. To set your asset host in Rails, you need to set [`config.asset_host`](configuring.html#config-asset-host) in `config/environments/production.rb`:
```
config.asset_host = "mycdnsubdomain.fictional-cdn.com"
```
You only need to provide the "host", this is the subdomain and root domain, you do not need to specify a protocol or "scheme" such as `http://` or `https://`. When a web page is requested, the protocol in the link to your asset that is generated will match how the webpage is accessed by default.
You can also set this value through an [environment variable](https://en.wikipedia.org/wiki/Environment_variable) to make running a staging copy of your site easier:
```
config.asset_host = ENV["CDN_HOST"]
```
You would need to set `CDN_HOST` on your server to `mycdnsubdomain .fictional-cdn.com` for this to work.
Once you have configured your server and your CDN, asset paths from helpers such as:
```
<%= asset_path('smile.png') %>
```
Will be rendered as full CDN URLs like `http://mycdnsubdomain.fictional-cdn.com/assets/smile.png` (digest omitted for readability).
If the CDN has a copy of `smile.png`, it will serve it to the browser, and the origin server won't even know it was requested. If the CDN does not have a copy, it will try to find it at the "origin" `example.com/assets/smile.png`, and then store it for future use.
If you want to serve only some assets from your CDN, you can use custom `:host` option for your asset helper, which overwrites the value set in [`config.action_controller.asset_host`](configuring.html#config-action-controller-asset-host).
```
<%= asset_path 'image.png', host: 'mycdnsubdomain.fictional-cdn.com' %>
```
##### [3.3.3.2. Customize CDN Caching Behavior](#customize-cdn-caching-behavior)
A CDN works by caching content. If the CDN has stale or bad content, then it is hurting rather than helping your application. The purpose of this section is to describe general caching behavior of most CDNs. Your specific provider may behave slightly differently.
**CDN Request Caching**
While a CDN is described as being good for caching assets, it actually caches the entire request. This includes the body of the asset as well as any headers. The most important one being `Cache-Control`, which tells the CDN (and web browsers) how to cache contents. This means that if someone requests an asset that does not exist, such as `/assets/i-dont-exist.png`, and your Rails application returns a 404, then your CDN will likely cache the 404 page if a valid `Cache-Control` header is present.
**CDN Header Debugging**
One way to check the headers are cached properly in your CDN is by using [curl](https://explainshell.com/explain?cmd=curl+-I+http%3A%2F%2Fwww.example.com). You can request the headers from both your server and your CDN to verify they are the same:
```
$ curl -I http://www.example/assets/application-
d0e099e021c95eb0de3615fd1d8c4d83.css
HTTP/1.1 200 OK
Server: Cowboy
Date: Sun, 24 Aug 2014 20:27:50 GMT
Connection: keep-alive
Last-Modified: Thu, 08 May 2014 01:24:14 GMT
Content-Type: text/css
Cache-Control: public, max-age=2592000
Content-Length: 126560
Via: 1.1 vegur
```
Versus the CDN copy:
```
$ curl -I http://mycdnsubdomain.fictional-cdn.com/application-
d0e099e021c95eb0de3615fd1d8c4d83.css
HTTP/1.1 200 OK Server: Cowboy Last-
Modified: Thu, 08 May 2014 01:24:14 GMT Content-Type: text/css
Cache-Control:
public, max-age=2592000
Via: 1.1 vegur
Content-Length: 126560
Accept-Ranges:
bytes
Date: Sun, 24 Aug 2014 20:28:45 GMT
Via: 1.1 varnish
Age: 885814
Connection: keep-alive
X-Served-By: cache-dfw1828-DFW
X-Cache: HIT
X-Cache-Hits:
68
X-Timer: S1408912125.211638212,VS0,VE0
```
Check your CDN documentation for any additional information they may provide such as `X-Cache` or for any additional headers they may add.
**CDNs and the Cache-Control Header**
The [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header describes how a request can be cached. When no CDN is used, a browser will use this information to cache contents. This is very helpful for assets that are not modified so that a browser does not need to re-download a website's CSS or JavaScript on every request. Generally we want our Rails server to tell our CDN (and browser) that the asset is "public". That means any cache can store the request. Also we commonly want to set `max-age` which is how long the cache will store the object before invalidating the cache. The `max-age` value is set to seconds with a maximum possible value of `31536000`, which is one year. You can do this in your Rails application by setting
```
config.public_file_server.headers = {
"cache-control" => "public, max-age=31536000"
}
```
Now when your application serves an asset in production, the CDN will store the asset for up to a year. Since most CDNs also cache headers of the request, this `Cache-Control` will be passed along to all future browsers seeking this asset. The browser then knows that it can store this asset for a very long time before needing to re-request it.
**CDNs and URL-based Cache Invalidation**
Most CDNs will cache contents of an asset based on the complete URL. This means that a request to
```
http://mycdnsubdomain.fictional-cdn.com/assets/smile-123.png
```
Will be a completely different cache from
```
http://mycdnsubdomain.fictional-cdn.com/assets/smile.png
```
If you want to set far future `max-age` in your `Cache-Control` (and you do), then make sure when you change your assets that your cache is invalidated. For example when changing the smiley face in an image from yellow to blue, you want all visitors of your site to get the new blue face. When using a CDN with the Rails asset pipeline `config.assets.digest` is set to true by default so that each asset will have a different file name when it is changed. This way you don't have to ever manually invalidate any items in your cache. By using a different unique asset name instead, your users get the latest asset.
## [4. Sprockets to Propshaft](#sprockets-to-propshaft)
### [4.1. Evolution of Asset Management Techniques](#evolution-of-asset-management-techniques)
Within the last few years, the evolution of the web has led to significant changes that have influenced how assets are managed in web applications. These include:
1. **Browser Support**: Modern browsers have improved support for new features and syntax, reducing the need for transpilation and polyfills.
2. **HTTP/2**: The introduction of HTTP/2 has made it easier to serve multiple files in parallel, reducing the need for bundling.
3. **ES6+**: Modern JavaScript syntax (ES6+) is supported by most modern browsers, reducing the need for transpilation.
Therefore, the asset pipeline powered by Propshaft, no longer includes transpilation, bundling, or compression by default. However, fingerprinting still remains an integral part. You can read more about the evolution of asset management techniques and how they directed the change from Sprockets to Propshaft below.
#### [4.1.1. Transpilation β](#transpilation-β)
Transpilation involves converting code from one language or format to another.
For example, converting TypeScript to JavaScript.
```
const greet = (name: string): void => {
console.log(`Hello, ${name}!`);
};
```
After transpilation, this code becomes:
```
const greet = (name) => {
console.log(`Hello, ${name}!`);
};
```
In the past, pre-processors like [Sass](https://sass-lang.com/) and [Less](https://lesscss.org/) were essential for CSS features such as variables and nesting. Today, modern CSS supports these natively, reducing the need for transpilation.
#### [4.1.2. Bundling β](#bundling-β)
Bundling combines multiple files into one to reduce the number of HTTP requests a browser needs to make to render a page.
For example, if your application has three JavaScript files:
* menu.js
* cart.js
* checkout.js
Bundling will merge these into a single application.js file.
```
// app/javascript/application.js
// Contents of menu.js, cart.js, and checkout.js are combined here
```
This was crucial with HTTP/1.1, which limited 6-8 simultaneous connections per domain. With HTTP/2, browsers fetch multiple files in parallel, making bundling less critical for modern applications.
#### [4.1.3. Compression β](#compression-β)
Compression encodes files in a more efficient format to reduce their size further when delivered to users. A common technique is [Gzip compression](https://en.wikipedia.org/wiki/Gzip).
For example, a CSS file that's 200KB may compress to just 50KB when Gzipped. Browsers automatically decompress such files upon receipt, saving bandwidth and improving speed.
However, with CDNs automatically compressing assets, the need for manual compression has decreased.
### [4.2. Sprockets vs. Propshaft](#sprockets-vs-propshaft)
#### [4.2.1. Load Order](#load-order)
In Sprockets, you could link files together to ensure they loaded in the correct order. For example, a main JavaScript file that depended on other files would automatically have its dependencies managed by Sprockets, ensuring everything loaded in the right sequence. Propshaft, on the other hand, does not automatically handle these dependencies, and instead [lets you manage the asset load order manually](#asset-load-order).
#### [4.2.2. Versioning](#versioning)
Sprockets simplifies asset fingerprinting by appending a hash to filenames whenever assets are updated, ensuring proper cache invalidation. With Propshaft, youβll need to handle certain aspects manually. For example, while asset fingerprinting works, you might need to use a bundler or trigger transformations manually for JavaScript files to ensure filenames are updated correctly. Read more about [fingerprinting in Propshaft](#fingerprinting-versioning-with-digest-based-urls).
#### [4.2.3. Precompilation](#precompilation)
Sprockets processed assets that were explicitly included in a bundle. In contrast, Propshaft automatically processes all assets located in the specified paths, including images, stylesheets, JavaScript files, and more, without requiring explicit bundling. Read more about [asset digesting](#asset-digesting).
### [4.3. Migration Steps](#migration-steps)
Propshaft is intentionally simpler than [Sprockets](https://github.com/rails/sprockets-rails), which may make migrating from Sprockets a fair amount of work. This is especially true if you rely on Sprockets for tasks like transpiling [TypeScript](https://www.typescriptlang.org/) or [Sass](https://sass-lang.com/), or if you're using gems that provide this functionality. In such cases, you'll either need to stop transpiling or switch to a Node.js-based transpiler, such as those provided by [`jsbundling-rails`](https://github.com/rails/jsbundling-rails) or [`cssbundling-rails`](https://github.com/rails/cssbundling-rails). Read more about these in the [Advanced Asset Management section](#advanced-asset-management).
However, if you're already using a Node-based setup to bundle JavaScript and CSS, Propshaft should integrate smoothly into your workflow. Since you wonβt need an additional tool for bundling or transpiling, Propshaft will primarily handle asset digesting and serving.
Some key steps in the migration include:
1. Remove some gems using the following:
```
bundle remove sprockets
bundle remove sprockets-rails
bundle remove sass-rails
```
2. Delete the `config/assets.rb` and `assets/config/manifest.js` files from your project.
3. If you've already upgraded to Rails 8, then Propshaft is already included in your application. Otherwise, install it using `bundle add propshaft`.
4. Remove the `config.assets.paths << Rails.root.join('app', 'assets')` line from your `application.rb` file.
5. Migrate asset helpers by replacing all instances of asset helpers in your CSS files (e.g., `image_url`) with standard `url()` functions, keeping in mind that Propshaft utilizes relative paths. For example, `image_url("logo.png")` may become `url("/logo.png")`.
6. If you're relying on Sprockets for transpiling, you'll need to switch to a Node-based transpiler like Webpack, esbuild, or Vite. You can use the `jsbundling-rails` and `cssbundling-rails` gems to integrate these tools into your Rails application.
For more information, you can read the [detailed guide on how to migrate from Sprockets to Propshaft](https://github.com/rails/propshaft/blob/main/UPGRADING.md).
## [5. Advanced Asset Management](#advanced-asset-management)
Over the years, there have been multiple default approaches for handling assets, and as the web evolved, we began to see more JavaScript-heavy applications. In The Rails Doctrine we believe that [The Menu Is Omakase](https://rubyonrails.org/doctrine#omakase), so Propshaft focuses on delivering a production-ready setup with modern browsers by default.
There is no one-size-fits-all solution for the various JavaScript and CSS frameworks and extensions available. However, there are other bundling libraries in the Rails ecosystem that should empower you in cases where the default setup isn't enough.
### [5.1. `jsbundling-rails`](#jsbundling-rails)
[`jsbundling-rails`](https://github.com/rails/jsbundling-rails) is a gem that integrates modern JavaScript bundlers into your Rails application. It allows you to manage and bundle JavaScript assets with tools like [Bun](https://bun.sh), [esbuild](https://esbuild.github.io/), [rollup.js](https://rollupjs.org/), or [Webpack](https://webpack.js.org/), offering a runtime-dependent approach for developers seeking flexibility and performance.
#### [5.1.1. How `jsbundling-rails` Works](#how-jsbundling-rails-works)
1. After installation, it sets up your Rails app to use your chosen JavaScript bundler.
2. It creates a `build` script in your `package.json` file to compile your JavaScript assets.
3. During development, the `build:watch` script ensures live updates to your assets as you make changes.
4. In production, the gem ensures that JavaScript is built and included during the precompilation step, reducing manual intervention. It hooks into Rails' `assets:precompile` task to build JavaScript for all entry points during deployment. This integration ensures that your JavaScript is production-ready with minimal configuration.
The gem automatically handles entry-point discovery - identifying the primary JavaScript files to bundle by following Rails conventions, typically looking in directories like `app/javascript/` and configuration. By adhering to Rails conventions, `jsbundling-rails` simplifies the process of integrating complex JavaScript workflows into Rails projects.
#### [5.1.2. When Should You Use It?](#jsbundling-rails-when-should-you-use-it-questionmark)
`jsbundling-rails` is ideal for Rails applications that:
* Require modern JavaScript features like ES6+, TypeScript, or JSX.
* Need to leverage bundler-specific optimizations like tree-shaking, code splitting, or minification.
* Use `Propshaft` for asset management and need a reliable way to integrate precompiled JavaScript with the broader Rails asset pipeline.
* Utilize libraries or frameworks that depend on a build step. For example, projects requiring transpilationβsuch as those using [Babel](https://babeljs.io/), [TypeScript](https://www.typescriptlang.org/), or React JSXβbenefit greatly from `jsbundling-rails`. These tools rely on a build step, which the gem seamlessly supports.
By integrating with Rails tools like `Propshaft` and simplifying JavaScript workflows, `jsbundling-rails` allows you to build rich, dynamic front-ends while staying productive and adhering to Rails conventions.
### [5.2. `cssbundling-rails`](#cssbundling-rails)
[`cssbundling-rails`](https://github.com/rails/cssbundling-rails) integrates modern CSS frameworks and tools into your Rails application. It allows you to bundle and process your stylesheets. Once processed, the resulting CSS is delivered via the Rails asset pipeline.
#### [5.2.1. How `cssbundling-rails` Works](#how-cssbundling-rails-works)
1. After installation, it sets up your Rails app to use your chosen CSS framework or processor.
2. It creates a `build:css` script in your `package.json` file to compile your stylesheets.
3. During development, a `build:css --watch` task ensures live updates to your CSS as you make changes, providing a smooth and responsive workflow.
4. In production, the gem ensures your stylesheets are compiled and ready for deployment. During the `assets:precompile` step, it installs all `package.json` dependencies via `bun`, `yarn`, `pnpm` or `npm` and runs the `build:css` task to process your stylesheet entry points. The resulting CSS output is then digested by the asset pipeline and copied into the `public/assets` directory, just like other asset pipeline files.
This integration simplifies the process of preparing production-ready styles while ensuring all your CSS is managed and processed efficiently.
#### [5.2.2. When Should You Use It?](#cssbundling-rails-when-should-you-use-it-questionmark)
`cssbundling-rails` is ideal for Rails applications that:
* Use CSS frameworks like [Tailwind CSS](https://tailwindcss.com/), [Bootstrap](https://getbootstrap.com/), or [Bulma](https://bulma.io/) that require processing during development or deployment.
* Need advanced CSS capabilities such as custom preprocessing with [PostCSS](https://postcss.org/) or [Dart Sass](https://sass-lang.com/) plugins.
* Require seamless integration of processed CSS into the Rails asset pipeline.
* Benefit from live updates to stylesheets during development with minimal manual intervention.
**NOTE**: Unlike [`dartsass-rails`](https://github.com/rails/dartsass-rails) or [`tailwindcss-rails`](https://github.com/rails/tailwindcss-rails), which use standalone versions of [Dart Sass](https://sass-lang.com/) and [Tailwind CSS](https://tailwindcss.com/), `cssbundling-rails` introduces a Node.js dependency. This makes it a good choice for applications already relying on Node for JavaScript processing with gems like `jsbundling-rails`. However, if you're using [`importmap-rails`](https://github.com/rails/importmap-rails) for JavaScript and prefer to avoid Node.js, standalone alternatives like [`dartsass-rails`](https://github.com/rails/dartsass-rails) or [`tailwindcss-rails`](https://github.com/rails/tailwindcss-rails) offer a simpler setup.
By integrating modern CSS workflows, automating production builds, and leveraging the Rails asset pipeline, `cssbundling-rails` enables developers to efficiently manage and deliver dynamic styles.
### [5.3. `tailwindcss-rails`](#tailwindcss-rails)
[`tailwindcss-rails`](https://github.com/rails/tailwindcss-rails) is a wrapper gem that integrates [Tailwind CSS](https://tailwindcss.com/) into your Rails application. By bundling Tailwind CSS with a [standalone executable](https://tailwindcss.com/blog/standalone-cli), it eliminates the need for Node.js or additional JavaScript dependencies. This makes it a lightweight and efficient solution for styling Rails applications.
#### [5.3.1. How `tailwindcss-rails` Works](#how-tailwindcss-rails-works)
1. When installed, by providing `--css tailwind` to the `rails new` command, the gem generates a `tailwind.config.js` file for customizing your Tailwind setup and a `stylesheets/application.tailwind.css` file for managing your CSS entry points.
2. Instead of relying on Node.js, the gem uses a precompiled Tailwind CSS binary. This standalone approach allows you to process and compile CSS without adding a JavaScript runtime to your project.
3. During development, changes to your Tailwind configuration or CSS files are automatically detected and processed. The gem rebuilds your stylesheets and provides a `watch` process to automatically generate Tailwind output in development.
4. In production, the gem hooks into the `assets:precompile` task. It processes your Tailwind CSS files and generates optimized, production-ready stylesheets, which are then included in the asset pipeline. The output is fingerprinted and cached for efficient delivery.
#### [5.3.2. When Should You Use It?](#tailwindcss-rails-when-should-you-use-it-questionmark)
`tailwindcss-rails` is ideal for Rails applications that:
* Want to use [Tailwind CSS](https://tailwindcss.com/) without introducing a Node.js dependency or JavaScript build tools.
* Require a minimal setup for managing utility-first CSS frameworks.
* Need to take advantage of Tailwind's powerful features like custom themes, variants, and plugins without complex configuration.
The gem works seamlessly with Rails' asset pipeline tools, like Propshaft, ensuring that your CSS is preprocessed, digested, and efficiently served in production environments.
### [5.4. `importmap-rails`](#importmap-rails)
[`importmap-rails`](https://github.com/rails/importmap-rails) enables a Node.js-free approach to managing JavaScript in Rails applications. It leverages modern browser support for [ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to load JavaScript directly in the browser without requiring bundling or transpilation. This approach aligns with Rails' commitment to simplicity and convention over configuration.
#### [5.4.1. How `importmap-rails` Works](#how-importmap-rails-works)
* After installation, `importmap-rails` configures your Rails app to use ``. Read more about XSS and injection later on.
* The attacker lures the victim to the infected page with the JavaScript code. By viewing the page, the victim's browser will change the session ID to the trap session ID.
* As the new trap session is unused, the web application will require the user to authenticate.
* From now on, the victim and the attacker will co-use the web application with the same session: The session became valid and the victim didn't notice the attack.
### [3.7. Session Fixation - Countermeasures](#session-fixation-countermeasures)
*One line of code will protect you from session fixation.*
The most effective countermeasure is to *issue a new session identifier* and declare the old one invalid after a successful login. That way, an attacker cannot use the fixed session identifier. This is a good countermeasure against session hijacking, as well. Here is how to create a new session in Rails:
```
reset_session
```
If you use the popular [Devise](https://rubygems.org/gems/devise) gem for user management, it will automatically expire sessions on sign in and sign out for you. If you roll your own, remember to expire the session after your sign in action (when the session is created). This will remove values from the session, therefore *you will have to transfer them to the new session*.
Another countermeasure is to *save user-specific properties in the session*, verify them every time a request comes in, and deny access, if the information does not match. Such properties could be the remote IP address or the user agent (the web browser name), though the latter is less user-specific. When saving the IP address, you have to bear in mind that there are Internet service providers or large organizations that put their users behind proxies. *These might change over the course of a session*, so these users will not be able to use your application, or only in a limited way.
### [3.8. Session Expiry](#session-expiry)
*Sessions that never expire extend the time-frame for attacks such as cross-site request forgery (CSRF), session hijacking, and session fixation.*
One possibility is to set the expiry time-stamp of the cookie with the session ID. However the client can edit cookies that are stored in the web browser so expiring sessions on the server is safer. Here is an example of how to *expire sessions in a database table*. Call `Session.sweep(20.minutes)` to expire sessions that were used longer than 20 minutes ago.
```
class Session < ApplicationRecord
def self.sweep(time = 1.hour)
where(updated_at: ...time.ago).delete_all
end
end
```
The section about session fixation introduced the problem of maintained sessions. An attacker maintaining a session every five minutes can keep the session alive forever, although you are expiring sessions. A simple solution for this would be to add a `created_at` column to the sessions table. Now you can delete sessions that were created a long time ago. Use this line in the sweep method above:
```
where(updated_at: ...time.ago).or(where(created_at: ...2.days.ago)).delete_all
```
## [4. Cross-Site Request Forgery (CSRF)](#cross-site-request-forgery-csrf)
This attack method works by including malicious code or a link in a page that accesses a web application that the user is believed to have authenticated. If the session for that web application has not timed out, an attacker may execute unauthorized commands.
In the [session chapter](#sessions) you have learned that most Rails applications use cookie-based sessions. Either they store the session ID in the cookie and have a server-side session hash, or the entire session hash is on the client-side. In either case the browser will automatically send along the cookie on every request to a domain, if it can find a cookie for that domain. The controversial point is that if the request comes from a site of a different domain, it will also send the cookie. Let's start with an example:
* Bob browses a message board and views a post from a hacker where there is a crafted HTML image element. The element references a command in Bob's project management application, rather than an image file: ``
* Bob's session at `www.webapp.com` is still alive, because he didn't log out a few minutes ago.
* By viewing the post, the browser finds an image tag. It tries to load the suspected image from `www.webapp.com`. As explained before, it will also send along the cookie with the valid session ID.
* The web application at `www.webapp.com` verifies the user information in the corresponding session hash and destroys the project with the ID 1. It then returns a result page which is an unexpected result for the browser, so it will not display the image.
* Bob doesn't notice the attack - but a few days later he finds out that project number one is gone.
It is important to notice that the actual crafted image or link doesn't necessarily have to be situated in the web application's domain, it can be anywhere - in a forum, blog post, or email.
CSRF appears very rarely in CVE (Common Vulnerabilities and Exposures) - less than 0.1% in 2006 - but it really is a 'sleeping giant' \[Grossman]. This is in stark contrast to the results in many security contract works - *CSRF is an important security issue*.
### [4.1. CSRF Countermeasures](#csrf-countermeasures)
*First, as is required by the W3C, use GET and POST appropriately. Secondly, a security token in non-GET requests will protect your application from CSRF.*
#### [4.1.1. Use GET and POST Appropriately](#use-get-and-post-appropriately)
The HTTP protocol basically provides two main types of requests - GET and POST (DELETE, PUT, and PATCH should be used like POST). The World Wide Web Consortium (W3C) provides a checklist for choosing HTTP GET or POST:
**Use GET if:**
* The interaction is more *like a question* (i.e., it is a safe operation such as a query, read operation, or lookup).
**Use POST if:**
* The interaction is more *like an order*, or
* The interaction *changes the state* of the resource in a way that the user would perceive (e.g., a subscription to a service), or
* The user is *held accountable for the results* of the interaction.
If your web application is RESTful, you might be used to additional HTTP verbs, such as PATCH, PUT, or DELETE. Some legacy web browsers, however, do not support them - only GET and POST. Rails uses a hidden `_method` field to handle these cases.
*POST requests can be sent automatically, too*. In this example, the link [www.harmless.com](http://www.harmless.com) is shown as the destination in the browser's status bar. But it has actually dynamically created a new form that sends a POST request.
```
To the harmless survey
```
Or the attacker places the code into the onmouseover event handler of an image:
```
```
There are many other possibilities, like using a `
```
This JavaScript code will simply display an alert box. The next examples do exactly the same, only in very uncommon places:
```
```
##### [7.3.2.1. Cookie Theft](#cookie-theft)
These examples don't do any harm so far, so let's see how an attacker can steal the user's cookie (and thus hijack the user's session). In JavaScript you can use the `document.cookie` property to read and write the document's cookie. JavaScript enforces the same origin policy, that means a script from one domain cannot access cookies of another domain. The `document.cookie` property holds the cookie of the originating web server. However, you can read and write this property, if you embed the code directly in the HTML document (as it happens with XSS). Inject this anywhere in your web application to see your own cookie on the result page:
```
```
For an attacker, of course, this is not useful, as the victim will see their own cookie. The next example will try to load an image from the URL plus the cookie. Of course this URL does not exist, so the browser displays nothing. But the attacker can review their web server's access log files to see the victim's cookie.
```
```
The log files on [www.attacker.com](http://www.attacker.com) will read like this:
```
GET http://www.attacker.com/_app_session=836c1c25278e5b321d6bea4f19cb57e2
```
You can mitigate these attacks (in the obvious way) by adding the **httpOnly** flag to cookies, so that `document.cookie` may not be read by JavaScript. HTTP only cookies can be used from IE v6.SP1, Firefox v2.0.0.5, Opera 9.5, Safari 4, and Chrome 1.0.154 onwards. But other, older browsers (such as WebTV and IE 5.5 on Mac) can actually cause the page to fail to load. Be warned that cookies [will still be visible using Ajax](https://owasp.org/www-community/HttpOnly#browsers-supporting-httponly), though.
##### [7.3.2.2. Defacement](#defacement)
With web page defacement, an attacker can do a lot of things, for example, present false information or lure the victim to the attacker's website to steal the cookie, login credentials, or other sensitive data. The most popular way is to include code from external sources by iframes:
```
```
This loads arbitrary HTML and/or JavaScript from an external source and embeds it as part of the site. This `iframe` is taken from an actual attack on legitimate Italian sites using the [Mpack attack framework](https://isc.sans.edu/diary/MPack+Analysis/3015). Mpack tries to install malicious software through security holes in the web browser - very successfully, 50% of the attacks succeed.
A more specialized attack could overlap the entire website or display a login form, which looks the same as the site's original, but transmits the username and password to the attacker's site. Or it could use CSS and/or JavaScript to hide a legitimate link in the web application, and display another one in its place, which redirects to a fake website.
Reflected injection attacks are those where the payload is not stored to present it to the victim later on, but is included in the URL. Especially search forms fail to escape the search string. The following link presented a page which stated that "George Bush appointed a 9 year old boy to be the chairperson...":
```
http://www.cbsnews.com/stories/2002/02/15/weather_local/main501644.shtml?zipcode=1-->
Hello World
<%= flash[:notice] %>
```
To internationalize this code, replace the strings with calls to Rails' `#t` helper using translation keys. The heading is translated in the view, while the flash message is translated where it is set in the controller:
```
# app/controllers/home_controller.rb
class HomeController < ApplicationController
def index
flash[:notice] = t("home_flash")
end
end
```
```
<%= t("home_title") %>
<%= flash[:notice] %>
```
Now, when this view is rendered, it will show an error message indicating that the translations for the keys `"home_title"` and `"home_flash"` are missing.
```
Home Title
Translation missing: en.home_flash
```
Now add the translations to your locale files:
```
# config/locales/en.yml
en:
home_title: Hello world!
home_flash: Hello flash!
```
```
# config/locales/es.yml
es:
home_title: Β‘Hola mundo!
home_flash: Β‘Hola flash!
```
With the default locale, the page renders the English strings.
```
Hello world!
Hello flash!
```
If the default locale is set to the Spanish locale:
```
# config/application.rb
config.i18n.default_locale = :es
```
the response renders the Spanish strings:
```
Β‘Hola mundo!
Β‘Hola flash!
```
You need to restart the server when you add new locale files.
### [3.4. Passing Variables to Translations](#passing-variables-to-translations)
One key consideration for successfully internationalizing an application is to avoid making incorrect assumptions about grammar rules when abstracting localized code. Grammar rules that seem fundamental in one locale may not hold true in another.
Improper abstraction is shown in the following example, where assumptions are made about the ordering of the different parts of the translation.
```
<%= "#{t('currency')}#{@product.price}" %>
```
```
# config/locales/nl.yml
nl:
currency: "β¬ "
```
```
# config/locales/es.yml
es:
currency: "β¬ "
```
If the productβs price is 100, Dutch might want `"β¬ 100"` while Spanish might want `"100 β¬"`, but this abstraction produces `"β¬ 100"` for both locales.
To create proper abstraction, the I18n gem ships with a feature called variable interpolation that allows you to use variables in translation definitions and pass the values for these variables to the translation method.
Proper abstraction is shown in the following example:
```
<%= t('product_price', price: @product.price) %>
```
```
# config/locales/nl.yml
nl:
product_price: "β¬ %{price}"
```
```
# config/locales/es.yml
es:
product_price: "%{price} β¬"
```
All grammatical and punctuation decisions are made in the definition itself, so the abstraction can give a proper translation.
```
I18n.t("product_price", price: 100, locale: :nl)
# => "β¬ 100"
I18n.t("product_price", price: 100, locale: :es)
# => "100 β¬"
```
Rails provides helpers such as [`number_to_currency`](https://api.rubyonrails.org/v8.1.4/classes/ActionView/Helpers/NumberHelper.html#method-i-number_to_currency) for localizing numbers and currency values.
The `default` and `scope` keywords are reserved and can't be used as variable names. If used, an `I18n::ReservedInterpolationKey` exception is raised. If a translation expects an interpolation variable, but this has not been passed to `#translate`, an `I18n::MissingInterpolationArgument` exception is raised.
### [3.5. Adding Date/Time Formats](#adding-date-time-formats)
To localize the time format, you can pass the `Time` object to `I18n.l` or, preferably, use Rails' `#l` helper. You can pick a format by passing the `:format` option.
```
<%= t("home_title") %>
<%= flash[:notice] %>
<%= l(Time.now, format: :short) %>
```
For example, you can define a custom short time format in a locale file:
```
# config/locales/es.yml
es:
time:
formats:
short: "%H:%M"
```
Then `l(Time.current, format: :short, locale: :es)` uses that format for the Spanish locale.
Rails also provides [`relative_time_in_words`](https://api.rubyonrails.org/v8.1.4/classes/ActionView/Helpers/DateHelper.html#method-i-relative_time_in_words) for a localized past/future phrase rather than a formatted timestamp:
```
```
This renders phrases such as:
```
in 3 minutes
less than 20 seconds ago
```
By default, this looks up translations in the `datetime.relative` scope and combines them with the same localized distance strings used by [`distance_of_time_in_words`](https://api.rubyonrails.org/v8.1.4/classes/ActionView/Helpers/DateHelper.html#method-i-distance_of_time_in_words).
You may need to add additional date and time formats for the I18n backend to behave as expected. However, translations for Railsβ default formats are often already available for many locales. See the [rails-i18n repository](https://github.com/svenfuchs/rails-i18n/tree/master/rails/locale) for an archive of various locale files. Placing these files in `config/locales/` makes them automatically available to your application.
### [3.6. Localized Views](#localized-views)
In some cases, translating individual strings is not the best fit. If an entire template differs by locale, Rails can render a localized view instead.
For example, consider a `BooksController` with an index action that renders the `app/views/books/index.html.erb` template. If a localized variant of this template, `index.es.html.erb`, is added to the same directory, Rails will render that template when the locale is set to :es. When the locale is set to the default locale, the generic `index.html.erb` template will be used.
```
`
* Bob's session at `www.webapp.com` is still alive, because he didn't log out a few minutes ago.
* By viewing the post, the browser finds an image tag. It tries to load the suspected image from `www.webapp.com`. As explained before, it will also send along the cookie with the valid session ID.
* The web application at `www.webapp.com` verifies the user information in the corresponding session hash and destroys the project with the ID 1. It then returns a result page which is an unexpected result for the browser, so it will not display the image.
* Bob doesn't notice the attack - but a few days later he finds out that project number one is gone.
It is important to notice that the actual crafted image or link doesn't necessarily have to be situated in the web application's domain, it can be anywhere - in a forum, blog post, or email.
CSRF appears very rarely in CVE (Common Vulnerabilities and Exposures) - less than 0.1% in 2006 - but it really is a 'sleeping giant' \[Grossman]. This is in stark contrast to the results in many security contract works - *CSRF is an important security issue*.
### [4.1. CSRF Countermeasures](#csrf-countermeasures)
*First, as is required by the W3C, use GET and POST appropriately. Secondly, a security token in non-GET requests will protect your application from CSRF.*
#### [4.1.1. Use GET and POST Appropriately](#use-get-and-post-appropriately)
The HTTP protocol basically provides two main types of requests - GET and POST (DELETE, PUT, and PATCH should be used like POST). The World Wide Web Consortium (W3C) provides a checklist for choosing HTTP GET or POST:
**Use GET if:**
* The interaction is more *like a question* (i.e., it is a safe operation such as a query, read operation, or lookup).
**Use POST if:**
* The interaction is more *like an order*, or
* The interaction *changes the state* of the resource in a way that the user would perceive (e.g., a subscription to a service), or
* The user is *held accountable for the results* of the interaction.
If your web application is RESTful, you might be used to additional HTTP verbs, such as PATCH, PUT, or DELETE. Some legacy web browsers, however, do not support them - only GET and POST. Rails uses a hidden `_method` field to handle these cases.
*POST requests can be sent automatically, too*. In this example, the link [www.harmless.com](http://www.harmless.com) is shown as the destination in the browser's status bar. But it has actually dynamically created a new form that sends a POST request.
```
To the harmless survey
```
Or the attacker places the code into the onmouseover event handler of an image:
```
```
There are many other possibilities, like using a `
```
This JavaScript code will simply display an alert box. The next examples do exactly the same, only in very uncommon places:
```
)