phpBB upgrade 3.1.5 to 3.2.7 - NOT as easy as it used to be

OK, the automatic update of phpBB has gotten us and many inexperienced users used to the simplicity of phpBB upgrade... However, this was not the case with my upgrade from 3.1.5 to 3.2.7... and many forum posts were unclear at best or misleading... Here is a much more detailed upgrade procedure.

1. Read this procedure IN ITS ENTIRETY before beginning any work.

2. Dedicate an absolute minimum of four hours to this... Don't do at 11PM if you have to go to work the next day...

3. Make sure you satisfy all phpBB version 3.2.7 requirements (PHP and database version, etc, etc).

4. You want to take your site down in a manner that lets your users know you are performing maintenance, or see point X below for an alternative to this...

5. BACKUP BACKUP BACKUP. I usually perform at least FOUR backups:

5A. A backup of database to an .sql file, this is explained very well elsewhere on my website...

5B. A full FileZilla download to my computer, preferable to a *nix filesystem like EXT4 rather than NTFS (to retain all file properties).

5C. Using SSH, perform a folder copy to your server. This is also very useful for an alternative solution where you copy your PRODUCTION server/folder to a DEVELOPER/MAINTENANCE location, test your upgrade skills on the DEVELOPER server/installation folder (note that config.php would have to be modified to reflect the different root path...), test the upgrade, LEAVE THE PRODUCTION FOLDER INTACT, and rather just transfer your domain pointer to the tested upgrade... This results in a tested, fail-safe upgrade, that also appears nearly "instantaneous" to your end-user when the domain pointer update takes place... This is BY FAR the best way to perform any work on a server that has more value than a mere curiosity just to yourself...

ssh [login settings]

cd [navigate to root server folder if necessary]


(all commands, command parameters, folder names, and file names are CASE SENSITIVE in *nix!)

5D. Finally, I also create an archive .tar.gz (or bz2) using SSH for archival / backup purposes...

tar -czvf name-of-archive_date.tar.gz /pathtodirectoryifnecessary/directorytobearchived


6. Then, you need to head over to the MCP and find out your current version, which is 3.1.5. Then, find out the latest version, which as of writing is 3.2.7.

7. Spend a little time to read RELEASE NOTES, INSTALLATION NOTES, and forum complaints and issues reports (this is why a seasoned web developer generally DOES NOT install any update on day one of its release... wait a month or two for others to find out all the issues first...).

8. If you changed ANY .php files other than configuration files on the server you SHOULD NOT do a full update otherwise you will wipe out your custom modifications to files... I happen to know that I DID make a few modifications to a few files, but I don't remember exactly what those changes were...

9. Grab the Automatic Update DIFF file with wget (really, why would you download a file from your browser, only to upload it to your server over a very slow UPLOAD data link???). First, you have to enter your current version here to get the file link. Use the Automatic Update tab. Right-click on bz2 file and Get Link Location.

ssh if necessary

cd to forum server folder if necessary


10. Uncompress the file into your forum directory

tar -xjvf phpBB-3.1.5_to_3.2.7.tar.bz2

This will create directories called install and vendor.


11. If you now visit your forum, you will see error:

Catchable fatal error: Object of class Twig\Source could not be converted to string in /PATH/phpbb/template/twig/lexer.php on line 142

