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.