Date: Fri, 25 Aug 2006 17:25:49 +0000 Subject: Initial Import --- user_guide/libraries/database/active_record.html | 610 +++++++++++++++++++++++ user_guide/libraries/database/call_function.html | 123 +++++ user_guide/libraries/database/configuration.html | 144 ++++++ user_guide/libraries/database/connecting.html | 172 +++++++ user_guide/libraries/database/examples.html | 183 +++++++ user_guide/libraries/database/fields.html | 144 ++++++ user_guide/libraries/database/index.html | 99 ++++ user_guide/libraries/database/queries.html | 180 +++++++ user_guide/libraries/database/results.html | 235 +++++++++ user_guide/libraries/database/table_data.html | 116 +++++ 10 files changed, 2006 insertions(+) create mode 100644 user_guide/libraries/database/active_record.html create mode 100644 user_guide/libraries/database/call_function.html create mode 100644 user_guide/libraries/database/configuration.html create mode 100644 user_guide/libraries/database/connecting.html create mode 100644 user_guide/libraries/database/examples.html create mode 100644 user_guide/libraries/database/fields.html create mode 100644 user_guide/libraries/database/index.html create mode 100644 user_guide/libraries/database/queries.html create mode 100644 user_guide/libraries/database/results.html create mode 100644 user_guide/libraries/database/table_data.html (limited to 'user_guide/libraries/database') diff --git a/user_guide/libraries/database/active_record.html b/user_guide/libraries/database/active_record.html new file mode 100644 index 000000000..8fc3b8131 --- /dev/null +++ b/user_guide/libraries/database/active_record.html @@ -0,0 +1,610 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + +
+ + + +

+ + +

Active Record Class

+ + +

Code Igniter uses a modified version of the Active Record Database Pattern. +This pattern allows information to be retrieved, inserted, and updated in your database with minimal scripting. +In some cases only one or two lines of code are necessary to perform a database action. +Code Igniter does not require that each database table be its own class file. It instead provides a more simplified interface.

+ +

Beyond simplicity, a major benefit to using the Active Record features is that it allows you to create database independent applications, since the query syntax +is generated by each database adapter. It also allows for safer queries, since the values are escaped automatically by the system.

+ +

Note: If you intend to write your own queries you can disable this class in your database config file, allowing the core database library and adapter to utilize fewer resources.

+ +
+ +

Selecting Data
Inserting Data
Updating Data
Deleting Data
Method Chaining

+ + + + + +

Selecting Data

+ +

The following functions allow you to build SQL SELECT statements.

+ +

Note: If you are using PHP 5 you can use method chaining for more compact syntax. This is described at the end of the page.

+ + +

$this->db->get();

+ +

Runs the selection query and returns the result. Can be used by itself to retrieve all records from a table:

+ +

$query = $this->db->get('mytable');

+

+// Produces: SELECT * FROM mytable

+ +

The second and third parameters enable you do set a limit and offset clause:

+ +

$query = $this->db->get('mytable', 10, 20);

+

+// Produces: SELECT * FROM mytable LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax)

+ + + +

You'll notice that the above function is assigned to a variable named $query, which can be used to show the results:

+ +

$query = $this->db->get('mytable');

+

+foreach ($query->result() as $row)

+{

+    echo $row->title;

+}

+ +

Please visit the result functions page for a full discussion regarding result generation.

+ + +

$this->db->getwhere();

+ +

Identical to the above function except that it permits you to add a "where" clause in the second parameter, +instead of using the db->where() function:

+ +$query = $this->db->getwhere('mytable', array(id => $id), $limit, $offset); + +

Please read the about the where function below for more information.

+ + +

$this->db->select();

+ +

Permits you to write the SELECT portion of your query:

+ +


+$this->db->select('title, content, date');

+

+$query = $this->db->get('mytable');

+

+// Produces: SELECT title, content, date FROM mytable

+ +

Note: If you are selecting all (*) from a table you do not need to use this function. When omitted, Code Igniter assumes you wish to SELECT *

+ + +

$this->db->from();

+ +

Permits you to write the FROM portion of your query:

+ +


+$this->db->select('title, content, date');

+$this->db->from('mytable');

+

+$query = $this->db->get();

+

+// Produces: SELECT title, content, date FROM mytable

+ +

Note: As shown earlier, the FROM portion of your query can be specified in the $this->db->get() function, so use whichever method +you prefer.

+ +

$this->db->join();

+ +

