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/CollectionInterface.php

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

/**
 * 
 * Represents a collection of \GDAO\Model\RecordInterface objects.
 *
 * @author Rotimi Adegbamigbe
 * @copyright (c) 2022, Rotexsoft
 * 
 */
interface CollectionInterface extends \ArrayAccess, \Countable, \IteratorAggregate
{
    ////////////////////////////////////////////////////////////////////////////
    ////////////////////////////////////////////////////////////////////////////
    ////
    //// RECOMMENDATIONS
    //// * Data for the collection should be stored in a property of the collection 
    ////   class implementing this interface. It could be an array, ArrayObject, 
    ////   SPLFixedArray or any other suitable data structure.
    ////   
    //// * 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 collection.
    ////   
    ////////////////////////////////////////////////////////////////////////////
    ////////////////////////////////////////////////////////////////////////////    
    
    /**
     * 
     * @param \GDAO\Model $model The model object that transfers data between the db and this collection.
     * @param \GDAO\Model\RecordInterface[] $data instances of \GDAO\Model\RecordInterface
     */
    public function __construct(
        \GDAO\Model $model, \GDAO\Model\RecordInterface ...$data
    );
    
    /**
     * 
     * Deletes each record in the collection from the database, but leaves the
     * record objects with their data inside the collection object.
     * 
     * Call $this->removeAll() to empty the collection of the record objects.
     * 
     * @return bool|array true if all records were successfully deleted or an
     *                    array of keys in the collection for the records that 
     *                    couldn't be successfully deleted. It's most likely a 
     *                    PDOException would be thrown if the deletion failed.
     * 
     * @throws \PDOException 
     * 
     */
    public function deleteAll();
    
    /**
     * 
     * Returns an array of all values for a single column in the collection.
     *
     * @param string $col The column name to retrieve values for.
     *
     * @return array An array of key-value pairs where the key is the collection 
     *               element key, and the value is the column value for that
     *               element.
     * 
     */
    public function getColVals($col): array;
    
    /**
     * 
     * Returns all the keys for this collection.
     * 
     * @return array<string|int, string|int>
     */
    public function getKeys(): array;
    
    /**
     * 
     * Returns the model from which the data originates.
     * 
     * @return \GDAO\Model The origin model object.
     * 
     */
    public function getModel(): \GDAO\Model;
    
    /**
     * 
     * Are there any records in the collection?
     * 
     * @return bool True if empty, false if not.
     * 
     */
    public function isEmpty(): bool;
    
    /**
     * 
     * Load the collection with one or more records.
     * 
     * @param \GDAO\Model\RecordInterface[] $data_2_load
     * 
     */
    public function loadData(\GDAO\Model\RecordInterface ...$data_2_load): self;
    
    
    /**
     * 
     * Removes all records from the collection but **does not** delete them
     * from the database.
     * 
     */
    public function removeAll():self;

    /**
     * 
     * Saves all the records from this collection to the database one-by-one,
     * inserting or updating as needed. 
     * 
     * For better performance, it can gather all records for inserts together
     * and then perform a single insert of multiple rows with one sql operation.
     * 
     * Updates cannot be batched together (they must be performed one-by-one) 
     * because there seems to be no neat update equivalent for bulk inserts:
     * 
     * example bulk insert:
     * 
     *      INSERT INTO mytable
     *                 (id, title)
     *          VALUES ('1', 'Lord of the Rings'),
     *                 ('2', 'Harry Potter');
     * 
     * @param bool $group_inserts_together true to group all records to be 
     *                                     inserted together in order to perform 
     *                                     a single sql insert operation, false
     *                                     to perform one-by-one inserts.
     * 
     * @return bool|array true if all inserts and updates were successful or
     *                    return an array of keys in the collection for the 
     *                    records that couldn't be successfully inserted or
     *                    updated. It's most likely a PDOException would be
     *                    thrown if an insert or update fails.
     * 
     * @throws \PDOException
     * 
     */
    public function saveAll($group_inserts_together=false);
    
    /**
     * 
     * Injects the model from which the data originates.
     * 
     * @param \GDAO\Model $model The origin model object.
     * 
     */
    public function setModel(\GDAO\Model $model): self;
    
    /**
     * 
     * Returns an array representation of an instance of this class.
     * 
     * @return array an array representation of an instance of this class.
     * 
     */
    public function toArray(): array;
    
    /**
     * 
     * Returns a record from the collection based on its key value.
     * 
     * @param int|string $key The sequential or associative key value for the
     *                        record.
     * 
     */
    public function __get($key): \GDAO\Model\RecordInterface;

    /**
     * 
     * Does a certain key exist in the data?
     * 
     * @param string $key The requested data key.
     * 
     */
    public function __isset($key): bool;

    /**
     * 
     * Set a key value.
     * 
     * @param string $key The requested key.
     * @param \GDAO\Model\RecordInterface $val The value to set it to.
     * 
     */
    public function __set($key, \GDAO\Model\RecordInterface $val): void;

