Blog

Posts Tagged ‘Development’

Attention developers: GitHub Codespaces enabled in phpBB!

Posted by battye in Development with the tags , , , on February 4th, 2023

If you’re a PHP developer, you’ll know that setting up a new development environment can be annoying and time consuming! You have to find a code editor, you have to install a web server like Apache, a database and PHP. Even if you’re using some virtualisation software like Vagrant or containerisation software like Docker to simplify the process, it still takes up time that you’d prefer to spend coding.

Enter: GitHub Codespaces.

The tech world is moving towards the cloud at a rapid pace and software development is no exception. A web-based project like phpBB is a good fit for cloud development and while a local development environment is wonderful, the ability to quickly code and test changes on any device with a browser is nice to have in the arsenal.

Codespaces includes a web-based code editor (VS Code) as well as a virtual machine which can be used to run software. Effective immediately, the phpBB project on GitHub contains a pre-configured Codespace with a LAMP stack and XDebug, allowing developers to modify and debug a vanilla board which is already automatically installed.

This tutorial explains how to:

  • Create a GitHub Codespace with an automatically created fresh installation of phpBB
  • Use a Codespace to make a code change to phpBB
  • Use XDebug to debug phpBB code in real time

Step 1

See if there is a ticket in the phpBB issue tracker describing the problem you would like to fix or the feature you would like to add. If there is not an existing ticket, you can create a new ticket, logging in using your phpBB.com login details.

In this case, we’ll look at a simple bug that was raised at https://tracker.phpbb.com/projects/PHPBB3/issues/PHPBB3-17025 – the number 0 appears as the default topic ID on the MCP move posts page, but there is no valid use case for this because it is an invalid ID. We will use this bug (resolved here) to demonstrate how GitHub Codespaces works and how it can be used for phpBB development.

The reporter provided some valuable information which acts as a good starting point, namely that the bug is on line 76 of prosilver/template/mcp_topic.html. We will come back to this in Step 3.

Step 2

Create a new branch on your own fork of phpBB. If you have never done this before, the procedure is outlined at https://area51.phpbb.com/docs/dev/3.3.x/development/git.html

Then on GitHub.com, create a new Codespace for this branch. It will already be preconfigured from the code in the phpbb/phpbb repository.

screenshot_create_codespace

This will create a brand new installation of phpBB with XDebug installed to assist developers.

Step 3

From the online VS Code website, which looks almost identical to the desktop version of VS Code, click on the files icon and navigate to mcp_topic.html – or use the shortcut Ctrl+P to search for the file.

screenshot_file_search

By looking at line 76 of that file, we can see that the “value” attribute listed in the ticket is set to a variable called TO_TOPIC_ID.

Using the Ctrl+Shift+F (global search) feature, if we search for that TO_TOPIC_ID variable we can see that it only gets used in one other place.

screenshot_global_search

Double click mcp_topic.php to open the other place where that variable is used – line 386 of the file.

The template variable is set to take the exact value of $to_topic_id.

Step 4

Using the power of XDebug, we can debug the issue in real time. Using the Ctrl+F (local search) feature, we can see where $to_topic_id is declared and how it is used.

On line 52 it takes input from the URL – and defaults to 0 if the parameter isn’t supplied in the URL. On line 357, it is forcibly set to 0 if a certain condition is met.

Line 376 is the best place to see XDebug in action though. Left click once just to the side of the line number so that a red breakpoint appears. A breakpoint is used to identify where execution should temporarily halt during debugging.

screenshot_breakpoint

Step 5

Now that a breakpoint has been set (you can set as many breakpoints as you wish), debugging can be turned on by clicking the “Run and Debug” button and then the green play button beside “Debug phpBB”.

screenshot_debug_on

Step 6

At this point, debug mode is active. Under the Ports tab at the bottom of screen, click the “Open in Browser” button and the fresh phpBB installation will open.

screenshot_open_site

Log in to the board with the credentials admin/adminadmin and, for the purposes of this example, add some posts and topics so that posts can be moved in the MCP to replicate the original bug.

Step 7

When the move posts page of the MCP is loaded, the XDebug breakpoint will automatically be hit – meaning the execution of the page is paused at that point to give developers the chance to analyse the code before it has finished running.

The browser tab will show a small red circle to indicate a breakpoint has been hit. Within VS Code, the line will be highlighted as well.

To identify the value of the variables at the point the execution has paused, either hover over a variable (like in the case of $to_topic_id on the right of screen) or look at the variable list on the left of screen.

screenshot_hit_breakpoint

Step 8

From this information, we learn that $to_topic_id is set to 0 as a default and it has been done intentionally. So to fix the bug of 0 appearing by default in the template, we don’t want to refactor the entire file and potentially introduce a new problem.

