3.5. Memento

3.5.1. Purpose

Provide the ability to restore an object to its previous state (undo via rollback).

The memento pattern is implemented with three objects: the originator, a caretaker and a memento. The originator is some object that has an internal state. The caretaker is going to do something to the originator, but wants to be able to undo the change. The caretaker first asks the originator for a memento object. Then it does whatever operation (or sequence of operations) it was going to do. To roll back to the state before the operations, it returns the memento object to the originator. The memento object itself is an opaque object (one which the caretaker cannot, or should not, change). When using this pattern, care should be taken if the originator may change other objects or resources - the memento pattern operates on a single object.

3.5.2. Examples

  • The seed of a pseudorandom number generator
  • The state in a finite state machine

3.5.3. UML Diagram

Alt Momento UML Diagram

3.5.4. Code

You can also find these code on GitHub

Memento.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<?php

namespace DesignPatterns\Behavioral\Memento;

class Memento
{
    /* @var mixed */
    private $state;

    /**
     * @param mixed $stateToSave
     */
    public function __construct($stateToSave)
    {
        $this->state = $stateToSave;
    }

    /**
     * @return mixed
     */
    public function getState()
    {
        return $this->state;
    }
}

Originator.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<?php

namespace DesignPatterns\Behavioral\Memento;

class Originator
{
    /* @var mixed */
    private $state;

    // The class could also contain additional data that is not part of the
    // state saved in the memento..

    /**
     * @param mixed $state
     */
    public function setState($state)
    {
        $this->state = $state;
    }

    /**
     * @return Memento
     */
    public function saveToMemento()
    {
        $state = is_object($this->state) ? clone $this->state : $this->state;

        return new Memento($state);
    }

    public function restoreFromMemento(Memento $memento)
    {
        $this->state = $memento->getState();
    }
}

Caretaker.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<?php

namespace DesignPatterns\Behavioral\Memento;

class Caretaker
{
    public static function run()
    {
        /* @var $savedStates Memento[] */

        $savedStates = array();

        $originator = new Originator();

        //Setting state to State1
        $originator->setState("State1");
        //Setting state to State2
        $originator->setState("State2");
        //Saving State2 to Memento
        $savedStates[] = $originator->saveToMemento();
        //Setting state to State3
        $originator->setState("State3");

        // We can request multiple mementos, and choose which one to roll back to.
        // Saving State3 to Memento
        $savedStates[] = $originator->saveToMemento();
        //Setting state to State4
        $originator->setState("State4");

        $originator->restoreFromMemento($savedStates[1]);
        //State after restoring from Memento: State3
    }
}

3.5.5. Test

Tests/MementoTest.php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
<?php

namespace DesignPatterns\Behavioral\Memento\Tests;

use DesignPatterns\Behavioral\Memento\Originator;

/**
 * MementoTest tests the memento pattern
 */
class MementoTest extends \PHPUnit_Framework_TestCase
{

    public function testStringState()
    {
        $originator = new Originator();
        $originator->setState("State1");

        $this->assertAttributeEquals("State1", "state", $originator);

        $originator->setState("State2");

        $this->assertAttributeEquals("State2", "state", $originator);

        $savedState = $originator->saveToMemento();

        $this->assertAttributeEquals("State2", "state", $savedState);

        $originator->setState("State3");

        $this->assertAttributeEquals("State3", "state", $originator);

        $originator->restoreFromMemento($savedState);

        $this->assertAttributeEquals("State2", "state", $originator);
    }

    public function testObjectState()
    {
        $originator = new Originator();

        $foo       = new \stdClass();
        $foo->data = "foo";

        $originator->setState($foo);

        $this->assertAttributeEquals($foo, "state", $originator);

        $savedState = $originator->saveToMemento();

        $this->assertAttributeEquals($foo, "state", $savedState);

        $bar       = new \stdClass();
        $bar->data = "bar";

        $originator->setState($bar);

        $this->assertAttributeEquals($bar, "state", $originator);

        $originator->restoreFromMemento($savedState);

        $this->assertAttributeEquals($foo, "state", $originator);

        $foo->data = null;

        $this->assertAttributeNotEquals($foo, "state", $savedState);

        $this->assertAttributeNotEquals($foo, "state", $originator);
    }
}