Project: OmniPHP(tm) Framework 0.1.1 Author: Carmelo Vargas URLs: http://www.omniphp.com/ http://www.omniphp.net/ http://www.omniphp.org/ http://omniphp.sourceforge.net/ NOTE: This tutorial is meant to help all newcomers, please feel free to contribute or suggest on implementations for this. We welcome any input. =============================== TUTORIAL 1 =============================== [Requirements] Unfortunately I do not have the time to provide support for non-experienced developers and since the main purpose of the framework is to provide an enterprise-quality solution it was always inteded to be used by experienced web developers who already knew PHP, XHTML, CSS, JavaScript, XML, and an RDBMS (MS SQL Server and/or MySQL). If you are a beginner there are hundreds of excellent books, support forums, communities, etc where you can become a proficient programmer. You should particularly develop a few professional quality applications and websites before you move on to use a framework as it is of upmost importance that you understand what the framework is doing in case you need to customize a very particular solution that would require you to modify the framework libraries. [Technical Requirements] You need a fully functional server that runs PHP and have one of these RDBMS's: MySQL or MSSQL. You need to create a database called omniphp in either MS SQL Server or MySQL (default). If you use MS SQL Server you need to comment all the MySQL lines in the sample applications and uncomment the MS SQL ones. Install the databases: See instructions on README.txt and install databases.sql (MySQL) or databases.xls (MS SQL Server) or both (recommended) so you can go through the sample applications. [Recommended Software for Development] For commercial development I recommend one of these three IDE's/Editors: + DreamWeaver + NuSphere PhpED + Zend Studio You can also use the excellent (and quite probably the best editor for Windows): Notepad++ The Linux gurus can of course use their all time favorites: Emacs or Vi. [In Good Faith] Please note that this project is in NO WAY affiliated with the PHP language or any of its projects or subsidiaries. The OmniPHP(tm) Framework is only a set of libraries independently developed to serve a purpose and it is not part of any of those projects. Please DO NOT refer any questions regarding this framework to PHP, MySQL, Microsoft, Linux, or any other entity; feel free to use our support forums, contact us via e-mail, or through any of the provided information [How to use] How to use the OmniPHP(tm) Framework? The easiest path is to go through the samples, starting from the easiest one a basic form that inserts data to a database. Before we discuss this, let's go through the basics; what you need. All applications using the framework will need all the files in that are located in the core folder, except for core.php which is basically a sample of useful web controls you can implement in a form. You will see a folder called _include (I recommend you make this folder READ-ONLY) with the following files: .htaccess (Apache configuration file that blocks access to this folder, for IIS do this in the administration tools for your site). globals_inc.php You may change $OMNIPHP_COPYRIGHT to your own copyright notice. Whether you are using MySQL or SQL Server (or both) change the appropriate values (host, username, password, database, and optionally a table name (usually done if you will only be querying one table, for simpler applications)). omniphp_config_inc.php For testing purposes leave this "define("OMNIPHP_DEBUG", true);" line of code, this will output all the variables that were posted (HTTP request) during a submission, it will display PHP code errors (i.e. incorrect syntax, incorrect calls, exceptions, etc), and database errors. This information is intended for development/debugging only and SHOULD NOT be available on production releases, once you are ready to upload your code for official release comment this line of code. Modify the language and time zone, values available for Puerto Rico and United States, if you are in another country you can comment these lines and just make a date_default_timezone_set(...) call to your country as stated see the Appendix in the PHP Manual for your timezone. This defaults to US/Eastern. omniphp_db.php This is the library that handles all database connectivity for the supported RDBMS engines. You do NOT need to modify anything here, you browse through the code as reference on how to perform API calls to this library, but preferably just follow the samples (discussed later on). omniphp_inc.php This is the library that wraps and extends Spry and jQuery to provide Web 2.0 RIA interfacing with the framework. Also this library includes debugging functions, session management, AJAX, XML, and others. Basically this is the core of the framework. Like with the omniphp_db, you do NOT need to modify anything here, you browse through the code as reference on how to perform API calls to this library, but preferably just follow the samples (discussed later on). The "images" folder literarily contains that, you may add your images here or modify this at will. The jquery.ui.x and the SpryAssets folders contain the JavaScript/AJAX wrappers; you do NOT need to modify any of the content here. You will then see 4 optional files that are not required but recommended: .htaccess Again an Apache configuration file that disallows indexing, on IIS do this in the administration tools. core.php Samples of many useful web controls you can implement (first finish this tutorial before diving in this). omniphp_layout.css A generic CSS used in the samples and the core.php, you can modify this at will or add the CSS's you require. omniphp_validation.css A CSS that overrides the Spry framework styles and makes the web controls more user friendly. We recommend you leave this file as it is unless you want to use your own styles for the controls. Now let's go back to going through the samples, go back to the root folder (omniphp) and go to the "samples" folder. You will see 3 different application samples here: 1) A feedback/comments simple form application (feedback.php) that INSERTS to a database. 2) A basic report application (report.php) that RETRIEVES from a database and produces a very basic report. 3) A full-blown CRUD (Create, Retrieve, Update, Delete) application that emulates database management of a hypothetical customers database of a hypothetical bank (dataentry.php AND searchdb.php). [ THE TUTORIAL -- FEEDBACK APPLICATION ] This tutorial will focus in a basic example; the feedback application. I. Open feedback.php in your favorite editor. II. In the actual code, the entire section under includes and libraries has to be included FOR ALL projects using the OmniPHP(tm) Framework. In the "if(!empty($_POST))" section you will perform all server-side validations. At runtime these will be performed before any SQL command (select query, insert, update, or delete) is executed. Upon finding an error you should push it into the $submissionErrorsArray which will be dispatched before performing any SQL command. Only successful validations will go through. To validate data, i.e. CustomerName, instead of $_POST['frmCustomerName'], I recommend you use $lg_lastVal['frmCustomerName'] PLEASE NOTE the frm prefix, you will ALWAYS prefix any posted variable with frm, so if you created an integer input textbox called Age, you will retrieve it like: $lg_lastVal['frmAge']. For instance if you wanted the input for an age to be between 18 and 50 years then you could add code like this: if(!empty($_POST)) { $lg_lastVal = $_POST; //Server-side validations: if(!ctype_digit($lg_lastVal['frmAge']) || $lg_lastVal['frmAge'] < 18 || $lg_lastVal['frmAge'] > 50) { array_push($submissionErrorsArray, "Only ages through 18 - 50 qualify."); } } III. The HTML code can be modified at will, though I prefer that you only modify keywords and description meta tags and leave the rest as they are. Add the title and CSS layouts you wish (I recommend you leave the omniphp_validation.css at the very least. You will need all the Spry and jQuery includes, DO NOT MODIFY or delete these. IV. You may ignore the rest of the code until: else //all validations passed, perform INSERT/UPDATE. Here you will tell the code to perform an INSERT (in this case) For the $VARCHAR_LENGTH, add the specific value for each column that has a distinct length. The value will be truncated to this (so if you have a VARCHAR(500) for the column CustomerEmail, then you should set something like this: if($i === "frmCustomerEmail") $VARCHAR_LENGTH = 500; On this line: if($i == "Submit" || $i == "frmUID") Add all the posted data names that need to be ignored. Customize the success and error messages at will, you can also output all errors (only for debugging) or only display a generic 'system down'-like error. V. The code in the form (web controls) is self explanatory you will basically create the variable name in $domName (i.e. Age, CustomerName, CustomerEmail, CreditCardNumber, ProductList, Comments, etc.) then you will perform a method call to the control you want to create. See omniphp_inc.php for reference on all method calls and the arguments to pass over. Also omniphp_db.php for the method calls to the database and how to perform the SQL commands.