waArrayObjectDiff

This class allows creating a hierarchical storage of values with equal access to them either as items of multidimensional arrays or as objects containing nested collections of objects, just like its parent class waArrayObject does.

The difference between waArrayObjectDiff and its parent class is that it allows tracking changes made to object properties and then either finally apply or revert them. Before such temporary changes have been applied or reverted you can view their contents; after that their contents are cleared.

Examples

$object = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

// make a temporary change
$object->foo = 300;

wa_dumpc(
    $object->toArray(), // ['foo' => 300, 'bar' => 200]
    $object->diff()     // ['foo' => 300]
);

// a) revert the change
$object->revert();

wa_dumpc(
    $object->toArray(), // ['foo' => 100, 'bar' => 200]
    $object->diff()     // []
);

// or

// b) apply the change
// $object->merge();
//
// wa_dumpc(
//       $object->toArray(), // ['foo' => 300, 'bar' => 200]
//       $object->diff()     // []
// );

Methods

• __construct

  Class constructor.

• diff

  Returns values of temporary changes made to object properties.

• merge

  Applies temporary changes to object properties.

• revert

  Reverts temporary changes to object properties.

• clearPersistent

  Clears persistent values stored in object properties.

• getPersistent

  Returns the instance of the waArrayObject class in which persistent object properties values are stored.

• setPersistent

  Sets the instance of the waArrayObject class in which persistent object properties values are stored.

• restorePersistentInvariant

  Restores correct data structure after changes made to object property persistent.

public function __construct ($persistent = [])

Class constructor.

Parameters

• $persistent

  Value implementing the Traversable interface or an instance of the waArrayObject class.

Example

// variant 1
$array_object_diff = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

// variant 2
$array_object_ = new waArrayObject([
    'foo' => 100,
    'bar' => 200,
]);

$array_object_diff = new waArrayObjectDiff($array_object_);

public function diff ($new = true)

Returns values of temporary changes made to object properties.

Parameters

• $new

  Returned value mode:

  • true: return the array of new values of changed object properties.
  • false: return the array of old values of changed object properties, including those deleted using the unset() construct.

Example

$object = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

$object->foo = 300;

wa_dump(
    $object->diff(true),  // ['foo' => 300]
    $object->diff(false), // ['foo' => 100]
);

Example

$object = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

unset($object->foo);

wa_dump(
    $object->diff(true),  // []
    $object->diff(false), // ['foo' => 100]
);

public function merge()

Applies temporary changes to object properties.

Example

$object = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

$object->foo = 300;
$object->merge();

// view changes contents
wa_dump($object->diff(true)); // []

public function revert()

Reverts temporary changes to object properties.

Example

$object = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

$object->foo = 300;
$object->revert();

wa_dump($object->toArray());

Result

[
    'foo' => 100,
    'bar' => 200,
]

public function clearPersistent()

Clears persistent values stored in object properties and moves them to the temporary changes storage. After that an object is in the same state as if some temporary changes had been made to an empty object, which had not then been applied using the merge() method.

Example

$object = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

wa_dumpc(
    $object->toArray(),  // ['foo' => 100, 'bar' => 200]
    $object->diff()      // []
);

// clear persistent values
// and move them to the temporary changes storage
$object->clearPersistent();

wa_dumpc(
    $object->toArray(),  // ['foo' => 100, 'bar' => 200]
    $object->diff()      // ['foo' => 100, 'bar' => 200]
);

// clear temporary changes
// persistent values have already been deleted by the clearPersistent() method
$object->revert();

wa_dumpc(
    $object->toArray(),  // []
    $object->diff()      // []
);

public function getPersistent()

Returns the instance of the waArrayObject class in which persistent object properties values are stored.

Example

$object = new waArrayObjectDiff([
    'foo' => 100,
    'bar' => 200,
]);

wa_dump($object->getPersistent());

Result

waArrayObject object {
    *rec_data => [
      'foo' => 100,
      'bar' => 200,
    ]
    *stub => false
}

public function setPersistent (waArrayObject $p)

Sets the instance of the waArrayObject class in which persistent object properties values are stored.

Example

$object = new waArrayObjectDiff();
$object->setPersistent(new waArrayObject([
    'foo' => 100,
    'bar' => 200,
]));

public function restorePersistentInvariant()

Restores correct data structure after changes made to object property persistent; e.g., in sub-classes.

Example

class myArrayObjectDiff extends waArrayObjectDiff
{
    public function setPersistentValue ($name, $value)
    {
        $this->persistent[$name] = $value;
        $this->restorePersistentInvariant();
    }
}