In order to complete T206163, the Block class needs to be refactored so that blocks made from multiple blocks can be separated out from single blocks. In doing this, we will create an AbstractBlock parent class which can be extended by a class for single blocks and a new class for multiple blocks (CompositeBlock). The CompositeBlock class is convenient, because it allows the rest of the codebase (except the BlockManager) to be unaware of overlapping blocks.
While we are doing this, it makes sense also to separate out system blocks, which are temporary blocks usually created against IP addresses listed in global configs. These are single blocks but are never saved to the database.
In summary, Block will be refactored into the following classes:
AbstractBlock - abstract parent class
DatabaseBlock - blocks that are saved to the database
SystemBlock - temporary blocks
In addition there will be:
CompositeBlock - blocks made from several blocks
Block remains as a deprecated alias for DatabaseBlock, the most common type of block.
Breaking changes
This work breaks any cases where typehints for Block could be expecting a SystemBlock or a DatabaseBlock. These need to be updated to AbstractBlock. (Such cases are unusual - in most cases only a DatabaseBlock is expected.)
Where a Block typehint expects only a DatabaseBlock, it should still be updated since Block is deprecated, but will not break for now.
Naming
There have been some discussions about an alternative naming scheme, in which the parent class is named Block and the class for database blocks is called DatabaseBlock. This avoids the break mentioned above, but would break calls to static methods such as Block::newFrom* and calls to the constructor new Block(). Given the prevalence of these across extensions, this would be a much less convenient change.
Plan
- Introduce an empty AbstractBlock class, and have Block extend it. This is just to avoid the breaking change mentioned above and will be quickly followed-up with the refactoring patch.
- Update any typehints in extensions that use Block (but may expect a SystemBlock or CompositeBlock), based on: https://codesearch.wmflabs.org/deployed/?q=(%3F%3A%5CsBlock%5Cs%7Cinstanceof%5CsBlock)&i=nope&files=&repos= (NB most of these examples are in fact expecting a database Block, so do not need to be updated.)
- Split Block into AbstractBlock, Block and SystemBlock
- Make Block a deprecated alias of DatabaseBlock, which is more descriptive
- Communicate and verify documentation of the soft deprecation