Rename IP::isValidBlock to isValidRange, deprecating the former

This is to remove confusion with the MediaWiki Block class.

All instances of isValidBlock within MediaWiki core have been updated.

Usage of this function will be more widespread with this patch:
https://gerrit.wikimedia.org/r/#/c/349457/

Change-Id: Ice1bdae3d16cf365da14c6df0e8d91d2b914e067

diff --git a/RELEASE-NOTES-1.30 b/RELEASE-NOTES-1.30
index 0cb6508..c7270ee 100644 (file)
--- a/RELEASE-NOTES-1.30
+++ b/RELEASE-NOTES-1.30
@@ -152,6 +152,7 @@ changes to languages because of Phabricator reports.
   WikiPage::makeParserOptions() to create the ParserOptions object and only
   change options that affect the parser cache key.
 * Article::viewRedirect() is deprecated.
+* IP::isValidBlock() was deprecated. Use the equivalent IP::isValidRange().
 * DeprecatedGlobal no longer supports passing in a direct value, it requires a
   callable factory function or a class name.
 * The $parserMemc global, wfGetParserCacheStorage(), and ParserCache::singleton()

diff --git a/includes/Block.php b/includes/Block.php
index 5066038..05e97b9 100644 (file)
--- a/includes/Block.php
+++ b/includes/Block.php
@@ -1354,7 +1354,7 @@ class Block {
                                self::TYPE_IP
                        ];
 
-               } elseif ( IP::isValidBlock( $target ) ) {
+               } elseif ( IP::isValidRange( $target ) ) {
                        # Can't create a User from an IP range
                        return [ IP::sanitizeRange( $target ), self::TYPE_RANGE ];
                }

diff --git a/includes/libs/IP.php b/includes/libs/IP.php
index bde8c69..3bfb531 100644 (file)
--- a/includes/libs/IP.php
+++ b/includes/libs/IP.php
@@ -23,14 +23,14 @@
 
 use IPSet\IPSet;
 
-// Some regex definition to "play" with IP address and IP address blocks
+// Some regex definition to "play" with IP address and IP address ranges
 
 // An IPv4 address is made of 4 bytes from x00 to xFF which is d0 to d255
 define( 'RE_IP_BYTE', '(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|0?[0-9]?[0-9])' );
 define( 'RE_IP_ADD', RE_IP_BYTE . '\.' . RE_IP_BYTE . '\.' . RE_IP_BYTE . '\.' . RE_IP_BYTE );
-// An IPv4 block is an IP address and a prefix (d1 to d32)
+// An IPv4 range is an IP address and a prefix (d1 to d32)
 define( 'RE_IP_PREFIX', '(3[0-2]|[12]?\d)' );
-define( 'RE_IP_BLOCK', RE_IP_ADD . '\/' . RE_IP_PREFIX );
+define( 'RE_IP_RANGE', RE_IP_ADD . '\/' . RE_IP_PREFIX );
 
 // An IPv6 address is made up of 8 words (each x0000 to xFFFF).
 // However, the "::" abbreviation can be used on consecutive x0000 words.
@@ -47,8 +47,8 @@ define( 'RE_IPV6_ADD',
                RE_IPV6_WORD . '(?::' . RE_IPV6_WORD . '){7}' .
        ')'
 );
-// An IPv6 block is an IP address and a prefix (d1 to d128)
-define( 'RE_IPV6_BLOCK', RE_IPV6_ADD . '\/' . RE_IPV6_PREFIX );
+// An IPv6 range is an IP address and a prefix (d1 to d128)
+define( 'RE_IPV6_RANGE', RE_IPV6_ADD . '\/' . RE_IPV6_PREFIX );
 // For IPv6 canonicalization (NOT for strict validation; these are quite lax!)
 define( 'RE_IPV6_GAP', ':(?:0+:)*(?::(?:0+:)*)?' );
 define( 'RE_IPV6_V4_PREFIX', '0*' . RE_IPV6_GAP . '(?:ffff:)?' );