Permits you to write the JOIN portion of your query:

+ +


+$this->db->select('*');

+$this->db->from('blogs');

+$this->db->join('comments', 'comments.id = blogs.id');

+

+$query = $this->db->get();

+

+// Produces: 

+// SELECT * FROM blogs

+// JOIN comments ON comments.id = blogs.id

+

+ +

Multiple function calls can be made if you need several joins in one query.

+ +

If you need something other than a natural JOIN you can specify it via the third parameter of the function. +Options are: left, right, outer, inner, left outer, and right outer.

+ +


+$this->db->join('comments', 'comments.id = blogs.id', 'left');

+

+// Produces: LEFT JOIN comments ON comments.id = blogs.id

+ + + + + +

$this->db->where();

This function enables you to set WHERE clauses using one of four methods:

+ +

Note: All values passed to this function are escaped automatically, producing safer queries.

+ +

Simple key/value method: + + $this->db->where('name', $name); + // Produces: WHERE name = 'Joe' + + +
Notice that the equal sign is added for you.
+ +
If you use multiple function calls they will be chained together with AND between them:
+ + $this->db->where('name', $name); + $this->db->where('title', $title); + $this->db->where('status', $status); + // WHERE = 'Joe' AND title = 'boss' AND status = 'active' + + + +
Custom key/value method: + +
You can include an operator in the first parameter in order to to control the comparison:
+ + $this->db->where('name !=', $name); + $this->db->where('id <', $id); + // Produces: WHERE name != 'Joe' AND id < 45 + + + + +
Associative array method: + + + + $array = array('name' => $name, 'title' => $title, 'status' => $status); + + $this->db->where($array); + // Produces: WHERE name = 'Joe' AND title = 'boss' AND status = 'active' + + +
You can include your own operators using this method as well:
+ + + $array = array('name !=' => $name, 'id <' => $id, 'date >' => $date); + + $this->db->where($array); + +
Custom string: + +
You can write your own clauses manually:
+ + + $where = "name='Joe' AND status='boss' OR status='active'"; + $this->db->where($where); + +

+ + +

$this->db->orwhere();

This function is identical to the one above, except that multiple instances are joined by OR:

+ +


+$this->db->where('name !=', $name);

+$this->db->orwhere('id >', $id);
+

// Produces: WHERE name != 'Joe' OR id > 50
+

+ + + + +

$this->db->like();

This function enables you to generate LIKE clauses, useful for doing searches.

+ +

Note: All values passed to this function are escaped automatically.

+ + +

Simple key/value method: + + $this->db->like('title', $match); + // Produces: WHERE title LIKE '%match%' + + +
If you use multiple function calls they will be chained together with AND between them:
+ + $this->db->like('title', $match); + $this->db->like('body', $match); + // WHERE title LIKE '%match%' AND body LIKE '%match%' + + +
Associative array method: + + + $array = array('title' => $match, 'page1' => $match, 'page2' => $match); + + $this->db->like($array); + // WHERE title LIKE '%match%' AND page1 LIKE '%match%' AND page2 LIKE '%match%' + + +

+ + +

$this->db->orlike();

This function is identical to the one above, except that multiple instances are joined by OR:

+ +


+$this->db->like('title', $match);

+$this->db->orlike('body', $match);
+

// WHERE title LIKE '%match%' OR  body LIKE '%match%'
+

+ + + + +

$this->db->groupby();

+ +

Permits you to write the GROUP BY portion of your query:

+ +

$this->db->groupby("title");
+

// Produces: GROUP BY title
+

+ +

You can also pass an array of multiple values as well:

+ +

