2012-03-15 09:25:18 -04:00
# Query
2016-07-19 20:51:18 -04:00
A query builder/database abstraction layer, using prepared statements for security.
2012-03-15 12:02:26 -04:00
2016-07-19 20:51:18 -04:00
[![Code Coverage ](https://scrutinizer-ci.com/g/aviat4ion/Query/badges/coverage.png?b=develop )](https://scrutinizer-ci.com/g/aviat4ion/Query/?branch=develop)
[![Scrutinizer Code Quality ](https://scrutinizer-ci.com/g/aviat4ion/Query/badges/quality-score.png?b=develop )](https://scrutinizer-ci.com/g/aviat4ion/Query/?branch=develop)
2016-08-05 12:48:32 -04:00
[![Latest Stable Version ](https://poser.pugx.org/aviat/query/v/stable.png )](https://packagist.org/packages/aviat/query)
[![Total Downloads ](https://poser.pugx.org/aviat/query/downloads.png )](https://packagist.org/packages/aviat/query)
[![Latest Unstable Version ](https://poser.pugx.org/aviat/query/v/unstable.png )](https://packagist.org/packages/aviat/query)
2012-03-22 15:07:27 -04:00
2012-03-15 12:02:26 -04:00
## Requirements
2019-12-13 15:11:49 -05:00
* PDO extensions for the databases you wish to use
2020-04-10 20:53:52 -04:00
* PHP 7.4 or later
2019-12-13 15:11:49 -05:00
2012-03-15 12:09:43 -04:00
## Databases Supported
2014-02-25 12:04:51 -05:00
2019-12-13 15:11:49 -05:00
* MySQL 5+ / MariaDB
* PostgreSQL 8.4+
2012-03-15 12:09:43 -04:00
* SQLite
2012-03-19 13:24:36 -04:00
## Including Query in your application
2016-07-19 20:51:18 -04:00
* Install via composer and include `vendor/autoload.php`
2014-02-25 12:04:51 -05:00
2012-03-15 12:02:26 -04:00
## Connecting
Create a connection array or object similar to this:
2016-02-01 20:53:54 -05:00
```php
< ?php
2014-02-25 12:04:51 -05:00
2016-02-01 20:53:54 -05:00
$params = array(
2018-01-26 16:27:34 -05:00
'type' => 'mysql', // mysql, pgsql, sqlite
2016-07-19 20:51:18 -04:00
'host' => 'localhost', // address or socket
2016-02-01 20:53:54 -05:00
'user' => 'root',
'pass' => '',
'port' => '3306',
'database' => 'test_db',
2014-02-25 12:04:51 -05:00
2016-07-19 20:51:18 -04:00
// Only required for
2019-12-13 15:11:49 -05:00
// SQLite
2016-02-01 20:53:54 -05:00
'file' => '/path/to/db/file',
2014-02-25 12:04:51 -05:00
2018-01-26 16:27:34 -05:00
// Optional parameters
2016-02-01 20:53:54 -05:00
'prefix' => 'tbl_', // Database table prefix
'alias' => 'old' // Connection name for the Query function
);
2014-02-25 12:04:51 -05:00
2016-02-01 20:53:54 -05:00
$db = Query($params);
```
2012-03-15 12:02:26 -04:00
2014-02-25 12:04:51 -05:00
The parameters required depend on the database.
### Query function
2012-11-09 15:01:41 -05:00
You can use the `Query()` function as a reference to the last connected database. E.g.
2016-02-01 20:53:54 -05:00
```php
2016-02-01 20:59:21 -05:00
< ?php
2016-02-01 20:53:54 -05:00
Query()->get('table_name');
2014-02-25 12:04:51 -05:00
2016-02-01 20:59:21 -05:00
// or
2016-02-01 20:53:54 -05:00
$result = Query()->query($sql);
```
2014-02-25 12:04:51 -05:00
2012-11-09 15:01:41 -05:00
If the `alias` key is set in the parameters, you can refer to a specific database connection
2016-02-01 20:53:54 -05:00
```php
2016-02-01 20:59:21 -05:00
< ?php
2016-02-01 20:53:54 -05:00
// Set the alias in the connection parameters
$params['alias'] = 'old';
2012-11-09 15:01:41 -05:00
2016-02-01 20:53:54 -05:00
// Connect to the legacy database
Query('old')->query($sql);
```
2012-03-15 12:02:26 -04:00
### Running Queries
2019-12-13 15:11:49 -05:00
Query is based on CodeIgniter's [Query Builder ](http://www.codeigniter.com/user_guide/database/query_builder.html ) class.
However, it has camelCased method names, and does not implement the caching methods.
2018-01-26 09:16:13 -05:00
For specific query builder methods, see the [class documentation ](https://gitdev.timshomepage.net/Query/apiDocumentation/classes/Query_QueryBuilder.html#methods ).
2019-12-13 15:11:49 -05:00
Other database methods not directly involved in building queries, are also available from the query builder object.
The methods available depend on the database, but common methods are documented
2018-01-26 09:16:13 -05:00
[here ](https://gitdev.timshomepage.net/Query/apiDocumentation/classes/Query_Drivers_AbstractDriver.html#methods ).
2012-03-15 12:02:26 -04:00
2016-07-19 20:51:18 -04:00
#### You can also run queries manually.
2012-04-25 10:43:39 -04:00
To run a prepared statement, call
2018-01-22 15:43:56 -05:00
`$db->prepareExecute($sql, $params)` .
2012-04-25 10:43:39 -04:00
To run a plain query, `$db->query($sql)`
### Retrieving Results:
2012-03-19 17:07:54 -04:00
2012-03-19 15:12:50 -04:00
An example of a moderately complex query:
2016-02-01 20:53:54 -05:00
```php
2016-02-01 20:59:21 -05:00
< ?php
2016-02-01 20:53:54 -05:00
$query = $db->select('id, key as k, val')
->from('table t')
->where('k >', 3)
2019-12-13 15:11:49 -05:00
->orWhere('id !=', 5)
2018-01-22 15:43:56 -05:00
->orderBy('val', 'DESC')
2016-02-01 20:53:54 -05:00
->limit(3, 1)
->get();
```
2014-02-25 12:04:51 -05:00
2016-07-19 20:51:18 -04:00
This will generate a query similar to (with this being the output for a PostgreSQL database):
2012-03-19 15:12:50 -04:00
2016-02-01 20:53:54 -05:00
```sql
SELECT "id", "key" AS "k", "val"
FROM "table" "t"
WHERE "k" > ?
OR "id" != ?
ORDER BY "val" DESC
LIMIT 3 OFFSET 1
```
2012-03-19 15:12:50 -04:00
2018-01-26 16:27:34 -05:00
The query execution methods `get` , `getWhere` , `insert` ,
2019-12-13 15:11:49 -05:00
`insertBatch` ,`update`, and `delete` return a native [PDOStatement ](http://php.net/manual/en/class.pdostatement.php ) object.
To retrieve the results of a query, use the PDOStatement method [fetch ](http://php.net/manual/en/pdostatement.fetch.php ) and/or
[fetchAll ](http://php.net/manual/en/pdostatement.fetchall.php ).
2012-03-15 12:02:26 -04:00
2016-02-01 20:59:21 -05:00
```php
< ?php
$query = $db->get('table_name');
2014-02-25 12:04:51 -05:00
2016-02-01 20:59:21 -05:00
$results = $query->fetchAll(PDO::FETCH_ASSOC);
```
2014-02-25 12:04:51 -05:00
2012-10-23 09:40:11 -04:00
### Inserting / Updating
An example of an insert query:
2016-02-01 20:53:54 -05:00
```php
2016-02-01 20:59:21 -05:00
< ?php
2016-02-01 20:53:54 -05:00
$query = $db->set('foo', 'bar')
->set('foobar', 'baz')
->where('foo !=', 'bar')
->insert('table');
```
2014-02-25 12:04:51 -05:00
2012-10-23 09:40:11 -04:00
An example of an update query:
2016-02-01 20:53:54 -05:00
```php
2016-02-01 20:59:21 -05:00
< ?php
2016-02-01 20:53:54 -05:00
$query = $db->set('foo', 'bar')
->set('foobar', 'baz')
->where('foo !=', 'bar')
->update('table');
```
2014-02-25 12:04:51 -05:00
2016-07-19 20:51:18 -04:00
The `set` method can also take an array as a parameter, instead of setting individual values.
2012-10-23 09:40:11 -04:00