百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
S

state_machines-activerecord

> 编程语言
开源

StateMachines 主动记录集成

433 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

StateMachines 主动记录集成

StateMachines Active Record Integration

The Active Record 8.0+ integration adds support for database transactions, automatically saving the record, named scopes, validation errors.

Requirements

  • Ruby 3.2+
  • Rails 8.0+

Installation

Add this line to your application's Gemfile:

gem 'state_machines-activerecord'

And then execute:

$ bundle

Or install it yourself as:

$ gem install state_machines-activerecord

Usage

For the complete usage guide, see http://www.rubydoc.info/github/state-machines/state_machines-activerecord/StateMachines/Integrations/ActiveRecord

Example

ruby
class Vehicle  :parked do
    before_transition :parked => any - :parked, :do => :put_on_seatbelt
    after_transition any => :parked do |vehicle, transition|
      vehicle.seatbelt = 'off'
    end
    around_transition :benchmark

    event :ignite do
      transition :parked => :idling
    end

    state :first_gear, :second_gear do
      validates :seatbelt_on, presence: true
    end
  end

  def put_on_seatbelt
    ...
  end

  def benchmark
    ...
    yield
    ...
  end
end

Scopes

Usage of the generated scopes (assuming default column state):

ruby
Vehicle.with_state(:parked)                         # also plural #with_states
Vehicle.without_states(:first_gear, :second_gear)   # also singular #without_state

Transparent Scopes

State scopes will return all records when nil is passed, making them perfect for search filters:

ruby
Vehicle.with_state(nil)                            # Returns all vehicles
Vehicle.with_state(params[:state])                 # Returns all vehicles if params[:state] is nil
Vehicle.where(color: 'red').with_state(nil)        # Returns all red vehicles (chainable)

Rails Enum Integration

When your ActiveRecord model uses Rails enums and defines a state machine on the same attribute, this gem automatically detects the conflict and provides seamless integration. This prevents method name collisions between Rails enum methods and state machine methods.

Auto-Detection and Conflict Resolution

ruby
class Order  :cancelled
    end
  end
end

When enum integration is detected, the gem automatically:

  • Preserves original Rails enum methods (pending?, processing?, etc.)
  • Generates prefixed state machine methods to avoid conflicts (status_pending?, status_processing?, etc.)
  • Creates prefixed scope methods (Order.status_pending, Order.status_processing, etc.)

Available Methods

Original Rails enum methods (preserved):

ruby
order = Order.create(status: :pending)
order.pending?        # => true (Rails enum method)
order.processing?     # => false (Rails enum method)
order.processing!     # Sets status to :processing (Rails enum method)

Order.pending         # Rails enum scope
Order.processing      # Rails enum scope

Generated state machine methods (prefixed):

ruby
# Predicate methods
order.status_pending?     # => true (state machine method)
order.status_processing?  # => false (state machine method)
order.status_completed?   # => false (state machine method)

# Bang methods (for conflict resolution only)
# These are placeholders and raise runtime errors
order.status_processing!  # => raises RuntimeError

# Scope methods  
Order.status_pending      # State machine scope
Order.status_processing   # State machine scope
Order.not_status_pending  # Negative state machine scope

Introspection API

The integration provides a comprehensive introspection API for advanced use cases:

…

Integer-backed state attributes

Integer columns whose states don't declare explicit values are converted transparently: application code reads state names while the database stores integers (mapped by definition order).

ruby
class Order  "approved"
# The database stores 1.

Machines where every state declares an explicit integer value keep the classic raw-integer behavior automatically: reads return the integer and status_name returns the state name:

ruby
class LegacyOrder  1
order.status_name # => :approved
# The database stores 1.

Applications that want no type conversion at all can disable it during boot, before defining affected state machines:

ruby
# config/initializers/state_machines.rb

StateMachines::Integrations::ActiveRecord.auto_convert_integer_state_attributes = false

With this setting disabled, integer-backed state attributes are left entirely to ActiveRecord's normal integer handling.

Requirements for Enum Integration

  • The state machine attribute must match an existing Rails enum attribute
  • Auto-detection is enabled by default when this condition is met

Configuration Options

The enum integration supports several configuration options:

  • prefix (default: true) - Adds a prefix to generated methods to avoid conflicts
  • suffix (default: false) - Alternative naming strategy using suffixes instead of prefixes
  • scopes (default: true) - Controls whether state machine scopes are generated

State driven validations

As mentioned in StateMachines::Machine#state, you can define behaviors, like validations, that only execute for certain states. One important caveat here is that, due to a constraint in ActiveRecord's validation framework, custom validators will not work as expected when defined to run in multiple states. For example:

ruby
class Vehicle :speed_is_legal validation will only get run
for the :second_gear state.  To avoid this, you can define your
custom validation like so:

```ruby
class Vehicle < ApplicationRecord
  state_machine do
    state :first_gear, :second_gear do
      validate {|vehicle| vehicle.speed_is_legal}
    end
  end
end

Contributing

  1. Fork it ( https://github.com/state-machines/state_machines-activerecord/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Issues· 5 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rubyactiverecordrubystate-machine

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言