Tag: Updating

You don’t generally need to backup all of your tables before updating phpBB

On: By: Mark

Updated October 13, 2019 to mention that the phpbb_migrations table is always changed with an update.

When updating phpBB, you should backup your database. That’s the guidance given by the phpBB Group. Updates occur when you are moving from one micro version of phpBB to another, say 3.2.6 to 3.2.7. When moving from minor versions, like 3.1 to 3.2, you are doing an upgrade and different procedures apply.

It’s never a bad idea to backup your database. It can be done manually in phpBB: ACP > Maintenance > Backup. This method though is not foolproof. Particularly on larger forums or on shared hosting, backups can time out. Sometimes you think you have a complete backup and you don’t. The only way to know for sure is to download it, and examine it in an editor. If the bottom of the file shows the phpbb_zebra table is being populated and ends with a semicolon, it should be complete. Web hosts often offer features that make automatic database and file backups for you.

But it turns out that when making updates, generally not much of your forum’s database actually changes. Only two tables are guaranteed to change: phpbb_config and phpbb_migrations. (I use phpbb_ as your table prefix. Yours may be different. You can see your actual table prefix in your forum’s config.php file.) This is because phpBB always tracks the current version of phpBB installed, and it is stored as a row in the phpbb_config table. And with each update, one or more rows are added to the phpbb_migrations table to indicate what migrations were made.

Most updates don’t affect many tables. In fact, it’s typical that only the phpbb_config and phpbb_migration tables are affected.

So there is no point in making a full backup of your database prior to updating if you don’t need to. It’s a real hassle on larger forums.

It turns out that if you look through phpBB’s code you can figure out which tables are updated. The /phpbb/db/migration folder contains a number of subfolders. The programs in these subfolders do the work of changing your database during updates.

For example, there is a v320 folder. This contains the migration programs used to bring phpBB up to version 3.2.0.

There is also a v32x folder. This contains the migration programs used for each version update of phpBB 3.2. You can infer from the file names which these are. For example, v321.php and v321rc1.php are used to update from phpBB 3.2.0 to 3.2.1. “rc” in the file name means “release candidate”. There is typically at least one release candidate before an official release. So it’s a matter of reading these programs to see what tables are actually affected.

That’s what I did, and you can see the results on my Do I need to update page. Or you can examine them yourself. I’ll keep the update page updated as new micro releases occur. You might want to bookmark it and refer to it before doing your own update.

Of course, I do updating as a service. You can see my pricing here and send me a service inquiry if you’d like to get started.

If you do it yourself, follow the official procedures on phpBB’s update page. But you may decide to backup only the tables that are actually changed to save yourself extra hassle. If an error occurs, restore these tables and recover your files.

 

End phpBB update styling rework with a custom style

On: By: Mark

Updated October 20, 2019.

Has this happened to you? You update phpBB to the latest version and find out that your custom logo or various style changes that you tediously made to phpBB are gone, or partially gone. It’s a common problem and one reason many forum owners defer updating phpBB.

You can end this hassle by creating and installing your own custom style. Using this approach your custom style inherits most of its styling from a primary phpBB style. You then selectively override the primary style’s CSS, HTML or Javascript with your own changes. This way when the primary style you use is changed, you don’t lose your custom changes. This also ensures that your styles and templates use the most current and approved code, which often includes security patches.

In this tutorial I will show how you can do this. I will keep my example simple by using my custom style to swap out the default phpBB logo with my own logo, sized to the new logo’s dimensions. In principle though you can go way beyond this simple use. For example, your custom style can overwrite the inherited style’s colors, padding and margins, or container widths and heights. You can also overwrite HTML and Javascript files.

Note: I now offer this as a service. See my pricing summary for my current rates.

Overview of steps required

The basic approach is:

  1. Make a note of all the changes you made to your style
  2. Reload your preferred style
  3. Create a custom style that inherits from your preferred style
  4. Override the preferred style’s stylesheet directives. This is best done by creating a stylesheet.css file for your custom style and placing your style customizations there.
  5. If you changed some templates, place the custom version of these templates in your custom style’s template directory. Frequently, forum owners will make changes to overall_header.html and overall_footer.html.
  6. Install the custom style
  7. Make the custom style the primary style
  8. Test and refine

