Using lists, tags and smart searches I’ve managed to not only never lose track of a task. I estimate this has made me about a billion times more efficient, and has reduced stress levels a thousand fold.

Additionally, I use the new and increasingly indispensable ifttt beta to automate a bunch of tasks around the internet; e.g. to grab a copy of Facebook pictures I get tagged in, send me an SMS when the there’s a problem on my girlfriend’s route to work, etc.

Every so often something happens on the internet and, rather than undertaking a specific action, you want to be prompted to undertake some appropriate action. Wouldn’t it be sweet if when these things happened you could have a virtual PA drop a note on your daily todo list?

Twitter to the rescue!

Sadly, Ifttt doesn’t have a Remember the milk channel (yet) but, like many web apps, Remember the milk has a twitter bot. If you add this bot as a friend and associate your RTM account with your twitter account you are able to add things to your task list by sending the bot a direct message.

Ifttt has a twitter task, so all you need to do to add something to your task list when an action is triggered is begin the twitter message with “d rtm”, e.g.

d rtm Write about Latakoo’s latest blog ^today #work

You can use RTM markup in your message to control what list it goes to, set due dates etc.

My standard use case is to prompt me to write a blog post in response to a client updating their blog, or to tell me cover my car’s windscreen when it’s forecast to snow the next day. I’m sure there’s much more you can do with it!

The bad news is that in only works for a handful of printers natively. But never fear, Linux to the rescue!

At this point I’m going to assume that you have a Linux box somewhere on your network acting as a file and print server (pretty regular kit in most geek homes).

Set up your printer

The first step is to set up CUPS on your linux server and then installing the appropriate printer driver for your printer.

I won’t go into detail here as there are numerous guides out there on the wider web, but mostly this is a matter of installing cups and foomatic and then visiting the cups configuration website on the server (localhost:631 usually) and adding your printer.

Make sure that the printer is shared. Print a test page.

One gotcha I found is that my default configuration only allowed connections from the local machine, even though the printer was marked as shared (although frankly I was cheating since most of my computers printed to my server over a Samba relay, but that’s by the by).

Take a look at /etc/cups/cupsd.conf and make sure that has an Allow From from your local network. E.g.


<Location />
Order Deny,Allow
Deny From All
Allow From 127.0.0.1
Allow From 192.168.0.0/24
</Location>

Export the printer

The next step is to install the zeroconf demon, which is called Avahi. This varies from system to system, but on debian this is pretty much a matter of apt-getting avahi-daemon. You may also want avahi-discover so you can browse the exported devices on your network.

Assuming you’ve correctly set up and shared your printers in CUPS the next step is to generate an avahi configuration for it. Thankfully, there’s a handy Python script called airprint-generate, available on github which does much of the donkey work.

Copy the resultant file to /etc/avahi/services and restart the avahi demon.

If your printer is password protected, you will want to add a <txt-record>air=username,password</txt-record> field to the file before doing so. Where username and password is the literal cleartext strings sent.

Profit!!!

Theoretically that should be it. After the configuration, and restarting the various demons involved your printer should be available to the various iOS devices kicking around your network.

Let me know if you have any questions!

This is not a sideline for Amazon – a recent conversation I had with an Amazon guy I met at a Barcamp revealed that in terms of revenue AWS exceeds the store – and it dramatically lowers the cost of entry for web authors. Using AWS it is possible to compete with the big boys without the need to mortgage your house for the data center and it solves many storage and scalability problems, what’s more – its pay as you go.

To be clear then, Amazon is now a hosting company, and its rather curious as to why people (Amazon included) are not making a big deal of this.

Anywho, I’ve recently had the opportunity to work on a few projects which use AWS extensively, and since I did run into a few gotcha’s I’d thought I’d jot some notes down here, more as an aide-mémoire as anything else.

Getting an AWS account

Before you begin, you’re going to need an account. So, head over here and create one.

Creating a server

