3722570167

Build Type

push

github

Committed by rotimi

Commit Message

Spec Docblock Tweak.

Run Details

66 of 75 relevant lines covered (88.0%)

2.52 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/src/GDAO/Model/RecordInterface.php

<?php
declare(strict_types=1);
namespace GDAO\Model;

/**
 * 
 * Contains a list of methods that Record classes must implement.
 *
 * @copyright (c) 2022, Rotexsoft
 */
interface RecordInterface extends \ArrayAccess, \Countable, \IteratorAggregate 
{
    ////////////////////////////////////////////////////////////////////////////
    ////////////////////////////////////////////////////////////////////////////
    ////
    //// RECOMMENDATIONS
    //// * Data for the record ([to be saved to the DB] or [as read from the DB]) 
    ////   should be stored in a property of the record class implementing this
    ////   interface. It could be an array, ArrayObject or any other suitable 
    ////   data structure. Data from this property should be returned via 
    ////   $this->getData() & $this->getDataByRef(). Data contained in this 
    ////   property should be set via 
    ////   $this->loadData($data_2_load, array $cols_2_load = array()).
    ////   For documentation purposes this property will be refered to as
    ////   $this->data (with an assumption that it is an array).
    ////   
    //// * Another property of the same data type as the one described above should
    ////   be present in the class implementing this interface. This property should 
    ////   only be set the first time record data is fetched from the DB (it holds
    ////   a copy of the data initially loaded into the record from the DB). This 
    ////   property's values should be compared with the values of the property 
    ////   described above in order to be able to determine if the record's data 
    ////   has changed (this should be implemented in $this->isChanged($col=null)). 
    ////   Data from this property should be returned via $this->getInitialData() 
    ////   & $this->getInitialDataByRef(). Data contained in this property should 
    ////   be set ONCE via $this->loadData($data_2_load, array $cols_2_load = array())
    ////   the first time loadData is called on a record.
    ////   For documentation purposes this property will be refered to as
    ////   $this->initial_data (with an assumption that it is an array).
    ////   
    //// * Another property should be present in the class implementing this 
    ////   interface. This property should hold data related to a record (ie.
    ////   has-many, has-one, belongs-to and has-many-through relationship data).
    ////   Data from this property should be returned via $this->getRelatedData()
    ////   & $this->getRelatedDataByRef(). Data contained in this property should 
    ////   be set via $this->setRelatedData($key, $value).
    ////   For documentation purposes this property will be refered to as
    ////   $this->related_data (with an assumption that it is an array).
    ////   
    //// * Another property should be present in the class implementing this 
    ////   interface. This property should hold other data for a record instance 
    ////   (i.e. data not from any actual db column and not related data).
    ////   Data from this property should be returned via $this->getNonTableColAndNonRelatedData()
    ////   & $this->getNonTableColAndNonRelatedDataByRef().
    ////   For documentation purposes this property will be refered to as
    ////   $this->non_table_col_and_non_related_data (with an assumption that it is an array).
    ////   
    //// * A boolean property should be present in the class implementing this 
    ////   interface. This property should be set to true if a record is new
    ////   (ie. its data has never been saved to the DB), else false.
    ////   For documentation purposes this property will be refered to as
    ////   $this->is_new.
    ////   
    //// * A property of type \GDAO\Model should be present in a class implementing
    ////   this interface. This is the model object that will perform database 
    ////   operations on behalf of the record.
    ////   For documentation purposes this property will be refered to as
    ////   $this->model
    ////   
    ////////////////////////////////////////////////////////////////////////////
    ////////////////////////////////////////////////////////////////////////////    
    
    /**
     * 
     * @param array $data associative array of data to be loaded into this record.
     *                    [
     *                      'col_name1'=>'value_for_col1', 
     *                      .............................,
     *                      .............................,
     *                      'col_nameN'=>'value_for_colN'
     *                    ]
     * @param \GDAO\Model $model The model object that transfers data between the db and this record.
     */
    public function __construct(array $data, \GDAO\Model $model);
        
