<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>EasySQL Documentation</title>
<style type="text/css">
<!--
body {
margin: 30px 5%;
text-align: left;
font: 75% Verdana, Arial;
}
h1 {
margin: 0px 0px 70px 0px;
text-align: center;
color: #00c;
}
h2 {
margin: 50px 0px 0px 0px;
color: #c00;
}
h3 {
margin: 50px 0px 10px 0px;
color: #080;
}
h3 .parameters {
font-size: 90%;
color: #333;
}
h3 .type {
color: #999;
font-style: italic;
}
hr {
margin: 5px 0px;
width: 90%;
text-align: left;
color: #aaa;
}
.title {
line-height: 40px;
font-size: 120%;
color: #000;
font-weight: bold;
}
pre.code {
margin: 0px 0px 40px 0px;
width: 750px;
padding: 10px;
background-color: #e5e5e5;
border: 1px dotted #000;
font: 120% Courier New, Lucida Console;
}
pre.code .php_tags {
font-weight: bold;
color: #c00;
}
pre.code .function {
color: #00c;
}
pre.code .structure {
color: #060;
}
pre.code .string {
color: #c00;
}
pre.code .numeric {
color: #f00;
}
pre.code .comments {
color: #f70;
}
a:link {
color: #00c;
text-decoration: none;
}
a:visited {
color: #00c;
text-decoration: none;
}
a:hover {
color: #c70;
}
a:active {
color: #c00;
}
strong.note {
color: #00c;
margin-left: 30px;
}
ol {
margin-top: 5px;
}
-->
</style>
</head>
<body>
<h1>EasySQL Documentation</h1>
<h2>Introduction</h2>
<hr />
<p>
EasySQL provides the same interface to access MySQL, PostgreSQL and SQLite. It also has friendly
methods that will help to create and execute "SELECT", "INSERT",
"UPDATE", "DELETE" and "TRUNCATE" queries.
</p>
<h2>How to Use</h2>
<hr />
<p>
First, it will be necessary import <strong>EasySQL</strong> class file to the script. Than you may create the object from
EasySQL class.
</p>
<span class="title">1. Creating the EasySQL object:</span>
<pre class="code">
<span class="php_tags"><?php</span>
<span class="comments">// Imports EasySQL class</span>
<span class="function">require_once</span> <span class="string">"class.easysql.php"</span>;
<span class="comments">// Creates and object called "$SQL"</span>
$SQL = <span class="structure">new</span> <span class="function">EasySQL</span>(<span class="string">"MySQL"</span>, <span class="string">"host"</span>, <span class="string">"user"</span>, <span class="string">"password"</span>, <span class="string">"database_name"</span>, <span class="numeric">3306</span>);
<span class="php_tags">?></span>
</pre>
<p>
Parameters are: database software (e.g. "MySQL", "PostGreSQL", "SQLite"),
host (default: "localhost"), user, password, database that will be selected and server port. This
last one is optional, and will assume default ports for each server software (3306 for MySQL, 5432 for PostGreSQL).
</p>
<p>
<strong class="note">NOTE:</strong> on SQLite, parameters "host", "user", "password"
and "port" will be automatically ignored, because this database won't use them. So, you can use
an alternative method to create the object when using SQLite:
</p>
<span class="title">2. SQLite allows a different instance:</span>
<pre class="code">
<span class="php_tags"><?php</span>
<span class="comments">// These examples produce exactly the same result because SQLite doesn't need
// any other parameter than "database_name"</span>
$SQL = <span class="structure">new</span> <span class="function">EasySQL</span>(<span class="string">"SQLite"</span>, <span class="string">"host"</span>, <span class="string">"user"</span>, <span class="string">"password"</span>, <span class="string">"database_name"</span>, <span class="numeric">3306</span>);
$SQL = <span class="structure">new</span> <span class="function">EasySQL</span>(<span class="string">"SQLite"</span>, <span class="string">"database_name"</span>);
<span class="php_tags">?></span>
</pre>
<p>
And now a real life example. Let's suppose you want to select the "name" and "email" of all
clients that celebrate birthday in this month. The name of database in this example is "my_database" and
the selected table is "clients".
</p>
<span class="title">3. Using SELECT clause:</span>
<pre class="code">
<span class="php_tags"><?php</span>
$SQL = <span class="structure">new</span> <span class="function">EasySQL</span>(<span class="string">"MySQL"</span>, <span class="string">"localhost"</span>, <span class="string">"root"</span>, <span class="string">"password"</span>, <span class="string">"my_database"</span>);
$SQL-><span class="function">useTable</span>(<span class="string">"clients"</span>);
<span class="comments">// You could avoid the 3 next steps writing the query:
// $SQL->query("SELECT name, email FROM clients WHERE MONTH(birthday) = MONTH(now())")</span>
$SQL-><span class="function">setSelection</span>(<span class="string">"name, email"</span>);
$SQL-><span class="function">setWhere</span>(<span class="string">"MONTH(birthday) = MONTH(now())"</span>);
$SQL-><span class="function">select</span>();
<span class="comments">// Printing results</span>
<span class="structure">while</span> ($row = $SQL-><span class="function">fetchArray</span>()) {
<span class="function">echo</span> <span class="string">"<br />"</span> . $row[<span class="string">'name'</span>] . <span class="string">" - "</span> . $row[<span class="string">'email'</span>];
}
<span class="function">echo</span> <span class="string">"<br />Total: "</span> . $SQL->total_rows;
<span class="php_tags">?></span>
</pre>
<p>
If your database software were PostGreSQL or SQLite, you would use exactly the same functions.
</p>
<p>
<strong class="note">NOTE:</strong> you do NOT need to call <em>connect()</em> or <em>close()</em> methods when using
<em>query()</em>, <em>select()</em>, <em>insert()</em>, <em>update()</em>, <em>delete()</em> or
<em>truncate()</em> methods. They all will test if the object has been connected to the database. If not,
it will create a temporary connection (only during the query execution).
</p>
<h2>Methods</h2>
<hr />
<p>
<h3><span class="type">void</span> EasySQL <span class="parameters">( <span class="type">str</span> $db_software, <span class="type">str</span> $host, <span class="type">str</span> $user, <span class="type">str</span> $password, <span class="type">str</span> $db_name [, <span class="type">int</span> $port ] )</span></h3>
Class constructor. Parameters are:
<ol>
<li>database_software: could be "mysql" or 0, if using MySQL. "pg","postgre",
"postgresql" or 1, if using PostGreSQL. And "sqlite" or 2 if using SQLite. This
parameter is case insensitive, so "MySQL" is equal to "mysql".</li>
<li>host: host address (default if parameter is empty: localhost).</li>
<li>user: database username.</li>
<li>password: password for username.</li>
<li>database_name: database that will be used.</li>
<li>port: port number. This is optional, and will assume 3306 for MySQL, and 5432 for PostGreSQL.</li>
</ol>
</p>
<p>
<h3><span class="type">resource</span> connect <span class="parameters">( [<span class="type">str</span> $db_name] )</span></h3>
Opens a connection to the specified database. If no parameters were passed, it will try the database defined on
the class constructor.
</p>
<p>
<h3><span class="type">resource</span> pconnect <span class="parameters">( [<span class="type">str</span> $db_name] )</span></h3>
The same of connect(), but the conection opened is persistent.
</p>
<p>
<h3><span class="type">bool</span> close <span class="parameters">()</span></h3>
Closes the connection opened by connect().
</p>
<p>
<h3><span class="type">bool</span> disconnect <span class="parameters">()</span></h3>
This method is an alias to close().
</p>
<p>
<h3><span class="type">resource</span> query <span class="parameters">( <span class="type">str</span> $query )</span></h3>
Sends a query.
</p>
<p>
<h3><span class="type">array</span> fetchArray <span class="parameters">( [<span class="type">resource</span> $result] )</span></h3>
Returns an array that corresponds to the fetched row, or FALSE if there are no more rows. This method works like the
PHP native "fetch_array" functions (as mysql_fetch_array(), for example). If no parameters were defined, it
will use the result of the last executed query.
</p>
<p>
<h3><span class="type">array</span> fetchAssoc <span class="parameters">( [<span class="type">resource</span> $result] )</span></h3>
Returns an associative array that corresponds to the fetched row, or FALSE if there are no more rows. This method works
like the PHP native "fetch_assoc" functions (as mysql_fetch_assoc(), for example). If no parameters were defined,
it will use the result of the last executed query.
</p>
<p>
<h3><span class="type">array</span> fetchRow <span class="parameters">( [<span class="type">resource</span> $result] )</span></h3>
Returns an array that corresponds to the fetched row, or FALSE if there are no more rows. This method works
like the PHP native "fetch_row" functions (as mysql_fetch_row(), for example). If no parameters were defined, it
will use the result of the last executed query.
</p>
<p>
<h3><span class="type">void</span> useDatabase <span class="parameters">( <span class="type">str</span> $db_name )</span></h3>
Changes the database name specified in the class constructor.
</p>
<p>
<h3><span class="type">str</span> error <span class="parameters">( )</span></h3>
Displays the last error.
</p>
<p style="margin-top: 70px; font-weight: bold; color: #c00;">
Methods below are intended to make easier the process of creating and executing queries. You will not necessarily use them.
</p>
<p>
<h3><span class="type">void</span> useTable <span class="parameters">( <span class="type">str</span> $table_name )</span></h3>
Defines what table should be used when creating and executing the SQL query.
</p>
<p>
<h3><span class="type">void</span> setFieldValue <span class="parameters">( <span class="type">str</span> $field, <span class="type">mixed</span> $value, <span class="type">bool</span> $is_sql_function )</span></h3>
Creates an internal list of field values that will be used on INSERT or UPDATE queries. Optional parameter sets if
the parameter passed on $value should be interpreted as an SQL function, like NOW(), CONCAT(), etc.
</p>
<p>
<h3><span class="type">void</span> setWhere <span class="parameters">( <span class="type">str</span> $where_clause )</span></h3>
Defines the WHERE clause used on SELECT, UPDATE and DELETE queries. Use this method without writing "WHERE" in
the beginning of the parameter. The right way is: setWhere("id > 10 AND name LIKE '%Reche%'");
</p>
<p>
<h3><span class="type">void</span> setLimit <span class="parameters">( <span class="type">str</span> $limit_clause )</span></h3>
Defines the LIMIT clause used on SELECT, UPDATE and DELETE queries. Use this method without writing "LIMIT" in
the beginning of the parameter. The right way is: setLimit("0, 20");
</p>
<p>
<h3><span class="type">void</span> setSelection <span class="parameters">( <span class="type">str</span> $selection )</span></h3>
Defines the selected fields on SELECT clause. Default is "*"
</p>
<p>
<h3><span class="type">resource</span> select <span class="parameters">( )</span></h3>
Executes a SELECT query.
</p>
<p>
<h3><span class="type">resource</span> insert <span class="parameters">( )</span></h3>
Executes an INSERT query.
</p>
<p>
<h3><span class="type">resource</span> update <span class="parameters">( )</span></h3>
Executes an UPDATE query. If where clause is not defined, the query execution is aborted for security reasons.
</p>
<p>
<h3><span class="type">resource</span> delete <span class="parameters">( )</span></h3>
Executes a DELETE query. If where clause is not defined, the query execution is aborted for security reasons.
</p>
<p>
<h3><span class="type">resource</span> truncate <span class="parameters">( )</span></h3>
Executes a TRUNCATE query (erases all contents of the table).
</p>
<h2>Credits</h2>
<hr />
<p>
Carlos Reche <br />
<em><a href="mailto:hide@address.com">carlosreche at yahoo dot com</a></em>
</p>
<p>
Jan 5, 2005<br />
Sorocaba, SP - Brazil
</p>
</body>
</html>