Let’s delve into each step to see how this is done.

Make a note of all the changes you made to your style

You probably know what these changes are, but if you have any questions you can use a file comparison tool like WinMerge (for Windows) or kdiff3 (for pretty much any operating system) to compare your files with a reference version.

  1. Download your current style folder where you made all your custom changes, such as /styles/prosilver
  2. Download a reference version of your style for your current release of phpBB. phpBB keeps a list of its releases here. If your styles are based on prosilver then you would use the reference /styles/prosilver folder for your current release of phpBB. (You can see what version of phpBB you are using when you go into the Administration Control Panel. Look for Board version.) If using a non-prosilver style, find the style version you are using. You can see the version by selecting the Details link for the style in ACP > Customise > Style management > Styles. You can also find it by reading the style.cfg file in the root folder of the style. If it’s one of the free styles, you can find it on the styles demo page. Find the style, then click on the Details button. On the Revisions tab, click on the link for the version for your style to download that version. If a proprietary style, if you don’t have it already, you may have to download it from the style author’s website.
  3. Run the file comparison tool and note the changes you made so they can be reapplied in the custom style.

Reload your preferred style

  1. Make certain you have documented all the changes you made to your style. Once they are overwritten, you may not be able to recover them.
  2. If you need to update phpBB, you might want to do this first. Bear in mind if you do this, the default prosilver style will be updated
  3. You might also want to load the latest version of the style you are using, which will become the parent style. Otherwise, since you made changes to your preferred style, it’s a good time to undo them. The simplest way is to upload the reference version of your style, replacing anything that’s there. Purge the cache. If you don’t see the style changes afterward, clear your browser’s cache and reload the page.

Create a custom style that inherits from your preferred style

  1. First review phpBB’s Creating & Modifying Styles page.
  2. Create a folder in the styles folder for the name of your style. In this example I keep it simple and call the folder “custom”, i.e. /styles/custom. Keep the folder name simple. Don’t use any spaces in the folder name. It’s easier if you keep the name all in lowercase.
  3. Create a style.cfg file in this folder. Copy the style.cfg contents from your parent style’s style.cfg file. Below is the code in /styles/prosilver/style.cfg for phpBB 3.2, which I used because my “custom” style inherits from prosilver.
#
# phpBB Style Configuration File
#
# This file is part of the phpBB Forum Software package.
#
# @copyright (c) phpBB Limited <https://www.phpbb.com>
# @license GNU General Public License, version 2 (GPL-2.0)
#
# For full copyright and license information, please see
# the docs/CREDITS.txt file.
#
# At the left is the name, please do not change this
# At the right the value is entered
#
# Values get trimmed, if you want to add a space in front or at the end of
# the value, then enclose the value with single or double quotes.
# Single and double quotes do not need to be escaped.
#
#

# General Information about this style
name = prosilver
copyright = © phpBB Limited, 2007
style_version = 3.3.0
phpbb_version = 3.3.0

# Defining a different template bitfield
# template_bitfield = lNg=

# Parent style
# Set value to empty or to this style's name
# if this style does not have a parent style
parent = prosilver
  1. In my example I changed “name = prosilver” to “name = custom”. Since I want to inherit from prosilver I left the “parent = prosilver” line unchanged. If you are changing a style other than prosilver as the primary style, you need to change the parent style to the correct style name. It must match the parent folder name in the styles folder. You might also want to edit the copyright, style_version and phpbb_version lines. If it’s only for your own use, this is not necessary. Here are my changes:
# General Information about this style
name = custom
copyright = © Mark D. Hamill
style_version = 1.0.0
phpbb_version = 3.3.0

# Defining a different template bitfield
# template_bitfield = lNg=

# Parent style
# Set value to empty or to this style's name
# if this style does not have a parent style
parent = prosilver
  1. Save the file, making sure it is in the root folder for the custom style, e.g.: /styles/custom/style.cfg.

