phpBB • Free and Open Source Forum Software

To round out this series, we’ll look at the different categories of extensions that people like to download.

The list of extension categories is:

• Official Extensions
• Cosmetic
• Tools
• Security
• Communication
• Profile/User Control Panel
• Add-Ons
• Anti-Spam
• Entertainment
• Miscellaneous

Overview of extension categories:

It’s worth mentioning that the download figures will not add up to the total extension downloads from part four, because some extensions belong to more than one category.

Add-Ons are the most popular type of extension, most likely due to their broad nature, with all of the top 10 most downloaded extensions belonging to this category (among others).

Official Extensions get downloaded in huge numbers due to their high profile, while some of the most downloaded extensions like Board Announcements and Advanced BBCode Box 3.1 belong to the Communication category.

Interestingly Anti-Spam extensions don’t feature highly, but with that said it’s probably a good thing if additional measures are not required to keep the spambots at bay.

This brings to a conclusion the phpBB Numerology series. I hope those that appreciate their statistics – or have a general interest in phpBB and its user submitted customisations – have enjoyed these last five blog posts.

MODs, extensions and styles are what immediately come to mind when thinking of the phpBB.com customisation database, but there are other types of customisations too.

This part of phpBB Numerology takes a look at every type of customisation.

Overview of all customisation downloads:

There are some obvious anomalies in the data (like the Viewtopic Birthday MOD) which haven’t been removed from this raw analysis. With that said, this data still gives a fairly accurate representation of how people use the customisation database.

The first figure that sticks out in this table is the the 52.02 views per download for bbCode. This is disingenuous. Taking the fairly popular bbCode “Open URL in new window” as an example, it’s had 8026 views and 0 downloads. Why is this? Because there is nothing to download – the instructions are on the main contribution page: https://www.phpbb.com/customise/db/bbcode/open_url_in_new_window/

MODs, due to their prevalence in the phpBB2 and phpBB 3.0 era, are still the undisputed king of the customisation database and will take some catching up. Styles may catch up in the medium term though, as it’s a forever expanding customisation type in phpBB 3.1.

It’s not surprising to see phpBB tools well represented on the list. AutoMOD and UMIL alone represented 208757 and 151820 downloads respectively – very popular tools. Converters and Bridges round out the top 8, being quite niche categories.

As noted earlier, the figures may be a little high due to anomalies but after taking into account off-site downloads through development topics and the like the numbers may actually be conservative. It’s therefore very pleasing for everyone involved in the phpBB community, and something to be very proud of, that phpBB customisations have exceed 15 million downloads.

For the fifth and final part of phpBB Numerology we’ll go back to where it all started – extensions – and take a closer look at the categories of extensions that are most popular.

For the second blog post in this series I thought it would be interesting to do a direct comparison with the data presented in the 2011 post.

Most downloaded phpBB3 MODs:

There are a few figures which are unrealistic, which have been struck out accordingly. For example, “User recent activity” apparently has nearly 80,000 downloads while its customisation page has only had 5300 page views.

The most significant movers and shakers were the Advanced BBCode Box 3 MOD, which had a huge spike in downloads in moved up 18 positions from 2011. The ReIMG Image Resizer also experienced a spike, but due to its favourable position in 2011 only moved up 7 places. None of the top 10 from 2011 experienced large drops.

Most downloaded MOD/extension authors (primary authors for phpBB2 and phpBB3):

Due to the overwhelming successes of the Attachment MOD and Cash MOD for phpBB2, both Acyd Burn and Xore remain among the most downloaded phpBB MOD/extension authors of all time.

nickvergessen is the third most downloaded author of all time, despite not having any entries in the top 10 downloads for an individual customisation. This is because two of his submissions are/were highly popular and fall just outside the top 10 of their respective lists; phpBB Gallery for 3.1.x has 57,070 downloads while NV advanced last topic titles for 3.0.x has 49,372 downloads.

In part three of this series, we’ll look at the most downloaded language packs for phpBB which will also offer some insights into which regions phpBB is most popular.

Most downloaded phpBB3 extensions:

