Manual:Block abstraction layer


A block is a restriction that's matched against users trying to perform actions, and might prevent those actions. MediaWiki core defines some types of blocks (see Manual:Block and unblock for more on those) but allows extensions to define their own blocks.

Class hierarchy[edit]

Blocks in MediaWiki are represented by the AbstractBlock class. (There is a Block interface, but in practice there is no separation between the two.) In MediaWiki core there are three types of blocks:

Interacting with blocks[edit]

There are three ways to interact with blocks in the code:

  • Via PermissionManager or equivalent mechanisms (such as the permission-related methods of User or Authority): block checks are integrated into permission checks so calling e.g. PermissionManager::getPermissionErrors() or Authority::authorizeWrite() will return the appropriate error message if the user is blocked, so usually no explicit interaction is needed. The Authority methods provide a PermissionStatus, which also exposes the block object.
    Note that probablyCan and equivalent checks intentionally ignore blocks: the presence of UX elements for most actions should not depend on whether the user is blocked from performing that action at the moment.
  • Via BlockManager and especially its getUserBlock() method.
  • Via block-related User (and Authority) methods such as User::getBlock(). These get cached within the User object.

Interacting with global blocks[edit]

For historical reasons, global blocks aren't fully integrated with the block system. Using the permissions system will work, the other two approaches won't. Global blocks can be retrieved with User::getGlobalBlock() instead. Note that the only existing implementation of global blocks (Extension:GlobalBlocking ) is quite buggy, most of the methods on the block object won't work properly (T315644).

Managing blocks[edit]

Managing blocks (such as blocking and unblocking users, or listing active blocks) is not part of the abstraction layer; each extension has its own mechanisms and interfaces for that.

Extending the block system[edit]

Extensions providing a new type of block need to use the GetUserBlock hook to return a block whenever the conditions for the user being blocked. (There is also a UserIsBlockedGlobally hook for global blocks, but there is not much point in using it; the handling of global blocks is somewhat erratic, and there is no real meaning to being "global" – nothing prevents a GetUserBlock extension from using cross-wiki logic.)

Block management (such as blocking, unblocking, listing active blocks, showing a block log) needs to be implemented from scratch. The OtherBlockLogLink and OtherAutoblockLogLink hooks can be used to expose custom logging-related special pages from the standard ones.