File: HowToInstall.txt

 HOW TO INSTALL DbProxy DEMO
-------------------------------

Contents:
 1. What is DbProxy
 2. What the demo does
 3. Installing the demo
 4. License
 5. Author
 6. Version

1. DbProxy is a PHP class that provides a generic agregation mechanism for SQL queries.

   Essentially, you place SQL templates in external XML files, one file for each class that needs
   database access. Every such SQL template becomes a stub, a virtual PHP method that you can invoke and
   pass arguments to. The arguments you invoke a stub with fill its associated SQL template. The
   resulting query is executed on the database. Once this query has produced a result, this result is
   parsed and then passed back to the originating stub, as its return value.

   The DbProxy class provides protection against SQL injections. All string arguments passed to stubs
   are encoded prior to being sent to the database. All string values read from the database are decoded
   prior to being returned to stubs. It is, thus, recomended not to mix proxied and direct access to the
   same database.

2. This demo provides a sample PHP class, ./DbProxyDemo.php, and a sample database access file,
   ./dbAccess.xml. You will use the database access file to execute proxied operations on the
   database.

   The sample PHP class is only roughly sketched, as it doesn't perform a full CRUD (create, read,
   update, delete) set of operations on the database.

3. a) ParamsProxy Setup
      If you have already setup ParamsProxy on this machine, you may skip this step, in whole or in
      part.

      DbProxy is built on top of the ParamsProxy class. Before being able to use the ParamsProxy class,
      you must setup a configuration folder. All configuration files will live in here, each placed
      under a sub-folder with the same name as the name of the class to be configured.

      Under Unix, create this folder:
      /home/MyConfig

      Under Windows, create this folder:
      C:\MyConfig

      Open the file ./ParamsProxy_config.xml and fill in the path of the folder just created,
      e.g.:

      <value>/home/MyConfig/</value>

   b) Gathering required dependencies
      i.   the ParamsProxy class requires the DOMIT! XML parsing library by John Heinstein;
      ii.  the DbProxy class requires the ParamsProxy class.
      iii. the DbProxy class requires the UTF8 library.
      iv.  the DbProxyDemo class requires the DbProxy class.

      In this demo, all required files are placed under the ./assets folder, but in real life
      scenarios you'll want to provide better grouping to your libraries, especially for large projects.
      For now, just include needed files by placing this code in DbProxyDemo.php:

	  require_once ('domit/xml_domit_include.php');
	  require_once ('ParamsProxy.php');
	  require_once ('UTF8.php');
	  require_once ('DbProxy.php');

   c) Declaring the class
   	  In order to execute proxied operations on the database, you need to create an instance of DbProxy
   	  and hook it to the current execution context. In our case, the current execution context is the
   	  current instance of our DbProxyDemo class.

      Open the DbProxyDemo.php file and add this code to its constructor method:

	  // Instantiate the proxy:
	  $this->dbProxy = new DbProxy();
	  // Hook up this class to the proxy:
	  $this->dbProxy->configure($this);

   d) Database access file
	  You will allways write your SQL templates in a file named dbAccess.xml. You place this file,
	  under the configuration folder, in a sub-folder with the same name as the name of the class that
	  needs database access. This is the exact same location as for configuration files.

	  i.   change into /home/MyConfig (on Unix) or C:\MyConfig (on Windows);
	  ii.  create sub-folder DbProxyDemo
	  iii. change into just created sub-folder
	  iv.  copy provided file ./dbAccess.xml as /home/MyConfig/DbProxyDemo/dbAccess.xml (on
	       Unix) or as C:\MyConfig\DbProxyDemo\dbAccess.xml (on Windows)

   e) Database setup
      You need to provide a database to host the table needed by this demo.

      The mysql session transcript below shows you how to create a database called "DbProxyDemo", having
      a user named "test", authenticated by password "1234". You may, of course, use a visual tool, such
      as PHPMyAdmin instead of the mysql terminal; or you could use an already existing database
      althogether. If you do use an existing database, you must update its connection data inside your
      database access file.

	  mysql> mysql -u root -p
	  Enter password: ****
	  Welcome to the MySQL monitor.  Commands end with ; or \g.
	  Your MySQL connection id is 2
	  Server version: 5.1.33-community MySQL Community Server (GPL)

	  Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

	  mysql> create database DbProxyDemo;
	  Query OK, 1 row affected (0.02 sec)
	  mysql> grant all on DbProxyDemo.* to test@localhost identified by '1234';
	  Query OK, 0 rows affected (0.03 sec)
	  mysql> quit;
	  Bye

   f) Completing instalation
      Point your browser to the DbProxyDemo.php file. If you have correctly installed DbProxy, you
      should see an empty table and a form beneath it.

      Use the form to add entries to the table.

      For any new PHP class that needs to execute proxied operations on the database, you'll only need
      to repeat c) trough e). Of course, you'll need to adapt the database access file (and the database
      itself) accordingly.

4. Both this demo and the DbProxy class are licensed under the Creative Commons Attribution Share
   Alike license. You should have received a full copy of this license as
   ./Creative Commons Attribution Share Alike.txt. The full license body is also available
   online, at http://creativecommons.org/licenses/by-sa/3.0/legalcode.

5. The DbProxy class has been written and is being maintained by Claudius Tiberiu Iacob. You can reach
   me at claudius.iacob@gmail.com.

6. You're holding version 1.5a (alpha) of DbProxy. Please note that API and functionality are subject to
   change in future versions. Send all bugs to claudius.iacob@gmail.com, thank you.