$line
\n"; 71 | } else { 72 | $colour = self::$term_colours[$colour]; 73 | return chr(27) . "[0;{$colour}m{$line}" . chr(27) . "[00m\n"; 74 | } 75 | } 76 | 77 | /** 78 | * Report a passed test 79 | */ 80 | private static function report_pass($test_name) { 81 | echo self::format_line("PASS: $test_name", 'GREEN'); 82 | self::$passed_tests[] = $test_name; 83 | } 84 | 85 | /** 86 | * Report a failed test 87 | */ 88 | private static function report_failure($test_name, $expected, $actual) { 89 | echo self::format_line("FAIL: $test_name", 'RED'); 90 | echo self::format_line("Expected: $expected", 'RED'); 91 | echo self::format_line("Actual: $actual", 'RED'); 92 | self::$failed_tests[] = $test_name; 93 | } 94 | 95 | /** 96 | * Print a summary of passed and failed test counts 97 | */ 98 | public static function report() { 99 | $passed_count = count(self::$passed_tests); 100 | $failed_count = count(self::$failed_tests); 101 | echo self::format_line(''); 102 | echo self::format_line("$passed_count tests passed. $failed_count tests failed."); 103 | 104 | if ($failed_count != 0) { 105 | echo self::format_line("Failed tests: " . join(", ", self::$failed_tests)); 106 | } 107 | } 108 | 109 | /** 110 | * Check the provided string is equal to the last 111 | * query generated by the dummy database class. 112 | */ 113 | public static function check_equal($test_name, $query) { 114 | $last_query = ORM::get_last_query(); 115 | if ($query === $last_query) { 116 | self::report_pass($test_name); 117 | } else { 118 | self::report_failure($test_name, $query, $last_query); 119 | } 120 | } 121 | } 122 | -------------------------------------------------------------------------------- /test/test_queries.php: -------------------------------------------------------------------------------- 1 | find_many(); 20 | $expected = "SELECT * FROM `widget`"; 21 | Tester::check_equal("Basic unfiltered find_many query", $expected); 22 | 23 | ORM::for_table('widget')->find_one(); 24 | $expected = "SELECT * FROM `widget` LIMIT 1"; 25 | Tester::check_equal("Basic unfiltered find_one query", $expected); 26 | 27 | ORM::for_table('widget')->where_id_is(5)->find_one(); 28 | $expected = "SELECT * FROM `widget` WHERE `id` = '5' LIMIT 1"; 29 | Tester::check_equal("where_id_is method", $expected); 30 | 31 | ORM::for_table('widget')->find_one(5); 32 | $expected = "SELECT * FROM `widget` WHERE `id` = '5' LIMIT 1"; 33 | Tester::check_equal("Filtering on ID passed into find_one method", $expected); 34 | 35 | ORM::for_table('widget')->count(); 36 | $expected = "SELECT COUNT(*) AS `count` FROM `widget` LIMIT 1"; 37 | Tester::check_equal("COUNT query", $expected); 38 | 39 | ORM::for_table('person')->max('height'); 40 | $expected = "SELECT MAX(`height`) AS `max` FROM `person` LIMIT 1"; 41 | Tester::check_equal("MAX query", $expected); 42 | 43 | ORM::for_table('person')->min('height'); 44 | $expected = "SELECT MIN(`height`) AS `min` FROM `person` LIMIT 1"; 45 | Tester::check_equal("MIN query", $expected); 46 | 47 | ORM::for_table('person')->avg('height'); 48 | $expected = "SELECT AVG(`height`) AS `avg` FROM `person` LIMIT 1"; 49 | Tester::check_equal("AVG query", $expected); 50 | 51 | ORM::for_table('person')->sum('height'); 52 | $expected = "SELECT SUM(`height`) AS `sum` FROM `person` LIMIT 1"; 53 | Tester::check_equal("SUM query", $expected); 54 | 55 | ORM::for_table('widget')->where('name', 'Fred')->find_one(); 56 | $expected = "SELECT * FROM `widget` WHERE `name` = 'Fred' LIMIT 1"; 57 | Tester::check_equal("Single where clause", $expected); 58 | 59 | ORM::for_table('widget')->where('name', 'Fred')->where('age', 10)->find_one(); 60 | $expected = "SELECT * FROM `widget` WHERE `name` = 'Fred' AND `age` = '10' LIMIT 1"; 61 | Tester::check_equal("Multiple WHERE clauses", $expected); 62 | 63 | ORM::for_table('widget')->where_not_equal('name', 'Fred')->find_many(); 64 | $expected = "SELECT * FROM `widget` WHERE `name` != 'Fred'"; 65 | Tester::check_equal("where_not_equal method", $expected); 66 | 67 | ORM::for_table('widget')->where_like('name', '%Fred%')->find_one(); 68 | $expected = "SELECT * FROM `widget` WHERE `name` LIKE '%Fred%' LIMIT 1"; 69 | Tester::check_equal("where_like method", $expected); 70 | 71 | ORM::for_table('widget')->where_not_like('name', '%Fred%')->find_one(); 72 | $expected = "SELECT * FROM `widget` WHERE `name` NOT LIKE '%Fred%' LIMIT 1"; 73 | Tester::check_equal("where_not_like method", $expected); 74 | 75 | ORM::for_table('widget')->where_in('name', array('Fred', 'Joe'))->find_many(); 76 | $expected = "SELECT * FROM `widget` WHERE `name` IN ('Fred', 'Joe')"; 77 | Tester::check_equal("where_in method", $expected); 78 | 79 | ORM::for_table('widget')->where_not_in('name', array('Fred', 'Joe'))->find_many(); 80 | $expected = "SELECT * FROM `widget` WHERE `name` NOT IN ('Fred', 'Joe')"; 81 | Tester::check_equal("where_not_in method", $expected); 82 | 83 | ORM::for_table('widget')->limit(5)->find_many(); 84 | $expected = "SELECT * FROM `widget` LIMIT 5"; 85 | Tester::check_equal("LIMIT clause", $expected); 86 | 87 | ORM::for_table('widget')->limit(5)->offset(5)->find_many(); 88 | $expected = "SELECT * FROM `widget` LIMIT 5 OFFSET 5"; 89 | Tester::check_equal("LIMIT and OFFSET clause", $expected); 90 | 91 | ORM::for_table('widget')->order_by_desc('name')->find_one(); 92 | $expected = "SELECT * FROM `widget` ORDER BY `name` DESC LIMIT 1"; 93 | Tester::check_equal("ORDER BY DESC", $expected); 94 | 95 | ORM::for_table('widget')->order_by_asc('name')->find_one(); 96 | $expected = "SELECT * FROM `widget` ORDER BY `name` ASC LIMIT 1"; 97 | Tester::check_equal("ORDER BY ASC", $expected); 98 | 99 | ORM::for_table('widget')->order_by_expr('SOUNDEX(`name`)')->find_one(); 100 | $expected = "SELECT * FROM `widget` ORDER BY SOUNDEX(`name`) LIMIT 1"; 101 | Tester::check_equal("ORDER BY expression", $expected); 102 | 103 | ORM::for_table('widget')->order_by_asc('name')->order_by_desc('age')->find_one(); 104 | $expected = "SELECT * FROM `widget` ORDER BY `name` ASC, `age` DESC LIMIT 1"; 105 | Tester::check_equal("Multiple ORDER BY", $expected); 106 | 107 | ORM::for_table('widget')->group_by('name')->find_many(); 108 | $expected = "SELECT * FROM `widget` GROUP BY `name`"; 109 | Tester::check_equal("GROUP BY", $expected); 110 | 111 | ORM::for_table('widget')->group_by('name')->group_by('age')->find_many(); 112 | $expected = "SELECT * FROM `widget` GROUP BY `name`, `age`"; 113 | Tester::check_equal("Multiple GROUP BY", $expected); 114 | 115 | ORM::for_table('widget')->group_by_expr("FROM_UNIXTIME(`time`, '%Y-%m')")->find_many(); 116 | $expected = "SELECT * FROM `widget` GROUP BY FROM_UNIXTIME(`time`, '%Y-%m')"; 117 | Tester::check_equal("GROUP BY expression", $expected); 118 | 119 | ORM::for_table('widget')->where('name', 'Fred')->limit(5)->offset(5)->order_by_asc('name')->find_many(); 120 | $expected = "SELECT * FROM `widget` WHERE `name` = 'Fred' ORDER BY `name` ASC LIMIT 5 OFFSET 5"; 121 | Tester::check_equal("Complex query", $expected); 122 | 123 | ORM::for_table('widget')->where_lt('age', 10)->where_gt('age', 5)->find_many(); 124 | $expected = "SELECT * FROM `widget` WHERE `age` < '10' AND `age` > '5'"; 125 | Tester::check_equal("Less than and greater than", $expected); 126 | 127 | ORM::for_table('widget')->where_lte('age', 10)->where_gte('age', 5)->find_many(); 128 | $expected = "SELECT * FROM `widget` WHERE `age` <= '10' AND `age` >= '5'"; 129 | Tester::check_equal("Less than or equal and greater than or equal", $expected); 130 | 131 | ORM::for_table('widget')->where_null('name')->find_many(); 132 | $expected = "SELECT * FROM `widget` WHERE `name` IS NULL"; 133 | Tester::check_equal("where_null method", $expected); 134 | 135 | ORM::for_table('widget')->where_not_null('name')->find_many(); 136 | $expected = "SELECT * FROM `widget` WHERE `name` IS NOT NULL"; 137 | Tester::check_equal("where_not_null method", $expected); 138 | 139 | ORM::for_table('widget')->where_raw('`name` = ? AND (`age` = ? OR `age` = ?)', array('Fred', 5, 10))->find_many(); 140 | $expected = "SELECT * FROM `widget` WHERE `name` = 'Fred' AND (`age` = '5' OR `age` = '10')"; 141 | Tester::check_equal("Raw WHERE clause", $expected); 142 | 143 | ORM::for_table('widget')->where_raw('STRFTIME("%Y", "now") = ?', array(2012))->find_many(); 144 | $expected = "SELECT * FROM `widget` WHERE STRFTIME(\"%Y\", \"now\") = '2012'"; 145 | Tester::check_equal("Raw WHERE clause with '%'", $expected); 146 | 147 | ORM::for_table('widget')->where_raw('`name` = "Fred"')->find_many(); 148 | $expected = "SELECT * FROM `widget` WHERE `name` = \"Fred\""; 149 | Tester::check_equal("Raw WHERE clause with no parameters", $expected); 150 | 151 | ORM::for_table('widget')->where('age', 18)->where_raw('(`name` = ? OR `name` = ?)', array('Fred', 'Bob'))->where('size', 'large')->find_many(); 152 | $expected = "SELECT * FROM `widget` WHERE `age` = '18' AND (`name` = 'Fred' OR `name` = 'Bob') AND `size` = 'large'"; 153 | Tester::check_equal("Raw WHERE clause in method chain", $expected); 154 | 155 | ORM::for_table('widget')->raw_query('SELECT `w`.* FROM `widget` w')->find_many(); 156 | $expected = "SELECT `w`.* FROM `widget` w"; 157 | Tester::check_equal("Raw query", $expected); 158 | 159 | ORM::for_table('widget')->raw_query('SELECT `w`.* FROM `widget` w WHERE `name` = ? AND `age` = ?', array('Fred', 5))->find_many(); 160 | $expected = "SELECT `w`.* FROM `widget` w WHERE `name` = 'Fred' AND `age` = '5'"; 161 | Tester::check_equal("Raw query with parameters", $expected); 162 | 163 | ORM::for_table('widget')->select('name')->find_many(); 164 | $expected = "SELECT `name` FROM `widget`"; 165 | Tester::check_equal("Simple result column", $expected); 166 | 167 | ORM::for_table('widget')->select('name')->select('age')->find_many(); 168 | $expected = "SELECT `name`, `age` FROM `widget`"; 169 | Tester::check_equal("Multiple simple result columns", $expected); 170 | 171 | ORM::for_table('widget')->select('widget.name')->find_many(); 172 | $expected = "SELECT `widget`.`name` FROM `widget`"; 173 | Tester::check_equal("Specify table name and column in result columns", $expected); 174 | 175 | ORM::for_table('widget')->select('widget.name', 'widget_name')->find_many(); 176 | $expected = "SELECT `widget`.`name` AS `widget_name` FROM `widget`"; 177 | Tester::check_equal("Aliases in result columns", $expected); 178 | 179 | ORM::for_table('widget')->select_expr('COUNT(*)', 'count')->find_many(); 180 | $expected = "SELECT COUNT(*) AS `count` FROM `widget`"; 181 | Tester::check_equal("Literal expression in result columns", $expected); 182 | 183 | ORM::for_table('widget')->select_many(array('widget_name' => 'widget.name'), 'widget_handle')->find_many(); 184 | $expected = "SELECT `widget`.`name` AS `widget_name`, `widget_handle` FROM `widget`"; 185 | Tester::check_equal("Aliases in select many result columns", $expected); 186 | 187 | ORM::for_table('widget')->select_many_expr(array('count' => 'COUNT(*)'), 'SUM(widget_order)')->find_many(); 188 | $expected = "SELECT COUNT(*) AS `count`, SUM(widget_order) FROM `widget`"; 189 | Tester::check_equal("Literal expression in select many result columns", $expected); 190 | 191 | ORM::for_table('widget')->join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id'))->find_many(); 192 | $expected = "SELECT * FROM `widget` JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id`"; 193 | Tester::check_equal("Simple join", $expected); 194 | 195 | ORM::for_table('widget')->join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id'))->find_one(5); 196 | $expected = "SELECT * FROM `widget` JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id` WHERE `widget`.`id` = '5' LIMIT 1"; 197 | Tester::check_equal("Simple join with where_id_is method", $expected); 198 | 199 | ORM::for_table('widget')->inner_join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id'))->find_many(); 200 | $expected = "SELECT * FROM `widget` INNER JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id`"; 201 | Tester::check_equal("Inner join", $expected); 202 | 203 | ORM::for_table('widget')->left_outer_join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id'))->find_many(); 204 | $expected = "SELECT * FROM `widget` LEFT OUTER JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id`"; 205 | Tester::check_equal("Left outer join", $expected); 206 | 207 | ORM::for_table('widget')->right_outer_join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id'))->find_many(); 208 | $expected = "SELECT * FROM `widget` RIGHT OUTER JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id`"; 209 | Tester::check_equal("Right outer join", $expected); 210 | 211 | ORM::for_table('widget')->full_outer_join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id'))->find_many(); 212 | $expected = "SELECT * FROM `widget` FULL OUTER JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id`"; 213 | Tester::check_equal("Full outer join", $expected); 214 | 215 | ORM::for_table('widget') 216 | ->join('widget_handle', array('widget_handle.widget_id', '=', 'widget.id')) 217 | ->join('widget_nozzle', array('widget_nozzle.widget_id', '=', 'widget.id')) 218 | ->find_many(); 219 | $expected = "SELECT * FROM `widget` JOIN `widget_handle` ON `widget_handle`.`widget_id` = `widget`.`id` JOIN `widget_nozzle` ON `widget_nozzle`.`widget_id` = `widget`.`id`"; 220 | Tester::check_equal("Multiple join sources", $expected); 221 | 222 | ORM::for_table('widget')->table_alias('w')->find_many(); 223 | $expected = "SELECT * FROM `widget` `w`"; 224 | Tester::check_equal("Main table alias", $expected); 225 | 226 | ORM::for_table('widget')->join('widget_handle', array('wh.widget_id', '=', 'widget.id'), 'wh')->find_many(); 227 | $expected = "SELECT * FROM `widget` JOIN `widget_handle` `wh` ON `wh`.`widget_id` = `widget`.`id`"; 228 | Tester::check_equal("Join with alias", $expected); 229 | 230 | ORM::for_table('widget')->join('widget_handle', "widget_handle.widget_id = widget.id")->find_many(); 231 | $expected = "SELECT * FROM `widget` JOIN `widget_handle` ON widget_handle.widget_id = widget.id"; 232 | Tester::check_equal("Join with string constraint", $expected); 233 | 234 | ORM::for_table('widget')->distinct()->select('name')->find_many(); 235 | $expected = "SELECT DISTINCT `name` FROM `widget`"; 236 | Tester::check_equal("Select with DISTINCT", $expected); 237 | 238 | $widget = ORM::for_table('widget')->create(); 239 | $widget->name = "Fred"; 240 | $widget->age = 10; 241 | $widget->save(); 242 | $expected = "INSERT INTO `widget` (`name`, `age`) VALUES ('Fred', '10')"; 243 | Tester::check_equal("Insert data", $expected); 244 | 245 | $widget = ORM::for_table('widget')->create(); 246 | $widget->name = "Fred"; 247 | $widget->age = 10; 248 | $widget->set_expr('added', 'NOW()'); 249 | $widget->save(); 250 | $expected = "INSERT INTO `widget` (`name`, `age`, `added`) VALUES ('Fred', '10', NOW())"; 251 | Tester::check_equal("Insert data containing an expression", $expected); 252 | 253 | $widget = ORM::for_table('widget')->find_one(1); 254 | $widget->name = "Fred"; 255 | $widget->age = 10; 256 | $widget->save(); 257 | $expected = "UPDATE `widget` SET `name` = 'Fred', `age` = '10' WHERE `id` = '1'"; 258 | Tester::check_equal("Update data", $expected); 259 | 260 | $widget = ORM::for_table('widget')->find_one(1); 261 | $widget->name = "Fred"; 262 | $widget->age = 10; 263 | $widget->set_expr('added', 'NOW()'); 264 | $widget->save(); 265 | $expected = "UPDATE `widget` SET `name` = 'Fred', `age` = '10', `added` = NOW() WHERE `id` = '1'"; 266 | Tester::check_equal("Update data containing an expression", $expected); 267 | 268 | $widget = ORM::for_table('widget')->find_one(1); 269 | $widget->set(array("name" => "Fred", "age" => 10)); 270 | $widget->save(); 271 | $expected = "UPDATE `widget` SET `name` = 'Fred', `age` = '10' WHERE `id` = '1'"; 272 | Tester::check_equal("Update multiple fields", $expected); 273 | 274 | $widget = ORM::for_table('widget')->find_one(1); 275 | $widget->set(array("name" => "Fred", "age" => 10)); 276 | $widget->set_expr(array("added" => "NOW()", "lat_long" => "GeomFromText('POINT(1.2347 2.3436)')")); 277 | $widget->save(); 278 | $expected = "UPDATE `widget` SET `name` = 'Fred', `age` = '10', `added` = NOW(), `lat_long` = GeomFromText('POINT(1.2347 2.3436)') WHERE `id` = '1'"; 279 | Tester::check_equal("Update multiple fields containing an expression", $expected); 280 | 281 | $widget = ORM::for_table('widget')->find_one(1); 282 | $widget->set(array("name" => "Fred", "age" => 10)); 283 | $widget->set_expr(array("added" => "NOW()", "lat_long" => "GeomFromText('POINT(1.2347 2.3436)')")); 284 | $widget->lat_long = 'unknown'; 285 | $widget->save(); 286 | $expected = "UPDATE `widget` SET `name` = 'Fred', `age` = '10', `added` = NOW(), `lat_long` = 'unknown' WHERE `id` = '1'"; 287 | Tester::check_equal("Update multiple fields containing an expression (override previously set expression with plain value)", $expected); 288 | 289 | $widget = ORM::for_table('widget')->find_one(1); 290 | $widget->delete(); 291 | $expected = "DELETE FROM `widget` WHERE `id` = '1'"; 292 | Tester::check_equal("Delete data", $expected); 293 | 294 | $widget = ORM::for_table('widget')->where_equal('age', 10)->delete_many(); 295 | $expected = "DELETE FROM `widget` WHERE `age` = '10'"; 296 | Tester::check_equal("Delete many", $expected); 297 | 298 | ORM::raw_execute("INSERT OR IGNORE INTO `widget` (`id`, `name`) VALUES (?, ?)", array(1, 'Tolstoy')); 299 | $expected = "INSERT OR IGNORE INTO `widget` (`id`, `name`) VALUES ('1', 'Tolstoy')"; 300 | Tester::check_equal("Raw execute", $expected); // A bit of a silly test, as query is passed through 301 | 302 | // Regression tests 303 | 304 | $widget = ORM::for_table('widget')->select('widget.*')->find_one(); 305 | $expected = "SELECT `widget`.* FROM `widget` LIMIT 1"; 306 | Tester::check_equal("Issue #12 - incorrect quoting of column wildcard", $expected); 307 | 308 | $widget = ORM::for_table('widget')->where_raw('username LIKE "ben%"')->find_many(); 309 | $expected = 'SELECT * FROM `widget` WHERE username LIKE "ben%"'; 310 | Tester::check_equal('Issue #57 - _log_query method raises a warning when query contains "%"', $expected); 311 | 312 | $widget = ORM::for_table('widget')->where_raw('comments LIKE "has been released?%"')->find_many(); 313 | $expected = 'SELECT * FROM `widget` WHERE comments LIKE "has been released?%"'; 314 | Tester::check_equal('Issue #57 - _log_query method raises a warning when query contains "?"', $expected); 315 | 316 | // Tests that alter Idiorm's config are done last 317 | 318 | ORM::configure('id_column', 'primary_key'); 319 | ORM::for_table('widget')->find_one(5); 320 | $expected = "SELECT * FROM `widget` WHERE `primary_key` = '5' LIMIT 1"; 321 | Tester::check_equal("Setting: id_column", $expected); 322 | 323 | ORM::configure('id_column_overrides', array( 324 | 'widget' => 'widget_id', 325 | 'widget_handle' => 'widget_handle_id', 326 | )); 327 | 328 | ORM::for_table('widget')->find_one(5); 329 | $expected = "SELECT * FROM `widget` WHERE `widget_id` = '5' LIMIT 1"; 330 | Tester::check_equal("Setting: id_column_overrides, first test", $expected); 331 | 332 | ORM::for_table('widget_handle')->find_one(5); 333 | $expected = "SELECT * FROM `widget_handle` WHERE `widget_handle_id` = '5' LIMIT 1"; 334 | Tester::check_equal("Setting: id_column_overrides, second test", $expected); 335 | 336 | ORM::for_table('widget_nozzle')->find_one(5); 337 | $expected = "SELECT * FROM `widget_nozzle` WHERE `primary_key` = '5' LIMIT 1"; 338 | Tester::check_equal("Setting: id_column_overrides, third test", $expected); 339 | 340 | ORM::for_table('widget')->use_id_column('new_id')->find_one(5); 341 | $expected = "SELECT * FROM `widget` WHERE `new_id` = '5' LIMIT 1"; 342 | Tester::check_equal("Instance ID column, first test", $expected); 343 | 344 | ORM::for_table('widget_handle')->use_id_column('new_id')->find_one(5); 345 | $expected = "SELECT * FROM `widget_handle` WHERE `new_id` = '5' LIMIT 1"; 346 | Tester::check_equal("Instance ID column, second test", $expected); 347 | 348 | ORM::for_table('widget_nozzle')->use_id_column('new_id')->find_one(5); 349 | $expected = "SELECT * FROM `widget_nozzle` WHERE `new_id` = '5' LIMIT 1"; 350 | Tester::check_equal("Instance ID column, third test", $expected); 351 | 352 | // Test caching. This is a bit of a hack. 353 | ORM::configure('caching', true); 354 | ORM::for_table('widget')->where('name', 'Fred')->where('age', 17)->find_one(); 355 | ORM::for_table('widget')->where('name', 'Bob')->where('age', 42)->find_one(); 356 | $expected = ORM::get_last_query(); 357 | ORM::for_table('widget')->where('name', 'Fred')->where('age', 17)->find_one(); // this shouldn't run a query! 358 | Tester::check_equal("Caching, same query not run twice", $expected); 359 | 360 | 361 | Tester::report(); 362 | ?> 363 | -------------------------------------------------------------------------------- /README.markdown: -------------------------------------------------------------------------------- 1 | Idiorm 2 | ====== 3 | 4 | [http://j4mie.github.com/idiormandparis/](http://j4mie.github.com/idiormandparis/) 5 | 6 | A lightweight nearly-zero-configuration object-relational mapper and fluent query builder for PHP5. 7 | 8 | Tested on PHP 5.2.0+ - may work on earlier versions with PDO and the correct database drivers. 9 | 10 | Released under a [BSD license](http://en.wikipedia.org/wiki/BSD_licenses). 11 | 12 | **See Also: [Paris](http://github.com/j4mie/paris), an Active Record implementation built on top of Idiorm.** 13 | 14 | Features 15 | -------- 16 | 17 | * Makes simple queries and simple CRUD operations completely painless. 18 | * Gets out of the way when more complex SQL is required. 19 | * Built on top of [PDO](http://php.net/pdo). 20 | * Uses [prepared statements](http://uk.php.net/manual/en/pdo.prepared-statements.php) throughout to protect against [SQL injection](http://en.wikipedia.org/wiki/SQL_injection) attacks. 21 | * Requires no model classes, no XML configuration and no code generation: works out of the box, given only a connection string. 22 | * Consists of just one class called `ORM`. Minimal global namespace pollution. 23 | * Database agnostic. Currently supports SQLite and MySQL. May support others, please give it a try! 24 | 25 | Changelog 26 | --------- 27 | 28 | #### 1.2.3 - release 2012-11-28 29 | 30 | * Fix issue #78 - remove use of PHP 5.3 static call 31 | 32 | #### 1.2.2 - release 2012-11-15 33 | 34 | * Fix bug where input parameters were sent as part-indexed, part associative 35 | 36 | #### 1.2.1 - release 2012-11-15 37 | 38 | * Fix minor bug caused by IdiormStringException not extending Exception 39 | 40 | #### 1.2.0 - release 2012-11-14 41 | 42 | * Setup composer for installation via packagist (j4mie/idiorm) 43 | * Add `order_by_expr` method [[sandermarechal](http://github.com/sandermarechal)] 44 | * Add support for raw queries without parameters argument [[sandermarechal](http://github.com/sandermarechal)] 45 | * Add support to set multiple properties at once by passing an associative array to `set` method [[sandermarechal](http://github.com/sandermarechal)] 46 | * Allow an associative array to be passed to `configure` method [[jordanlev](http://github.com/jordanlev)] 47 | * Patch to allow empty Paris models to be saved ([[j4mie/paris](http://github.com/j4mie/paris)]) issue #58 48 | * Add `select_many` and `select_many_expr` - closing issues #49 and #69 49 | * Add support for `MIN`, `AVG`, `MAX` and `SUM` - closes issue #16 50 | * Add `group_by_expr` - closes issue #24 51 | * Add `set_expr` to allow database expressions to be set as ORM properties - closes issues #59 and #43 [[brianherbert](https://github.com/brianherbert)] 52 | * Prevent ambiguous column names when joining tables - issue #66 [[hellogerard](https://github.com/hellogerard)] 53 | * Add `delete_many` method [[CBeerta](https://github.com/CBeerta)] 54 | * Allow unsetting of ORM parameters [[CBeerta](https://github.com/CBeerta)] 55 | * Add `find_array` to get the records as associative arrays [[Surt](https://github.com/Surt)] - closes issue #17 56 | * Fix bug in `_log_query` with `?` and `%` supplied in raw where statements etc. - closes issue #57 [[ridgerunner](https://github.com/ridgerunner)] 57 | 58 | #### 1.1.1 - release 2011-01-30 59 | 60 | * Fix bug in quoting column wildcard. j4mie/paris#12 61 | * Small documentation improvements 62 | 63 | #### 1.1.0 - released 2011-01-24 64 | 65 | * Add `is_dirty` method 66 | * Add basic query caching 67 | * Add `distinct` method 68 | * Add `group_by` method 69 | 70 | #### 1.0.0 - released 2010-12-01 71 | 72 | * Initial release 73 | 74 | 75 | Philosophy 76 | ---------- 77 | 78 | The [Pareto Principle](http://en.wikipedia.org/wiki/Pareto_principle) states that *roughly 80% of the effects come from 20% of the causes.* In software development terms, this could be translated into something along the lines of *80% of the results come from 20% of the complexity*. In other words, you can get pretty far by being pretty stupid. 79 | 80 | **Idiorm is deliberately simple**. Where other ORMs consist of dozens of classes with complex inheritance hierarchies, Idiorm has only one class, `ORM`, which functions as both a fluent `SELECT` query API and a simple CRUD model class. If my hunch is correct, this should be quite enough for many real-world applications. Let's face it: most of us aren't building Facebook. We're working on small-to-medium-sized projects, where the emphasis is on simplicity and rapid development rather than infinite flexibility and features. 81 | 82 | You might think of **Idiorm** as a *micro-ORM*. It could, perhaps, be "the tie to go along with [Slim](http://github.com/codeguy/slim/)'s tux" (to borrow a turn of phrase from [DocumentCloud](http://github.com/documentcloud/underscore)). Or it could be an effective bit of spring cleaning for one of those horrendous SQL-littered legacy PHP apps you have to support. 83 | 84 | **Idiorm** might also provide a good base upon which to build higher-level, more complex database abstractions. For example, [Paris](http://github.com/j4mie/paris) is an implementation of the [Active Record pattern](http://martinfowler.com/eaaCatalog/activeRecord.html) built on top of Idiorm. 85 | 86 | Installation 87 | ------------ 88 | 89 | ### Packagist ### 90 | 91 | This library is available through Packagist with the vendor and package identifier of `j4mie/idiorm` 92 | 93 | Please see the [Packagist documentation](http://packagist.org/) for further information. 94 | 95 | ### Download ### 96 | 97 | You can clone the git repository, download idiorm.php or a release tag and then drop the idiorm.php file in the vendors/3rd party/libs directory of your project. 98 | 99 | Let's See Some Code 100 | ------------------- 101 | 102 | The first thing you need to know about Idiorm is that *you don't need to define any model classes to use it*. With almost every other ORM, the first thing to do is set up your models and map them to database tables (through configuration variables, XML files or similar). With Idiorm, you can start using the ORM straight away. 103 | 104 | ### Setup ### 105 | 106 | First, `require` the Idiorm source file: 107 | 108 | require_once 'idiorm.php'; 109 | 110 | Then, pass a *Data Source Name* connection string to the `configure` method of the ORM class. This is used by PDO to connect to your database. For more information, see the [PDO documentation](http://php.net/manual/en/pdo.construct.php). 111 | 112 | ORM::configure('sqlite:./example.db'); 113 | 114 | You may also need to pass a username and password to your database driver, using the `username` and `password` configuration options. For example, if you are using MySQL: 115 | 116 | ORM::configure('mysql:host=localhost;dbname=my_database'); 117 | ORM::configure('username', 'database_user'); 118 | ORM::configure('password', 'top_secret'); 119 | 120 | Also see "Configuration" section below. 121 | 122 | ### Querying ### 123 | 124 | Idiorm provides a [*fluent interface*](http://en.wikipedia.org/wiki/Fluent_interface) to enable simple queries to be built without writing a single character of SQL. If you've used [jQuery](http://jquery.com) at all, you'll be familiar with the concept of a fluent interface. It just means that you can *chain* method calls together, one after another. This can make your code more readable, as the method calls strung together in order can start to look a bit like a sentence. 125 | 126 | All Idiorm queries start with a call to the `for_table` static method on the ORM class. This tells the ORM which table to use when making the query. 127 | 128 | *Note that this method **does not** escape its query parameter and so the table name should **not** be passed directly from user input.* 129 | 130 | Method calls which add filters and constraints to your query are then strung together. Finally, the chain is finished by calling either `find_one()` or `find_many()`, which executes the query and returns the result. 131 | 132 | Let's start with a simple example. Say we have a table called `person` which contains the columns `id` (the primary key of the record - Idiorm assumes the primary key column is called `id` but this is configurable, see below), `name`, `age` and `gender`. 133 | 134 | #### Single records #### 135 | 136 | Any method chain that ends in `find_one()` will return either a *single* instance of the ORM class representing the database row you requested, or `false` if no matching record was found. 137 | 138 | To find a single record where the `name` column has the value "Fred Bloggs": 139 | 140 | $person = ORM::for_table('person')->where('name', 'Fred Bloggs')->find_one(); 141 | 142 | This roughly translates into the following SQL: `SELECT * FROM person WHERE name = "Fred Bloggs"` 143 | 144 | To find a single record by ID, you can pass the ID directly to the `find_one` method: 145 | 146 | $person = ORM::for_table('person')->find_one(5); 147 | 148 | #### Multiple records #### 149 | 150 | Any method chain that ends in `find_many()` will return an *array* of ORM class instances, one for each row matched by your query. If no rows were found, an empty array will be returned. 151 | 152 | To find all records in the table: 153 | 154 | $people = ORM::for_table('person')->find_many(); 155 | 156 | To find all records where the `gender` is `female`: 157 | 158 | $females = ORM::for_table('person')->where('gender', 'female')->find_many(); 159 | 160 | ##### As an associative array ##### 161 | 162 | You can also find many records as an associative array instead of Idiorm instances. To do this substitute any call to `find_many()` with `find_array()`. 163 | 164 | $females = ORM::for_table('person')->where('gender', 'female')->find_array(); 165 | 166 | This is useful if you need to serialise the the query output into a format like JSON and you do not need the ability to update the returned records. 167 | 168 | #### Counting results #### 169 | 170 | To return a count of the number of rows that would be returned by a query, call the `count()` method. 171 | 172 | $number_of_people = ORM::for_table('person')->count(); 173 | 174 | #### Filtering results #### 175 | 176 | Idiorm provides a family of methods to extract only records which satisfy some condition or conditions. These methods may be called multiple times to build up your query, and Idiorm's fluent interface allows method calls to be *chained* to create readable and simple-to-understand queries. 177 | 178 | ##### *Caveats* ##### 179 | 180 | Only a subset of the available conditions supported by SQL are available when using Idiorm. Additionally, all the `WHERE` clauses will be `AND`ed together when the query is run. Support for `OR`ing `WHERE` clauses is not currently present. 181 | 182 | These limits are deliberate: these are by far the most commonly used criteria, and by avoiding support for very complex queries, the Idiorm codebase can remain small and simple. 183 | 184 | Some support for more complex conditions and queries is provided by the `where_raw` and `raw_query` methods (see below). If you find yourself regularly requiring more functionality than Idiorm can provide, it may be time to consider using a more full-featured ORM. 185 | 186 | ##### Equality: `where`, `where_equal`, `where_not_equal` ##### 187 | 188 | By default, calling `where` with two parameters (the column name and the value) will combine them using an equals operator (`=`). For example, calling `where('name', 'Fred')` will result in the clause `WHERE name = "Fred"`. 189 | 190 | If your coding style favours clarity over brevity, you may prefer to use the `where_equal` method: this is identical to `where`. 191 | 192 | The `where_not_equal` method adds a `WHERE column != "value"` clause to your query. 193 | 194 | ##### Shortcut: `where_id_is` ##### 195 | 196 | This is a simple helper method to query the table by primary key. Respects the ID column specified in the config. 197 | 198 | ##### Less than / greater than: `where_lt`, `where_gt`, `where_lte`, `where_gte` ##### 199 | 200 | There are four methods available for inequalities: 201 | 202 | * Less than: `$people = ORM::for_table('person')->where_lt('age', 10)->find_many();` 203 | * Greater than: `$people = ORM::for_table('person')->where_gt('age', 5)->find_many();` 204 | * Less than or equal: `$people = ORM::for_table('person')->where_lte('age', 10)->find_many();` 205 | * Greater than or equal: `$people = ORM::for_table('person')->where_gte('age', 5)->find_many();` 206 | 207 | ##### String comparision: `where_like` and `where_not_like` ##### 208 | 209 | To add a `WHERE ... LIKE` clause, use: 210 | 211 | $people = ORM::for_table('person')->where_like('name', '%fred%')->find_many(); 212 | 213 | Similarly, to add a `WHERE ... NOT LIKE` clause, use: 214 | 215 | $people = ORM::for_table('person')->where_not_like('name', '%bob%')->find_many(); 216 | 217 | ##### Set membership: `where_in` and `where_not_in` ##### 218 | 219 | To add a `WHERE ... IN ()` or `WHERE ... NOT IN ()` clause, use the `where_in` and `where_not_in` methods respectively. 220 | 221 | Both methods accept two arguments. The first is the column name to compare against. The second is an *array* of possible values. 222 | 223 | $people = ORM::for_table('person')->where_in('name', array('Fred', 'Joe', 'John'))->find_many(); 224 | 225 | ##### Working with `NULL` values: `where_null` and `where_not_null` ##### 226 | 227 | To add a `WHERE column IS NULL` or `WHERE column IS NOT NULL` clause, use the `where_null` and `where_not_null` methods respectively. Both methods accept a single parameter: the column name to test. 228 | 229 | ##### Raw WHERE clauses ##### 230 | 231 | If you require a more complex query, you can use the `where_raw` method to specify the SQL fragment for the WHERE clause exactly. This method takes two arguments: the string to add to the query, and an (optional) array of parameters which will be bound to the string. If parameters are supplied, the string should contain question mark characters (`?`) to represent the values to be bound, and the parameter array should contain the values to be substituted into the string in the correct order. 232 | 233 | This method may be used in a method chain alongside other `where_*` methods as well as methods such as `offset`, `limit` and `order_by_*`. The contents of the string you supply will be connected with preceding and following WHERE clauses with AND. 234 | 235 | $people = ORM::for_table('person') 236 | ->where('name', 'Fred') 237 | ->where_raw('(`age` = ? OR `age` = ?)', array(20, 25)) 238 | ->order_by_asc('name') 239 | ->find_many(); 240 | 241 | // Creates SQL: 242 | SELECT * FROM `person` WHERE `name` = "Fred" AND (`age` = 20 OR `age` = 25) ORDER BY `name` ASC; 243 | 244 | Note that this method only supports "question mark placeholder" syntax, and NOT "named placeholder" syntax. This is because PDO does not allow queries that contain a mixture of placeholder types. Also, you should ensure that the number of question mark placeholders in the string exactly matches the number of elements in the array. 245 | 246 | If you require yet more flexibility, you can manually specify the entire query. See *Raw queries* below. 247 | 248 | ##### Limits and offsets ##### 249 | 250 | *Note that these methods **do not** escape their query parameters and so these should **not** be passed directly from user input.* 251 | 252 | The `limit` and `offset` methods map pretty closely to their SQL equivalents. 253 | 254 | $people = ORM::for_table('person')->where('gender', 'female')->limit(5)->offset(10)->find_many(); 255 | 256 | ##### Ordering ##### 257 | 258 | *Note that these methods **do not** escape their query parameters and so these should **not** be passed directly from user input.* 259 | 260 | Two methods are provided to add `ORDER BY` clauses to your query. These are `order_by_desc` and `order_by_asc`, each of which takes a column name to sort by. The column names will be quoted. 261 | 262 | $people = ORM::for_table('person')->order_by_asc('gender')->order_by_desc('name')->find_many(); 263 | 264 | If you want to order by something other than a column name, then use the `order_by_expr` method to add an unquoted SQL expression as an `ORDER BY` clause. 265 | 266 | $people = ORM::for_table('person')->order_by_expr('SOUNDEX(`name`)')->find_many(); 267 | 268 | #### Grouping #### 269 | 270 | *Note that this method **does not** escape it query parameter and so this should **not** by passed directly from user input.* 271 | 272 | To add a `GROUP BY` clause to your query, call the `group_by` method, passing in the column name. You can call this method multiple times to add further columns. 273 | 274 | $people = ORM::for_table('person')->where('gender', 'female')->group_by('name')->find_many(); 275 | 276 | It is also possible to `GROUP BY` a database expression: 277 | 278 | $people = ORM::for_table('person')->where('gender', 'female')->group_by_expr("FROM_UNIXTIME(`time`, '%Y-%m')")->find_many(); 279 | 280 | #### Result columns #### 281 | 282 | By default, all columns in the `SELECT` statement are returned from your query. That is, calling: 283 | 284 | $people = ORM::for_table('person')->find_many(); 285 | 286 | Will result in the query: 287 | 288 | SELECT * FROM `person`; 289 | 290 | The `select` method gives you control over which columns are returned. Call `select` multiple times to specify columns to return or use [`select_many`](#shortcuts-for-specifying-many-columns) to specify many columns at once. 291 | 292 | $people = ORM::for_table('person')->select('name')->select('age')->find_many(); 293 | 294 | Will result in the query: 295 | 296 | SELECT `name`, `age` FROM `person`; 297 | 298 | Optionally, you may also supply a second argument to `select` to specify an alias for the column: 299 | 300 | $people = ORM::for_table('person')->select('name', 'person_name')->find_many(); 301 | 302 | Will result in the query: 303 | 304 | SELECT `name` AS `person_name` FROM `person`; 305 | 306 | Column names passed to `select` are quoted automatically, even if they contain `table.column`-style identifiers: 307 | 308 | $people = ORM::for_table('person')->select('person.name', 'person_name')->find_many(); 309 | 310 | Will result in the query: 311 | 312 | SELECT `person`.`name` AS `person_name` FROM `person`; 313 | 314 | If you wish to override this behaviour (for example, to supply a database expression) you should instead use the `select_expr` method. Again, this takes the alias as an optional second argument. You can specify multiple expressions by calling `select_expr` multiple times or use [`select_many_expr`](#shortcuts-for-specifying-many-columns) to specify many expressions at once. 315 | 316 | // NOTE: For illustrative purposes only. To perform a count query, use the count() method. 317 | $people_count = ORM::for_table('person')->select_expr('COUNT(*)', 'count')->find_many(); 318 | 319 | Will result in the query: 320 | 321 | SELECT COUNT(*) AS `count` FROM `person`; 322 | 323 | ##### Shortcuts for specifying many columns ##### 324 | 325 | `select_many` and `select_many_expr` are very similar, but they allow you to specify more than one column at once. For example: 326 | 327 | $people = ORM::for_table('person')->select_many('name', 'age')->find_many(); 328 | 329 | Will result in the query: 330 | 331 | SELECT `name`, `age` FROM `person`; 332 | 333 | To specify aliases you need to pass in an array (aliases are set as the key in an associative array): 334 | 335 | $people = ORM::for_table('person')->select_many(array('first_name' => 'name', 'age'), 'height')->find_many(); 336 | 337 | Will result in the query: 338 | 339 | SELECT `name` AS `first_name`, `age`, `height` FROM `person`; 340 | 341 | You can pass the the following styles into `select_many` and `select_many_expr` by mixing and matching arrays and parameters: 342 | 343 | select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5') 344 | select_many('column', 'column2', 'column3') 345 | select_many(array('column', 'column2', 'column3'), 'column4', 'column5') 346 | 347 | All the select methods can also be chained with each other so you could do the following to get a neat select query including an expression: 348 | 349 | $people = ORM::for_table('person')->select_many('name', 'age', 'height')->select_expr('NOW()', 'timestamp')->find_many(); 350 | 351 | Will result in the query: 352 | 353 | SELECT `name`, `age`, `height`, NOW() AS `timestamp` FROM `person`; 354 | 355 | 356 | #### DISTINCT #### 357 | 358 | To add a `DISTINCT` keyword before the list of result columns in your query, add a call to `distinct()` to your query chain. 359 | 360 | $distinct_names = ORM::for_table('person')->distinct()->select('name')->find_many(); 361 | 362 | This will result in the query: 363 | 364 | SELECT DISTINCT `name` FROM `person`; 365 | 366 | #### Joins #### 367 | 368 | Idiorm has a family of methods for adding different types of `JOIN`s to the queries it constructs: 369 | 370 | Methods: `join`, `inner_join`, `left_outer_join`, `right_outer_join`, `full_outer_join`. 371 | 372 | Each of these methods takes the same set of arguments. The following description will use the basic `join` method as an example, but the same applies to each method. 373 | 374 | The first two arguments are mandatory. The first is the name of the table to join, and the second supplies the conditions for the join. The recommended way to specify the conditions is as an *array* containing three components: the first column, the operator, and the second column. The table and column names will be automatically quoted. For example: 375 | 376 | $results = ORM::for_table('person')->join('person_profile', array('person.id', '=', 'person_profile.person_id'))->find_many(); 377 | 378 | It is also possible to specify the condition as a string, which will be inserted as-is into the query. However, in this case the column names will **not** be escaped, and so this method should be used with caution. 379 | 380 | // Not recommended because the join condition will not be escaped. 381 | $results = ORM::for_table('person')->join('person_profile', 'person.id = person_profile.person_id')->find_many(); 382 | 383 | The `join` methods also take an optional third parameter, which is an `alias` for the table in the query. This is useful if you wish to join the table to *itself* to create a hierarchical structure. In this case, it is best combined with the `table_alias` method, which will add an alias to the *main* table associated with the ORM, and the `select` method to control which columns get returned. 384 | 385 | $results = ORM::for_table('person') 386 | ->table_alias('p1') 387 | ->select('p1.*') 388 | ->select('p2.name', 'parent_name') 389 | ->join('person', array('p1.parent', '=', 'p2.id'), 'p2') 390 | ->find_many(); 391 | 392 | #### Aggregate functions #### 393 | 394 | There is support for `MIN`, `AVG`, `MAX` and `SUM` in addition to `COUNT` (documented earlier). 395 | 396 | To return a minimum value of column, call the `min()` method. 397 | 398 | $min = ORM::for_table('person')->min('height'); 399 | 400 | The other functions (`AVG`, `MAX` and `SUM`) work in exactly the same manner. Supply a column name to perform the aggregate function on and it will return an integer. 401 | 402 | #### Raw queries #### 403 | 404 | If you need to perform more complex queries, you can completely specify the query to execute by using the `raw_query` method. This method takes a string and optionally an array of parameters. The string can contain placeholders, either in question mark or named placeholder syntax, which will be used to bind the parameters to the query. 405 | 406 | $people = ORM::for_table('person')->raw_query('SELECT p.* FROM person p JOIN role r ON p.role_id = r.id WHERE r.name = :role', array('role' => 'janitor'))->find_many(); 407 | 408 | The ORM class instance(s) returned will contain data for all the columns returned by the query. Note that you still must call `for_table` to bind the instances to a particular table, even though there is nothing to stop you from specifying a completely different table in the query. This is because if you wish to later called `save`, the ORM will need to know which table to update. 409 | 410 | Note that using `raw_query` is advanced and possibly dangerous, and Idiorm does not make any attempt to protect you from making errors when using this method. If you find yourself calling `raw_query` often, you may have misunderstood the purpose of using an ORM, or your application may be too complex for Idiorm. Consider using a more full-featured database abstraction system. 411 | 412 | ### Getting data from objects ### 413 | 414 | Once you've got a set of records (objects) back from a query, you can access properties on those objects (the values stored in the columns in its corresponding table) in two ways: by using the `get` method, or simply by accessing the property on the object directly: 415 | 416 | $person = ORM::for_table('person')->find_one(5); 417 | 418 | // The following two forms are equivalent 419 | $name = $person->get('name'); 420 | $name = $person->name; 421 | 422 | You can also get the all the data wrapped by an ORM instance using the `as_array` method. This will return an associative array mapping column names (keys) to their values. 423 | 424 | The `as_array` method takes column names as optional arguments. If one or more of these arguments is supplied, only matching column names will be returned. 425 | 426 | $person = ORM::for_table('person')->create(); 427 | 428 | $person->first_name = 'Fred'; 429 | $person->surname = 'Bloggs'; 430 | $person->age = 50; 431 | 432 | // Returns array('first_name' => 'Fred', 'surname' => 'Bloggs', 'age' => 50) 433 | $data = $person->as_array(); 434 | 435 | // Returns array('first_name' => 'Fred', 'age' => 50) 436 | $data = $person->as_array('first_name', 'age'); 437 | 438 | ### Updating records ### 439 | 440 | To update the database, change one or more of the properties of the object, then call the `save` method to commit the changes to the database. Again, you can change the values of the object's properties either by using the `set` method or by setting the value of the property directly. By using the `set` method it is also possible to update multiple properties at once, by passing in an associative array: 441 | 442 | $person = ORM::for_table('person')->find_one(5); 443 | 444 | // The following two forms are equivalent 445 | $person->set('name', 'Bob Smith'); 446 | $person->age = 20; 447 | 448 | // This is equivalent to the above two assignments 449 | $person->set(array( 450 | 'name' => 'Bob Smith', 451 | 'age' => 20 452 | )); 453 | 454 | // Syncronise the object with the database 455 | $person->save(); 456 | 457 | #### Properties containing expressions #### 458 | 459 | It is possible to set properties on the model that contain database expressions using the `set_expr` method. 460 | 461 | $person = ORM::for_table('person')->find_one(5);; 462 | $person->set('name', 'Bob Smith'); 463 | $person->age = 20; 464 | $person->set_expr('updated', 'NOW()'); 465 | $person->save(); 466 | 467 | The `updated` column's value will be inserted into query in its raw form therefore allowing the database to execute any functions referenced - such as `NOW()` in this case. 468 | 469 | ### Creating new records ### 470 | 471 | To add a new record, you need to first create an "empty" object instance. You then set values on the object as normal, and save it. 472 | 473 | $person = ORM::for_table('person')->create(); 474 | 475 | $person->name = 'Joe Bloggs'; 476 | $person->age = 40; 477 | 478 | $person->save(); 479 | 480 | After the object has been saved, you can call its `id()` method to find the autogenerated primary key value that the database assigned to it. 481 | 482 | #### Properties containing expressions #### 483 | 484 | It is possible to set properties on the model that contain database expressions using the `set_expr` method. 485 | 486 | $person = ORM::for_table('person')->create(); 487 | $person->set('name', 'Bob Smith'); 488 | $person->age = 20; 489 | $person->set_expr('added', 'NOW()'); 490 | $person->save(); 491 | 492 | The `added` column's value will be inserted into query in its raw form therefore allowing the database to execute any functions referenced - such as `NOW()` in this case. 493 | 494 | ### Checking whether a property has been modified ### 495 | 496 | To check whether a property has been changed since the object was created (or last saved), call the `is_dirty` method: 497 | 498 | $name_has_changed = $person->is_dirty('name'); // Returns true or false 499 | 500 | ### Deleting records ### 501 | 502 | To delete an object from the database, simply call its `delete` method. 503 | 504 | $person = ORM::for_table('person')->find_one(5); 505 | $person->delete(); 506 | 507 | To delete more than one object from the database, build a query: 508 | 509 | $person = ORM::for_table('person') 510 | ->where_equal('zipcode', 55555) 511 | ->delete_many(); 512 | 513 | ### Transactions ### 514 | 515 | Idiorm doesn't supply any extra methods to deal with transactions, but it's very easy to use PDO's built-in methods: 516 | 517 | // Start a transaction 518 | ORM::get_db()->beginTransaction(); 519 | 520 | // Commit a transaction 521 | ORM::get_db()->commit(); 522 | 523 | // Roll back a transaction 524 | ORM::get_db()->rollBack(); 525 | 526 | For more details, see [the PDO documentation on Transactions](http://www.php.net/manual/en/pdo.transactions.php). 527 | 528 | ### Configuration ### 529 | 530 | Other than setting the DSN string for the database connection (see above), the `configure` method can be used to set some other simple options on the ORM class. Modifying settings involves passing a key/value pair to the `configure` method, representing the setting you wish to modify and the value you wish to set it to. 531 | 532 | ORM::configure('setting_name', 'value_for_setting'); 533 | 534 | A shortcut is provided to allow passing multiple key/value pairs at once. 535 | 536 | ORM::configure(array( 537 | 'setting_name_1' => 'value_for_setting_1', 538 | 'setting_name_2' => 'value_for_setting_2', 539 | 'etc' => 'etc' 540 | )); 541 | 542 | #### Database authentication details #### 543 | 544 | Settings: `username` and `password` 545 | 546 | Some database adapters (such as MySQL) require a username and password to be supplied separately to the DSN string. These settings allow you to provide these values. A typical MySQL connection setup might look like this: 547 | 548 | ORM::configure('mysql:host=localhost;dbname=my_database'); 549 | ORM::configure('username', 'database_user'); 550 | ORM::configure('password', 'top_secret'); 551 | 552 | Or you can combine the connection setup into a single line using the configuration array shortcut: 553 | 554 | ORM::configure(array( 555 | 'mysql:host=localhost;dbname=my_database', 556 | 'username' => 'database_user', 557 | 'password' => 'top_secret' 558 | )); 559 | 560 | #### PDO Driver Options #### 561 | 562 | Setting: `driver_options` 563 | 564 | Some database adapters require (or allow) an array of driver-specific configuration options. This setting allows you to pass these options through to the PDO constructor. For more information, see [the PDO documentation](http://www.php.net/manual/en/pdo.construct.php). For example, to force the MySQL driver to use UTF-8 for the connection: 565 | 566 | ORM::configure('driver_options', array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8')); 567 | 568 | 569 | #### PDO Error Mode #### 570 | 571 | Setting: `error_mode` 572 | 573 | This can be used to set the `PDO::ATTR_ERRMODE` setting on the database connection class used by Idiorm. It should be passed one of the class constants defined by PDO. For example: 574 | 575 | ORM::configure('error_mode', PDO::ERRMODE_WARNING); 576 | 577 | The default setting is `PDO::ERRMODE_EXCEPTION`. For full details of the error modes available, see [the PDO documentation](http://uk2.php.net/manual/en/pdo.setattribute.php). 578 | 579 | #### Identifier quote character #### 580 | 581 | Setting: `identifier_quote_character` 582 | 583 | Set the character used to quote identifiers (eg table name, column name). If this is not set, it will be autodetected based on the database driver being used by PDO. 584 | 585 | #### ID Column #### 586 | 587 | By default, the ORM assumes that all your tables have a primary key column called `id`. There are two ways to override this: for all tables in the database, or on a per-table basis. 588 | 589 | Setting: `id_column` 590 | 591 | This setting is used to configure the name of the primary key column for all tables. If your ID column is called `primary_key`, use: 592 | 593 | ORM::configure('id_column', 'primary_key'); 594 | 595 | Setting: `id_column_overrides` 596 | 597 | This setting is used to specify the primary key column name for each table separately. It takes an associative array mapping table names to column names. If, for example, your ID column names include the name of the table, you can use the following configuration: 598 | 599 | ORM::configure('id_column_overrides', array( 600 | 'person' => 'person_id', 601 | 'role' => 'role_id', 602 | )); 603 | 604 | #### Query logging #### 605 | 606 | Setting: `logging` 607 | 608 | Idiorm can log all queries it executes. To enable query logging, set the `logging` option to `true` (it is `false` by default). 609 | 610 | When query logging is enabled, you can use two static methods to access the log. `ORM::get_last_query()` returns the most recent query executed. `ORM::get_query_log()` returns an array of all queries executed. 611 | 612 | #### Query caching #### 613 | 614 | Setting: `caching` 615 | 616 | Idiorm can cache the queries it executes during a request. To enable query caching, set the `caching` option to `true` (it is `false` by default). 617 | 618 | When query caching is enabled, Idiorm will cache the results of every `SELECT` query it executes. If Idiorm encounters a query that has already been run, it will fetch the results directly from its cache and not perform a database query. 619 | 620 | ##### Warnings and gotchas ##### 621 | 622 | * Note that this is an in-memory cache that only persists data for the duration of a single request. This is *not* a replacement for a persistent cache such as [Memcached](http://www.memcached.org/). 623 | 624 | * Idiorm's cache is very simple, and does not attempt to invalidate itself when data changes. This means that if you run a query to retrieve some data, modify and save it, and then run the same query again, the results will be stale (ie, they will not reflect your modifications). This could potentially cause subtle bugs in your application. If you have caching enabled and you are experiencing odd behaviour, disable it and try again. If you do need to perform such operations but still wish to use the cache, you can call the `ORM::clear_cache()` to clear all existing cached queries. 625 | 626 | * Enabling the cache will increase the memory usage of your application, as all database rows that are fetched during each request are held in memory. If you are working with large quantities of data, you may wish to disable the cache. 627 | -------------------------------------------------------------------------------- /idiorm.php: -------------------------------------------------------------------------------- 1 | 'sqlite::memory:', 58 | 'id_column' => 'id', 59 | 'id_column_overrides' => array(), 60 | 'error_mode' => PDO::ERRMODE_EXCEPTION, 61 | 'username' => null, 62 | 'password' => null, 63 | 'driver_options' => null, 64 | 'identifier_quote_character' => null, // if this is null, will be autodetected 65 | 'logging' => false, 66 | 'caching' => false, 67 | ); 68 | 69 | // Database connection, instance of the PDO class 70 | protected static $_db; 71 | 72 | // Last query run, only populated if logging is enabled 73 | protected static $_last_query; 74 | 75 | // Log of all queries run, only populated if logging is enabled 76 | protected static $_query_log = array(); 77 | 78 | // Query cache, only used if query caching is enabled 79 | protected static $_query_cache = array(); 80 | 81 | // --------------------------- // 82 | // --- INSTANCE PROPERTIES --- // 83 | // --------------------------- // 84 | 85 | // The name of the table the current ORM instance is associated with 86 | protected $_table_name; 87 | 88 | // Alias for the table to be used in SELECT queries 89 | protected $_table_alias = null; 90 | 91 | // Values to be bound to the query 92 | protected $_values = array(); 93 | 94 | // Columns to select in the result 95 | protected $_result_columns = array('*'); 96 | 97 | // Are we using the default result column or have these been manually changed? 98 | protected $_using_default_result_columns = true; 99 | 100 | // Join sources 101 | protected $_join_sources = array(); 102 | 103 | // Should the query include a DISTINCT keyword? 104 | protected $_distinct = false; 105 | 106 | // Is this a raw query? 107 | protected $_is_raw_query = false; 108 | 109 | // The raw query 110 | protected $_raw_query = ''; 111 | 112 | // The raw query parameters 113 | protected $_raw_parameters = array(); 114 | 115 | // Array of WHERE clauses 116 | protected $_where_conditions = array(); 117 | 118 | // LIMIT 119 | protected $_limit = null; 120 | 121 | // OFFSET 122 | protected $_offset = null; 123 | 124 | // ORDER BY 125 | protected $_order_by = array(); 126 | 127 | // GROUP BY 128 | protected $_group_by = array(); 129 | 130 | // The data for a hydrated instance of the class 131 | protected $_data = array(); 132 | 133 | // Fields that have been modified during the 134 | // lifetime of the object 135 | protected $_dirty_fields = array(); 136 | 137 | // Fields that are to be inserted in the DB raw 138 | protected $_expr_fields = array(); 139 | 140 | // Is this a new object (has create() been called)? 141 | protected $_is_new = false; 142 | 143 | // Name of the column to use as the primary key for 144 | // this instance only. Overrides the config settings. 145 | protected $_instance_id_column = null; 146 | 147 | // ---------------------- // 148 | // --- STATIC METHODS --- // 149 | // ---------------------- // 150 | 151 | /** 152 | * Pass configuration settings to the class in the form of 153 | * key/value pairs. As a shortcut, if the second argument 154 | * is omitted and the key is a string, the setting is 155 | * assumed to be the DSN string used by PDO to connect 156 | * to the database (often, this will be the only configuration 157 | * required to use Idiorm). If you have more than one setting 158 | * you wish to configure, another shortcut is to pass an array 159 | * of settings (and omit the second argument). 160 | */ 161 | public static function configure($key, $value=null) { 162 | if (is_array($key)) { 163 | // Shortcut: If only one array argument is passed, 164 | // assume it's an array of configuration settings 165 | foreach ($key as $conf_key => $conf_value) { 166 | self::configure($conf_key, $conf_value); 167 | } 168 | } else { 169 | if (is_null($value)) { 170 | // Shortcut: If only one string argument is passed, 171 | // assume it's a connection string 172 | $value = $key; 173 | $key = 'connection_string'; 174 | } 175 | self::$_config[$key] = $value; 176 | } 177 | } 178 | 179 | /** 180 | * Despite its slightly odd name, this is actually the factory 181 | * method used to acquire instances of the class. It is named 182 | * this way for the sake of a readable interface, ie 183 | * ORM::for_table('table_name')->find_one()-> etc. As such, 184 | * this will normally be the first method called in a chain. 185 | */ 186 | public static function for_table($table_name) { 187 | self::_setup_db(); 188 | return new self($table_name); 189 | } 190 | 191 | /** 192 | * Set up the database connection used by the class. 193 | */ 194 | protected static function _setup_db() { 195 | if (!is_object(self::$_db)) { 196 | $connection_string = self::$_config['connection_string']; 197 | $username = self::$_config['username']; 198 | $password = self::$_config['password']; 199 | $driver_options = self::$_config['driver_options']; 200 | $db = new PDO($connection_string, $username, $password, $driver_options); 201 | $db->setAttribute(PDO::ATTR_ERRMODE, self::$_config['error_mode']); 202 | self::set_db($db); 203 | } 204 | } 205 | 206 | /** 207 | * Set the PDO object used by Idiorm to communicate with the database. 208 | * This is public in case the ORM should use a ready-instantiated 209 | * PDO object as its database connection. 210 | */ 211 | public static function set_db($db) { 212 | self::$_db = $db; 213 | self::_setup_identifier_quote_character(); 214 | } 215 | 216 | /** 217 | * Detect and initialise the character used to quote identifiers 218 | * (table names, column names etc). If this has been specified 219 | * manually using ORM::configure('identifier_quote_character', 'some-char'), 220 | * this will do nothing. 221 | */ 222 | public static function _setup_identifier_quote_character() { 223 | if (is_null(self::$_config['identifier_quote_character'])) { 224 | self::$_config['identifier_quote_character'] = self::_detect_identifier_quote_character(); 225 | } 226 | } 227 | 228 | /** 229 | * Return the correct character used to quote identifiers (table 230 | * names, column names etc) by looking at the driver being used by PDO. 231 | */ 232 | protected static function _detect_identifier_quote_character() { 233 | switch(self::$_db->getAttribute(PDO::ATTR_DRIVER_NAME)) { 234 | case 'pgsql': 235 | case 'sqlsrv': 236 | case 'dblib': 237 | case 'mssql': 238 | case 'sybase': 239 | return '"'; 240 | case 'mysql': 241 | case 'sqlite': 242 | case 'sqlite2': 243 | default: 244 | return '`'; 245 | } 246 | } 247 | 248 | /** 249 | * Returns the PDO instance used by the the ORM to communicate with 250 | * the database. This can be called if any low-level DB access is 251 | * required outside the class. 252 | */ 253 | public static function get_db() { 254 | self::_setup_db(); // required in case this is called before Idiorm is instantiated 255 | return self::$_db; 256 | } 257 | 258 | /** 259 | * Executes a raw query as a wrapper for PDOStatement::execute. 260 | * Useful for queries that can't be accomplished through Idiorm, 261 | * particularly those using engine-specific features. 262 | * @example raw_execute('SELECT `name`, AVG(`order`) FROM `customer` GROUP BY `name` HAVING AVG(`order`) > 10') 263 | * @example raw_execute('INSERT OR REPLACE INTO `widget` (`id`, `name`) SELECT `id`, `name` FROM `other_table`') 264 | * @param string $query The raw SQL query 265 | * @param array $parameters Optional bound parameters 266 | * @return bool Success 267 | */ 268 | public static function raw_execute($query, $parameters = array()) { 269 | self::_setup_db(); 270 | 271 | self::_log_query($query, $parameters); 272 | $statement = self::$_db->prepare($query); 273 | return $statement->execute($parameters); 274 | } 275 | 276 | /** 277 | * Add a query to the internal query log. Only works if the 278 | * 'logging' config option is set to true. 279 | * 280 | * This works by manually binding the parameters to the query - the 281 | * query isn't executed like this (PDO normally passes the query and 282 | * parameters to the database which takes care of the binding) but 283 | * doing it this way makes the logged queries more readable. 284 | */ 285 | protected static function _log_query($query, $parameters) { 286 | // If logging is not enabled, do nothing 287 | if (!self::$_config['logging']) { 288 | return false; 289 | } 290 | 291 | if (count($parameters) > 0) { 292 | // Escape the parameters 293 | $parameters = array_map(array(self::$_db, 'quote'), $parameters); 294 | 295 | // Avoid %format collision for vsprintf 296 | $query = str_replace("%", "%%", $query); 297 | 298 | // Replace placeholders in the query for vsprintf 299 | if(false !== strpos($query, "'") || false !== strpos($query, '"')) { 300 | $query = IdiormString::str_replace_outside_quotes("?", "%s", $query); 301 | } else { 302 | $query = str_replace("?", "%s", $query); 303 | } 304 | 305 | // Replace the question marks in the query with the parameters 306 | $bound_query = vsprintf($query, $parameters); 307 | } else { 308 | $bound_query = $query; 309 | } 310 | 311 | self::$_last_query = $bound_query; 312 | self::$_query_log[] = $bound_query; 313 | return true; 314 | } 315 | 316 | /** 317 | * Get the last query executed. Only works if the 318 | * 'logging' config option is set to true. Otherwise 319 | * this will return null. 320 | */ 321 | public static function get_last_query() { 322 | return self::$_last_query; 323 | } 324 | 325 | /** 326 | * Get an array containing all the queries run up to 327 | * now. Only works if the 'logging' config option is 328 | * set to true. Otherwise returned array will be empty. 329 | */ 330 | public static function get_query_log() { 331 | return self::$_query_log; 332 | } 333 | 334 | // ------------------------ // 335 | // --- INSTANCE METHODS --- // 336 | // ------------------------ // 337 | 338 | /** 339 | * "Private" constructor; shouldn't be called directly. 340 | * Use the ORM::for_table factory method instead. 341 | */ 342 | protected function __construct($table_name, $data=array()) { 343 | $this->_table_name = $table_name; 344 | $this->_data = $data; 345 | } 346 | 347 | /** 348 | * Create a new, empty instance of the class. Used 349 | * to add a new row to your database. May optionally 350 | * be passed an associative array of data to populate 351 | * the instance. If so, all fields will be flagged as 352 | * dirty so all will be saved to the database when 353 | * save() is called. 354 | */ 355 | public function create($data=null) { 356 | $this->_is_new = true; 357 | if (!is_null($data)) { 358 | return $this->hydrate($data)->force_all_dirty(); 359 | } 360 | return $this; 361 | } 362 | 363 | /** 364 | * Specify the ID column to use for this instance or array of instances only. 365 | * This overrides the id_column and id_column_overrides settings. 366 | * 367 | * This is mostly useful for libraries built on top of Idiorm, and will 368 | * not normally be used in manually built queries. If you don't know why 369 | * you would want to use this, you should probably just ignore it. 370 | */ 371 | public function use_id_column($id_column) { 372 | $this->_instance_id_column = $id_column; 373 | return $this; 374 | } 375 | 376 | /** 377 | * Create an ORM instance from the given row (an associative 378 | * array of data fetched from the database) 379 | */ 380 | protected function _create_instance_from_row($row) { 381 | $instance = self::for_table($this->_table_name); 382 | $instance->use_id_column($this->_instance_id_column); 383 | $instance->hydrate($row); 384 | return $instance; 385 | } 386 | 387 | /** 388 | * Tell the ORM that you are expecting a single result 389 | * back from your query, and execute it. Will return 390 | * a single instance of the ORM class, or false if no 391 | * rows were returned. 392 | * As a shortcut, you may supply an ID as a parameter 393 | * to this method. This will perform a primary key 394 | * lookup on the table. 395 | */ 396 | public function find_one($id=null) { 397 | if (!is_null($id)) { 398 | $this->where_id_is($id); 399 | } 400 | $this->limit(1); 401 | $rows = $this->_run(); 402 | 403 | if (empty($rows)) { 404 | return false; 405 | } 406 | 407 | return $this->_create_instance_from_row($rows[0]); 408 | } 409 | 410 | /** 411 | * Tell the ORM that you are expecting multiple results 412 | * from your query, and execute it. Will return an array 413 | * of instances of the ORM class, or an empty array if 414 | * no rows were returned. 415 | */ 416 | public function find_many() { 417 | $rows = $this->_run(); 418 | return array_map(array($this, '_create_instance_from_row'), $rows); 419 | } 420 | 421 | /** 422 | * Tell the ORM that you are expecting multiple results 423 | * from your query, and execute it. Will return an array, 424 | * or an empty array if no rows were returned. 425 | * @return array 426 | */ 427 | public function find_array() { 428 | return $this->_run(); 429 | } 430 | 431 | /** 432 | * Tell the ORM that you wish to execute a COUNT query. 433 | * Will return an integer representing the number of 434 | * rows returned. 435 | */ 436 | public function count($column = '*') { 437 | return $this->_call_aggregate_db_function(__FUNCTION__, $column); 438 | } 439 | 440 | /** 441 | * Tell the ORM that you wish to execute a MAX query. 442 | * Will return the max value of the choosen column. 443 | */ 444 | public function max($column) { 445 | return $this->_call_aggregate_db_function(__FUNCTION__, $column); 446 | } 447 | 448 | /** 449 | * Tell the ORM that you wish to execute a MIN query. 450 | * Will return the min value of the choosen column. 451 | */ 452 | public function min($column) { 453 | return $this->_call_aggregate_db_function(__FUNCTION__, $column); 454 | } 455 | 456 | /** 457 | * Tell the ORM that you wish to execute a AVG query. 458 | * Will return the average value of the choosen column. 459 | */ 460 | public function avg($column) { 461 | return $this->_call_aggregate_db_function(__FUNCTION__, $column); 462 | } 463 | 464 | /** 465 | * Tell the ORM that you wish to execute a SUM query. 466 | * Will return the sum of the choosen column. 467 | */ 468 | public function sum($column) { 469 | return $this->_call_aggregate_db_function(__FUNCTION__, $column); 470 | } 471 | 472 | /** 473 | * Execute an aggregate query on the current connection. 474 | * @param string $sql_function The aggregate function to call eg. MIN, COUNT, etc 475 | * @param string $column The column to execute the aggregate query against 476 | * @return int 477 | */ 478 | protected function _call_aggregate_db_function($sql_function, $column) { 479 | $alias = strtolower($sql_function); 480 | $sql_function = strtoupper($sql_function); 481 | if('*' != $column) { 482 | $column = $this->_quote_identifier($column); 483 | } 484 | $this->select_expr("$sql_function($column)", $alias); 485 | $result = $this->find_one(); 486 | return ($result !== false && isset($result->$alias)) ? (int) $result->$alias : 0; 487 | } 488 | 489 | /** 490 | * This method can be called to hydrate (populate) this 491 | * instance of the class from an associative array of data. 492 | * This will usually be called only from inside the class, 493 | * but it's public in case you need to call it directly. 494 | */ 495 | public function hydrate($data=array()) { 496 | $this->_data = $data; 497 | return $this; 498 | } 499 | 500 | /** 501 | * Force the ORM to flag all the fields in the $data array 502 | * as "dirty" and therefore update them when save() is called. 503 | */ 504 | public function force_all_dirty() { 505 | $this->_dirty_fields = $this->_data; 506 | return $this; 507 | } 508 | 509 | /** 510 | * Perform a raw query. The query can contain placeholders in 511 | * either named or question mark style. If placeholders are 512 | * used, the parameters should be an array of values which will 513 | * be bound to the placeholders in the query. If this method 514 | * is called, all other query building methods will be ignored. 515 | */ 516 | public function raw_query($query, $parameters = array()) { 517 | $this->_is_raw_query = true; 518 | $this->_raw_query = $query; 519 | $this->_raw_parameters = $parameters; 520 | return $this; 521 | } 522 | 523 | /** 524 | * Add an alias for the main table to be used in SELECT queries 525 | */ 526 | public function table_alias($alias) { 527 | $this->_table_alias = $alias; 528 | return $this; 529 | } 530 | 531 | /** 532 | * Internal method to add an unquoted expression to the set 533 | * of columns returned by the SELECT query. The second optional 534 | * argument is the alias to return the expression as. 535 | */ 536 | protected function _add_result_column($expr, $alias=null) { 537 | if (!is_null($alias)) { 538 | $expr .= " AS " . $this->_quote_identifier($alias); 539 | } 540 | 541 | if ($this->_using_default_result_columns) { 542 | $this->_result_columns = array($expr); 543 | $this->_using_default_result_columns = false; 544 | } else { 545 | $this->_result_columns[] = $expr; 546 | } 547 | return $this; 548 | } 549 | 550 | /** 551 | * Add a column to the list of columns returned by the SELECT 552 | * query. This defaults to '*'. The second optional argument is 553 | * the alias to return the column as. 554 | */ 555 | public function select($column, $alias=null) { 556 | $column = $this->_quote_identifier($column); 557 | return $this->_add_result_column($column, $alias); 558 | } 559 | 560 | /** 561 | * Add an unquoted expression to the list of columns returned 562 | * by the SELECT query. The second optional argument is 563 | * the alias to return the column as. 564 | */ 565 | public function select_expr($expr, $alias=null) { 566 | return $this->_add_result_column($expr, $alias); 567 | } 568 | 569 | /** 570 | * Add columns to the list of columns returned by the SELECT 571 | * query. This defaults to '*'. Many columns can be supplied 572 | * as either an array or as a list of parameters to the method. 573 | * 574 | * Note that the alias must not be numeric - if you want a 575 | * numeric alias then prepend it with some alpha chars. eg. a1 576 | * 577 | * @example select_many(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5'); 578 | * @example select_many('column', 'column2', 'column3'); 579 | * @example select_many(array('column', 'column2', 'column3'), 'column4', 'column5'); 580 | * 581 | * @return \ORM 582 | */ 583 | public function select_many() { 584 | $columns = func_get_args(); 585 | if(!empty($columns)) { 586 | $columns = $this->_normalise_select_many_columns($columns); 587 | foreach($columns as $alias => $column) { 588 | if(is_numeric($alias)) { 589 | $alias = null; 590 | } 591 | $this->select($column, $alias); 592 | } 593 | } 594 | return $this; 595 | } 596 | 597 | /** 598 | * Add an unquoted expression to the list of columns returned 599 | * by the SELECT query. Many columns can be supplied as either 600 | * an array or as a list of parameters to the method. 601 | * 602 | * Note that the alias must not be numeric - if you want a 603 | * numeric alias then prepend it with some alpha chars. eg. a1 604 | * 605 | * @example select_many_expr(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5') 606 | * @example select_many_expr('column', 'column2', 'column3') 607 | * @example select_many_expr(array('column', 'column2', 'column3'), 'column4', 'column5') 608 | * 609 | * @return \ORM 610 | */ 611 | public function select_many_expr() { 612 | $columns = func_get_args(); 613 | if(!empty($columns)) { 614 | $columns = $this->_normalise_select_many_columns($columns); 615 | foreach($columns as $alias => $column) { 616 | if(is_numeric($alias)) { 617 | $alias = null; 618 | } 619 | $this->select_expr($column, $alias); 620 | } 621 | } 622 | return $this; 623 | } 624 | 625 | /** 626 | * Take a column specification for the select many methods and convert it 627 | * into a normalised array of columns and aliases. 628 | * 629 | * It is designed to turn the following styles into a normalised array: 630 | * 631 | * array(array('alias' => 'column', 'column2', 'alias2' => 'column3'), 'column4', 'column5')) 632 | * 633 | * @param array $columns 634 | * @return array 635 | */ 636 | protected function _normalise_select_many_columns($columns) { 637 | $return = array(); 638 | foreach($columns as $column) { 639 | if(is_array($column)) { 640 | foreach($column as $key => $value) { 641 | if(!is_numeric($key)) { 642 | $return[$key] = $value; 643 | } else { 644 | $return[] = $value; 645 | } 646 | } 647 | } else { 648 | $return[] = $column; 649 | } 650 | } 651 | return $return; 652 | } 653 | 654 | /** 655 | * Add a DISTINCT keyword before the list of columns in the SELECT query 656 | */ 657 | public function distinct() { 658 | $this->_distinct = true; 659 | return $this; 660 | } 661 | 662 | /** 663 | * Internal method to add a JOIN source to the query. 664 | * 665 | * The join_operator should be one of INNER, LEFT OUTER, CROSS etc - this 666 | * will be prepended to JOIN. 667 | * 668 | * The table should be the name of the table to join to. 669 | * 670 | * The constraint may be either a string or an array with three elements. If it 671 | * is a string, it will be compiled into the query as-is, with no escaping. The 672 | * recommended way to supply the constraint is as an array with three elements: 673 | * 674 | * first_column, operator, second_column 675 | * 676 | * Example: array('user.id', '=', 'profile.user_id') 677 | * 678 | * will compile to 679 | * 680 | * ON `user`.`id` = `profile`.`user_id` 681 | * 682 | * The final (optional) argument specifies an alias for the joined table. 683 | */ 684 | protected function _add_join_source($join_operator, $table, $constraint, $table_alias=null) { 685 | 686 | $join_operator = trim("{$join_operator} JOIN"); 687 | 688 | $table = $this->_quote_identifier($table); 689 | 690 | // Add table alias if present 691 | if (!is_null($table_alias)) { 692 | $table_alias = $this->_quote_identifier($table_alias); 693 | $table .= " {$table_alias}"; 694 | } 695 | 696 | // Build the constraint 697 | if (is_array($constraint)) { 698 | list($first_column, $operator, $second_column) = $constraint; 699 | $first_column = $this->_quote_identifier($first_column); 700 | $second_column = $this->_quote_identifier($second_column); 701 | $constraint = "{$first_column} {$operator} {$second_column}"; 702 | } 703 | 704 | $this->_join_sources[] = "{$join_operator} {$table} ON {$constraint}"; 705 | return $this; 706 | } 707 | 708 | /** 709 | * Add a simple JOIN source to the query 710 | */ 711 | public function join($table, $constraint, $table_alias=null) { 712 | return $this->_add_join_source("", $table, $constraint, $table_alias); 713 | } 714 | 715 | /** 716 | * Add an INNER JOIN souce to the query 717 | */ 718 | public function inner_join($table, $constraint, $table_alias=null) { 719 | return $this->_add_join_source("INNER", $table, $constraint, $table_alias); 720 | } 721 | 722 | /** 723 | * Add a LEFT OUTER JOIN souce to the query 724 | */ 725 | public function left_outer_join($table, $constraint, $table_alias=null) { 726 | return $this->_add_join_source("LEFT OUTER", $table, $constraint, $table_alias); 727 | } 728 | 729 | /** 730 | * Add an RIGHT OUTER JOIN souce to the query 731 | */ 732 | public function right_outer_join($table, $constraint, $table_alias=null) { 733 | return $this->_add_join_source("RIGHT OUTER", $table, $constraint, $table_alias); 734 | } 735 | 736 | /** 737 | * Add an FULL OUTER JOIN souce to the query 738 | */ 739 | public function full_outer_join($table, $constraint, $table_alias=null) { 740 | return $this->_add_join_source("FULL OUTER", $table, $constraint, $table_alias); 741 | } 742 | 743 | /** 744 | * Internal method to add a WHERE condition to the query 745 | */ 746 | protected function _add_where($fragment, $values=array()) { 747 | if (!is_array($values)) { 748 | $values = array($values); 749 | } 750 | $this->_where_conditions[] = array( 751 | self::WHERE_FRAGMENT => $fragment, 752 | self::WHERE_VALUES => $values, 753 | ); 754 | return $this; 755 | } 756 | 757 | /** 758 | * Helper method to compile a simple COLUMN SEPARATOR VALUE 759 | * style WHERE condition into a string and value ready to 760 | * be passed to the _add_where method. Avoids duplication 761 | * of the call to _quote_identifier 762 | */ 763 | protected function _add_simple_where($column_name, $separator, $value) { 764 | // Add the table name in case of ambiguous columns 765 | if (count($this->_join_sources) > 0 && strpos($column_name, '.') === false) { 766 | $column_name = "{$this->_table_name}.{$column_name}"; 767 | } 768 | $column_name = $this->_quote_identifier($column_name); 769 | return $this->_add_where("{$column_name} {$separator} ?", $value); 770 | } 771 | 772 | /** 773 | * Return a string containing the given number of question marks, 774 | * separated by commas. Eg "?, ?, ?" 775 | */ 776 | protected function _create_placeholders($fields) { 777 | if(!empty($fields)) { 778 | $db_fields = array(); 779 | foreach($fields as $key => $value) { 780 | // Process expression fields directly into the query 781 | if(array_key_exists($key, $this->_expr_fields)) { 782 | $db_fields[] = $value; 783 | } else { 784 | $db_fields[] = '?'; 785 | } 786 | } 787 | return implode(', ', $db_fields); 788 | } 789 | } 790 | 791 | /** 792 | * Add a WHERE column = value clause to your query. Each time 793 | * this is called in the chain, an additional WHERE will be 794 | * added, and these will be ANDed together when the final query 795 | * is built. 796 | */ 797 | public function where($column_name, $value) { 798 | return $this->where_equal($column_name, $value); 799 | } 800 | 801 | /** 802 | * More explicitly named version of for the where() method. 803 | * Can be used if preferred. 804 | */ 805 | public function where_equal($column_name, $value) { 806 | return $this->_add_simple_where($column_name, '=', $value); 807 | } 808 | 809 | /** 810 | * Add a WHERE column != value clause to your query. 811 | */ 812 | public function where_not_equal($column_name, $value) { 813 | return $this->_add_simple_where($column_name, '!=', $value); 814 | } 815 | 816 | /** 817 | * Special method to query the table by its primary key 818 | */ 819 | public function where_id_is($id) { 820 | return $this->where($this->_get_id_column_name(), $id); 821 | } 822 | 823 | /** 824 | * Add a WHERE ... LIKE clause to your query. 825 | */ 826 | public function where_like($column_name, $value) { 827 | return $this->_add_simple_where($column_name, 'LIKE', $value); 828 | } 829 | 830 | /** 831 | * Add where WHERE ... NOT LIKE clause to your query. 832 | */ 833 | public function where_not_like($column_name, $value) { 834 | return $this->_add_simple_where($column_name, 'NOT LIKE', $value); 835 | } 836 | 837 | /** 838 | * Add a WHERE ... > clause to your query 839 | */ 840 | public function where_gt($column_name, $value) { 841 | return $this->_add_simple_where($column_name, '>', $value); 842 | } 843 | 844 | /** 845 | * Add a WHERE ... < clause to your query 846 | */ 847 | public function where_lt($column_name, $value) { 848 | return $this->_add_simple_where($column_name, '<', $value); 849 | } 850 | 851 | /** 852 | * Add a WHERE ... >= clause to your query 853 | */ 854 | public function where_gte($column_name, $value) { 855 | return $this->_add_simple_where($column_name, '>=', $value); 856 | } 857 | 858 | /** 859 | * Add a WHERE ... <= clause to your query 860 | */ 861 | public function where_lte($column_name, $value) { 862 | return $this->_add_simple_where($column_name, '<=', $value); 863 | } 864 | 865 | /** 866 | * Add a WHERE ... IN clause to your query 867 | */ 868 | public function where_in($column_name, $values) { 869 | $column_name = $this->_quote_identifier($column_name); 870 | $placeholders = $this->_create_placeholders($values); 871 | return $this->_add_where("{$column_name} IN ({$placeholders})", $values); 872 | } 873 | 874 | /** 875 | * Add a WHERE ... NOT IN clause to your query 876 | */ 877 | public function where_not_in($column_name, $values) { 878 | $column_name = $this->_quote_identifier($column_name); 879 | $placeholders = $this->_create_placeholders($values); 880 | return $this->_add_where("{$column_name} NOT IN ({$placeholders})", $values); 881 | } 882 | 883 | /** 884 | * Add a WHERE column IS NULL clause to your query 885 | */ 886 | public function where_null($column_name) { 887 | $column_name = $this->_quote_identifier($column_name); 888 | return $this->_add_where("{$column_name} IS NULL"); 889 | } 890 | 891 | /** 892 | * Add a WHERE column IS NOT NULL clause to your query 893 | */ 894 | public function where_not_null($column_name) { 895 | $column_name = $this->_quote_identifier($column_name); 896 | return $this->_add_where("{$column_name} IS NOT NULL"); 897 | } 898 | 899 | /** 900 | * Add a raw WHERE clause to the query. The clause should 901 | * contain question mark placeholders, which will be bound 902 | * to the parameters supplied in the second argument. 903 | */ 904 | public function where_raw($clause, $parameters=array()) { 905 | return $this->_add_where($clause, $parameters); 906 | } 907 | 908 | /** 909 | * Add a LIMIT to the query 910 | */ 911 | public function limit($limit) { 912 | $this->_limit = $limit; 913 | return $this; 914 | } 915 | 916 | /** 917 | * Add an OFFSET to the query 918 | */ 919 | public function offset($offset) { 920 | $this->_offset = $offset; 921 | return $this; 922 | } 923 | 924 | /** 925 | * Add an ORDER BY clause to the query 926 | */ 927 | protected function _add_order_by($column_name, $ordering) { 928 | $column_name = $this->_quote_identifier($column_name); 929 | $this->_order_by[] = "{$column_name} {$ordering}"; 930 | return $this; 931 | } 932 | 933 | /** 934 | * Add an ORDER BY column DESC clause 935 | */ 936 | public function order_by_desc($column_name) { 937 | return $this->_add_order_by($column_name, 'DESC'); 938 | } 939 | 940 | /** 941 | * Add an ORDER BY column ASC clause 942 | */ 943 | public function order_by_asc($column_name) { 944 | return $this->_add_order_by($column_name, 'ASC'); 945 | } 946 | 947 | /** 948 | * Add an unquoted expression as an ORDER BY clause 949 | */ 950 | public function order_by_expr($clause) { 951 | $this->_order_by[] = $clause; 952 | return $this; 953 | } 954 | 955 | /** 956 | * Add a column to the list of columns to GROUP BY 957 | */ 958 | public function group_by($column_name) { 959 | $column_name = $this->_quote_identifier($column_name); 960 | $this->_group_by[] = $column_name; 961 | return $this; 962 | } 963 | 964 | /** 965 | * Add an unquoted expression to the list of columns to GROUP BY 966 | */ 967 | public function group_by_expr($expr) { 968 | $this->_group_by[] = $expr; 969 | return $this; 970 | } 971 | 972 | /** 973 | * Build a SELECT statement based on the clauses that have 974 | * been passed to this instance by chaining method calls. 975 | */ 976 | protected function _build_select() { 977 | // If the query is raw, just set the $this->_values to be 978 | // the raw query parameters and return the raw query 979 | if ($this->_is_raw_query) { 980 | $this->_values = $this->_raw_parameters; 981 | return $this->_raw_query; 982 | } 983 | 984 | // Build and return the full SELECT statement by concatenating 985 | // the results of calling each separate builder method. 986 | return $this->_join_if_not_empty(" ", array( 987 | $this->_build_select_start(), 988 | $this->_build_join(), 989 | $this->_build_where(), 990 | $this->_build_group_by(), 991 | $this->_build_order_by(), 992 | $this->_build_limit(), 993 | $this->_build_offset(), 994 | )); 995 | } 996 | 997 | /** 998 | * Build the start of the SELECT statement 999 | */ 1000 | protected function _build_select_start() { 1001 | $result_columns = join(', ', $this->_result_columns); 1002 | 1003 | if ($this->_distinct) { 1004 | $result_columns = 'DISTINCT ' . $result_columns; 1005 | } 1006 | 1007 | $fragment = "SELECT {$result_columns} FROM " . $this->_quote_identifier($this->_table_name); 1008 | 1009 | if (!is_null($this->_table_alias)) { 1010 | $fragment .= " " . $this->_quote_identifier($this->_table_alias); 1011 | } 1012 | return $fragment; 1013 | } 1014 | 1015 | /** 1016 | * Build the JOIN sources 1017 | */ 1018 | protected function _build_join() { 1019 | if (count($this->_join_sources) === 0) { 1020 | return ''; 1021 | } 1022 | 1023 | return join(" ", $this->_join_sources); 1024 | } 1025 | 1026 | /** 1027 | * Build the WHERE clause(s) 1028 | */ 1029 | protected function _build_where() { 1030 | // If there are no WHERE clauses, return empty string 1031 | if (count($this->_where_conditions) === 0) { 1032 | return ''; 1033 | } 1034 | 1035 | $where_conditions = array(); 1036 | foreach ($this->_where_conditions as $condition) { 1037 | $where_conditions[] = $condition[self::WHERE_FRAGMENT]; 1038 | $this->_values = array_merge($this->_values, $condition[self::WHERE_VALUES]); 1039 | } 1040 | 1041 | return "WHERE " . join(" AND ", $where_conditions); 1042 | } 1043 | 1044 | /** 1045 | * Build GROUP BY 1046 | */ 1047 | protected function _build_group_by() { 1048 | if (count($this->_group_by) === 0) { 1049 | return ''; 1050 | } 1051 | return "GROUP BY " . join(", ", $this->_group_by); 1052 | } 1053 | 1054 | /** 1055 | * Build ORDER BY 1056 | */ 1057 | protected function _build_order_by() { 1058 | if (count($this->_order_by) === 0) { 1059 | return ''; 1060 | } 1061 | return "ORDER BY " . join(", ", $this->_order_by); 1062 | } 1063 | 1064 | /** 1065 | * Build LIMIT 1066 | */ 1067 | protected function _build_limit() { 1068 | if (!is_null($this->_limit)) { 1069 | return "LIMIT " . $this->_limit; 1070 | } 1071 | return ''; 1072 | } 1073 | 1074 | /** 1075 | * Build OFFSET 1076 | */ 1077 | protected function _build_offset() { 1078 | if (!is_null($this->_offset)) { 1079 | return "OFFSET " . $this->_offset; 1080 | } 1081 | return ''; 1082 | } 1083 | 1084 | /** 1085 | * Wrapper around PHP's join function which 1086 | * only adds the pieces if they are not empty. 1087 | */ 1088 | protected function _join_if_not_empty($glue, $pieces) { 1089 | $filtered_pieces = array(); 1090 | foreach ($pieces as $piece) { 1091 | if (is_string($piece)) { 1092 | $piece = trim($piece); 1093 | } 1094 | if (!empty($piece)) { 1095 | $filtered_pieces[] = $piece; 1096 | } 1097 | } 1098 | return join($glue, $filtered_pieces); 1099 | } 1100 | 1101 | /** 1102 | * Quote a string that is used as an identifier 1103 | * (table names, column names etc). This method can 1104 | * also deal with dot-separated identifiers eg table.column 1105 | */ 1106 | protected function _quote_identifier($identifier) { 1107 | $parts = explode('.', $identifier); 1108 | $parts = array_map(array($this, '_quote_identifier_part'), $parts); 1109 | return join('.', $parts); 1110 | } 1111 | 1112 | /** 1113 | * This method performs the actual quoting of a single 1114 | * part of an identifier, using the identifier quote 1115 | * character specified in the config (or autodetected). 1116 | */ 1117 | protected function _quote_identifier_part($part) { 1118 | if ($part === '*') { 1119 | return $part; 1120 | } 1121 | $quote_character = self::$_config['identifier_quote_character']; 1122 | return $quote_character . $part . $quote_character; 1123 | } 1124 | 1125 | /** 1126 | * Create a cache key for the given query and parameters. 1127 | */ 1128 | protected static function _create_cache_key($query, $parameters) { 1129 | $parameter_string = join(',', $parameters); 1130 | $key = $query . ':' . $parameter_string; 1131 | return sha1($key); 1132 | } 1133 | 1134 | /** 1135 | * Check the query cache for the given cache key. If a value 1136 | * is cached for the key, return the value. Otherwise, return false. 1137 | */ 1138 | protected static function _check_query_cache($cache_key) { 1139 | if (isset(self::$_query_cache[$cache_key])) { 1140 | return self::$_query_cache[$cache_key]; 1141 | } 1142 | return false; 1143 | } 1144 | 1145 | /** 1146 | * Clear the query cache 1147 | */ 1148 | public static function clear_cache() { 1149 | self::$_query_cache = array(); 1150 | } 1151 | 1152 | /** 1153 | * Add the given value to the query cache. 1154 | */ 1155 | protected static function _cache_query_result($cache_key, $value) { 1156 | self::$_query_cache[$cache_key] = $value; 1157 | } 1158 | 1159 | /** 1160 | * Execute the SELECT query that has been built up by chaining methods 1161 | * on this class. Return an array of rows as associative arrays. 1162 | */ 1163 | protected function _run() { 1164 | $query = $this->_build_select(); 1165 | $caching_enabled = self::$_config['caching']; 1166 | 1167 | if ($caching_enabled) { 1168 | $cache_key = self::_create_cache_key($query, $this->_values); 1169 | $cached_result = self::_check_query_cache($cache_key); 1170 | 1171 | if ($cached_result !== false) { 1172 | return $cached_result; 1173 | } 1174 | } 1175 | 1176 | self::_log_query($query, $this->_values); 1177 | $statement = self::$_db->prepare($query); 1178 | $statement->execute($this->_values); 1179 | 1180 | $rows = array(); 1181 | while ($row = $statement->fetch(PDO::FETCH_ASSOC)) { 1182 | $rows[] = $row; 1183 | } 1184 | 1185 | if ($caching_enabled) { 1186 | self::_cache_query_result($cache_key, $rows); 1187 | } 1188 | 1189 | return $rows; 1190 | } 1191 | 1192 | /** 1193 | * Return the raw data wrapped by this ORM 1194 | * instance as an associative array. Column 1195 | * names may optionally be supplied as arguments, 1196 | * if so, only those keys will be returned. 1197 | */ 1198 | public function as_array() { 1199 | if (func_num_args() === 0) { 1200 | return $this->_data; 1201 | } 1202 | $args = func_get_args(); 1203 | return array_intersect_key($this->_data, array_flip($args)); 1204 | } 1205 | 1206 | /** 1207 | * Return the value of a property of this object (database row) 1208 | * or null if not present. 1209 | */ 1210 | public function get($key) { 1211 | return isset($this->_data[$key]) ? $this->_data[$key] : null; 1212 | } 1213 | 1214 | /** 1215 | * Return the name of the column in the database table which contains 1216 | * the primary key ID of the row. 1217 | */ 1218 | protected function _get_id_column_name() { 1219 | if (!is_null($this->_instance_id_column)) { 1220 | return $this->_instance_id_column; 1221 | } 1222 | if (isset(self::$_config['id_column_overrides'][$this->_table_name])) { 1223 | return self::$_config['id_column_overrides'][$this->_table_name]; 1224 | } else { 1225 | return self::$_config['id_column']; 1226 | } 1227 | } 1228 | 1229 | /** 1230 | * Get the primary key ID of this object. 1231 | */ 1232 | public function id() { 1233 | return $this->get($this->_get_id_column_name()); 1234 | } 1235 | 1236 | /** 1237 | * Set a property to a particular value on this object. 1238 | * To set multiple properties at once, pass an associative array 1239 | * as the first parameter and leave out the second parameter. 1240 | * Flags the properties as 'dirty' so they will be saved to the 1241 | * database when save() is called. 1242 | */ 1243 | public function set($key, $value = null) { 1244 | $this->_set_orm_property($key, $value); 1245 | } 1246 | 1247 | public function set_expr($key, $value = null) { 1248 | $this->_set_orm_property($key, $value, true); 1249 | } 1250 | 1251 | /** 1252 | * Set a property on the ORM object. 1253 | * @param string|array $key 1254 | * @param string|null $value 1255 | * @param bool $raw Whether this value should be treated as raw or not 1256 | */ 1257 | protected function _set_orm_property($key, $value = null, $expr = false) { 1258 | if (!is_array($key)) { 1259 | $key = array($key => $value); 1260 | } 1261 | foreach ($key as $field => $value) { 1262 | $this->_data[$field] = $value; 1263 | $this->_dirty_fields[$field] = $value; 1264 | if (false === $expr and isset($this->_expr_fields[$field])) { 1265 | unset($this->_expr_fields[$field]); 1266 | } else if (true === $expr) { 1267 | $this->_expr_fields[$field] = true; 1268 | } 1269 | } 1270 | } 1271 | 1272 | /** 1273 | * Check whether the given field has been changed since this 1274 | * object was saved. 1275 | */ 1276 | public function is_dirty($key) { 1277 | return isset($this->_dirty_fields[$key]); 1278 | } 1279 | 1280 | /** 1281 | * Save any fields which have been modified on this object 1282 | * to the database. 1283 | */ 1284 | public function save() { 1285 | $query = array(); 1286 | 1287 | // remove any expression fields as they are already baked into the query 1288 | $values = array_values(array_diff_key($this->_dirty_fields, $this->_expr_fields)); 1289 | 1290 | if (!$this->_is_new) { // UPDATE 1291 | // If there are no dirty values, do nothing 1292 | if (count($values) == 0) { 1293 | return true; 1294 | } 1295 | $query = $this->_build_update(); 1296 | $values[] = $this->id(); 1297 | } else { // INSERT 1298 | $query = $this->_build_insert(); 1299 | } 1300 | 1301 | self::_log_query($query, $values); 1302 | $statement = self::$_db->prepare($query); 1303 | $success = $statement->execute($values); 1304 | 1305 | // If we've just inserted a new record, set the ID of this object 1306 | if ($this->_is_new) { 1307 | $this->_is_new = false; 1308 | if (is_null($this->id())) { 1309 | $this->_data[$this->_get_id_column_name()] = self::$_db->lastInsertId(); 1310 | } 1311 | } 1312 | 1313 | $this->_dirty_fields = array(); 1314 | return $success; 1315 | } 1316 | 1317 | /** 1318 | * Build an UPDATE query 1319 | */ 1320 | protected function _build_update() { 1321 | $query = array(); 1322 | $query[] = "UPDATE {$this->_quote_identifier($this->_table_name)} SET"; 1323 | 1324 | $field_list = array(); 1325 | foreach ($this->_dirty_fields as $key => $value) { 1326 | if(!array_key_exists($key, $this->_expr_fields)) { 1327 | $value = '?'; 1328 | } 1329 | $field_list[] = "{$this->_quote_identifier($key)} = $value"; 1330 | } 1331 | $query[] = join(", ", $field_list); 1332 | $query[] = "WHERE"; 1333 | $query[] = $this->_quote_identifier($this->_get_id_column_name()); 1334 | $query[] = "= ?"; 1335 | return join(" ", $query); 1336 | } 1337 | 1338 | /** 1339 | * Build an INSERT query 1340 | */ 1341 | protected function _build_insert() { 1342 | $query[] = "INSERT INTO"; 1343 | $query[] = $this->_quote_identifier($this->_table_name); 1344 | $field_list = array_map(array($this, '_quote_identifier'), array_keys($this->_dirty_fields)); 1345 | $query[] = "(" . join(", ", $field_list) . ")"; 1346 | $query[] = "VALUES"; 1347 | 1348 | $placeholders = $this->_create_placeholders($this->_dirty_fields); 1349 | $query[] = "({$placeholders})"; 1350 | return join(" ", $query); 1351 | } 1352 | 1353 | /** 1354 | * Delete this record from the database 1355 | */ 1356 | public function delete() { 1357 | $query = join(" ", array( 1358 | "DELETE FROM", 1359 | $this->_quote_identifier($this->_table_name), 1360 | "WHERE", 1361 | $this->_quote_identifier($this->_get_id_column_name()), 1362 | "= ?", 1363 | )); 1364 | $params = array($this->id()); 1365 | self::_log_query($query, $params); 1366 | $statement = self::$_db->prepare($query); 1367 | return $statement->execute($params); 1368 | } 1369 | 1370 | /** 1371 | * Delete many records from the database 1372 | */ 1373 | public function delete_many() { 1374 | // Build and return the full DELETE statement by concatenating 1375 | // the results of calling each separate builder method. 1376 | $query = $this->_join_if_not_empty(" ", array( 1377 | "DELETE FROM", 1378 | $this->_quote_identifier($this->_table_name), 1379 | $this->_build_where(), 1380 | )); 1381 | self::_log_query($query, $this->_values); 1382 | $statement = self::$_db->prepare($query); 1383 | return $statement->execute($this->_values); 1384 | } 1385 | 1386 | // --------------------- // 1387 | // --- MAGIC METHODS --- // 1388 | // --------------------- // 1389 | public function __get($key) { 1390 | return $this->get($key); 1391 | } 1392 | 1393 | public function __set($key, $value) { 1394 | $this->set($key, $value); 1395 | } 1396 | 1397 | public function __unset($key) { 1398 | unset($this->_data[$key]); 1399 | unset($this->_dirty_fields[$key]); 1400 | } 1401 | 1402 | 1403 | public function __isset($key) { 1404 | return isset($this->_data[$key]); 1405 | } 1406 | } 1407 | 1408 | /** 1409 | * A class to handle str_replace operations that involve quoted strings 1410 | * @example IdiormString::str_replace_outside_quotes('?', '%s', 'columnA = "Hello?" AND columnB = ?'); 1411 | * @example IdiormString::value('columnA = "Hello?" AND columnB = ?')->replace_outside_quotes('?', '%s'); 1412 | * @author Jeff Roberson