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: about 1 month 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 10 years ago)
• Default Branch: master
• Last Pushed: 2024-03-13T16:31:46.000Z (10 months ago)
• Last Synced: 2024-10-29T16:59:08.279Z (about 2 months ago)
• Topics: activerecord, ruby, state-machine
• Language: Ruby
• Homepage: https://github.com/state-machines/state_machines-activerecord
• Size: 127 KB
• Stars: 403
• Watchers: 8
• Forks: 83
• Open Issues: 16
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

        
[![Build Status](https://travis-ci.com/state-machines/state_machines-activerecord.svg?branch=master)](https://travis-ci.com/state-machines/state_machines-activerecord)

[![Code Climate](https://codeclimate.com/github/state-machines/state_machines-activerecord.svg)](https://codeclimate.com/github/state-machines/state_machines-activerecord)

# StateMachines Active Record Integration

The Active Record 5.1+ integration adds support for database transactions, automatically

saving the record, named scopes, validation errors.

## 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

```

### 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