Rev 58 | Go to most recent revision | Only display areas with differences | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed
| Rev 58 | Rev 61 | ||
|---|---|---|---|
| 1 | <?php
|
1 | <?php
|
| 2 | 2 | ||
| 3 | namespace PointedEars\PHPX\Db; |
3 | namespace PointedEars\PHPX\Db; |
| 4 | 4 | ||
| 5 | use \PointedEars\PHPX\Application; |
5 | use \PointedEars\PHPX\Application; |
| 6 | 6 | ||
| 7 | /**
|
7 | /**
|
| 8 | * Generic database table model class
|
8 | * Generic database table model class
|
| 9 | *
|
9 | *
|
| 10 | * @author Thomas Lahn
|
10 | * @author Thomas Lahn
|
| 11 | * @property Database $database
|
11 | * @property Database $database
|
| 12 | * @property-read int $lastInsertId
|
12 | * @property-read int $lastInsertId
|
| 13 | * ID of the last inserted row, or the last value from
|
13 | * ID of the last inserted row, or the last value from
|
| 14 | a sequence object, depending on the underlying driver.
|
14 | a sequence object, depending on the underlying driver.
|
| 15 | */
|
15 | */
|
| 16 | class Table extends \PointedEars\PHPX\AbstractModel |
16 | class Table extends \PointedEars\PHPX\AbstractModel |
| 17 | {
|
17 | {
|
| 18 | /**
|
18 | /**
|
| 19 | * Name of the table
|
19 | * Name of the table
|
| 20 | * @var string
|
20 | * @var string
|
| 21 | */
|
21 | */
|
| 22 | protected static $_name = ''; |
22 | protected static $_name = ''; |
| 23 | 23 | ||
| 24 | /**
|
24 | /**
|
| 25 | * Columns definition
|
25 | * Columns definition
|
| 26 | * @var array
|
26 | * @var array
|
| 27 | * @see Table::create()
|
27 | * @see Table::create()
|
| 28 | */
|
28 | */
|
| 29 | protected static $_columns; |
29 | protected static $_columns; |
| 30 | 30 | ||
| 31 | /**
|
31 | /**
|
| 32 | * Indexes definition
|
32 | * Indexes definition
|
| 33 | * @var array
|
33 | * @var array
|
| 34 | * @see Table::create()
|
34 | * @see Table::create()
|
| 35 | */
|
35 | */
|
| 36 | protected static $_indexes; |
36 | protected static $_indexes; |
| 37 | 37 | ||
| 38 | /**
|
38 | /**
|
| 39 | * Constraints definition
|
39 | * Constraints definition
|
| 40 | * @var array
|
40 | * @var array
|
| 41 | * @see Table::create()
|
41 | * @see Table::create()
|
| 42 | */
|
42 | */
|
| 43 | protected static $_constraints; |
43 | protected static $_constraints; |
| 44 | 44 | ||
| 45 | /**
|
45 | /**
|
| 46 | * Database of the table
|
46 | * Database of the table
|
| 47 | * @var Database|string
|
47 | * @var Database|string
|
| 48 | * @see Table::create()
|
48 | * @see Table::create()
|
| 49 | */
|
49 | */
|
| 50 | protected static $_database; |
50 | protected static $_database; |
| 51 | 51 | ||
| 52 | /**
|
52 | /**
|
| 53 | * Name of the primary key column of the table
|
53 | * Name of the primary key column of the table
|
| 54 | * @var string
|
54 | * @var string
|
| 55 | */
|
55 | */
|
| 56 | protected static $_id = 'id'; |
56 | protected static $_id = 'id'; |
| 57 | 57 | ||
| 58 | /**
|
58 | /**
|
| 59 | * Creates a new <code>Table</code> instance.
|
59 | * Creates a new <code>Table</code> instance.
|
| 60 | *
|
60 | *
|
| 61 | * Each of the parameters is optional and can also be given
|
61 | * Each of the parameters is optional and can also be given
|
| 62 | * by a protected property where the parameter name is preceded
|
62 | * by a protected property where the parameter name is preceded
|
| 63 | * by <code>_</code>. Parameter values overwrite the default
|
63 | * by <code>_</code>. Parameter values overwrite the default
|
| 64 | * property values. It is recommended to use default property
|
64 | * property values. It is recommended to use default property
|
| 65 | * values of inheriting classes except for small applications
|
65 | * values of inheriting classes except for small applications
|
| 66 | * and testing purposes.
|
66 | * and testing purposes.
|
| 67 | *
|
67 | *
|
| 68 | * @param Database $database
|
68 | * @param Database $database
|
| 69 | * Database of the table (required in order to use a fitting
|
69 | * Database of the table (required in order to use a fitting
|
| 70 | * query language)
|
70 | * query language)
|
| 71 | * @param string $name
|
71 | * @param string $name
|
| 72 | * Table name
|
72 | * Table name
|
| 73 | * @param string $id
|
73 | * @param string $id
|
| 74 | * Name of the primary key column
|
74 | * Name of the primary key column
|
| 75 | * @throws InvalidArgumentException
|
75 | * @throws InvalidArgumentException
|
| 76 | */
|
76 | */
|
| 77 | public function __construct ($database = null, $name = '', $id = '') |
77 | public function __construct ($database = null, $name = '', $id = '') |
| 78 | {
|
78 | {
|
| 79 | if ($database === null) |
79 | if ($database === null) |
| 80 | {
|
80 | {
|
| 81 | /* Call getter to convert to Database if possible */
|
81 | /* Call getter to convert to Database if possible */
|
| 82 | if ($this->database === null) |
82 | if ($this->database === null) |
| 83 | {
|
83 | {
|
| 84 | $this->database = Application::getInstance()->getDefaultDatabase(); |
84 | $this->database = Application::getInstance()->getDefaultDatabase(); |
| 85 | }
|
85 | }
|
| 86 | }
|
86 | }
|
| 87 | else
|
87 | else
|
| 88 | {
|
88 | {
|
| 89 | $this->database = $database; |
89 | $this->database = $database; |
| 90 | }
|
90 | }
|
| 91 | 91 | ||
| 92 | if ($name !== '') |
92 | if ($name !== '') |
| 93 | {
|
93 | {
|
| 94 | $this->name = $name; |
94 | $this->name = $name; |
| 95 | }
|
95 | }
|
| 96 | 96 | ||
| 97 | $name = $this->name; |
97 | $name = $this->name; |
| 98 | if (!\is_string($name)) |
98 | if (!\is_string($name)) |
| 99 | {
|
99 | {
|
| 100 | throw new \InvalidArgumentException( |
100 | throw new \InvalidArgumentException( |
| 101 | 'Expected string for table name, saw '
|
101 | 'Expected string for table name, saw '
|
| 102 | . (\is_object($name) ? \get_class($name) : \gettype($name))); |
102 | . (\is_object($name) ? \get_class($name) : \gettype($name))); |
| 103 | }
|
103 | }
|
| 104 | 104 | ||
| 105 | if ($id !== '') |
105 | if ($id !== '') |
| 106 | {
|
106 | {
|
| 107 | $this->id = $id; |
107 | $this->id = $id; |
| 108 | }
|
108 | }
|
| 109 | }
|
109 | }
|
| 110 | 110 | ||
| 111 | /**
|
111 | /**
|
| 112 | * @param string $value
|
112 | * @param string $value
|
| 113 | */
|
113 | */
|
| 114 | public function setName ($value) |
114 | public function setName ($value) |
| 115 | {
|
115 | {
|
| 116 | $class = \get_class($this); |
116 | $class = \get_class($this); |
| 117 | $class::$_name = (string) $value; |
117 | $class::$_name = (string) $value; |
| 118 | }
|
118 | }
|
| 119 | 119 | ||
| 120 | /**
|
120 | /**
|
| 121 | * @return string
|
121 | * @return string
|
| 122 | */
|
122 | */
|
| 123 | public function getName () |
123 | public function getName () |
| 124 | {
|
124 | {
|
| 125 | $class = \get_class($this); |
125 | $class = \get_class($this); |
| 126 | return $class::$_name; |
126 | return $class::$_name; |
| 127 | }
|
127 | }
|
| 128 | 128 | ||
| 129 | /**
|
129 | /**
|
| 130 | * Returns the database for the table
|
130 | * Returns the database for the table
|
| 131 | * @return Database
|
131 | * @return Database
|
| 132 | */
|
132 | */
|
| 133 | public function getDatabase() |
133 | public function getDatabase() |
| 134 | {
|
134 | {
|
| 135 | $class = \get_class($this); |
135 | $class = \get_class($this); |
| 136 | if (\is_string($class::$_database)) |
136 | if (\is_string($class::$_database)) |
| 137 | {
|
137 | {
|
| 138 | /* Call setter to convert to Database */
|
138 | /* Call setter to convert to Database */
|
| 139 | $this->setDatabase($class::$_database); |
139 | $this->setDatabase($class::$_database); |
| 140 | }
|
140 | }
|
| 141 | 141 | ||
| 142 | return $class::$_database; |
142 | return $class::$_database; |
| 143 | }
|
143 | }
|
| 144 | 144 | ||
| 145 | /**
|
145 | /**
|
| 146 | * @param Database|string $value
|
146 | * @param Database|string $value
|
| 147 | * @throws InvalidArgumentException
|
147 | * @throws InvalidArgumentException
|
| 148 | */
|
148 | */
|
| 149 | public function setDatabase ($value) |
149 | public function setDatabase ($value) |
| 150 | {
|
150 | {
|
| 151 | $class = \get_class($this); |
151 | $class = \get_class($this); |
| 152 | if ($value instanceof Database) |
152 | if ($value instanceof Database) |
| 153 | {
|
153 | {
|
| 154 | $class::$_database = $value; |
154 | $class::$_database = $value; |
| 155 | }
|
155 | }
|
| 156 | else if ($value !== null) |
156 | else if ($value !== null) |
| 157 | {
|
157 | {
|
| 158 | $database = new $value(); |
158 | $database = new $value(); |
| 159 | if (!($database instanceof Database)) |
159 | if (!($database instanceof Database)) |
| 160 | {
|
160 | {
|
| 161 | throw new \InvalidArgumentException( |
161 | throw new \InvalidArgumentException( |
| 162 | 'Expected Database instance or string for class name, saw '
|
162 | 'Expected Database instance or string for class name, saw '
|
| 163 | . (\is_object($value) ? \get_class($value) : \gettype($value)) |
163 | . (\is_object($value) ? \get_class($value) : \gettype($value)) |
| 164 | ); |
164 | ); |
| 165 | }
|
165 | }
|
| 166 | 166 | ||
| 167 | $class::$_database = $database; |
167 | $class::$_database = $database; |
| 168 | }
|
168 | }
|
| 169 | }
|
169 | }
|
| 170 | 170 | ||
| 171 | /**
|
171 | /**
|
| 172 | * @param string $value
|
172 | * @param string $value
|
| 173 | */
|
173 | */
|
| 174 | public function setId ($value) |
174 | public function setId ($value) |
| 175 | {
|
175 | {
|
| 176 | $class = \get_class($this); |
176 | $class = \get_class($this); |
| 177 | $class::$_id = (string) $value; |
177 | $class::$_id = (string) $value; |
| 178 | }
|
178 | }
|
| 179 | 179 | ||
| 180 | /**
|
180 | /**
|
| 181 | * @return string
|
181 | * @return string
|
| 182 | */
|
182 | */
|
| 183 | public function getId () |
183 | public function getId () |
| 184 | {
|
184 | {
|
| 185 | $class = \get_class($this); |
185 | $class = \get_class($this); |
| 186 | return $class::$_id; |
186 | return $class::$_id; |
| 187 | }
|
187 | }
|
| 188 | 188 | ||
| 189 | /**
|
189 | /**
|
| 190 | * Returns the <var>options</var> array for {@link Database::createTable}
|
190 | * Returns the <var>options</var> array for {@link Database::createTable}
|
| 191 | *
|
191 | *
|
| 192 | * Should be called and overridden by inheriting classes.
|
192 | * Should be called and overridden by inheriting classes.
|
| 193 | *
|
193 | *
|
| 194 | * @return array
|
194 | * @return array
|
| 195 | */
|
195 | */
|
| 196 | protected function _createOptions () |
196 | protected function _createOptions () |
| 197 | {
|
197 | {
|
| 198 | $options = array(); |
198 | $options = array(); |
| 199 | 199 | ||
| 200 | foreach (array('indexes', 'constraints') as $option) |
200 | foreach (array('indexes', 'constraints') as $option) |
| 201 | {
|
201 | {
|
| 202 | if ($class::${"_$option"}) |
202 | if ($class::${"_$option"}) |
| 203 | {
|
203 | {
|
| 204 | $options[$option] = $class::${"_$option"}; |
204 | $options[$option] = $class::${"_$option"}; |
| 205 | }
|
205 | }
|
| 206 | }
|
206 | }
|
| 207 | 207 | ||
| 208 | return $options; |
208 | return $options; |
| 209 | }
|
209 | }
|
| 210 | 210 | ||
| 211 | /**
|
211 | /**
|
| 212 | * Creates the table for this model
|
212 | * Creates the table for this model
|
| 213 | *
|
213 | *
|
| 214 | * @return bool
|
214 | * @return bool
|
| 215 | */
|
215 | */
|
| 216 | public function create () |
216 | public function create () |
| 217 | {
|
217 | {
|
| 218 | $class = \get_class($this); |
218 | $class = \get_class($this); |
| 219 | return $this->database->createTable( |
219 | return $this->database->createTable( |
| 220 | $class::$_name, $class::$_columns, $this->_createOptions()); |
220 | $class::$_name, $class::$_columns, $this->_createOptions()); |
| 221 | }
|
221 | }
|
| 222 | 222 | ||
| 223 | /**
|
223 | /**
|
| 224 | * Initiates a transaction
|
224 | * Initiates a transaction
|
| 225 | *
|
225 | *
|
| 226 | * @return bool
|
226 | * @return bool
|
| 227 | * @see Database::beginTransaction()
|
227 | * @see Database::beginTransaction()
|
| 228 | */
|
228 | */
|
| 229 | public function beginTransaction() |
229 | public function beginTransaction() |
| 230 | {
|
230 | {
|
| 231 | return $this->database->beginTransaction(); |
231 | return $this->database->beginTransaction(); |
| 232 | }
|
232 | }
|
| 233 | 233 | ||
| 234 | /**
|
234 | /**
|
| 235 | * Rolls back a transaction
|
235 | * Rolls back a transaction
|
| 236 | *
|
236 | *
|
| 237 | * @return bool
|
237 | * @return bool
|
| 238 | * @see Database::rollBack()
|
238 | * @see Database::rollBack()
|
| 239 | */
|
239 | */
|
| 240 | public function rollBack() |
240 | public function rollBack() |
| 241 | {
|
241 | {
|
| 242 | return $this->database->rollBack(); |
242 | return $this->database->rollBack(); |
| 243 | }
|
243 | }
|
| 244 | 244 | ||
| 245 | /**
|
245 | /**
|
| 246 | * Commits a transaction
|
246 | * Commits a transaction
|
| 247 | *
|
247 | *
|
| 248 | * @return bool
|
248 | * @return bool
|
| 249 | * @see Database::commit()
|
249 | * @see Database::commit()
|
| 250 | */
|
250 | */
|
| 251 | public function commit() |
251 | public function commit() |
| 252 | {
|
252 | {
|
| 253 | return $this->database->commit(); |
253 | return $this->database->commit(); |
| 254 | }
|
254 | }
|
| 255 | 255 | ||
| 256 | /**
|
256 | /**
|
| 257 | * Retrieves all rows from the table
|
257 | * Retrieves all rows from the table
|
| 258 | *
|
258 | *
|
| 259 | * @return array
|
259 | * @return array
|
| 260 | * @see Database::fetchAll()
|
260 | * @see Database::fetchAll()
|
| 261 | */
|
261 | */
|
| 262 | public function fetchAll($fetch_style = null, $column_index = null, array $ctor_args = null) |
262 | public function fetchAll($fetch_style = null, $column_index = null, array $ctor_args = null) |
| 263 | {
|
263 | {
|
| 264 | return $this->database->fetchAll($this->name, $fetch_style, $column_index, $ctor_args); |
264 | return $this->database->fetchAll($this->name, $fetch_style, $column_index, $ctor_args); |
| 265 | }
|
265 | }
|
| 266 | 266 | ||
| 267 | /**
|
267 | /**
|
| 268 | * Selects data from one or more tables
|
268 | * Selects data from one or more tables
|
| 269 | *
|
269 | *
|
| 270 | * @return array
|
270 | * @return array
|
| 271 | * @see Database::select()
|
271 | * @see Database::select()
|
| 272 | */
|
272 | */
|
| 273 | public function select($columns = null, $where = null, $order = null, $limit = null) |
273 | public function select($columns = null, $where = null, $order = null, $limit = null) |
| 274 | {
|
274 | {
|
| 275 | return $this->database->select($this->name, $columns, $where, $order, $limit); |
275 | return $this->database->select($this->name, $columns, $where, $order, $limit); |
| 276 | }
|
276 | }
|
| 277 | 277 | ||
| 278 | /**
|
278 | /**
|
| 279 | * Updates records in one or more tables
|
279 | * Updates records in one or more tables
|
| 280 | *
|
280 | *
|
| 281 | * @return bool
|
281 | * @return bool
|
| 282 | * @see Database::update()
|
282 | * @see Database::update()
|
| 283 | */
|
283 | */
|
| 284 | public function update($data, $condition) |
284 | public function update($data, $condition) |
| 285 | {
|
285 | {
|
| 286 | return $this->database->update($this->name, $data, $condition); |
286 | return $this->database->update($this->name, $data, $condition); |
| 287 | }
|
287 | }
|
| 288 | 288 | ||
| 289 | /**
|
289 | /**
|
| 290 | * Inserts a record into the table
|
290 | * Inserts a record into the table
|
| 291 | *
|
291 | *
|
| 292 | * @return bool
|
292 | * @return bool
|
| 293 | * @see Database::insert()
|
293 | * @see Database::insert()
|
| 294 | */
|
294 | */
|
| 295 | public function insert($data, $cols = null) |
295 | public function insert($data, $cols = null) |
| 296 | {
|
296 | {
|
| 297 | return $this->database->insert($this->name, $data, $cols); |
297 | return $this->database->insert($this->name, $data, $cols); |
| 298 | }
|
298 | }
|
| 299 | 299 | ||
| 300 | /**
|
300 | /**
|
| 301 | * Returns the ID of the last inserted row, or the last value from
|
301 | * Returns the ID of the last inserted row, or the last value from
|
| 302 | * a sequence object, depending on the underlying driver.
|
302 | * a sequence object, depending on the underlying driver.
|
| 303 | *
|
303 | *
|
| 304 | * @return int
|
304 | * @return int
|
| 305 | * @see Database::getLastInsertId()
|
305 | * @see Database::getLastInsertId()
|
| 306 | */
|
306 | */
|
| 307 | public function getLastInsertId() |
307 | public function getLastInsertId() |
| 308 | {
|
308 | {
|
| 309 | return $this->database->lastInsertId; |
309 | return $this->database->lastInsertId; |
| 310 | }
|
310 | }
|
| 311 | 311 | ||
| 312 | /**
|
312 | /**
|
| 313 | * Delete a record from the table
|
313 | * Delete a record from the table
|
| 314 | *
|
314 | *
|
| 315 | * @param int $id
|
315 | * @param int $id
|
| 316 | * ID of the record to delete. May be <code>null</code>,
|
316 | * ID of the record to delete. May be <code>null</code>,
|
| 317 | * in which case <var>$condition</var> must specify
|
317 | * in which case <var>$condition</var> must specify
|
| 318 | * the records to be deleted.
|
318 | * the records to be deleted.
|
| 319 | * @param array[optional] $condition
|
319 | * @param array[optional] $condition
|
| 320 | * Conditions that must be met for a record to be deleted.
|
320 | * Conditions that must be met for a record to be deleted.
|
| 321 | * Ignored if <var>$id</var> is not <code>null</code>.
|
321 | * Ignored if <var>$id</var> is not <code>null</code>.
|
| 322 | * @return bool
|
322 | * @return bool
|
| 323 | * @throws InvalidArgumentException if both <var>$id</var> and
|
323 | * @throws InvalidArgumentException if both <var>$id</var> and
|
| 324 | * <var>$condition</var> are <code>null</code>.
|
324 | * <var>$condition</var> are <code>null</code>.
|
| 325 | * @see Database::delete()
|
325 | * @see Database::delete()
|
| 326 | */
|
326 | */
|
| 327 | public function delete ($id, array $condition = null) |
327 | public function delete ($id, array $condition = null) |
| 328 | {
|
328 | {
|
| 329 | if ($id !== null) |
329 | if ($id !== null) |
| 330 | {
|
330 | {
|
| 331 | $condition = array($this->id => $id); |
331 | $condition = array($this->id => $id); |
| 332 | }
|
332 | }
|
| 333 | else if ($condition === null) |
333 | else if ($condition === null) |
| 334 | {
|
334 | {
|
| 335 | throw new InvalidArgumentException( |
335 | throw new InvalidArgumentException( |
| 336 | '$id and $condition cannot both be null'); |
336 | '$id and $condition cannot both be null'); |
| 337 | }
|
337 | }
|
| 338 | 338 | ||
| 339 | return $this->database->delete($this->name, $condition); |
339 | return $this->database->delete($this->name, $condition); |
| 340 | }
|
340 | }
|
| 341 | 341 | ||
| 342 | /**
|
342 | /**
|
| 343 | * Inserts a row into the table or updates an existing one
|
343 | * Inserts a row into the table or updates an existing one
|
| 344 | *
|
344 | *
|
| 345 | * @param array $data
|
345 | * @param array $data
|
| 346 | * Associative array of column-value pairs to be updated/inserted
|
346 | * Associative array of column-value pairs to be updated/inserted
|
| 347 | * @param string|array $condition
|
347 | * @param string|array $condition
|
| 348 | * If there are no records matching this condition, a row will be inserted;
|
348 | * If there are no records matching this condition, a row
|
| 349 | * otherwise matching records are updated
|
349 | * will be inserted; otherwise matching records are updated.
|
| 350 | * @return bool
|
350 | * @return bool
|
| - | 351 | * The return value of Table::update() or Table::insert()
|
|
| 351 | * @see Table::update()
|
352 | * @see Table::update()
|
| 352 | * @see Table::insert()
|
353 | * @see Table::insert()
|
| 353 | */
|
354 | */
|
| 354 | public function updateOrInsert($data, array $condition = null) |
355 | public function updateOrInsert($data, array $condition = null) |
| 355 | {
|
356 | {
|
| 356 | if ($this->select($this->id, $condition)) |
357 | if ($this->select($this->id, $condition)) |
| 357 | {
|
358 | {
|
| 358 | return $this->update($data, $condition); |
359 | return $this->update($data, $condition); |
| 359 | }
|
360 | }
|
| 360 | 361 | ||
| 361 | return $this->insert($data); |
362 | return $this->insert($data); |
| 362 | }
|
363 | }
|
| 363 | 364 | ||
| 364 | /**
|
365 | /**
|
| 365 | * Finds a record by ID
|
366 | * Finds a record by ID
|
| 366 | *
|
367 | *
|
| 367 | * @param mixed $id
|
368 | * @param mixed $id
|
| 368 | * @return array
|
369 | * @return array
|
| 369 | */
|
370 | */
|
| 370 | public function find ($id) |
371 | public function find ($id) |
| 371 | {
|
372 | {
|
| 372 | /* DEBUG */
|
373 | /* DEBUG */
|
| 373 | if (defined('DEBUG') && DEBUG > 0) |
374 | if (defined('DEBUG') && DEBUG > 0) |
| 374 | {
|
375 | {
|
| 375 | debug($id); |
376 | debug($id); |
| 376 | }
|
377 | }
|
| 377 | 378 | ||
| 378 | $result = $this->select(null, array($this->id => $id)); |
379 | $result = $this->select(null, array($this->id => $id)); |
| 379 | 380 | ||
| 380 | if ($result) |
381 | if ($result) |
| 381 | {
|
382 | {
|
| 382 | $result = $result[0]; |
383 | $result = $result[0]; |
| 383 | }
|
384 | }
|
| 384 | 385 | ||
| 385 | return $result; |
386 | return $result; |
| 386 | }
|
387 | }
|
| 387 | }
|
388 | }
|