The phpBB file structure

I try to write at least one “tip” post a month. Today I want to dig into phpBB’s file structure. Looking at the folder and file names, a lot of it is self explanatory, but not all of it is.

To start, the file structure has two parts: data and software. Most of it is software which is replaced with upgrades or updates. But some of it is pure data and must be carefully avoided when upgrading or updating. Note that most of your content is actually stored in a database attached to your forum.

Data folders

There are three data folders:

• /files contains any files that are uploaded by users, with a few exceptions. Mostly these are images attached to posts, but sometimes they are documents attached to posts if permissions allow. If you allow attachments to private messages, they are also stored here. If you go into the files folder though, you will see file names that don’t look the least bit like images and lack the file suffix you would expect, such as a .jpg, .gif or .png. The file names look all scrambled, such as “2_09acd47ea11adef5e4d9cac2903e4ddc”. This is mostly a random hexadecimal file name created by the phpBB software. Its purpose is to hide the intent of the file. If a file represents a thumbnail, it is prefixed with thumb_. phpBB uses a database table, the phpbb_attachments table, and a program called download/file.php to actually render the file. file.php sends HTTP headers that tell the browser how to interpret the file, such as a JPEG image. It’s actually quite clever — security through obscurity! Unless you are on the forum reading a topic, you have no idea what the uploaded file name was, its file type, or who uploaded it. Moreover, you can only indirectly download it. You don’t want to tamper with this folder as it must be consistent with the phpbb_attachments table. Since uploaded files must be stored, this folder must have 777 file permissions.
• /images contains images, which is not too surprising but not any images users attached to posts, as they are in the /files folder. If you drill down into the folder you will see a bunch of subfolders that describe the content of images placed inside them, such as /avatars, /ranks and /smilies. If you allow users to upload an avatar, they are stored in the /images/avatars/upload folder, which is why this folder should have 777 file permissions. If you add rank images or smilies packs, they must be uploaded with FTP into the appropriate folder to be seen and used. In general, you don’t need to mess with this folder. Just leave it alone. But since there is no software inside it, it’s a pure data folder.
• /store contains miscellaneous files that may be created by phpBB. It is most often used to store an extract of your database, which you can do: ACP > Maintenance > Backup. If you recover your database, it will read the file placed here using the ACP > Maintenance > Restore function. It has occasional other uses. When upgrading or updating phpBB, lock files are created here. If things go awry you may have to manually delete them. Extensions that store data outside of the database may also write data here. These folders must be identified by the vendor and extension name. For example, my digests extension uses a /store/phpbbservices/digests folder.

Styles folder

The /styles folder can be considered a data folder, but only if you made custom changes to the styles. Your custom changes will get overwritten with a phpBB upgrade or update, or if you update a non prosilver style. As a general practice, you should backup all your folders and files before upgrading or updating. But if you made custom changes to a style, you really need to back these up and reapply them if desired after an update or upgrade. You might want to read my post on creating a custom style to minimize the impact of these changes.

Cache folder

The /cache folder hints on its function: it creates a “cache” of PHP scripts that speed up the process of rendering web pages. For example, your style creates a unique look for your site, so parts of the web page are actually a .php program placed here dynamically created by phpBB.

The cache folder is new since phpBB 3.0, but since phpBB 3.2 there are two major subfolders: /cache/production contains your “production” cache and /cache/installer is used during updating or upgrading phpBB. The cache folder itself must have 777 permissions so they can be publicly written to. The same is true with all folders and files inside it: folders must have 777 file permissions and files must have 666 file permissions.

When you click on the “Purge the cache” button in the ACP, you are destroying files in the /cache/production folder. If you accidentally delete files in the cache folder outside of phpBB, they will get recreated. You will notice a little lag rendering these web pages while the cache files are recreated.

Tip: if you get weird error messages that seem to lock up your board, use your FTP program or web host control panel file manager to delete the files and folders in the /cache/production folder. Often, the site will come back up with a page refresh!

config.php file

This is a critical file in your forum’s root folder that is essentially a data file and should not normally be messed with. Why? This joins phpBB software to your database, so it contains your database host server, name and the credentials of the account (including the password!) to your database. Consequently, don’t mess with this file unless you know what you are doing and do not allow it to be publicly readable. Ideally, the file will have 600 file permissions.

Tip: if you move from PHP 5.x to 7.x and you get a message saying mysql drivers are not supported, edit the line in this file:

$dbms = 'mysql';

changing to:

$dbms = 'mysqli';

and your forum should come up! PHP 7 does not support older mysql drivers and requires the newer mysqli (i is for “interactive”) drivers.

Software folders

With the exception of the above files and folders, all the other folders and files are software. I use the term “software” liberally. Technically, only PHP programs and Javascript files are “software” in that they implement programmatic logic. In reality though there are a host of technologies used to render phpBB including HTML, CSS, jQuery and XML. 

For the most part the folder name describes what they do, so I’ll concentrate on important folders.

• Principle programs. The principle programs are in the forum’s root file. For example, index.php renders the index and viewtopic.php assembles and presents all posts in a topic. Obviously you don’t want to edit any of these.
• /adm contains the styles used inside the Administration Control Panel. Except for the index.php program, the actual ACP software is in /includes/acp.
• /ext folder contains extensions. Extensions are additional functionality that developers write that does not come “out of the box” with phpBB. They are placed in an ext/vendor/package folder. For example, my digests extension if installed is in the /ext/phpbbservices/digests. The vendor is phpbbservices and the extension name is digests. These must be uploaded with FTP then enabled: ACP > Customise > Manage extensions
• /includes contains key support programs used by the principle programs.
• /language contains various language translations. British English is provided. If you install one or more language packs, they are uploaded to this folder. For example, a French language translation will be in a /language/fr folder.
• /phpbb contains a set of phpBB objects and services that “object-orient” phpBB. This object-orientation became system-wide starting in phpBB 3.1. Most programs in the /includes folder as well as the key programs use one or more objects or services in these folders.
• /vendor contains third-party software than phpBB needs to run. Since phpBB 3.1, phpBB has depended on a number of high-quality, 3rd-party software solutions. If you look inside the /vendor folder you can see all of them. For example, phpBB uses the /vendor/twig folder’s software for handing its templates, i.e. inserting dynamic data into web pages.

Hopefully this gives you a good idea of how phpBB’s file organization works.