version: #7 (current)  |  last edited by: rteqcodo  |  on: saturday, may 16, 2015, 2:24 am pdt (about 2 years ago)


Getting Started with Qcodo

Installing the Framework

You can download the framework from the Downloads section of the Qcodo.com website.  Qcodo is released with two different versions:

  • A .tar.gz “tarball”, which is primarily used in POSIX-based environments, including Unix, Linux, Mac OS X, and Cygwin
  • A .zip file, which is primarily used for Windows-based environments

You'll notice that the distribution has three top-level directories:

  • cli - the “command line interface” directory has the main qcodo and qcodo.bat CLI runner scripts (for POSIX- and Windows-based environments, respectively), and the scripts to execute the code generator, Qcodo updater tool, and the QPM package management tools.  Note that any custom scripts that you write can be placed here, as well, in the cli/scripts directory.
  • includes - this directory contains all the Qcodo class files as well as any other PHP include files which may be called on that do not need to reside in the web-accessible docroot
  • www - this is the directory that is “web-accessible”, containing all the top-level .php files, as well as any other web assets, including images, JavaScript files, CSS stylesheets, etc.

You can install the Qcodo Framework in a new web application, or you can install it to run alongside an existing web application...

If you are installing Qcodo as part of a new web application, the above folder structure is the one that Qcodo recommends, where you have your cli and includes directory at the same level as your “document root”, and the www directory is the document root, itself.  So for example on a Windows-based environment, assuming our docroot is currently at c:\xampp\htdocs, then this could be one way to set up our Qcodo-based folder structure:

c:\xampp\cli
c:\xampp\includes
c:\xampp\htdocs

Alternatively, if you are installing Qcodo as part of an existing web application, then you can make www a subfolder within your existing docroot, or you can simply move the subdirectories in www into your docroot.  Then, be sure and place the cli and includes directory in the same level as your docroot.  So for example on a sample POSIX-based environment, assuming our docroot is currently at /var/www/vhosts/www.mysite.com/htdocs, then this could be one way to set up our Qcodo-based folder structure:

/var/www/vhosts/www.mysite.com/cli
/var/www/vhosts/www.mysite.com/includes
/var/www/vhosts/www.mysite.com/htdocs

Copy-Creating the Configuration Files

As of Qcodo 0.4.1, there are four configuration files that must be created.  Fortunately, the Qcodo distribution comes with distribution-based versions of the file which you can use to copy as a way to create them (similar to how PHP comes with php.ini-dist as the “default” version of your php.ini file):

  • cli/settings/codegen.xml-dist
  • cli/settings/qpm.xml-dist
  • includes/qcodo/_core/QApplication.class.php-dist
  • includes/qcodo/_core/configuration.inc.php-dist

Note that configuration.inc.php actually comes with a “-full” version of the file as well.  The “-dist” version is what is generally recommended that you use.  However, note that the “-full” version is the exact same code, except it has significantly more inline comments.  These inline comments can be very useful in explaining what each configuration constant and setting is... however, it does add a considerable amount of “clutter” to the code, itself, which is why Qcodo recommends that you use the “-dist” version.

The codegen's CLI XML settings file should be copied to the cli/settings directory, while the other two QApplication.class.php and configuration.inc.php files should be copied to the includes/ directory.  So for example on a sample POSIX-based environment, you would run the following commands:

$ cd /var/www/vhosts/www.mysite.com
$ cp cli/settings/codegen.xml-dist cli/settings/codegen.xml
$ cp cli/settings/qpm.xml-dist cli/settings/qpm.xml
$ cp includes/qcodo/_core/QApplication.class.php-dist includes/QApplication.class.php
$ cp includes/qcodo/_core/configuration.inc.php-dist includes/configuration.inc.php

Update the Configuration file

Finally, you should update the includes/configuration.inc.php file to reflect the settings of your system.  First and foremost, you will want to make sure the _DOCROOT_ constant is set up correctly.  The value of the _DOCROOT_ constant should be the directory of your www/ directory, depending on how you set up your directory structure above.

Test the Installation

You should be able to go to your browser and browse to the root /index.php (e.g. by going to http://localhost/index.php or http://www.mysite.com/index.php depending on how you have your apache, server and/or hosts file set up).  You should see a simple web page that says:

Qcodo Development Framework
Start Page

It worked!

If you are seeing this, then it means that the framework has been successfully installed.

If so, then your installation appears to be working correctly.

Testing the CLI Tools

A lot of the powerful features of Qcodo reside within the Command Line Interface (CLI) infrastructure of Qcodo.  It is a good idea to test it out to make sure it is working properly.  This can be done using a terminal/shell (for Linux/Unix folks), Terminal.app (for Mac OS X folks) or the Windows Command prompt / cmd.exe (for Windows folks).

For Unix, Linux and Mac OS X (continuing with example folder directory structure used above):

$ cd /var/www/vhosts/www.mysite.com
$ cli/qcodo

For Windows (again, continuing with example folder directory structure used above):

> cd c:\xampp
> cli\qcodo.bat

If it is working properly, you should see the default output from the Qcodo CLI Runner script.

Qcodo CLI Runner v0.4.16
usage: qcodo SCRIPT [SCRIPT-SPECIFIC ARGS]

required parameters:
  SCRIPT         the .cli.php script name inside the cli/scripts directory
                 that you wish to run

the following SCRIPTs are included with the Qcodo distribution:
  codegen        Code generates your ORM-layer
  qcodo-updater  Updates your installed Qcodo framework to a new version
  qpm-download   Download and installs an external QPM package
  qpm-upload     Packages custom code you wrote into a QPM package

Other custom scripts can be created as well.
See "/var/www/vhosts/www.mysite.com/cli/scripts/_README.txt" for more info

To run any other script, you can simply run the qcodo or qcodo.bat script as above, and pass in the name of the script you wish to run.

Using qpm-download to Download the Examples Site QPM Package

So for example, if you want to download the entire Examples Site QPM Package, you can simply run either of the following commands:

$ cli/qcodo qpm-download -l -f mikeho/qcodo_examples

or for Windows folks...
> cli\qcodo.bat qpm-download -l -f mikeho/qcodo_examples

Using codegen to Run the Code Generator

As another example, if you are ready to run codegen against your database, then you can simply run either of the following commands:

$ cli/qcodo codegen

or for Windows folks...
> cli\qcodo.bat codegen

Reminder to Read _README.txt file.

After downloading and extracting the files into your websites root directory, be sure to read the included _README.txt file. It contains updated information.



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