    /**
     * 
     * Delete the record from the db. 
     * 
     * If deletion was successful and the primary key column for the record's db
     * table is auto-incrementing, then unset the primary key field in the data 
     * contained in the record object.
     * 
     * NOTE: data contained in the record include $this->data, $this->related_data
     *       and $this->initial_data.
     * 
     * @param bool $set_record_objects_data_to_empty_array true to reset the record object's data to an empty array if db deletion was successful, false to keep record object's data
     * 
     * @return bool true if record was successfully deleted from db or false if not
     * 
     */
    public function delete($set_record_objects_data_to_empty_array=false): bool;
    
    /**
     * 
     * Get the data for this record.
     * Modifying the returned data will not affect the data inside this record.
     * 
     * @return array a copy of the current data for this record
     */
    public function getData(): array;
    
    /**
     * 
     * Get a copy of the initial data loaded into this record.
     * Modifying the returned data will not affect the initial data inside this record.
     * 
     * @return array a copy of the initial data loaded into this record.
     */
    public function getInitialData(): array;
    
    
    /**
     * 
     * Get all the related data loaded into this record.
     * Modifying the returned data will not affect the related data inside this record.
     * 
     * @return array a reference to all the related data loaded into this record.
     */
    public function getRelatedData(): array;
    
    /**
     * 
     * Get data for this record that does not belong to any of it's table columns and is not related data.
     * 
     * @return array Data for this record (not to be saved to the db i.e. not from any actual db column and not related data).
     */
    public function getNonTableColAndNonRelatedData(): array;
    
    /**
     * 
     * Get a reference to the data for this record.
     * Modifying the returned data will affect the data inside this record.
     * 
     * @return array a reference to the current data for this record.
     */
    public function &getDataByRef(): array;
    
    /**
     * 
     * Get a reference to the initial data loaded into this record.
     * Modifying the returned data will affect the initial data inside this record.
     * 
     * @return array a reference to the initial data loaded into this record.
     */
    public function &getInitialDataByRef(): array;
    
    /**
     * 
     * Get a reference to all the related data loaded into this record.
     * Modifying the returned data will affect the related data inside this record.
     * 
     * @return array a reference to all the related data loaded into this record.
     */
    public function &getRelatedDataByRef(): array;
    
    /**
     * 
     * Get data for this record that does not belong to any of it's table columns and is not related data.
     * 
     * @return array reference to the data for this record (not from any actual db column and not related data).
     */
    public function &getNonTableColAndNonRelatedDataByRef(): array;
    
    /**
     * 
     * Set relation data for this record.
     * 
     * @param string $key relation name
     * @param mixed $value an array or record or collection containing related data
     * 
     * @throws \GDAO\Model\RecordRelationWithSameNameAsAnExistingDBTableColumnNameException
     * 
     * @return $this
     */
    public function setRelatedData($key, $value): self;
    
    /**
     * 
     * Get the model object that saves and reads data to and from the db on 
     * behalf of this record
     */
    public function getModel(): \GDAO\Model;
    
    /**
     * 
     * @return string name of the primary-key column of the db table this record belongs to
     */
    public function getPrimaryCol(): string;
    
    /**
     * 
     * @return mixed the value stored in the primary-key column for this record.
     */
    public function getPrimaryVal();
    
    /**
     * 
     * Tells if the record, or a particular table-column in the record, has 
     * changed from its initial value.
     * 
     * @param string $col The table-column name.
     * 
     * @return null|bool Returns null if the table-column name does not exist,
     * boolean true if the data is changed, boolean false if not changed.
     *  
     */
    public function isChanged($col = null): ?bool;
    
    /**
     * 
     * Is the record new? (I.e. its data has never been saved to the db)
     * 
     */
    public function isNew(): bool;
    
    /**
     * 
     * This method partially or completely overwrites pre-existing data for a 
     * record and replaces it with the new data (this does not include related
     * data). If no data has previously been loaded into the record, keep a copy
     * of the loaded data for comparison in $this->isChanged($col=null)).
     * 
     * Note if $cols_2_load === null all data should be replaced, else only
     * replace data for the cols in $cols_2_load.
     * 
     * If $data_2_load is an instance of \GDAO\Model\RecordInterface and if 
     * $data_2_load->getModel()->getTableName() !== $this->getModel()->getTableName(), 
     * then the exception below should be thrown:
     * 
     *      \GDAO\Model\LoadingDataFromInvalidSourceIntoRecordException
     * 
     * @param \GDAO\Model\RecordInterface|array $data_2_load
     * @param array $cols_2_load name of field to load from $data_2_load. 
     *                           If empty, load all fields in $data_2_load.
     * 
     * @throws \GDAO\Model\LoadingDataFromInvalidSourceIntoRecordException
     * 
     * @return $this
     */
    public function loadData($data_2_load, array $cols_2_load = []): self;
    
