App Includes - Including your own files easily in QCubed

A framework is goddamn useless. You know that right? Well, the framework provides you facilities. It is you who should actually use the features provided by the framework to create your application; and in that process sir, you are going to create more files. Of those files, there would be some files whose whole purpose is to be included elsewhere and such files are usually called as 'includes'. As such, the QCubed framework itself is contained in the includes directory of the installation.

However, it is not just the framework that you are going to need. With time, you will create your own files for being included in other pages of your application. The one thing that comes to my mind when I think of including new files is "Controls". You might just want to create a control which you would be using again and again on various pages. Now, there might be a dozen pages where you would want to include that file. So what do you do? What if there are a dozen such controls and other classes? Do a 'include_once' at all places in the code? Nah! With QCubed, you just need to use the app-includes feature which allows you to easily do all this!

Autoloading and the Include file problem

Basically, including too many files makes a script slow. So PHP has this little facility called autoloading. You write a function which stores the name of classes and the files which contain them and allows to search a filename based on the class. Then you use all those classes freely across the script without including those files manually. PHP will include files on the fly as and when they are required! That keeps everything real fast. QCubed utilizes this same technique so that you can use the features of entire framework without needing an extra file include. However, this is not as easy with your custom made classes and include files that contain them. You create a directory somewhere and then include the files again and again wherever they are needed using the path. This not only makes your page slow under certain cases, but also brings in a lot of headache for you! The simple reason is: if you want to change the path of a file containing a particular class (and believe me, as your application will grow, you will want to do that), you gotta change the path each and everywhere you included that. So you cannot move them around or rename them either!

How QCubed solves this - using App-Includes

So before I tell you how to make it all simple using app-includes, I will tell you the way QCubed works internally (I hope that would save time for you). In case you are not interested in knowing this, skip this para, it wont do you no harm. So the way QCubed works is - you include a file called qcubed.inc.php in all your scripts where you want to use the features of QCubed framework. This file is located inside the root of the installation. When you include this file, QCubed registers all the files containing all of its own classes and the classes generated during the codegen process and makes sure that database operations can be called in anytime from the code that you are going to write. Once it is done, the control comes into your script where you are supposed to include anything else you want!

However, since the 2.1 release, we have added a new directory (folder) which you should use to place your own include files. This folder is called app_includes and is placed inside the includes folder itself. This directory is all yours sir, you are free to keep all your include files organized here, the way you want them. The way you use this feature is simple - you create a folder inside app_includes directory (let us say you created one with the name MyControls) and inside that, you create a file and create a class inside that. Let us assume that the file you created is called PersonDetailsControl.class.php and the class that you created in that is called PersonDetails. Now, you should go to the app_includes directory and open the file app_includes.inc.php. In there you would get examples of how to include your class into QCubed for autoloading. You should read the instructions in the file. However, for our case the line that you should include is:

QApplicationBase::$ClassFile['persondetails'] = __APP_INCLUDES__ . '/MyControls/PersonDetailsControl.class.php';

Do notice that we are writing the key name for the QApplicationBase::$ClassFile array same as the class name in all lower characters and the path to the file as it is. It is also worth being kept in mind that the app_includes directory itself is referred to as __APP_INCLUDES__ and you should use that name. This facilitates you to move your entire app_includes directory anywhere you want without changing anything but one variable in configuration.inc.php file!

Now, you do not need to include the PersonDetailsControl.class.php file in your pages. When you include 'qcubed.inc.php' file, your file is registered for autoloading and the class becomes available in all scripts automatically. Now you can move the file around at any and all places you want and rename it as you wish and the only change you have to make is in the app_includes.inc.php file - updating the path of the new file where the class is kept! Easy right?

How does it work?

The way it works is simple - When you include qcubed.inc.php, it also includes app_includes.inc.php automatically and thus registers the classes with their filenames so they become available for autoloading. To go a little deeper, the QApplicationBase::$ClassFile array is the one array which contains the class names in all lower characters as the key and the paths as the values.

Other benefits out of app_includes

Since app_includes.inc.php is run every time, you can include any files you want to include at all times (for example, a file which contains the code to increment a 'view-counter' in the database). It is however recommended that you always use app_includes.inc.php to only include files which you want to get executed and never write any code in the file. This is not a mandate but is just for your own convenience. You can include any files which contain functions which you do not want to write into a class for some reason, or just include a file which contains a set of your own named constants (the ones created using 'define' function call) so that they can be used all throughout your application. After this, you hardly need to touch any framework core files (as they are not really supposed to be changed and contain 'temporary workarounds').

The fact be said, the way it is written is that it even allows you to copy a core file and place it in your own folder inside app_includes directory and include its path in the app_includes.inc.php file and the file you have created will take effect instead of the one in the core (the one exception to this is QApplicationBase.class.php)! So you can do all your worksrounds while being sure that the core remains untouched and an accidental update to the core framework will not overwrite your modifications!