• log out

How Qbix code gets included

Your apps typically contain PHP and Node.js scripts that will include Qbix as a library. This is done by simply requiring Q.inc.php in PHP or Q.inc.js in JS. These files are found in the Q_DIR/scripts directory, but your apps have their own versions in the scripts and web directories.

The MyApp and SmartApp templates already come with web/index.php and web/action.php which serve as the entry points for lots of requests from the web, and they include Q.inc.php .

Cascading File System

When Qbix bootstraps itself, it sets up the include path so that include or require a relative filename will try directories in the following order:

  1. Your app's directory, stored as APP_DIR
  2. All the plugins in the app, from most recently loaded to least recently loaded, stored as {$X}_PLUGIN_DIR
  3. Qbix platform's directory, stored as Q_DIR

Because of this, you can easily override a file in the framework (such as Q_DIR/handlers/foo/bar.php) by placing a file at the corresponding path in a plugin or an app (e.g. APP_DIR/handlers/foo/bar.php).

Local directory

Whether you are working with a team or not, you will probably want to use version control software to keep backups of your project.

Qbix recognizes that some things are specific to your local development environment, and should not be checked into version control. This includes things like absolute pathnames, database credentials, and API keys. For this purpose, Qbix apps have the APP_DIR/local directory.

You can add the APP_DIR/local.sample directory to version control, and it will serve as a template that you will have to modify on each machine where you install the app. In this way, your app is like every other portable PHP application.

Various directories

Besides the local directory, your Qbix app will typically contain the following directories:

  • web: The web server's document root. Anything here is usually publicly readable/executable.
  • files: This is where the app will dynamically save any files it needs, so it should have write permissions in this directory.
  • classes: PHP classes that can be autoloaded and follow standard naming conventions. Also Node.js files that can be loaded with Q.require('Module/filepath.js')
  • handlers: PHP and Node.js functions to handle Qbix events, autoloaded and named according to a standard convention.
  • scripts: Stores standard Qbix scripts, sql update scripts, long-running Node.js services, etc.
  • views: Stores various templates and layouts
  • config: Plugins and apps place their configuration files in this directory

By convention, files in almost all the above directories are namespaced. For example, the First app would store all its files under files/First/ and all its classes under classes/First/. Plugins especially should save files under their own namespace, so they can coexist peacefully with one another.

Plugins

Plugins are essentially packages of functionality for apps and other plugins to re-use. They are added to Qbix as directories under Q_DIR/Q/plugins. Qbix ships with at least two plugins out of the box: Users and Streams, but developers can create their own and share them between projects.

The directory structure of plugins is identical to that of an app. The app simply indicates the plugins it wishes to use in the Q/Q/plugins config array, and they are loaded in that order by the bootstrap. The file cascade does the rest.

Plugins come with a config file just like apps do, which is named PLUGIN_DIR/config/plugin.json and contains JSON for any config the plugin might need. Here is an example: 

{
  "Q": {
    "pluginInfo": {
      "Fancy": {
        "version": "0.3", 
        "compatible": "0.1",
        "requires": {
          "Q": "0.8", 
          "Users": "0.8"
         },
        "connections": ["DbConn1", "DbConn2"]
      }
    }
  },
  "Fancy": {
    "something": {
	  "here": 2
    }
  }
}

The "Q/pluginInfo" section says the current version is 0.3, but it's still compatible with 0.1 (in case the app requires version 0.1 of this plugin for instance). The connections refer to the database connections this plugin uses.

Installer

An app's config file typically has a config file that begins like this: 

{
"Q": {
  "app": "First",
  "appInfo" : {
    "version" : "0.5",
    "compatible": "0.1",
    "requires": {
      "Q": "0.8",
      "Users": "0.8",
      "Streams": "0.8"
    }
    "connections": ["First"]
  },
  "plugins": ["Users", "Streams"],
}

The "appInfo" section tells the installer what plugins need to be installed for this app to work. The database connections stored in each "appInfo" and "pluginInfo" are used to determine where to store the version information for those apps or plugins. If your app or plugin makes use of a certain database connection, you must list it there.

The install script is APP_DIR/scripts/Q/install.php and it's smart enough to keep track of all the versions and execute the right scripts to update the plugins and apps as needed.