Joomla! 3 Getting Started With Extension Development

Reading time ~11 minutes

Most of the books or articles on Joomla! development focus on building your first module or component, but do not really talk about the setup needed in order to actually be a successful developer.

I have been involved in the Joomla! community for a couple of years now, following discussion groups and forums, so I have a good idea about the level at which most of the extension developers are (especially the ones just starting with PHP development).

While it may actually seem easier to just change code on a production server or to install tools like XAMPP or WAMP, I want to present you a workflow that will not only save you time in the long run, but it may provide a solid understanding of how Joomla works.

You are here because you want to learn something new, right? So if you want to be serious about Joomla! development (or PHP development in general), please do exactly as I suggest, even if you may not agree with some points.

Some things may not work, so do not get frustrated. Just leave a comment in the section below and I will try to help you.

In a nutshell you will learn the following from this article:

  1. Using a virtual machine (devbox) and installing Joomla! without lifting a finger
  2. Choosing the right IDE
  3. Configuring the debugger
  4. Versioning your code using Git
  5. Building and delivering the extension
  6. Testing your extension

1. Using a virtual machine (devbox) and installing Joomla! without lifting a finger


This devbox has been succesfully tested on Windows 10, OS X El Capitan and Ubuntu 16.04 LTS.

Please observe the following prerequisites before getting started:

  • Vagrant, at least version 1.8.x
  • Virtualbox, minumum 5.0.x
  • Git (Windows users are advised to install Git with Git Bash)
  • PHP installed locally (needed later for Phing)

If you do not already have these tools, go ahead and install them please. You will find enough instructions on how to do that somewhere else.

In a nutshell, Vagrant will take care of creating a virtual machine as instructed, while Virtualbox is a software virtualization package, allowing us to have an additional operating system running on top of your current operating system.

In our context, the terms virtual machine, development machine or devbox refer to the same thing.

Creating the virtual machine

After all the tools are installed, open a command line tool (Windows users are advised to use Git Bash) and clone the following repository:

git clone

cd joomla-training-devbox

Now let us start the virtual machine (you always have to be inside the directory containing the Vagrantfile file to run vagrant commands):

vagrant up

Word of advice for Windows users: If you have never used Vagrant on your machine, this step might be blood and tears for you. Sorry about that! You will probably get tons of errors. Searching for a specific error usually helps as you are not the first one having problems. Rebooting your system and sometimes destroying your devbox (with vagrant destroy and after that running vagrant up again) might help. Please do not give up!

The command vagrant up will initialize the virtual machine and this will take a while. At the end you should see this


If you scroll up and do not see a any errors, you are good. Congratulations.

Now you need to edit your hosts file and include two new entries: joomla-development.local joomla-testing.local

After this step you will be able to open your browser and to access the two domains listed below:

For development we will use joomla-development.local.


For testing any extensions that we will develop, we will use joomla-testing.local


The administrator login is admin / admin.

What happened?

With “vagrant up” we instructed Vagrant to build us a virtual machine according to some predefined settings (we call them recipies). We created an Ubuntu machine, with PHP and everything else we need and at the end we installed Joomla on top of it.

To create this “miracle”, I have used, a very neat only configurator for virtual machines. Feel free to experiment with it once you are done with this tutorial.

Additionally you may want to inspect the scripts included in the folder (/puphpet/files/exec-once/) to understand who Joomla! was automatically installed.

The advantage of doing this is that you can recreate this environment (or any other enviroment) as often as you like, WITHOUT any manual work, configurations etc. You can also share this with our fellow colleagues.

2. Choosing the right IDE

I cannot stress how important is using a modern IDE for software development.

Please do not use Atom, Notepad++, Sublime, Vim, Emacs or something similar for writing code. It just does not work. STOP doing this. I really mean it!

There are many solutions out there but the only IDE I can truly recommend is PhpStorm. Unfortunately for your pockets, PhpStorm is a commercial solution.