You are going to want to create a server to run your code on. The service you need here is Amazon Elastic Compute Cloud (EC2), so sign up for EC2 from the AWS Management Console.

You are going to have to select an EC2 Image to start from, and there are a number of them available. An Image (called AMIs) is a snapshot of your server, its disks and any software you want to run. Once configured you can start one or more Instances of it, which are your running servers.

Once you’ve configured your server, you can create your own image which you can share or use to boot other instances. This whole process is made infinitely easier by using an EBS based image. EBS is a virtual disk, these can be added like normal disks to your server – sizes 1GB to 1TB. EBS backed images store data to these disks and so configuration changes are preserved, additionally new server images can be cloned with the click of a button.

You can add extra disks to your server, but they must be in the same availability zone (datacenter) as your EC2 image and currently can’t be shared between EC2 instances.

So:

• Save your sanity and use an EBS backed image – if you’re looking for a Debian or Ubuntu based one, I recommend the ones created buy Alestic. You can search for community managed images from within the management console, be sure to select EBS backed! For reference, the AMI I often use is identified as ami-209e7349.
• Grab an Elastic IP and assign it to your image, point your domain at this.
• Your goal is to build an AMI consisting of a ready to go install of your web project, so install the necessary software.
• Note however, that you want to build your AMI so that you can run multiple instances of it in order to handle scalability. Since EBS disks can’t be shared you may have to change your architecture slightly:
  • Don’t store user data on the server – user icons etc – these can’t be shared across instances. Store these instead on Amazon S3 and reference them directly using URL where possible. Note, temporary files like caches are probably ok.
  • If you use a database, use MySQL, but only install the client libraries on your image – you won’t be using a local server (see below)!

Once you’ve configured your server create an AMI out of it, this can then be booted multiple times.

Using a database

The database service you will most likely want to use is called Amazon Relational Database Service (RDS) which can function as a drop in replacement for MySQL.

Sign up for it using the management tool, create a database (making note of the passwords and user names you assign) and allow access from your running server instance(s) via the security settings.

The database is running on its own machine, so make a note of the host name in the properties – you will need to pass this in your connect string.

Conclusion

AWS is a powerful tool, if you use it right. There is a lot more complexity to cover of course, but this should serve as a start.

I’ll cover the more advanced scalability stuff later when I actually get to use them in anguish (and get the time to write about it!)

ProFTP

I recently had the need to get this working and authenticating off a PHP maintained MySQL backend, and this post is primarily to aid my own memory should I ever have to do it again.

Installing ProFTP

In order to use MySQL as a back end you need to install some packages. If you’re using a Debian based distro like Ubuntu, this is easy:

apt-get install mysql-server proftpd proftpd-mod-mysql

The database schema

Next, you need to install the database schema to store your users and passwords.

CREATE TABLE IF NOT EXISTS users (
userid varchar(30) NOT NULL default '',
passwd varchar(128) NOT NULL default '',
uid int(11) default NULL,
gid int(11) default NULL,
homedir varchar(255) default NULL,
shell varchar(255) default NULL,
UNIQUE KEY uid (uid),
UNIQUE KEY userid (userid)
) TYPE=MyISAM;

CREATE TABLE IF NOT EXISTS groups (
groupname varchar(30) NOT NULL default '',
gid int(11) NOT NULL default '0',
members varchar(255) default NULL
) TYPE=MyISAM;

One important thing to note here – that caused me a fair amount of hair pulling when I tried to use encrypted passwords – is that the password field shown in many howtos on the internet is much too short. This causes the hashed password to be quietly truncated by MySQL when saved.

This results in a somewhat misleading “No such user found” error to appear in the logs when using encrypted passwords.

To end all argument I’ve allowed passwords up to 128 chars, but this field could probably be a good deal shorter.

The user table looks much like /etc/passwd and is largely self explanatory. The uid & gid fields correspond to a system user in most cases, but since we’re using virtual users they can largely be ignored. Homedir points to a location which will serve as the user’s default directory. Shell is largely unused and can be set to /bin/false or similar.