Override the preferred style’s stylesheet directives

  1. Create a theme folder for your style. In my example, this would be /styles/custom/theme.
  2. Create an images folder inside the theme folder. In my example, this would be /styles/custom/theme/images.
  3. If changing the logo, upload the logo you will use to /styles/custom/theme/images. Make a note of the image’s height and width as you will need this later.
  4. Create a file called stylesheet.css in the theme folder.
  5. To inherit styles from your parent style, you need an @import statement at the top of this file. For example, if prosilver is the preferred style, this line would be at the top of the file. Generally you just need to reference the stylesheet.css file in the parent style. You will have to amend the path so it finds the parent style’s stylesheet files. In my case for the @import line, I added “../../prosilver/theme/”. The ?v=3.3 indicates the version of phpBB expected, so it may have to be changed. Note: in some cases you may have to add a second import statement. For example, the prosilver_se style’s stylesheet.css file does not reference the parent prosilver style’s stylesheet.css file. So you may need a second import statement to reference the prosilver style.
@import url("../../prosilver/theme/stylesheet.css?v=3.3");
  1. Any style changes that you want to override should now be appended to the end of this file. In the example of replacing the logo, in the prosilver style you would normally edit the .site_logo class in colours.css and common.css. In my case I added these lines at the end of my /styles/custom/theme/stylesheet.css file, which provides the correct image to use for the logo and its proper dimensions:
.site_logo {
    background-image: url("./images/mark.jpg");
    width: 181px;
    height: 229px;
}
  1. I then saved the file stylesheet.css with my changes.

Changing templates

In my example, since I am only replacing the logo, no template changes were needed. The only viable approach is to copy the template, for example, /styles/prosilver/template/overall_header.html to /styles/custom/template/overall_header.html. Then make the changes that you need to make and save the file. This has a downside: if there are changes made to the parent’s template with an update, your version won’t have them unless you manually inspect for any changes and apply them to your custom version.

Install the custom style

  1. ACP > Customise > Style management > Install Styles
  2. Select the new style you created (“custom” in my example) by pressing the corresponding Install style link.

Make the custom style the primary style

ACP > General > Board configuration > Board settings. Generally you set the default style to your new custom style, the guest style to your new custom style and you may optionally want to set the override user style option to Yes. Submit the form.

Test and refine

You should not need to purge the cache if you make any stylesheet changes. However, if you make subsequent changes to any templates first purge the cache then test. If you don’t see the style changes, try deleting your browser’s cache, then reload the page. On desktop and laptop computers, sometimes holding the SHIFT key down while pressing the RELOAD button will work.

Approach when upgrading

This approach is unlikely to work correctly when upgrading. An upgrade is when you go from one minor release of phpBB to another, such as from 3.2 to 3.3. You can of course go through the process of creating a new custom style again. As for updates, this should work.

Enjoy!

phpBB 3.2 Rhea, third look

On: By: Mark

(Read part 1 and part 2 if you haven’t.)

Updating from 3.0 or 3.1

One thing that is unclear about phpBB 3.2 is how to update to it. The phpBB group itself may be contributing to the confusion. On the launch page they say:

With our brand new installer updating will be easier than ever in phpBB 3.2! Upload a single folder to your board and all your files will automatically be replaced.

This implies that it’s already there. But if you are upgrading from 3.1 no interface exists. Rather, you follow procedures similar to updating from 3.0 to 3.1, found here. The easier way of updating will apply to subsequent releases of phpBB 3.2. There is no 3.2.1 released yet, so you can use the new improved updater yet.

In addition, you used to run /install/database_update.php to update the database. Now you run /install/app.php/update instead and select Update database only. You can also run /install and select the update tab and do it that way.

Other things to note:

  • Quotes are improved. To quote someone you generally click the “Reply with quote” button on the post you want to quote. Doing this creates an enhanced BBCode quote tag with additional attributes that include the post_id, the post time and the user_id. When you submit your post, the quote now indicates the this information in the quote and via an up arrow link can take you to the referencing post.
  • The notifications system has been rewritten to be faster. Since notifications are created when posts are made, you should notice much less delay time between submitting the post and the topic refreshing.