[Info] phpBB 3.2 Upgrade Notes for Extensions

[MattF]

**************** UPDATE ****************
The information in this post has been documented in our Official phpBB Extension Documentation.

Please read What’s New for phpBB 3.2
*******************************************

Extensions should, for the most part, be compatible with phpBB 3.2 with no need for specific changes, and they should be able to maintain backwards compatibility with 3.1. However, there are many changes in phpBB 3.2 that can be made to extensions to keep them current, or may be needed in a few rare cases where compatibility between 3.1 and 3.2 has been broken. This topic should cover what you need to know to keep your extensions working in phpBB 3.2.

There following tags are used to distinguish what types of changes are being described:

• (3.1/3.2) For changes that should be made for 3.2, but are also compatible with 3.1 and are probably good to do no matter what.
• (3.2 optional) For changes that can be made for 3.2, but are not required yet. These are changes that will break backwards compatibility with 3.1, so they should only be made if your extension is no longer supporting 3.1. If you can support 3.1 and 3.2, then these changes can be skipped.
• (3.2 only) For changes required for 3.2 compatibility. If your extension makes these changes, it will no longer support 3.1, and should in effect represent a new major version development cycle for your extension.

PHP CHANGES:

Replace $user->lang with $language->lang (3.2 optional)
The language class has been de-coupled from the user class. This means the language class in 3.2 can now be accessed from \phpbb\language\language. The old \phpbb\user class is still available for backwards compatibility with 3.1, but the user's lang methods have been deprecated and will be removed in a future phpBB version. Also, the old user class' add_lang_ext() method is deprecated and handled by the smarter language class' add_lang method.

Code: Select all

// phpBB 3.1 and 3.2 compatible
$user->add_lang('posting');
$user->add_lang_ext('phpbb/boardrules', 'common');
$user->lang('HELLO_WORLD');

// phpBB 3.2 only
$language->add_lang('posting');
$language->add_lang('common', 'phpbb/boardrules');
$language->lang('HELLO_WORLD');

Notifications (3.2 only)
If your extension uses the notifications system by extending the notifications class, then you should take a look at how the notifications classes have changed for 3.2. The notable changes are made to the find_users_for_notification and create_insert_array methods.

Code: Select all

public function find_users_for_notification($data, $options = array())
{
    ...
    // phpBB 3.1 usage:
    $users[$row['user_id']] = array('');

    // phpBB 3.2 usage:
    $users[$row['user_id']] = $this->notification_manager->get_default_methods();
    ...
}

Code: Select all

public function create_insert_array($data, $pre_create_data = array())
{
    ...
    // phpBB 3.1 usage:
    return parent::create_insert_array($data, $pre_create_data);
   
    // phpBB 3.2 usage:
    parent::create_insert_array($data, $pre_create_data);
}

BBCode FAQ Controller Route (3.2 optional)
The link to the BBCode FAQ can now be handled using the route system:

Code: Select all

//phpBB 3.1 and 3.2 compatible:
<a href="' . append_sid("{$this->root_path}faq.{$this->php_ext}", 'mode=bbcode') . '">

//phpBB 3.2 only:
<a href="' . $this->controller_helper->route('phpbb_help_bbcode_controller') . '">

Group Helper get_name() Method (3.2 optional)
There's a new method for displaying the name of a user group in 3.2:

Code: Select all

//phpbb 3.1 and 3.2 compatible:
($row['group_type'] == GROUP_SPECIAL) ? $this->user->lang('G_' . $row['group_name']) : $row['group_name'];

//phpBB 3.2 only:
$this->group_helper->get_name($group_row['group_name'])

BBCODE CHANGES:

BBCode engine (3.1/3.2)
The BBCode engine has been replaced by the s9e/textformatter. Most extensions should not be affected by this. Unless your extension directly modifies how BBCodes are configured, processed or rendered, via the bbcodes.php class. In most cases even if you do need to make changes to work with the new textformatter, you can do so via many of its strategically positioned events which should allow you to have events and code compatible with the 3.2 engine and simultaneously keep code for the old engine in place, thus able to maintain backwards compatibility with 3.1. The BBCode changes are too extensive to detail here, so if you need to explore the new engine further, you can start with this thread by the new engine's author.

Text Reparser (3.2 optional)
If your extension is storing text with BBCodes in its own tables in the database, you may want to consider adding a text reparser class. When phpBB updates a board to 3.2, it reparses all posts and a few other spots where phpBB uses BBCodes, updating them to the new BBCode format. Unparsed old bbcodes should still work as expected, but it can be piece of mind, especially if your extension stores a lot of messages with BBCodes, to have them updated to the new format. Doing so requires two things:

1. Extend a reparser plugin class to scan your extension's tables containing messages for reparsing (the table is defined in the service).
2. Write a migration to put your reparser into action.

An example of how this was done can be viewed in the 3.2 branch of the Board Rules extension.

TEMPLATE CHANGES:

Twig loops prefix (3.2 optional)
If you are already using Twig template syntax, and you have been using template loops, the loops prefix is no longer needed for 3.2. However, it is still needed if backwards compatibility with 3.1 is desired.

Code: Select all

// phpBB 3.1 and 3.2 compatible
{% for item in loops.items %}
   item.MY_VAR
{% endfor %}

// phpBB 3.2 only
{% for item in items %}
   item.MY_VAR
{% endfor %}