Configuring ProFTP

Next, you need to make some changes to the ProFTP configuration files stored in /etc/proftpd. While doing this it is handy to run proftp in debug mode from the console:

proftpd -nd6

proftpd.conf

1. Make sure the AuthOrder line looks like:
   

   AuthOrder mod_sql.c

2. Ensure that the following line is uncommented:
   

   Include /etc/proftpd/sql.conf

3. For belts and braces I’ve included the following at the end, although I’m not entirely sure it’s strictly required:
   

   <IfModule mod_auth_pam.c>
AuthPAM off
</IfModule>


4. Our users don’t need a valid shell, so:
   

   RequireValidShell off

modules.conf

1. Make sure the following lines are uncommented:
   

   LoadModule mod_sql.c
LoadModule mod_sql_mysql.c

sql.conf

1. Set your SQL backend and ensure that authentication is turned on:
   

   SQLBackend mysql
SQLEngine on
SQLAuthenticate on

2. Tell proftp how passwords are stored. You have a number of options here, but since I was using mysql’s PASSWORD function, I’ll defer to the backend.
   

   SQLAuthTypes backend

3. Tell proftp how to connect to your database by providing the required connection details, ensure that the user has full access to these tables.
   

   SQLConnectInfo database@host user password

4. Define your table structure in the format tablename fields….
   

   SQLUserInfo users userid passwd uid gid homedir shell
SQLGroupInfo groups groupname gid members

Adding users

I manage users from within a PHP web application that I’m developing, but in a nutshell adding FTP users from this point is a simple insert statement looking something like:

