Introduction to Writing MODs
This article outlines the basics of writing modifications for phpBB3.
WHAT IS MODDING?
MODding is when someone makes modifications to the phpBB code in order to alter, remove or create different functionalities. Many of these modifications are released to the rest of the community by those who create them. The final package, which could include new files and instructions on what changes to make, is referred to as a MOD.
The ultimate goal of a MOD author is to have their MOD appear in the phpBB.com MOD Database.
The phpBB MOD Team oversees and administers all MOD related activies.
WHAT YOU NEED TO KNOW BEFORE YOU GET STARTED
phpBB is written in the PHP programming language; in order to write MODs it is important to have some understanding of PHP.
All major software is designed with a set of coding guidelines in mind. phpBB is no exception, and the full coding guidelines are publicly available at http://code.phpbb.com/svn/phpbb/branches/phpBB-3_0_0/phpBB/docs/coding-guidelines.html. MOD authors should follow these guidelines in order to have their MOD accepted into the MOD Database.
Coding guidelines are needed to ensure consistency in the code. They ensure that:
- the code is easy to follow and understand
- all parts of the software are secure
- the software remains compatable with recommended server setups
- the software runs efficiently
- there is no redundancy (ie. you don't recreate existing functions)
The biggest change in MODding since phpBB 2.0.x was the transition to MODX from the text-template. MODX is an XML format used to detail MOD instructions. There is an entire MODX resource centre at http://www.phpbb.com/mods/modx/ which MOD authors are advised to read if they are not already familiar with the new format.
MOD authors should also be aware of the various policies related to submitting MODs to the MOD Database.
There are three major policies that the MOD Team enforces.
- General policies
The general policy contains the basic information MOD authors need to know about writing and packaging their MOD such as which functions are permitted, correct MODX usage and file structure. This policy can be viewed at http://www.phpbb.com/mods/policies/general.php.
- Insta-deny policies
There are certain criteria that could see a MOD be denied instantly. The full policy can be read at http://www.phpbb.com/mods/policies/instadeny.php.
- Repackaging policies
If there are minor problems with a MOD that the validation team finds and the MOD author has given permission, then the MOD Team will repackage the MOD in order to fix these problems and save the MOD author the time of resubmitting a MOD that was mostly acceptable for release. The policy which outlines when a MOD is eligible for repackaging can be viewed at http://www.phpbb.com/mods/policies/repack.php.
HOW TO RELEASE A MOD
Once a MOD author is ready to release his or her MOD, they should go to the [3.0.x] MODs in Development forum, where a MOD topic is to be created. There are 6 statuses a MOD can have in the title.
If it is still in development, and the MOD is not ready for release yet, the name of the MOD should be prefixed with [DEV]. This is commonly a community-input or "planning" phase, where the MOD author could ask for feature requests and idea if they wish.
Alpha is the first letter of the Greek alphabet. As such, in software development it represents the first testing release. In phpBB MODs, typically this will mean the main functionality is there but many features are still missing. There is still some way to go before the software is ready for submission to the MOD Database.
Beta is the second letter of the Greek alphabet and in software development it represents the second testing stage. By this point, a MOD will be nearing the completion of development with most, if not all, features fully developed.
RC stands for Release Candidate. A Release Candidate represents completed software and allows users to test the software in its final stage. This offers the community a chance to report any minor issues or bugs that may have been missed in the previous stages to the developer to fix before they submit the MOD to the MOD Database. Just like with Alpha and Beta releases, there can be many RC releases until the MOD is perfect. Generally at this stage no more features will be added.
Once a MOD has been approved and is in the MOD Database, the MOD author should change their MOD topic title to [MODDB] so that users know that all discussion to the newly created MOD will be in the topic in the MOD Database Releases forum. Users are encouraged to lock their own development topic once the MOD has been approved.
If a MOD author has abandoned their MOD then it should be labelled as [ABD] and the user can lock the topic.
Full documentation regarding MOD Development forum rules can be read at http://www.phpbb.com/mods/rules-and-policies/development/.
Once a MOD author is ready to submit their MOD for validation, they should go to the MOD Database "Submit a modification" page and fill out the required information. Once the MOD has been reviewed, the MOD author will be notified.
IMPORTANT TOOLS AND LINKS FOR MOD AUTHORS
http://www.phpbb.com/mods/mpv/ (MOD Pre-Validator)
Authors can check their MODs for basic errors prior to submitting them for review to the MOD Database by allowing the online MOD Pre-Validator (MPV) to check the contents of the MODs .zip file for common code and MODX issues.
http://www.phpbb.com/mods/umil/ (Unified MOD Install Library)
MOD authors can use UMIL to create installation scripts for databases.
http://www.phpbb.com/mods/modx/ (MODX Resource Centre)
An entire section of the website devoted to MODX. This includes a detailed overview of each MODX tag, a sample MODX file to see how it works, etc.
http://www.phpbb.com/community/viewforum.php?f=71 (MOD Writers Discussion forum)
If a MOD author has any queries about any stage of the MODding process or needs assistance from a coding perspective, they should post a message in the MOD Writers Discussion forum where they can receive assistance from other MOD authors and members of the MOD Team.
AutoMOD is an automatic MOD installer and is an important tool for MOD authors who wish to test their MODs by installing quickly on a vanilla (un-modded) phpBB3 installation.
http://wiki.phpbb.com/ (phpBB Wiki)
The Wiki is a very useful resource for finding information about functions and classes within phpBB, as well as other information related to MODding.
http://code.phpbb.com/svn/phpbb/branches/phpBB-3_0_0/phpBB/docs/coding-guidelines.html (phpBB3 Sourcecode Documentation)
The official source code documentation for phpBB3.
http://www.phpbb.com/support/docs/kb/ (Knowledge Base)
The Knowledge Base contains many articles useful for MOD authors.