Every now and then a question pops up in the discussion forums about which MODs are most essential for board owners to install. It’s difficult to answer this question for one key reason; what is essential for one admin may be trivial to another. It all comes down to personal preferences and the unique needs of a particular bulletin board. Unfortunately, while this response is accurate, it still leaves enthusiastic new administrators without any answers.

The purpose of this blog post isn’t to provide a definitive answer to the question, but more to provide something of a starting point for users beginning their search for suitable MODs… or something to munch on for the statistically inclined!

Number of downloads is the primary piece of data used in the calculation of the statistics below. There is no way of knowing exactly how many times a MOD has been installed so the number of downloads is the best option available to reasonably estimate a MODs ranking in terms of total use in the wider community.

Due to the overwhelming success of the Attachment MOD which provided functionality for file attachments in the early-to-mid 2000’s, Acyd Burn remains – and will remain for the foreseeable future – phpBB’s most downloaded MOD author.

If anyone reading this is feeling nostalgic, you may also be interested in the figures for phpBB2 MODs. Quite conceivably (and conservatively), at its peak the Attachment MOD averaged over 200 downloads per day.

Most of you have probably already seen the blog post regarding the RFC process for hook locations to be added to Ascraeus (phpBB 3.1). And many of you may not know what a hook system actually is, so I will take the time to explain it.

In Olympus (phpBB 3.0) all new additions to the core must be made by editing or patching the core files. The MODification is either installed manually or by using AutoMOD. What a MOD usually does is add some specific code at a specific location, this ranges from database queries, template assignments and loading of language files to any custom PHP code. Now, this approach worked for 2.0 and it works for 3.0, but frankly it produces a horrible mess. Installing MODifications is a great pain, uninstalling them is almost impossible in many cases.

To solve this issue we are introducing a hook system. The hook system defines code injection points, giving each one of them a unique identifier. The hooks controller allows MODifications to bind to a specific code injection point or hook location. When that point is reached in execution, the hooks controller will call all of the hooks that registered, passing in the context, so that local variables can be read and/or modified by the hook, thus “injecting” the hook into that location. Technical details can be found within the General Hook Architecture RFC.

Automagic

To remove the need for any core edits the files defining and registering hooks will be automatically loaded. They will be in a certain folder that phpBB will scan regularly. This will hopefully make the whole MOD installation procedure automagic. You drop in the files and are ready to go.

To make the registering of hooks more convenient, MOD authors will be able to define a class of which each method represents a hook.

This allows all hooks belonging to a certain MOD to be grouped within one file that can be automatically loaded and registered.

Example

Here is an example with code. Note that this API may change since it’s not final yet. The hook location will be in user_add as described in this RFC topic ([RFC] user_add hook).

We will create a file called hook/logging.php (convention will change) containing the following class, which will be loaded automatically by phpBB.

Code: Select all

class phpbb_mod_logging
{
public function user_add(&$sql_ary, &$cp_data)
{
file_put_contents('registered_users.txt', time() . ": " . $sql_ary['username'] . "\n", FILE_APPEND);
}
}

Since we want to hook into user_add and the RFC describes the input arguments as $sql_ary, $cp_data (by reference), our hook will have to take those arguments. In this example we will write the unix timestamp and the username of every new user into a log file. This happens right before a user is created.

The user_add() function will execute all ‘user_add’ hooks before inserting the user. While we are only reading the arguments here, it is also possible for hooks to modify them.

Under the hood

So, how does this work? Let’s take a look at the engines that power this. These are mostly internals of the hook system that you will not have to deal with, because it is all taken care of by phpBB.

Before we can do anything hook related, we need to create a hooks controller. The hooks controller manages the hooks and makes sure all of them are called. All hook-related actions go through this class.

Code: Select all

// create the hooks manager
$hook_handler = new phpbb_hooks_controller();

