state_machines-activerecord

The gem provides two ways to handle integer columns used for states:

Automatic Conversion (Default)

If states do not declare explicit integer values, the gem converts them transparently. Application code reads state names (strings), but the database stores integers (mapped by definition order).

# Database stores 1, but code sees "approved"
order.status = :approved
order.status # => "approved"

Explicit Integer Values

If states declare explicit values, the gem maintains classic raw-integer behavior. Reading the attribute returns the integer, and status_name returns the symbol.

# state :pending, value: 0
# state :approved, value: 1

order.status      # => 1
order.status_name # => :approved

Disabling Auto-Conversion

To disable all type conversion and use standard ActiveRecord integer handling, set this in an initializer before defining state machines:

# config/initializers/state_machines.rb
StateMachines::Integrations::ActiveRecord.auto_convert_integer_state_attributes = false

class Order < ApplicationRecord
  state_machine :status, initial: :pending do
    state :pending
    state :approved
  end
end

order = Order.create!
order.status = :approved
order.status # => "approved"
# The database stores 1.

If an ActiveRecord model uses a Rails enum and a state_machine on the same attribute, the gem automatically detects the conflict and resolves it by prefixing state machine methods to prevent collisions with Rails enum methods.

Auto-Detection Requirements

• The state machine attribute must match an existing Rails enum attribute.
• Auto-detection is enabled by default.

Conflict Resolution Behavior

When integration is detected, the gem:

1. Preserves original Rails enum methods (e.g., pending?, processing!).
2. Generates prefixed state machine methods (e.g., status_pending?).
3. Creates prefixed scope methods (e.g., Order.status_pending).

Configuration Options

• prefix (default: true): Adds a prefix to generated methods.
• suffix (default: false): Uses suffixes instead of prefixes.
• scopes (default: true): Controls whether state machine scopes are generated.

class Order < ApplicationRecord
  # Rails enum definition
  enum :status, { pending: 0, processing: 1, completed: 2, cancelled: 3 }
  
  # State machine on the same attribute
  state_machine :status do
    state :pending, :processing, :completed, :cancelled
    
    event :process do
      transition pending: :processing
    end
    
    event :complete do
      transition processing: :completed
    end
    
    event :cancel do
      transition [:pending, :processing] => :cancelled
    end
  end
end

State machines in ActiveRecord create public event attributes (e.g., state_event) to allow transitions via mass-assignment. To prevent malicious users from triggering transitions through web forms, you must use Rails' Strong Parameters to permit only intended attributes.

Protecting Events

If you want to prevent users from tampering with events, exclude the event attribute from your permitted parameters:

class VehiclesController < ApplicationController
  def vehicle_params
    # Exclude state_event to prevent tampering
    params.require(:vehicle).permit(:color, :make, :model)
  end
end

Implementing Public and Private Machines

If you need certain events to be triggerable via mass-assignment while others remain protected, you can define two separate state machines that target the same underlying attribute:

class Vehicle < ApplicationRecord
  # Private machine for internal logic
  state_machine do
    # Define private events here
  end

  # Public machine for mass-assignment/external control
  state_machine :public_state, :attribute => :state do
    # Define public events here
  end
end

The StateMachines::Type::Integer class is a custom ActiveRecord::Type::Value designed for state machine attributes backed by integer columns. It manages the bidirectional conversion between state name strings (used by the state machine logic) and integer values (stored in the database).

Mapping Logic

• Implicit Mapping: States without an explicit integer value are mapped by their index position in the states collection (0, 1, 2, ...).
• Explicit Mapping: States with an explicit integer value (e.g., state :pending, value: 2) use that specific integer directly.
• Passthrough Mode: If every named state in the machine has an explicit integer value, the type enters "passthrough mode." In this mode, it delegates to the column's original integer type, preserving raw-integer behavior (e.g., record.status returns the integer, while record.status_name returns the symbol).

Conversion Lifecycle

• deserialize(value): Converts an integer from the database into a state name string.
• cast(value): Converts an assigned value (Symbol, String, or Integer) into the in-memory state name string.
• serialize(value): Converts the in-memory state name string back into an integer for database storage.