├── .gitattributes
├── .gitignore
├── src
    ├── Exception
    │   ├── IpException.php
    │   ├── Formatter
    │   │   └── FormatException.php
    │   ├── InvalidIpAddressException.php
    │   ├── WrongVersionException.php
    │   ├── InvalidCidrException.php
    │   └── Strategy
    │   │   ├── PackingException.php
    │   │   └── ExtractionException.php
    ├── Formatter
    │   ├── ProtocolFormatterInterface.php
    │   ├── NativeFormatter.php
    │   └── ConsistentFormatter.php
    ├── Version
    │   ├── MultiVersionInterface.php
    │   ├── Version4Interface.php
    │   ├── Version6Interface.php
    │   ├── IPv4.php
    │   ├── IPv6.php
    │   └── Multi.php
    ├── Strategy
    │   ├── EmbeddingStrategyInterface.php
    │   ├── Compatible.php
    │   ├── Mapped.php
    │   └── Derived.php
    ├── Util
    │   ├── MbString.php
    │   └── Binary.php
    ├── IpInterface.php
    └── AbstractIP.php
├── phpstan.neon
├── composer.json
├── LICENSE.md
├── CHANGELOG.md
├── README.md
└── CODE_OF_CONDUCT.md


/.gitattributes:
--------------------------------------------------------------------------------
1 | * text=auto
2 | 
3 | /.github/ export-ignore
4 | /docs/ export-ignore
5 | /tests/ export-ignore
6 | /mkdocs.yaml export-ignore
7 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /.idea/
2 | /build/
3 | /gh-pages/
4 | /vendor/
5 | # Because this library will never be the root package, don't commit Composer's lock file.
6 | /composer.lock
7 | 


--------------------------------------------------------------------------------
/src/Exception/IpException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Exception;
 6 | 
 7 | class IpException extends \Exception
 8 | {
 9 | }
10 | 


--------------------------------------------------------------------------------
/phpstan.neon:
--------------------------------------------------------------------------------
 1 | parameters:
 2 |     level: 'max'
 3 |     paths: [ 'src', 'tests' ]
 4 |     checkFunctionNameCase: true
 5 |     reportUnmatchedIgnoredErrors: true
 6 |     treatPhpDocTypesAsCertain: false
 7 |     parallel:
 8 |         maximumNumberOfProcesses: 4
 9 |     ignoreErrors:
10 |         -
11 |             # This project purposefully uses variable constructors and "new static()".
12 |             identifier: new.static
13 | 
14 | includes:
15 |     - 'vendor/phpstan/phpstan-deprecation-rules/rules.neon'
16 |     - 'vendor/phpstan/phpstan/conf/bleedingEdge.neon'
17 | 


--------------------------------------------------------------------------------
/src/Formatter/ProtocolFormatterInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Formatter;
 6 | 
 7 | interface ProtocolFormatterInterface
 8 | {
 9 |     /**
10 |      * Protocol to Binary
11 |      *
12 |      * @throws \Darsyn\IP\Exception\Formatter\FormatException
13 |      */
14 |     public function pton(string $binary): string;
15 | 
16 |     /**
17 |      * Binary to Protocol
18 |      *
19 |      * @throws \Darsyn\IP\Exception\Formatter\FormatException
20 |      */
21 |     public function ntop(string $binary): string;
22 | }
23 | 


--------------------------------------------------------------------------------
/src/Exception/Formatter/FormatException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Exception\Formatter;
 6 | 
 7 | use Darsyn\IP\Exception\IpException;
 8 | 
 9 | class FormatException extends IpException
10 | {
11 |     /** @var string $binary */
12 |     private $binary;
13 | 
14 |     public function __construct(string $binary, ?\Exception $previous = null)
15 |     {
16 |         $this->binary = $binary;
17 |         parent::__construct('Cannot format invalid binary sequence; must be a string either 4 or 16 bytes long.', 0, $previous);
18 |     }
19 | 
20 |     public function getSuppliedBinary(): string
21 |     {
22 |         return $this->binary;
23 |     }
24 | }
25 | 


--------------------------------------------------------------------------------
/src/Exception/InvalidIpAddressException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Exception;
 6 | 
 7 | class InvalidIpAddressException extends IpException
 8 | {
 9 |     /** @var mixed $ip */
10 |     private $ip;
11 | 
12 |     /**
13 |      * Constructor
14 |      *
15 |      * @param scalar $ip
16 |      */
17 |     public function __construct($ip, ?\Exception $previous = null)
18 |     {
19 |         $this->ip = $ip;
20 |         parent::__construct('The IP address supplied is not valid.', 0, $previous);
21 |     }
22 | 
23 |     /**
24 |      * @return mixed
25 |      */
26 |     public function getSuppliedIp()
27 |     {
28 |         return $this->ip;
29 |     }
30 | }
31 | 


--------------------------------------------------------------------------------
/src/Exception/WrongVersionException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Exception;
 6 | 
 7 | class WrongVersionException extends InvalidIpAddressException
 8 | {
 9 |     /** @var int $expected */
10 |     private $expected;
11 | 
12 |     /** @var int $actual */
13 |     private $actual;
14 | 
15 |     /**
16 |      * @param scalar $ip
17 |      * @param \Exception|null $previous
18 |      */
19 |     public function __construct(int $expected, int $actual, $ip, ?\Exception $previous = null)
20 |     {
21 |         $this->expected = $expected;
22 |         $this->actual = $actual;
23 |         parent::__construct($ip, $previous);
24 |     }
25 | 
26 |     public function getExpectedVersion(): int
27 |     {
28 |         return $this->expected;
29 |     }
30 | 
31 |     public function getActualVersion(): int
32 |     {
33 |         return $this->actual;
34 |     }
35 | }
36 | 


--------------------------------------------------------------------------------
/src/Version/MultiVersionInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Version;
 6 | 
 7 | use Darsyn\IP\Strategy\EmbeddingStrategyInterface;
 8 | 
 9 | interface MultiVersionInterface extends Version4Interface, Version6Interface
10 | {
11 |     /**
12 |      * Set the default embedding strategy to be used for all new instances of
13 |      * this class that do not specify their own embedding strategy.
14 |      */
15 |     public static function setDefaultEmbeddingStrategy(EmbeddingStrategyInterface $strategy): void;
16 | 
17 |     /**
18 |      * Get Protocol-appropriate Address
19 |      *
20 |      * Converts an IP address into the smallest protocol notation it can;
21 |      * dot-notation for IPv4, and compacted (double colons) notation for IPv6.
22 |      * Only IPv4 addresses according to the embedding strategy used will be
23 |      * returned in dot-notation.
24 |      */
25 |     public function getProtocolAppropriateAddress(): string;
26 | }
27 | 


--------------------------------------------------------------------------------
/src/Strategy/EmbeddingStrategyInterface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Strategy;
 6 | 
 7 | interface EmbeddingStrategyInterface
 8 | {
 9 |     /**
10 |      * Checks if the IPv6 binary string supplied contains an IPv4 embedded
11 |      * according to the implemented embedding strategy.
12 |      */
13 |     public function isEmbedded(string $binary): bool;
14 | 
15 |     /**
16 |      * Extract the embedded IPv4 binary string from the IPv6 binary string
17 |      * supplied, according to the implemented embedding strategy.
18 |      *
19 |      * @throws \Darsyn\IP\Exception\Strategy\ExtractionException
20 |      */
21 |     public function extract(string $binary): string;
22 | 
23 |     /**
24 |      * Convert the supplied IPv4 binary string into an embedded IPv6 binary
25 |      * string, according to the implemented embedding strategy.
26 |      *
27 |      * @throws \Darsyn\IP\Exception\Strategy\PackingException
28 |      */
29 |     public function pack(string $binary): string;
30 | }
31 | 


