Joomla Discussion
The Joomla 3.x Execution Cycle
When Joomla starts up it goes through a process to boot strap itself, gathers information it needs and classes it has to have to run. After getting its house in order at some point Joomla will execute the code for modules, plugins and components. The output of these extensions are held in a buffer until the data is needed. After running these, it back fills the data into the template which is also stored in a buffer. When finally all the processing is complete and the data gathered and assembled into the template, it is then sent to the end user as a webpage. This document discusses the process that Joomla goes through each time a page is brought up.
When we go the to front end with the URL, http://www.joom.dev, the web server sees that no specific page was passed to it to return to the calling browser. Since no specific page was requested, it looks at a list of pages that it would send in the absence of a specific request. The list of pages and the order that it will send them all depends on how the web server is set up and configured. In our case, the web server will send the index.php file located in the root of our web folder. Recall, that this is the “Site” application for Joomla. So with the index.php script loaded, let’s try to get an overview of what is happening.
The code listed below the paragraphs is part of the ‘site’ applications index.php file. Hopefully, the paragraph will adequately explain what is happening.
Joomla first defines the minimum version of PHP in which it will run. Then compares this defined version against the version of PHP that is actually installed on the server. If the servers version of PHP is less than the required version, then Joomla bails out with an error indicating that the server does not meet the minimum requirements for joomla to run.
/**
* Define the application's minimum supported PHP version as a constant so it can be referenced within the application.
*/
define('JOOMLA_MINIMUM_PHP', '5.3.10');
if (version_compare(PHP_VERSION, JOOMLA_MINIMUM_PHP, '<'))
{
die('Your host needs to use PHP ' . JOOMLA_MINIMUM_PHP . ' or higher to run this version of Joomla!');
}
Next Joomla grabs the start time and memory usage. This is used in profiling the script if debugging has been turned on.
// Saves the start time and memory usage.
$startTime = microtime(1);
$startMem = memory_get_usage();
Joomla then defines the _JEXEC constant. This constant is used in every page that joomla loads and executes. This is a safety feature the prevents a script from being run outside the joomla environment.
/**
* Constant that is checked in included files to prevent direct access.
* define() is used in the installation folder rather than "const" to not error for PHP 5.2 and lower
*/
define('_JEXEC', 1);
Next Joomla looks to see if a defines.php file exists in the current directory, if it does it will load the file. Under normal circumstances your install will not contain this file. It would be used if you were interested in moving the files from your default locations to somewhere else.
if (file_exists(__DIR__ . '/defines.php'))
{
include_once __DIR__ . '/defines.php';
}
Now we get to the start of the magic. Joomla loads the defines.php file located in the includes folder. This file defines a set of constants that point to the locations of files it needs to have in order to work. For example, it sets up a constant that points to the libraries folder so that it can find the library files.
if (!defined('_JDEFINES'))
{
define('JPATH_BASE', __DIR__);
require_once JPATH_BASE . '/includes/defines.php';
}
After the defines are loaded then Joomla loads the framework.php file from the includes folder. The framework.php file registers the classes Joomla needs to run using the JLoader class. Next, framwork.php sets some error handling, then checks to see if a configuration file exists. If it does not it will launch the installation application. In the event that the installation program does not exist, Joomla will throw an error and stop running. Framwork.php will then set the php error level reporting to what has been saved in the configuration file.
require_once JPATH_BASE . '/includes/framework.php';
If debug has been turned on, Joomla will start the profiler marking the start time and memory usage, marking it ‘afterload’.
// Set profiler start time and memory usage and mark afterLoad in the profiler.
JDEBUG ? $_PROFILER->setStart($startTime, $startMem)->mark('afterLoad') : null;
With the framework loaded, the index.php file will instantiate the site application, when the application has been created then index.php will execute the site application.
// Instantiate the application.
$app = JFactory::getApplication('site');
// Execute the application.
$app->execute();
That was a quick rundown of how Joomla starts up, but it would be helpful to know more about it. So lets take a look at what happens when joomla creates a site application object.
The Site Application
Joomla creates the Site Application with a call to JFactory::getApplication('site') from the index.php file.
JFactory looks to see if the application has already been created, and if not will instantiate a new application using the JApplicationCms::getInstance($id) static method call. This application object is stored in JFactory in the event it is needed again in a later script. This is a singleton pattern and prevents multiple application objects from being created. Finally, JFactory returns the application object to the caller. In our index.php file this is assigned to a variable called $app. Just as a side note, in this case, the parameter $id being passed in the JApplicationCms::getInstance($id) would contain the value of ‘site’.
When the JApplicationCms::getInstance($id) method executes, it will create a class name composing of JApplication and concatenate to it the $id parameter passed to it. In our case it turns out to be JApplicationSite. Once the classname is determined, the method will create an instance of this class, JApplicationSite, store it and then return a copy to the caller, JFactory::getApplication('site').
When the JapplicationSite object is created, all the associated objects and properties that are needed to define what a site application is, are created and populated. This would include the Input (POST and GET variables for example), configuration, the system URI, etcetera.The code below is the getApplication() method of the JFactory class.
public static function getApplication($id = null, array $config = array(), $prefix = 'J')
{
if (!self::$application)
{
if (!$id)
{
throw new Exception('Application Instantiation Error', 500);
}
self::$application = JApplicationCms::getInstance($id);
}
return self::$application;
}
To sum up so far, the index.php file does the following
- Loads the includes and classes needed to run
-
Get’s an instance of the application, JapplicationSite
With the site application object created, the index.php file calls the execute() method of the object to finally start running the application with the line $app->execute().
Executing the Application
Recall from above that $app is a JApplicationSite object. Many of JApplicationSite methods and properties are inherited from the its parent classes above it. Rather than getting caught up in the weeds of the code with how and what gets executed, I will instead outline what is happening as the code runs.
To start, the application is initialized with the following call.
$this->initialiseApp();
Initializing the application will do the following:
- Gets the User
- Loads language strings for translation
- Sets the configuration of the API
- Gets the user’s editor
After the application is initialized a call is made to route the application with the code:
$this->route();
When the application’s route method is called, the following happens:
- Gets a copy of the JURI object (The URI broken down into individual components uri, scheme, host, port, user, pass, path, query, fragment and vars)
- Gets the JRouterSite (router class)
- Parses the URI (gets the query variables, option, Itemid, View etc) It should be noted that if a component was not supplied in the URL, that Joomla will set the component to whatever is set to the HOME link. If you have made no changes to Joomla, this will end up being the com_content component with the view set to featured.
With the routing completed, the application is dispatched with the following code.
$this->dispatch();
The dispatch method does the lions share of the work to get the application ready for the end user. When this method runs the following happens:
- Gets the component name from the parsed URL (component will be the option variable if it is set for example com_content. Otherwise it returns null)
- Gets a copy of the document
- Gets a copy of the Router
- Gets the component parameters
- Sets the metadata in the document if an html document
- Gets the template if an html document
- Sets the document title and description
- Sets the generator to Joomla
- runs the component
- Stores the output of the component to the $document component buffer
- loads and triggers system plugins
With the above completed and the main component having been run and sitting in the component buffer, the application can be rendered. It is done with the following call.
$this->render();
When the document is rendered, the following things happen:
- Gets the template
- Calls the document->parse()1 method
- Loads system plugins and executes onBeforeRender event.
- Caches the page if caching is turned on
1The parse() method looks at the template, fills in the component and runs the modules that are assigned to the positions available if they are set to show in the current menu link.
If compression has been enabled, then the application will be compressed with a call to
$this->compress();
With all the document rendering complete, Joomla can finally send the application output to the end user. This is done with the following method call.
$this->respond();
This method does the following:
- Sets the document headers
- Sends the headers
- Sends the document
What to take away from all this?
Joomla does a lot of work to send information to the end user, but having a bird’s eye view of what Joomla does to perform this will give you respect for all the work that has went into creating the platform and give you a good understanding of how your extension gets processed and rendered by Joomla. Although knowing this stuff isn’t strictly necessary to write extensions for Joomla it does help to know where your extension fits in the process of things.
END OF TUTORIAL
A Walk in the Weeds
Yeah, I know, not very creative but let's face it, there are a lot of things that should be known about joomla. This section discusses some of things to know like what the file structure means, and how does the Joomla execution cycle work and probably a bunch more to besides that.
The Joomla 3.x File System layout.
I discuss the file system layout that Joomla uses. Although not mandatory, knowing how Joomla uses the file system when it runs make writing extensions a little more clear. Also I discuss the three applications that Joomla is packaged with. The "site", "administrator" and "install" applications.
The Joomla 3.x Execution Cycle
We explore Joomla's execution cycle. It covers loading the framework, building the application document, where the component gets run, loading the template, running the modules and finally sending the finished document to the uiser.
The Joomla 3.x File System Layout
When Joomla is first unzipped to the root folder of the web server for installation quite a number of files and folders are created. Understanding what these files and folders are will aid you in the long run when you start to develop extensions for the Joomla CMS.
The first thing to understand about Joomla, is that it consists of three applications. There is the “site” application, which is what your users see. For example, when you type http://www.joom.dev in your browser, Joomla is serving the “site” application. The “site” applications files and folders reside in the root of your web folder. Next there is the “administrator” application. This is what Joomla runs when you are in the backend, creating content, menus, categories, etc when your browser is pointed to http://www.joom.dev/administrator. The “administrator” application files and folders are all located under the administrator folder within in your web sites root web folder. Lastly, there is the “Installation” application. This application runs the very first time you access your Joomla site. It's job is to set up the environment for your Joomla install, including things like the site name, description, the database server and credentials, installing sample data and other things. Unlike the site and administrator applications, the install application needs to be deleted or disabled by some other means after is completes its job before Joomla will allow you to run the site and administrator applications.
The image to the left shows the files and folders created when you first extract the Joomla archive to your computer. Understanding what these files and folders are, is key to getting a grip on how the Joomla CMS and the extensions for it work. As I progress through the series, this will be talked about in more depth but for now it would be a good idea to cover the basics. Below is a short description of the folder or file listed in the image to the left.
administrator: This folder and all the folders and files it contains run the administrator application. We will come back to this in a little bit.
bin: The bin folder holds the keychain class and is used by Joomla when there is a need to load or store data to an encrypted data source.
cache: The cache folder holds cached modules, pages and views that do not change frequently. By caching a module, page or view it saves Joomla some processing time because it does not have to generate these again and as a result will serve the page a little faster.
cli: The cli folder holds scripts that would interact with Joomla or its database but would not be run from the web browser. For example, if we had a turn based game component, a file in the cli folder would be run with cron periodically to update the game turns. This is where you would want to store any scripts that need to modify the data of one of your extensions outside the normal Joomla web interface.
components: The components folder is home to all the site application's components. In a default install of Joomla, this is where the content, contacts and other components are stored. There will be much more to learn about the component hierarchy when we start writing components for Joomla.
images: The images folder is where assets for your web pages and extensions are stored. These would be images and assets the user has uploaded to the web server, or possibly assets that belong to an extension you have written but are intended to be changed or modified. I say this, because there is another place that is used in addition to store assets for your extension.
includes: The includes folder contains bootstrap code that starts Joomla. The application's index.php files uses the files in this folder to create the constants needed to find things like libraries, plugins and templates. Included in this folder is the bootstrap for the framework. The framework will load the necessary files to start Joomla and then check for and import the configuration, etc.
installation: This folder and the contents under it hold the installation application. The installation application is responsible for setting up the environment and other details about your Joomla install. The installation application is typically ran one time and is removed from the website after it has run.
language: Joomla is designed to be a multi-lingual CMS. It is in this folder that the site application stores the language files for the Joomla CMS and any components or modules that run. A folder exists below this folder for each language you want to use in Joomla. Unless you have installed additional language packs there should be one folder under the language folder with the name of the language you selected at the time you install Joomla. As you will learn later when we start to develop extensions, there are other locations that language files can be stored.
layouts: Joomla allows you to override layouts. Sometimes you want the same layout for different extensions. Joomla allows this by allowing you to group layouts together. Joomla groups it common layouts together in this folder. You can use these in your own extensions or you can even override these layouts. More on this topic when we get into extension development.
libraries: This folder contains all the library classes and code that Joomla uses to run. You can also install you own libraries here making them available to other extensions.
logs: This folder contains any logs that Joomla may write. Additionally, you can use this folder when logging information with your component using JLog.
media: This folder holds assets related to extensions and the Joomla system. For example, in this folder you would store images, css, javascript or other assets that your extension would use but would never be modified under normal circumstances. It differs from the images folder in that respect. The images folder could hold assets for your extension, but these are likely to be changed over time. More will be discussed on this folder when we start developing extensions.
modules: This folder hold the module extensions for the site application or frontend. Each module installed in Joomla will reside in a folder under this folder. More will be discussed about this folder when we start developing modules for Joomla.
Plugins: This folder hold the plugin extensions for the site application or frontend. Each plugin installed in Joomla will reside in a folder under this folder. More will be discussed about this folder when we start developing plugins for Joomla.
templates: Templates are another type of extension that can be written for Joomla. Templates define the overall look and feel for the website. Each template installed in Joomla will reside in a folder under the templates folder. We will cover more about this when we discuss templates and layout overrides.
tmp: The tmp folder hold files and data that are in temporary use. For example, when you upload a component or other extension to Joomla, that file is usually a zipped archive. Joomla will extract the archive in the tmp folder to do the installation process.
htaccess.txt: This is a sample htaccess file that you can use if you are using a server that runs Apache web server. This file is used to control how Apache handles some things. For example, if you were to use Joomla friendly URL encoding you would use this file to control the rewriting of the URLs.
index.php: This is the file that loads when Joomla is called on the Frontend. It is responsible for creating and running the site application that was discussed above.
LICENSE.txt: This file holds the text of the GPL License that Joomla is released under. If you have never read the GPL License, you should take the time to read it at least once.
README.txt: This is Joomla's main readme file. It explains what Joomla is, how to get updates, how to get involved and some other stuff. It is a small file and you should take the time to read it through.
robots.txt.dist: This file is a sample robots.txt file to use on your site to prevent search engines from indexing your site folders. Robots will still be allowed to index your site content, but there is no reason for them to index the files and folders that make up your website. If allowed to do so, then there is a chance that a hacker would be given sensitive information that may assist them in hacking you. The comment in the top of the file explains how it is used.
web.config.txt: This file is like the htaccess file discussed above, but is used for MS IIS.
That concludes the list of the files and folders that are included on the site application install. These folders and files are used in the context of the sites Frontend with exception of the administrator and installation folders. Since this series of tutorials does not cover the installation application no detail discussion of its folders and files will be mentioned. However, because extensions that are written for Joomla cover both the site and administrator applications, a discussion on the files and folders in the administrator folder will follow.
The image to the left shows the files and folders that are created under the administrator folder when Joomla was extracted. Below is a list of them and what they mean.
cache: Just like the Frontend or site application, this is where Joomla will store cached content to save processing time making the site a little faster.
components: This folder holds all the components that are installed on the Backend or administrator application. Each installed component will have its own folder located under this folder.
help: This folder holds the files for the web locations of the help system built into Joomla.
includes: Like the Frontend, the includes folder has files and defines that help start the administrator application.
language: This is where the laguage file are stored for the Joomla CMS as well and extensions. When we start to develop extensions we will discover that there are other places that language files can be stored.
manifests: The manifest folder holds the xml manifest files for files, libraries and packages installed for the core Joomla CMS. Manifest files as you will learn hold all the information Joomla requires to install, upgrade and remove software from the Joomla framework. We will be discussing manifest files in detail when we start developing extensions for Joomla.
modules: Just like the Frontend, the Backend (administator application) can have modules installed. Modules for the Backend are stored under this folder.
templates: Just as the Frontend can have template defining the look and feel the end user gets, so does the Backend. Templates are stored in folders under this one for the Backend.
index.php: When the Backend application is started by going to http://www.joom.dev/administrator this is the file that gets launched. It is responsible for setting up the application and launching it.
That pretty much sums up the files and folders that are created when you install Joomla. I know that I didn't go into great detail about some of them, but we will learn their use and naming conventions as we go through the process of learning to develop extensions for Joomla. Thank you for your participation.
ALL DONE!!!