$this->db->groupby(array("title", "date");
+

// Produces: GROUP BY title, date
+

+ + +

$this->db->having();

+ +

Permits you to write the HAVING portion of your query:

+ +

$this->db->having('user_id = 45');
+

// Produces: HAVING 'user_id = 45'
+

+ +

You can also pass an array of multiple values as well:

+ + +

$this->db->having(array('title =' => 'My Title', 'id <' => $id));
+

// Produces: HAVING title = 'My Title', 'id < 45'
+

+ + + +

$this->db->orderby();

Lets you set an ORDER BY clause. The first parameter contains the name of the column you would like to order by. +The second parameter lets you set the direction of the result. Options are asc or desc

+ +

$this->db->orderby("title", "desc");
+

// Produces: ORDER BY title DESC
+

+ +

You can also pass your own string in the first parameter:

+ +

$this->db->orderby('title desc, name asc');
+

// Produces: ORDER BY title DESC, name ASC
+

+ + + +

$this->db->limit();

Lets you limit the number of rows you would like returned by the query: + ++$this->db->limit(10); + +// Produces: LIMIT 10 + + +

The second parameter lets you set a result offset.

+ +


+$this->db->limit(10, 20);

+

+// Produces: LIMIT 20, 10 (in MySQL.  Other databases have slightly different syntax)

+ + +

$this->db->count_all();

+ +

Permits you to determine the number of rows in a particular table. Submit the table name in the first parameter. Example:

+ +

echo $this->db->count_all('my_table');

+

+// Produces an integer, like 25

+ + + + + +

Inserting Data

+ +

$this->db->insert();

Generates an insert string based on the data you supply, and runs the query. You can either pass an +array or an object to the function. Here is an example using an array:

+ +


+$data = array(

+               'title' => $title,

+               'name' => $name,

+               'date' => $date

+            );

+

+$this->db->insert('mytable', $data);
+


+// Produces: INSERT INTO mytable (title, name, date) VALUES ('{$title}', '{$name}', '{$date}')

+ +

The first parameter will contain the table name, the second is an associative array of values.

+ +

Here is an example using an object:

+ +


+/*

+    class Myclass {

+        var = $title = 'My Title';

+        var = $content = 'My Content';

+        var = $date = 'My Date';

+    }

+*/

+

+$object = new Myclass;

+

+$this->db->insert('mytable', $object);
+


+// Produces: INSERT INTO mytable (title, name, date) VALUES ('{$title}', '{$name}', '{$date}')

+ +

The first parameter will contain the table name, the second is an associative array of values.

+ +

Note: All values are escaped automatically producing safer queries.

+ + + + +

$this->db->set();

This function enables you to set values for inserts or updates.

+ +

It can be used instead of passing a data array directly to the insert or update functions:

+ +

$this->db->set('name', $name);
+

+$this->db->insert('mytable');
+


+// Produces: INSERT INTO mytable (name) VALUES ('{$name}')

+ +

If you use multiple function called they will be assembled properly based on whether you are doing an insert or an update:

+ +

$this->db->set('name', $name);

+$this->db->set('title', $title);

+$this->db->set('status', $status);

+$this->db->insert('mytable');
+

+ +

You can also pass an associative array to this function:

+ +


+$array = array('name' => $name, 'title' => $title, 'status' => $status);


+
+$this->db->set($array);

+$this->db->insert('mytable');
+

+ +

Or an object:

+ + +


+/*

+    class Myclass {

+        var = $title = 'My Title';

+        var = $content = 'My Content';

+        var = $date = 'My Date';

+    }

+*/

+

+$object = new Myclass;

+

+$this->db->set($object);

+$this->db->insert('mytable');
+

+ + + + +

Updating Data

+ +

$this->db->update();

Generates an update string and runs the query based on the data you supply. You can pass an +array or an object to the function. Here is an example using +an array:

+ +


+$data = array(

+               'title' => $title,

+               'name' => $name,

+               'date' => $date

+            );

+

+$this->db->where('id', $id);

+$this->db->update('mytable', $data);
+


+// Produces:

+// UPDATE mytable 

+// SET title = '{$title}', name = '{$name}', date = '{$date}'

+// WHERE id = $id

+ +

Or you can supply an object:

+ +


+/*

+    class Myclass {

+        var = $title = 'My Title';

+        var = $content = 'My Content';

+        var = $date = 'My Date';

+    }

+*/

+

+$object = new Myclass;

+

+$this->db->where('id', $id);

+$this->db->update('mytable', $object, $where);
+


+// Produces:

+// UPDATE mytable 

+// SET title = '{$title}', name = '{$name}', date = '{$date}'

+// WHERE id = $id

+ + + +

Note: All values are escaped automatically producing safer queries.

+ +

You'll notice the use of the $this->db->where() function, enabling you to set the WHERE clause. +You can optionally pass this information directly into the update function as a string:

+ +$this->db->update('mytable', $data, "id = 4"); + +

Or as an array:

+ +$this->db->update('mytable', $data, array('id' => $id)); + +

You may also use the $this->db->set() function described above when performing updates.

+ + + +

Deleting Data

+ + + +

$this->db->delete();

Generates a delete SQL string and runs the query.

+ +


+$this->db->delete('mytable', array('id', $id));
+


+// Produces:

+// DELETE FROM mytable 

+// WHERE id = $id

+ +

The first parameter is the table name, the second is the where clause. You can also use the where() or orwhere() functions instead of passing +the data to the second parameter of the function: + ++$this->db->where('id', $id); +$this->db->delete('mytable'); + +// Produces: +// DELETE FROM mytable +// WHERE id = $id + +

Note: All values are escaped automatically producing safer queries.

+ + + +

Method Chaining

+ +

Method chaining allows you to simplify your syntax by connecting multiple functions. Consider this example:

+ +


+$this->db->select('title')->from('mytable')->where('id', $id)->limit(10, 20);

+

+$query = $this->db->get();

+ +

Note: Method chaining only works with PHP 5.

+ + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/call_function.html b/user_guide/libraries/database/call_function.html new file mode 100644 index 000000000..9c860a426 --- /dev/null +++ b/user_guide/libraries/database/call_function.html @@ -0,0 +1,123 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + +
+ + + +

+ +

Custom Function Calls

+ +

$this->db->call_function();

+ +

This function enables you to call PHP database functions that are not natively included in Code Igniter, in a platform independent manner. +For example, lets say you want to call the mysql_get_client_info() function, which is not natively supported +by Code Igniter. You could do so like this: +

+ +$this->db->call_function('get_client_info'); + +

You must supply the name of the function, without the mysql_ prefix, in the first parameter. The prefix is added +automatically based on which database driver is currently being used. This permits you to run the same function on different database platforms. +Obviously not all function calls are identical between platforms, so there are limits to how useful this function can be in terms of portability.

+ +

Any parameters needed by the function you are calling will be added to the second parameter.

+ +$this->db->call_function('some_function', $param1, $param2, etc..); + + +

Often, you will either need to supply a database connection ID or a database result ID. The connection ID can be accessed using:

+ +$this->db->conn_id; + +

The result ID can be accessed from within your result object, like this:

+ +

$query = $this->db->query("SOME QUERY");

+

+$query->result_id;

+ + + + + + + + + + + + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/configuration.html b/user_guide/libraries/database/configuration.html new file mode 100644 index 000000000..4b7d2a8a0 --- /dev/null +++ b/user_guide/libraries/database/configuration.html @@ -0,0 +1,144 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + +
+ + + +

+ + +

Database Configuration

+ +

Code Igniter has a config file that lets you store your database connection values (username, password, database name, etc.). +The config file is located at: + +

application/config/database.php

+ +

The config settings are stored in a multi-dimensional array with this prototype:

+ +

$db['default']['hostname'] = "localhost";

+$db['default']['username'] = "root";

+$db['default']['password'] = "";

+$db['default']['database'] = "database_name";

+$db['default']['dbdriver'] = "mysql";

+$db['default']['dbprefix'] = "";

+$db['default']['pconnect'] = TRUE;

+$db['default']['db_debug'] = FALSE;

+$db['default']['active_r'] = TRUE;

+ +

The reason we use a multi-dimensional array rather than a more simple one is to permit you to optionally store +multiple sets of connection values. If, for example, you run multiple environments (development, production, test, etc.) +under a single installation, you can set up a connection group for each, then switch between groups as needed. +For example, to set up a "test" environment you would do this:

+ +

$db['test']['hostname'] = "localhost";

+$db['test']['username'] = "root";

+$db['test']['password'] = "";

+$db['test']['database'] = "database_name";

+$db['test']['dbdriver'] = "mysql";

+$db['test']['dbprefix'] = "";

+$db['test']['pconnect'] = TRUE;

+$db['test']['db_debug'] = FALSE;

+$db['test']['active_r'] = TRUE;

+ + +

Then, to globally tell the system to use that group you would set this variable located in the config file:

+ +$active_group = "test"; + +

Note: The name "test" is arbitrary. It can be anything you want. By default we've used the word "default" +for the primary connection, but it too can be renamed to something more relevant to your project.

+ +

Explanation of Values:

+ +

hostname - The hostname of your database server. Often this is "localhost".
username - The username used to connect to the database.
password - The password used to connect to the database.
database - The name of the database you want to connect to.
dbdriver - The database type. ie: mysql, postgre, obdc, etc. Must be specified in lower case.
dbprefix - An optional table prefix which will added to the table name when running Active Record queries. This permits multiple Code Igniter installations to share one database.
pconnect - TRUE/FALSE (boolean) - Whether to use a persistent connection.
db_debug - TRUE/FALSE (boolean) - Whether database errors should be displayed.
active_r - TRUE/FALSE (boolean) - Whether to load the Active Record Class. If you are not using the active record class you can have it omitted when the database classes are initialized in order to utilize less resources.

+ +

Note: Depending on what database platform you are using (MySQL, Postgre, etc.) +not all values will be needed. For example, when using SQLite you will not need to supply a username or password, and +the database name will be the path to your database file. The information above assumes you are using MySQL.

+ + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/connecting.html b/user_guide/libraries/database/connecting.html new file mode 100644 index 000000000..7bf93c302 --- /dev/null +++ b/user_guide/libraries/database/connecting.html @@ -0,0 +1,172 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + +
+ + + +

+ + +

Connecting to your Database

+ +

There are two ways to connect to a database:

+ +

Automatically Connecting

+ +

The "auto connect" feature will load and instantiate the database class with every page load. +To enable "auto connecting", add the word database to the core array, as indicated in the following file:

+ +

application/config/autoload.php

+ +

Manually Connecting

+ +

If only some of your pages require database connectivity you can manually connect to your database by adding this +line of code in any function where it is needed, or in your class constructor to make the database +available globally in that class.

+ +$this->load->database(); + +

If the above function does not contain any information in the first parameter it will connect +to the group specified in your database config file. For most people, this is the preferred method of use.

+ + +

The first parameter of this function can optionally be used to specify a particular database group +from your config file, or you can even submit connection values for a database that is not specified in your config file. +Examples:

+ +

To choose a specific group from your config file you can do this:

+ +$this->load->database('group_name'); + +

Where group_name is the name of the connection group from your config file.

+ + +

To connect manually to a desired database you can pass an array of values:

+ +

$config['hostname'] = "localhost";

+$config['username'] = "myusername";

+$config['password'] = "mypassword";

+$config['database'] = "mydatabase";

+$config['dbdriver'] = "mysql";

+$config['dbprefix'] = "";

+$config['pconnect'] = FALSE;

+$config['db_debug'] = TRUE;

+$config['active_r'] = TRUE;

+

+$this->load->database($config);

+ +

For information on each of these values please see the configuration page. + +

Or you can submit your database values as a Data Source Name. DSNs must have this prototype: + +$dsn = 'dbdriver://username:password@hostname/database'; + +$this->load->database('$dsn'); + +

Note that if you use a DSN you will not be able to specify some of the default values like you can if you use a connection array.

+ + + + +

Connecting to Multiple Databases

+ +

If you need to connect to more than one database simultaneously you can do so as follows:

+ + +

$DB1 = $this->load->database('group_one', TRUE);

+$DB2 = $this->load->database('group_two', TRUE);
+

+ +

Note: Change the words "group_one" and "group_two" to the specific group names you are connecting to (or +you can pass the connection values as indicated above).

+ +

By setting the second parameter to TRUE (boolean) the function will return the database object.

+ +

When you connect this way, you will use your object name to issue commands rather than the syntax used throughout this guide. In other words, rather than issuing commands with:

+ +

$this->db->query();
$this->db->result();
etc...

+ +

You will instead use:

+ +

$DB1->query();
$DB1->result();
etc...

+ +

+ + + + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/examples.html b/user_guide/libraries/database/examples.html new file mode 100644 index 000000000..e738ba825 --- /dev/null +++ b/user_guide/libraries/database/examples.html @@ -0,0 +1,183 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + + +

+ + + +
+ + + +

+ + +

Database Quick Start: Example Code

+ +

The following page contains example code showing how the database class is used. For complete details please +read the individual pages describing each function.

+ + +

Initializing the Database Class

+ +

The following code loads and initializes the database class based on your configuration settings:

+ +$this->load->database(); + +

Once loaded the class is ready to be used as described below.

+ +

Note: If all your pages require database access you can connect automatically. See the connecting page for details.

+ + +

Standard Query With Multiple Results (Object Version)

+ +

$query = $this->db->query('SELECT name, title, email FROM my_table');

+

+foreach ($query->result() as $row)

+{

+    echo $row->title;

+    echo $row->name;

+    echo $row->email;

+}

+

+echo 'Total Results: ' . $query->num_rows();
+

+ +

The above result() function returns an array of objects. Example: $row->title

+ + +

Standard Query With Multiple Results (Array Version)

+ +

$query = $this->db->query('SELECT name, title, email FROM my_table');

+

+foreach ($query->result_array() as $row)

+{

+    echo $row['title'];

+    echo $row['name'];

+    echo $row['email'];

+}

+ +

The above result_array() function returns an array of standard array indexes. Example: $row['title']

+ + +

Standard Query With Single Result

+ +

$query = $this->db->query('SELECT name FROM my_table LIMIT 1');

+

+$row = $query->row();

+echo $row->name;

+

+ + +

Standard Insert

+ +


+$sql = "INSERT INTO mytable (title, name) 

+        VALUES (".$this->db->escape($title).", ".$this->db->escape($name).")";

+

+$this->db->query($sql);

+

+echo $this->db->affected_rows();
+

+ + + + +

Active Record Query

+ +

The Active Record Pattern gives you a simplified means of retrieving data:

+ +


+$query = $this->db->get('table_name');

+

+foreach ($query->result() as $row)

+{

+    echo $row->title;

+}

+ + +

Active Record Insert

+ +


+$data = array(

+               'title' => $title,

+               'name' => $name,

+               'date' => $date

+            );

+

+$this->db->insert('mytable', $data);
+


+// Produces: INSERT INTO mytable (title, name, date) VALUES ('{$title}', '{$name}', '{$date}')

+ + + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/fields.html b/user_guide/libraries/database/fields.html new file mode 100644 index 000000000..dd2def9a3 --- /dev/null +++ b/user_guide/libraries/database/fields.html @@ -0,0 +1,144 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + +

+ + + +
+ + + +

+ + +

Field Data

+ + +

Retrieving Field Names

Sometimes it's helpful to gather the field names.

+ +

$this->db->field_names();

Returns an array containing the field names. You must supply the table name to the function:

+ +


+$fields = $this->db->field_names('table_name');


+
+foreach ($fields as $field)

+{

+   echo $field;

+}
+

+ + + +

Retrieving Field MetaData

Sometimes it's helpful to gather the field names or other metadata, like the column type, max length, etc.

+ +

$this->db->field_data();

Returns an array of objects containing field information.

+ +

Note: Not all databases provide meta-data.

+ +

Usage example:

+ +


+$fields = $this->db->field_data('table_name');


+
+foreach ($fields as $field)

+{

+   echo $field->name;

+   echo $field->type;

+   echo $field->max_length;

+   echo $field->primary_key;

+}
+

+ +

If you have run a query already you can use the result oject instead of supplying the table name:

+ +


+$query = $this->db->query("YOUR QUERY");

+$fields = $query->field_data();
+

+ + +

The following data is available from this function if supported by your database:

+ +

name - column name
max_length - maximum length of the column
primary_key - 1 if the column is a primary key
type - the type of the column

+ + + + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/index.html b/user_guide/libraries/database/index.html new file mode 100644 index 000000000..a8e7c8e77 --- /dev/null +++ b/user_guide/libraries/database/index.html @@ -0,0 +1,99 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + +
+ + + +

+ + +

The Database Class

+ +

Code Igniter comes with a full-featured and very fast abstracted database class that supports both traditional +structures and Active Record patterns. The database functions offer clear, simple syntax.

+ +

+ + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/queries.html b/user_guide/libraries/database/queries.html new file mode 100644 index 000000000..57fd916ef --- /dev/null +++ b/user_guide/libraries/database/queries.html @@ -0,0 +1,180 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + + +
+ + + +

+ + +

Queries

+ +

To submit a query, use the following function:

+ +$this->db->query('YOUR QUERY HERE'); + +

The query() function returns a database result object +which you can use to show your results. You will typically assign the query to your own variable, like this:

+ +$query = $this->db->query('YOUR QUERY HERE'); + + +

Escaping Queries

+ +

It's a very good security practice to escape your data before sumbiting it into your database. +Code Igniter has two functions that help you do this:

+ +

$this->db->escape() This function determines the data type so that it +can escape only string data. It also automatically adds single quotes around the data so you don't have to: + +$sql = "INSERT INTO table (title) VALUES(".$this->db->escape($title).")"; + + +
$this->db->escape_str() This function escapes the data passed to it, regardless of type. +Most of the time you'll use the above function rather then this one. Use the function like this: + +$sql = "INSERT INTO table (title) VALUES('".$this->db->escape_str($title)."')"; + + +

+ + + +

Query Bindings

+ + +

Bindings enable you to simplify your query syntax by letting the system put the queries together for you. Consider the following example:

+ +


+$sql = "SELECT * FROM some_table WHERE id = ? AND status = ? AND author = ?";
+


+$this->db->query($sql, array(3, 'live', 'Rick'));
+

+ +

The question marks in the query are automatically replaced with the values in the array in the second parameter of the query function.

The secondary benefit of using binds is that the values are automatically escaped, producing safer queries. You don't have to remember to manually escape data; the engine does it automatically for you.

+ + + +

Query Helper Functions

+ + +

$this->db->last_query();

+ +

Returns the last query that was run (the query string, not the result). Example:

+ +

$str = $this->db->last_query();

+

+// Produces:  SELECT * FROM sometable....
+

+ + +

The following two functions help simplify the process of writing database INSERTs and UPDATEs.

+ + +

$this->db->insert_string();

This function simplifies the process of writing database inserts. It returns a correctly formatted SQL insert string. Example:

+ +

$data = array('name' => $name, 'email' => $email, 'url' => $url);

+

+$str = $this->db->insert_string('table_name', $data);
+

+ +

The first parameter is the table name, the second is an associative array with the data to be inserted. The above example produces:

+INSERT INTO table_name (name, email, url) VALUES ('Rick', 'rick@your-site.com', 'www.your-site.com') + + + +

$this->db->update_string();

This function simplifies the process of writing database updates. It returns a correctly formatted SQL update string. Example:

+ +

$data = array('name' => $name, 'email' => $email, 'url' => $url);

+

+$where = "author_id = 1 AND status = 'active'";
+


+$str = $this->db->update_string('table_name', $data, $where);
+

+ +

The first parameter is the table name, the second is an associative array with the data to be inserted, and the third parameter is the "where" clause. The above example produces:

 UPDATE exp_weblog SET name = 'Rick', email = 'rick@your-site.com', url = 'www.your-site.com' WHERE author_id = 1 AND status = 'active'

+ + + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/results.html b/user_guide/libraries/database/results.html new file mode 100644 index 000000000..7e6b95d2f --- /dev/null +++ b/user_guide/libraries/database/results.html @@ -0,0 +1,235 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + +
+ + + +

+ + + +

Query Results

+ + +

There are several ways to generate query results:

+ +

result()

+ +

This function returns the query result as an array of objects, or FALSE on failure. + + Typically you'll use this in a foreach loop, like this:

+ +


+	$query = $this->db->query("YOUR QUERY");

+	

+	foreach ($query->result() as $row)

+	{

+	   echo $row->title;

+	   echo $row->name;

+	   echo $row->body;

+	}

+ +

If you run queries that might not produce a result, you are encouraged to test the result first:

+ +


+	$query = $this->db->query("YOUR QUERY");

+	

+	if ($query->num_rows() > 0)

+	{

+	   foreach ($query->result() as $row)

+	   {

+	      echo $row->title;

+	      echo $row->name;

+	      echo $row->body;

+	   }

+	}
+

+ +

result_array()

+ +

This function returns the query result as a pure array, or FALSE on failure. Typically you'll use this in a foreach loop, like this:


+	$query = $this->db->query("YOUR QUERY");

+	

+	foreach ($query->result_array() as $row)

+	{

+	   echo $row['title'];

+	   echo $row['name'];

+	   echo $row['body'];

+	}

+ + +

row()

+ +

This function returns a single result row. If your query has more than one row, it returns only the first row. + The result is returned as an object. Here's a usage example:


+	$query = $this->db->query("YOUR QUERY");

+	

+	if ($query->num_rows() > 0)

+	{

+	   $row = $query->row();
+	


+	   echo $row->title;

+	   echo $row->name;

+	   echo $row->body;

+	}
+

+ +

If you want a specific row returned you can submit the row number as a digit in the first parameter: + + $row = $query->row(5); + + +

row_array()

+ +

Identical to the above row() function, except it returns an array. Example:

+ +


+	$query = $this->db->query("YOUR QUERY");

+	

+	if ($query->num_rows() > 0)

+	{

+	   $row = $query->row_array();
+	


+	   echo $row['title'];

+	   echo $row['name'];

+	   echo $row['body'];

+	}
+

+ + +

If you want a specific row returned you can submit the row number as a digit in the first parameter: + + $row = $query->row_array(5); + + +

In addition, you can walk forward/backwards/first/last through your results using these variations:

+ +

+ $row = $query->first_row()
+ $row = $query->last_row()
+ $row = $query->next_row()
+ $row = $query->previous_row() +

+ +

By default they return an object unless you put the word "array" in the parameter:

+ +

+ $row = $query->first_row('array')
+ $row = $query->last_row('array')
+ $row = $query->next_row('array')
+ $row = $query->previous_row('array') +

+ + +

Query Result Helpers

+ +

The following functions provide useful information when dealing with query results.

+ +

$query->num_rows()

The number of rows returned by the query. Note: $query is the variable that the query was assigned to:

+ +

$query = $this->db->query('SELECT * FROM my_table');


+echo $query->num_rows();
+

+ +

$query->num_fields()

The number of FIELDS returned by the query. Make sure to call the function using your query result object:

+ +

$query = $this->db->query('SELECT * FROM my_table');


+echo $query->num_fields();
+

+ + +

$this->db->insert_id()

The insert ID number when performing database inserts.

+ +

$this->db->affected_rows()

Displays the number of affected rows, when doing "write" type queries (insert, update, etc.).

Note: In MySQL "DELETE FROM TABLE" returns 0 affected rows. The database class has a small hack that allows it to return the +correct number of affected rows. By default this hack is enabled but it can be turned off in the database driver file.

+ + +

$this->db->version()

Outputs the database version you are running:

+ +echo $this->db->version(); + + + + + +

+ + + + + + + \ No newline at end of file diff --git a/user_guide/libraries/database/table_data.html b/user_guide/libraries/database/table_data.html new file mode 100644 index 000000000..7d340d4e8 --- /dev/null +++ b/user_guide/libraries/database/table_data.html @@ -0,0 +1,116 @@ + + + + +Code Igniter User Guide + + + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

+ + + +
+ + + +

+ +

Table Data

+ +

These functions let you fetch table information.

+ +

$this->db->tables();

+ +

Returns an array containing the names of all the tables in the database you are currently connected to. Example:

+ +

$tables = $this->db->tables()

+

+foreach ($tables as $table)

+{

+   echo $table;

+}
+

+ + +

$this->db->table_exists();

+ +

Sometimes it's helpful to know whether a particular table exists before running an operation on it. +Returns a boolean TRUE/FALSE. Usage example:

+ +


+if ($this->db->table_exists('table_name'))

+{

+   // some code...

+}
+

+ +

Note: Replace table_name with the name of the table you are looking for.

+ + + + + +

+ + + + + + + \ No newline at end of file -- cgit v1.2.3-24-g4f1b

Code Igniter User Guide Version 1.4.0

Active Record Class

Selecting Data

$this->db->get();

$this->db->getwhere();

$this->db->select();

$this->db->from();

$this->db->join();

$this->db->where();

$this->db->orwhere();

$this->db->like();

$this->db->orlike();

$this->db->groupby();

$this->db->having();

$this->db->orderby();

$this->db->limit();

$this->db->count_all();

Inserting Data

$this->db->insert();

$this->db->set();

Updating Data

$this->db->update();

Deleting Data

$this->db->delete();

Method Chaining

Code Igniter User Guide Version 1.4.0

Custom Function Calls

$this->db->call_function();

Code Igniter User Guide Version 1.4.0

Database Configuration

Explanation of Values:

Code Igniter User Guide Version 1.4.0

Connecting to your Database

Automatically Connecting

Manually Connecting

Connecting to Multiple Databases

Code Igniter User Guide Version 1.4.0

Database Quick Start: Example Code

Initializing the Database Class

Standard Query With Multiple Results (Object Version)

Standard Query With Multiple Results (Array Version)

Standard Query With Single Result

Standard Insert

Active Record Query

Active Record Insert

Code Igniter User Guide Version 1.4.0

Field Data

Retrieving Field Names

$this->db->field_names();

Retrieving Field MetaData

$this->db->field_data();

Code Igniter User Guide Version 1.4.0

The Database Class

Code Igniter User Guide Version 1.4.0

Queries

Escaping Queries

Query Bindings

Query Helper Functions

$this->db->last_query();

$this->db->insert_string();

$this->db->update_string();

Code Igniter User Guide Version 1.4.0

Query Results

result()

result_array()

row()

row_array()

Query Result Helpers

$query->num_rows()

$query->num_fields()

$this->db->insert_id()

$this->db->affected_rows()

$this->db->version()

Code Igniter User Guide Version 1.4.0

Table Data

$this->db->tables();

$this->db->table_exists();