Delayed Select v0.1

Started: 2008-01-25
Updated: 2008-02-29
Language: PHP5
OS: Web
License: MIT

I needed another layer of abstraction so I could delay the construction of a query string, yet still pass around a partial query. This project takes care of that. It's so simple that the API probably won't change much, but I'm making no promises.

Example Usage

$q = query('select * from users')->where('name like "Al%"')->limit(10);
$r = mysql_query((string)$q);

What's the Use?

I'm working on an Object Relational Mapping project in PHP. ORM lets you treat database rows as objects. Imagine there's a User object that is associated with multiple Order objects. Now also imagine I only want to pull the User's Orders for this year:

$user = new user(1); // pull user record with id of 1
$orders = $user->orders()->where('dateCreated like "2008%"');
foreach($orders as $order) {
// do stuff
}

In the above code, the orders() method would return a subclass of this Query Container class. The QC instance would already be filled with the appropriate query to pull all the Orders for that User. The call to where() would add another stipulation to only pull the orders that match the date and then return the same QC instance. Only when the QC instance is referenced in an iterator context (or otherwise treated as an array) would the query be run and an array of Order objects returned. This is the need for delaying construction and execution of a query.

(This is a bit of a simplification but the rest of the details just aren't important)

Taken further, imagine doing things like this:

$user->orders()->orderedProducts()->products()

The above would allow you to loop over all products ever ordered by a user.

Downloads

None yet. Still packaging things up.

However, you can hit up the Mercurial Repository. Check index.php for usage examples.

API

It's really the normal parts you'd expect to be present in a query, but settable via function calls.

Regular Functions

select(): Returns an instance of the select class.

"select" Class Methods

select(string): Sets the select portion of the query (italicized)
select users.* from users ...
from(string): Adds another from clause. For when you need to push multiple, like
select users.* from users,orders ...
where(string): Adds another where clause. They'll all be separated by " and "
orWhere(string): Add another where clause - the string preceded by " or "
group(string): Adds another group by expression
order(string): Adds another order by expression
limit([offset,] count): Will create a limit clause with specified offset and count
parameters([value]): Push another parameter to be used to replace placeholders found within the query. This is helpful if the final query will be passed through PDO, in which case they should have appropriate keys for the placeholders contained in your query.
parameter($key, $value): Adds new named placeholding parameter with specified key and value.
__toString(): When called explicitly (or behind the scenes as the result of a type conversion) it'll use all the previous parameters to construct and return a final query string. The query will contain previously specified placeholders; they won't be replaced with parameter values. That should be done at a later stage either by PDO or dbFacile.
parameters: This member variable can be called to get the array containing all parameters that should be used to replace the placeholders found within the query string.