From f67d623d529c75dae7b18c29e87841c46b7e8764 Mon Sep 17 00:00:00 2001 From: FrenkyNet Date: Wed, 13 Apr 2011 08:19:58 +0800 Subject: [PATCH] DB docs part one, the basics --- assets/js/nav.js | 11 +- classes/database/db.html | 1132 ++++++++++++++++++++++++++++ classes/database/introduction.html | 83 ++ classes/database/usage.html | 250 ++++++ 4 files changed, 1474 insertions(+), 2 deletions(-) create mode 100644 classes/database/db.html create mode 100644 classes/database/introduction.html create mode 100644 classes/database/usage.html diff --git a/assets/js/nav.js b/assets/js/nav.js index 5190f4e64..c89913ada 100644 --- a/assets/js/nav.js +++ b/assets/js/nav.js @@ -50,8 +50,15 @@ var nav = { "Cookie": "classes/cookie.html", "Crypt": "classes/crypt.html", // "Database": "todo.html", - "Date": "classes/date.html", - "DB": "classes/db.html", + "Date": "classes/date.html", + "Database": { + "Introduction": "classes/database/introduction.html", + //"Configuration": "classes/database/configuration.html", + "Usage": "classes/database/usage.html", + "DB class": "classes/database/db.html" + //"DBUtil class": "todo.html", + }, + //"DB": "classes/db.html", // "DButil": "todo.html", "Debug": "classes/debug.html", // "Email": "todo.html", diff --git a/classes/database/db.html b/classes/database/db.html new file mode 100644 index 000000000..88a27fe31 --- /dev/null +++ b/classes/database/db.html @@ -0,0 +1,1132 @@ + + + + + DB Class - Configuration - Fuel Documentation + + + + + + + + +
+

Fuel Documentation

+
+ + + +
+

DB Class

+ +

The DB class allows you to build and execute database queries and fetch the result.

+ +
+

DB::query

+

The query method returns an new Database_Query object.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$queryrequiredSQL query
+
ReturnsReturns a Database_Query_Builder_Select object.
Example + 
// Will prepare: SELECT * FROM `users`
+$query = DB::query('SELECT * FROM `users`');
+
+
+
+ +
+

DB::select

+

The select method returns an new Database_Query_Builder_Select object.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$columnsnullColumns to select.
+
ReturnsReturns a Database_Query_Builder_Select object.
Example + 
// Will prepare: SELECT *
+$query = DB::select();
+
+// Will prepare: SELECT `id`, `name`
+$query = DB::select('id', 'name');
+
+
+
+ +
+

DB::select_array

+

The select_array method returns an new Database_Query_Builder_Select object.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$columnsarray();Array of columns to select.
+
ReturnsReturns a Database_Query_Builder_Select object.
Example + 
// Will prepare: SELECT *
+$query = DB::select_array();
+
+// Will prepare: SELECT `id`, `name`
+$query = DB::select_array(array('id', 'name'));
+
+
+
+ +
+

DB::insert

+

The insert method returns an new Database_Query_Builder_Insert object.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$tablenullArray of columns to select.
$columnsarray();Array of columns to select.
+
ReturnsReturns a Database_Query_Builder_Insert object.
Example + 
// Will prepare: INSERT INTO `table_name`
+$query = DB::insert('table_name');
+
+// Will prepare: INSERT INTO `table_name` (`id`, `name`)
+$query = DB::insert('table_name', array('id', 'name'));
+
+
+
+ +
+

DB::update

+

The update method returns an new Database_Query_Builder_Update object.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$tablenullTable to update.
+
ReturnsReturns a Database_Query_Builder_Update object.
Example + 
// Will prepare: UPDATE `table_name`
+$query = DB::update('table_name');
+
+
+
+ +
+

DB::delete

+

The insert method returns an new Database_Query_Builder_Delete object.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$tablenullThe table to delete from.
+
ReturnsReturns a Database_Query_Builder_Delete object.
Example + 
// Will prepare: DELETE FROM `table_name`
+$query = DB::delete('table_name');
+
+
+
+ +
+

DB::expr

+

The expr method returns an new Database_Expression object.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$expressionnullThe expression.
+
ReturnsReturns a Database_Expression object.
Example + 
// returns new Database_Expression('COUNT(table_name.table_column)');
+$query = DB::expr('COUNT(table_name.table_column)');
+
+
+
+ +
+

DB::quote

+

The quote method returns a quoted string for an SQL query.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$stringrequiredThe string to quote
$dbnullThe database connection.
+
ReturnsReturns a Database_Expression object.
Example + 
// returns 'something\'s quoted'.
+$query = DB::quote("'something's quoted'");
+
+// returns 'something\'s quoted' through a defined database connection.
+$query = DB::quote("'something's quoted'", $db_connection);
+
+
+
+ +
+

DB::quote_identifier

+

The quote_identifier method returns a quoted string for an SQL query.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$stringrequiredThe string, or array of strings, to quote.
$dbnullThe database connection.
+
ReturnsReturns a quoted string for an SQL query.
Example + 
// `users`.`name`
+print_r(DB::quote_identifier('users.name'));
+
+// array(
+//    [0] => `users`.`name`
+// )
+print_r(DB::quote_identifier(array('users.name')));
+
+
+
+ +
+

DB::quote_table

+

The quote_table method returns a quoted string for an SQL query.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$stringrequiredThe string, or array of strings, to quote.
$dbnullThe database connection.
+
ReturnsReturns a quoted string for an SQL query.
Example + 
// `users`
+print_r(DB::quote_table('users'));
+
+// array(
+//    [0] => `users`
+// )
+print_r(DB::quote_identifier(array('users')));
+
+
+
+ +
+

DB::table_prefix

+

The table_prefix method returns the table name with the configured prefix. + If not, then just the prefix is returned.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$stringrequiredThe table name to prefix.
$dbnullThe database connection.
+
ReturnsReturns the prefixed table name or the table name.
Example + 
// prefixed_table_name
+print_r(DB::table_prefix('table_name'));
+
+
+
+ +
+

DB::escape

+

The escape method returns a escaped string for an SQL query.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$stringrequiredThe string to escape.
$dbnullThe database connection.
+
ReturnsReturns an escaped string for an SQL query.
Example + 
// 'or *\' \"'
+print_r(DB::escape('or *\' "'));
+
+
+
+ +
+

DB::list_columns

+

The list_columns method return a lists all of the columns in a table. + Optionally, a LIKE string can be used to search for specific fields.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$tablenullThe table to look in.
$likenullThe column to search for.
$dbnullThe database connection.
+
ReturnsReturns an array with field data.
Example + 
/*
+Array
+(
+	[id] => Array
+	(
+		[type] => int
+		[min] => -2147483648
+		[max] => 2147483647
+		[column_name] => id
+		[column_default] => 
+		[data_type] => int
+		[is_nullable] => 
+		[ordinal_position] => 1
+		[display] => 255
+		[comment] => 
+		[extra] => auto_increment
+		[key] => PRI
+		[privileges] => select,insert,update,references
+	)
+	
+	[name] => Array
+	(
+		[type] => string
+		[column_name] => name
+		[column_default] => 
+		[data_type] => varchar
+		[is_nullable] => 
+		[ordinal_position] => 3
+		[character_maximum_length] => 255
+		[collation_name] => utf8_unicode_ci
+		[comment] => 
+		[extra] => 
+		[key] => 
+		[privileges] => select,insert,update,references
+	)
+)
+*/
+print_r(DB::list_columns('users'));
+
+/*
+Array
+(
+	[name] => Array
+	(
+		[type] => string
+		[column_name] => name
+		[column_default] => 
+		[data_type] => varchar
+		[is_nullable] => 
+		[ordinal_position] => 3
+		[character_maximum_length] => 255
+		[collation_name] => utf8_unicode_ci
+		[comment] => 
+		[extra] => 
+		[key] => 
+		[privileges] => select,insert,update,references
+	)
+)
+*/
+print_r(DB::list_columns('users','%name%'));
+
+
+
+ +
+

DB::list_tables

+

The list_tables method return a lists all of the tables in a database. + Optionally, a LIKE string can be used to search for specific tables.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$likenullThe table to search for.
$dbnullThe database connection.
+
ReturnsReturns an array with table names.
Example + 
/*
+Array
+(
+    [0] => areas
+    [1] => fuel_sessions
+    [2] => config
+    [3] => files
+)
+*/
+DB::list_tables();
+
+/*
+Array
+(
+    [0] => fuel_sessions
+
+)
+*/
+DB::list_tables('%sessions%');
+
+
+
+ +
+

DB::datatype

+

The datatype method returns a normalized array describing the SQL data type.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$typerequiredThe SQL data type.
$dbnullThe database connection.
+
ReturnsReturns a normalized array describing the SQL data type.
Example + 
/*
+Array
+(
+    [type] => string
+    [exact] => 1
+)
+*/
+DB::datatype('char');
+
+
+
+ +
+

DB::count_records

+

The count_records method returns the number of records in a table.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$tablerequiredThe table to count records from.
$dbnullThe database connection.
+
ReturnsReturns the number of records in a table.
Example + 
// (int) 14
+DB::count_records('users');
+
+
+
+ +
+

DB::count_last_query

+

The count_last_query method returns the number of records in the last query, without LIMIT or OFFSET applied.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$dbnullThe database connection.
+
ReturnsReturns the number of records in the last query, without LIMIT or OFFSET applied.
Example + 
// SELECT * FROM `users` WHERE `active` = "yes" LIMIT 10;
+$limited_result = DB::select()->from('users')->where('active', '=', 'yes')->limit(10)->execute();
+
+// SELECT count(*) as count FROM `users` WHERE `active` = "yes";
+DB::count_records('users');
+
+
+
+ +
+

DB::set_charset

+

The set_charset method sets the connection character set. This is called automatically by [static::connect].

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$charsetrequiredThe character set name.
$dbnullThe database connection.
+
Returnsvoid
Example + 
DB::set_charset('utf8');
+
+
+
+ +
+

DB::transactional

+

The transactional method sets the Database instance to use transactions.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + + + + + + +
ParamDefaultDescription
$use_transtrueUse tranactions TRUE/FALSE.
$dbnullThe database connection.
+
Returnsvoid
Example + 
DB::transactional(FALSE);
+
+
+
+ +
+

DB::start_transaction

+

The start_transaction method begins a transaction on an instance.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$dbnullThe database connection.
+
Returnsvoid
Example + 
DB::start_transaction();
+
+
+
+ +
+

DB::commit_transaction

+

The commit_transaction method commits all pending transactional queries.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$dbnullThe database connection.
+
Returnsvoid
Example + 
DB::commit_transaction();
+
+
+
+ +
+

DB::rollback_transaction

+

The rollback_transaction method rolls back all pending transactional queries.

+ + + + + + + + + + + + + + + + + + + +
StaticYes
Parameters + + + + + + + + + + + +
ParamDefaultDescription
$dbnullThe database connection.
+
Returnsvoid
Example + 
DB::rollback_transaction();
+
+
+
+ + + + + \ No newline at end of file diff --git a/classes/database/introduction.html b/classes/database/introduction.html new file mode 100644 index 000000000..df1678d0e --- /dev/null +++ b/classes/database/introduction.html @@ -0,0 +1,83 @@ + + + + + Database - Introduction - Fuel Documentation + + + + + + + + +
+

Fuel Documentation

+
+ + + +
+

Database Introduction

+
+

Introduction

+ +

+ Fuel offers a driver based database abstration layer. At the time of writing supported + drivers are MySQL, MySQLi and PDO. Aside from regular database interaction, fuel also + comes with a DBUtil class to perform database operations such as creating databases, + adding fields and much more. +

+ +

+ Please note that not all features are supported bij every driver. +

+
+ +
+

Configuration

+ +

+ In order to begin working with databases, you must change the database settings. The + database config file is located at APPPATH/config/db.php. +

+

+ Database configurations are formated like so: +

+ 
'dev' => array(
+	'type'           => 'mysqli',
+	'connection'     => array(
+		'hostname'       => 'localhost',
+		'port'           => '3306',
+		'database'       => 'fuel_db',
+		'username'       => 'your_username',
+		'password'       => 'y0uR_p@ssW0rd',
+		'persistent'     => false,
+	),
+	'table_prefix'   => '',
+	'charset'        => 'utf8',
+	'caching'        => false,
+	'profiling'      => false,
+),
+

+ Once you have your configuration in place, it's time to use it. +

+
+ +
+ + + + + \ No newline at end of file diff --git a/classes/database/usage.html b/classes/database/usage.html new file mode 100644 index 000000000..d26ea6d61 --- /dev/null +++ b/classes/database/usage.html @@ -0,0 +1,250 @@ + + + + + Database - Usage - Fuel Documentation + + + + + + + + +
+

Fuel Documentation

+
+ + + +
+

Database Usage

+

+ Normal database interactions are to go through the DB class. + The following examples will give you a feel for how to go about using the databse in fuel. +

+

Database usage is devided into a couple of segments:

+ + + + +
+

Running queries

+

First we prepare a query using DB::query.

+ 
// returns a new Database_Query
+$query = DB::query('SELECT * FROM `users`');
+
+

Now we can execute that query:

+ 
$query = DB::query('SELECT * FROM `users`');
+
+// return a new Database_MySQLi_Result
+$query->execute();
+
+// Or execute is on a different database group
+$query->execute('another_group');
+// or
+$query->execute(Database_Connection::instance('another_group'));
+
+// And we can chain then like this:
+$result = DB::query('SELECT * FROM `users`')->execute();
+
+
+ +
+

Selection data

+

+ First let's select data using DB::query. + As we are going to fetch a result from this query, we need to let the it know + what kind of query we are going to run. +

+ 

+$result = DB::query('SELECT * FROM `users`', DB::SELECT)->execute();
+
+

+ We can also select data using DB::select or + DB::select_array. +

+ 
// Will execute SELECT `id`, `name` FROM `users`
+$result = DB::select('id','name')->from('users')->execute();
+
+ +

If you want to alias columns, use arrays instead of strings

+ + 
// Will execute SELECT `name` as `the_name` FROM `users`;
+$result = DB::select(array('name','the_name'))->from('users')->execute();
+
+ +

Results

+

+ Executing a select query will generate a result object containing the requested database records. + By default the result is fetched as objects. Here is an exaple how to influence this behaviour. +

+ 
// Will fetch the result as an associative array.
+$result = DB::select('id','name')->from('users')->as_assoc()->execute();
+
+// Will fetch the result as an object.
+$result = DB::select('id','name')->from('users')->as_object()->execute();
+
+// Will fetch the result as an Model_Users object.
+$result = DB::select('id','name')->from('users')->as_object('Model_Users')->execute();
+
+

Want to know how many records you have fetched? It's dead simple!

+

+$result = DB::select('*')->from('users')->execute();
+// Just count the results, it returns an int.
+$num_rows = count($result);
+
+

To access these results you eighter loop through the result object directly, or get the result array.

+ 
$result = DB::select()->from('users')->execute();
+foreach($result as $item)
+{
+	// do something with $item
+}
+
+$result_array = $result->as_array();
+foreach($result_array as $item)
+{
+	// do something with $item
+}
+
+

Optionaly we specify the array key and value to be returned from as_array

+ 
$result = DB::select()->from('users')->execute();
+$on_key = $result->as_array('id');
+foreach($on_key as $id => $item)
+{
+	// $id will contain the records id
+	// do something with $item or it's $id
+}
+
+$key_value = $result->as_array('id', 'email');
+foreach($on_key as $id => $email)
+{
+	// now $email will be the email field.
+	// so you can do something with $id or $email
+}
+
+ +
+ +
+ +

Filtering

+

+ In order to set the conditions on our queries we can set WHERE conditions. + These examples also apply to updating and deleting. +

+ 
// Will execute SELECT * FROM `users` WHERE `id` = 1
+$result = DB::select()->from('users')->where('id', '=', 1)->execute();
+
+// Will execute SELECT * FROM `users` WHERE `id` IN (1, 2, 3)
+$id_array = array(1,2,3);
+$result = DB::select()->from('users')->where('id', 'IN', $id_array)->execute();
+
+// Will execute SELECT * FROM `users` WHERE `id` != 1
+$result = DB::select()->from('users')->where('id', '!=', 1)->execute();
+
+// Will execute SELECT * FROM `users` WHERE `name` LIKE "john%"
+$who = "john%";
+$result = DB::select()->from('users')->where('id', 'like', $who)->execute();
+
+

Grouped where statements are also supported

+ + 
// SELECT * FROM `users` WHERE (`name` = 'John' AND `email` = 'john@example.com')
+// OR (`name` = 'mike' OR `name` = 'dirk')
+$result = DB::select()->from('users')->where_open()
+	->where('name', 'John')
+	->and_where('email', 'john@example.com')
+->where_close()
+->or_where_open()
+	->where('name', 'mike')
+	->or_where('name', 'dirk')
+->or_where_close()->execute();
+
+ +
+ +
+ +

Inserting

+

+ For inserting data we use DB::insert. + If succesfully executed an insert query will return an array containing a + list of insert id and rows created. +

+ 
// Will execute INSERT INTO `users`(`name`,`email`,`password`) 
+// VALUES ("John Random", "john@example.com", "s0_s3cr3t")
+list($insert_id, $rows_affected) = DB::insert('users')->set(array(
+	'name' => 'John Random',
+	'email' => 'john@example.com',
+	'password' => 's0_s3cr3t',
+))->execute();
+
+

You can also set the columns and values seperatly

+ + 
// Will execute INSERT INTO `users`(`name`,`email`,`password`)
+// VALUES ("John Random", "john@example.com", "s0_s3cr3t")
+list($insert_id, $rows_affected) = DB::insert('users')->columns(array(
+	'name', 'email', 'password'
+))->values(array(
+	'John Random', 'john@example.com', 's0_s3cr3t'
+))->execute();
+
+ +
+ +
+ +

Deleting

+ +

+ To delete records, use DB::delete. + When executed it will return the number of rows affected. +

+ 
// Empty the whole users table
+$result = DB::delete('users')->execute(); // (int) 20
+
+// Executes DELETE FROM `users` WHERE `email` LIKE "%@example.com"
+$result = DB::delete('users')->where('email', 'like', '%example.com')->execute(); // (int) 7
+
+ +
+ +
+ +

Joins

+

When selecting data, you can also join other tables into the result.

+ + 
// Will execute SELECT * FROM `users` LEFT JOIN `roles` ON `roles`.`id` = `users`.`role_id`
+$result = DB::select()->from('users')->join('roles','LEFT')->on('roles.id', '=', 'users.role_id');
+
+// Will execute SELECT * FROM `users` RIGHT OUTER JOIN `roles` ON `roles`.`id` = `users`.`role_id`
+$result = DB::select()->from('users')->join('roles','right outer')->on('roles.id', '=', 'users.role_id');
+
+ +
+ +
+ + + + +