    /**
     * 
     * ArrayAccess: set a key value; appends to the array when using []
     * notation.
     * 
     * NOTE: Implementers of this class must make sure that $val is an instance 
     *       of \GDAO\Model\RecordInterface else throw a 
     *       \GDAO\Model\CollectionCanOnlyContainGDAORecordsException exception.
     * 
     * @param string $key The requested key.
     * 
     * @param \GDAO\Model\RecordInterface $val The value to set it to.
     * 
     * @throws \GDAO\Model\CollectionCanOnlyContainGDAORecordsException
     * 
     */
    public function offsetSet($key, $val): void;
    
    /**
     * 
     * Returns a string representation of an instance of this class.
     * 
     * @return string a string representation of an instance of this class.
     * 
     */
    public function __toString(): string;

    /**
     * 
     * Removes a record with the specified key from the collection.
     * 
     * @param string $key The requested data key.
     * 
     */
    public function __unset($key): void;
    
    //Hooks
    
    /**
     * 
     * User-defined pre-delete logic.
     * 
     * Implementers of this class should add a call to this method as the 
     * first line of code in their implementation of $this->deleteAll()
     * 
     */
    public function preDeleteAll(): void;
    
    /**
     * 
     * User-defined post-delete logic.
     * 
     * Implementers of this class should add a call to this method as the 
     * last line of code in their implementation of $this->deleteAll()
     * 
     */
    public function postDeleteAll(): void;
    
    /**
     * 
     * User-defined pre-save logic for the collection.
     * 
     * Implementers of this class should add a call to this method as the 
     * first line of code in their implementation of $this->save(...)
     * 
     */
    public function preSaveAll(bool $group_inserts_together=false): void;
    
    /**
     * 
     * User-defined post-save logic for the collection.
     * 
     * Implementers of this class should add a call to this method as the 
     * last line of code in their implementation of $this->save(...)
     * 
     * @param bool|array $save_all_result result returned from $this->saveAll(..)
     * @param bool $group_inserts_together exact value passed to $this->saveAll($group_inserts_together)
     */
    public function postSaveAll($save_all_result, bool $group_inserts_together=false): void;
}

