Rails State Machine

Build Status

Rails State Machine is a ActiveRecord-bound state machine.

Installation

Add this line to your application’s Gemfile:

ruby gem 'rails_state_machine'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rails_state_machine

Usage

Your model needs a state attribute. You can then simply define your state machine as follows.

```ruby class YourModel < ApplicationRecord include RailsStateMachine::Model

state_machine do state :draft, initial: true state :review_pending state :approved state :rejected

event :request_review do
  transitions from: [:draft, :rejected], to: :review_pending
end

event :approve do
  transitions from: :review_pending, to: :approved
end

event :reject do
  transitions from: :review_pending, to: :rejected
end   end end ```

This will define instance methods with the names of those events, and constants like STATE_DRAFT on the model. If a state is configured as initial: true, new instances will be assigned this state.

A model instance offers these state machine methods:

  • <state_name>? to find out if this is the current state.
  • <event_name> call an event and transition into a new state. The record will be saved, if valid.
  • <event_name>! call an event and transition into a new state. Calls save! to save the record.
  • may_<event_name>? to find out if an event transition could be taken. Note that this will not validate if the model is valid afterwards.
  • state_event= to take a state event, but not save yet. Commonly used for forms where the controller takes a “state_event” param and saves.
  • state_event to get the name of the event that will be called

Should you ever need to query the state machine for its states or events, it is accessible via state_machine class or instance methods on the model. This is mostly helpful in tests.

If you want an event to be available for a different edge in your graph, you may define multiple transitions per event:

ruby event :request_feedback do transitions from: :draft, to: :draft transitions from: :review_pending, to: :review_pending end

As an alternative to using RailsStateMachine::Model and state_machine do, configure the state machine manually. This only adds the state_machine to your model, but no states or state_events.

```ruby class YourModel < ApplicationRecord RailsStateMachine::StateMachine.new(self).configure do state :draft, initial: true state :review_pending state :approved state :rejected

event :request_review do
  transitions from: [:draft, :rejected], to: :review_pending
end

event :approve do
  transitions from: :review_pending, to: :approved
end

event :reject do
  transitions from: :review_pending, to: :rejected
end   end

def self.states state_machine.state_names end

def self.state_events state_machine.event_names end end ```

Event callbacks

Here is a list with all the available callbacks, listed in the same order in which they will get called during the respective operations. The callbacks are chained with the existing active record callbacks on the model.

  • before_validation
  • before_save
  • after_save
  • after_commit

Example:

```ruby event :request_review do transitions from: [:draft, :rejected], to: :review_pending

before_validation do # this callback is chained with existing before_validation callbacks of the model end

before_save do # this callback is chained with existing before_save callbacks of the model end

after_save do # this callback is chained with existing after_save callbacks of the model end

after_commit do # this callback is chained with existing after_commit callbacks of the model end end ```

Development

There are tests in spec. We only accept PRs with tests. To run tests:

  • Install Ruby 2.4.4
  • Copy the file spec/support/database.sample.yml to spec/support/database.yml and enter your PostgreSQL credentials. You can create the database afterwards with createdb rails_state_machine_test.
  • Run bin/setup to install development dependencies.
  • Run tests using bundle exec rspec

We recommend to test large changes against multiple versions of Ruby and multiple dependency sets. Supported combinations are configured in .travis.yml. We provide some rake tasks to help with this:

  • Install development dependencies using bundle matrix:install
  • Run tests using bundle matrix:spec

You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

If you would like to contribute:

  • Fork the repository.
  • Push your changes with passing specs.
  • Send us a pull request.

We want to keep this gem leightweight and on topic. If you are unsure whether a change would make it into the gem, open an issue and discuss.

Note that we have configured Travis CI to automatically run tests in all supported Ruby versions and dependency sets after each push. We will only merge pull requests after a green Travis build.

License

The gem is available as open source under the terms of the MIT License.

Credits

Arne Hartherz and Emanuel Denzel from makandra.