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

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:

• DatabaseBlock - managed by users of the wiki (typically sysops) and stored in the database.
• SystemBlock - typically managed via configuration variables such as $wgProxyList or $wgDnsBlacklistUrls .
• CompositeBlock - generated automatically by the block manager service when more than one block applies to the user.

Interacting with blocks

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

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

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

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.