Module: ActiveRecord::Enum

Included in:
Base
Defined in:
lib/active_record/enum.rb

Overview

Declare an enum attribute where the values map to integers in the database, but can be queried by name. Example:

class Conversation < ActiveRecord::Base
  enum status: [ :active, :archived ]
end

# conversation.update! status: 0
conversation.active!
conversation.active? # => true
conversation.status  # => "active"

# conversation.update! status: 1
conversation.archived!
conversation.archived? # => true
conversation.status    # => "archived"

# conversation.status = 1
conversation.status = "archived"

conversation.status = nil
conversation.status.nil? # => true
conversation.status      # => nil

Scopes based on the allowed values of the enum field will be provided as well. With the above example:

Conversation.active
Conversation.archived

Of course, you can also query them directly if the scopes don't fit your needs:

Conversation.where(status: [:active, :archived])
Conversation.where.not(status: :active)

You can set the default value from the database declaration, like:

create_table :conversations do |t|
  t.column :status, :integer, default: 0
end

Good practice is to let the first declared status be the default.

Finally, it's also possible to explicitly map the relation between attribute and database integer with a hash:

class Conversation < ActiveRecord::Base
  enum status: { active: 0, archived: 1 }
end

Note that when an array is used, the implicit mapping from the values to database integers is derived from the order the values appear in the array. In the example, :active is mapped to 0 as it's the first element, and :archived is mapped to 1. In general, the i-th element is mapped to i-1 in the database.

Therefore, once a value is added to the enum array, its position in the array must be maintained, and new values should only be added to the end of the array. To remove unused values, the explicit hash syntax should be used.

In rare circumstances you might need to access the mapping directly. The mappings are exposed through a class method with the pluralized attribute name, which return the mapping in a HashWithIndifferentAccess:

Conversation.statuses[:active]    # => 0
Conversation.statuses["archived"] # => 1

Use that class method when you need to know the ordinal value of an enum. For example, you can use that when manually building SQL strings:

Conversation.where("status <> ?", Conversation.statuses[:archived])

You can use the :_prefix or :_suffix options when you need to define multiple enums with same values. If the passed value is true, the methods are prefixed/suffixed with the name of the enum. It is also possible to supply a custom value:

class Conversation < ActiveRecord::Base
  enum status: [:active, :archived], _suffix: true
  enum comments_status: [:active, :inactive], _prefix: :comments
end

With the above example, the bang and predicate methods along with the associated scopes are now prefixed and/or suffixed accordingly:

conversation.active_status!
conversation.archived_status? # => false

conversation.comments_inactive!
conversation.comments_active? # => false

Defined Under Namespace

Classes: EnumType

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(base) ⇒ Object

:nodoc:



99
100
101
 
# File 'lib/active_record/enum.rb', line 99

def self.extended(base) # :nodoc:
  base.class_attribute(:defined_enums, instance_writer: false, default: {})
end

Instance Method Details

#enum(definitions) ⇒ Object 



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/active_record/enum.rb', line 151

def enum(definitions)
  klass = self
  enum_prefix = definitions.delete(:_prefix)
  enum_suffix = definitions.delete(:_suffix)
  definitions.each do |name, values|
    # statuses = { }
    enum_values = ActiveSupport::HashWithIndifferentAccess.new
    name = name.to_s

    # def self.statuses() statuses end
    detect_enum_conflict!(name, name.pluralize, true)
    singleton_class.send(:define_method, name.pluralize) { enum_values }
    defined_enums[name] = enum_values

    detect_enum_conflict!(name, name)
    detect_enum_conflict!(name, "#{name}=")

    attr = attribute_alias?(name) ? attribute_alias(name) : name
    decorate_attribute_type(attr, :enum) do |subtype|
      EnumType.new(attr, enum_values, subtype)
    end

    _enum_methods_module.module_eval do
      pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
      pairs.each do |label, value|
        if enum_prefix == true
          prefix = "#{name}_"
        elsif enum_prefix
          prefix = "#{enum_prefix}_"
        end
        if enum_suffix == true
          suffix = "_#{name}"
        elsif enum_suffix
          suffix = "_#{enum_suffix}"
        end

        value_method_name = "#{prefix}#{label}#{suffix}"
        enum_values[label] = value
        label = label.to_s

        # def active?() status == "active" end
        klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
        define_method("#{value_method_name}?") { self[attr] == label }

        # def active!() update!(status: 0) end
        klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
        define_method("#{value_method_name}!") { update!(attr => value) }

        # scope :active, -> { where(status: 0) }
        klass.send(:detect_enum_conflict!, name, value_method_name, true)
        klass.scope value_method_name, -> { where(attr => value) }
      end
    end
    enum_values.freeze
  end
end

#inherited(base) ⇒ Object

:nodoc:



103
104
105
106
 
# File 'lib/active_record/enum.rb', line 103

def inherited(base) # :nodoc:
  base.defined_enums = defined_enums.deep_dup
  super
end