Location: PHPKode > scripts > EasySQL classes > documentation.htm
<?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 &quot;SELECT&quot;, &quot;INSERT&quot;, 
        &quot;UPDATE&quot;, &quot;DELETE&quot; and &quot;TRUNCATE&quot; 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">&lt;?php</span>

<span class="comments">// Imports EasySQL class</span>
<span class="function">require_once</span> <span class="string">&quot;class.easysql.php&quot;</span>;

<span class="comments">// Creates and object called &quot;$SQL&quot;</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">?&gt;</span>
</pre>

    <p>
        Parameters are: database software (e.g. &quot;MySQL&quot;, &quot;PostGreSQL&quot;, &quot;SQLite&quot;),
        host (default: &quot;localhost&quot;), 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 &quot;host&quot;, &quot;user&quot;, &quot;password&quot;
        and &quot;port&quot; 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">&lt;?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">?&gt;</span>
</pre>

    <p>
        And now a real life example. Let's suppose you want to select the &quot;name&quot; and &quot;email&quot; of all 
        clients that celebrate birthday in this month. The name of database in this example is &quot;my_database&quot; and 
        the selected table is &quot;clients&quot;.
    </p>

<span class="title">3. Using SELECT clause:</span>
<pre class="code">
<span class="php_tags">&lt;?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">&quot;clients&quot;</span>);

<span class="comments">// You could avoid the 3 next steps writing the query:
// $SQL->query(&quot;SELECT name, email FROM clients WHERE MONTH(birthday) = MONTH(now())&quot;)</span>
$SQL-><span class="function">setSelection</span>(<span class="string">&quot;name, email&quot;</span>);
$SQL-><span class="function">setWhere</span>(<span class="string">&quot;MONTH(birthday) = MONTH(now())&quot;</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">&quot;&lt;br /&gt;&quot;</span> . $row[<span class="string">'name'</span>] . <span class="string">&quot; - &quot;</span>  . $row[<span class="string">'email'</span>];
}

<span class="function">echo</span> <span class="string">&quot;&lt;br /&gt;Total: &quot;</span> . $SQL->total_rows;

<span class="php_tags">?&gt;</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 &quot;mysql&quot; or 0, if using MySQL. &quot;pg&quot;,&quot;postgre&quot;,
               &quot;postgresql&quot; or 1, if using PostGreSQL. And &quot;sqlite&quot; or 2 if using SQLite. This
               parameter is case insensitive, so &quot;MySQL&quot; is equal to &quot;mysql&quot;.</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 &quot;fetch_array&quot; 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 &quot;fetch_assoc&quot; 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 &quot;fetch_row&quot; 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 &quot;WHERE&quot; in 
         the beginning of the parameter. The right way is: setWhere(&quot;id > 10 AND name LIKE '%Reche%'&quot;);
       </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 &quot;LIMIT&quot; in 
         the beginning of the parameter. The right way is: setLimit(&quot;0, 20&quot;);
       </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 &quot;*&quot;
       </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>
Return current item: EasySQL classes