version: #1 (current)  |  last edited by: Mike Ho  |  on: tuesday, october 18, 2005, 5:30 pm pdt (about 13 years ago)


This is an elaboration of the README file that is included in the official release.  It takes you through the four simple, quick steps to installing and getting up and running with the Qcodo framework.



NOTE: The instructions here are for Beta 1.  For Beta 1.1 and Beta 2, please refer to the _README.txt file which is included in the distribution.


This article will take you to the quick, simple few steps to install and get you started with Qcodo.  This article will assume that you have at least some very basic knowledge of setting up and/or configuring webservers.  If you need assistance with this, please feel free to read the documentation for your webserver.

Installing the Prerequisites

The first thing you want to do is ensure that you have a standard, working installation of a webserver (e.g. Apache, IIS, etc.) and of PHP 5.  The framework is not compatible with version 4 of PHP -- the main reason is that PHP 5 has a completely redesigned, mature object model which Qcodo takes direct advantage of.

You will also want to have a MySQL installed.  Over the next couple of months, Qcodo will incorporate adapters for other databases, including support for SQL Server, PostgreSQL, and Oracle.  But for now, only MySQL support is included built-in.

Obviously, you will want to make sure that all three are functioning together before moving on.

Step 1: Installing Qcodo

The Qcodo Framework is released as a zip/tar.gz file, which includes all the PHP scripts and folders for the framework, itself.  To install, simply unzip the contents, and copy all the files from wwwroot to the docroot of your webserver.

If you want to install Qcodo within a subfolder of wwwroot, then you can do so.  But you will need to specify the name of this subfolder in the includes/prepend.inc file.  In prepend.inc, set the name of the subfolder in the Application::$SubFolder variable in that file.

You will note the following files and directories in the package:

File Listing

    README.txt (contains basic installation instructions)
    wwwroot/codegen
    wwwroot/codegen/index.php (a web front-end for the Code Generator)
    wwwroot/form_drafts
    wwwroot/form_drafts/index.php (a page that displays links to all generated Form Drafts)
    wwwroot/includes
    wwwroot/includes/qcodo
    wwwroot/includes/qcodo/... (the bulk of the framework resides in this folder)
    wwwroot/includes/qform/
    wwwroot/includes/qform/... (customized framework objects for the Qforms library reside here)
    wwwroot/includes/_configuration.inc (database connection information)
    wwwroot/includes/prepend.inc (to be included in all PHP scripts that wants to utilize the framework)
    wwwroot/index.php (a quick test to see if the framework is being properly included)

Step 2: Setting Up the Include Directory

Qcodo requires that the includes/ directory be part of the PHP include_path, so that PHP knows where to look for the framework objects/libraries.  There are several ways to do this.  The easiest and preferred method is by updating the php.ini file, so that includes/ is part of include_path:

php.ini snippet (example)

; An Example for Unix/Linux-based systems, e.g. with Apache
include_path = ".:/home/www/htdocs/includes"

; An Example for Windows-based systems, e.g. with IIS
include_path = ".;c:\inetpub\wwwroot\includes"

Of course, if you installed Qcodo within a subdirectory of wwwroot, be sure to specify the correct includes/ location in include_path, accounting for that subdirectory.

If you do not have access to the php.ini file, some webservers like Apache will allow you to make VirtualDirectory or Folder-based directives to setup the include_path parameter.  See the PHP website for more documentation on how to do this.

An Alternate to Step 2: Setting Up the Include Path Manually

If you absolutely cannot set the include_path parameter via configuration scripts, you can do so manually on the top of every webserver-run page which requires the framework.  While this sounds like a daunting task, there are actually only a few files that need to be updated.

A webserver-run page (as opposed to a PHP include file) is any file that ends with .php which needs the use of the framework.  This would include files like index.php, project_list.php, etc.

Currently, there should only be one webserver-run page, which is the web front-end to the code generator itself.  All the other ones will be eventually code-generated for you.

So what you need to do is update codegen/index.php so that one of the following four lines of code resides as the first line of code.  You will need to pick the correct line to use based on the configuration of your system:

(Again, if you installed Qcodo within a subdirectory of wwwroot, be sure to specify the correct includes/ location in include_path, accounting for that subdirectory.)

Alternate to using php.ini

// Used on Unix/Linux-based systems where PHP is run as a plugin or module
ini_set('include_path', '.:' . $_SERVER['DOCUMENT_ROOT'] . '/includes/');

// Used on Windows-based systems where PHP is run as a plugin or module
ini_set('include_path', '.:' . $_SERVER['DOCUMENT_ROOT'] . '\\includes\\');

// Used on Unix/Linux-based systems where PHP is run as a CGI
ini_set('include_path', '.:' . substr($_SERVER['SCRIPT_FILENAME'], 0, strlen($_SERVER['SCRIPT_FILENAME']) - strlen($_SERVER['SCRIPT_NAME'])) . '/includes/');

// Used on Windows-based systems where PHP is run as a CGI
ini_set('include_path', '.;' . substr($_SERVER['SCRIPT_FILENAME'], 0, strlen($_SERVER['SCRIPT_FILENAME']) - strlen($_SERVER['SCRIPT_NAME'])) . '\\includes\\');

The above line of code that you select for your system will utilize built-in PHP functionality to try and calculate what the actual docroot is.

Now, because the code generator will generate other webserver-run PHP scripts using templates, you will also need to update the following templates to ensure that when those PHP files are generated, it will also properly include the manual “ini_set” line.

template files that generate into webserver-run PHP pages

   /path/to/docroot/includes/qcodo/codegen/templates/object_edit_form_draft.tpl
    /path/to/docroot/includes/qcodo/codegen/templates/object_list_form_draft.tpl

Step 3: Including Qcodo

On each webserver-run PHP page, the way to include the framework is to simply have the following line of code reside at the very top (or as the second line if you performed the “Alternative to Step 2” above).

the include command

    require_once('prepend.inc');

Some developers enjoy using the auto_prepend_file functionality in PHP.  While this is not the preferred method for Qcodo, it will definitely still work.  Just be sure to remove any references to the “require_once” command both in codegen/index.php as well as the template files mentioned in “Alternative to Step 2” above.

Step 4: Properly Setting File/Folder Permissions

Because the code generator generates files in multiple locations, you want to be sure that the webserver process has permissions to write to the docroot.

The simplest way to do this is just to allow full access to the docroot for everyone.  While this is obviously not recommended for production environments, if you are reading this, I think it is safe to assume you are working in a development environment. =P

On Unix/Linux, simply run “chmod -R ugo+w” on your wwwroot folder, select “Properties”, go to the “Security” tab, Add a “Everyone” user, and specify that “Everyone” has “Full Control”.  Also, on the “general” tab, make sure that “Read-Only” is unchecked.  If asked, be sure to apply changes to this folder and all subfolders.

Testing it Out

Hopefully, you should be able to open a webbrowser to try and view http://localhost/ (or wherever your webserver is configured) to see the quick test page.

If there are any issues, or if for whatever reason a welcome page doesn't appear, please feel free to visit the Forums section of this website to see if members in the community can try and solve the issue.

Otherwise, you can move on to “A QuickStart Guide to the Qcodo Code Generator” to start playing with the database and code generation, or to “A QuickStart Guide to Qforms” to start playing with the Qforms platform.



Copyright © 2005 - 2019, Quasidea Development, LLC
This open-source framework for PHP is released under the terms of The MIT License.