If you do not have it already, please go ahead to download and install it. It comes with a free 30-day trial, enough time to complete this tutorial and and get an idea if it is worth.

PhpStorm also has an Early Access Program (EAP), which allows you to get a 30 days license with each build you download and install. The disadvantage is that the builds may be very unstable or crash. Also I am not sure if the license allows commercial use.

I will not go to great lengths on how to use PhpStorm in this post. Please refer to the manual shall you have any questions or issues.

At a later point, if you decide that PhpStorm is not really for you, good open-source & free solutions are Eclipse Standard (with PDT) and Netbeans.

Creating a new project

Open PhpStorm and create a new project by opening an existing location (locate the folder joomla-training-devbox\joomla-development.local).

Create Joomla! Project with PhpStrom

Soon PhpStorm will detect that you have a Joomla! project and will invite you to enable support for it. Go ahead and do that.

PhpStrom Joomla support

3. Configuring the debugger

The most important feature you need to have in your IDE up and running is the debugger. This will not only help you understand why your code does not work as expected, but it is also an excellent insight on how Joomla works.

STOP debugging code with var_dump() and die(). I really mean it. STOP!

Please remember this: the documentation will never manage to keep up with all the code changes. So it is your duty as a developer to read and understand the Joomla! code base. When something does not work right, go with the debugger through Joomla!. You will learn a lot. Trust me.

Don’t skip this part! Do it now! It will get back at you later. I promise.

Configuring the debugger in PhpStorm

We will need to create a debug configuration in PhpStorm and this is done with very little configuration. Your devbox already has Xdebug up and running.

From top menu select Run - Edit configurations. Click the green plus (+) button to create a new configuration and select “PHP Remote Debug”.

PhpStrom New PHP Remote Debug Configuration

PhpStrom No Server

Go ahead and create a new server, following the configuration shown below:

PhpStrom New Server

Now click on “Use path mappings” and configure the paths as described below. The right side is the virtual machine and left side is your local machine. You need to make sure the left path is the right one.

PhpStrom Setup Path Mappings

After clicking OK, you return to the previous screen where you can select the server you have created. Additionally, insert PHPSTORM in the field “Ide Key”.

PhpStrom Ide Key

Depending on the browser you use, you will need an additional plugin in order to start the debugging session in your browser.

For Chrome I use Xdebug helper. For other browsers you will find similar tools. Bear in mind that you need to do a small configuration and set the PHPSTORM key.

PhpStrom Chrome Xdebug Helper

Now activate the plugin so that it stays green all the time.

Activate Chrome Xdebug Helper

In PhpStorm set a breakpoint in a file (I will demonstrate by setting it inside the index.php file).

Activate Chrome Xdebug Helper

From the top menu select Run - Debug. A new window should popup and listen for incomming Xdebug connections.

PhpStorm Run Debug

Open the browser pointing to joomla-development.local and your IDE should almost instantly start a Xdebug session.

Xdebug Incomming Connection

Please refer to the PhpStorm manual for more details about using the debugger.

Configuring the debugger in other IDE

In Eclipse / Netbeans could be a bit trickier to configure, but there are plenty of tutorials out there. Take your time and do it right.

4. Versioning your code using Git

Now that we have a running devbox, a Joomla installation, an IDE and a working debugger, let us dive into extension development.

Taking the example of a component, every tutorial will tell you that you need to put some code in the root components, some in the administrator/components, the extension manifest file, language files, media files there … so basically pieces of code everywhere.

Because the code is spread all over the place, it is quite difficult to put it in a version control system like Git, without actually versioning the whole installation.


Step 1 You already have created a new PhpStorm project from the sources available in the folder joomla-development.local. If you have not done that already, read again the previous section.

The command listed below assume that you are already inside the folder joomla-development.local.

Step 2 You will notice in the root structure a folder called _source. We will use this folder to keep track of our sources (Joomla extensions).

