Source for file Update.php

Documentation is available at Update.php


1 <?php
2 /**
3 * $Id: Update.php,v 1.1.1.1 2004/02/14 01:43:24 luckec Exp $
4 *
5 * Subclass of tgcSqlBuilder that helps to create UPDATE sql-statements.
6 *
7 * @package tgcSqlBuilder
8 * @author Carsten Lucke <luckec@tool-garage.de>
9 * @copyright Carsten Lucke <http://www.tool-garage.de>
10 */
11
12
13
14 /**
15 * No update values specified for a query
16 *
17 * @access private
18 */
19 define('SQLBUILDER_ERROR_NO_UPDATE_VALUES', 301);
20
21
22
23 /**
24 * Subclass of tgcSqlBuilder that helps to create UPDATE sql-statements.
25 *
26 * @package tgcSqlBuilder
27 * @access public
28 * @version 1.0.0
29 * @author Carsten Lucke <luckec@tool-garage.de>
30 */
31 class tgcSqlBuilder_Update extends tgcSqlBuilder
32 {
33
34 /**
35 * Keeps the WHERE information.
36 *
37 * Structure:
38 * <pre>
39 * array(
40 * 'OR' => array(
41 * array(
42 * 'table' => $tableName,
43 * 'column' => $columnName,
44 * 'value' => $value,
45 * 'compOp' => $comparisonOperator,
46 * },
47 * ...
48 * ),
49 * 'AND' => array(
50 * array(
51 * 'table' => $tableName,
52 * 'column' => $columnName,
53 * 'value' => $value,
54 * 'compOp' => $comparisonOperator,
55 * },
56 * ...
57 * )
58 * </pre>
59 *
60 * @access private
61 * @var array WHERE information
62 */
63 var $_where = array(
64 SQLBUILDER_LOGICAL_AND => array(),
65 SQLBUILDER_LOGICAL_OR => array()
66 );
67
68 /**
69 * Keeps the raw WHERE information.
70 *
71 * Structure:
72 * <pre>
73 * array(
74 * 'OR' => array(
75 * $statement1,
76 * $statement2,
77 * ...
78 * ),
79 * 'AND' => array(
80 * $statement1,
81 * $statement2,
82 * ...
83 * )
84 * </pre>
85 *
86 * @access private
87 * @var array WHERE information
88 */
89 var $_rawWhere = array(
90 SQLBUILDER_LOGICAL_AND => array(),
91 SQLBUILDER_LOGICAL_OR => array()
92 );
93
94 /**
95 * Keeps the LIMIT information.
96 *
97 * @access private
98 * @var int limit information
99 */
100 var $_limit;
101
102 /**
103 * Tablename on which a sql-statement concerns.
104 *
105 * It's a numeric array, that contains the tablenames, that shall be used in an sql-statement.
106 *
107 * @access private
108 * @var array tablename
109 */
110 var $_tables;
111
112 /**
113 * Update data.
114 *
115 * Array structure:
116 * <pre>
117 * array (
118 * $col1Name => $col1Value,
119 * $col2Name => $col2Value,
120 * ...
121 * )
122 * </pre>
123 *
124 * @access private
125 * @var array update data
126 */
127 var $_update = array();
128
129 /**
130 * Raw UPDATE data.
131 *
132 * Array structure:
133 * <pre>
134 * array (
135 * statement1,
136 * statement2,
137 * ...
138 * )
139 * </pre>
140 *
141 * @access private
142 * @var array UPDATE data
143 */
144 var $_rawUpdate = array();
145
146
147
148 /**
149 * Constructor
150 *
151 * @access public
152 * @param object $dbc PEAR::DB connection object
153 */
154 function tgcSqlBuilder_Update(&$dbc)
155 {
156 parent::tgcSqlBuilder($dbc);
157 }
158
159 /**
160 * Generate the sql-statement.
161 *
162 * This method generates a query based on the object-information and returns it as a string.
163 *
164 * <code>
165 * $sql = new tgcSqlBuilder_Update($dbc);
166 * $query = $sql->generateQuery();
167 * </code>
168 *
169 * @access public
170 * @return string sql-statement
171 */
172 function generateQuery()
173 {
174 // check if a table has been specified
175 if (empty($this->_tables))
176 {
177 return PEAR::raiseError (
178 'You have to specifiy a tablename first',
179 SQLBUILDER_ERROR_NO_TABLE_FOUND
180 );
181 }
182
183 $query = 'UPDATE ' . $this->_tables . ' SET';
184
185 $updateInformation = $this->_generateUpdateInformation($this->_update, $this->_rawUpdate);
186 if ($updateInformation != '') {
187 $query .= ' ' . $updateInformation;
188
189 if (count($this->_where[SQLBUILDER_LOGICAL_AND]) || count($this->_where[SQLBUILDER_LOGICAL_OR])) {
190 $query .= ' WHERE ' . $this->_generateWhereInformation($this->_where, $this->_rawWhere);
191 }
192
193 if (! is_null($this->_limit)) {
194 $query .= ' LIMIT ' . $this->_limit;
195 }
196
197 $this->reset();
198 return $query;
199 }
200
201 return PEAR::raiseError (
202 'No update values found.',
203 SQLBUILDER_ERROR_NO_UPDATE_VALUES,
204 null,
205 null,
206 'To generate a valid query you have to specify at least one update value'
207 );
208 }
209
210 /**
211 * Generates the UPDATE information.
212 *
213 * @access private
214 * @param array $update UPDATE information
215 * @param array $rawUpdate raw UPDATE information
216 * @return string statement for the query on success, else empty string
217 */
218 function _generateUpdateInformation($update, $rawUpdate)
219 {
220 $information = '';
221
222 if (count($update) || count($rawUpdate)) {
223 $colNames = array_keys($update);
224 $values = array_map(array($this, 'escape'), array_values($update));
225
226 foreach ($rawUpdate as $name => $value) {
227 array_push($colNames, $name);
228 array_push($values, $value);
229 }
230
231 $parts = array();
232 for ($i = 0; $i< count($colNames); $i++) {
233 array_push($parts, sprintf('%s = %s', $colNames[$i], $values[$i]));
234 }
235 $information = implode(', ', $parts);
236 $foundValues = true;
237 return $information;
238 }
239
240 return '';
241 }
242
243 /**
244 * Add the statements table.
245 *
246 * If you call this method twice, the tablename that was set in first call will be overwritten.
247 *
248 * <code>
249 * $sql = new tgcSqlBuilder_Update($dbc);
250 * $sql->addTable('users');
251 * // now the generated sql-statement would look like: UPDATE users ...
252 * </code>
253 *
254 * @access public
255 * @param string $tableName tablename
256 */
257 function addTable($tableName)
258 {
259 $this->_tables = $tableName;
260 }
261
262 /**
263 * Remove the tablename.
264 *
265 * @access public
266 */
267 function removeTable()
268 {
269 $this->_tables = null;
270 }
271
272 /**
273 * Set the LIMIT for the sql-statement.
274 *
275 * @access public
276 * @param int $offset offset
277 * @param int $rows rows
278 */
279 function setLimit($rows)
280 {
281 $this->_limit = $rows;
282 }
283
284 /**
285 * Remove the LIMIT for the sql-statement.
286 *
287 * @access public
288 */
289 function unsetLimit()
290 {
291 $this->_limit = null;
292 }
293
294 /**
295 * Add a WHERE statement.
296 *
297 * Possible comparison operators are:
298 * SQLBUILDER_COMP_EQUAL, SQLBUILDER_COMP_NOT_EQUAL, SQLBUILDER_COMP_LESSER_THAN, SQLBUILDER_COMP_LESSER_EQUAL,
299 * SQLBUILDER_COMP_GREATER_EQUAL, SQLBUILDER_COMP_GREATER_THAN, SQLBUILDER_COMP_STARTSWITH, SQLBUILDER_COMP_CONTAINS,
300 * SQLBUILDER_COMP_ENDSWITH, SQLBUILDER_COMP_BETWEEN
301 *
302 * If none is specified then SQLBUILDER_COMP_EQUAL will be used.
303 *
304 * Possible logical expressions are:
305 * SQLBUILDER_LOGICAL_AND, SQLBUILDER_LOGICAL_OR
306 *
307 * If none is specified, then SQLBUILDER_LOGICAL_AND will be used.
308 *
309 * When you are using SQLBUILDER_COMP_BETWEEN, then specify $values as a numerical array with two values
310 * in correct order.
311 *
312 * @access public
313 * @param string $table tablename
314 * @param string $column columnname
315 * @param mixed $value value(s)
316 * @param string $compOp comparison operator
317 * @param string $logic logical linkup
318 */
319 function addWhere($table, $column, $value, $compOp = null, $logic = null)
320 {
321 $this->_addWhereHaving($this->_where, $table, $column, $value, $compOp, $logic);
322 }
323
324 /**
325 * Remove a WHERE statement.
326 *
327 * If you don't specify any parameter, then all WHERE information will be removed.
328 * If you specify a tablename and a columnname, then this specific ORDER BY setting will be removed.
329 *
330 * @access public
331 * @param string $table tablename
332 * @param string $column columnname
333 * @param string $logic logical operation (possible values: SQLBUILDER_LOGICAL_AND, SQLBUILDER_LOGICAL_OR)
334 * @return mixed true on success or PEAR_Error (possible error(s): SQLBUILDER_ERROR_INVALID_PARAM_COMBO)
335 */
336 function removeWhere($table = null, $column = null, $logic = null)
337 {
338 return $this->_removeWhereHaving($this->_where, $table, $column, $logic);
339 }
340
341 /**
342 * Add a value to update.
343 *
344 * There are two ways of calling this method:
345 *
346 * <code>
347 * // simple method-call
348 * $sql = new tgcSqlBuilder_Update($dbc);
349 * $sql->addUpdate('col_Username', 'superman');
350 *
351 * // complex method-call, you can add more than one update with only one method-call
352 * $update = array (
353 * 'col_Username' => 'superman',
354 * 'col_Email' => 'superman@superheroes.com'
355 * );
356 * $sql->addUpdate($update);
357 * </code>
358 *
359 * @access public
360 * @param mixed $colName columnname or associative array containing pairs of $colName => $value
361 * @param mixed $value value to update
362 * @return mixed true on success, else PEAR_Error (possible error(s): SQLBUILDER_ERROR_INVALID_PARAM_COMBO)
363 */
364 function addUpdate($colName, $value = null)
365 {
366 if (is_array($colName) && is_null($value)) {
367 foreach ($colName as $key => $value) {
368 $this->_update[$key] = $value;
369 }
370 return true;
371 }
372
373 if (! is_null($colName) && ! is_null($value)) {
374 $this->_update[$colName] = $value;
375 return true;
376 }
377
378 return PEAR::raiseError( 'Invalid parameter combination',
379 SQLBUILDER_ERROR_INVALID_PARAM_COMBO,
380 null,
381 null,
382 'You called this method with an invalid parameter combination.'
383 );
384 }
385
386 /**
387 * Remove one or all update columns.
388 *
389 * If you specify a columnname, then just this column's update will be removed, else all updates will be removed.
390 *
391 * @access public
392 * @param string $colName columnname
393 * @return mixed true on success, else PEAR_Error (possible error(s): SQLBUILDER_ERROR_COLUMN_DOES_NOT_EXIST)
394 */
395 function removeUpdate($colName = null)
396 {
397 if(! is_null($colName)) {
398 if (isset($this->_update[$colName])) {
399 unset($this->_update[$colName]);
400 return true;
401 }
402
403 return PEAR::raiseError (
404 'Column doesn\'t exist',
405 SQLBUILDER_ERROR_COLUMN_DOES_NOT_EXIST,
406 null,
407 null,
408 'The column you tried to remove does not exist.'
409 );
410 }
411
412 $this->_update = array();
413 return true;
414 }
415
416 /**
417 * Add a raw UPDATE statement
418 *
419 * There are two ways of calling this method:
420 *
421 * <code>
422 * // simple method-call
423 * $sql = new tgcSqlBuilder_Update($dbc);
424 * $sql->addUpdate('creationTime', 'NOW()');
425 *
426 * // complex method-call, you can add more than one insert with only one method-call
427 * $update = array (
428 * 'created' => 'NOW()',
429 * 'changed' => 'NOW()'
430 * );
431 * $sql->addUpdate($update);
432 * </code>
433 *
434 * @access public
435 * @param mixed $colName columnname or associative array containing pairs of $colName => $value
436 * @param mixed $value value to insert
437 * @return mixed true on success, else PEAR_Error (possible error(s): SQLBUILDER_ERROR_INVALID_PARAM_COMBO)
438 */
439 function addRawUpdate($colName, $value = null)
440 {
441 if (is_array($colName) && is_null($value)) {
442 foreach ($colName as $key => $value) {
443 $this->_rawUpdate[$key] = $value;
444 }
445 return true;
446 }
447
448 if (! is_null($colName) && ! is_null($value)) {
449 $this->_rawUpdate[$colName] = $value;
450 return true;
451 }
452
453 return PEAR::raiseError( 'Invalid parameter combination',
454 SQLBUILDER_ERROR_INVALID_PARAM_COMBO,
455 null,
456 null,
457 'You called this method with an invalid parameter combination.'
458 );
459 }
460
461 /**
462 * Remove one or all UPDATE columns.
463 *
464 * If you specify a columnname, then just this column's UPDATE will be removed, else all UPDATEs will be removed.
465 *
466 * @access public
467 * @param string $colName columnname
468 * @return mixed true on success, else PEAR_Error (possible error(s): SQLBUILDER_ERROR_COLUMN_DOES_NOT_EXIST)
469 */
470 function removeRawUpdate($colName = null)
471 {
472 if(! is_null($colName)) {
473 if (isset($this->_rawUpdate[$colName])) {
474 unset($this->_rawUpdate[$colName]);
475 return true;
476 }
477
478 return PEAR::raiseError (
479 'Column doesn\'t exist',
480 SQLBUILDER_ERROR_COLUMN_DOES_NOT_EXIST,
481 null,
482 null,
483 'The column you tried to remove does not exist.'
484 );
485 }
486
487 $this->_rawUpdate = array();
488 return true;
489 }
490
491 /**
492 * Reset the object's whole information.
493 *
494 * @access public
495 */
496 function reset()
497 {
498 $this->removeTable();
499 $this->removeUpdate();
500 $this->removeRawUpdate();
501 $this->removeRawWhere();
502 $this->removeWhere();
503 $this->unsetLimit();
504 }
505
506 /**
507 * Add a raw WHERE statement.
508 *
509 * You can add a raw WHERE statement and define a logical operator. As default this is the logical AND.
510 *
511 * @access public
512 * @param string $statement raw WHERE statement
513 * @ param string $logic SQLBUILDER_LOGICAL_AND or SQLBUILDER_LOGICAL_OR
514 */
515 function addRawWhere($statement, $logic = SQLBUILDER_LOGICAL_AND)
516 {
517 array_push($this->_rawWhere[$logic], $statement);
518 }
519
520 /**
521 * Remove the raw WHERE statements, that have been stored so far.
522 *
523 * @access public
524 * @param string $logic SQLBUILDER_LOGICAL_AND or SQLBUILDER_LOGICAL_OR
525 * @return boolean true on success, else PEAR_Error
526 */
527 function removeRawWhere($logic = null)
528 {
529 // check $logic, if specified
530 if (! is_null($logic) && ! ($logic == SQLBUILDER_LOGICAL_AND || $logic == SQLBUILDER_LOGICAL_OR)) {
531 return PEAR::raiseError (
532 'Invalid logical operator',
533 SQLBUILDER_ERROR_INVALID_LOGICAL_OPERATOR
534 );
535 }
536
537 // remove all raw WHERE statements
538 if (is_null($logic)) {
539 $this->_rawWhere = array
540 (
541 SQLBUILDER_LOGICAL_AND => array(),
542 SQLBUILDER_LOGICAL_OR => array()
543 );
544 return true;
545 }
546
547 // delete depending on $logic
548 $this->_rawWhere[$logic] = array();
549 return true;
550 }
551
552 }
553 ?>

Documentation generated on Fri, 19 Nov 2004 23:54:06 +0100 by phpDocumentor 1.2.3