--------------------------------------------------------------------------------
/src/Exception/InvalidCidrException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Exception;
 6 | 
 7 | class InvalidCidrException extends IpException
 8 | {
 9 |     /** @var mixed $cidr */
10 |     private $cidr;
11 | 
12 |     /**
13 |      * Constructor
14 |      *
15 |      * @param mixed $cidr
16 |      * @param mixed $addressLengthInBytes
17 |      */
18 |     public function __construct($cidr, $addressLengthInBytes, ?\Exception $previous = null)
19 |     {
20 |         $this->cidr = $cidr;
21 |         $message = 'The supplied CIDR is not valid; it must be an integer ';
22 |         if (!\is_int($addressLengthInBytes)) {
23 |             $message .= '(could not determine valid CIDR range).';
24 |         } else {
25 |             $message .= \sprintf('(between 0 and %d).', $addressLengthInBytes * 8);
26 |         }
27 |         parent::__construct($message, 0, $previous);
28 |     }
29 | 
30 |     /**
31 |      * @return mixed
32 |      */
33 |     public function getSuppliedCidr()
34 |     {
35 |         return $this->cidr;
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "darsyn/ip",
 3 |     "description": "An immutable IP Address value object that provides several different notations, including helper functions.",
 4 |     "license": "MIT",
 5 |     "keywords": ["library", "value-object", "immutable", "ip", "ipv4", "ipv6"],
 6 |     "type": "library",
 7 |     "homepage": "https://github.com/darsyn/ip",
 8 |     "authors": [
 9 |         {
10 |             "name": "Zan Baldwin",
11 |             "email": "hello@zanbaldwin.com",
12 |             "homepage": "https://zanbaldwin.com"
13 |         }
14 |     ],
15 |     "autoload": {
16 |         "psr-4": {
17 |             "Darsyn\\IP\\": "src/"
18 |         }
19 |     },
20 |     "require": {
21 |         "php-64bit": ">=7.1",
22 |         "php-ipv6": ">=7.1",
23 |         "ext-ctype": "*"
24 |     },
25 |     "autoload-dev": {
26 |         "psr-4": {
27 |             "Darsyn\\IP\\Tests\\": "tests/"
28 |         }
29 |     },
30 |     "require-dev": {
31 |         "phpunit/phpunit": "*"
32 |     },
33 |     "prefer-stable": true,
34 |     "config": {
35 |         "sort-packages": true
36 |     },
37 |     "suggest": {
38 |         "darsyn/ip-doctrine": "to use IP as a Doctrine column type"
39 |     }
40 | }
41 | 


--------------------------------------------------------------------------------
/src/Exception/Strategy/PackingException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Exception\Strategy;
 6 | 
 7 | use Darsyn\IP\Exception\IpException;
 8 | use Darsyn\IP\Strategy\EmbeddingStrategyInterface;
 9 | 
10 | class PackingException extends IpException
11 | {
12 |     /** @var string $binary */
13 |     private $binary;
14 | 
15 |     /** @var \Darsyn\IP\Strategy\EmbeddingStrategyInterface $embeddingStrategy */
16 |     private $embeddingStrategy;
17 | 
18 |     public function __construct(string $binary, EmbeddingStrategyInterface $embeddingStrategy, ?\Exception $previous = null)
19 |     {
20 |         $this->binary = $binary;
21 |         $this->embeddingStrategy = $embeddingStrategy;
22 |         parent::__construct(\sprintf(
23 |             'Could not pack IPv4 address into IPv6 binary string using the "%s" strategy.',
24 |             \get_class($embeddingStrategy)
25 |         ), 0, $previous);
26 |     }
27 | 
28 |     public function getSuppliedBinary(): string
29 |     {
30 |         return $this->binary;
31 |     }
32 | 
33 |     public function getEmbeddingStrategy(): EmbeddingStrategyInterface
34 |     {
35 |         return $this->embeddingStrategy;
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/src/Strategy/Compatible.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Strategy;
 6 | 
 7 | use Darsyn\IP\Exception\Strategy as StrategyException;
 8 | use Darsyn\IP\Util\MbString;
 9 | 
10 | class Compatible implements EmbeddingStrategyInterface
11 | {
12 |     /**
13 |      * {@inheritDoc}
14 |      */
15 |     public function isEmbedded(string $binary): bool
16 |     {
17 |         return MbString::getLength($binary) === 16
18 |             && MbString::subString($binary, 0, 12) === "\0\0\0\0\0\0\0\0\0\0\0\0";
19 |     }
20 | 
21 |     /**
22 |      * {@inheritDoc}
23 |      */
24 |     public function extract(string $binary): string
25 |     {
26 |         if (MbString::getLength($binary) === 16) {
27 |             return MbString::subString($binary, 12, 4);
28 |         }
29 |         throw new StrategyException\ExtractionException($binary, $this);
30 |     }
31 | 
32 |     /**
33 |      * {@inheritDoc}
34 |      */
35 |     public function pack(string $binary): string
36 |     {
37 |         if (MbString::getLength($binary) === 4) {
38 |             return "\0\0\0\0\0\0\0\0\0\0\0\0" . $binary;
39 |         }
40 |         throw new StrategyException\PackingException($binary, $this);
41 |     }
42 | }
43 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | The [MIT License](http://j.mp/mit-license)
 2 | ==========================================
 3 | 
 4 | Copyright (c) 2015 [Zan Baldwin](https://github.com/zanbaldwin)
 5 | 
 6 | Permission is hereby granted, free of charge, to any person obtaining a copy of
 7 | this software and associated documentation files (the "Software"), to deal in
 8 | the Software without restriction, including without limitation the rights to
 9 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
10 | the Software, and to permit persons to whom the Software is furnished to do so,
11 | subject to the following conditions:
12 | 
13 | The above copyright notice and this permission notice shall be included in all
14 | copies or substantial portions of the Software.
15 | 
16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
18 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
19 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
20 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/src/Version/Version4Interface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Version;
 6 | 
 7 | use Darsyn\IP\IpInterface;
 8 | 
 9 | interface Version4Interface extends IpInterface
10 | {
11 |     /**
12 |      * Get Dot Address
13 |      *
14 |      * Convert an IP into an IPv4 dot-notation address string
15 |      * This method will NOT work with IPv6 addresses.
16 |      *
17 |      * @throws \Darsyn\IP\Exception\IpException
18 |      * @throws \Darsyn\IP\Exception\WrongVersionException
19 |      */
20 |     public function getDotAddress(): string;
21 | 
22 |     /**
23 |      * Whether the IP is a broadcast address, according to RFC 919.
24 |      *
25 |      * @throws \Darsyn\IP\Exception\WrongVersionException
26 |      */
27 |     public function isBroadcast(): bool;
28 | 
29 |     /**
30 |      * Whether the IP is part of the Shared Address Space, according to RFC 6598.
31 |      *
32 |      * @throws \Darsyn\IP\Exception\WrongVersionException
33 |      */
34 |     public function isShared(): bool;
35 | 
36 |     /**
37 |      * Whether the IP is reserved for future use, according to RFC 1112.
38 |      *
39 |      * @throws \Darsyn\IP\Exception\WrongVersionException
40 |      */
41 |     public function isFutureReserved(): bool;
42 | }
43 | 


--------------------------------------------------------------------------------
/src/Strategy/Mapped.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Strategy;
 6 | 
 7 | use Darsyn\IP\Exception\Strategy as StrategyException;
 8 | use Darsyn\IP\Util\Binary;
 9 | use Darsyn\IP\Util\MbString;
10 | 
11 | class Mapped implements EmbeddingStrategyInterface
12 | {
13 |     /**
14 |      * {@inheritDoc}
15 |      */
16 |     public function isEmbedded(string $binary): bool
17 |     {
18 |         return MbString::getLength($binary) === 16
19 |             && MbString::subString($binary, 0, 12) === Binary::fromHex('00000000000000000000ffff');
20 |     }
21 | 
22 |     /**
23 |      * {@inheritDoc}
24 |      */
25 |     public function extract(string $binary): string
26 |     {
27 |         if (MbString::getLength($binary) === 16) {
28 |             return MbString::subString($binary, 12, 4);
29 |         }
30 |         throw new StrategyException\ExtractionException($binary, $this);
31 |     }
32 | 
33 |     /**
34 |      * {@inheritDoc}
35 |      */
36 |     public function pack(string $binary): string
37 |     {
38 |         if (MbString::getLength($binary) === 4) {
39 |             return Binary::fromHex('00000000000000000000ffff') . $binary;
40 |         }
41 |         throw new StrategyException\PackingException($binary, $this);
42 |     }
43 | }
44 | 


--------------------------------------------------------------------------------
/src/Strategy/Derived.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Strategy;
 6 | 
 7 | use Darsyn\IP\Exception\Strategy as StrategyException;
 8 | use Darsyn\IP\Util\Binary;
 9 | use Darsyn\IP\Util\MbString;
10 | 
11 | class Derived implements EmbeddingStrategyInterface
12 | {
13 |     /**
14 |      * {@inheritDoc}
15 |      */
16 |     public function isEmbedded(string $binary): bool
17 |     {
18 |         return MbString::getLength($binary) === 16
19 |             && MbString::subString($binary, 0, 2) === Binary::fromHex('2002')
20 |             && MbString::subString($binary, 6, 10) === "\0\0\0\0\0\0\0\0\0\0";
21 |     }
22 | 
23 |     /**
24 |      * {@inheritDoc}
25 |      */
26 |     public function extract(string $binary): string
27 |     {
28 |         if (MbString::getLength($binary) === 16) {
29 |             return MbString::subString($binary, 2, 4);
30 |         }
31 |         throw new StrategyException\ExtractionException($binary, $this);
32 |     }
33 | 
34 |     /**
35 |      * {@inheritDoc}
36 |      */
37 |     public function pack(string $binary): string
38 |     {
39 |         if (MbString::getLength($binary) === 4) {
40 |             return Binary::fromHex('2002') . $binary . "\0\0\0\0\0\0\0\0\0\0";
41 |         }
42 |         throw new StrategyException\PackingException($binary, $this);
43 |     }
44 | }
45 | 


--------------------------------------------------------------------------------
/src/Exception/Strategy/ExtractionException.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Exception\Strategy;
 6 | 
 7 | use Darsyn\IP\Exception\IpException;
 8 | use Darsyn\IP\Strategy\EmbeddingStrategyInterface;
 9 | 
10 | class ExtractionException extends IpException
11 | {
12 |     /** @var string $binary */
13 |     private $binary;
14 | 
15 |     /** @var \Darsyn\IP\Strategy\EmbeddingStrategyInterface $embeddingStrategy */
16 |     private $embeddingStrategy;
17 | 
18 |     /**
19 |      * @param string $binary
20 |      * @param \Darsyn\IP\Strategy\EmbeddingStrategyInterface $embeddingStrategy
21 |      * @param \Exception|null $previous
22 |      */
23 |     public function __construct(string $binary, EmbeddingStrategyInterface $embeddingStrategy, ?\Exception $previous = null)
24 |     {
25 |         $this->binary = $binary;
26 |         $this->embeddingStrategy = $embeddingStrategy;
27 |         parent::__construct(\sprintf(
28 |             'Could not extract IPv4 address from IPv6 binary string using the "%s" strategy.',
29 |             \get_class($embeddingStrategy)
30 |         ), 0, $previous);
31 |     }
32 | 
33 |     public function getSuppliedBinary(): string
34 |     {
35 |         return $this->binary;
36 |     }
37 | 
38 |     public function getEmbeddingStrategy(): EmbeddingStrategyInterface
39 |     {
40 |         return $this->embeddingStrategy;
41 |     }
42 | }
43 | 


--------------------------------------------------------------------------------
/src/Util/MbString.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Util;
 6 | 
 7 | class MbString
 8 | {
 9 |     public static function getLength(string $str): int
10 |     {
11 |         return \function_exists('\\mb_strlen')
12 |             ? \mb_strlen($str, '8bit')
13 |             : (int) (\strlen(\bin2hex($str)) / 2);
14 |     }
15 | 
16 |     public static function subString(string $str, int $start, ?int $length = null): string
17 |     {
18 |         if (\function_exists('\\mb_substr')) {
19 |             return (\mb_substr($str, $start, $length, '8bit') ?: '');
20 |         }
21 |         return is_int($length)
22 |             ? (\substr($str, $start, $length) ?: '')
23 |             // On PHP versions 7.2 to 7.4, the $length argument cannot be null.
24 |             // The official PHP docs do not mention this peculiarity.
25 |             : (\substr($str, $start) ?: '');
26 |     }
27 | 
28 |     /**
29 |      * PHP doesn't have a function for multibyte string padding. This should suffice in case
30 |      * PHP's internal string functions have been overloaded by the mbstring extension.
31 |      */
32 |     public static function padString(string $input, int $paddingLength, string $padding = ' ', int $type = \STR_PAD_RIGHT): string
33 |     {
34 |         $diff = \strlen($input) - static::getLength($input);
35 |         return \str_pad($input, $paddingLength + $diff, $padding, $type);
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/src/Version/Version6Interface.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Version;
 6 | 
 7 | use Darsyn\IP\IpInterface;
 8 | 
 9 | interface Version6Interface extends IpInterface
10 | {
11 |     const MULTICAST_INTERFACE_LOCAL = 1;
12 |     const MULTICAST_LINK_LOCAL = 2;
13 |     const MULTICAST_REALM_LOCAL = 3;
14 |     const MULTICAST_ADMIN_LOCAL = 4;
15 |     const MULTICAST_SITE_LOCAL = 5;
16 |     const MULTICAST_ORGANIZATION_LOCAL = 8;
17 |     const MULTICAST_GLOBAL = 14;
18 | 
19 |     /**
20 |      * Get Compacted Address
21 |      *
22 |      * Converts an IP (regardless of version) into a compacted IPv6 address
23 |      * (including double-colons if appropriate).
24 |      *
25 |      * @throws \Darsyn\IP\Exception\IpException
26 |      */
27 |     public function getCompactedAddress(): string;
28 | 
29 |     /**
30 |      * Get Expanded Address
31 |      *
32 |      * Converts an IP (regardless of version) address into a full IPv6 address
33 |      * (no double colons).
34 |      *
35 |      * @throws \Darsyn\IP\Exception\IpException
36 |      */
37 |     public function getExpandedAddress(): string;
38 | 
39 |     /**
40 |      * Returns the IP address’s multicast scope if the address is multicast,
41 |      * null otherwise. Return values are integers mapped to the MULTICAST_*
42 |      * constants on this interface.
43 |      */
44 |     public function getMulticastScope(): ?int;
45 | 
46 |     /**
47 |      * Whether the IP is a unique local address, according to RFC 4193.
48 |      */
49 |     public function isUniqueLocal(): bool;
50 | 
51 |     /**
52 |      * Whether the IP is a unicast address, according to RFC 4291.
53 |      */
54 |     public function isUnicast(): bool;
55 | 
56 |     /**
57 |      * Whether the IP is a globally routable unicast address, according to
58 |      * RFC 2941.
59 |      */
60 |     public function isUnicastGlobal(): bool;
61 | }
62 | 


--------------------------------------------------------------------------------
/src/Formatter/NativeFormatter.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Formatter;
 6 | 
 7 | use Darsyn\IP\Exception\Formatter\FormatException;
 8 | use Darsyn\IP\Util\MbString;
 9 | 
10 | class NativeFormatter implements ProtocolFormatterInterface
11 | {
12 |     /**
13 |      * {@inheritDoc}
14 |      */
15 |     public function ntop(string $binary): string
16 |     {
17 |         $length = MbString::getLength($binary);
18 |         if ($length === 16 || $length === 4) {
19 |             $pack = \pack(\sprintf('A%d', $length), $binary);
20 |             // $pack return type is `string|false` below PHP 8 and `string`
21 |             // above PHP 8.
22 |             // @phpstan-ignore identical.alwaysFalse
23 |             if (false === $pack || false === $protocol = \inet_ntop($pack)) {
24 |                 throw new FormatException($binary);
25 |             }
26 |             return $protocol;
27 |         }
28 |         throw new FormatException($binary);
29 |     }
30 | 
31 |     /**
32 |      * {@inheritDoc}
33 |      */
34 |     public function pton(string $binary): string
35 |     {
36 |         if (\filter_var($binary, \FILTER_VALIDATE_IP, \FILTER_FLAG_IPV4)) {
37 |             $number = \inet_pton($binary);
38 |             if (false === $number
39 |                 || false === ($sequence = \unpack('a4', $number))
40 |                 || !is_string($return = \current($sequence))
41 |             ) {
42 |                 throw new FormatException($binary);
43 |             }
44 |             return $return;
45 |         }
46 |         if (\filter_var($binary, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
47 |             $number = \inet_pton($binary);
48 |             if (false === $number
49 |                 || false === ($sequence = \unpack('a16', $number))
50 |                 || !is_string($return = \current($sequence))
51 |             ) {
52 |                 throw new FormatException($binary);
53 |             }
54 |             return $return;
55 |         }
56 |         $length = MbString::getLength($binary);
57 |         if ($length === 4 || $length === 16) {
58 |             return $binary;
59 |         }
60 |         throw new FormatException($binary);
61 |     }
62 | }
63 | 


--------------------------------------------------------------------------------
/src/Util/Binary.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Util;
 6 | 
 7 | class Binary
 8 | {
 9 |     /**
10 |      * @param string $hex
11 |      * @throws \InvalidArgumentException
12 |      * @return string
13 |      */
14 |     public static function fromHex(string $hex): string
15 |     {
16 |         if (!(\ctype_xdigit($hex) || $hex === '') || MbString::getLength($hex) % 2 !== 0) {
17 |             throw new \InvalidArgumentException('Valid hexadecimal string not provided.');
18 |         }
19 |         return \pack('H*', \strtolower($hex));
20 |     }
21 | 
22 |     /**
23 |      * @param string $binary
24 |      * @throws \InvalidArgumentException
25 |      * @return string
26 |      */
27 |     public static function toHex(string $binary): string
28 |     {
29 |         if (false === ($data = \unpack('H*', $binary)) || !is_string($hex = \reset($data))) {
30 |             throw new \InvalidArgumentException('Unknown error converting string to hexadecimal.');
31 |         }
32 |         return $hex;
33 |     }
34 | 
35 |     /**
36 |      * @param string $asciiBinarySequence
37 |      * @throws \InvalidArgumentException
38 |      * @return string
39 |      */
40 |     public static function fromHumanReadable(string $asciiBinarySequence): string
41 |     {
42 |         if (!\preg_match('/^[01]*$/', $asciiBinarySequence)
43 |             || MbString::getLength($asciiBinarySequence) % 8 !== 0
44 |         ) {
45 |             throw new \InvalidArgumentException('Valid (ASCII) binary sequence not provided.');
46 |         }
47 |         return $asciiBinarySequence === '' ? '' : static::fromHex(\implode('', \array_map(function ($byteRepresentation) {
48 |             return MbString::padString(\dechex((int) \bindec($byteRepresentation)), 2, '0', \STR_PAD_LEFT);
49 |         }, \function_exists('mb_str_split') ? \mb_str_split($asciiBinarySequence, 8, '8bit') : \str_split($asciiBinarySequence, 8))));
50 |     }
51 | 
52 |     /**
53 |      * @param string $binary
54 |      * @throws \InvalidArgumentException
55 |      * @return string
56 |      */
57 |     public static function toHumanReadable(string $binary): string
58 |     {
59 |         $hex = static::toHex($binary);
60 |         return \implode('', \array_map(function ($character) {
61 |             return MbString::padString(\decbin((int) \hexdec($character)), 8, '0', \STR_PAD_LEFT);
62 |         }, \function_exists('mb_str_split') ? \mb_str_split($hex, 2, '8bit') : \str_split($hex, 2)));
63 |     }
64 | }
65 | 


--------------------------------------------------------------------------------
/src/Formatter/ConsistentFormatter.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Darsyn\IP\Formatter;
 6 | 
 7 | use Darsyn\IP\Exception\Formatter\FormatException;
 8 | use Darsyn\IP\Util\Binary;
 9 | use Darsyn\IP\Util\MbString;
10 | 
11 | class ConsistentFormatter extends NativeFormatter
12 | {
13 |     /**
14 |      * {@inheritDoc}
15 |      */
16 |     public function ntop(string $binary): string
17 |     {
18 |         $length = MbString::getLength($binary);
19 |         if ($length === 16) {
20 |             return $this->ntopVersion6($binary);
21 |         }
22 |         if ($length === 4) {
23 |             return $this->ntopVersion4($binary);
24 |         }
25 |         throw new FormatException($binary);
26 |     }
27 | 
28 |     private function ntopVersion6(string $binary): string
29 |     {
30 |         $hex = Binary::toHex($binary);
31 |         $parts = \str_split($hex, 4);
32 |         $zeroes = \array_map(function ($part) {
33 |             return $part === '0000';
34 |         }, $parts);
35 |         $length = $i = 0;
36 |         $sequences = [];
37 |         foreach ($zeroes as $zero) {
38 |             $length = $zero ? ++$length : 0;
39 |             $sequences[++$i] = $length;
40 |         }
41 |         if (\count($sequences) > 0) {
42 |             $maxLength = \max($sequences);
43 |             $endPosition = \array_search($maxLength, $sequences, true);
44 |             if (!\is_int($endPosition)) {
45 |                 throw new \RuntimeException;
46 |             }
47 |             $startPosition = $endPosition - $maxLength;
48 |         } else {
49 |             $maxLength = $startPosition = 0;
50 |         }
51 |         $parts = \array_map(function ($part) {
52 |             return \ltrim($part, '0') ?: '0';
53 |         }, $parts);
54 |         if ($maxLength > 0) {
55 |             \array_splice($parts, $startPosition, $maxLength, ':');
56 |         }
57 |         if (null === $shortened = \preg_replace('/\:{2,}/', '::', \implode(':', $parts))) {
58 |             throw new FormatException($binary);
59 |         }
60 |         return \str_pad($shortened, 2, ':');
61 |     }
62 | 
63 |     private function ntopVersion4(string $binary): string
64 |     {
65 |         // $pack return type is `string|false` below PHP 8 and `string`
66 |         // above PHP 8.
67 |         $pack = \pack('A4', $binary);
68 |         // @phpstan-ignore identical.alwaysFalse
69 |         if (false === $pack || false === $protocol = \inet_ntop($pack)) {
70 |             throw new FormatException($binary);
71 |         }
72 |         return $protocol;
73 |     }
74 | }
75 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Darsyn IP
 2 | 
 3 | ## `5.0.0`
 4 | 
 5 | - Removed Doctrine functionality, and split it off into its own package:
 6 |   [`darsyn/ip-doctrine`](https://packagist.org/packages/darsyn/ip-doctrine).
 7 |   List it as a Composer dependency suggestion.
 8 | - Change from [Psalm](https://psalm.dev/) to [PHPStan](https://phpstan.org/) for
 9 |   static analysis.
10 |   - Add types to all function arguments lists and return values.
11 |   - Update the codebase to pass static analysis on `max` level (standard,
12 |     deprecation, and bleeding edge rules).
13 | - Test against PHP versions `8.2` and `8.3` in CI pipeline.
14 | - Update README with notes on version compatibility.
15 | - Explicitly state the requirement of the `ctype` PHP extension.
16 | - Add PHPUnit attributes alongside annotations to be compatible with the highest
17 |   version of PHPUnit for any supported PHP version.
18 | 
19 | ## `4.1.0`
20 | 
21 | - Added `IpInterface::equals()` method for comparing two IP addresses.
22 | - Added `getCommonCidr(IpInterface $ip): int` for determining how in range two
23 |   IP addresses are according to their common CIDR value.
24 | - Added `isBenchmarking()`, `isDocumentation()`, and `isPublicUse()` type
25 |   methods for both IPv4 and IPv6 addresses.
26 | - Added `isBroadcast()`, `isShared()`, and `isFutureReserved()` type methods for
27 |   IPv4 addresses.
28 | - Added `getMulticastScope()`, `isUniqueLocal()`, `isUnicast()`, and
29 |   `isUnicastGlobal()` type methods for IPv6 addresses.
30 | - Added `Ipv6::fromEmbedded()` factory method to create an instance of an
31 |   IPv4-embedded address as IPv6 instead of Multi.
32 | - Made internal helper methods for dealing with binary data into utility
33 |   classes: `Darsyn\IP\Util\Binary` and `Darsyn\IP\Util\MbString`.
34 | - Complete documentation overhaul
35 | - Increase test coverage.
36 | - Started using static analysis both locally and via GitHub actions.
37 | - Documentation and tests are excluded from the Git archive to reduce download
38 |   size when installing Composer dependency as dist.
39 | - Updated Code of Conduct to Contributor Covenant v2.1
40 | 
41 | ## `4.0.2`
42 | 
43 | - Add return types to DocComments to prevent
44 |   [`symfony/error-handler`](https://github.com/symfony/symfony/tree/5.4/src/Symfony/Component/ErrorHandler)
45 |   from throwing deprecation errors
46 | 
47 | ## `4.0.1`
48 | 
49 | - Add Code of Conduct to project.
50 | - Add new internal helper for dealing with binary strings.
51 | - Add namespace indicator to function calls to speed up symbol resolution.
52 | - Add `__toString()` to IP objects.
53 | - Update unit tests, now runnable on all PHP versions 5.6 to 8.1
54 | 
55 | ## `4.0.0`
56 | 
57 | - Complete rewrite of library.
58 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | IP is an immutable value object for (both version 4 and 6) IP addresses. Several
 2 | helper methods are provided for ranges, broadcast and network addresses, subnet
 3 | masks, whether an IP is a certain type (defined by RFC's), etc.
 4 | 
 5 | This project aims for simplicity of use and any contribution towards that goal -
 6 | whether a bug report, modifications to the codebase, or an improvement to the
 7 | accuracy or readability of the documentation - are always welcome.
 8 | 
 9 | # Documentation
10 | 
11 | Full documentation is available in the [`docs/`](docs/) folder.
12 | 
13 | ## Compatibility
14 | 
15 | This library has extensive test coverage using PHPUnit on PHP versions: `7.1`,
16 | `7.2`, `7.3`, `7.4`, `8.0`, `8.1`, `8.2`, `8.3` and `8.4`.
17 | 
18 | > Versions `5.x.x` of this library are compatible with PHP versions `5.6` to
19 | > `8.3` (and will continue to receive bug fixes).
20 | >
21 | > Versions `6.x.x` of this library are compatible with PHP versions `7.1` and
22 | > above, and will receive continued support for future versions of PHP (also
23 | > accepting proposed new features).
24 | 
25 | Static analysis is performed with PHPStan at `max` level on PHP `8.4`, using
26 | core, bleeding edge, and deprecation rules.
27 | 
28 | > The Doctrine features for this library have been split off into their own
29 | > package, [`darsyn/ip-doctrine`](https://packagist.org/packages/darsyn/ip-doctrine).
30 | 
31 | ## Brief Example
32 | 
33 | - There are three main classes: [`IPv4`](src/Version/IPv4.php),
34 |   [`IPv6`](src/Version/IPv6.php), and [`Multi`](src/Version/Multi.php) (for both
35 |   version 4 and 6 addresses).
36 | - Objects are created using a static factory method
37 |   [`IpInterface::factory()`](src/IpInterface.php) instead of the constructor to
38 |   speed up internal processes.
39 | - When using `Multi`, the default strategy for representing version 4 addresses
40 |   internally is [IPv4-mapped](docs/05-strategies.md).
41 | 
42 | ```php
43 | <?php declare(strict_types=1);
44 | 
45 | use Darsyn\IP\Exception;
46 | use Darsyn\IP\Version\IPv4;
47 | 
48 | try {
49 |     $ip = IPv4::factory('192.168.0.1');
50 | } catch (Exception\InvalidIpAddressException $e) {
51 |     exit('The IP address supplied is invalid!');
52 | }
53 | 
54 | $companyNetwork = IPv4::factory('216.58.198.174');
55 | if (!$ip->inRange($companyNetwork, 25)) {
56 |     throw new \Exception('Request not from a known company IP address.');
57 | }
58 | 
59 | // Is it coming from the local network?
60 | if (!$ip->isPrivateUse()) {
61 |     record_visit($ip->getBinary(), $_SERVER['HTTP_USER_AGENT']);
62 | }
63 | ```
64 | 
65 | ## Code of Conduct
66 | 
67 | This project includes and adheres to the [Contributor Covenant as a Code of
68 | Conduct](CODE_OF_CONDUCT.md).
69 | 
70 | # License
71 | 
72 | Please see the [separate license file](LICENSE.md) included in this repository
73 | for a full copy of the MIT license, which this project is licensed under.
74 | 
75 | # Authors
76 | 
77 | - [Zan Baldwin](https://zanbaldwin.com)
78 | - [Jaume Casado Ruiz](http://jau.cat)
79 | - [Pascal Hofmann](http://pascalhofmann.de)
80 | 
81 | If you make a contribution (submit a pull request), don't forget to add your
82 | name here!
83 | 


--------------------------------------------------------------------------------
/src/IpInterface.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Darsyn\IP;
  6 | 
  7 | interface IpInterface
  8 | {
  9 |     /**
 10 |      * @throws \Darsyn\IP\Exception\InvalidIpAddressException
 11 |      * @throws \Darsyn\IP\Exception\WrongVersionException
 12 |      * @return static
 13 |      */
 14 |     public static function factory(string $ip);
 15 | 
 16 |     /**
 17 |      * Get Binary Representation
 18 |      */
 19 |     public function getBinary(): string;
 20 | 
 21 |     /**
 22 |      * Do two IP objects represent the same IP address?
 23 |      */
 24 |     public function equals(self $ip): bool;
 25 | 
 26 |     /**
 27 |      * Get the IP version from the binary value
 28 |      */
 29 |     public function getVersion(): int;
 30 | 
 31 |     /**
 32 |      * Is Version?
 33 |      */
 34 |     public function isVersion(int $version): bool;
 35 | 
 36 |     /**
 37 |      * Whether the IP is version 4
 38 |      */
 39 |     public function isVersion4(): bool;
 40 | 
 41 |     /**
 42 |      * Whether the IP is version 6
 43 |      */
 44 |     public function isVersion6(): bool;
 45 | 
 46 |     /**
 47 |      * Get Network Address
 48 |      *
 49 |      * Get a new value object from the network address of the original IP.
 50 |      *
 51 |      * @throws \Darsyn\IP\Exception\InvalidCidrException
 52 |      * @return static
 53 |      */
 54 |     public function getNetworkIp(int $cidr);
 55 | 
 56 |     /**
 57 |      * Get Broadcast Address
 58 |      *
 59 |      * Get a new value object from the broadcast address of the original IP.
 60 |      *
 61 |      * @param int $cidr
 62 |      * @throws \Darsyn\IP\Exception\InvalidCidrException
 63 |      * @return static
 64 |      */
 65 |     public function getBroadcastIp(int $cidr);
 66 | 
 67 |     /**
 68 |      * Is IP Address In Range?
 69 |      *
 70 |      * Returns a boolean value depending on whether the IP address in question
 71 |      * is within the range of the target IP/CIDR combination.
 72 |      * Comparing two IPs of different byte-lengths (IPv4 vs IPv6/IPv4-embedded)
 73 |      * will throw a WrongVersionException.
 74 |      *
 75 |      * @throws \Darsyn\IP\Exception\InvalidCidrException
 76 |      * @throws \Darsyn\IP\Exception\WrongVersionException
 77 |      */
 78 |     public function inRange(self $ip, int $cidr): bool;
 79 | 
 80 |     /**
 81 |      * Get Common CIDR Between IP Addresses
 82 |      *
 83 |      * Returns the highest common CIDR between the current IP address and another
 84 |      *
 85 |      * @throws \Darsyn\IP\Exception\WrongVersionException
 86 |      */
 87 |     public function getCommonCidr(self $ip): int;
 88 | 
 89 |     /**
 90 |      * Whether the IP is an IPv4-mapped IPv6 address (eg, "::ffff:7f00:1").
 91 |      */
 92 |     public function isMapped(): bool;
 93 | 
 94 |     /**
 95 |      * Whether the IP is a 6to4-derived address (eg, "2002:7f00:1::").
 96 |      */
 97 |     public function isDerived(): bool;
 98 | 
 99 |     /**
100 |      * Whether the IP is an IPv4-compatible IPv6 address (eg, `::7f00:1`).
101 |      */
102 |     public function isCompatible(): bool;
103 | 
104 |     /**
105 |      * Whether the IP is an IPv4-embedded IPv6 address (according to the
106 |      * embedding strategy used).
107 |      */
108 |     public function isEmbedded(): bool;
109 | 
110 |     /**
111 |      * Whether the IP is reserved for link-local usage, according to
112 |      * RFC 3927/RFC 4291 (IPv4/IPv6).
113 |      */
114 |     public function isLinkLocal(): bool;
115 | 
116 |     /**
117 |      * Whether the IP is a loopback address, according to RFC 2373/RFC 3330
118 |      * (IPv4/IPv6).
119 |      */
120 |     public function isLoopback(): bool;
121 | 
122 |     /**
123 |      * Whether the IP is a multicast address, according to RFC 3171/RFC 2373
124 |      * (IPv4/IPv6).
125 |      */
126 |     public function isMulticast(): bool;
127 | 
128 |     /**
129 |      * Whether the IP is for private use, according to RFC 1918/RFC 4193
130 |      * (IPv4/IPv6).
131 |      */
132 |     public function isPrivateUse(): bool;
133 | 
134 |     /**
135 |      * Whether the IP is unspecified, according to RFC 5735/RFC 2373 (IPv4/IPv6).
136 |      */
137 |     public function isUnspecified(): bool;
138 | 
139 |     /**
140 |      * Whether the IP is reserved for network devices benchmarking, according
141 |      * to RFC 2544/RFC 5180 (IPv4/IPv6).
142 |      */
143 |     public function isBenchmarking(): bool;
144 | 
145 |     /**
146 |      * Whether the IP is in range designated for documentation, according to
147 |      * RFC 5737/RFC 3849 (IPv4/IPv6).
148 |      */
149 |     public function isDocumentation(): bool;
150 | 
151 |     /**
152 |      * Whether the IP appears to be publicly/globally routable. Please refer to
153 |      * the IANA Special-Purpose Address Registry documents.
154 |      *
155 |      * @see https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
156 |      * @see https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv6-special-registry.xhtml
157 |      */
158 |     public function isPublicUse(): bool;
159 | 
160 |     /**
161 |      * Implement string casting for IP objects.
162 |      */
163 |     public function __toString(): string;
164 | }
165 | 


--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
  1 | # Contributor Covenant Code of Conduct
  2 | 
  3 | ## Our Pledge
  4 | 
  5 | We as members, contributors, and leaders pledge to make participation in our
  6 | community a harassment-free experience for everyone, regardless of age, body
  7 | size, visible or invisible disability, ethnicity, sex characteristics, gender
  8 | identity and expression, level of experience, education, socio-economic status,
  9 | nationality, personal appearance, race, caste, color, religion, or sexual
 10 | identity and orientation.
 11 | 
 12 | We pledge to act and interact in ways that contribute to an open, welcoming,
 13 | diverse, inclusive, and healthy community.
 14 | 
 15 | ## Our Standards
 16 | 
 17 | Examples of behavior that contributes to a positive environment for our
 18 | community include:
 19 | 
 20 | * Demonstrating empathy and kindness toward other people
 21 | * Being respectful of differing opinions, viewpoints, and experiences
 22 | * Giving and gracefully accepting constructive feedback
 23 | * Accepting responsibility and apologizing to those affected by our mistakes,
 24 |   and learning from the experience
 25 | * Focusing on what is best not just for us as individuals, but for the overall
 26 |   community
 27 | 
 28 | Examples of unacceptable behavior include:
 29 | 
 30 | * The use of sexualized language or imagery, and sexual attention or advances of
 31 |   any kind
 32 | * Trolling, insulting or derogatory comments, and personal or political attacks
 33 | * Public or private harassment
 34 | * Publishing others' private information, such as a physical or email address,
 35 |   without their explicit permission
 36 | * Other conduct which could reasonably be considered inappropriate in a
 37 |   professional setting
 38 | 
 39 | ## Enforcement Responsibilities
 40 | 
 41 | Community leaders are responsible for clarifying and enforcing our standards of
 42 | acceptable behavior and will take appropriate and fair corrective action in
 43 | response to any behavior that they deem inappropriate, threatening, offensive,
 44 | or harmful.
 45 | 
 46 | Community leaders have the right and responsibility to remove, edit, or reject
 47 | comments, commits, code, wiki edits, issues, and other contributions that are
 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation
 49 | decisions when appropriate.
 50 | 
 51 | ## Scope
 52 | 
 53 | This Code of Conduct applies within all community spaces, and also applies when
 54 | an individual is officially representing the community in public spaces.
 55 | Examples of representing our community include using an official e-mail address,
 56 | posting via an official social media account, or acting as an appointed
 57 | representative at an online or offline event.
 58 | 
 59 | ## Enforcement
 60 | 
 61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be
 62 | reported to the community leaders responsible for enforcement at
 63 | `hello@zanbaldwin.com`.
 64 | All complaints will be reviewed and investigated promptly and fairly.
 65 | 
 66 | All community leaders are obligated to respect the privacy and security of the
 67 | reporter of any incident.
 68 | 
 69 | ## Enforcement Guidelines
 70 | 
 71 | Community leaders will follow these Community Impact Guidelines in determining
 72 | the consequences for any action they deem in violation of this Code of Conduct:
 73 | 
 74 | ### 1. Correction
 75 | 
 76 | **Community Impact**: Use of inappropriate language or other behavior deemed
 77 | unprofessional or unwelcome in the community.
 78 | 
 79 | **Consequence**: A private, written warning from community leaders, providing
 80 | clarity around the nature of the violation and an explanation of why the
 81 | behavior was inappropriate. A public apology may be requested.
 82 | 
 83 | ### 2. Warning
 84 | 
 85 | **Community Impact**: A violation through a single incident or series of
 86 | actions.
 87 | 
 88 | **Consequence**: A warning with consequences for continued behavior. No
 89 | interaction with the people involved, including unsolicited interaction with
 90 | those enforcing the Code of Conduct, for a specified period of time. This
 91 | includes avoiding interactions in community spaces as well as external channels
 92 | like social media. Violating these terms may lead to a temporary or permanent
 93 | ban.
 94 | 
 95 | ### 3. Temporary Ban
 96 | 
 97 | **Community Impact**: A serious violation of community standards, including
 98 | sustained inappropriate behavior.
 99 | 
100 | **Consequence**: A temporary ban from any sort of interaction or public
101 | communication with the community for a specified period of time. No public or
102 | private interaction with the people involved, including unsolicited interaction
103 | with those enforcing the Code of Conduct, is allowed during this period.
104 | Violating these terms may lead to a permanent ban.
105 | 
106 | ### 4. Permanent Ban
107 | 
108 | **Community Impact**: Demonstrating a pattern of violation of community
109 | standards, including sustained inappropriate behavior, harassment of an
110 | individual, or aggression toward or disparagement of classes of individuals.
111 | 
112 | **Consequence**: A permanent ban from any sort of public interaction within the
113 | community.
114 | 
115 | ## Attribution
116 | 
117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118 | version 2.1, available at
119 | [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120 | 
121 | Community Impact Guidelines were inspired by
122 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123 | 
124 | For answers to common questions about this code of conduct, see the FAQ at
125 | [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126 | [https://www.contributor-covenant.org/translations][translations].
127 | 
128 | [homepage]: https://www.contributor-covenant.org
129 | [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130 | [Mozilla CoC]: https://github.com/mozilla/diversity
131 | [FAQ]: https://www.contributor-covenant.org/faq
132 | [translations]: https://www.contributor-covenant.org/translations
133 | 


--------------------------------------------------------------------------------
/src/Version/IPv4.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Darsyn\IP\Version;
  6 | 
  7 | use Darsyn\IP\AbstractIP;
  8 | use Darsyn\IP\Exception;
  9 | use Darsyn\IP\Util\Binary;
 10 | use Darsyn\IP\Util\MbString;
 11 | 
 12 | /**
 13 |  * IPv4 Address
 14 |  *
 15 |  * IPv4 is an immutable value object for IP addresses, including some helper
 16 |  * functions for broadcast and network addresses, and whether its within the
 17 |  * range of another IP address according to a CIDR (subnet mask), etc.
 18 |  * This class deals solely with IPv4 addresses and will throw an
 19 |  * InvalidIpAddressException when IPv6 addresses are used.
 20 |  * Internally, the IP address is converted to a 4 byte binary sequence for easy
 21 |  * mathematical operations and consistency (for example, storing the IP address'
 22 |  * binary sequence in a fixed-length database column).
 23 |  *
 24 |  * @author    Zan Baldwin <hello@zanbaldwin.com>
 25 |  * @link      https://github.com/darsyn/ip
 26 |  * @copyright 2015 Zan Baldwin
 27 |  * @license   MIT/X11 <http://j.mp/mit-license>
 28 |  */
 29 | class IPv4 extends AbstractIP implements Version4Interface
 30 | {
 31 |     /**
 32 |      * {@inheritDoc}
 33 |      */
 34 |     public static function factory(string $ip)
 35 |     {
 36 |         try {
 37 |             // Convert from protocol notation to binary sequence.
 38 |             $binary = self::getProtocolFormatter()->pton($ip);
 39 |             // If the string was not 4 bytes long, then the IP supplied was
 40 |             // neither in protocol notation or binary sequence notation. Throw
 41 |             // an exception.
 42 |             if (MbString::getLength($binary) !== 4) {
 43 |                 if (MbString::getLength($ip) !== 4) {
 44 |                     throw new Exception\WrongVersionException(4, 6, $ip);
 45 |                 }
 46 |                 $binary = $ip;
 47 |             }
 48 |         } catch(Exception\IpException $e) {
 49 |             throw new Exception\InvalidIpAddressException($ip, $e);
 50 |         }
 51 |         return new static($binary);
 52 |     }
 53 | 
 54 |     /**
 55 |      * {@inheritDoc}
 56 |      */
 57 |     public function getDotAddress(): string
 58 |     {
 59 |         try {
 60 |             return self::getProtocolFormatter()->ntop($this->getBinary());
 61 |         } catch (Exception\Formatter\FormatException $e) {
 62 |             throw new Exception\IpException('An unknown error occured internally.', 0, $e);
 63 |         }
 64 |     }
 65 | 
 66 |     /**
 67 |      * {@inheritDoc}
 68 |      */
 69 |     public function getVersion(): int
 70 |     {
 71 |         return 4;
 72 |     }
 73 | 
 74 |     /**
 75 |      * {@inheritDoc}
 76 |      */
 77 |     public function isLinkLocal(): bool
 78 |     {
 79 |         return $this->inRange(new self(Binary::fromHex('a9fe0000')), 16);
 80 |     }
 81 | 
 82 |     /**
 83 |      * {@inheritDoc}
 84 |      */
 85 |     public function isLoopback(): bool
 86 |     {
 87 |         return $this->inRange(new self(Binary::fromHex('7f000000')), 8);
 88 |     }
 89 | 
 90 |     /**
 91 |      * {@inheritDoc}
 92 |      */
 93 |     public function isMulticast(): bool
 94 |     {
 95 |         return $this->inRange(new self(Binary::fromHex('e0000000')), 4);
 96 |     }
 97 | 
 98 |     /**
 99 |      * {@inheritDoc}
100 |      */
101 |     public function isPrivateUse(): bool
102 |     {
103 |         return $this->inRange(new self(Binary::fromHex('0a000000')), 8)
104 |             || $this->inRange(new self(Binary::fromHex('ac100000')), 12)
105 |             || $this->inRange(new self(Binary::fromHex('c0a80000')), 16);
106 |     }
107 | 
108 |     /**
109 |      * {@inheritDoc}
110 |      */
111 |     public function isUnspecified(): bool
112 |     {
113 |         return $this->getBinary() === "\0\0\0\0";
114 |     }
115 | 
116 |     /**
117 |      * {@inheritDoc}
118 |      */
119 |     public function isBenchmarking(): bool
120 |     {
121 |         return $this->inRange(new self(Binary::fromHex('c6120000')), 15);
122 |     }
123 | 
124 |     /**
125 |      * {@inheritDoc}
126 |      */
127 |     public function isDocumentation(): bool
128 |     {
129 |         return $this->inRange(new self(Binary::fromHex('c0000200')), 24)
130 |             || $this->inRange(new self(Binary::fromHex('c6336400')), 24)
131 |             || $this->inRange(new self(Binary::fromHex('cb007100')), 24);
132 |     }
133 | 
134 |     /**
135 |      * {@inheritDoc}
136 |      */
137 |     public function isPublicUse(): bool
138 |     {
139 |         // Both 192.0.0.9 and 192.0.0.10 are globally routable, despite being in the future reserved block.
140 |         if (in_array(Binary::toHex($this->getBinary()), ['c0000009', 'c000000a'], true)) {
141 |             return true;
142 |         }
143 | 
144 |         // The whole 0.0.0.0/8 block is not for public use.
145 |         if ($this->inRange(new self(Binary::fromHex('00000000')), 8)) {
146 |             return false;
147 |         }
148 | 
149 |         // Addresses reserved for future protocols are not globally routable (different to reserved for future use).
150 |         if ($this->inRange(new self(Binary::fromHex('c0000000')), 24)) {
151 |             return false;
152 |         }
153 | 
154 |         return !$this->isPrivateUse()
155 |             && !$this->isLoopback()
156 |             && !$this->isLinkLocal()
157 |             && !$this->isBroadcast()
158 |             && !$this->isShared()
159 |             && !$this->isDocumentation()
160 |             && !$this->isFutureReserved()
161 |             && !$this->isBenchmarking();
162 |     }
163 | 
164 |     /**
165 |      * {@inheritDoc}
166 |      */
167 |     public function isBroadcast(): bool
168 |     {
169 |         return $this->getBinary() === Binary::fromHex('ffffffff');
170 |     }
171 | 
172 |     /**
173 |      * {@inheritDoc}
174 |      */
175 |     public function isShared(): bool
176 |     {
177 |         return $this->inRange(new self(Binary::fromHex('64400000')), 10);
178 |     }
179 | 
180 |     /**
181 |      * {@inheritDoc}
182 |      */
183 |     public function isFutureReserved(): bool
184 |     {
185 |         return $this->getBinary() !== Binary::fromHex('ffffffff')
186 |             && $this->inRange(new self(Binary::fromHex('f0000000')), 4);
187 |     }
188 | 
189 |     /**
190 |      * {@inheritDoc}
191 |      */
192 |     public function __toString(): string
193 |     {
194 |         return $this->getDotAddress();
195 |     }
196 | }
197 | 


--------------------------------------------------------------------------------
/src/Version/IPv6.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Darsyn\IP\Version;
  6 | 
  7 | use Darsyn\IP\AbstractIP;
  8 | use Darsyn\IP\Exception;
  9 | use Darsyn\IP\Strategy\EmbeddingStrategyInterface;
 10 | use Darsyn\IP\Util\Binary;
 11 | use Darsyn\IP\Util\MbString;
 12 | 
 13 | /**
 14 |  * IPv6 Address
 15 |  *
 16 |  * IPv6 is an immutable value object for IP addresses, including some helper
 17 |  * functions for broadcast and network addresses, and whether its within the
 18 |  * range of another IP address according to a CIDR (subnet mask), etc.
 19 |  * This class deals solely with IPv6 addresses and will throw an
 20 |  * InvalidIpAddressException when IPv4 addresses are used.
 21 |  * Internally, the IP address is converted to a 16 byte binary sequence for easy
 22 |  * mathematical operations and consistency (for example, storing the IP address'
 23 |  * binary sequence in a fixed-length database column).
 24 |  *
 25 |  * @author    Zan Baldwin <hello@zanbaldwin.com>
 26 |  * @link      https://github.com/darsyn/ip
 27 |  * @copyright 2015 Zan Baldwin
 28 |  * @license   MIT/X11 <http://j.mp/mit-license>
 29 |  */
 30 | class IPv6 extends AbstractIP implements Version6Interface
 31 | {
 32 | 
 33 |     /**
 34 |      * {@inheritDoc}
 35 |      */
 36 |     public static function factory(string $ip)
 37 |     {
 38 |         try {
 39 |             // Convert from protocol notation to binary sequence.
 40 |             $binary = self::getProtocolFormatter()->pton($ip);
 41 |             // If the string was not 4 bytes long, then the IP supplied was neither
 42 |             // in protocol notation or binary sequence notation. Throw an exception.
 43 |             if (MbString::getLength($binary) !== 16) {
 44 |                 throw new Exception\WrongVersionException(6, 4, $ip);
 45 |             }
 46 |         } catch (Exception\IpException $e) {
 47 |             throw new Exception\InvalidIpAddressException($ip, $e);
 48 |         }
 49 |         return new static($binary);
 50 |     }
 51 | 
 52 |     /**
 53 |      * @param \Darsyn\IP\Strategy\EmbeddingStrategyInterface|null $strategy
 54 |      * @throws \Darsyn\IP\Exception\InvalidIpAddressException
 55 |      * @throws \Darsyn\IP\Exception\WrongVersionException
 56 |      * @return static
 57 |      */
 58 |     public static function fromEmbedded(string $ip, ?EmbeddingStrategyInterface $strategy = null)
 59 |     {
 60 |         return new static(Multi::factory($ip, $strategy)->getBinary());
 61 |     }
 62 | 
 63 |     /**
 64 |      * {@inheritDoc}
 65 |      */
 66 |     public function getExpandedAddress(): string
 67 |     {
 68 |         // Convert the 16-byte binary sequence into a hexadecimal-string
 69 |         // representation, insert a colon between every block of 4 characters,
 70 |         // and return the resulting IP address in full IPv6 protocol notation.
 71 |         $expanded = \preg_replace('/([a-fA-F0-9]{4})/', '$1:', Binary::toHex($this->getBinary()));
 72 |         return MbString::subString(\is_string($expanded) ? $expanded : '', 0, -1);
 73 |     }
 74 | 
 75 |     /**
 76 |      * {@inheritDoc}
 77 |      */
 78 |     public function getCompactedAddress(): string
 79 |     {
 80 |         try {
 81 |             return self::getProtocolFormatter()->ntop($this->getBinary());
 82 |         } catch (Exception\Formatter\FormatException $e) {
 83 |             throw new Exception\IpException('An unknown error occured internally.', 0, $e);
 84 |         }
 85 |     }
 86 | 
 87 |     /**
 88 |      * {@inheritDoc}
 89 |      */
 90 |     public function getVersion(): int
 91 |     {
 92 |         return 6;
 93 |     }
 94 | 
 95 |     /**
 96 |      * {@inheritDoc}
 97 |      */
 98 |     public function isLinkLocal(): bool
 99 |     {
100 |         return $this->inRange(new self(Binary::fromHex('fe800000000000000000000000000000')), 10);
101 |     }
102 | 
103 |     /**
104 |      * {@inheritDoc}
105 |      */
106 |     public function isLoopback(): bool
107 |     {
108 |         return $this->inRange(new self(Binary::fromHex('00000000000000000000000000000001')), 128);
109 |     }
110 | 
111 |     /**
112 |      * {@inheritDoc}
113 |      */
114 |     public function isMulticast(): bool
115 |     {
116 |         return $this->inRange(new self(Binary::fromHex('ff000000000000000000000000000000')), 8);
117 |     }
118 | 
119 |     /**
120 |      * {@inheritDoc}
121 |      */
122 |     public function getMulticastScope(): ?int
123 |     {
124 |         if (!$this->isMulticast()) {
125 |             return null;
126 |         }
127 |         $firstSegment = MbString::subString($this->getBinary(), 0, 2);
128 |         return (int) hexdec(Binary::toHex($firstSegment & Binary::fromHex('000f')));
129 |     }
130 | 
131 |     /**
132 |      * {@inheritDoc}
133 |      */
134 |     public function isPrivateUse(): bool
135 |     {
136 |         return $this->inRange(new self(Binary::fromHex('fd000000000000000000000000000000')), 8);
137 |     }
138 | 
139 |     /**
140 |      * {@inheritDoc}
141 |      */
142 |     public function isUnspecified(): bool
143 |     {
144 |         return $this->getBinary() === "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
145 |     }
146 | 
147 |     /**
148 |      * @inheritDoc
149 |      */
150 |     public function isBenchmarking(): bool
151 |     {
152 |         return $this->inRange(new self(Binary::fromHex('20010002000000000000000000000000')), 48);
153 |     }
154 | 
155 |     /**
156 |      * @inheritDoc
157 |      */
158 |     public function isDocumentation(): bool
159 |     {
160 |         return $this->inRange(new self(Binary::fromHex('20010db8000000000000000000000000')), 32);
161 |     }
162 | 
163 |     /**
164 |      * @inheritDoc
165 |      */
166 |     public function isPublicUse(): bool
167 |     {
168 |         return $this->getMulticastScope() === self::MULTICAST_GLOBAL || $this->isUnicastGlobal();
169 |     }
170 | 
171 |     /**
172 |      * @inheritDoc
173 |      */
174 |     public function isUniqueLocal(): bool
175 |     {
176 |         return $this->inRange(new self(Binary::fromHex('fc000000000000000000000000000000')), 7);
177 |     }
178 | 
179 |     /**
180 |      * @inheritDoc
181 |      */
182 |     public function isUnicast(): bool
183 |     {
184 |         return !$this->isMulticast();
185 |     }
186 | 
187 |     /**
188 |      * @inheritDoc
189 |      */
190 |     public function isUnicastGlobal(): bool
191 |     {
192 |         return $this->isUnicast()
193 |             && !$this->isLoopback()
194 |             && !$this->isLinkLocal()
195 |             && !$this->isUniqueLocal()
196 |             && !$this->isUnspecified()
197 |             && !$this->isDocumentation();
198 |     }
199 | 
200 |     /**
201 |      * {@inheritDoc}
202 |      */
203 |     public function __toString(): string
204 |     {
205 |         return $this->getCompactedAddress();
206 |     }
207 | }
208 | 


--------------------------------------------------------------------------------
/src/AbstractIP.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Darsyn\IP;
  6 | 
  7 | use Darsyn\IP\Exception\WrongVersionException;
  8 | use Darsyn\IP\Formatter\ConsistentFormatter;
  9 | use Darsyn\IP\Formatter\ProtocolFormatterInterface;
 10 | use Darsyn\IP\Util\Binary;
 11 | use Darsyn\IP\Util\MbString;
 12 | 
 13 | abstract class AbstractIP implements IpInterface
 14 | {
 15 |     /** @var \Darsyn\IP\Formatter\ProtocolFormatterInterface $formatter */
 16 |     protected static $formatter;
 17 | 
 18 |     /**
 19 |      * Keep this private to prevent modification of object's main value from
 20 |      * child classes.
 21 |      * @var string $ip
 22 |      */
 23 |     private $ip;
 24 | 
 25 |     public static function setProtocolFormatter(ProtocolFormatterInterface $formatter): void
 26 |     {
 27 |         self::$formatter = $formatter;
 28 |     }
 29 | 
 30 |     /**
 31 |      * Get the protocol formatter set by the user, falling back to using our
 32 |      * custom formatter for consistency by default if the user has not set one
 33 |      * globally.
 34 |      */
 35 |     protected static function getProtocolFormatter(): ProtocolFormatterInterface
 36 |     {
 37 |         if (null === self::$formatter) {
 38 |             self::$formatter = new ConsistentFormatter;
 39 |         }
 40 |         return self::$formatter;
 41 |     }
 42 | 
 43 |     protected function __construct(string $ip)
 44 |     {
 45 |         $this->ip = $ip;
 46 |     }
 47 | 
 48 |     /**
 49 |      * {@inheritDoc}
 50 |      */
 51 |     final public function getBinary(): string
 52 |     {
 53 |         return $this->ip;
 54 |     }
 55 | 
 56 |     /**
 57 |      * {@inheritDoc}
 58 |      */
 59 |     public function equals(IpInterface $ip): bool
 60 |     {
 61 |         return $this->getBinary() === $ip->getBinary();
 62 |     }
 63 | 
 64 |     /**
 65 |      * {@inheritDoc}
 66 |      */
 67 |     public function isVersion(int $version): bool
 68 |     {
 69 |         return $this->getVersion() === $version;
 70 |     }
 71 | 
 72 |     /**
 73 |      * {@inheritDoc}
 74 |      */
 75 |     public function isVersion4(): bool
 76 |     {
 77 |         return $this->isVersion(4);
 78 |     }
 79 | 
 80 |     /**
 81 |      * {@inheritDoc}
 82 |      */
 83 |     public function isVersion6(): bool
 84 |     {
 85 |         return $this->isVersion(6);
 86 |     }
 87 | 
 88 |     /**
 89 |      * {@inheritDoc}
 90 |      */
 91 |     public function getNetworkIp(int $cidr)
 92 |     {
 93 |         // Providing that the CIDR is valid, bitwise AND the IP address binary
 94 |         // sequence with the mask generated from the CIDR.
 95 |         return new static($this->getBinary() & $this->generateBinaryMask(
 96 |             $cidr,
 97 |             MbString::getLength($this->getBinary())
 98 |         ));
 99 |     }
100 | 
101 |     /**
102 |      * {@inheritDoc}
103 |      */
104 |     public function getBroadcastIp(int $cidr)
105 |     {
106 |         // Providing that the CIDR is valid, bitwise OR the IP address binary
107 |         // sequence with the inverse of the mask generated from the CIDR.
108 |         return new static($this->getBinary() | ~$this->generateBinaryMask(
109 |             $cidr,
110 |             MbString::getLength($this->getBinary())
111 |         ));
112 |     }
113 | 
114 |     /**
115 |      * {@inheritDoc}
116 |      */
117 |     public function inRange(IpInterface $ip, int $cidr): bool
118 |     {
119 |         if (!$this->isSameByteLength($ip)) {
120 |             // Cannot calculate if one IP is in range of another if they of different byte-lengths.
121 |             throw new WrongVersionException($this->getVersion(), $ip->getVersion(), (string) $ip);
122 |         }
123 |         // If this method is being called, it means Multi may have failed it's
124 |         // IPv4 check, and we must proceed as IPv6 only. We must perform
125 |         // getNetworkIp() as IPv6, otherwise instances of Multi with IPv4-embedded
126 |         // addresses and CIDR below 32 will return an incorrect network IP for
127 |         // comparison.
128 |         $ours = $this instanceof Version\MultiVersionInterface ? new Version\IPv6($this->getBinary()) : $this;
129 |         $theirs = $ip instanceof Version\MultiVersionInterface ? new Version\IPv6($ip->getBinary()) : $ip;
130 |         return $ours->getNetworkIp($cidr)->getBinary() === $theirs->getNetworkIp($cidr)->getBinary();
131 |     }
132 | 
133 |     /** {@inheritDoc} */
134 |     public function getCommonCidr(IpInterface $ip): int
135 |     {
136 |         // Cannot calculate the greatest common CIDR between an IPv4 and
137 |         // IPv6/IPv4-embedded address, they are fundamentally incompatible.
138 |         if (!$this->isSameByteLength($ip)) {
139 |             throw new WrongVersionException(
140 |                 MbString::getLength($this->getBinary()) === 4 ? 4 : 6,
141 |                 MbString::getLength($ip->getBinary()) === 4 ? 4 : 6,
142 |                 (string) $ip
143 |             );
144 |         }
145 |         $mask = $this->getBinary() ^ $ip->getBinary();
146 |         $parts = explode('1', Binary::toHumanReadable($mask), 2);
147 |         return MbString::getLength($parts[0]);
148 |     }
149 | 
150 |     /**
151 |      * {@inheritDoc}
152 |      */
153 |     public function isMapped(): bool
154 |     {
155 |         return (new Strategy\Mapped)->isEmbedded($this->getBinary());
156 |     }
157 | 
158 |     /**
159 |      * {@inheritDoc}
160 |      */
161 |     public function isDerived(): bool
162 |     {
163 |         return (new Strategy\Derived)->isEmbedded($this->getBinary());
164 |     }
165 | 
166 |     /**
167 |      * {@inheritDoc}
168 |      */
169 |     public function isCompatible(): bool
170 |     {
171 |         return (new Strategy\Compatible)->isEmbedded($this->getBinary());
172 |     }
173 | 
174 |     /**
175 |      * {@inheritDoc}
176 |      */
177 |     public function isEmbedded(): bool
178 |     {
179 |         return false;
180 |     }
181 | 
182 |     protected function isSameByteLength(IpInterface $ip): bool
183 |     {
184 |         return MbString::getLength($this->getBinary()) === MbString::getLength($ip->getBinary());
185 |     }
186 | 
187 |     /**
188 |      * 128-bit masks can often evaluate to integers over PHP_MAX_INT, so we have
189 |      * to construct the bitmask as a string instead of doing any mathematical
190 |      * operations (such as base_convert).
191 |      *
192 |      * @throws \Darsyn\IP\Exception\InvalidCidrException
193 |      */
194 |     protected function generateBinaryMask(int $cidr, int $lengthInBytes): string
195 |     {
196 |         if ($cidr < 0    || $lengthInBytes < 0
197 |             // CIDR is measured in bits; we're describing the length in bytes.
198 |             || $cidr > $lengthInBytes * 8
199 |         ) {
200 |             throw new Exception\InvalidCidrException($cidr, $lengthInBytes);
201 |         }
202 |         // Eg, a CIDR of 24 and length of 4 bytes (IPv4) would make a mask of:
203 |         // 11111111111111111111111100000000.
204 |         $asciiBinarySequence = MbString::padString(
205 |             \str_repeat('1', $cidr),
206 |             $lengthInBytes * 8,
207 |             '0',
208 |             \STR_PAD_RIGHT
209 |         );
210 |         return Binary::fromHumanReadable($asciiBinarySequence);
211 |     }
212 | }
213 | 


--------------------------------------------------------------------------------
/src/Version/Multi.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Darsyn\IP\Version;
  6 | 
  7 | use Darsyn\IP\Exception;
  8 | use Darsyn\IP\IpInterface;
  9 | use Darsyn\IP\Strategy\EmbeddingStrategyInterface;
 10 | use Darsyn\IP\Strategy\Mapped as MappedEmbeddingStrategy;
 11 | use Darsyn\IP\Util\Binary;
 12 | use Darsyn\IP\Util\MbString;
 13 | 
 14 | /**
 15 |  * Multi-version IP Address
 16 |  *
 17 |  * IP is an immutable value object that provides several notations of the same
 18 |  * IP value, including some helper functions for broadcast and network
 19 |  * addresses, and whether its within the range of another IP address according
 20 |  * to a CIDR (subnet mask), etc.
 21 |  * Although it deals with both IPv4 and IPv6 notations, it makes no distinction
 22 |  * between the two protocol formats as it converts both of them to a 16-byte
 23 |  * binary sequence for easy mathematical operations and consistency (for
 24 |  * example, storing both IPv4 and IPv6 addresses' binary sequences in a
 25 |  * fixed-length database column). in the same column in a database).
 26 |  *
 27 |  * @author    Zan Baldwin <hello@zanbaldwin.com>
 28 |  * @link      https://github.com/darsyn/ip
 29 |  * @copyright 2015 Zan Baldwin
 30 |  * @license   MIT/X11 <http://j.mp/mit-license>
 31 |  */
 32 | class Multi extends IPv6 implements MultiVersionInterface
 33 | {
 34 |     /** @var \Darsyn\IP\Strategy\EmbeddingStrategyInterface|null $defaultEmbeddingStrategy */
 35 |     private static $defaultEmbeddingStrategy;
 36 | 
 37 |     /** @var \Darsyn\IP\Strategy\EmbeddingStrategyInterface $embeddingStrategy */
 38 |     private $embeddingStrategy;
 39 | 
 40 |     /** @var bool $embedded */
 41 |     private $embedded;
 42 | 
 43 |     /**
 44 |      * {@inheritDoc}
 45 |      */
 46 |     public static function setDefaultEmbeddingStrategy(EmbeddingStrategyInterface $strategy): void
 47 |     {
 48 |         self::$defaultEmbeddingStrategy = $strategy;
 49 |     }
 50 | 
 51 |     /**
 52 |      * Get the default embedding strategy set. Default to the IPv4-mapped IPv6
 53 |      * embedding strategy if the user has not set one globally.
 54 |      */
 55 |     private static function getDefaultEmbeddingStrategy(): EmbeddingStrategyInterface
 56 |     {
 57 |         return self::$defaultEmbeddingStrategy ?: new MappedEmbeddingStrategy;
 58 |     }
 59 | 
 60 |     /**
 61 |      * {@inheritDoc}
 62 |      * @param \Darsyn\IP\Strategy\EmbeddingStrategyInterface $strategy
 63 |      */
 64 |     public static function factory(string $ip, ?EmbeddingStrategyInterface $strategy = null): self
 65 |     {
 66 |         // We need a strategy to pack version 4 addresses.
 67 |         $strategy = $strategy ?: self::getDefaultEmbeddingStrategy();
 68 | 
 69 |         try {
 70 |             // Convert from protocol notation to binary sequence.
 71 |             $binary = self::getProtocolFormatter()->pton($ip);
 72 | 
 73 |             // If the IP address is a binary sequence of 4 bytes, then pack it into
 74 |             // a 16 byte IPv6 binary sequence according to the embedding strategy.
 75 |             if (MbString::getLength($binary) === 4) {
 76 |                 $binary = $strategy->pack($binary);
 77 |             }
 78 |         } catch (Exception\IpException $e) {
 79 |             throw new Exception\InvalidIpAddressException($ip, $e);
 80 |         }
 81 |         return new static($binary, $strategy);
 82 |     }
 83 | 
 84 |     /**
 85 |      * {@inheritDoc}
 86 |      */
 87 |     protected function __construct(string $ip, ?EmbeddingStrategyInterface $strategy = null)
 88 |     {
 89 |         // Fallback to default in case this instance was created from static in
 90 |         // the abstract IP class.
 91 |         $this->embeddingStrategy = $strategy ?: self::getDefaultEmbeddingStrategy();
 92 |         parent::__construct($ip);
 93 |     }
 94 | 
 95 |     /** {@inheritDoc} */
 96 |     public function getProtocolAppropriateAddress(): string
 97 |     {
 98 |         // If binary string contains an embedded IPv4 address, then extract it.
 99 |         $ip = $this->isEmbedded()
100 |             ? $this->getShortBinary()
101 |             : $this->getBinary();
102 |         // Render the IP address in the correct notation according to its
103 |         // protocol (based on how long the binary string is).
104 |         return self::getProtocolFormatter()->ntop($ip);
105 |     }
106 | 
107 |     /**
108 |      * @throws \Darsyn\IP\Exception\WrongVersionException
109 |      * @throws \Darsyn\IP\Exception\IpException
110 |      */
111 |     public function getDotAddress(): string
112 |     {
113 |         if ($this->isEmbedded()) {
114 |             try {
115 |                 return self::getProtocolFormatter()->ntop($this->getShortBinary());
116 |             } catch (Exception\Formatter\FormatException $e) {
117 |                 throw new Exception\IpException('An unknown error occured internally.', 0, $e);
118 |             }
119 |         }
120 |         throw new Exception\WrongVersionException(4, 6, (string) $this);
121 |     }
122 | 
123 |     /** {@inheritDoc} */
124 |     public function getVersion(): int
125 |     {
126 |         return $this->isEmbedded() ? 4 : 6;
127 |     }
128 | 
129 |     /** {@inheritDoc} */
130 |     public function getNetworkIp(int $cidr): self
131 |     {
132 |         try {
133 |             if ($this->isVersion4WithAppropriateCidr($cidr)) {
134 |                 $v4 = (new IPv4($this->getShortBinary()))->getNetworkIp($cidr)->getBinary();
135 |                 return new static(
136 |                     $this->embeddingStrategy->pack($v4),
137 |                     clone $this->embeddingStrategy
138 |                 );
139 |             }
140 |         } catch (Exception\IpException $e) {
141 |         }
142 |         return new static(parent::getNetworkIp($cidr)->getBinary(), clone $this->embeddingStrategy);
143 |     }
144 | 
145 |     /** {@inheritDoc} */
146 |     public function getBroadcastIp(int $cidr): self
147 |     {
148 |         try {
149 |             if ($this->isVersion4WithAppropriateCidr($cidr)) {
150 |                 $v4 = (new IPv4($this->getShortBinary()))->getBroadcastIp($cidr)->getBinary();
151 |                 return new static(
152 |                     $this->embeddingStrategy->pack($v4),
153 |                     clone $this->embeddingStrategy
154 |                 );
155 |             }
156 |         } catch (Exception\IpException $e) {
157 |         }
158 |         return new static(parent::getBroadcastIp($cidr)->getBinary(), clone $this->embeddingStrategy);
159 |     }
160 | 
161 |     /** {@inheritDoc} */
162 |     public function inRange(IpInterface $ip, int $cidr): bool
163 |     {
164 |         try {
165 |             if ($this->isVersion4WithAppropriateCidr($cidr) && $this->isVersion4CompatibleWithCurrentStrategy($ip)) {
166 |                 $ours = $this->getShortBinary();
167 |                 $theirs = $this->embeddingStrategy->extract($ip->getBinary());
168 |                 return (new IPv4($ours))->inRange(new IPv4($theirs), $cidr);
169 |             }
170 |         } catch (Exception\IpException $e) {
171 |             // If an exception was thrown, the two IP addresses were incompatible
172 |             // and should not have been checked as IPv4 addresses, fallback to
173 |             // performing the operation as IPv6 addresses.
174 |         }
175 |         return parent::inRange($ip, $cidr);
176 |     }
177 | 
178 |     /** {@inheritDoc} */
179 |     public function getCommonCidr(IpInterface $ip): int
180 |     {
181 |         try {
182 |             if ($this->isVersion4CompatibleWithCurrentStrategy($ip)) {
183 |                 $ours = $this->getShortBinary();
184 |                 $theirs = $this->embeddingStrategy->extract($ip->getBinary());
185 |                 return (new IPv4($ours))->getCommonCidr(new IPv4($theirs));
186 |             }
187 |         } catch (Exception\IpException $e) {
188 |             // If an exception was thrown, the two IP addresses were incompatible
189 |             // and should not have been checked as IPv4 addresses, fallback to
190 |             // performing the operation as IPv6 addresses.
191 |         }
192 |         return parent::getCommonCidr($ip);
193 |     }
194 | 
195 |     /** {@inheritDoc} */
196 |     public function isEmbedded(): bool
197 |     {
198 |         if (null === $this->embedded) {
199 |             $this->embedded = $this->embeddingStrategy->isEmbedded($this->getBinary());
200 |         }
201 |         return $this->embedded;
202 |     }
203 | 
204 |     /** {@inheritDoc} */
205 |     public function isLinkLocal(): bool
206 |     {
207 |         return $this->isEmbedded()
208 |             ? (new IPv4($this->getShortBinary()))->isLinkLocal()
209 |             : parent::isLinkLocal();
210 |     }
211 | 
212 |     /** {@inheritDoc} */
213 |     public function isLoopback(): bool
214 |     {
215 |         return $this->isEmbedded()
216 |             ? (new IPv4($this->getShortBinary()))->isLoopback()
217 |             : parent::isLoopback();
218 |     }
219 | 
220 |     /** * {@inheritDoc} */
221 |     public function isMulticast(): bool
222 |     {
223 |         return $this->isEmbedded()
224 |             ? (new IPv4($this->getShortBinary()))->isMulticast()
225 |             : parent::isMulticast();
226 |     }
227 | 
228 |     /** {@inheritDoc} */
229 |     public function isPrivateUse(): bool
230 |     {
231 |         return $this->isEmbedded()
232 |             ? (new IPv4($this->getShortBinary()))->isPrivateUse()
233 |             : parent::isPrivateUse();
234 |     }
235 | 
236 |     /** {@inheritDoc} */
237 |     public function isUnspecified(): bool
238 |     {
239 |         return $this->isEmbedded()
240 |             ? (new IPv4($this->getShortBinary()))->isUnspecified()
241 |             : parent::isUnspecified();
242 |     }
243 | 
244 |     /** {@inheritDoc} */
245 |     public function isBenchmarking(): bool
246 |     {
247 |         return $this->isEmbedded()
248 |             ? (new IPv4($this->getShortBinary()))->isBenchmarking()
249 |             : parent::isBenchmarking();
250 |     }
251 | 
252 |     /** {@inheritDoc} */
253 |     public function isDocumentation(): bool
254 |     {
255 |         return $this->isEmbedded()
256 |             ? (new IPv4($this->getShortBinary()))->isDocumentation()
257 |             : parent::isDocumentation();
258 |     }
259 | 
260 |     /** {@inheritDoc} */
261 |     public function isPublicUse(): bool
262 |     {
263 |         return $this->isEmbedded()
264 |             ? (new IPv4($this->getShortBinary()))->isPublicUse()
265 |             : parent::isPublicUse();
266 |     }
267 | 
268 |     /**
269 |      * @inheritDoc
270 |      */
271 |     public function isUniqueLocal(): bool
272 |     {
273 |         if ($this->isEmbedded()) {
274 |             throw new Exception\WrongVersionException(6, 4, (string) $this);
275 |         }
276 |         return parent::isUniqueLocal();
277 |     }
278 | 
279 |     /**
280 |      * @inheritDoc
281 |      */
282 |     public function isUnicast(): bool
283 |     {
284 |         if ($this->isEmbedded()) {
285 |             throw new Exception\WrongVersionException(6, 4, (string) $this);
286 |         }
287 |         return parent::isUnicast();
288 |     }
289 | 
290 |     /**
291 |      * @inheritDoc
292 |      */
293 |     public function isUnicastGlobal(): bool
294 |     {
295 |         if ($this->isEmbedded()) {
296 |             throw new Exception\WrongVersionException(6, 4, (string) $this);
297 |         }
298 |         return parent::isUnicastGlobal();
299 |     }
300 | 
301 |     /**
302 |      * {@inheritDoc}
303 |      */
304 |     public function isBroadcast(): bool
305 |     {
306 |         if ($this->isEmbedded()) {
307 |             return (new IPv4($this->getShortBinary()))->isBroadcast();
308 |         }
309 |         throw new Exception\WrongVersionException(4, 6, (string) $this);
310 |     }
311 | 
312 |     /**
313 |      * {@inheritDoc}
314 |      */
315 |     public function isShared(): bool
316 |     {
317 |         if ($this->isEmbedded()) {
318 |             return (new IPv4($this->getShortBinary()))->isShared();
319 |         }
320 |         throw new Exception\WrongVersionException(4, 6, (string) $this);
321 |     }
322 | 
323 |     /**
324 |      * {@inheritDoc}
325 |      */
326 |     public function isFutureReserved(): bool
327 |     {
328 |         if ($this->isEmbedded()) {
329 |             return (new IPv4($this->getShortBinary()))->isFutureReserved();
330 |         }
331 |         throw new Exception\WrongVersionException(4, 6, (string) $this);
332 |     }
333 | 
334 |     /**
335 |      * @throws \Darsyn\IP\Exception\Strategy\ExtractionException
336 |      */
337 |     private function getShortBinary(): string
338 |     {
339 |         return $this->embeddingStrategy->extract($this->getBinary());
340 |     }
341 | 
342 |     /**
343 |      * Can the supplied CIDR and current version be considered as an IPv4 operation?
344 |      */
345 |     private function isVersion4WithAppropriateCidr(int $cidr): bool
346 |     {
347 |         return $cidr <= 32 && $this->isVersion4();
348 |     }
349 | 
350 |     /**
351 |      * Can the supplied and current IP be considered as an IPv4 operation?
352 |      */
353 |     private function isVersion4CompatibleWithCurrentStrategy(IpInterface $ip): bool
354 |     {
355 |         return $this->isVersion4() && $ip->isVersion4() && $this->embeddingStrategy->isEmbedded($ip->getBinary());
356 |     }
357 | 
358 |     /**
359 |      * {@inheritDoc}
360 |      */
361 |     public function __toString(): string
362 |     {
363 |         return $this->getProtocolAppropriateAddress();
364 |     }
365 | }
366 | 


--------------------------------------------------------------------------------