https://github.com/state-machines/state_machines-activerecord
StateMachines Active Record Integration
https://github.com/state-machines/state_machines-activerecord
activerecord ruby state-machine
Last synced: 3 months ago
JSON representation
StateMachines Active Record Integration
- Host: GitHub
- URL: https://github.com/state-machines/state_machines-activerecord
- Owner: state-machines
- License: mit
- Created: 2015-01-06T15:29:46.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2025-07-03T15:57:17.000Z (3 months ago)
- Last Synced: 2025-07-11T18:48:22.128Z (3 months ago)
- Topics: activerecord, ruby, state-machine
- Language: Ruby
- Homepage: https://github.com/state-machines/state_machines-activerecord
- Size: 155 KB
- Stars: 410
- Watchers: 8
- Forks: 84
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://github.com/state-machines/state_machines-activerecord/actions/workflows/ruby.yml)
# StateMachines Active Record Integration
The Active Record 7.2+ integration adds support for database transactions, automatically
saving the record, named scopes, validation errors.
## Requirements
- Ruby 3.2+
- Rails 7.2+
## 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 < ApplicationRecord
state_machine :initial => :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)
```
### 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 < ApplicationRecord
state_machine do
state :first_gear, :second_gear do
validate :speed_is_legal
end
end
end
```
In this case, the :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