Query/README.md

132 lines
3.9 KiB
Markdown
Raw Normal View History

2012-03-15 09:25:18 -04:00
# Query
A query builder/database abstraction layer, using prepared queries for security.
2012-03-22 15:07:27 -04:00
[![Build Status](https://secure.travis-ci.org/timw4mail/Query.png)](http://travis-ci.org/timw4mail/Query)
[![Code Coverage](https://scrutinizer-ci.com/g/timw4mail/Query/badges/coverage.png?s=a96df5417089f90250aeb59013a3964b1ff9b588)](https://scrutinizer-ci.com/g/timw4mail/Query/)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/timw4mail/Query/badges/quality-score.png?s=ce0f185067d7049cfe3f0aba2ca30ed56fb97b20)](https://scrutinizer-ci.com/g/timw4mail/Query/)
2014-02-25 12:28:21 -05:00
[![Latest Stable Version](https://poser.pugx.org/aviat4ion/query/v/stable.png)](https://packagist.org/packages/aviat4ion/query)
[![Total Downloads](https://poser.pugx.org/aviat4ion/query/downloads.png)](https://packagist.org/packages/aviat4ion/query)
[![Latest Unstable Version](https://poser.pugx.org/aviat4ion/query/v/unstable.png)](https://packagist.org/packages/aviat4ion/query)
[![License](https://poser.pugx.org/aviat4ion/query/license.png)](http://www.dbad-license.org/)
2012-03-22 15:07:27 -04:00
## Requirements
2012-03-15 12:09:43 -04:00
* Pdo extensions for the databases you wish to use (unless it's Firebird, in which case, the interbase extension is required)
2014-02-17 20:15:41 -05:00
* PHP 5.3+
2012-03-15 12:09:43 -04:00
## Databases Supported
2014-02-25 12:04:51 -05:00
2012-07-20 16:40:58 -04:00
* Firebird (via interbase extension)
* Firebird (via PDO) -- expirimental
2012-03-15 12:09:43 -04:00
* MySQL
* PostgreSQL
* SQLite
## Including Query in your application
To include Query in your PHP project, just include the `autoload.php` file. This will automatically load the classes that are supported by the current PHP installation.
2014-02-25 12:04:51 -05:00
## Connecting
Create a connection array or object similar to this:
<?php
2014-02-25 12:04:51 -05:00
$params = array(
'type' => 'mysql',
'host' => 'localhost',
'user' => 'root',
'pass' => '',
'port' => '3306',
'database' => 'test_db',
2014-02-25 12:04:51 -05:00
// Only required
// SQLite or Firebird
'file' => '/path/to/db/file',
2014-02-25 12:04:51 -05:00
2012-11-09 15:01:41 -05:00
// Optional paramaters
'prefix' => 'tbl_', // Database table prefix
'alias' => 'old' // Connection name for the Query function
);
2014-02-25 12:04:51 -05:00
$db = Query($params);
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.
Query()->get('table_name');
2014-02-25 12:04:51 -05:00
2012-11-09 15:01:41 -05:00
or
2014-02-25 12:04:51 -05:00
2012-11-09 15:01:41 -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
// Set the alias in the connection parameters
$params['alias'] = 'old';
// Connect to the legacy database
2014-02-25 12:04:51 -05:00
Query('old')->query($sql);
### Running Queries
2014-03-31 16:01:58 -04:00
Query uses the same interface as CodeIgniter's [Active Record class](http://ellislab.com/codeigniter/user-guide/database/active_record.html). However, it does not implement the `update_batch` or caching methods.
2014-02-25 12:04:51 -05:00
####You can also run queries manually.
2012-04-25 10:43:39 -04:00
To run a prepared statement, call
2014-02-25 12:04:51 -05:00
`$db->prepare_execute($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:
$query = $db->select('id, key as k, val')
->from('table t')
->where('k >', 3)
->or_where('id !=' 5)
->order_by('val', 'DESC')
->limit(3, 1)
->get();
2014-02-25 12:04:51 -05:00
2012-03-19 15:12:50 -04:00
This will generate a query similar to (with this being the output for a Postgres database):
SELECT "id", "key" AS "k", "val"
FROM "table" "t"
WHERE "k" > ?
OR "id" != ?
ORDER BY "val" DESC
LIMIT 3 OFFSET 1
2012-03-19 23:47:07 -04:00
To retreive the results of a query, use the PDO 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:09:43 -04:00
$query = $db->get('table_name');
2014-02-25 12:04:51 -05:00
$results = $query->fetchAll(PDO::FETCH_ASSOC);
2014-02-25 12:04:51 -05:00
### Inserting / Updating
An example of an insert query:
$query = $db->set('foo', 'bar')
->set('foobar', 'baz')
->where('foo !=', 'bar')
->insert('table');
2014-02-25 12:04:51 -05:00
An example of an update query:
$query = $db->set('foo', 'bar')
->set('foobar', 'baz')
->where('foo !=', 'bar')
->update('table');
2014-02-25 12:04:51 -05:00
The `set` method can also take an array as a paramater, instead of setting individual values.