Blocks

Blocks#

Classes#

There are 4 classes representing blocks:

Arokettu\IP\IPv4Block

IPv4 block

Arokettu\IP\IPv6Block

IPv6 block

Arokettu\IP\IPBlock

Common factory methods with version autodetection

Arokettu\IP\AnyIPBlock

An interface meaning both IPv4Block and IPv6Block

Factories#

fromBytes()#

  • Arokettu\IP\IPv4Block::fromBytes($bytes, $prefix, $strict = false)

  • Arokettu\IP\IPv6Block::fromBytes($bytes, $prefix, $strict = false)

  • Arokettu\IP\IPBlock::fromBytes($bytes, $prefix, $strict = false)

Creates an object from a byte representation of the base address (such as created by the inet_pton() function) and a prefix value. Non-strict mode allows non-normalized base address and negative prefixes (for IPv4 -1 equals to 32 and -32 equals to 1):

<?php

use Arokettu\IP\IPBlock;

$block = IPBlock::fromBytes("\x7f\0\0\0", 8); // 127.0.0.0/8

// denormalized base:
$block = IPBlock::fromBytes("\x7f\0\0\1", 8); // 127.0.0.0/8
$block = IPBlock::fromBytes("\x7f\0\0\1", 8, strict: true); // UnexpectedValueException

// negative prefix:
$block = IPBlock::fromBytes("\x7f\0\0\1", -25); // 127.0.0.0/8
$block = IPBlock::fromBytes("\x7f\0\0\1", -25, strict: true); // UnexpectedValueException
// mostly useful for single IP blocks in autodetect factories:
$block = IPBlock::fromBytes("\x7f\0\0\1", -1); // 127.0.0.1/32
$block = IPBlock::fromBytes("\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1", -1); // ::1/128

fromString()#

  • Arokettu\IP\IPv4Block::fromString($string, $prefix, $strict = false)

  • Arokettu\IP\IPv6Block::fromString($string, $prefix, $strict = false)

  • Arokettu\IP\IPBlock::fromString($string, $prefix, $strict = false)

Creates an object from a string representation of the base address (same valid values as for the inet_pton() function) and a prefix value. Prefix may be a part of the string (CIDR notation) or a separate parameter. Non-strict mode allows non-normalized base addresses, negative prefixes, and prefix present in both string and $prefix:

<?php

use Arokettu\IP\IPBlock;

// CIDR notation
$block = IPBlock::fromString("127.0.0.0/8");
// Separate prefix
$block = IPBlock::fromString("127.0.0.0", 8); // 127.0.0.0/8
// String value takes precedence
$block = IPBlock::fromString("127.0.0.0/8", 16); // 127.0.0.0/8
// Strict mode disallows double prefix
$block = IPBlock::fromString("127.0.0.0/8", 16, strict: true); // BadMethodCallException

// Negative prefixes, like in fromBytes
$block = IPBlock::fromString("127.0.0.1", -1); // 127.0.0.1/32
$block = IPBlock::fromString("::1", -1); // ::1/128
// Strict mode disallows that
$block = IPBlock::fromString("::1", -1, strict: true); // UnexpectedValueException
// Negative prefixes can only be in a separate parameter
$block = IPBlock::fromString("127.0.0.1/-1"); // UnexpectedValueException

// Denormalized base:
$block = IPBlock::fromString("127.0.0.1/8"); // 127.0.0.0/8
$block = IPBlock::fromString("127.0.0.1/8", strict: true); // UnexpectedValueException

Methods#

Containment#

Exists in 3 versions:

  • strictContains($addressOrBlock) does not allow mixing of IP versions

  • nonStrictContains($addressOrBlock) allows mixing of IP versions, blocks never contain a “wrong” type of address

  • contains($addressOrBlock, $strict = false) calls one of the above depending on $strict

A method to check if an address or a smaller block belongs to the given block:

<?php

use Arokettu\IP\IPAddress;
use Arokettu\IP\IPBlock;

$block1 = IPBlock::fromString('127.0.0.0/8');
$block2 = IPBlock::fromString('127.0.0.0/16');

$ip1 = IPAddress::fromString('127.0.0.1');
$ip2 = IPAddress::fromString('fc80::abcd');

$block1->contains($ip1); // true
$block1->contains($ip2); // false
$block1->contains($ip2, strict: true); // TypeError
$block1->contains($block2); // true

Comparison#

Note

See Compare Helper

Also exists in 3 versions:

  • strictCompare($address) does not allow mixing of IP versions

  • nonStrictCompare($address) allows mixing of IP versions, IPv4 blocks are “smaller” than IPv6 versions

  • compare($address, $strict = false) calls one of the above depending on $strict

Blocks are compared first by base addresses, then by prefix lengths in natural order.

127.0.0.0/8 < 192.168.0.0/16 < 192.168.0.0/24 < 192.168.1.0/24 < 255.0.0.0/8

Returns one of [-1, 0, 1] like strcmp() or <=>.

<?php

use Arokettu\IP\IPBlock;

$block1 = IPBlock::fromString("127.0.0.0/16");
$block2 = IPBlock::fromString("127.1.0.0/16");

$block2->compare($block1) > 0; // $block2 > $block1; true

Equality#

Also exists in 3 versions:

  • strictEquals($address) does not allow mixing of IP versions

  • nonStrictEquals($address) allows mixing of IP versions, IPv4 and IPv6 are never equal to each other

  • equals($address, $strict = false) calls one of the above depending on $strict

Returns boolean.

<?php

use Arokettu\IP\IPBlock;

$block1 = IPBlock::fromString("127.0.0.0/16");
$block2 = IPBlock::fromString("127.1.0.0/16");

$block1->equals($block2); // $block1 == $block2; false

toString()#

Returns the canonical string representation of the IP block in CIDR notation:

<?php

use Arokettu\IP\IPBlock;

$block = IPBlock::fromString("127.0.0.0/8");

echo $block->toString(); // 127.0.0.0/8

Other getters#

getBytes()

Byte representation of the base address

getPrefix()

Prefix length

getMaskBytes()

Byte representation of the mask

getMaskString()

Mask value in the IP notation

getFirstAddress()

The first IP in the block, also its base address

getLastAddress()

The last IP in the block, the multicast address for the IPv4

isSingleAddress()

If the block encodes a single address (/32 for v4 or /128 for v6)

IPv6-Only Methods#

toFullHexString()#

Returns a non-shortened full hex string of the IPv6:

<?php

use Arokettu\IP\IPv4Block;
use Arokettu\IP\IPv6Block;

$ip = IPv6Block::fromString('2001:abc::abcd:0/112');

var_dump($ip->toString()); // 2001:abc::abcd:0/112
var_dump($ip->toFullHexString()); // 2001:0abc:0000:0000:0000:0000:abcd:0000/112

$ip = IPv4Block::fromString('192.168.112.0/24')->toMappedIPv6();

var_dump($ip->toString()); // ::ffff:192.168.112.0/120
var_dump($ip->toFullHexString()); // 0000:0000:0000:0000:0000:ffff:c0a8:7000/120