mysql_query("REPLACE INTO users
(userid, passwd, uid, gid, homedir, shell)
VALUES
('$userid', PASSWORD('$password'), $uid, $gid, '$homedir', '$shell')");

Have fun!

In a slight departure from what I usually talk about, I thought I’d quickly jot down how I got the wireless controller to work with my Ubuntu XBMC media PC.

The wireless controller provides a slightly more usable remote than my iPhone (which must first be unlocked making quick pauses impossible) or rather flaky wireless keyboard, so hopefully this will be useful to someone.

Getting started

My media PC currently runs Ubuntu Karmic with XBMC. To begin with you will need to install the XBox kernel driver (already installed on Karmic).

Most importantly however, you will need to get yourself a XBox wireless gaming receiver for Windows – which I got included with my second controller. Xbox controllers do not use standard bluetooth, so you can’t just pair in the normal way using your existing hardware.

This howto has some more info…

Configuring XBMC

Assuming you have your module installed and controller paired you will need to tell XBMC about it by configuring a keyfile:

1. I used this keyfile as a starting point. Download and save it as ~/.xbmc/userdata/keymaps/Keymap.xml (note case).
2. Find out what your computer thinks the controller is by looking at the output from: cat /proc/bus/input/devices – you want a "Name" that says something like "Xbox 360 Wireless Receiver"
3. Replace all occurrences of "Microsoft Xbox Controller S" with this value.

At this point if you start XBMC it should respond to the controller. If you are lucky this is all you will have to do, however for me I had to mess around with the key bindings a bit since the example keymap file didn’t match my controller exactly.

If this happens to you there’s not much I can suggest other than to bind one key at a time, restart XBMC and see what button that maps to then repeat until all your keys are mapped. I’m sure there must be an easier way that I’ve overlooked, feel free to comment below!

For what it’s worth, here is my modified (but somewhat incomplete) key file which has largely sensible bindings. Hack away to get it working how you like.

» Modified Keymap

Image “XBMC” by Miskan

In this article I will document the process, but first I should point out:

• This is highly experimental and not endorsed in any way.
• It is built against Elgg 1.6.1
• This is not canonical and doesn’t reflect anything to do with the roadmap
• This has not been extensively tested so caveat emptor.

Setting up the cluster

The first step is to set up the cluster on your equipment.

A MySQL cluster consists of a management node and several data nodes connected together by a network. Because I was running rather low on hardware, I cheated here and created each node as a Virtual Box image on my laptop – but the principle is the same.

Each node is an Ubuntu install (although you can use pretty much any OS) with two (virtual) network cards, one connected to the wider network (to install packages) and another on an internal network. If you do this for real you should consider removing the internet facing card once you’ve set everything up since a cluster isn’t secure enough to be run on the wider internet.

In my test configuration I had three nodes with name/internal IP as follows:

• HHCluster1/192.168.2.1 – Management node & web server
• HHCluster2/192.168.2.2 – First data node
• HHCluster3/192.168.2.3 – Second data node

HHCluster1 – The management node

Install mysql, apache etc. This should be a simple matter of apt-getting the relevant packages. Clustering (ndb) support is built into the version of mysql bundled with Ubuntu, but this may not be the case universally so check!

You need to create a file in /etc/mysql/ called ndb_mgmd.cnf, this should contain the following:


[NDBD DEFAULT]
NoOfReplicas=2 # How many nodes you have
DataMemory=80M # How much memory to allocate for data storage (change for larger clusters)
IndexMemory=18M # How much memory to allocate for index storage (change for larger clusters)
[MYSQLD DEFAULT]
[NDB_MGMD DEFAULT]
[TCP DEFAULT]

[NDB_MGMD]
HostName=192.168.2.1 # IP address of this system

# Now we describe each node on the system

# First data node
HostName=192.168.2.2
DataDir=/var/lib/mysql-cluster
BackupDataDir=/var/lib/mysql-cluster/backup
DataMemory=512M
[NDBD]
# Second data node node
HostName=192.168.2.3
DataDir=/var/lib/mysql-cluster
BackupDataDir=/var/lib/mysql-cluster/backup
DataMemory=512M


#one [MYSQLD] per data storage node
[MYSQLD]
[MYSQLD]

Data nodes (HHCluster2 & 3)
You must now configure your data nodes:

1. Create the data directories, as root type:
   

   mkdir -p /var/lib/mysql-cluster/backup
chown -R mysql:mysql /var/lib/mysql-cluster

2. Edit your /etc/mysql/my.cnf and add the following to the [mysqld] section:
   

   ndbcluster
# Replace the following with the IP address of your management server
ndb-connectstring=192.168.2.1

3. Again in /etc/mysql/my.cnf uncomment and edit the [MYSQL_CLUSTER] section so it contains the location of your management server:
   

   [MYSQL_CLUSTER]
ndb-connectstring=192.168.2.1

4. You need to create your database on each node (this is because clustering operates on a table level rather than a database level):
   

   CREATE DATABASE elggcluster;

Starting the cluster

1. Start the management node:
   

   /etc/init.d/mysql-ndb-mgm start

2. Start your data nodes:
   

   /etc/init.d/mysql restart
/etc/init.d/mysql-ndb restart

Verifying the cluster
You should now have the cluster up and running, you can verify this by logging into your management node and typing show in ndb_mgm.

A word on access…

The cluster is now set up and will replicate tables (created with the ndbcluster engine – more on that later), but that is only useful to a point. Right now we don’t have a single endpoint to direct queries to, so this direction needs to be done at the application level.

We could take advantage of Elgg’s built in split read and writes, but this would only allow us to use a maximum of two nodes. A better solution would be to use a load balancer here such as Ultramonkey to direct the query to the appropriate server allowing us to scale much further.

I didn’t really have time to get into this, so I am using the somewhat simpler mysql-proxy.

1. On HHCluster1 install and run mysql-proxy:
   

   apt-get install mysql-proxy
mysql-proxy --proxy-backend-addresses=192.168.2.2:3306 --proxy-backend-addresses=192.168.2.2:3306

2. On your data nodes edit your /etc/mysql/my.cnf file. Find bind-address and change it’s IP to the node’s IP address. Also ensure that you have commented out any occurrence of skip-networking.
3. Again on your client nodes, log in to mysql and grant access to your cluster table to a user on HHCluster1 – for example:
   

   GRANT ALL ON elggcluster.* TO `root`@`HHCluster1.local` IDENTIFIED BY '[some password]'

Installing elgg

Unfortunately as it stands, you need to make some code changes to the vanilla version of Elgg in order for it to work in a clustered environment. These changes are necessary because of the restrictions placed on us by the ndbcluster engine.

Two things in particular cause us problems – ndbcluster doesn’t support FULLTEXT indexes, and it also doesn’t support indexes over TEXT or BLOB fields.

FULLTEXT is for searching and is largely not used in the vanilla install of elgg, so I removed them. Equally, most indexes blobs one can live without, the exception being on the metastrings table.

Metastrings is accessed a lot, so the index is critical. Therefore I added an extra varchar field which we’ll modify the code to include the first 50 characters of the indexed text – this is equivalent to the existing index:

CREATE TABLE `prefix_metastrings` (
`id` int(11) NOT NULL auto_increment,
`string` TEXT NOT NULL,
`string_index` varchar(50) NOT NULL,
PRIMARY KEY (`id`),
KEY `string_index` (`string_index`)
) ENGINE=ndbcluster DEFAULT CHARSET=utf8;

And the modified query:

$row = get_data_row("SELECT * from {$CONFIG->dbprefix}metastrings where string=$cs'$string' and string_index='$string_index' limit 1");

Mysql’s optimiser checks the index first so this doesn’t lose a significant amount of efficiency (at least according to the explain command).

» Modified schema

The next problem is that the system log currently uses INSERT DELAYED to insert the log data. This is also not supported under the clustered engine.

There are a number of approaches we could take including using Elgg’s delayed write functionality or writing a plugin which replaces and logs to a different location.

For the purposes of this test I decided to just comment out the code in system_log().

What won’t work
Currently there are a couple of core things that won’t work under these changes, here is a by no means complete summary:

• The system log (as previously described). This isn’t too much of a show stopper as the river code introduced in Elgg 1.5 no longer uses this.
• The log rotate plugin as this attempts to copy the table into the archive engine type and we can’t guarantee which node it will be executed on in this scenario.
• Any third party plugins which attempt to access the metastrings table directly (of which there should be none as direct table access is a big no no!)

Anyway, here is a patch I made against the released version of 1.6.1 with all the code changes I made. Once you have applied this patch to your Elgg install you should be able to proceed with the normal Elgg install.

Let me know any feedback you may have!

» Elgg Clustering patch for Elgg 1.6.1

Top image “Birds-eye view of the 10,240-processor SGI Altix supercomputer housed at the NASA Advanced Supercomputing facility.”

This gives you the opportunity to develop interoperable web services and provide them to the users of your site, all in a standardised way.

The endpoint

To make an API call you must direct your query at a special URL. This query will be either a GET or a POST query (depending on the command you are executing), the specific endpoint you use depends on the format you want the return value returned in.

The endpoint:

http://yoursite.com/pg/api/[protocol]/[return format]/

Where:

• [protocol] is the protocol being used, in this case and for the moment only “rest” is supported.
• [return format] is the format you want your information returned in, either “php”, “json” or “xml”.

This endpoint should then be passed the method and any parameters as GET variables, so for example:

http://yoursite.com/pg/api/rest/xml/?method=test.test&myparam=foo&anotherparam=bar

Would pass “foo” and “bar” as the given named parameters to the function “test.test” and return the result in XML format.

Notice here also that the API uses the “PG” page handler extension, this means that it would be a relatively simple matter to add a new API protocol or replace the entire API subsystem in a module – should you be so inclined.

Return result

The result of the api call will be an entity encoded in your chosen format.

This entity will have a “status” parameter – zero for success, non-zero denotes an error. Result data will be in the “result” parameter. You may also receive some messages and debug information.

Exporting a function

Any Elgg function – core or module – can be exposed via the API, all you have to do is declare it using expose_function() from within your code, passing the method name, handler and any parameters (note that these parameters must be declared in the same order as they appear in your function).

Listing functions

You can see a list of all registered functions using the built in api command “system.api.list”, this is also a useful test to see if your client is configured correctly.

E.g.

http://yoursite.com/pg/api/rest/xml/?method=system.api.list

Authorising and authenticating

Most commands will require some form of authorisation in order to function. There are two main types of authorisation – protocol level which determines whether a given client is permitted to connect, and user level where a command whereby a user requires a special token in lieu of a username and password.

Protocol level authentication
Protocol level authentication is a way to ensure that commands only come from approved clients for which you have previously given keys. This is in keeping with many web based API systems and permits you to disconnect clients who abuse your system, or track usage for accountancy purposes.

The client must send a HMAC signature together with a set of special HTTP headers when making a call. This ensures that the API call is being made from the stated client and that the data has not been tampered with.

Eagle-eyed readers with long memories will see a lot of similarity with the ElggVoices API I wrote about previously.

The HMAC must be constructed over the following data:

• The Secret Key provided by the target Elgg install (as provided easily by the APIAdmin plugin).
• The current unix time in microseconds as a floating point decimal, produced my microtime(true).
• Your API key identifying you to the Elgg api server (companion to your secret key).
• URLEncoded string representation of any GET variable parameters, eg “method=test.test&foo=bar”
• If you are sending post data, the hash of this data.

Some extra information must be added to the HTTP header in order for this data to be correctly processed:

• X-Elgg-apikey – The API key (not the secret key!)
• X-Elgg-time – Microtime used in the HMAC calculation
• X-Elgg-hmac – The HMAC as hex characters.
• X-Elgg-hmac-algo – The algorithm used in the HMAC calculation – eg, sha1, md5 etc

If you are sending POST data you must also send:

• X-Elgg-posthash – The hash of the POST data.
• X-Elgg-posthash-algo – The algorithm used to produce the POST data hash – eg, md5.
• Content-type – The content type of the data you are sending (if in doubt use application/octet-stream).
• Content-Length – The length in bytes of your POST data.

Much of this will be handled for you if you use the built in Elgg API Client.

User level tokens

User level tokens are used to identify a specific user on the target system, in much the same way as if they were to log in with their user name and password, but without the need to send this for every API call.

Tokens are time limited, and so it will be necessary for your client to periodically refresh the token they use to identify the user.

Tokens are generated by using the API command “auth.gettoken” and passing the username and password as parameters, eg:

http://yoursite.com/pg/api/rest/xml/?method=auth.gettoken&username=foo&password=bar

Anonymous methods
Anonymous methods (such as “system.api.list”) can be executed without any form of authentication, thus accepting connections from any client and regardless of whether they provide a user token. This is useful in certain situations and it goes without saying that you don’t expose sensitive functionality this way.

To do so set $anonymous=true in your call to expose_function().

Image “In UR Reality” by XKCD

For this, Elgg has a cron endpoint.

Cron is a unix tool which executes commands at a specific time of day (other operating systems have similar tools). This keys off a file called a crontab – an example is given file is included and called crontab.example.

The crontab calls simplified yet powerful cron endpoint – http://yoursite/pg/cron/PERIOD, where PERIOD is one of the following:

• reboot – Execute on system reboot
• minute – Execute every minute
• fiveminute – Execute every five minutes
• fifteenmin – Execute every fifteen minutes
• halfhour – Execute every half hour
• hourly – Execute once every hour
• daily – Execute every day
• weekly – Execute weekly
• monthly – Execute once a month
• yearly – Execute every year

When these endpoints are triggered by your crontab a plugin hook is triggered. To make use of this, register a plugin hook as follows:

register_plugin_hook('cron', PERIOD, 'my_cron_handler');

Where PERIOD is one of the key words listed above. Here is some sample code using Cron – in this case it is taken from the system log rotation module I added to SVN today.

<?php
/**
* Elgg log rotator.
*
* @package ElggLogRotate
* @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU Public License version 2
* @author Curverider Ltd
* @copyright Curverider Ltd 2008
* @link http://elgg.com/
*/

/**
* Initialise the plugin.
*
*/
function logrotate_init()
{
$period = get_plugin_setting('period','logrotate');
switch ($period)
{
case 'weekly':
case 'monthly' :
case 'yearly' :
break;
default: $period = 'monthly';
}

// Register cron hook
register_plugin_hook('cron', $period, 'logrotate_cron');
}

/**
* Trigger the log rotation.
*
*/
function logrotate_cron($hook, $entity_type, $returnvalue, $params)
{
$resulttext = elgg_echo("logrotate:logrotated");
if (!archive_log())
$resulttext = elgg_echo("logrotate:lognotrotated");

return $returnvalue . $resulttext;
}

// Initialise plugin
register_elgg_event_handler('init','system','logrotate_init');
?>

Here is a short post explaining how you as a plugin writer could add river reporting to your code!

Events

The key to how the river works is the Elgg 1 events system and the system log.

The system log will listen to events and some events pass an object. If the object implements the Loggable interface it will automatically be included in the system log.

The view

In order for things to appear in the river you need to provide a view. This view should be /river/CLASSNAME/EVENT, where CLASSNAME is the class you’re interested in and EVENT is the event.

For example, if you want to output create events for all ElggObjects then you would need to create a file called create.php in a directory /river/ElggObject/create.php.

This file will be passed a number of variables via $vars.

• $vars['performed_by'] : An ElggUser object of the user that performed the action.
• $vars['log_entry'] : The system log row (which includes the event).
• $vars['object'] : The subject of the event.

You can use this information to put together a very customisable view, don’t forget to internationalise your strings!

This provides two main advantages:

1. The application programmer does not have to write the SQL themselves.
2. It becomes considerably easier to change database back ends later down the line.

In addition, we can add free stuff like access controls etc.

From the documentation:

Query provides a framework to construct complex queries in a safer environment.

The usage of this class depends on the type of query you are executing, but the basic idea is to construct a query out of pluggable classes.

Once constructed SQL can be generated using the toString method, this should happen automatically if you pass the Query object to get_data or similar.

To construct a query, create a new Query() object and begin populating it with the various classes that define the various aspects of the query.

Notes:

• You do not have to specify things in any particular order, provided you specify all required components.
• With database tables you do not have to specify your db prefix, this will be added automatically.
• When constructing your query keep an eye on the error log – any problems will get spit out here. Note also that __toString won’t let you throw Exceptions (!!!) so these are caught and echoed to the log instead.

Here is an example of a select statement:

// Construct the query
$query = new Query();

// Say which table we're interested in
$query->addTable(new TableQueryComponent("entities"));

// What fields are we interested in
$query->addSelectField(new SelectFieldQueryComponent("entities","*"));

// Add access control (Default access control uses default fields on entities table.
// Note that it will error without something specified here!
$query->setAccessControl(new AccessControlQueryComponent());

// Set a limit and offset, may be omitted.
$query->setLimitAndOffset(new LimitOffsetQueryComponent(10,0));

// Specify the order, may be omitted
$query->setOrder(new OrderQueryComponent("entities", "subtype", "desc"));

// Construct a where query
//
// This demonstrates a WhereSet which lets you have sub wheres, a
// WhereStatic which lets you compare a table field against a value and a
// Where which lets you compare a table/field with another table/field.
$query->addWhere(
new WhereSetQueryComponent(
array(
new WhereStaticQueryComponent("entities", "subtype","=", 1),
new WhereQueryComponent("entities","subtype","=", "entities", "subtype")
)
)
);

get_data($query);

Constructing a query out of classes in this way provides a lot of scope for expanding the functionality within a common framework, as well as providing a structured way of constructing complicated database queries.

However, if it looks too complicated, you can use about 99% of Query‘s functionality by using the subclass SimpleQuery, which provides methods for performing much of the standard functionality.