I've recently been asked by a few people about how to best get started in developing your first Moodle block. While I love hearing from people, I also love sharing information. The following is one approach that I recommend.
Moodle is made up of millions of lines of source code which can be daunting at first for a beginner - but it doesn't have to be. Starting with the development of a simple Moodle block can be a great introduction into the world of Moodle development.
Here are the steps that I recommend for getting started. It assumes that you will be developing on your local computer, not a separate server.
1) Create an account on Moodle.org. You will need this to access the Moodle General Developer forum and download Moodle plugins.
2) Read Getting Started with Moodle Development.
3) Create an account on GitHub and install Git on your computer. This is the source code version control repository tool of choice for Moodle development.
4) Setup a AMP (Apache, MySQL/MariaDB, PHP) stack on Linux, Windows or OS X. While this can be done manually in each of these operating systems using the files found at https://download.moodle.org/releases/latest/, it is easiest to just download one of the available installer package for Mac OS X or Windows which include a complete pre-configured XAMPP environment. Installing it on Linux is a little more involved.
More advanced options include using MAMP and WAMP instead but, as with Linux, you will need to make sure that you install/configure all of the required Apache and PHP libraries and settings. If you prefer, there are also unofficial Vagrant boxes and Docker containers available but this might be more advanced at this point as it also requires that you install VirtualBox on your computer.
Note about NGINX: Although recent versions of Moodle are compatible with NGINX and PHP 7 and you are very likely to see a significant performance improvement, older versions of Moodle and some 3rd party Moodle plugins/themes may not be compatible with these yet. It might be wise to stick with Apache and PHP 5.6 for now - for compatibility reasons.
5) If you didn't use one of the installers for Windows or OS X...
The next step will be to install Moodle. I also highly recommend installing phpMyAdmin (it is included with the above mentioned installers) to make administration of your MySQL server a much easier as the first step will be to create a database. I recommend that you name your databases the same way you name your Moodle instance folders which I put into a folder off your web root called "moodleXX" where XX is the version number of Moodle. That way, you can have multiple versions of Moodle running on your server at the same time which is great for compatibility testing. For example, I have a folder and a database both called moodle33. That way it is easy to keep track of which database belongs to which Moodle sites and avoids confusion down the road when you end up with many versions of Moodle.
In order to avoid setting up development environments for each version of Moodle, I tend to develop in the current Long Term Support (LTS) version of Moodle, currently Moodle 3.1, and then test in other versions of Moodle. The next LTS version of Moodle will be 3.4, due to be released in November this year. LTS releases happen every 4th version of Moodlle (e.g. 2.7, 3.1, 3.4).
For more information on installing Moodle manually, see Installing Moodle.
6) Set-up Moodle for development.
Your Moodle website should now be accessible using your web browser by going to http://localhost/ if you used the installer method, or http://localhost/moodleXX if you installed Moodle in folder under your webroot. Next,
- Install the Moodle Code Checker plugin. This will be used to test your plugin for conformance with Moodle coding standards. Use this to develop good coding skills.
- Install the Moodle PHPdoc Check plugin. This will be used to test your source code documentation. This will also help improve your coding skills.
- Enable the Moodle Debugger: Login to Moodle as an Administrator and click Home > Site Administration > Development > Debugging and a) set the Debug Messages to "DEVELOPER: extra Moodle debug messages for developers" AND check the box next to "Display debug messages" to display errors on your screen. When developing in Moodle, you should live 100% of the time with this turned on. Only turn it off for demonstration purposes as it does have a considerable impact on the performance of your Moodle website.
Advanced topic: In order to trace step-by-step through PHP source code when debugging, you will need to use XDEBUG if it is not already built-into your development IDE. On a side note, the implementation for Notepad++ using the DBPG plugin is not capable of debugging Moodle code which is too deeply nested and too large for it to handle. Debugging Moodle PHP code seems to work fairly well in NetBeans and Eclipse PDT though it can be a little complicated to setup. I've also had some success with SublimeText, PhpStorm and phpDesigner... in case you were wondering. I do not recommend using JavaScript based editors like Atom or Visual Studio Code. While very nice code editors, they tend to slow to a crawl when you are editing some large Moodle PHP library files - where it can take up to several seconds to insert a simple carriage return.
7) If you just want to learn about creating Moodle blocks, a solid choice for getting started would be to clone the blocks/html plugin. It is a relatively simple plugin yet includes most basic functionality for a plugin. The process will help you become familiar with the structure of a block plugin.
Cloning the html plugin involves:
- Copying the whole html directory and give it a new name like myhtml in this example.
- Changing the directory names. Any directory name containing the substring "html" will need to be changed to "myhtml".
- Changing some of the file names. Any file name containing the substring "html" will need to be changed to "myhtml".
- Editing every source code file, replacing references to the name html with "myhtml", even in function names.
- Update just about all the settings in the plugin's version.php.
It is important to be consistent in the naming of your plugin files and source code functions, especially classes, in order for them to integrate well into Moodle.
This exercise will take you through each of the files and give you a good idea of how a Moodle block plugin is structured.
Because it is a custom Moodle plugin (not a core plugin), you should also create the following files and folders:
- A folder called "pix".
- An graphic called pix/icon.png (16px X 16px)
- A file called README.md - This is your main documentation for the plugin and will also be the content for the repository's home page on GitHub.
- A file called CHANGELOG.md - This should contain a list of recent fixes for your plugin.
- A file called LICENSE.txt - This is the terms and conditions of the license for your plugin. Must be GNU GPL (open source) since you are using Moodle APIs which are GPL. However GPL does not force you to release your plugin to the public if you want to sell it. Get some legal advice if this is a concern for you.
- If your plugin will be using classes, consider putting them into a folder you create called "class".
- To keep things simple for now, you won't need the backup folder.
Note: .md files are just regular .txt files but with a different extension. They can include markup which is interpreted by Github.
Always resolve all errors and warnings that show up with Moodle debugging turned on. Errors and warnings mean that something isn't working as it is supposed to which means your code isn't doing what you intended it to.
PHP Debugging tip: If ever Moodle doesn't display anything, not even an error message, check all of your PHP source code for syntax errors. PHP includes its own PHP syntax checker which you can use from the command line:
- php.exe -l filename.php
Note that is a -l (lowercase L). You can probably even configure this into your favourite source code editor so you don't need to go to the command line. In Notepad++ for example, you can create a CTRL-F6 script called "Check PHP Syntax" containing the following line:
- "c:\xampp\PHP\php.exe" -l "$(FULL_CURRENT_PATH)"
Keep in mind that this will just give you a basic overview of the Moodle block plugin. There is a lot more functionality that can go into a Moodle plugin as well as automated unit testing but those are more advanced topics which you can learn by reading through the source code of other block plugins.
Learning how to code in Moodle involves a lot of learning by example and reading other people's source code including Moodle core code. If you have a particular type of block in mind that you would like to create, I recommend that you start by finding a plugin which provides similar functionality and use the process outlined above to clone it. Then customize it to suit your needs. You can even do this with 3rd party plugins found on moodle.org/plugins. That's just one of the many advantages of developing with open source. Just always remember to give credit to the original author for his/her original hard work.
You may also be interested in taking a look at the Step-by-step Guide to Creating Blocks.
Learning all of Moodle and its database takes time - maybe even years. In fact you may never come across parts of it and that's OK. Take it one step at a time and don't be afraid to ask for help when you get stuck. The only expectation by the worldwide community is that you will have tried to figure things out on your own before asking a question. Google is your friend. Just start your query with the word "moodle".
Hope you found this useful. I encourage you to submit your questions in the Moodle General Developer forum. You'll find that most of the community loves helping beginner developers. If anyone gives you a bad attitude, just ignore them. NEVER respond to these people - they have forgotten what it is to be new in a community are not worth your time. There are lots of good people around.
Best regards,
Michael Milette