Manual:Block abstraction layer/en

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 for more on those) but allows extensions to define their own blocks.

Class hierarchy
Blocks in MediaWiki are represented by the 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:


 * - managed by users of the wiki (typically sysops) and stored in the database.
 * - typically managed via configuration variables such as or.
 * - 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 or equivalent mechanisms (such as the permission-related methods of  or ): block checks are integrated into permission checks so calling e.g.   or   will return the appropriate error message if the user is blocked, so usually no explicit interaction is needed. The   methods provide a, which also exposes the block object. Note that   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 and especially its   method.
 * Via block-related  (and  ) methods such as  . These get cached within the   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  instead. Note that the only existing implementation of global blocks 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 hook to return a block whenever the conditions for the user being blocked. (There is also a 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 and  hooks can be used to expose custom logging-related special pages from the standard ones.