Building Custom Moodle Plugins: A Step-by-Step Guide for PHP Developers

Iqra SarwarPosted on May 15, 2025

6-7 Min Read TimeAdd as preferred on Google

Building custom plugins is a great way to make Moodle work exactly how we need it to. When we first started customizing Moodle, it seemed complicated, but once we broke it down into steps, it turned out to be quite manageable. In this blog, we’ll walk you through creating your first Moodle plugin with simple, easy-to-follow steps. Let’s get started!

What You'll Need Before Starting

Before we start, make sure you have:

• A working Moodle installation (for testing)
• Basic PHP knowledge (you don't need to be an expert!)
• Some understanding of HTML and JavaScript
• A code editor like Visual Studio Code or Sublime Text
• A bit of patience (trust me, it's worth it!)

Understanding Moodle Plugin Types

Moodle has different plugin types, each serving a specific purpose. The most common ones are:

• Activity modules - Add new activities for students
• Blocks - Display information in sidebars
• Themes - Change how Moodle looks
• Authentication - Control how users log in
• Admin tools - Add new admin features

For this blog, we'll create a simple block plugin since they're the easiest to start with.

Set Up Your Plugin Folder Structure

Let's create a simple block that displays a motivational quote to students. First, we need to set up our folder structure.

1. Go to your Moodle installation directory
2. Navigate to the /blocks folder
3. Create a new folder named motivational_quotes

Inside your new folder, create these files:

• block_motivational_quotes.php (main plugin file)
• version.php (version information)
• db/access.php (permissions)
• lang/en/block_motivational_quotes.php (language strings)

Define Your Plugin Version

Open version.php and add the following lines of code:

This code is used in a Moodle plugin to define important details about the plugin. The first line checks if the file is being accessed properly through Moodle; if not, it stops the script for safety. The next few lines provide information about the plugin, such as its name (block_motivational_quotes), the version number based on the date (May 11, 2025), and the minimum Moodle version it needs to work (April 24, 2023). It also shows that this is version 1.0 of the plugin and that it is stable and ready for use.

Set Up Language Strings

Open lang/en/block_motivational_quotes.php and add:

These lines define the text that will be shown to users for different parts of the "Motivational Quotes" block in Moodle. The $string['pluginname'] sets the name of the plugin that users will see. The $string['motivational_quotes'] is usually the title shown on the block itself. The next two lines set permission strings, one allows a user to add the block anywhere (addinstance), and the other allows adding it specifically to their personal dashboard (myaddinstance). These text labels help Moodle display clear options and messages to users when they use or manage the block.

Define Access Capabilities

Open db/access.php and add:

This code defines who is allowed to add the "Motivational Quotes" block in Moodle and where they can add it. The first line ensures the file is only run inside Moodle. Then, two permissions (called capabilities) are listed. The first one, block/motivational_quotes:addinstance, lets users like editing teachers and managers add the block to course pages. It also includes a risk warning for things like spam or unsafe content (XSS). The second permission, block/motivational_quotes:myaddinstance, allows any user to add the block to their personal dashboard. Both permissions copy behavior from existing Moodle permissions to make the setup easier and more consistent.

Create the Main Block Class

Now for the main plugin file. Open block_motivational_quotes.php and add:

This code creates the main part of the "Motivational Quotes" block in Moodle. It defines a class that extends Moodle's block system. The init() function sets the title of the block using the plugin name. The get_content() function controls what shows up inside the block. It picks a random quote from a list of motivational quotes and displays it. If the content is already set, it just returns it to save time. The applicable_formats() function says this block can be shown on any page, and instance_allow_multiple() allows users to add more than one copy of this block to a page

Install Your Plugin

Now it's time to install your plugin:

1. Log in to your Moodle site as an administrator
2. Go to Site administration > Dashboard.
3. Moodle will detect your new plugin and prompt you to install it
4. Follow the on-screen instructions to complete the installation

Add Your Block to a Page

After installation:

1. Turn editing on (top-right corner)
2. Look for the "Add a block" option, usually in the right sidebar
3. Select "Motivational Quotes" from the list
4. Your block should appear showing a random quote!

Making Your Plugin More Advanced

Once you get the basics working, here are some ways to improve your plugin.

Adding Configuration Options

Adding configuration options is pretty straightforward. You'll want to create a settings.php file in your plugin folder. This lets you add a text box where admins can put in their own quotes. Then you just need to update your block to pull these quotes from the settings instead of using the built-in ones.

Adding a Database Table

If you need to store more complex data, you'll probably want a database table. Create an install.xml file in your db folder to set up your table structure. Moodle's XMLDB Editor is super helpful for this, it saves tons of time. You can access it through Site administration > Development > XMLDB editor. 

When designing your table, you'll need to think about fields (like id, content, timecreated), keys (primary and foreign), and indexes for performance. Once that's done, you can use the $DB object to work with your data. For example, $DB->insert_record('your_table', $dataobject) to add stuff, or $DB->get_records('your_table', array('userid' => $USER->id)) to fetch records. The API makes database work much easier than writing raw SQL.

Adding JavaScript and CSS

Making things look nice is important too. Just add a styles.css file for your custom styling. For any interactive stuff, load your JavaScript using $PAGE->requires->js(). Makes a huge difference to the user experience.

Common Pitfalls to Avoid

Watch out for some common mistakes, though. We often forget to check permissions properly when coding quickly. And we should never hard-code text—using language strings ensures that others can translate the plugin easily. Direct database queries might seem tempting, but they can cause major issues later if we don’t stick to Moodle's API. And yes, we should always test with different themes—we’ve spent hours debugging issues that only appeared with a specific theme.

Wrapping Up

Honestly, Moodle plugin development isn't as hard as people make it out to be. Start small and work your way up. The block we talked about is a perfect first project.

When you get stuck (and you will), the Moodle forums are amazing. Someone's always willing to help out. The developer docs are pretty good too, though sometimes a bit outdated.

Good luck! Hope this helps you build something awesome for your Moodle site.