Class yii\behaviors\OptimisticLockBehavior

OptimisticLockBehavior automatically upgrades a model's lock version using the column name returned by optimisticLock().

Optimistic locking allows multiple users to access the same record for edits and avoids potential conflicts. In case when a user attempts to save the record upon some staled data (because another user has modified the data), a StaleObjectException exception will be thrown, and the update or deletion is skipped.

To use this behavior, first enable optimistic lock by following the steps listed in optimisticLock(), remove the column name holding the lock version from the rules() method of your ActiveRecord class, then add the following code to it:

use yii\behaviors\OptimisticLockBehavior;

public function behaviors()
{
    return [
        OptimisticLockBehavior::class,
    ];
}

By default, OptimisticLockBehavior will use getBodyParam() to parse the submitted value or set it to 0 on any fail. That means a request not holding the version attribute may achieve a first successful update to entity, but starting from there any further try should fail unless the request is holding the expected version number.

Once attached, internal use of the model class should also fail to save the record if the version number isn't held by getBodyParam(). It may be useful to extend your model class, enable optimistic lock in parent class by overriding optimisticLock(), then attach the behavior to the child class so you can tie the parent model to internal use while linking the child model holding this behavior to the controllers responsible of receiving end user inputs. Alternatively, you can also configure the $value property with a PHP callable to implement a different logic.

OptimisticLockBehavior also provides a method named upgrade() that increases a model's version by one, that may be useful when you need to mark an entity as stale among connected clients and avoid any change to it until they load it again:

$model->upgrade();

See also yii\db\BaseActiveRecord::optimisticLock() for details on how to enable optimistic lock.