The sensible approach is to just change the way the value is passed to the template because, as we discovered from the global search in Step 3, the template variable does not get used anywhere else.

Using the ternary operator we can make a simple change so that the template variable declaration reads as:

‘TO_TOPIC_ID’ => $to_topic_id ?: ”,

This means that if $to_topic_id evaluates to true (the integer 0 does not evaluate to true, but if a valid topic ID is passed through the URL as explained in Step 4 it does evaluate to true), then $to_topic_id will be passed as the default value to the input field – otherwise, an empty string will.

Step 9

By returning to the tab with the phpBB board open, we can confirm that the fix is working as intended.

screenshot_bug_fixed

Step 10

Satisfied that the fix is correct, we can now commit and push the change to the local branch. This is easily done in VS Code, simply click the “Source Control” tab and stage the change to mcp_topic.php (the file we edited) by right clicking it and clicking “Stage Changes”.

Type a commit message in the box (using the format described at https://area51.phpbb.com/docs/dev/3.3.x/development/git.html), and then select “Commit and Push” from the dropdown option.

screenshot_commit_push

The list of files in the install directory can be safely ignored – they are deleted when setting up the Codespace to allow phpBB to run normally.

Step 11

Finally, create a pull request on GitHub.com from your local branch to either the phpbb/phpbb 3.3.x branch or the master branch. phpBB’s GitHub Actions will run unit tests, ensuring no features were broken accidentally as a result of the change, and then the development team will review the code.

And with that, it becomes clear that GitHub Codespaces is a really handy tool to be aware of and which can be used to easily and powerfully make code changes for phpBB.

Vote For phpBB’s Next Codename

Posted by MattF in Development with the tags , , , , , on October 16th, 2016

At phpBB we love codenames as much as we love Bertie.

Previously we have travelled to Mars and Saturn to find the most prominent features to name our versions. Now it’s time to come up with another codename for the version of phpBB.

In line with having an open mind for new features, looks, and changes in phpBB’s next major version we’re also opening up the decision on the codename to the community.

The phpBB Team has already pre-selected four possibilities from a rather long list.

Now it’s time for you, the community, to have the final say:
[Vote] Codename of next phpBB version

The vote will end in two weeks on October 30th, 2016.

Happy voting!


 beer_bertie

phpBB 3.2 Rhea is near – help us test it now!

Posted by naderman in Development with the tags , , on March 26th, 2016

On October 28th, 2014, we published phpBB 3.1 Ascraeus, the culmination of nearly 8 years of development since phpBB 3.0—an eternity when it comes to web development. We learned our lesson from trying to build a major feature release over a timespan that saw major changes in web technologies; while our roadmap had to change frequently, none of the progress was made available to you—our users. When we finally released phpBB 3.1, I announced that phpBB would from now on see feature releases on an annual basis.

It has now been one year and 6 months since I made this statement. Our most recent release has been phpBB 3.2 Rhea 3.2.0 Beta2, on March 7th 2016. So we missed our goal, but we’re well on the way to reaching a new stable feature release before summer this year. We’ve been making great progress with tweaking our workflows to more strictly adhere to the schedule in the future.

As the Development Team Leader, I updated you much too infrequently on development progress, partly due to having many other tasks to also focus on. Unless you follow our development forums at Area51, or our social media accounts on Facebook or Twitter, you are unlikely to have heard of our recent 3.2 Beta releases. As these responsibilities exceed what a single person can do well, Marc Alexander stepped up in February to take over the Development Team Lead position. From now on, I will be responsible for more frequently informing you of all developments regarding phpBB, as its new Product Manager.

We are looking forward to your feedback on the Beta releases and upcoming final release candidates of phpBB 3.2 Rhea.We cannot produce a stable final product without your testing and bug reporting. Download Beta packages from our archive at https://download.phpbb.com/pub/release/3.2/unstable/3.2.0-b2/. Please keep in mind that you should not run this version of phpBB on your live sites yet, and no support will be offered until the RC phase.

If you’d like to get involved with phpBB development to help us finish new features faster, check out the information available on Area51. And lastly, if you’d like to stay up to date on phpBB development progress, follow this blog!

phpBB Developer Documentation

Posted by nickvergessen in Development, Extensions with the tags , , , on July 5th, 2015

When the phpBB Team met in Prague last month for a short productivity meeting we achieved many things. We fixed bugs, worked on our bamboo infrastructure, reduced the size of the extension validation queue and worked on a new phpBB/Symfony Authentication bridge however one of the most significant things we did was start the base of our new developer documentation:
https://area51.phpbb.com/docs/dev/31x/

The plan with this documentation is to consolidate all core and extension development related information that is currently spread out on our wiki, Area51 (and a variety of other places) into one central location.

As a first step the “[HowTo] Convert a 3.0 modification into a 3.1 extension” tutorial was converted and is now available to view here.

Since then, we have ported over many many other Wiki pages and readmes to the new doc system including:

The documentation is written using rst and our documentation source can be found in the “development” folder of our pre-existing documentation repository: https://github.com/phpbb/documentation/

We will be continuing to move existing documentation over the coming months and if you are familiar with rst and git(hub) and want to help, please do feel free to send pull requests. Whether it is with porting existing documentation over, fixing typos or even writing brand new pieces of documentation, every contribution is appreciated.

Google Summer of Code 2012: Authentication Plugin Refactoring and User Integration

Posted by Hardolaf in Development with the tags , , on July 16th, 2012

During Google Summer of Code, I have been working on refactoring the authentication system (login and registration) to allow for login via OpenID providers and Facebook Connect [code]. The system’s old authentication plugins (db, ldap, apache) have all been ported to the new authentication provider system and can be enabled/disabled via the administration control panel. Currently, OpenID is implemented using the Zend Framework 2 OpenID package. The Zend Framework 2 OpenID code, currently does not allow login via Google (a popular OpenID provider), however, support for login via Google should be available by the end of Google Summer of Code. The user interface has been nominally changed from its previous look, however, additional changes to the interface will be made to make logging in via various popular providers more convenient for users.

The current (temporary) login box design.

The current (temporary) registration design.

As can be seen from the images, not much work has been done on styling the interface. It currently is focused on functionality for use in tests. The design of the interface will undoubtedly change before the end of Google Summer of Code.

For the remainder of the summer, I will be implementing login via Facebook Connect and potentially (time permitting) adding general support for OAuth2.0 providers. I will also be writing a wrapper class that will handle old authentication plugins so that they will continue to work while they are being transferred over to the new provider system.

I look forward to continue working with my mentor, Nils Adermann, on the remainder of the project. It has been a great experience so far contributing to phpBB, and although I’m am uncertain of how much time I will be able to commit after this summer, I look forward to continuing to work with phpBB and its community.

Google Summer of Code 2012: Search Backend Refactoring

Posted by dhruv.goel92 in Development with the tags , , , , on July 14th, 2012

During Google Summer of Code, I have been working on Search Backend Refactoring. The project involves minimizing code duplications by improving class abstraction in search backends and integrating PostgreSQL fulltext search [Code] and Sphinx search [Code] into phpBB core. Up till now, the progress has been good with PostgreSQL fulltext search backend already integrated into phpBB 3.1 and Sphinx backend nearing completion too.

The project has been a great learning experience. Apart from learning the various features of Git, I have been able to understand the basics of PostgreSQL and MySQL Databases more clearly. I was introduced to Sphinx during the course of project and honestly I was quite impressed by its performance. All boards running on MySQL and PgSQL databases will soon be able to switch to Sphinx search backend for faster indexing and searching.

Next I intend to start code refactoring and fixing bugs in multiple search backends to provide better search functionality to both users and administrators (by exposing more options in ACP). I will also be writing automated tests side by side to ensure search functionality continues to work correctly.

All this has been possible only because of the timely help I have received from mentors and other team members. They have been patient and appropriately guided me at all times. The overall development experience in the phpBB community has been fantastic, I would love to remain involved and contribute even after GSoC.

Google Summer of Code 2012: Attachment Improvements

Posted by Fyorl in Development with the tags , , , , on July 4th, 2012

During the Google Summer of Code I’ve been working on improving the current attachment system to have a bit more of a modern feel to it. I’m integrating Plupload which has a variety of features such as drag-and-drop, multiple file uploads and an upload queue.

The work has been pretty straightforward and I’ve been getting a lot of help from mentors and other team members so I’ve made considerable progress in a short time. The following screenshot shows Plupload integrated with phpBB and you can also look at the code itself in my pull request:

Plupload integration

By the end of it, phpBB users (with modern browsers) should be able to enjoy a much smoother attachment experience without a bunch of page refreshes interrupting their posting or waiting ages for a file to upload only to find out it was too big.

It’s not my first time contributing to an open source project but, surprisingly, one of the most useful things I’ve learnt is actually how to use git properly. There are a huge number of really useful features that I’ve never had to use until I started contributing to a project of this size. It’s given me more than my fair share of headaches and some of my activity history on github is a bit embarrassing now but everyone’s been really patient and helpful and I like to think I’m starting to get the hang of things now.

I’m having a lot of fun and intend to keep contributing to the project long after the GSoC has finished.

Help Us Automate phpBB Testing

Posted by imkingdavid in Development with the tags , , , on May 22nd, 2012

Automated Testing is a vital part of the development cycle, as it decreases the amount of time developers must spend making sure certain functionality works, and prevents new patches from breaking areas of functionality that are covered by the test suite. As you may have guessed, Automated Tests are simply sets of functionality tests that are automatically run as new features are developed, bugs are fixed, and changes are made to the codebase. Nothing is merged into the core phpBB repository without ensuring that whatever changes are being made do not break any existing functionality. If any tests fail, the developer is able to save time and energy that would have been spent later on, when a bug report would have been filed, by finding the problem and fixing it up front. Not only does this help by increasing the efficiency of the development cycle, but it also improves the quality of the software as a whole, because we can be certain that all features work as intended without having to manually test each one every time something is changed.

That sounds great, doesn’t it? Well, it is. The only problem is, only a very small portion of the code is actually covered by tests. One reason for this is because the automated tests have not been around for as long as the phpBB3 codebase, so they have had to be written long after the features they are testing have been merged, rather than in conjunction with the features themselves. Another reason is that there are two types of tests that need to be written: unit tests and functional tests.

Unit tests are simply tests that attempt to run certain peices of code that do not require a webserver or phpBB installation to work. These tests are generally easier and faster because all of the information they need is readily available and hardcoded into the test suite.

On the other hand, Functional tests are needed to run functionality that requires a phpBB installation. For instance, if you want to test whether an authentication plugin works, you have to actually be able to test logging into a board. For that, you need a database with a user account. You also need to be able to test that a cookie is sent. Unit tests cannot handle that, but Functional tests, are able to simulate browsing and using the forum almost just like a normal user.

However, functional tests cover even less of the code and functionality than unit tests do, and time that is spent writing functional tests is time that is not spent writing new functionality or expanding on existing functionality. So while we need functional tests to reap the benefits I explained above, it does not make sense to devote all of our time to writing tests and therefore have a significant “dry period”, during which no new or changed functionality is incorporated into the software.

This is where you come in. I, like many of you, was kind of intimidated when I first started to contribute to the core of phpBB. I felt much safer writing MODs because I knew my work would not be scrutinized as much as if I were to submit a patch to the core (that is not to say that the MOD team does not carefully review each and every MOD, but rather, that my code would likely not be viewed by as many people and would not be held to as high a standard). However, I found that by writing functional tests, I not only was able to contribute to the betterment of the software, but I also was able to better learn how things worked and how I could therefore use the things I learned in not only my MODs but also my core patches.

So all of that to say, there is plenty of work to be done and we would love to see contributions to our test framework from our vast, talented phpBB community. As I said, these contributions help not only the software and phpBB community as a whole, but also can give you the knowledge and skills you need to improve your MODs and, should you decide to, your patches to the phpBB software.

There is a wealth of information in the phpBB Development Wiki (see Automated Tests) to get you started with writing and running tests. And if you have a question or need help understanding how to do something, you are welcome to ask me or another developer in the #phpbb-dev IRC channel.

Explaining Hooks

Posted by igorw in Development with the tags , , , on October 9th, 2010

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.

phpBB “Ascraeus” 3.1 Feature Freeze

Posted by naderman in Development with the tags , , , , on July 20th, 2010

Yesterday marked the announced feature freeze date for phpBB Ascraeus 3.1. We have postponed this date once before and we are still a bit behind schedule, but we will stick to it this time. We have picked a number of features with unfinished implementations or still in RFC phase which we believe to be very important and which can be realistically finished in time. We are still learning to work with our new development model and I’m sure we will improve until the phpBB Arsia 3.2 release. All features that are implemented or suggested after today are going to have to wait for phpBB Arsia 3.2 to become part of phpBB (small exceptions may be made).

As you can see from the list below this release is going to focus on improving a number of existing features as well as improving MOD installation & MOD writing. The following is the list of features and improvements for 3.1 in no particular order:

Merged:

Patch in progress:

RFC only:

  • Migrations (UMIL) RFC Ticket Data Providers RFC
  • Changing IP banning to use ‘longest prefix matching’ RFC Ticket
  • Ability to delete auto login keys RFC Ticket
  • Authentication Plugin Refactoring, User Integration & OpenID RFC Ticket
  • Session Backend Abstraction (memcache support) RFC Ticket
  • Search Backend Refactoring RFC Ticket
  • Pre-Compile Template Includes RFC
  • Overridable imageset and theme paths for CDNs RFC

I would like to thank the rest of the development team for their work so far, and am looking forward to to finishing the first release of Ascraeus together with them. A special thank you goes to all the other volunteers who have brought great ideas to the proposal process and have provided us with high quality patches. They have really made me appreciate our active community and I’m looking forward to more collaboration during the next steps toward 3.1. You can find a list of all the contributors who have written code that was already merged at github This list will gain in length over the coming months as more of the proposed changes are merged.

Please discuss this blog post on the forum.