[Wikitech-l] FYI: Renaming and refactoring of the Block class

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/