    /**
     * 
     * Set the _is_new attribute of this record to true (meaning that the data
     * for this record has never been saved to the db).
     * 
     * @return $this
     */
    public function markAsNew(): self;
    
    /**
     * 
     * Set the _is_new attribute of this record to false (meaning that the data
     * for this record has been saved to the db or was read from the db).
     * 
     * @return $this
     */
    public function markAsNotNew(): self;
    
    /**
     * Set all properties of this record to the state they should be in for a new record.
     * For example:
     *  - unset its primary key value via unset($this[$this->getPrimaryCol()]);
     *  - call $this->markAsNew()
     *  - etc.
     * 
     * The _data & _initial_data properties can be updated as needed by the 
     * implementing sub-class. 
     * For example:
     *  - they could be left as is 
     *  - or the value of _data could be copied to _initial_data
     *  - or the value of _initial_data could be copied to _data
     *  - etc.
     * 
     * @return $this
     */
    public function setStateToNew(): self;

    /**
     * 
     * Save the specified or already existing data for this record to the db.
     * Since this record can only talk to the db via its model property (_model)
     * the save operation will actually be done via $this->model.
     * 
     * @param \GDAO\Model\RecordInterface|array $data_2_save
     * 
     * @return null|bool true: successful save, false: failed save, null: no changed data to save
     * 
     */
    public function save($data_2_save = null): ?bool;
    
    /**
     * 
     * Save the specified or already existing data for this record to the db.
     * Since this record can only talk to the db via its model property (_model)
     * the save operation will actually be done via $this->model.
     * This save operation shoould be gaurded by the PDO transaction mechanism
     * if available or another transaction mechanism. If the save operation 
     * fails all changes should be rolled back. If there is not transaction
     * mechanism available an Exception must be thrown alerting the caller to
     * use the save method instead.
     * 
     * @param \GDAO\Model\RecordInterface|array $data_2_save
     * 
     * @return bool|null true for a successful save, false for failed save, null: no changed data to save
     * 
     */
    public function saveInTransaction($data_2_save = null): ?bool;
    
    /**
     * 
     * Set the \GDAO\Model object for this record
     * 
     * @param \GDAO\Model $model
     * 
     * @return $this
     */
    public function setModel(\GDAO\Model $model): self;
    
    /**
     * 
     * Get all the data and property (name & value pairs) for this record.
     * 
     * @return array of all data & property (name & value pairs) for this record.
     * 
     */
    public function toArray(): array;
    
    //Magic Methods
    
    /**
     * 
     * Gets a data value.
     * 
     * @param string $key The requested data key.
     * 
     * @return mixed The data value.
     * 
     */
    public function __get($key);

    /**
     * 
     * Does a certain key exist in the data?
     * 
     * Note that this is slightly different from normal PHP isset(); it will
     * say the key is set, even if the key value is null or otherwise empty.
     * 
     * @param string $key The requested data key.
     *  
     */
    public function __isset($key): bool;

    /**
     * 
     * Sets a key value.
     * 
     * @param string $key The requested data key.
     * 
     * @param mixed $val The value to set the data to.
     * 
     */
    public function __set($key, $val): void;

    /**
     * 
     * Get the string representation of all the data and property 
     * (name & value pairs) for this record.
     * 
     * @return string string representation of all the data & property 
     *                (name & value pairs) for this record.
     * 
     */
    public function __toString(): string;

    /**
     * 
     * Removes a key and its value in the data.
     * 
     * @param string $key The requested data key.
     * 
     */
    public function __unset($key): void;
}