Step 3 I already have a sample extension ready for you, which we are going to use for this tutorial.

We are going to store this extension inside the _source folder. Because we already have checked out Joomla! as a Git project (stating branch), we are going to add our extension as a git submodule.

git submodule add _source/components/com_fleetmanagement

Step 4 Now you have to register the component with Joomla!. Inside Extension Manager, use install from folder and give the following path:


Joomla! Install from Source

Step 5 Check if the extension is working in the frontend. Open the following URL:

Frontend: http://joomla-development.local/index.php?option=com_fleetmanagement

Backend: http://joomla-development.local/administrator/index.php?option=com_fleetmanagement

Step 6 Now the we have registered our extension with Joomla, we will reset all changes Joomla made to the filesystem when installing our extension.

Please run this git command inside the Joomla! root folder.

git clean -f -d

Step 7

If your operating system is OS X or Linux that you should do this:

Inside the extension source folder (_source/components/com_fleetmanagement), we will execute a small bash script which will create symlinks:


If you are using Windows, you need to follow these steps:

a. Stop the already running devbox with vagrant halt.

b. You need to enable the symlink creation on the guest OS, which is disabled by default in Virtualbox.

VBoxManage setextradata joomladev1.puphpet VBoxInternal2/SharedFoldersEnableSymlinksCreate/joomla-development.local 1

VBoxManage is only available if you already added it to your PATH. Otherwise you need to use the full path like:

C:\Program Files\Oracle\VirtualBox\VBoxManage.exe ….

c. Start your console as an Administrator and run vagrant up.

d. Login into your devbox by tying vagrant ssh.

e. Create the symlinks by running:

sh /var/www/joomla-development.local/\_source/components/com_fleetmanagement/

As an Linux or OS X user, you will be able to see the component com_fleetmanagement in the _source folder as well as in the normal folders from Joomla (under components). Windows users will only be able to see and change the code from the _source folder.

(image here)

5. Building and delivering the extension

We want to be able to build new versions of your extension as often as possible. To make this possible we need to reduce / eliminate any manual work.

To achieve this, we will be using a build tool called Phing, inspired from Apache Ant, very popular in the Java world.

Let us have a look at the steps needed in order to build a new version of your extension:

  • update the extension manifest file (fleetmanagement.xml) with a new creation date, version and so on.
  • pack all the files in a zip archive and name it accordingly (we will call this an artifact)

So let us get started.

Step 1. First we need to install Phing in PhpStorm. From Settings search for “Phing”, and download it as instructed by PhpStorm.

PhpStorm Install Phing

Step 2. You will notice a file called build.xml in the extension source folder. Open it and try to understand what is supposed to do.

Step 3. Right-click the build.xml file and from the context menu select “Add as Phing Build File”.

Step 4. A new view should be displayed, showing the build file tasks. Select “build” and click the Run button.

PhpStorm Start Phing Build

Step 5. Inspect the _builds folder for the artifact.

Even if the build file is quite simple and you can do it easily by hand, the purpose is to demonstrate a one-click build process. You might later want additional tasks, so it is good to have a starting point. Not to mention it would make it even more easier to integrate with a continuous integration (CI) server like Jenkins.

6. Testing

Now that we have an artifact of our extension, which we can distribute to users, let us make sure that this build was a successful one.

Open the test installation (joomla-testing.local), login in the backend and install this build.

This testing enviroment will allow you to test new installations, uninstallation, updates and so on. It will not interfere with your development enviroment and you do not have to worry if you break it.

Pro Tip If you have already checked the scripts inside /puphpet/files/exec-once/, you can probably figure out how you can recreate the testing enviroment if it gets broken.


We have managed to create a development environment (devbox), to automatically install Joomla!

Use Let’s Encrypt on Google App Engine with Python, Java, PHP, Go or whatever

This article is mostly inspired from existing sources on the interwebs[1][1] [2][2] but tries to simplify the process by making it envi...… Continue reading