Creating a Site Module for Joomla 3.x - Part 2
Yes, it’s a Joomla Module, but it’s incomplete.
Now that a minimal Site Module has been created for Joomla, it is time to expand on it a bit. Recall, that we used the least amount of code possible to create and install the Module. The problem with this minimalist approach is that we left some holes that really need to be filled in. For example, the manifest file, the module’s XML file, will hold meta-data for the module that Joomla uses in the back end, or administrator application, to manage the module and provide the site administrator information about it. We also did not take into account that the web server will list the files of our module if we go to the folder directly. To see what I am talking about, open your browser and navigate to the following URL:
http://joom.dev/modules/mod_smallest
The actual URL you will enter will depend on what you called you virtual site and what you named your module. If you have been following the tutorials as I have produced them, the link above will be correct, otherwise you will need to adjust according to your environment.
The next issue, is that we did not prevent the module from running outside of Joomla’s environment. To demonstrate this, enter the following URL in your browser.
http://joom.dev/modules/mod_smallest/mod_smallest.php
You will see that the code in your module will execute. If you are following these tutorials, you will see the output of the module, “Welcome to my module!” has been printed to the screen. These two situations increase your vulnerability to a hacker out on the Internet. We should always consider that a user of our site has malicious intentions and write our code appropriately. So lets take care of these issues in this tutorial.
Exploring the Manifest file.
Recall that the manifest file we wrote for the minimal module contained the following code:
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.5" client="site" method="upgrade">
<name>Smallest Module</name>
<files>
<filename module="mod_smallest">mod_smallest.php</filename>
<filename>mod_smallest.xml</filename>
</files>
</extension>
Although the above code fulfills the minimum that we need to install our module, there is more that we should add to it to make the module that we have written more meaningful to the site administrator in the back end of Joomla. Add the following code, marked in red, to your module’s manifest file.
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.5" client="site" method="upgrade">
<name>Smallest Module</name>
<author>Joe Hildreth</author>
<creationDate>30 JUN 2016</creationDate>
<copyright>(c)2016 Joe Hildreth, All rights reserved</copyright>
<license>GNU General Public License V2 or later</license>
<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/authorEmail>
<authorUrl>http://www.myheap.com</authorUrl>
<version>1.0.0</version>
<description>The minimum code example for a module.</description>
<files>
<filename module="mod_smallest">mod_smallest.php</filename>
<filename>mod_smallest.xml</filename>
</files>
</extension
Let’s discuss the additions and where Joomla uses them. The tags we added to the manifest file above, starting with <author> … </author> and ending with <description> … </description>, are the meta-data tags. Joomla will use the contents of these tags to populate certain items on the back end. We will start with the first tag:
<author>Joe Hildreth</author>
The <author> tag contains the name of the writer of the extension. You would put your name between these tags, or your company or whatever you want. Joomla uses this value in the Author column when you are in the back end managing the extension. Extension | Manage | Manage from the main menu in the back end of Joomla.
<creationDate>30 JUN 2016</creationDate>
The <creationDate> tag will contain the date the extension was written or released. There is not any specific format that you have to use. I could have used June 30th, 2016 or 2016-06-30 or any other format I wanted. Joomla uses the value of this field to populate the Date column in the back end when you are managing your extension.
<copyright>(c)2016 Joe Hildreth, All rights reserved</copyright>
The <copyright> tag hold the copyright information about the extension. The copyright data can be in any format you like. I am unaware where Joomla uses this data if at all. If you know, please contact me. More importantly, it lets a user of your extension know who has the copyright.
<license>GNU General Public License V2 or later</license>
The <license> tag contains the licensing that the extension was released under. This field will let the end user know how your extension and the code can be used. Many folks will find an extension that is sort of what they need and make changes to it. The license that the extension has been released under will let you know what you can and cannot do with the extension and its code. This is another that I do not know where Joomla uses this data. Again, if you know where this is used, please let me know.
<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/authorEmail>
The <authorEmail> tag will contain the email address that an end user can use to contact the extension developer. Perhaps you need some support on how to use the extension. I am unaware where Joomla uses this field. Again, if you know, please let me know.
<authorUrl>http://www.myheap.com</authorUrl>
The <authorUrl> tag informs the end user the web address of the extension writer. This would be the address you would provide where they can go to get updates, instructions on use and general support. Joomla does not display this on the back end that I know of. If you know otherwise, please let me know.
<version>1.0.0</version>
The <version> tag holds the version of the extension. This value of this tag is used in the back end when you manage your extension and is used to populate the version column. Joomla also uses the value of this tag during the install if you are using the upgrade method. The version is stored in Joomla’s database and is compared to any other version stored there for the extension. We will cover this in more detail when we talk about versioning your extension.
<description>The minimum code example for a module.</description>
The <description> tag holds the description of your extension. It is used in the back end when you are managing your extension. The description is displayed when you mouse over the name of your extension as a tool tip.
That concludes the meta-data fields of the manifest file. One other thing I should point out. The <name> and <description> fields are translatable, meaning that you can use a language string as the data for the tag for internationalization of your extension. We will cover this when we get to language strings and internationalization. Now let us address our security issues.
Addressing the Security Vulnerabilities
Apache in a default configuration will list the contents of a directory if the default files cannot be found to load. Now the apache web server can be configured not to display the contents of a directory and I am sure that Microsoft’s IIS server can be too. The problem is, as an extension writer, we have no idea how the end web server will be configured so we should take the effort to prevent the directory listing ourselves. Fortunately, this is simple for us to do. We simply add an index.html file to each folder we create in our extension. So, create a new file in your module’s project directory and name it index.html and add the following code.
<!DOCTYPE html><title></title>
Save and close your index.html file. If you load this file in your browser, you get an empty screen. That will solve the problem of listing the contents of the directory. Now all we have to do is have Joomla copy this file over when we install our extension. Open your manifest file and add the line in red below:
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.5" client="site" method="upgrade">
<name>Smallest Module</name>
<author>Joe Hildreth</author>
<creationDate>30 JUN 2016</creationDate>
<copyright>(c)2016 Joe Hildreth, All rights reserved</copyright>
<license>GNU General Public License V2 or later</license>
<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
<authorUrl>http://www.myheap.com</authorUrl>
<version>1.0.0</version>
<description>The minimum code example for a module.</description>
<files>
<filename module="mod_smallest">mod_smallest.php</filename>
<filename>mod_smallest.xml</filename>
<filename>index.html</filename>
</files>
</extension>
Simply adding the file to the <files> section of the manifest is all Joomla needs to know that it should be copied into the site when you install your module.
That solves that problem, so now lets address the issue of a user being able to execute the code in our module outside the Joomla environment.
If you watched the video on the Joomla Execution Cycle, you learned that Joomla defined a constant in the index.php file that it loads when it starts with the line:
define('_JEXEC', 1);
We can leverage this knowledge and use it in our own scripts. If at the beginning of our script we check for this constant, we can decide what to do based on its existence. So, open your mod_smallest.php file, or whatever you named it, and add the following code marked in red:
<?php
defined('_JEXEC') or die;
echo 'Welcome to my module!';
This line of PHP simply checks to see if the constant _JEXEC has been defined and if it does not exist will kill the script. By placing this line at the top of our file, we are assured that Joomla is calling our file and not someone on the Internet. Save your file and let’s check out our module in Joomla.
Checking out our work.
Select the three files in your module project directory, index.html, mod_smallest.php and mod_smallest.xml and zip them up into an archive. With that done, log into the back end of your Joomla installation and re-install your module. There is no need to uninstall the old copy because we selected the upgrade method in the manifest, meaning that Joomla will copy over the files that were installed from the last go.
Now, let’s check our work.
Go to Extensions | Manage | Manage in the back end and find your module. Notice that the Author, Version and Date fields have been filled in with the information we supplied in the meta-data fields in the manifest file. Hover your mouse pointer over the name of your extension and notice that the description that you gave in the manifest file now appears as a tool tip along with the name of your extension. Pretty cool, huh?
Now, open your browser and point it to:
http://joom.dev/modules/mod_smallest/
Notice that apache just serves you up an empty webpage. Now, an end user has no idea what files and folders exist in our module, making it more secure than it was when we started. Enter the following URL in your browser:
http://joom.dev/modules/mod_smallest/mod_smallest.php
Notice that you get a blank screen. Since we entered the script directly, the constant _JEXEC does not exist, so the script is simply killed and there is no output. If you look at the page source you will see that it is empty.
Well we have come a long way this tutorial, but we have much more road to travel. Now that we have a firm understanding of how to write a simple Module for Joomla let’s expand our knowledge a little more. In an upcoming tutorial we will create a usable module based on what we have learned and expand on it. Thank you for participating
END OF TUTORIAL
