From the Rough Cut
From the Rough Cut
From the Rough Cut
Let's Ask Louis: Including PHP Files
|
Mark: |
Louis, I am confused about the way in which other PHP files get executed or included. I mean, we start with our one "index.php" file, and the next thing you know, we are running a whole bunch of other files. What's the deal? |
|
Louis: |
The ability to include other files is a really cool feature of PHP. It let's us keep our files relatively small and focused on one task and then put them together as needed. I mean, we could have the entire Joomla application be one giant script file, but how easy would that be to read? |
|
M: |
OK, you have me there. I guess a bunch of small files makes things easier to understand and maintain. But I still don't understand something about the way this is done. If you look at the code, we use at least four different commands to include files. I've seen "include_once", "require_once", "jimport", and "require". Don't they all basically do the same thing and just execute the PHP file? |
|
L: |
Yes and no. I mean, they all execute the named PHP file. But they have important differences. For example, "include_once" will not halt the execution of the program if the file is not found, whereas "require_once" will. "jimport" is used when the files being included use our Joomla library naming conventions. This command does some other cool Joomla-specific stuff along the way, like checking for helper class names. So there are generally good reasons to use the different commands. The "include_once" and "require_once" commands don't load the same file twice. This is really important if your file contains a class declaration and might already have been included. If you try to run a class declaration a second time, you will get a PHP error. On the other hand, with these commands, PHP has to check to see if the file has already been included. On some systems – especially large severs that use storage array networks (SAN's), this can really slow down the performance of Joomla. |
|
M: |
So, when I'm writing my own extensions, how do I know which command to use? |
|
L: |
I'm really glad you asked. We really should not be using "require_once" or "include_once" anywhere in Joomla, since they are very slow on some platforms. It turns out that it is much faster if we just keep track of the classes that are loaded in the application instead of asking PHP to keep track of the files that have been loaded. Most of the time when we are including other files, we are actually loading classes. And we already have a great method for including class files in the file "libraries/loader.php", called JLoader::register. The cool thing about this method is that it uses the PHP "autoloader" feature to load classes into memory only when they are needed. So this method just adds the class file to the list of files that PHP can load automatically if they are called. However, if it turns out we don't need that file, it doesn't get loaded into memory. This method for loading classes is much faster than using "require_once", at least on some hardware platforms. |
|
M: |
OK, big shot. A lot of the Joomla PHP files are just class declarations and don't actually do anything when you do a "jimport", "require_once", or "include_once" command. What's that all about? |
|
L: |
As you know, with PHP you can write procedural scripts or you can write files that create classes. If a file only contains a class declaration (meaning it declares a class with fields and methods), then no code is actually executed when that file is included. The code is only executed when you create an object of that type or execute on of the methods of the class. That's why the JLoader::register() method is great. Because, with that method, it doesn't even use memory to include a class file unless you actually use it. If we really wanted to, we could even automatically register every class in Joomla with this method during the initialization routine and then all of the core classes would be available without any further work. |
Figure 22: Ask Louis: Including PHP Files (Editor's question: Would it be fun to have some small head shot photos of Mark and Louis with funny expressions for the Let's Ask Louis sections?)
Load the Joomla Framework
The next line of code, shown below, loads the Joomla framework via the "includes/framework.php" file.
|
require_once JPATH_BASE.DS.'includes'.DS.'framework.php'; |
Figure 23: Including the Joomla Framework
The "framework.php" file does some important tasks. It loads the file "libraries/joomla/import.php", which in turn loads some very important classes, including "JFactory" ("libraries/joomla/factory.php").
It makes sure we have a "configuration.php" file. If we don't have one, it forces us to the "installation" application to try to install Joomla. If the installation files cannot be found, it shows an error message and quits.
Finally, it imports the framework classes. This is done in these lines of code:
// // Joomla library imports. // jimport('joomla.application.menu');jimport('joomla.user.user');jimport('joomla.environment.uri');jimport('joomla.html.html');jimport('joomla.utilities.utility');jimport('joomla.event.event');jimport('joomla.event.dispatcher');jimport('joomla.language.language');jimport('joomla.utilities.string');
|
Figure 24: Importing the Joomla Framework Classes
Note that the "libraries/joomla/import" file was already executed earlier in the "framework.php" file. This script loaded the "JLoader" class, which in turn provides the "jimport" method. So we can then use the "jimport" method to import the other framework classes.
Recall from the earlier discussion about command cycles that each command cycle has to entirely stand alone. That is why we have to load all of these classes into memory for each cycle.
Whew! At this point, it seems like we have done a lot, but we are just getting started. The real Joomla work can start now that we have the framework loaded.
Start or Continue the Session
If we return to "index.php", the next lines we see are shown below:
// Mark afterLoad in the profiler. JDEBUG ? $_PROFILER->mark('afterLoad') : null;
// Instantiate the application. $app = JFactory::getApplication('site');
// Initialise the application. $app->initialise(); // Mark afterIntialise in the profiler. JDEBUG ? $_PROFILER->mark('afterInitialise') : null;
|
Figure 25: Index.php "getApplication" and "initialise"
We can ignore the two JDEBUG statements. In normal operation, these are skipped. They are used to help evaluate the performance of different parts of the code.
So, the two things we do in this section are create the application object ($app) and then execute its "initialise()" method. (Note that we use the British spelling for the word "initialise", since that is the official language of Joomla.)
When we create the application object, we end up loading the JSite class from the file "includes/application.php". This class extends the JApplication class. A similar "JAdministrator" class in "administrator/includes/application.php" is used when you create a back-end application object.
At this point, we get our session. We either load the existing session or create a new one if one isn't found. Recall that Joomla doesn't know anything about what has happened in prior command cycles except for what has been saved in the session or the database. So finding the existing session is critical to carrying over information from one cycle to the next.
At this point, we also load the "configuration.php" file, which gives us access to the Joomla database and other settings for this specific web site.
Another small but helpful thing that happens here is to create a field called "requestTime". This is a time stamp field in the JApplication class that contains the date and time in GMT that the request cycle was started. If you need a current time stamp field, this is a simple way to get it ($app->requestTime or JFactory::getApplication()->requestTime). Unlike using the now() method, this value will stay constant during this command cycle.
Next, we run the "initialise()" method for the application. Since we are in the JSite class, we are running the the method from the "includes/application.php" file. The most important thing this method does is to figure out which language the user needs and loads this language object so that the text strings can be translated correctly. Near the end of the method, it also calls the parent's initialise method ("parent::initialise($options);). This calls the "initialise()" method from the "JApplication" class in the file "libraries/joomla/application/application.php", which figures out which editor is the right one for this user.
Route the URL
The next section of code in the "index.php" file is as follows:
// Route the application. $app->route(); // Mark afterRoute in the profiler. JDEBUG ? $_PROFILER->mark('afterRoute') : null;
|
Figure 26: Application "route()" Method
In Joomla jargon, a router is a class that translates between a URL and an array of commands. A router has two public methods, "parse()" and "build()". The "parse()" method takes a "JURI" object as input and returns an array of commands. The "build()" method reverses the process and takes an array of commands and turns it into a JURI object.
Let's see how this works in more detail. Recall that "$app" is a "JSite" object. Looking at the "route()" method for "JSite" ("includes/application.app"), we see the following:
public function route() {parent::route(); $Itemid = JRequest::getInt('Itemid');$this->authorise($Itemid); } |
Figure 27: JSite "route()" Method
Recall that "JSite" extends "JApplication" ("libraries/joomla/application/application.php"). "JApplication" also has a "route()" method. So the "route()" method in "JSite" overrides the one in "JApplication".
The first thing this does is call the route method of the parent ("JApplication"), with the command "parent::route();". If we look at this method (the "route()" method in "JApplication"), we see the following code:
public function route() {// Get the full request URI. $uri = clone JURI::getInstance(); $router = $this->getRouter(); $result = $router->parse($uri); JRequest::set($result, 'get', false); // Trigger the onAfterRoute event. JPluginHelper::importPlugin('system'); $this->triggerEvent('onAfterRoute');
} |
Figure 28: JApplication route() Method
This code gets the current "JURI" object. The clone command tells the system to make a copy of the "JURI" object instead of using the original one. This is done because we don't want to inadvertently modify the actual request URI when we are working with the "JURI" object. By making a clone of it, we can work with the clone, and perhaps modify it, without touching the original.
That gives us the URL we need to parse. The next line gets the actual router class. In this case, we are in the front end, also known as the "site", so when we execute the command "$this->getRouter()", we get a "JRouterSite" object ("includes/router.php").
Then we execute the "parse()" method of the router, which gives us an array of commands. In our example, the "JURI" object would contain the URL information for the article menu item ("http://myjoomlasite.org/index.php/my-article-name") and turn it into a command array as follows:
|
Itemid: |
123 (id of the menu item) |
|
option: |
com_content (name of the component) |
|
view: |
article (name of the view) |
|
id: |
234 (id of the article) |
Then we put this information back into the PHP $_GET variable using the "JRequest::set()" method. Finally, we trigger the "onAfterRoute" system event so that we can execute any system plugins for this event. (We'll talk a lot more about events and plugins in Chapter 6.)
At this point, we have finished with the parent's "route()" method and return to the "route()" method of "JSite". Here we get the Itemid, which is the "id" column in the database for the menu item we are going to display. Then we check that the current user is authorized to view this menu item, with the "$this->authorise()" method.
Last, we return to the "index.php" file and run a DEBUG command to mark the end of the routing process.
Execute the Component
Now we know what we are supposed to do. The URL entered by the user (for example, by clicking on a menu item link) has been checked and translated into an array of commands and saved in the PHP $_GET variable.
So, we are now ready to actually execute the component.
Returning to "index.php", we see the next section of code is as follows:
// Dispatch the application. $app->dispatch(); // Mark afterDispatch in the profiler. JDEBUG ? $_PROFILER->mark('afterDispatch') : null;
|
Figure 29: Dispatch() Method
The "dispatch()" method actually executes the component. Let's look at how this works.
The table below shows the code for the "dispatch()" method.
)
Figure 30: JSite "dispatch()" Method
We get the component name from the "option" command that we got when we parsed the URL. Then we create a new document. The $document object will be used to store everything about the page that will eventually be sent back to the browser.
There are a couple of important things to understand about the document. First of all, since it is an object in memory, we don't have to build it sequentially. We can insert portions of the document in any order we find convenient. We take advantage of this and build the document in a non-sequential order. For example, we will add the component first and then later insert the modules.
A second important point about the document is that Joomla supports different document types. When we are browsing a site, the type is normally "html". For this type, we do some special processing. We get the language for the page, set the metadata, and set the base if we are using SEF URL's. If the document is a newsfeed (type = "feed"), we skip most of this and just set the document base. If the document is any other type, we skip all of this special processing.
After setting the page title and description, we get to the heart of the matter with line 186:
$contents = JComponentHelper::renderComponent($component);
This executes our component and places the output into the $contents variable. Let's see how this works.
Here we are running a static method called "renderComponent()" from the "JContentHelper" class ("libraries/joomla/application/component/helper.php"). Here is the first part of the code.
)
Figure 31: JSite "dispatch()" Method
Here we are loading the template and the template language . Then, if you look at line 116, we are saving the component name in a field of the JSite object called "scope". This is a very handy field. It means that, at any point in the cycle, we can check this field to see what component is being run. We might, for example, make use of this when running a plugin that should only run for selected components.
Tricky Code Alert!
|
Notice we have some tricky code in lines 104 – 108 to load the language, using the boolean "or" operator ("||"). We frequently use this inside an "if" statement, when we want to check if more than one condition is true. However, this operator does something interesting – it stops processing as soon as it hits an expression that evaluates to the boolean "true". The "load()" method of the "JLanguage" class returns a boolean "true" if the load is successful and a boolean "false" otherwise. So this is a quick (and tricky) way to say "try loading the language file starting with the "JPATH_BASE", then "JPATH_THEMES", and so on. And, by the way, stop as soon as one of the loads is successful". |
Figure 32: Tricky Code Using Boolean "or" Operator
Line 118 just makes sure that the $option variable only has letters, numbers, and underscores. It replaces any other characters with dashes. That way we know that there are no characters that will cause problems inside a file name. Then, line 119 says "use the part of the $option name after position 4 as the file name". This is the naming convention for components. In our example, the component is called "com_content", so the file we will execute is called "content.php". We'll see more about other naming conventions in the next section.
We are almost ready to actually execute our component! The next section of code defines the path to component's front end and back-end files and we set the $path variable based on whether this component is a front-end (site) or back-end (administrator) component.
In lines 135-137 we make sure the component is enabled. Finally, in lines 142-145 we use the "or" trick again to load the language from one of the four possible file locations.
The next section of code actually loads our component file, as shown below.
){kind=small}
Figure 33: Execute the Component File
This code block clears out anything that might have been in the $contents variable. Then the "ob_start()" command tells PHP to turn on output buffering. So everything the component outputs will be saved in memory. Then we load the component file with "require_once $path". In our example, it loads the file "components/content.php".
Now, we will cover components and the Joomla model-view-controller (MVC) design pattern in Chapter 8. The important thing here to understand is that the only thing that Joomla actually does to execute the component is to load this one file. The rest is up to the component.
This means, for example, that a component does not have to follow the MVC pattern or even use classes and objects. It could be a single script, as long as it follows the naming convention. Having said that, there are very good reasons for following the MVC pattern for components, which we will discuss in Chapter 8.
You can do a quick experiment to prove to yourself how this works by creating your own "com_test" component according to the instructions on the Joomla documentation site here: http://docs.joomla.org/Testing_Checklists#Testing_Code_Snippets. By entering in "?option=com_test" in your URL, it executes the "test.php" file in your "components/com_test" folder.
Once the component has finished executing, we store the buffer contents of the buffer back into the $clean variable using the "ob_get_contents()" method. Finally, we clean out the buffer with the "ob_end_clean()" method.
At this point, our component has been executed and it's output is in the $contents variable. The last part of this method is shown below.
){kind=small}
Figure 34: End of "renderComponent()" Method
It checks to see if we need to show a toolbar and shows it if needed. Then it sets the "$app->scope" variable back to its previous value. Finally, we return the "$contents" variable to the calling method, which as you recall is line 186 of the "dispatch()" method in "JSite".
The next line,
loads the "$contents" into the "component" part of the document. Finally, we trigger the "onAfterDispatch" event for system plugins and, if we are debugging, we mark the "afterDispatch" point. Now we have the output of the component in the document and are ready to put in the other pieces of the page.
Render the Page
The next part of the "index.php" file is shown below.
// Render the application. $app->render(); |
Figure 35: JSite "render()" Called From "index.php" File
At this point, we have the output from the component, but we don't have any formatting and we don't have other page content, such as modules or messages.
The "$app->render()" method looks like this.
public function render() {$document = JFactory::getDocument(); $user = JFactory::getUser(); // get the format to render $format = $document->getType(); switch ($format) {case 'feed': $params = array(); break; case 'html': default: $template = $this->getTemplate(true); $file = JRequest::getCmd('tmpl', 'index');
if (!$this->getCfg('offline') && ($file == 'offline')) {$file = 'index'; } if ($this->getCfg('offline') && !$user->authorise('core.admin')) {$uri = JFactory::getURI(); $return = (string)$uri; $this->setUserState('users.login.form.data',array( 'return' => $return ) );$file = 'offline'; } if (!is_dir(JPATH_THEMES.DS.$template->template) && !$this->getCfg('offline')) {$file = 'component'; } $params = array( 'template' => $template->template, 'file' => $file.'.php', 'directory' => JPATH_THEMES, 'params' => $template->params ); break; } // Parse the document. $document = JFactory::getDocument(); $document->parse($params); // Trigger the onBeforeRender event. JPluginHelper::importPlugin('system'); $this->triggerEvent('onBeforeRender');
$caching = false; if ($this->getCfg('caching') && $this->getCfg('caching',2) == 2 && !$user->get('id')) {$caching = true; } // Render the document. JResponse::setBody($document->render($caching, $params)); // Trigger the onAfterRender event. $this->triggerEvent('onAfterRender');
} |
Figure 36: JSite "render()" Method
Here we start by getting the document, the user, and the document type or format. Based on the format, we do some processing in the switch statement. In our example, our type is "html", so we get the template and set the $params array.
After the switch statement, we call the document's "parse()" method, shown below. Note that, since the type is "html", the document object is of type JDocumentHTML ("libraries/joomla/document/html/html.php").
public function parse($params = array()) {
$this->_fetchTemplate($params); $this->_parseTemplate(); } |
Figure 37: JDocumentHTML "parse()" Method
The first line loads the template and corresponding language file. The "_parseTemplate()" method, shown below, examines the template's "index.php" file and creates an array of all of the "jdoc:include" elements.
private function _parseTemplate() {$replace = array(); $matches = array(); if (preg_match_all('#<jdoc:include\ type="([^"]+)" (.*)\/>#iU', $this->_template, $matches))
{$matches[0] = array_reverse($matches[0]); $matches[1] = array_reverse($matches[1]); $matches[2] = array_reverse($matches[2]); $count = count($matches[1]); for ($i = 0; $i < $count; $i++) {$attribs = JUtility::parseAttributes($matches[2][$i]); $type = $matches[1][$i]; $name = isset($attribs['name']) ? $attribs['name'] : null; $this->_template_tags[$matches[0][$i]] = array('type'=>$type, 'name' => $name,'attribs' => $attribs); } } } |
Figure 38: JDocumentHTML "_parseTemplate()" Method
The key to understanding this method is the "preg_match_all" statement. This is a complex statement to create, but what it does is easy to explain. The result of this statement is to create three larrays. The first one is a list of all the "jdoc:incude" elements in the template file. This is put into "$matches[0]". The second is a list of the "type" attribute for each of these elements. This is put into "$matches[1]". The type will normally be "head", "modules", "messages", "debug", or "component". The third is a list of the other attributes that come after the "type" attribute in the element. This is stored in "$matches[2]".
The "for" loop creates an associative array of "type", "name", and "attribs" using this information and stores it into thee "_template_tags" field of the $document ("$this->_template_tags").
Now we are ready to actually put the page together, placing head of the parts of the page into the right location on the template.
Returning now to the "render()" method of the "JSite" class, we trigger the "onBeforeRender" system event and then check to see if this page is cached.
Then we execute this line of code: JResponse::setBody($document->render($caching, $params));
Here, we are setting the field of the "JResponse" object using the "render()" method of the "JDocumentHTML" class. That method contains the following code:
public function render($caching = false, $params = array()) {$this->_caching = $caching; if (!empty($this->_template)) {
$data = $this->_renderTemplate(); } else {$this->parse($params); $data = $this->_renderTemplate(); } parent::render(); return $data; } |
Figure 39: JDocumentHTML "render()" Method
The key line of code here is "$data = $this->_renderTemplate();". This method reads through the array we created earlier in the "$document->_template_tags", as shown below.
private function _renderTemplate() {$replace = array(); $with = array(); foreach($this->_template_tags AS $jdoc => $args) {$replace[] = $jdoc; $with[] = $this->getBuffer($args['type'], $args['name'], $args['attribs']); } return str_replace($replace, $with, $this->_template); } |
Figure 40: JDocumentHTML "_renderTemplate()" Method
The key line here is "$with[] = $this->getBuffer($args['type'], $args['name'], $args['attribs']);". Recall that the "template_tags" field contains an array with the component, modules, head, messages, and debug element information. Each of these is processed in this loop and loaded into the "$with" array.
The component has already been rendered, so it is just copied from the "$contents" field. The "jdoc:include" elements for modules normally are done by position. If so, then each module assigned to that position for that menu item is executed and it's output is placed into the "$with" array.
Similarly, the "head", "messages", and "debug" elements are processed.
Then, the last line does a string replace statement to "inject" the actual rendered text output for each module, component, message, head, and debug element into the actual template file. At this point, the elements of the page are formatted inside the template and ready to be sent to the browser.
One important result of the way this is done is that a module is only executed if it is assigned to a position in the template. So there is no performance penalty for modules that are assigned to other positions or menu items.
Now, we return to the "render()" method from "JDocumentHTML" above and execute the "render()" method of its parent class, "JDocument" ("libraries/joomla/document/document.php"). This method simply sets the modified date and content type for the document header. Then it returns the "$data" variable, which is the template's "index.php" file with the page contents taking the place of the "jdoc:include" elements.
Recall that we started this part of the program with the following line of code from the "render()" method of the "JSite" class:
JResponse::setBody($document->render($caching, $params));
At this point, we have completed the "$document->render($caching, $params)" portion of the statement. The last thing to do is to pass the result of this to the "JResponse::setBody()" method. This method is shown below:
public static function setBody($content) {self::$body = array((string) $content); } |
Figure 41: JResponse "setBody()" Method
This simply places the resulting text into the "$body" field of this class.
The last thing done by the "render()" method is to fire the "onAfterRender" system event. At that point, we return to our top-level "index.php" file.
Output the Page
The last thing we need to do is actually send the output to the browser. Looking at the end of the "index.php" file, we see the following code.
// Mark afterRender in the profiler. JDEBUG ? $_PROFILER->mark('afterRender') : null;
// Return the response. echo $app; |
Figure 42: End of the "index.php" File
The JDEBUG statement, as before, simply marks the "afterRender" point for profiling the application.
The last line, "echo $app", has a trick to it. Recall that "$app" is a "JSite" object. The PHP "echo" command is used to send text to the browser. What does it mean to "echo" an object?
The answer is simple. If an object has a special method called "__toString()", this method is executed automatically when you use the "echo" command with an object. If not, the "echo" just returns the name of the class.
However, if we look at the "JSite" class ('includes/application.php'), we don't find a "__toString()" method. Not to worry. If we look at the parent class of "JSite", which is "JApplication" ('libraries/joomla/application/application.php'), we see that it has a "__toString()" method that "JSite" inherits, as follows.
public function __toString() { $compress = $this->getCfg('gzip', false);
return JResponse::toString($compress); } |
Figure 43: JApplication "__toString()" Method
This method in turn calls the "toString()" method of "JResponse", which does the following:
public static function toString($compress = false) {$data = self::getBody(); // Don't compress something if the server is going to do it anyway. Waste of time. if ($compress && !ini_get('zlib.output_compression') && ini_get('output_handler')!='ob_gzhandler') {$data = self::compress($data); } if (self::allowCache() === false) { self::setHeader('Cache-Control', 'no-cache', false);// HTTP 1.0 self::setHeader('Pragma', 'no-cache');
} self::sendHeaders(); return $data; } |
Figure 44: JResponse "toString()" Method
This method:
- Puts the body of the page in the "$data" variable.
- Checks whether to compress the page or not.
- Checks the caching and sets the page header accordingly.
- Sends the page headers.
- Returns the "$data" containing the entire page.
The contents of "$data" are then fed back to the PHP "echo" command, which sends it to the browser.
Summary of Joomla Session
Whew! That was quite a lot of work to display the page. What did we learn?
We saw that the first few steps in the process were just getting the file locations figured out, loading the Joomla framework, and figuring out if we are starting or continuing a session. Then we found and executed the component. Then we ran all of the modules and put everything into the template file. Finally, we sent it all to the browser.
Along the way, we triggered events that can work with plugins.
Even though there is a lot of code involved in each step, it is organized into a relatively small number of high-level methods, each of which can drill-down to lower level methods as needed. The high-level methods are set up in a structured way so that, at any given stage in the process, we are working on one task in the process.
We can also see from this overview how Joomla is designed to easily fit extensions into the framework provided by the CMS. Components, modules, plugins, and the template are executed at well-defined points in the process, and there is absolutely no distinction made between core extensions included in the standard installation, on the one hand, and extensions provided by third-party developers. All are treated exactly the same way, which allows for the seamless operation of extensions.