Add lots of @throws

[lhc/web/wiklou.git] / includes / Block.php

diff --git a/includes/Block.php b/includes/Block.php
index 6a29a05..9079fb0 100644 (file)
--- a/includes/Block.php
+++ b/includes/Block.php
@@ -113,7 +113,7 @@ class Block {
                        $this->forcedTargetID = $user; // needed for foreign users
                }
                if ( $by ) { // local user
-                       $this->setBlocker( User::newFromID( $by ) );
+                       $this->setBlocker( User::newFromId( $by ) );
                } else { // foreign user
                        $this->setBlocker( $byText );
                }
@@ -366,7 +366,7 @@ class Block {
        protected function initFromRow( $row ) {
                $this->setTarget( $row->ipb_address );
                if ( $row->ipb_by ) { // local user
-                       $this->setBlocker( User::newFromID( $row->ipb_by ) );
+                       $this->setBlocker( User::newFromId( $row->ipb_by ) );
                } else { // foreign user
                        $this->setBlocker( $row->ipb_by_text );
                }
@@ -580,7 +580,7 @@ class Block {
                if ( $this->isAutoblocking() && $this->getType() == self::TYPE_USER ) {
                        wfDebug( "Doing retroactive autoblocks for " . $this->getTarget() . "\n" );
 
-                       $continue = wfRunHooks(
+                       $continue = Hooks::run(
                                'PerformRetroactiveAutoblock', array( $this, &$blockIds ) );
 
                        if ( $continue ) {
@@ -693,7 +693,7 @@ class Block {
                }
 
                # Allow hooks to cancel the autoblock.
-               if ( !wfRunHooks( 'AbortAutoblock', array( $autoblockIP, &$this ) ) ) {
+               if ( !Hooks::run( 'AbortAutoblock', array( $autoblockIP, &$this ) ) ) {
                        wfDebug( "Autoblock aborted by hook.\n" );
                        return false;
                }
@@ -885,7 +885,7 @@ class Block {
        /**
         * Get/set a flag determining whether the master is used for reads
         *
-        * @param bool $x
+        * @param bool|null $x
         * @return bool
         */
        public function fromMaster( $x = null ) {
@@ -893,8 +893,8 @@ class Block {
        }
 
        /**
-        * Get/set whether the Block is a hardblock (affects logged-in users on a given IP/range
-        * @param bool $x
+        * Get/set whether the Block is a hardblock (affects logged-in users on a given IP/range)
+        * @param bool|null $x
         * @return bool
         */
        public function isHardblock( $x = null ) {
@@ -906,6 +906,10 @@ class Block {
                        : $this->isHardblock;
        }
 
+       /**
+        * @param null|bool $x
+        * @return bool
+        */
        public function isAutoblocking( $x = null ) {
                wfSetVar( $this->isAutoblocking, $x );
 
@@ -919,7 +923,7 @@ class Block {
        /**
         * Get/set whether the Block prevents a given action
         * @param string $action
-        * @param bool $x
+        * @param bool|null $x
         * @return bool
         */
        public function prevents( $action, $x = null ) {
@@ -1110,6 +1114,7 @@ class Block {
 
        /**
         * From a list of multiple blocks, find the most exact and strongest Block.
+        *
         * The logic for finding the "best" block is:
         *  - Blocks that match the block's target IP are preferred over ones in a range
         *  - Hardblocks are chosen over softblocks that prevent account creation
@@ -1117,12 +1122,15 @@ class Block {
         *  - Other softblocks are chosen over autoblocks
         *  - If there are multiple exact or range blocks at the same level, the one chosen
         *    is random
+        * This should be used when $blocks where retrieved from the user's IP address
+        * and $ipChain is populated from the same IP address information.
         *
-        * @param array $blocks Array of blocks
+        * @param array $blocks Array of Block objects
         * @param array $ipChain List of IPs (strings). This is used to determine how "close"
         *        a block is to the server, and if a block matches exactly, or is in a range.
         *        The order is furthest from the server to nearest e.g., (Browser, proxy1, proxy2,
         *        local-squid, ...)
+        * @throws MWException
         * @return Block|null The "best" block from the list
         */
        public static function chooseBlock( array $blocks, array $ipChain ) {
@@ -1156,6 +1164,7 @@ class Block {
                );
                $ipChain = array_reverse( $ipChain );
 
+               /** @var Block $block */
                foreach ( $blocks as $block ) {
                        // Stop searching if we have already have a "better" block. This
                        // is why the order of the blocks matters