Hello,
*TL;DR*
As part of our work on partial blocks, the Anti-Harassment Tools team has
been refactoring MediaWiki’s code related to blocking, including the Block
class. While “Block” still exists as an alias, extension developers and
anyone who works on code related to blocks should examine their code and
adjust accordingly. Please read further for more information.
*The reason*
With the introduction of partial blocks, and as a follow up to the previous
email we shared with this list several months ago, several cleanup efforts
were scheduled. One of our major tasks involved making sure that
restrictions of overlapping blocks are merged on enforcement[0]. To add
this type of functionality to the large block class in a way that would be
maintainable and extendable going forward, we found it necessary to do some
refactoring.
*Introducing a BlockManager service*
The first piece of cleanup work was the creation and addition of a
BlockManager class[1][2], which is responsible for managing the blocks that
apply to a user, considering that multiple blocks may impact the same user
- e.g. if the user is in a blocked (or partially blocked) IP range as well
as having a separate block (or partial block) on their user account or IP
address.
This work has so far involved moving several methods from the User and
(formerly) Block classes into the BlockManager. The User class uses the
BlockManager to get the correct state of a specific block and its
restrictions.
*Refactoring Block into AbstractBlock, SystemBlock, and DatabaseBlock (and
adding MultipleBlock)*
In order for block restrictions and enforcement to be properly evaluated
even in cases where there may be multiple blocks that apply, the blocks
were split into three main types[3]:
* DatabaseBlock: These blocks are stored in the database. Most blocks are
DatabaseBlocks; most extensions that deal with blocks only deal with
DatabaseBlocks. Blocks obtained using `DatabaseBlock::newFrom*` (formerly
`Block::newFrom*`) are DatabaseBlocks.
* SystemBlock: These blocks are temporary, and created by the system on
enforcement (e.g. blocks against blacklisted IP addresses).
* CompositeBlocks: These are blocks that were created from multiple other
blocks[0]. Like SystemBlocks, these are created temporarily on enforcement,
and not saved.
All three classes inherit the new base class “AbstractBlock”.
“Block” is now an alias for the DatabaseBlock class, and should be
considered deprecated.
*Followup: How to update your code*
The team has followed up with code in production to correct type hinting
and the uses we’ve encountered that require changes.“Block” is still an
alias of the new DatabaseBlock class, so there is no urgency in changing
existing code dealing with DatabaseBlocks (and most blocks are
DatabaseBlocks), but code maintainers and extension developers should
correct the uses of any blocking behavior as necessary, and as fits their
products.
Here are general tips for approaching any changes you may want to make to
adhere to the new block features:
* Any use of static Block methods such as Block::newFrom* should be changed
to use DatabaseBlock
* Any use of the Block constructor should be changed to the SystemBlock or
DatabaseBlock constructor. If the block has the `$systemBlockType`
property, then it should be a SystemBlock. If it is saved to or loaded from
the database, it should be a DatabaseBlock. (In the vast majority of cases,
it will be DatabaseBlock.)
* Any typehint for Block that could be expecting more than one type of
block should be changed to AbstractBlock - e.g. a block returned from
methods that call User::getBlockedStatus could be any type of block. If
expecting a DatabaseBlock, then Block will work for now, but should be
updated to DatabaseBlock
As always, if you find any bugs, please submit a ticket and tag it against
“Anti-Harassment” tag and “MediaWiki-User-management” tag.
Thank you,
The Anti Harassment Tools Team
*References*
[0] Restrictions of overlapping blocks should be merged on enforcement
https://phabricator.wikimedia.org/T206163
[1] Introduce a BlockManager service for getting and combining the blocks
that apply to a user/IP
https://phabricator.wikimedia.org/T219441
[2] Clean up code related to blocking
https://phabricator.wikimedia.org/T225011
[3] Refactor Block to AbstractBlock, DatabaseBlock and SystemBlock
https://phabricator.wikimedia.org/T222737
--
Moriel Schottlender (she/her)
Senior Software Engineer
Tech Lead | Community Tech and Anti Harassment Tools
Wikimedia Foundation
https://wikimediafoundation.org/