1	<?php
2	declare(strict_types=1);
3	namespace GDAO\Model;
4
5	/**
6	*
7	* Represents a collection of \GDAO\Model\RecordInterface objects.
8	*
9	* @author Rotimi Adegbamigbe
10	* @copyright (c) 2022, Rotexsoft
11	*
12	*/
13	interface CollectionInterface extends \ArrayAccess, \Countable, \IteratorAggregate
14	{
15	////////////////////////////////////////////////////////////////////////////
16	////////////////////////////////////////////////////////////////////////////
17	////
18	//// RECOMMENDATIONS
19	//// * Data for the collection should be stored in a property of the collection
20	//// class implementing this interface. It could be an array, ArrayObject,
21	//// SPLFixedArray or any other suitable data structure.
22	////
23	//// * A property of type \GDAO\Model should be present in a class implementing
24	//// this interface. This is the model object that will perform database
25	// operations on behalf of the collection.
26	////
27	////////////////////////////////////////////////////////////////////////////
28	////////////////////////////////////////////////////////////////////////////
29
30	/**
31	*
32	* @param \GDAO\Model $model The model object that transfers data between the db and this collection.
33	* @param \GDAO\Model\RecordInterface[] $data instances of \GDAO\Model\RecordInterface
34	*/
35	public function __construct(
36	\GDAO\Model $model, \GDAO\Model\RecordInterface ...$data
37	);	×
38
39	/**
40	*
41	* Deletes each record in the collection from the database, but leaves the
42	* record objects with their data inside the collection object.
43	*
44	* Call $this->removeAll() to empty the collection of the record objects.
45	*
46	* @return bool\|array true if all records were successfully deleted or an
47	* array of keys in the collection for the records that
48	* couldn't be successfully deleted. It's most likely a
49	* PDOException would be thrown if the deletion failed.
50	*
51	* @throws \PDOException
52	*
53	*/
54	public function deleteAll();
55
56	/**
57	*
58	* Returns an array of all values for a single column in the collection.
59	*
60	* @param string $col The column name to retrieve values for.
61	*
62	* @return array An array of key-value pairs where the key is the collection
63	* element key, and the value is the column value for that
64	* element.
65	*
66	*/
67	public function getColVals($col): array;
68
69	/**
70	*
71	* Returns all the keys for this collection.
72	*
73	* @return array<string\|int, string\|int>
74	*/
75	public function getKeys(): array;
76
77	/**
78	*
79	* Returns the model from which the data originates.
80	*
81	* @return \GDAO\Model The origin model object.
82	*
83	*/
84	public function getModel(): \GDAO\Model;
85
86	/**
87	*
88	* Are there any records in the collection?
89	*
90	* @return bool True if empty, false if not.
91	*
92	*/
93	public function isEmpty(): bool;
94
95	/**
96	*
97	* Load the collection with one or more records.
98	*
99	* @param \GDAO\Model\RecordInterface[] $data_2_load
100	*
101	*/
102	public function loadData(\GDAO\Model\RecordInterface ...$data_2_load): self;
103
104
105	/**
106	*
107	* Removes all records from the collection but does not delete them
108	* from the database.
109	*
110	*/
111	public function removeAll():self;
112
113	/**
114	*
115	* Saves all the records from this collection to the database one-by-one,
116	* inserting or updating as needed.
117	*
118	* For better performance, it can gather all records for inserts together
119	* and then perform a single insert of multiple rows with one sql operation.
120	*
121	* Updates cannot be batched together (they must be performed one-by-one)
122	* because there seems to be no neat update equivalent for bulk inserts:
123	*
124	* example bulk insert:
125	*
126	* INSERT INTO mytable
127	* (id, title)
128	* VALUES ('1', 'Lord of the Rings'),
129	* ('2', 'Harry Potter');
130	*
131	* @param bool $group_inserts_together true to group all records to be
132	* inserted together in order to perform
133	* a single sql insert operation, false
134	* to perform one-by-one inserts.
135	*
136	* @return bool\|array true if all inserts and updates were successful or
137	* return an array of keys in the collection for the
138	* records that couldn't be successfully inserted or
139	* updated. It's most likely a PDOException would be
140	* thrown if an insert or update fails.
141	*
142	* @throws \PDOException
143	*
144	*/
145	public function saveAll($group_inserts_together=false);	×
146
147	/**
148	*
149	* Injects the model from which the data originates.
150	*
151	* @param \GDAO\Model $model The origin model object.
152	*
153	*/
154	public function setModel(\GDAO\Model $model): self;
155
156	/**
157	*
158	* Returns an array representation of an instance of this class.
159	*
160	* @return array an array representation of an instance of this class.
161	*
162	*/
163	public function toArray(): array;
164
165	/**
166	*
167	* Returns a record from the collection based on its key value.
168	*
169	* @param int\|string $key The sequential or associative key value for the
170	* record.
171	*
172	*/
173	public function __get($key): \GDAO\Model\RecordInterface;
174
175	/**
176	*
177	* Does a certain key exist in the data?
178	*
179	* @param string $key The requested data key.
180	*
181	*/
182	public function __isset($key): bool;
183
184	/**
185	*
186	* Set a key value.
187	*
188	* @param string $key The requested key.
189	* @param \GDAO\Model\RecordInterface $val The value to set it to.
190	*
191	*/
192	public function __set($key, \GDAO\Model\RecordInterface $val): void;
193
194	/**
195	*
196	* ArrayAccess: set a key value; appends to the array when using []
197	* notation.
198	*
199	* NOTE: Implementers of this class must make sure that $val is an instance
200	* of \GDAO\Model\RecordInterface else throw a
201	* \GDAO\Model\CollectionCanOnlyContainGDAORecordsException exception.
202	*
203	* @param string $key The requested key.
204	*
205	* @param \GDAO\Model\RecordInterface $val The value to set it to.
206	*
207	* @throws \GDAO\Model\CollectionCanOnlyContainGDAORecordsException
208	*
209	*/
210	public function offsetSet($key, $val): void;
211
212	/**
213	*
214	* Returns a string representation of an instance of this class.
215	*
216	* @return string a string representation of an instance of this class.
217	*
218	*/
219	public function __toString(): string;
220
221	/**
222	*
223	* Removes a record with the specified key from the collection.
224	*
225	* @param string $key The requested data key.
226	*
227	*/
228	public function __unset($key): void;
229
230	//Hooks
231
232	/**
233	*
234	* User-defined pre-delete logic.
235	*
236	* Implementers of this class should add a call to this method as the
237	* first line of code in their implementation of $this->deleteAll()
238	*
239	*/
240	public function preDeleteAll(): void;
241
242	/**
243	*
244	* User-defined post-delete logic.
245	*
246	* Implementers of this class should add a call to this method as the
247	* last line of code in their implementation of $this->deleteAll()
248	*
249	*/
250	public function postDeleteAll(): void;
251
252	/**
253	*
254	* User-defined pre-save logic for the collection.
255	*
256	* Implementers of this class should add a call to this method as the
257	* first line of code in their implementation of $this->save(...)
258	*
259	*/
260	public function preSaveAll(bool $group_inserts_together=false): void;	×
261
262	/**
263	*
264	* User-defined post-save logic for the collection.
265	*
266	* Implementers of this class should add a call to this method as the
267	* last line of code in their implementation of $this->save(...)
268	*
269	* @param bool\|array $save_all_result result returned from $this->saveAll(..)
270	* @param bool $group_inserts_together exact value passed to $this->saveAll($group_inserts_together)
271	*/
272	public function postSaveAll($save_all_result, bool $group_inserts_together=false): void;	×
273	}

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