Font Awesome (3.2 only)
phpBB 3.2 has replaced almost every icon with a font icon using the Font Awesome toolkit. This has resulted in significant template changes to Prosilver, including many new classes. If your extension makes use of any of Prosilver's icons, or in any way recreates any of Prosilver's template layouts that include any iconography, you should examine if and how your template files may be impacted and need to be adjusted to be compliant with phpBB 3.2. Some backwards compatibility has been retained so, for example, extensions adding links to the nav bars should still work as expected. You may also consider leveraging the new font icons to your advantage as they make it quite easy now to add any of the available Font Awesome icons to improve GUI elements of your extension. For example, if you extension has a "delete" link or button, you could add a nice little Trash Can icon to that link or button.

INCLUDECSS changes (3.2 only)
Now, in phpBB 3.2, the INCLUDECSS syntax can be used anywhere in a template. In phpBB 3.1, this tag only worked in an event like overall_header_head_append, or before including overall_header.html. As of 3.2 it will be easier to implement this tag anywhere, just like the INCLUDEJS tag.

MISC CHANGES:

Quote service variables (3.1/3.2)
Symfony will require wrapping services definitions prefixed with @ and % in single-quotes (non-quoted strings is deprecated in Symfony 2.8 and will throw parser errors in 3.0). This has always been allowed but not practiced in phpBB 3.1. So this should be done for 3.2 at least (which is using Symfony 2.8), but is highly recommended for any extension since it is phpBB 3.1 and 3.2 compatible. For example:

Code: Select all

vendor.package.class:
   class: vendor\package\classname
   arguments:
      - '@dbal.conn'
      - '%custom.tables%'
   calls:
      - [set_controller_helper, ['@controller.helper']]    

Replace prototype scopes with shared services (3.1/3.2)
Symfony has deprecated the prototype scope in 2.8, and it will be removed in 3.0. As a result you should make this simple change if any of your services are defined to use the protoype scope. That means replace any occurrences of:

Code: Select all

scope: prototype

with:

Code: Select all

shared: false

An example:

Code: Select all

vendor.package.class:
   class: vendor\package\classname
   shared: false

This post is subject to change as phpBB 3.2 continues to be developed. Also please discuss any additional 3.2 updates discovered and they may be added to this list.

[david63]

In regard to the change of the language class - has something else changed when using arrays within the language array.

I have an array

Code: Select all

'FRUITS' => array(
		'apple' => 'apple',
		'orange' => 'orange',
		'pear' => 'pear',
	),

In 3.1 I would use $this->user->lang['FRUITS']['orange']
but in 3.2 when I use $this->language->lang['FRUITS']['orange']
I am getting
Fatal error: Cannot access protected property phpbb\language\language::$lang

I do not have any problems using the new language class with language variables that are not within an array - even in the same file which would seem to indicate that the property is accessible, just not when there is an array within the array.

[nicofuma]

$this->language->lang(['FRUITS', 'orange']) I think

[david63]

$this->language->lang(['FRUITS', 'orange']) I think

You think correctly

That was about the only permutation that I had not tried.

[david63]

Another language array problem

In 3.1 I would use $this->user->lang['dateformats'] which would return an array of the dateformat language variables but I cannot seem to find an equivalent in 3.2

I have tried:
$this->language->lang['dateformats']
$this->language->lang('dateformats')
$this->language->lang(['dateformats'])
$this->language->lang_array['dateformats']
$this->language->lang_array('dateformats')
All to no avail - have I missed something or is this not possible in 3.2?

[nicofuma]

I don't understand why you are doing that... The goal of the language system is to returns a translated string. A string, not an array, an object or anything else.

And indeed there is no way to get the raw data like in 3.1

[david63]

I don't understand why you are doing that... The goal of the language system is to returns a translated string. A string, not an array, an object or anything else.

And indeed there is no way to get the raw data like in 3.1

3.1 already does it.

It is done in the core - includes/acp/acp_board.php about line 1028 to build the date formats select

[LavIgor]

david63, two ways to fix your issue.
1. Use deprecated $user->lang[] for now.
2. Use $language->get_lang_array() - however, it contains a note:

Note: This function is needed for the BC purposes, until \phpbb\user::lang[] is not removed.

This function is not marked as deprecated, but contains that note.
Does that mean that it will be removed at some point?

[david63]

david63, two ways to fix your issue.

Thanks.

The first is what I am doing, and the second does not appear to work (I probably have not found the correct syntax)

[3Di]

As far I understood all of the BC's compatibilities still last till 3.3.0-dev, correct me if I am wrong.

[LavIgor]

$user->lang[] is planned to be removed in phpBB 4.0.0.

[nicofuma]

I see the problem. Can you please add a ticket saying that the lang() function should handle the cases where the key points to an array?

[david63]

I see the problem. Can you please add a ticket saying that the lang() function should handle the cases where the key points to an array?

Done - https://tracker.phpbb.com/browse/PHPBB3-14432

[combuster]

How can we obtain a $language instance in an ACP module?

This:

Code: Select all

global $language;
$language->add_lang('x_acp', 'a/x');

results in:

Code: Select all

Fatal error: Call to a member function add_lang() on a non-object in /.../phpBB3/ext/a/x/acp/x_module.php on line 45

Code: Select all

$this->language = $phpbb_container->get('phpbb.language.language');

results in:

Code: Select all

Uncaught exception 'Symfony\Component\DependencyInjection\Exception\InvalidArgumentException' with message 'The service definition "phpbb.language.language" does not exist.' in /...phpBB3/vendor/symfony/dependency-injection/ContainerBuilder.php on line 815

[kasimi]

See /config/default/container/services_language.yml for the language service definition.
You can access it with $phpbb_container->get('language');.