added readme

README.md

@@ -0,0 +1,255 @@
+# LiteMySQL
+
+A very light-weight and simple ORM-like MySQL library for PHP. Kind of like ActiveRecord's little brother.
+
+
+## Quick-start
+
+    # initialize and connect to database
+    $sql = new litemysql('host', 'username', 'password', 'database', 'table', 'encoding');
+
+    # fetch all rows
+    $rows = $sql->find_all();
+    
+    # insert a single row
+    $sql->insert(array('title' => 'hello', 'body' => 'Dude, sweet!', 'author' => 'John Doe'));
+    
+    # fetch last inserted row
+    $sql->find($sql->last_insert_id);
+
+
+### Config File
+
+You can place all your MySQL settings in a file like `config.php` bellow:
+
+    <?php
+    $database_settings = array(
+    	'host' => 'localhost',
+    	'username' => 'user',
+    	'password' => 'pass',
+    	'database' => 'database',
+    	'table' => 'table',
+    	'encoding' => 'utf8',
+    	'primary_key' => 'user_id',
+    	'persistent' => false,
+    );
+    ?>
+
+Then use the config file:
+
+    $sql = new litemysql('config.php');
+
+And you can also override any option specified in the config file:
+
+    $sql = new litemysql('config.php', null, null, 'my_database', 'my_table');
+
+
+## Input Arguments
+
+
+### Conditions
+
+Conditions can be specified in three ways:
+
+* As an **integer**, which is used as the primary_key value to find a single row.
+* As an **array**, which uses the array keys as columns and array values as column values.
+    * If one of the values in the array, is an array itself, the value is specified using `IN` in the SQL query.
+* As a **string**, which is used as a custom raw SQL where statement. Use with care as it's not filtered for possible SQL injections.
+
+#### Examples:
+
+    $result = $sql->find( 3 );
+    $result = $sql->find( array('id' => 3) );
+    $result = $sql->find( '`id` = 3' );
+    $result = $sql->find_all( array('id' => array(1,3,5)) );
+
+
+### Options
+
+Using the `$options` argument, you can specify `LIMIT`, `OFFSET`, `ORDER BY`, and `GROUP BY` options for the query. They key names used in the array are `limit`, `offset`, `order`, and `group`.
+
+#### Example:
+
+    $result = $sql->find_all(null, array('order' => 'title'));
+
+
+## Methods
+
+
+### `find( $conditions, $options = array() )`
+
+Retrieves a single record matching `$conditions`, or `false` if no record is found.
+
+
+### `find_all( $conditions, $options = array() )`
+
+Works just like `find()`, but retrieves all matching rows. Can be limited with the `limit` option. Returns an empty array if no records matched the specified conditions.
+
+
+### `insert( $input )`
+
+Takes an array as input. To insert a single record, the array should have keys matching the columns. To insert multiple records, `$input` must be an array with arrays containing column keys.
+
+#### Examples:
+
+Insert a single record:
+
+    $sql->insert(
+       array(
+          'title' => 'hello world',
+          'body' => 'my first blog post :D',
+          'author' => 'John Doe'
+       )
+    );
+
+Insert multiple records:
+
+    $sql->insert(
+    	array(
+    		array(
+    			'title' => 'hello world',
+    			'body' => 'my first blog post :D',
+    			'author' => 'John Doe',
+    		),
+    		array(
+    			'title' => 'omg omg!',
+    			'body' => 'i r uber cool!',
+    			'author' => 'Rupert McIdiot',
+    		),
+    	)
+    );
+
+
+### `update( $condtions, $input = array(), $options = array() )`
+
+Updates a single record matching `$conditions`, with the same input format as `insert()` takes for a single record insert.
+
+#### Example:
+
+    $sql->update(4, array('author' => 'James Dole'));
+
+
+### `update_all( $condtions, $input = array(), $options = array() )`
+
+Works just like `update()`, but it updates all records matching `$conditions`.
+
+#### Example:
+
+Change author "John Doe" to "John Smith".
+
+    $sql->update_all(array('author' => 'John Doe'), array('author' => 'John Smith'));
+
+
+### `delete( $conditions, $options = array() )`
+
+Deletes a single record matching `$conditions`.
+
+#### Example:
+
+    $sql->delete(4);
+
+
+### `delete_all( $conditions, $options = array() )`
+
+Deletes all records matching `$conditions`.
+
+#### Example:
+
+    $sql->delete_all(array('author' => 'John Smith'));
+
+
+### `count( $conditions, $options = array() )`
+
+Counts how many records match `$conditions`.
+
+#### Example:
+
+    $result = $sql->count(array('author' => 'John Smith'));
+
+
+### `random( $limit = null, $conditions = null )`
+
+Fetches X number of records from table sorted by random matching `$conditions`. Use `$limit` to specify how many records to retrieve. Be warned that this method uses `ORDER BY RAND()` which can be very slow on large tables.
+
+
+### `increment( $conditions, $column, $count = 1, $options = array() )`
+
+Increment a integer column by `$count` on a single record matching `$conditions`. `$count` defaults to `1` if not specified.
+
+To decrement instead of increment, simply specify a negative `$count` value.
+
+#### Example:
+
+    $sql->increment(array('slug' => 'hello-world'), 'views');
+
+
+### `query( $query )`
+
+Perform a SQL query.
+
+
+### `optimize()`
+
+Performs an `OPTIMIZE` query on the current table.
+
+
+### `truncate( $are_you_sure = false )`
+
+Truncates the table if `$are_you_sure` is true. **WARNING**: This removes ALL records from the current table.
+
+## LiteMySQL Object Properties
+
+### Primary Key
+
+Change the default column name used by the condition builder.
+
+    $sql->primary_key = 'user_id';
+    $result = $sql->find(3);
+
+This creates a `user_id = 3` WHERE clause in the query instead of the default `id = 3`.
+
+
+### Last Insert ID
+
+Contains the primary_key value of the last inserted record.
+
+    $sql->last_insert_id;
+
+
+### Query Log
+
+If `$sql->enable_logging` is set to true, all queries are logged to `$sql->query_log`.
+
+
+## To-do
+
+* Create some kind of basic tests for all the features.
+* Restructure and rewrite this ReadMe so it doesn't suck.
+* Come up with more to-do's for this list.
+
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2010 Jim Myhrberg.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+