@@ -64,7 +64,7 @@ define( 'IP_ADDRESS_STRING',
 
 /**
  * A collection of public static functions to play with IP address
- * and IP blocks.
+ * and IP ranges.
  */
 class IP {
 
@@ -116,16 +116,30 @@ class IP {
        }
 
        /**
-        * Validate an IP Block (valid address WITH a valid prefix).
+        * Validate an IP range (valid address with a valid CIDR prefix).
         * SIIT IPv4-translated addresses are rejected.
         * @note canonicalize() tries to convert translated addresses to IPv4.
         *
-        * @param string $ipblock
+        * @deprecated since 1.30. Use the equivalent IP::isValidRange().
+        * @param string $ipRange
         * @return bool True if it is valid
         */
-       public static function isValidBlock( $ipblock ) {
-               return ( preg_match( '/^' . RE_IPV6_BLOCK . '$/', $ipblock )
-                       || preg_match( '/^' . RE_IP_BLOCK . '$/', $ipblock ) );
+       public static function isValidBlock( $ipRange ) {
+               return self::isValidRange( $ipRange );
+       }
+
+       /**
+        * Validate an IP range (valid address with a valid CIDR prefix).
+        * SIIT IPv4-translated addresses are rejected.
+        * @note canonicalize() tries to convert translated addresses to IPv4.
+        *
+        * @param string $ipRange
+        * @return bool True if it is valid
+        * @since 1.30
+        */
+       public static function isValidRange( $ipRange ) {
+               return ( preg_match( '/^' . RE_IPV6_RANGE . '$/', $ipRange )
+                       || preg_match( '/^' . RE_IP_RANGE . '$/', $ipRange ) );
        }
 
        /**

diff --git a/tests/phpunit/includes/libs/IPTest.php b/tests/phpunit/includes/libs/IPTest.php
index 307652d..e47c4ba 100644 (file)
--- a/tests/phpunit/includes/libs/IPTest.php
+++ b/tests/phpunit/includes/libs/IPTest.php
@@ -237,7 +237,7 @@ class IPTest extends PHPUnit_Framework_TestCase {
                ];
                foreach ( $ipCIDRs as $i ) {
                        $this->assertFalse( IP::isValid( $i ),
-                               "$i is an invalid IP address because it is a block" );
+                               "$i is an invalid IP address because it is a range" );
                }
                // Incomplete/garbage
                $invalid = [
@@ -254,9 +254,9 @@ class IPTest extends PHPUnit_Framework_TestCase {
        }
 
        /**
-        * Provide some valid IP blocks
+        * Provide some valid IP ranges
         */
-       public function provideValidBlocks() {
+       public function provideValidRanges() {
                return [
                        [ '116.17.184.5/32' ],
                        [ '0.17.184.5/30' ],
@@ -274,22 +274,22 @@ class IPTest extends PHPUnit_Framework_TestCase {
        }
 
        /**
-        * @covers IP::isValidBlock
-        * @dataProvider provideValidBlocks
+        * @covers IP::isValidRange
+        * @dataProvider provideValidRanges
         */
-       public function testValidBlocks( $block ) {
-               $this->assertTrue( IP::isValidBlock( $block ), "$block is a valid IP block" );
+       public function testValidRanges( $range ) {
+               $this->assertTrue( IP::isValidRange( $range ), "$range is a valid IP range" );
        }
 
        /**
-        * @covers IP::isValidBlock
-        * @dataProvider provideInvalidBlocks
+        * @covers IP::isValidRange
+        * @dataProvider provideInvalidRanges
         */
-       public function testInvalidBlocks( $invalid ) {
-               $this->assertFalse( IP::isValidBlock( $invalid ), "$invalid is not a valid IP block" );
+       public function testInvalidRanges( $invalid ) {
+               $this->assertFalse( IP::isValidRange( $invalid ), "$invalid is not a valid IP range" );
        }
 
-       public function provideInvalidBlocks() {
+       public function provideInvalidRanges() {
                return [
                        [ '116.17.184.5/33' ],
                        [ '0.17.184.5/130' ],