6758244680

Committed 05 Sep 2023 08:29PM UTC coverage: 97.059% (-2.9%) from 100.0%

Build Type

push

github

Committed by rotimi

Commit Message

PHP 8.1 minimum version readiness

Run Details

66 of 68 relevant lines covered (97.06%)

11.12 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;

/**
 * @psalm-suppress MissingTemplateParam
 * 
 * Represents a collection of \GDAO\Model\RecordInterface objects.
 *
 * @author Rotimi Adegbamigbe
 * @copyright (c) 2023, Rotexsoft
 * 
 */
interface CollectionInterface extends \ArrayAccess, \Countable, \IteratorAggregate, \Stringable
{
    ////////////////////////////////////////////////////////////////////////////
    ////////////////////////////////////////////////////////////////////////////
    ////
    //// 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(): bool|array;
    
    /**
     * 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(string $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): static;
    
    /**
     * Removes all records from the collection but **does not** delete them
     * from the database.
     */
    public function removeAll(): static;

    /**
     * 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(bool $group_inserts_together=false): bool|array;
    
    /**
     * Injects the model from which the data originates.
     * 
     * @param \GDAO\Model $model The origin model object.
     */
    public function setModel(\GDAO\Model $model): static;
    
    /**
     * 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 mixed $key The requested key.
     * 
     * @param \GDAO\Model\RecordInterface $val The value to set it to.
     * 
     * @throws \GDAO\Model\CollectionCanOnlyContainGDAORecordsException
     */
    public function offsetSet(mixed $key, mixed $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;
    
    /**
     * 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(bool|array $save_all_result, bool $group_inserts_together=false): void;
}

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

rotexsoft / gdao / 6758244680

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