1	<?php
2	declare(strict_types=1);
3	namespace GDAO\Model;
4
5	/**
6	*
7	* Contains a list of methods that Record classes must implement.
8	*
9	* @copyright (c) 2022, Rotexsoft
10	*/
11	interface RecordInterface extends \ArrayAccess, \Countable, \IteratorAggregate
12	{
13	////////////////////////////////////////////////////////////////////////////
14	////////////////////////////////////////////////////////////////////////////
15	////
16	//// RECOMMENDATIONS
17	//// * Data for the record ([to be saved to the DB] or [as read from the DB])
18	//// should be stored in a property of the record class implementing this
19	//// interface. It could be an array, ArrayObject or any other suitable
20	//// data structure. Data from this property should be returned via
21	//// $this->getData() & $this->getDataByRef(). Data contained in this
22	//// property should be set via
23	//// $this->loadData($data_2_load, array $cols_2_load = array()).
24	//// For documentation purposes this property will be refered to as
25	//// $this->data (with an assumption that it is an array).
26	////
27	//// * Another property of the same data type as the one described above should
28	//// be present in the class implementing this interface. This property should
29	//// only be set the first time record data is fetched from the DB (it holds
30	//// a copy of the data initially loaded into the record from the DB). This
31	//// property's values should be compared with the values of the property
32	//// described above in order to be able to determine if the record's data
33	//// has changed (this should be implemented in $this->isChanged($col=null)).
34	//// Data from this property should be returned via $this->getInitialData()
35	//// & $this->getInitialDataByRef(). Data contained in this property should
36	//// be set ONCE via $this->loadData($data_2_load, array $cols_2_load = array())
37	//// the first time loadData is called on a record.
38	//// For documentation purposes this property will be refered to as
39	//// $this->initial_data (with an assumption that it is an array).
40	////
41	//// * Another property should be present in the class implementing this
42	//// interface. This property should hold data related to a record (ie.
43	//// has-many, has-one, belongs-to and has-many-through relationship data).
44	//// Data from this property should be returned via $this->getRelatedData()
45	//// & $this->getRelatedDataByRef(). Data contained in this property should
46	//// be set via $this->setRelatedData($key, $value).
47	//// For documentation purposes this property will be refered to as
48	//// $this->related_data (with an assumption that it is an array).
49	////
50	//// * Another property should be present in the class implementing this
51	//// interface. This property should hold other data for a record instance
52	//// (i.e. data not from any actual db column and not related data).
53	//// Data from this property should be returned via $this->getNonTableColAndNonRelatedData()
54	//// & $this->getNonTableColAndNonRelatedDataByRef().
55	//// For documentation purposes this property will be refered to as
56	//// $this->non_table_col_and_non_related_data (with an assumption that it is an array).
57	////
58	//// * A boolean property should be present in the class implementing this
59	//// interface. This property should be set to true if a record is new
60	//// (ie. its data has never been saved to the DB), else false.
61	//// For documentation purposes this property will be refered to as
62	//// $this->is_new.
63	////
64	//// * A property of type \GDAO\Model should be present in a class implementing
65	//// this interface. This is the model object that will perform database
66	//// operations on behalf of the record.
67	//// For documentation purposes this property will be refered to as
68	//// $this->model
69	////
70	////////////////////////////////////////////////////////////////////////////
71	////////////////////////////////////////////////////////////////////////////
72
73	/**
74	*
75	* @param array $data associative array of data to be loaded into this record.
76	* [
77	* 'col_name1'=>'value_for_col1',
78	* .............................,
79	* .............................,
80	* 'col_nameN'=>'value_for_colN'
81	* ]
82	* @param \GDAO\Model $model The model object that transfers data between the db and this record.
83	*/
84	public function __construct(array $data, \GDAO\Model $model);
85
86	/**
87	*
88	* Delete the record from the db.
89	*
90	* If deletion was successful and the primary key column for the record's db
91	* table is auto-incrementing, then unset the primary key field in the data
92	* contained in the record object.
93	*
94	* NOTE: data contained in the record include $this->data, $this->related_data
95	* and $this->initial_data.
96	*
97	* @param bool $set_record_objects_data_to_empty_array true to reset the record object's data to an empty array if db deletion was successful, false to keep record object's data
98	*
99	* @return bool true if record was successfully deleted from db or false if not
100	*
101	*/
102	public function delete($set_record_objects_data_to_empty_array=false): bool;	×
103
104	/**
105	*
106	* Get the data for this record.
107	* Modifying the returned data will not affect the data inside this record.
108	*
109	* @return array a copy of the current data for this record
110	*/
111	public function getData(): array;
112
113	/**
114	*
115	* Get a copy of the initial data loaded into this record.
116	* Modifying the returned data will not affect the initial data inside this record.
117	*
118	* @return array a copy of the initial data loaded into this record.
119	*/
120	public function getInitialData(): array;
121
122
123	/**
124	*
125	* Get all the related data loaded into this record.
126	* Modifying the returned data will not affect the related data inside this record.
127	*
128	* @return array a reference to all the related data loaded into this record.
129	*/
130	public function getRelatedData(): array;
131
132	/**
133	*
134	* Get data for this record that does not belong to any of it's table columns and is not related data.
135	*
136	* @return array Data for this record (not to be saved to the db i.e. not from any actual db column and not related data).
137	*/
138	public function getNonTableColAndNonRelatedData(): array;
139
140	/**
141	*
142	* Get a reference to the data for this record.
143	* Modifying the returned data will affect the data inside this record.
144	*
145	* @return array a reference to the current data for this record.
146	*/
147	public function &getDataByRef(): array;
148
149	/**
150	*
151	* Get a reference to the initial data loaded into this record.
152	* Modifying the returned data will affect the initial data inside this record.
153	*
154	* @return array a reference to the initial data loaded into this record.
155	*/
156	public function &getInitialDataByRef(): array;
157
158	/**
159	*
160	* Get a reference to all the related data loaded into this record.
161	* Modifying the returned data will affect the related data inside this record.
162	*
163	* @return array a reference to all the related data loaded into this record.
164	*/
165	public function &getRelatedDataByRef(): array;
166
167	/**
168	*
169	* Get data for this record that does not belong to any of it's table columns and is not related data.
170	*
171	* @return array reference to the data for this record (not from any actual db column and not related data).
172	*/
173	public function &getNonTableColAndNonRelatedDataByRef(): array;
174
175	/**
176	*
177	* Set relation data for this record.
178	*
179	* @param string $key relation name
180	* @param mixed $value an array or record or collection containing related data
181	*
182	* @throws \GDAO\Model\RecordRelationWithSameNameAsAnExistingDBTableColumnNameException
183	*
184	* @return $this
185	*/
186	public function setRelatedData($key, $value): self;
187
188	/**
189	*
190	* Get the model object that saves and reads data to and from the db on
191	* behalf of this record
192	*/
193	public function getModel(): \GDAO\Model;
194
195	/**
196	*
197	* @return string name of the primary-key column of the db table this record belongs to
198	*/
199	public function getPrimaryCol(): string;
200
201	/**
202	*
203	* @return mixed the value stored in the primary-key column for this record.
204	*/
205	public function getPrimaryVal();
206
207	/**
208	*
209	* Tells if the record, or a particular table-column in the record, has
210	* changed from its initial value.
211	*
212	* @param string $col The table-column name.
213	*
214	* @return null\|bool Returns null if the table-column name does not exist,
215	* boolean true if the data is changed, boolean false if not changed.
216	*
217	*/
218	public function isChanged($col = null): ?bool;	×
219
220	/**
221	*
222	* Is the record new? (I.e. its data has never been saved to the db)
223	*
224	*/
225	public function isNew(): bool;
226
227	/**
228	*
229	* This method partially or completely overwrites pre-existing data for a
230	* record and replaces it with the new data (this does not include related
231	* data). If no data has previously been loaded into the record, keep a copy
232	* of the loaded data for comparison in $this->isChanged($col=null)).
233	*
234	* Note if $cols_2_load === null all data should be replaced, else only
235	* replace data for the cols in $cols_2_load.
236	*
237	* If $data_2_load is an instance of \GDAO\Model\RecordInterface and if
238	* $data_2_load->getModel()->getTableName() !== $this->getModel()->getTableName(),
239	* then the exception below should be thrown:
240	*
241	* \GDAO\Model\LoadingDataFromInvalidSourceIntoRecordException
242	*
243	* @param \GDAO\Model\RecordInterface\|array $data_2_load
244	* @param array $cols_2_load name of field to load from $data_2_load.
245	* If empty, load all fields in $data_2_load.
246	*
247	* @throws \GDAO\Model\LoadingDataFromInvalidSourceIntoRecordException
248	*
249	* @return $this
250	*/
251	public function loadData($data_2_load, array $cols_2_load = []): self;	×
252
253	/**
254	*
255	* Set the _is_new attribute of this record to true (meaning that the data
256	* for this record has never been saved to the db).
257	*
258	* @return $this
259	*/
260	public function markAsNew(): self;
261
262	/**
263	*
264	* Set the _is_new attribute of this record to false (meaning that the data
265	* for this record has been saved to the db or was read from the db).
266	*
267	* @return $this
268	*/
269	public function markAsNotNew(): self;
270
271	/**
272	* Set all properties of this record to the state they should be in for a new record.
273	* For example:
274	* - unset its primary key value via unset($this[$this->getPrimaryCol()]);
275	* - call $this->markAsNew()
276	* - etc.
277	*
278	* The _data & _initial_data properties can be updated as needed by the
279	* implementing sub-class.
280	* For example:
281	* - they could be left as is
282	* - or the value of _data could be copied to _initial_data
283	* - or the value of _initial_data could be copied to _data
284	* - etc.
285	*
286	* @return $this
287	*/
288	public function setStateToNew(): self;
289
290	/**
291	*
292	* Save the specified or already existing data for this record to the db.
293	* Since this record can only talk to the db via its model property (_model)
294	* the save operation will actually be done via $this->model.
295	*
296	* @param \GDAO\Model\RecordInterface\|array $data_2_save
297	*
298	* @return null\|bool true: successful save, false: failed save, null: no changed data to save
299	*
300	*/
301	public function save($data_2_save = null): ?bool;	×
302
303	/**
304	*
305	* Save the specified or already existing data for this record to the db.
306	* Since this record can only talk to the db via its model property (_model)
307	* the save operation will actually be done via $this->model.
308	* This save operation shoould be gaurded by the PDO transaction mechanism
309	* if available or another transaction mechanism. If the save operation
310	* fails all changes should be rolled back. If there is not transaction
311	* mechanism available an Exception must be thrown alerting the caller to
312	* use the save method instead.
313	*
314	* @param \GDAO\Model\RecordInterface\|array $data_2_save
315	*
316	* @return bool\|null true for a successful save, false for failed save, null: no changed data to save
317	*
318	*/
319	public function saveInTransaction($data_2_save = null): ?bool;	×
320
321	/**
322	*
323	* Set the \GDAO\Model object for this record
324	*
325	* @param \GDAO\Model $model
326	*
327	* @return $this
328	*/
329	public function setModel(\GDAO\Model $model): self;
330
331	/**
332	*
333	* Get all the data and property (name & value pairs) for this record.
334	*
335	* @return array of all data & property (name & value pairs) for this record.
336	*
337	*/
338	public function toArray(): array;
339
340	//Magic Methods
341
342	/**
343	*
344	* Gets a data value.
345	*
346	* @param string $key The requested data key.
347	*
348	* @return mixed The data value.
349	*
350	*/
351	public function __get($key);
352
353	/**
354	*
355	* Does a certain key exist in the data?
356	*
357	* Note that this is slightly different from normal PHP isset(); it will
358	* say the key is set, even if the key value is null or otherwise empty.
359	*
360	* @param string $key The requested data key.
361	*
362	*/
363	public function __isset($key): bool;
364
365	/**
366	*
367	* Sets a key value.
368	*
369	* @param string $key The requested data key.
370	*
371	* @param mixed $val The value to set the data to.
372	*
373	*/
374	public function __set($key, $val): void;
375
376	/**
377	*
378	* Get the string representation of all the data and property
379	* (name & value pairs) for this record.
380	*
381	* @return string string representation of all the data & property
382	* (name & value pairs) for this record.
383	*
384	*/
385	public function __toString(): string;
386
387	/**
388	*
389	* Removes a key and its value in the data.
390	*
391	* @param string $key The requested data key.
392	*
393	*/
394	public function __unset($key): void;
395	}

rotexsoft / gdao / 3722570167

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous