Add Factory::getRangeFromAddresses() (#109)

Author: mlocati

README.md

@@ -235,6 +235,21 @@ $ranges = \IPLib\Factory::getRangesFromBoundaries('192.168.0.0', '192.168.0.5');
 echo implode(' ', $ranges);
 ```
 
+### Retrieve a range that contains a set of IP addresses
+
+You can use `IPLib\Factory::getRangeFromAddresses()` to retrieve the minimal IP range that contains all the provided IP addresses:
+
+```php
+$range = \IPLib\Factory::getRangeFromAddresses(array(
+  '1.2.2.225',
+  '1.2.1.124',
+  '1.2.3.237',
+));
+
+// This will print 1.2.0.0/22
+echo (string) $range;
+```
+
 ### Retrieve the boundaries of a range
 
 ```php

src/Factory.php

@@ -158,6 +158,53 @@ public static function getRangeFromBoundaries($from, $to, $flags = 0)
         return $from === false || $to === false ? null : static::rangeFromBoundaryAddresses($from, $to);
     }
 
+    /**
+     * Calculate the minimal range that contains all the specified addresses.
+     *
+     * @param array<non-empty-string|\IPLib\Address\AddressInterface|mixed> $addresses
+     * @param int $flags
+     *
+     * @return \IPLib\Range\RangeInterface|null Returns NULL if $addresses is empty, if it contains invalid addresses, or if the addresses aren't compatible (for example, both IPv4 and IPv6 addresses)
+     *
+     * @since 1.22.0
+     */
+    public static function getRangeFromAddresses(array $addresses, $flags = 0)
+    {
+        $min = null;
+        $max = null;
+        $numberOfBits = null;
+        foreach ($addresses as $address) {
+            if (!$address instanceof AddressInterface) {
+                $address = Factory::parseAddressString($address, $flags);
+                if ($address === null) {
+                    return null;
+                }
+            }
+            if ($numberOfBits === null) {
+                $min = $address;
+                $max = $address;
+                $numberOfBits = $address->getNumberOfBits();
+            } elseif ($numberOfBits !== $address->getNumberOfBits()) {
+                return null;
+            } else {
+                /** @var AddressInterface $min */
+                /** @var AddressInterface $max */
+                $comparable = $address->getComparableString();
+                if ($min->getComparableString() > $comparable) {
+                    $min = $address;
+                }
+                if ($max->getComparableString() < $comparable) {
+                    $max = $address;
+                }
+            }
+        }
+        if ($numberOfBits === null) {
+            return null;
+        }
+
+        return static::rangeFromBoundaryAddresses($min, $max);
+    }
+
     /**
      * @deprecated since 1.17.0: use the getRangesFromBoundaries() method instead.
      * For upgrading:
@@ -265,7 +312,7 @@ protected static function rangeFromBoundaryAddresses($from = null, $to = null)
      * @param string|\IPLib\Address\AddressInterface|mixed $to
      * @param int $flags
      *
-     * @return \IPLib\Address\AddressInterface[]|null[]|false[]
+     * @return array{\IPLib\Address\AddressInterface|false|null, \IPLib\Address\AddressInterface|false|null}
      */
     private static function parseBoundaries($from, $to, $flags = 0)
     {
@@ -285,6 +332,7 @@ private static function parseBoundaries($from, $to, $flags = 0)
             }
             $result[] = $value;
         }
+        /** @var array{\IPLib\Address\AddressInterface|false|null, \IPLib\Address\AddressInterface|false|null} $result */
         if ($result[0] && $result[1] && strcmp($result[0]->getComparableString(), $result[1]->getComparableString()) > 0) {
             $result = array($result[1], $result[0]);
         }

test/tests/Ranges/RangeFromAddressesTest.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace IPLib\Test\Ranges;
+
+use IPLib\Factory;
+use IPLib\ParseStringFlag;
+use IPLib\Test\TestCase;
+
+class RangeFromAddressesTest extends TestCase
+{
+    /**
+     * @return array{mixed}[]
+     */
+    public function invalidProvider()
+    {
+        return array(
+            array(array()),
+            array(array(null)),
+            array(array(false)),
+            array(array('')),
+            array(array('1.2.3.4.5')),
+            array(array('127.0.0.1', '::1')),
+            array(array(Factory::parseAddressString('127.0.0.1'), '::1')),
+        );
+    }
+
+    /**
+     * @dataProvider invalidProvider
+     *
+     * @param array{mixed} $addresses
+     *
+     * @return void
+     */
+    public function testInvalid(array $addresses)
+    {
+        $this->assertNull(Factory::getRangeFromAddresses($addresses));
+    }
+
+    /**
+     * @return array{array{mixed}, string, 2?: int}[]
+     */
+    public function validProvider()
+    {
+        return array(
+            array(array('1.2.3.4'), '1.2.3.4'),
+            array(array('1.2.3.4', Factory::parseAddressString('1.2.3.4')), '1.2.3.4'),
+            array(array('0.0.0.0'), '0.0.0.0'),
+            array(array('255.255.255.255'), '255.255.255.255'),
+            array(array('0.0.0.0', '255.255.255.255'), '0.0.0.0/0'),
+            array(array('0.0.0.0', '127.255.255.255'), '0.0.0.0/1'),
+            array(array('128.0.0.0', '255.255.255.255'), '128.0.0.0/1'),
+            array(array('255.255.255.255', '128.0.0.0', '128.0.0.0'), '128.0.0.0/1'),
+            array(array(Factory::parseAddressString('::')), '::'),
+            array(array(Factory::parseAddressString('::')), '::'),
+            array(
+                array(
+                    '131.100.75.124',
+                    '131.100.72.225',
+                    '131.100.72.237',
+                    '131.100.72.96',
+                    '131.100.73.125',
+                    '131.100.73.139',
+                    '131.100.74.24',
+                    '131.100.74.243:80',
+                ),
+                '131.100.72.0/22',
+                ParseStringFlag::MAY_INCLUDE_PORT,
+            ),
+        );
+    }
+
+    /**
+     * @dataProvider validProvider
+     *
+     * @param non-empty-array{non-empty-string|\IPLib\Address\AddressInterface} $addresses
+     * @param non-empty-string $expectedSubnetStringRepresentation
+     * @param int $flags
+     *
+     * @return void
+     */
+    public function testValid(array $addresses, $expectedSubnetStringRepresentation, $flags = 0)
+    {
+        $subnet = Factory::getRangeFromAddresses($addresses, $flags);
+        $this->assertNotNull($subnet);
+        $this->assertSame($expectedSubnetStringRepresentation, (string) $subnet);
+    }
+}