In phpBB this controller is automatically loaded, and there is also code that will load all the hook files (hook/*.php). It registers the hook containers of those files with the hooks controller.

Moving on to the actual hook invocation. Within the actual user_add function, you will find the following:

Code: Select all

// call hooks
$hook_handler->invoke_hook('user_add', array($sql_ary, $cp_data));

This calls all hooks that bound to ‘user_add’, passing the two arguments into them. There will be quite a few of these hook locations to take advantage of, and they will always provide a context that you can work with.

As a MODification author you will also be able to provide your own hook locations to other MOD writers. All it takes is a call to invoke_hook, which will allow others to hook into your code.

There are some more advanced features about hooks, such as (un)installing, enabling/disabling, prioritising hooks. But I’ll save that for later.

In summary

• class with methods representing hooks
• invoke_hook will call all hooks that registered
• hooks are automagic

So now that you understand the basics regarding hooks, I hope you can look forward to this great addition in ascraeus and help us by contributing Hook Location Requests.

This article was written primarily for MOD writers interested in ways to optimise testing. Everyone has their own style of testing which works for them, and this is only one such style.

A good way to test MODs is by using a local setup. A local setup is an installation on your own computer or network, as opposed to a remote setup which would typically be your website (as it is hosted by another company in a “remote” location). This means that less time is spent uploading and downloading through FTP as any changes you make take effect almost instantly. An added benefit is you can continue developing and testing your modifications when you are without an internet connection.

There are many types of software which will allow you to create a local setup, such as XAMPP and EasyPHP. What these programs do is install PHP, a database like MySQL and Apache in their own sandbox which only runs when you start the program. For the purposes of this article, I will look at EasyPHP.

Installation instructions can be found at http://www.easyphp.org. Once EasyPHP is installed, in Windows Explorer navigate to the local web server directory. In the case of EasyPHP v2.0b (and depending on how you configured the software during installation) then it might be C:\Program Files\EasyPHP 2.0b1\www

Now that EasyPHP is set up, a quick way to install phpBB3 is to use phpBB QuickInstall (by tumba25 and evil<3). Of course, you can simply install phpBB3 as you would normally – but for the purposes of testing MODs by using QuickInstall there is the added flexibility of being able to install multiple boards very quickly (such as if you wanted to have a separate test board for multiple MODs).

QuickInstall is very easy to use, simply download it from http://www.phpbb.com/mods/quickinstall/ and extract the zip file. Create a new directory in the EasyPHP local web space (www) called quickinstall and copy all of the extracted files into this directory. Then in your web browser, go to http://127.0.0.1/quickinstall/index.php – you should see a page like this:

Once you have filled in the forms and pressed submit, QuickInstall is configured and ready to use. This means you can now create test boards. To do this, go to the Main Page tab and fill out the options in the forms provided. When you get to the setting where it asks to install AutoMOD, make sure you select “Yes”.

It will take a few minutes to install and copy the files across to the new directory (in this case “test”).

Once this is has happened, the browser will automatically redirect you to the newly installed phpBB3.

Once this is done, if you have already written (or partially written) a MOD then you can install it on the test board. Installing your MOD is a simple matter of navigating to the Administration Control Panel (ACP) and clicking the AutoMOD tab. From here, providing your MOD is in the correct MODX format and can be read by AutoMOD, the MOD will be installed very quickly.

If the MOD installs correctly, you will see a message like this:

Now your MOD has been installed. If you have yet to start writing your MOD then you can edit the files directly, as mentioned above this is a huge time saver. In this example, the test board is located in C:\Program Files\EasyPHP 2.0b1\www\quickinstall\boards\test – so the files that require editing can all be found in that test directory.

Note: if you ever want to delete a directory this can be done very easily by navigating to the “Manage Boards” tab of QuickInstall and selecting the board, and clicking delete. There is no confirmation message, so be sure that you want to delete it before proceeding.

There are some other useful tips to bear in mind when running a test board.

The easiest way to check the performance of the script (the MOD) is to enable DEBUG and DEBUG_EXTRA in config.php.

@define(‘DEBUG’, true);
@define(‘DEBUG_EXTRA’, true);

QuickInstall enables this by default. To turn this off is as simple as commenting those lines out.

The purpose of DEBUG is to show page load and simple query information in the page footer:

DEBUG_EXTRA is very similar (and only works if DEBUG is enabled), except it shows the explain link:

Clicking the explain link leads to the SQL report page, which lists database query information:

It is worth noting that DEBUG and DEBUG_EXTRA can be used on individual pages. If you don’t want that footer information appearing everywhere, then you can comment out those two lines in config.php but include them at the top of the PHP file for any individual page. For instance, if the lines were commented out of config.php but included under the <?php line of index.php – then the debug information would appear only on the index page.

Another useful benefit of enabling DEBUG is to see PHP notices. For instance, suppose I included the line echo $dog[6]; at the top of index.php. If DEBUG is disabled then the script will run error-free, despite that variable never being defined.

With DEBUG enabled, the PHP notice will be shown. This is important because it does reduce the amount of mistakes and potential bugs in code. (Note: the PHP notices can be shown with DEBUG disabled if you include error_reporting(E_ALL | E_NOTICE); in the file. This is handy if you want to see the notices, but for whatever reason do not want the additions to the page footer).

When dealing with cached database queries, during testing you might want to clear the cache (or at least clear any cached queries relevant to your MOD). You may or may not want to remove this code once testing is complete, depending on the MOD. By including the line $cache->destroy(‘sql’, MOD_TABLE); you can remove any cached queries relating to the specified table (you would change MOD_TABLE to the constant of whichever table you want to clear the cache for).

When making changes to the template, it is very annoying to have to Purge Cache after each change. Fortunately this can be made a lot easier, by going to the Server configuration -> Load settings page in the ACP and setting “Recompile stale style components” to Yes.

Remember to exercise caution when editing templates though. It is always better to edit the html files directly instead of editing the templates from within the ACP. Edits from within the ACP are stored in the database, they don’t physically change the file. Therefore if you have made edits in the ACP to a given file, then if you edit that file directly in the future the changes you made within the ACP will be lost.

I hope this article has been of some help. If you already enjoy writing MODs, now you can enjoy testing them as well!

An easy way to add navigational links to your MOD is to use an inbuilt feature of phpBB3 called “breadcrumbs” (named because it leaves a trail back to the forum index).

It only requires a few extra lines of PHP code to add a breadcrumb to your own MOD (or to your website if you are doing personal customisations). This article explains how to do so.
Read the rest of this entry »

What is a Junior Validator?

Junior Validators assist the MOD Team with the validation of MODs. They help the MOD Team validators with pre-validation and testing.

Pre-validation involves running a check on MODs newly submitted to the MOD Database queue using the MOD Pre-Validation tool (MPV) and setting a status on the MOD accordingly.

Testing is the major role of a Junior Validator, and requires installing the MOD on a vanilla phpBB3 board through AutoMOD. After installing the MOD, all functions of the MOD and board should then be tested – all to make sure that the MOD and the board run error-free. The Junior Validator then makes any notes or suggestions to the MOD Team concerning the MOD and, again, the MOD status is set accordingly (“approve”, “deny”, “repack”, etc). In a nutshell, this is the role of a Junior Validator.

Why should I become a Junior Validator?

As a Junior Validator you will be gaining valuable first-hand experience with MOD Team processes which could lead to consideration for a position on the MOD Team. You will also have access to private forums including a Junior MOD Validators forum where you can discuss MOD validation with fellow Junior Validators and MOD Team members.

Most importantly, it will be fun! If you have a passion for writing MODs you will find working with the MOD Team to help validate MODs, and also the opportunity to give something back to the community, very rewarding. The phpBB Team is a very friendly group of people so the chance to work closely with the MOD Team will be very enjoyable.

What are the requirements?

To be considered for a position as a Junior Validator, it is important that you:

– have authored a MOD and submitted it to the MOD Database.
– can communicate in English.
– understand the phpBB3 codebase.
– have an understanding of MODX and MOD policies
– are familiar with the MOD Validation checklist

Where can I apply?

To apply, please fill out the form at the bottom of the Junior Validators page and your application will be reviewed by the MOD Team shortly thereafter. Successful applicants will be notified by private message on phpBB.com.