Just ignore the error! Instead, you have to go to /install folder instead (

BTW, this error is idiotic. A SITE DOWN message should be shown to your website visitors instead...

12. The update screen should appear.  Click on Update tab.


Perhaps because the FTP settings screen is idiotic and unintuitive (I have very high suspicions that I am not entering Path from the root to your phpBB board. correctly)...


13. OK, files will be checked for updates now. PAY ATTENTION TO ANY FILES LISTED IN Conflict files and Modified files sections!!! These will cause an error later!


14. Clicking on Update Files I get an INSTANT red error screen:

The installer detected a timeout

The installer has detected a timeout, you may try to refresh the page, which may lead to data corruption. We suggest that you either increase your timeout settings or try to use the CLI.


Well, if you got the same error, bummer you have to backtrack. The only way you can backtrack the installer if you remove the file store/install_config.php and try upgrader again with the Update files via direct file access (Automatic) option instead...


15. You better have the "The installer has finished successfully…" message with multiple green lines above it... At least this path worked for me!


16. Now navigate to your forum URL. You may see a very nasty

500 Internal Server Error

Internal Server Error

The server encountered an internal error or misconfiguration and was unable to complete your request.

Please contact the server administrator at to inform them of the time this error occurred, and the actions you performed just before this error.

More information about this error may be available in the server error log.

Additionally, a 500 Internal Server Error error was encountered while trying to use an ErrorDocument to handle the request.


17. Well the book says DON'T PANIC! What happened most likely is that .htaccess was modified by the installer. If there is a SINGLE unexpected character in an .htaccess file IT WILL BREAK YOUR SERVER. Very few other things will break your server. A good way to TEST also whether it is .htaccess type critical server fault or just your installation not working is to try to enter a direct URL for a file such as favicon.ico or an image file the path of which you know. If 500 Internal Server Error is still displayed, then it is most likely .htacces type issue. Even if phpBB files are all completely toasted you can always access files from your server directly via their URL: remember that!

OK so make a copy of the .htaccess file (if you are on Windows, it will think this is a strange file extension even though the dot in front actually means it is a *nix hidden file, and you will have some difficulty manipulating this file), then take a look at it. If you see garbage like:

AddType x-mapp-php5 .php
Options +FollowSymLinks
Options -Indexes
ServerSignature Off

<IfModule mod_rewrite.c>
RewriteEngine on

# Uncomment the statement below if URL rewriting doesn't
# work properly. If you installed phpBB in a subdirectory
# of your site, properly set the argument for the statement.
# e.g.: if your domain is and you installed phpBB
# in you have to set
# the statement RewriteBase /phpBB/
#RewriteBase /
>>>>>>> NEW_FILE

# Uncomment the statement below if you want to make use of
# HTTP authentication and it does not already work.
# This could be required if you are for example using PHP via Apache CGI.
#<IfModule mod_rewrite.c>
#RewriteEngine on
#RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

        <Files "config.php">
            Order Allow,Deny
            Deny from All
        <Files "common.php">
            Order Allow,Deny
            Deny from All

You have to restore .htaccess file from backup (of if you are an idiot and did not listen to me, you can delete the garbage that the installer put in this file that is in RED and everything below NEW_FILE.


18. Go back to your forum, and you should see the familiar blue!!! Except that it is politely reminding you to:

Please delete, move or rename the install directory before you use your board. If this directory is still present, only the Administration Control Panel (ACP) will be accessible.

Well, do just that (I at least temporarily like to rename the installation directory JIC I need it, rather than immediately deleting it, however be aware that the install directory kicking around on your server is a SECURITY/VULNERABILITY THREAT).


19. If you mistakenly renamed / deleted the vendor directory (I did it), you will see the following error message:
Fatal error: Composer dependencies have not been set up yet, run 'php ../composer.phar install' from the phpBB directory to do so. in /PATH/includes/startup.php on line 81

If you see that, you have to restore the vendor directory...


20. Go to your ACP and disable that phpBB monetization shit right away.

21. New version should be reflected in ACP, all functionality should work, all extensions should work, etc, etc.

22. This is the part that you redirect your domain name to the tested installation and your users experienced only a few minutes of downtime during the transition (but domain name changes may take up to 24 hours to take effect, by the way). If you did not follow my advice, you may otherwise, if something went wrong, either abandon your effort on a duplicate folder, or panic and try to repair your PRODUCTION installation that you just broke... I DID WARN YOU, DID I NOT???

If something broke hey man it's NOT MY fault!!! Otherwise, you are very, very welcome! I just saved you about two hours of reading BS forum posts.

˅˅˅ Additional valuable information is available at one of the links below: ˅˅˅


Did you like the article? Let Google Search know by clicking this button: . Please link to content that you find useful on this website on your own website, forum or blog! You can also comment on this page below, or to ask a question or suggest a topic for me to research. There is a user-editable Wiki available on my website, as well as a Forum that you can contribute to. Site Map.

Page last modified 01-Aug-19 19:20:29 EDT
Comments on this page: