| Index: trunk/phase3/includes/Block.php |
| — | — | @@ -13,8 +13,7 @@ |
| 14 | 14 | * |
| 15 | 15 | * @todo This could be used everywhere, but it isn't. |
| 16 | 16 | */ |
| 17 | | -class Block |
| 18 | | -{ |
| | 17 | +class Block { |
| 19 | 18 | /* public*/ var $mAddress, $mUser, $mBy, $mReason, $mTimestamp, $mAuto, $mId, $mExpiry, |
| 20 | 19 | $mRangeStart, $mRangeEnd, $mAnonOnly, $mEnableAutoblock, $mHideName, |
| 21 | 20 | $mBlockEmail, $mByName, $mAngryAutoblock; |
| — | — | @@ -52,15 +51,15 @@ |
| 53 | 52 | |
| 54 | 53 | /** |
| 55 | 54 | * Load a block from the database, using either the IP address or |
| 56 | | - * userid. |
| | 55 | + * user ID. Tries the user ID first, and if that doesn't work, tries |
| | 56 | + * the address. |
| 57 | 57 | * |
| 58 | 58 | * @return Block Object |
| 59 | 59 | * @param $address string IP address of user/anon |
| 60 | 60 | * @param $user int User id of user |
| 61 | 61 | * @param $killExpired bool Delete expired blocks on load |
| 62 | 62 | */ |
| 63 | | - static function newFromDB( $address, $user = 0, $killExpired = true ) |
| 64 | | - { |
| | 63 | + static function newFromDB( $address, $user = 0, $killExpired = true ) { |
| 65 | 64 | $block = new Block(); |
| 66 | 65 | $block->load( $address, $user, $killExpired ); |
| 67 | 66 | if ( $block->isValid() ) { |
| — | — | @@ -72,11 +71,11 @@ |
| 73 | 72 | |
| 74 | 73 | /** |
| 75 | 74 | * Load a blocked user from their block id. |
| | 75 | + * |
| 76 | 76 | * @return Block object |
| 77 | 77 | * @param $id int Block id to search for |
| 78 | 78 | */ |
| 79 | | - static function newFromID( $id ) |
| 80 | | - { |
| | 79 | + static function newFromID( $id ) { |
| 81 | 80 | $dbr = wfGetDB( DB_SLAVE ); |
| 82 | 81 | $res = $dbr->resultObject( $dbr->select( 'ipblocks', '*', |
| 83 | 82 | array( 'ipb_id' => $id ), __METHOD__ ) ); |
| — | — | @@ -92,8 +91,7 @@ |
| 93 | 92 | * Clear all member variables in the current object. Does not clear |
| 94 | 93 | * the block from the DB. |
| 95 | 94 | */ |
| 96 | | - function clear() |
| 97 | | - { |
| | 95 | + function clear() { |
| 98 | 96 | $this->mAddress = $this->mReason = $this->mTimestamp = ''; |
| 99 | 97 | $this->mId = $this->mAnonOnly = $this->mCreateAccount = |
| 100 | 98 | $this->mEnableAutoblock = $this->mAuto = $this->mUser = |
| — | — | @@ -102,7 +100,10 @@ |
| 103 | 101 | } |
| 104 | 102 | |
| 105 | 103 | /** |
| 106 | | - * Get the DB object and set the reference parameter to the query options |
| | 104 | + * Get the DB object and set the reference parameter to the select options. |
| | 105 | + * The options array will contain FOR UPDATE if appropriate. |
| | 106 | + * |
| | 107 | + * @param array $options |
| 107 | 108 | * @return Database |
| 108 | 109 | */ |
| 109 | 110 | function &getDBOptions( &$options ) { |
| — | — | @@ -122,15 +123,14 @@ |
| 123 | 124 | } |
| 124 | 125 | |
| 125 | 126 | /** |
| 126 | | - * Get a ban from the DB, with either the given address or the given username |
| | 127 | + * Get a block from the DB, with either the given address or the given username |
| 127 | 128 | * |
| 128 | 129 | * @param $address string The IP address of the user, or blank to skip IP blocks |
| 129 | 130 | * @param $user int The user ID, or zero for anonymous users |
| 130 | 131 | * @param $killExpired bool Whether to delete expired rows while loading |
| 131 | 132 | * |
| 132 | 133 | */ |
| 133 | | - function load( $address = '', $user = 0, $killExpired = true ) |
| 134 | | - { |
| | 134 | + function load( $address = '', $user = 0, $killExpired = true ) { |
| 135 | 135 | wfDebug( "Block::load: '$address', '$user', $killExpired\n" ); |
| 136 | 136 | |
| 137 | 137 | $options = array(); |
| — | — | @@ -198,12 +198,12 @@ |
| 199 | 199 | |
| 200 | 200 | /** |
| 201 | 201 | * Fill in member variables from a result wrapper |
| | 202 | + * |
| 202 | 203 | * @return bool |
| 203 | 204 | * @param $res ResultWrapper Row from the ipblocks table |
| 204 | 205 | * @param $killExpired bool Whether to delete expired rows while loading |
| 205 | 206 | */ |
| 206 | | - function loadFromResult( ResultWrapper $res, $killExpired = true ) |
| 207 | | - { |
| | 207 | + function loadFromResult( ResultWrapper $res, $killExpired = true ) { |
| 208 | 208 | $ret = false; |
| 209 | 209 | if ( 0 != $res->numRows() ) { |
| 210 | 210 | # Get first block |
| — | — | @@ -237,13 +237,13 @@ |
| 238 | 238 | /** |
| 239 | 239 | * Search the database for any range blocks matching the given address, and |
| 240 | 240 | * load the row if one is found. |
| | 241 | + * |
| 241 | 242 | * @return bool |
| 242 | 243 | * @param $address string IP address range |
| 243 | 244 | * @param $killExpired bool Whether to delete expired rows while loading |
| 244 | 245 | * @param $userid int If not 0, then sets ipb_anon_only |
| 245 | 246 | */ |
| 246 | | - function loadRange( $address, $killExpired = true, $user = 0 ) |
| 247 | | - { |
| | 247 | + function loadRange( $address, $killExpired = true, $user = 0 ) { |
| 248 | 248 | $iaddr = IP::toHex( $address ); |
| 249 | 249 | if ( $iaddr === false ) { |
| 250 | 250 | # Invalid address |
| — | — | @@ -282,10 +282,10 @@ |
| 283 | 283 | /** |
| 284 | 284 | * Given a database row from the ipblocks table, initialize |
| 285 | 285 | * member variables |
| | 286 | + * |
| 286 | 287 | * @param $row ResultWrapper A row from the ipblocks table |
| 287 | 288 | */ |
| 288 | | - function initFromRow( $row ) |
| 289 | | - { |
| | 289 | + function initFromRow( $row ) { |
| 290 | 290 | $this->mAddress = $row->ipb_address; |
| 291 | 291 | $this->mReason = $row->ipb_reason; |
| 292 | 292 | $this->mTimestamp = wfTimestamp(TS_MW,$row->ipb_timestamp); |
| — | — | @@ -312,8 +312,7 @@ |
| 313 | 313 | * Once $mAddress has been set, get the range they came from. |
| 314 | 314 | * Wrapper for IP::parseRange |
| 315 | 315 | */ |
| 316 | | - function initialiseRange() |
| 317 | | - { |
| | 316 | + function initialiseRange() { |
| 318 | 317 | $this->mRangeStart = ''; |
| 319 | 318 | $this->mRangeEnd = ''; |
| 320 | 319 | |
| — | — | @@ -324,10 +323,12 @@ |
| 325 | 324 | |
| 326 | 325 | /** |
| 327 | 326 | * Callback with a Block object for every block |
| 328 | | - * @return integer number of blocks; |
| | 327 | + * |
| | 328 | + * @deprecated Unlimited row count, do your own queries instead |
| | 329 | + * |
| | 330 | + * @return integer number of blocks |
| 329 | 331 | */ |
| 330 | | - /*static*/ function enumBlocks( $callback, $tag, $flags = 0 ) |
| 331 | | - { |
| | 332 | + /*static*/ function enumBlocks( $callback, $tag, $flags = 0 ) { |
| 332 | 333 | global $wgAntiLockFlags; |
| 333 | 334 | |
| 334 | 335 | $block = new Block(); |
| — | — | @@ -380,10 +381,10 @@ |
| 381 | 382 | |
| 382 | 383 | /** |
| 383 | 384 | * Delete the row from the IP blocks table. |
| | 385 | + * |
| 384 | 386 | * @return bool |
| 385 | 387 | */ |
| 386 | | - function delete() |
| 387 | | - { |
| | 388 | + function delete() { |
| 388 | 389 | if (wfReadOnly()) { |
| 389 | 390 | return false; |
| 390 | 391 | } |
| — | — | @@ -397,11 +398,12 @@ |
| 398 | 399 | } |
| 399 | 400 | |
| 400 | 401 | /** |
| 401 | | - * Insert a block into the block table. |
| 402 | | - * @return bool Whether or not the insertion was successful. |
| 403 | | - */ |
| 404 | | - function insert() |
| 405 | | - { |
| | 402 | + * Insert a block into the block table. Will fail if there is a conflicting |
| | 403 | + * block (same name and options) already in the database. |
| | 404 | + * |
| | 405 | + * @return bool Whether or not the insertion was successful. |
| | 406 | + */ |
| | 407 | + function insert() { |
| 406 | 408 | wfDebug( "Block::insert; timestamp {$this->mTimestamp}\n" ); |
| 407 | 409 | $dbw = wfGetDB( DB_MASTER ); |
| 408 | 410 | |
| — | — | @@ -436,11 +438,12 @@ |
| 437 | 439 | if ($affected) |
| 438 | 440 | $this->doRetroactiveAutoblock(); |
| 439 | 441 | |
| 440 | | - return $affected; |
| | 442 | + return (bool)$affected; |
| 441 | 443 | } |
| 442 | 444 | |
| 443 | 445 | /** |
| 444 | | - * Update block with new parameters. |
| | 446 | + * Update a block in the DB with new parameters. |
| | 447 | + * The ID field needs to be loaded first. |
| 445 | 448 | */ |
| 446 | 449 | public function update() { |
| 447 | 450 | wfDebug( "Block::update; timestamp {$this->mTimestamp}\n" ); |
| — | — | @@ -500,6 +503,7 @@ |
| 501 | 504 | /** |
| 502 | 505 | * Retroactively autoblocks the last IP used by the user (if it is a user) |
| 503 | 506 | * blocked by this Block. |
| | 507 | + * |
| 504 | 508 | * @return bool Whether or not a retroactive autoblock was made. |
| 505 | 509 | */ |
| 506 | 510 | function doRetroactiveAutoblock() { |
| — | — | @@ -539,8 +543,9 @@ |
| 540 | 544 | |
| 541 | 545 | /** |
| 542 | 546 | * Checks whether a given IP is on the autoblock whitelist. |
| | 547 | + * |
| 543 | 548 | * @return bool |
| 544 | | - * @param string $autoblockip The IP to check |
| | 549 | + * @param string $ip The IP to check |
| 545 | 550 | */ |
| 546 | 551 | function isWhitelistedFromAutoblocks( $ip ) { |
| 547 | 552 | global $wgMemc; |
| — | — | @@ -580,31 +585,32 @@ |
| 581 | 586 | } |
| 582 | 587 | |
| 583 | 588 | /** |
| 584 | | - * Autoblocks the given IP, referring to this Block. |
| 585 | | - * @param string $autoblockip The IP to autoblock. |
| 586 | | - * @param bool $justInserted The main block was just inserted |
| 587 | | - * @return bool Whether or not an autoblock was inserted. |
| 588 | | - */ |
| 589 | | - function doAutoblock( $autoblockip, $justInserted = false ) { |
| | 589 | + * Autoblocks the given IP, referring to this Block. |
| | 590 | + * |
| | 591 | + * @param string $autoblockIP The IP to autoblock. |
| | 592 | + * @param bool $justInserted The main block was just inserted |
| | 593 | + * @return bool Whether or not an autoblock was inserted. |
| | 594 | + */ |
| | 595 | + function doAutoblock( $autoblockIP, $justInserted = false ) { |
| 590 | 596 | # If autoblocks are disabled, go away. |
| 591 | 597 | if ( !$this->mEnableAutoblock ) { |
| 592 | 598 | return; |
| 593 | 599 | } |
| 594 | 600 | |
| 595 | 601 | # Check for presence on the autoblock whitelist |
| 596 | | - if (Block::isWhitelistedFromAutoblocks($autoblockip)) { |
| | 602 | + if (Block::isWhitelistedFromAutoblocks($autoblockIP)) { |
| 597 | 603 | return; |
| 598 | 604 | } |
| 599 | 605 | |
| 600 | 606 | ## Allow hooks to cancel the autoblock. |
| 601 | | - if (!wfRunHooks( 'AbortAutoblock', array( $autoblockip, &$this ) )) { |
| | 607 | + if (!wfRunHooks( 'AbortAutoblock', array( $autoblockIP, &$this ) )) { |
| 602 | 608 | wfDebug( "Autoblock aborted by hook." ); |
| 603 | 609 | return false; |
| 604 | 610 | } |
| 605 | 611 | |
| 606 | 612 | # It's okay to autoblock. Go ahead and create/insert the block. |
| 607 | 613 | |
| 608 | | - $ipblock = Block::newFromDB( $autoblockip ); |
| | 614 | + $ipblock = Block::newFromDB( $autoblockIP ); |
| 609 | 615 | if ( $ipblock ) { |
| 610 | 616 | # If the user is already blocked. Then check if the autoblock would |
| 611 | 617 | # exceed the user block. If it would exceed, then do nothing, else |
| — | — | @@ -623,8 +629,8 @@ |
| 624 | 630 | } |
| 625 | 631 | |
| 626 | 632 | # Make a new block object with the desired properties |
| 627 | | - wfDebug( "Autoblocking {$this->mAddress}@" . $autoblockip . "\n" ); |
| 628 | | - $ipblock->mAddress = $autoblockip; |
| | 633 | + wfDebug( "Autoblocking {$this->mAddress}@" . $autoblockIP . "\n" ); |
| | 634 | + $ipblock->mAddress = $autoblockIP; |
| 629 | 635 | $ipblock->mUser = 0; |
| 630 | 636 | $ipblock->mBy = $this->mBy; |
| 631 | 637 | $ipblock->mByName = $this->mByName; |
| — | — | @@ -650,8 +656,7 @@ |
| 651 | 657 | * Check if a block has expired. Delete it if it is. |
| 652 | 658 | * @return bool |
| 653 | 659 | */ |
| 654 | | - function deleteIfExpired() |
| 655 | | - { |
| | 660 | + function deleteIfExpired() { |
| 656 | 661 | $fname = 'Block::deleteIfExpired'; |
| 657 | 662 | wfProfileIn( $fname ); |
| 658 | 663 | if ( $this->isExpired() ) { |
| — | — | @@ -670,8 +675,7 @@ |
| 671 | 676 | * Has the block expired? |
| 672 | 677 | * @return bool |
| 673 | 678 | */ |
| 674 | | - function isExpired() |
| 675 | | - { |
| | 679 | + function isExpired() { |
| 676 | 680 | wfDebug( "Block::isExpired() checking current " . wfTimestampNow() . " vs $this->mExpiry\n" ); |
| 677 | 681 | if ( !$this->mExpiry ) { |
| 678 | 682 | return false; |
| — | — | @@ -684,16 +688,14 @@ |
| 685 | 689 | * Is the block address valid (i.e. not a null string?) |
| 686 | 690 | * @return bool |
| 687 | 691 | */ |
| 688 | | - function isValid() |
| 689 | | - { |
| | 692 | + function isValid() { |
| 690 | 693 | return $this->mAddress != ''; |
| 691 | 694 | } |
| 692 | 695 | |
| 693 | 696 | /** |
| 694 | 697 | * Update the timestamp on autoblocks. |
| 695 | 698 | */ |
| 696 | | - function updateTimestamp() |
| 697 | | - { |
| | 699 | + function updateTimestamp() { |
| 698 | 700 | if ( $this->mAuto ) { |
| 699 | 701 | $this->mTimestamp = wfTimestamp(); |
| 700 | 702 | $this->mExpiry = Block::getAutoblockExpiry( $this->mTimestamp ); |
| — | — | @@ -710,19 +712,9 @@ |
| 711 | 713 | } |
| 712 | 714 | } |
| 713 | 715 | |
| 714 | | - /* |
| 715 | | - function getIntegerAddr() |
| 716 | | - { |
| 717 | | - return $this->mIntegerAddr; |
| 718 | | - } |
| 719 | | - |
| 720 | | - function getNetworkBits() |
| 721 | | - { |
| 722 | | - return $this->mNetworkBits; |
| 723 | | - }*/ |
| 724 | | - |
| 725 | 716 | /** |
| 726 | 717 | * Get the user id of the blocking sysop |
| | 718 | + * |
| 727 | 719 | * @return int |
| 728 | 720 | */ |
| 729 | 721 | public function getBy() { |
| — | — | @@ -731,21 +723,31 @@ |
| 732 | 724 | |
| 733 | 725 | /** |
| 734 | 726 | * Get the username of the blocking sysop |
| | 727 | + * |
| 735 | 728 | * @return string |
| 736 | 729 | */ |
| 737 | | - function getByName() |
| 738 | | - { |
| | 730 | + function getByName() { |
| 739 | 731 | return $this->mByName; |
| 740 | 732 | } |
| 741 | 733 | |
| | 734 | + /** |
| | 735 | + * Get/set the SELECT ... FOR UPDATE flag |
| | 736 | + */ |
| 742 | 737 | function forUpdate( $x = NULL ) { |
| 743 | 738 | return wfSetVar( $this->mForUpdate, $x ); |
| 744 | 739 | } |
| 745 | 740 | |
| | 741 | + /** |
| | 742 | + * Get/set a flag determining whether the master is used for reads |
| | 743 | + */ |
| 746 | 744 | function fromMaster( $x = NULL ) { |
| 747 | 745 | return wfSetVar( $this->mFromMaster, $x ); |
| 748 | 746 | } |
| 749 | 747 | |
| | 748 | + /** |
| | 749 | + * Get the block name, but with autoblocked IPs hidden as per standard privacy policy |
| | 750 | + * @return string |
| | 751 | + */ |
| 750 | 752 | function getRedactedName() { |
| 751 | 753 | if ( $this->mAuto ) { |
| 752 | 754 | return '#' . $this->mId; |
| — | — | @@ -756,6 +758,7 @@ |
| 757 | 759 | |
| 758 | 760 | /** |
| 759 | 761 | * Encode expiry for DB |
| | 762 | + * |
| 760 | 763 | * @return string |
| 761 | 764 | * @param $expiry string Timestamp for expiry, or |
| 762 | 765 | * @param $db Database object |
| — | — | @@ -770,6 +773,7 @@ |
| 771 | 774 | |
| 772 | 775 | /** |
| 773 | 776 | * Decode expiry which has come from the DB |
| | 777 | + * |
| 774 | 778 | * @return string |
| 775 | 779 | * @param $expiry string Database expiry format |
| 776 | 780 | * @param $timestampType Requested timestamp format |
| — | — | @@ -784,10 +788,10 @@ |
| 785 | 789 | |
| 786 | 790 | /** |
| 787 | 791 | * Get a timestamp of the expiry for autoblocks |
| | 792 | + * |
| 788 | 793 | * @return string |
| 789 | 794 | */ |
| 790 | | - static function getAutoblockExpiry( $timestamp ) |
| 791 | | - { |
| | 795 | + static function getAutoblockExpiry( $timestamp ) { |
| 792 | 796 | global $wgAutoblockExpiry; |
| 793 | 797 | return wfTimestamp( TS_MW, wfTimestamp( TS_UNIX, $timestamp ) + $wgAutoblockExpiry ); |
| 794 | 798 | } |
| — | — | @@ -836,16 +840,21 @@ |
| 837 | 841 | } |
| 838 | 842 | |
| 839 | 843 | /** |
| 840 | | - * This is a special keyword for timestamps in PostgreSQL, and |
| 841 | | - * works with CHAR(14) as well because "i" sorts after all numbers. |
| | 844 | + * Get a value to insert into expiry field of the database when infinite expiry |
| | 845 | + * is desired. In principle this could be DBMS-dependant, but currently all |
| | 846 | + * supported DBMS's support the string "infinity", so we just use that. |
| | 847 | + * |
| 842 | 848 | * @return string |
| 843 | 849 | */ |
| 844 | 850 | static function infinity() { |
| | 851 | + # This is a special keyword for timestamps in PostgreSQL, and |
| | 852 | + # works with CHAR(14) as well because "i" sorts after all numbers. |
| 845 | 853 | return 'infinity'; |
| 846 | 854 | } |
| 847 | 855 | |
| 848 | 856 | /** |
| 849 | 857 | * Convert a DB-encoded expiry into a real string that humans can read. |
| | 858 | + * |
| 850 | 859 | * @param $encoded_expiry string Database encoded expiry time |
| 851 | 860 | * @return string |
| 852 | 861 | */ |