3.5. Memento

3.5.1. Purpose

It provides the ability to restore an object to it’s previous state (undovia rollback) or to gain access to state of the object, without revealingit’s implementation (i.e., the object is not required to have a functionto return the current state).

The memento pattern is implemented with three objects: the Originator, aCaretaker and a Memento.

Memento – an object that contains a concrete unique snapshot of state ofany object or resource: string, number, array, an instance of class and so on.The uniqueness in this case does not imply the prohibition existence of similarstates in different snapshots. That means the state can be extracted asthe independent clone. Any object stored in the Memento should bea full copy of the original object rather than a reference to the originalobject. The Memento object is a “opaque object” (the object that no one canor should change).

Originator – it is an object that contains the actual state of an externalobject is strictly specified type. Originator is able to create a uniquecopy of this state and return it wrapped in a Memento. The Originator doesnot know the history of changes. You can set a concrete state to Originatorfrom the outside, which will be considered as actual. The Originator mustmake sure that given state corresponds the allowed type of object. Originatormay (but not should) have any methods, but they they can’t make changes tothe saved object state.

Caretaker controls the states history. He may make changes to an object;take a decision to save the state of an external object in the Originator;ask from the Originator snapshot of the current state; or set the Originatorstate to equivalence with some snapshot from history.

3.5.2. Examples

• The seed of a pseudorandom number generator
• The state in a finite state machine
• Control for intermediate states of ORM Model before saving

3.5.3. UML Diagram

3.5.4. Code

You can also find this code on GitHub

Memento.php

<?php
 
namespace DesignPatterns\Behavioral\Memento;
 
class Memento
{
    /**
     * @var State
     */
    private $state;
 
    /**
     * @param State $stateToSave
     */
    public function __construct(State $stateToSave)
    {
        $this->state = $stateToSave;
    }
 
    /**
     * @return State
     */
    public function getState()
    {
        return $this->state;
    }
}

State.php

<?php
 
namespace DesignPatterns\Behavioral\Memento;
 
class State
{
    const STATE_CREATED = 'created';
    const STATE_OPENED = 'opened';
    const STATE_ASSIGNED = 'assigned';
    const STATE_CLOSED = 'closed';
 
    /**
     * @var string
     */
    private $state;
 
    /**
     * @var string[]
     */
    private static $validStates = [
        self::STATE_CREATED,
        self::STATE_OPENED,
        self::STATE_ASSIGNED,
        self::STATE_CLOSED,
    ];
 
    /**
     * @param string $state
     */
    public function __construct(string $state)
    {
        self::ensureIsValidState($state);
 
        $this->state = $state;
    }
 
    private static function ensureIsValidState(string $state)
    {
        if (!in_array($state, self::$validStates)) {
            throw new \InvalidArgumentException('Invalid state given');
        }
    }
 
    public function __toString(): string
    {
        return $this->state;
    }
}

Ticket.php

<?php
 
namespace DesignPatterns\Behavioral\Memento;
 
/**
 * Ticket is the "Originator" in this implementation
 */
class Ticket
{
    /**
     * @var State
     */
    private $currentState;
 
    public function __construct()
    {
        $this->currentState = new State(State::STATE_CREATED);
    }
 
    public function open()
    {
        $this->currentState = new State(State::STATE_OPENED);
    }
 
    public function assign()
    {
        $this->currentState = new State(State::STATE_ASSIGNED);
    }
 
    public function close()
    {
        $this->currentState = new State(State::STATE_CLOSED);
    }
 
    public function saveToMemento(): Memento
    {
        return new Memento(clone $this->currentState);
    }
 
    public function restoreFromMemento(Memento $memento)
    {
        $this->currentState = $memento->getState();
    }
 
    public function getState(): State
    {
        return $this->currentState;
    }
}

3.5.5. Test

Tests/MementoTest.php

<?php
 
namespace DesignPatterns\Behavioral\Memento\Tests;
 
use DesignPatterns\Behavioral\Memento\State;
use DesignPatterns\Behavioral\Memento\Ticket;
use PHPUnit\Framework\TestCase;
 
class MementoTest extends TestCase
{
    public function testOpenTicketAssignAndSetBackToOpen()
    {
        $ticket = new Ticket();
 
        // open the ticket
        $ticket->open();
        $openedState = $ticket->getState();
        $this->assertEquals(State::STATE_OPENED, (string) $ticket->getState());
 
        $memento = $ticket->saveToMemento();
 
        // assign the ticket
        $ticket->assign();
        $this->assertEquals(State::STATE_ASSIGNED, (string) $ticket->getState());
 
        // now restore to the opened state, but verify that the state object has been cloned for the memento
        $ticket->restoreFromMemento($memento);
 
        $this->assertEquals(State::STATE_OPENED, (string) $ticket->getState());
        $this->assertNotSame($openedState, $ticket->getState());
    }
}