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
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:
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:
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):
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
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
For Windows (again, continuing with example folder directory structure used above):
> cd c:\xampp
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]
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.