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, ./assets/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 ./assets/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 ('assets/domit/xml_domit_include.php'); require_once ('assets/ParamsProxy.php'); require_once ('assets/UTF8.php'); require_once ('assets/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 ./assets/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 email@example.com 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 ./assets/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 firstname.lastname@example.org 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 email@example.com, thank you.