1: <?php
  2: 
  3: namespace Charcoal\Object;
  4: 
  5: /**
  6:  * Defines a changeset of an object implementing {@see \Charcoal\Object\RevisionableInterface}.
  7:  *
  8:  * {@see \Charcoal\Object\ObjectRevision} for a basic implementation.
  9:  */
 10: interface ObjectRevisionInterface
 11: {
 12:     /**
 13:      * @param string $targetType The object type (type-ident).
 14:      * @return \Charcoal\Object\ObjectRevisionInterface Chainable
 15:      */
 16:     public function setTargetType($targetType);
 17: 
 18:     /**
 19:      * @return string
 20:      */
 21:     public function targetType();
 22: 
 23:     /**
 24:      * @param mixed $targetId The object ID.
 25:      * @return \Charcoal\Object\ObjectRevisionInterface Chainable
 26:      */
 27:     public function setTargetId($targetId);
 28: 
 29:     /**
 30:      * @return mixed
 31:      */
 32:     public function targetId();
 33: 
 34:     /**
 35:      * @param integer $revNum The revision number.
 36:      * @return \Charcoal\Object\ObjectRevisionInterface Chainable
 37:      */
 38:     public function setRevNum($revNum);
 39: 
 40:     /**
 41:      * @return integer
 42:      */
 43:     public function revNum();
 44: 
 45:     /**
 46:      * @param mixed $revTs The revision's timestamp.
 47:      * @return \Charcoal\Object\ObjectRevisionInterface Chainable
 48:      */
 49:     public function setRevTs($revTs);
 50: 
 51:     /**
 52:      * @return DateTime|null
 53:      */
 54:     public function revTs();
 55: 
 56:     /**
 57:      * @param string $revUser The revision user ident.
 58:      * @return \Charcoal\Object\ObjectRevisionInterface Chainable
 59:      */
 60:     public function setRevUser($revUser);
 61: 
 62:     /**
 63:      * @return string
 64:      */
 65:     public function revUser();
 66: 
 67:     /**
 68:      * @param array|string $data The previous revision data.
 69:      * @return ObjectRevision
 70:      */
 71:     public function setDataPrev($data);
 72: 
 73:     /**
 74:      * @return array
 75:      */
 76:     public function dataPrev();
 77: 
 78:     /**
 79:      * @param array|string $data The current revision (object) data.
 80:      * @return ObjectRevision
 81:      */
 82:     public function setDataObj($data);
 83: 
 84:     /**
 85:      * @return array
 86:      */
 87:     public function dataObj();
 88: 
 89:      /**
 90:       * @param array|string $data The data diff.
 91:       * @return ObjectRevision
 92:       */
 93:     public function setDataDiff($data);
 94: 
 95:     /**
 96:      * @return array
 97:      */
 98:     public function dataDiff();
 99: 
100:     /**
101:      * Create a new revision from an object
102:      *
103:      * 1. Load the last revision
104:      * 2. Load the current item from DB
105:      * 3. Create diff from (1) and (2).
106:      *
107:      * @param RevisionableInterface $obj The object to create the revision from.
108:      * @return ObjectRevision Chainable
109:      */
110:     public function createFromObject(RevisionableInterface $obj);
111: 
112:     /**
113:      * @param array $dataPrev Optional. The previous revision data.
114:      * @param array $dataObj  Optional. The current revision (object) data.
115:      * @return array The diff data
116:      */
117:     public function createDiff(array $dataPrev, array $dataObj);
118: 
119:     /**
120:      * Recursive arrayDiff.
121:      *
122:      * @param array $array1 First array.
123:      * @param array $array2 Second array.
124:      * @return array The array diff.
125:      */
126:     public function recursiveDiff(array $array1, array $array2);
127: 
128:     /**
129:      * @param RevisionableInterface $obj The object  to load the last revision of.
130:      * @return ObjectRevision The last revision for the give object.
131:      */
132:     public function lastObjectRevision(RevisionableInterface $obj);
133: 
134:     /**
135:      * Retrieve a specific object revision, by revision number.
136:      *
137:      * @param RevisionableInterface $obj    Target object.
138:      * @param integer               $revNum The revision number to load.
139:      * @return ObjectRevision
140:      */
141:     public function objectRevisionNum(RevisionableInterface $obj, $revNum);
142: }
143: