Add split and getNetworkPrefix to IP ranges (#93)

* [feat] add method split to range ips, to convert range smaller range

* [refactor] change split method to array

* [style]

* [refactor] delete interface split

* [test] add test

* [style]

* [test] php 5.3, 5.4, 5.5 compatibility

* Describe the type of the result of the split method

* Be sure that we receive an int as the argument of the split method

* Always run all tests

* Fix and simplify tests

* Use Coveralls only for the mlocati's repo

* Simplify "if" statements

* Document that split() can throw a \RuntimeException

* Optimization + accept a network prefix that's the same as the range's one

* Use OutOfBoundsException if $networkPrefix is invalid

* Check maximum range sizes for 32-bit systems

* Fix running Coveralls

* [feat] handle pattern range and update DocBlock

* [fix] move split method to single class

* [fix] fix class pattern

* [chore] update return type

* [test] add single test and pattern test

* [style] add readme

* [style]

* Add getNetworkPrefix() to RangeInterface

This implies checking $networkPrefix for Single::split() too, without efforts

* Add $forceSubnet parameter, test overflow for 64-bit systems too

* Fix coding style

* Improve documentation about the split() method

* Add @SInCE to split()

---------

Co-authored-by: Michele Locati <[email protected]>

Author: alissn

.github/workflows/tests.yml

@@ -66,6 +66,7 @@ jobs:
     env:
       CODE_COVERAGE_TOOL: none
     strategy:
+      fail-fast: false
       matrix:
         os:
           - ubuntu-latest
@@ -95,7 +96,7 @@ jobs:
     steps:
       -
         name: Set code coverage
-        if: startsWith(matrix.os, 'ubuntu') && matrix.php-version == '7.2'
+        if: startsWith(matrix.os, 'ubuntu') && matrix.php-version == '7.2' && github.repository_owner == 'mlocati'
         run: |
           echo "CODE_COVERAGE_TOOL=xdebug" >> $GITHUB_ENV
       -
@@ -119,31 +120,31 @@ jobs:
         run: composer --ansi --no-interaction --no-progress --optimize-autoloader --ignore-platform-reqs update
       -
         name: Run PHPUnit (without code coverage)
-        if: ${{ env.CODE_COVERAGE_TOOL == 'none' }}
+        if: env.CODE_COVERAGE_TOOL == 'none'
         run: composer --ansi --no-interaction run-script test
       -
         name: Run PHPUnit (with code coverage)
-        if: ${{ env.CODE_COVERAGE_TOOL != 'none' }}
+        if: env.CODE_COVERAGE_TOOL != 'none'
         run: composer --ansi --no-interaction run-script test -- --coverage-clover coverage-clover.xml
       -
         name: Download Coveralls
-        if: ${{ env.CODE_COVERAGE_TOOL != 'none' }}
+        if: env.CODE_COVERAGE_TOOL != 'none'
         run: curl -sSLf -o php-coveralls.phar https://github.com/php-coveralls/php-coveralls/releases/download/v2.5.3/php-coveralls.phar
       -
         name: Upload Coveralls data
-        if: ${{ env.CODE_COVERAGE_TOOL != 'none' }}
+        if: env.CODE_COVERAGE_TOOL != 'none'
         env:
           COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: >
           php php-coveralls.phar
           --coverage_clover=coverage-clover.xml --json_path=coveralls-upload.json --ansi --no-interaction -vvv
       -
         name: Download Scrutinizer
-        if: ${{ env.CODE_COVERAGE_TOOL != 'none' }}
+        if: env.CODE_COVERAGE_TOOL != 'none'
         run: curl -sSLf -o ocular.phar https://scrutinizer-ci.com/ocular.phar
       -
         name: Upload Scrutinizer data
-        if: ${{ env.CODE_COVERAGE_TOOL != 'none' }}
+        if: env.CODE_COVERAGE_TOOL != 'none'
         run: >
           php ocular.phar code-coverage:upload
           --format=php-clover --ansi --no-interaction

README.md

@@ -370,6 +370,57 @@ echo \IPLib\Factory::parseRangeString('10.0.0.0/8')->asPattern()->toString();
 
 Please remark that all the range types implement the `asPattern()` and `asSubnet()` methods.
 
+### Splitting IP ranges
+
+If you need to divide an IP address range into smaller ranges, you can use the `split` method.
+You can specify the length of the network prefix, as well as indicate whether you want to force the Subnet notation (by default, it is not).
+
+For example:
+
+```php
+$subnet = \IPLib\Factory::parseRangeString('192.168.112.203/24');
+$smallerSubnets = $subnet->split(25);
+print_r(array_map('strval', $smallerSubnets));
+/*
+ * You'll have:
+ * Array
+ * (
+ *     [0] => 192.168.112.0/25
+ *     [1] => 192.168.112.128/25
+ * )
+ */
+
+$subnet = \IPLib\Factory::parseRangeString('192.168.*.*');
+$smallerSubnets = $subnet->split(24);
+print_r(array_map('strval', $smallerSubnets));
+/*
+ * You'll have:
+ * Array
+ * (
+ *     [0] => 192.168.0.*
+ *     [1] => 192.168.1.*
+ *     [...]
+ *     [254] => 192.168.254.*
+ *     [255] => 192.168.255.*
+ * )
+ */
+
+$subnet = \IPLib\Factory::parseRangeString('192.168.*.*');
+$smallerSubnets = $subnet->split(24, true);
+print_r(array_map('strval', $smallerSubnets));
+/*
+ * You'll have:
+ * Array
+ * (
+ *     [0] => 192.168.0.0/24
+ *     [1] => 192.168.1.0/24
+ *     [...]
+ *     [254] => 192.168.254.0/24
+ *     [255] => 192.168.255.0/24
+ * )
+ */
+```
+
 ### Getting the subnet mask for IPv4 ranges
 
 You can use the `getSubnetMask()` to get the subnet mask for IPv4 ranges:

src/Range/AbstractRange.php

@@ -7,6 +7,8 @@
 use IPLib\Address\IPv6;
 use IPLib\Address\Type as AddressType;
 use IPLib\Factory;
+use OutOfBoundsException;
+use OverflowException;
 
 /**
  * Base class for range classes.
@@ -122,4 +124,48 @@ public function containsRange(RangeInterface $range)
 
         return $result;
     }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see \IPLib\Range\RangeInterface::split()
+     */
+    public function split($networkPrefix, $forceSubnet = false)
+    {
+        $networkPrefix = (int) $networkPrefix;
+        $myNetworkPrefix = $this->getNetworkPrefix();
+        if ($networkPrefix === $myNetworkPrefix) {
+            return array(
+                $forceSubnet ? $this->asSubnet() : $this,
+            );
+        }
+        if ($networkPrefix < $myNetworkPrefix) {
+            throw new OutOfBoundsException("The value of the \$networkPrefix parameter can't be smaller than the network prefix of the range ({$myNetworkPrefix})");
+        }
+        $startIp = $this->getStartAddress();
+        $maxPrefix = $startIp::getNumberOfBits();
+        if ($networkPrefix > $maxPrefix) {
+            throw new OutOfBoundsException("The value of the \$networkPrefix parameter can't be larger than the maximum network prefix of the range ({$maxPrefix})");
+        }
+
+        $systemBitness = PHP_INT_SIZE * 8;
+        $minPrefixByBitness = $maxPrefix - $systemBitness + 2;
+        if ($networkPrefix < $minPrefixByBitness) {
+            throw new OverflowException("The value of \$networkPrefix leads to too large ranges for the current machine bitness (you can use a value of at least {$minPrefixByBitness})");
+        }
+
+        $chunkSize = pow(2, $maxPrefix - $networkPrefix);
+        $maxIndex = $this->getSize() / $chunkSize;
+        $data = array();
+        for ($i = 0; $i < $maxIndex; $i++) {
+            $range = Subnet::parseString(sprintf('%s/%d', $startIp, $networkPrefix));
+            if (!$forceSubnet && $this instanceof Pattern) {
+                $range = $range->asPattern() ?: $range;
+            }
+            $data[] = $range;
+            $startIp = $startIp->getAddressAtOffset($chunkSize);
+        }
+
+        return $data;
+    }
 }

src/Range/Pattern.php

@@ -308,9 +308,11 @@ public function getSize()
     }
 
     /**
-     * @return float|int
+     * {@inheritdoc}
+     *
+     * @see \IPLib\Range\RangeInterface::getNetworkPrefix()
      */
-    private function getNetworkPrefix()
+    public function getNetworkPrefix()
     {
         switch ($this->getAddressType()) {
             case AddressType::T_IPv4:

src/Range/RangeInterface.php

@@ -157,4 +157,31 @@ public function getReverseDNSLookupName();
      * @since 1.16.0
      */
     public function getSize();
+
+    /**
+     * Get the "network prefix", that is how many bits of the address are dedicated to the network portion.
+     *
+     * @return int
+     *
+     * @since 1.19.0
+     *
+     * @example for 10.0.0.0/24 it's 24
+     * @example for 10.0.0.* it's 24
+     */
+    public function getNetworkPrefix();
+
+    /**
+     * Split the range into smaller ranges.
+     *
+     * @param int $networkPrefix
+     * @param bool $forceSubnet set to true to always have ranges in "subnet format" (ie 1.2.3.4/5), to false to try to keep the original format if possible (that is, pattern to pattern, single to single)
+     *
+     * @throws \OutOfBoundsException if $networkPrefix is not valid
+     * @throws \OverflowException if you are running a 32-bit system and the ranges are too wide
+     *
+     * @return \IPLib\Range\RangeInterface[]
+     *
+     * @since 1.19.0
+     */
+    public function split($networkPrefix, $forceSubnet = false);
 }

src/Range/Single.php

@@ -190,12 +190,7 @@ public function getComparableEndString()
      */
     public function asSubnet()
     {
-        $networkPrefixes = array(
-            AddressType::T_IPv4 => 32,
-            AddressType::T_IPv6 => 128,
-        );
-
-        return new Subnet($this->address, $this->address, $networkPrefixes[$this->address->getAddressType()]);
+        return new Subnet($this->address, $this->address, $this->getNetworkPrefix());
     }
 
     /**
@@ -241,4 +236,19 @@ public function getSize()
     {
         return 1;
     }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see \IPLib\Range\RangeInterface::getNetworkPrefix()
+     */
+    public function getNetworkPrefix()
+    {
+        switch ($this->getAddressType()) {
+            case AddressType::T_IPv4:
+                return 32;
+            case AddressType::T_IPv6:
+                return 128;
+        }
+    }
 }

src/Range/Subnet.php

@@ -261,10 +261,9 @@ public static function get6to4()
     }
 
     /**
-     * Get subnet prefix.
-     *
-     * @return int
+     * {@inheritdoc}
      *
+     * @see \IPLib\Range\RangeInterface::getNetworkPrefix()
      * @since 1.7.0
      */
     public function getNetworkPrefix()