Class List

FastSitePHP\Net\IP

Internet Protocol

This class includes several static functions for working with IP Addresses and CIDR Strings. Validating IP’s is often important for secure applications.

Source Code

Example Code

IP Addresses and Validation

// With FastSitePHP you can easily compare an IP Address to an accepted range
// of IP’s using CIDR Notation. CIDR Notation (Classless Inter-Domain Routing)
// is a compact representation of an IP address and its associated routing
// prefix. It is used regularly when working with digital networks and often
// needed for websites when handling IP Addresses for security.

// Check if IP Address '10.10.120.12' is in the '10.0.0.0/8' range
// Returns [true]
$matches = \FastSitePHP\Net\IP::cidr('10.0.0.0/8', '10.10.120.12');

// Check if IP Address '10.10.120.12' is in the '172.16.0.0/12' range
// Returns [false]
$matches2 = \FastSitePHP\Net\IP::cidr('172.16.0.0/12', '10.10.120.12');

// IPv6 is also supported
$matches3 = \FastSitePHP\Net\IP::cidr('fe80::/10', 'fe80::b091:1117:497a:9dc1');

// Get an array of Private Network Addresses in CIDR Notation
//   [
//     '127.0.0.0/8',      // IPv4 localhost
//     '10.0.0.0/8',       // IPv4 Private Network, RFC1918 24-bit block
//     '172.16.0.0/12',    // IPv4 Private Network, RFC1918 20-bit block
//     '192.168.0.0/16',   // IPv4 Private Network, RFC1918 16-bit block
//     '169.254.0.0/16',   // IPv4 local-link
//     '::1/128',          // IPv6 localhost
//     'fc00::/7',         // IPv6 Unique local address (Private Network)
//     'fe80::/10',        // IPv6 local-link
//   ]
$private_addr = \FastSitePHP\Net\IP::privateNetworkAddresses();

// The array from [privateNetworkAddresses()] can be used with the [cidr()]
// function to check if an IP address is from a private network or from the
// public internet. The [cidr()] function accepts the CIDR Parameter as
// either an array or a string.
$matches4 = \FastSitePHP\Net\IP::cidr($private_addr, '10.10.120.12');

// Get Info about a CIDR string when calling [cidr()] with only 1 parameter.
// This example returns the following:
//   [
//     'CIDR_Notation' => '10.63.5.183/24',
//     'Address_Type' => 'IPv4',
//     'IP_Address' => '10.63.5.183',
//     'Subnet_Mask' => '255.255.255.0',
//     'Subnet_Mask_Bits' => 24,
//     'Cisco_Wildcard' => '0.0.0.255',
//     'Network_Address' => '10.63.5.0',
//     'Broadcast' => '10.63.5.255',
//     'Network_Range_First_IP' => '10.63.5.0',
//     'Network_Range_Last_IP' => '10.63.5.255',
//     'Usable_Range_First_IP' => '10.63.5.1',
//     'Usable_Range_Last_IP' => '10.63.5.254',
//     'Addresses_in_Network' => 256,
//     'Usable_Addresses_in_Network' => 254,
//  ]
$info = \FastSitePHP\Net\IP::cidr('10.63.5.183/24');

// Example of CIDR Info when using IPv6:
//   [
//     'CIDR_Notation' => 'fe80::b091:1117:497a:9dc1/48',
//     'Address_Type' => 'IPv6',
//     'IP_Address' => 'fe80::b091:1117:497a:9dc1',
//     'Subnet_Mask' => 'ffff:ffff:ffff::',
//     'Subnet_Mask_Bits' => 48,
//     'Network_Address' => 'fe80::',
//     'Network_Range_First_IP' => 'fe80::',
//     'Network_Range_Last_IP' => 'fe80::ffff:ffff:ffff:ffff:ffff',
//     'Addresses_in_Network' => '1208925819614629174706176',
//   ]
$info_ip6 = \FastSitePHP\Net\IP::cidr('fe80::b091:1117:497a:9dc1/48');

Methods

`cidr($cidr, $ip_to_compare = null)`

Static Function

The function cidr() is named for Classless Inter-Domain Routing (CIDR) which is an Internet Standard that allows for an Internet Protocol Address (IP Address) and its Subnet mask to be defined in a compact format. The format named CIDR Notation allows for various network settings to be calculated from a string. CIDR Notation supports both IPv4 and IPv6 Addresses and it is commonly used to specify a network IP range and to compare other IP addresses to the network range.

An example of a CIDR Notation value is '10.63.5.183/24' and for this example means that the computer or device is on a private network (typically a corporate office network), that the IP Address of a specific computer is '10.63.5.183', that the network has a subnet mask of '255.255.255.0', and that there are 256 available IP Addresses for the network. Other IP Address can be compared to this CIDR Value to see if they are on the same network.

This function is used internally by FastSitePHP with [Web\Request->clientIp()] and other functions when checking trusted proxy addresses.

This function can be called with 2 different parameter options and has different return types based on how the function was called. If only a CIDR value is passed as the parameter then this function returns an array of information calculated from the CIDR value, and if both a CIDR Value (or an Array of CIDR Values) and an IP Address are passed as parameters then this function compares the IP Address to the CIDR Value or Values and returns true if the IP Address is on the same network and false if not. If there is an error with the CIDR Value format then this function will return an error message in an array if looking up the CIDR Value or throw an exception if comparing a CIDR Value to and IP Address. Additionally if an IP Address is used instead of the CIDR Value then this function will simply compare the two IP Addresses.

Examples:
     *** These examples are comparing different private
         network IP Addresses with either a CIDR Notation
         Value or another IP Address
     true  = cidr('10.63.5.183/24', '10.63.5.120')
     false = cidr('10.63.5.183/24', '10.63.4.183')
     true  = cidr('fe80::/10', 'fe80::b091:1117:497a:9dc1')
     true  = cidr('10.10.120.12', '10.10.120.12')
     false = cidr('10.10.120.12', '10.10.120.13')

     *** This example compares an IP Address to different
         IP Ranges for Amazon Web Services (AWS);
         note - these ranges may change over time
     true  = cidr('54.231.0.0/17', '54.231.17.108')    us-east-1
     false = cidr('54.231.128.0/19', '54.231.17.108')  eu-west-1

     *** The IPv6 Addresses below look different however have the
         same value so they return true when compared. They have
         the same value because the first address omits leading
         zeros for display while the 2nd address does not.
     true = cidr('::1', '0000:0000:0000:0000:0000:0000:0000:0001')
     true = cidr('::1/128', '0000:0000:0000:0000:0000:0000:0000:0001')

     *** This example is showing how an array of CIDR Strings can be used.
         If the IP Address being compared matches any of the CIDR Strings
         then this function will return true. The function [$app->privateNetworkAddresses()]
         is used to return a list of CIDR Strings that would be on a private network.
     true  = cidr(array('169.254.0.0/16', '10.0.0.0/8'), '10.10.120.14')
     true  = cidr($app->privateNetworkAddresses(), '10.10.120.15')
     false = cidr($app->privateNetworkAddresses(), '54.231.17.108')

     *** Both Port Numbers and IPv6 Zone Indices can be part of the IP Address
         used to compare. Depending upon the environment a Zone Index
         may also be referred to as a Zone Identifier or a Scope ID.
     true = cidr('10.0.0.0/8', '10.10.120.13:8080')  // IPv4 Port Number
     true = cidr('2001:db8::/32', '[2001:db8:cafe::17]:4711') // IPv6 Port Number
     true = cidr('fe80::/10', 'fe80::3030:70d9:5af2:cc71%3') // IPv6 Zone Index

     *** If an IPv6 Address is compared to an IPv4 CIDR or vice-versa
         this function will return false
     false = cidr('10.0.0.0/8', 'fe80::b091:1117:497a:9dc1')
     false = cidr('fe80::/10', '10.10.120.12')

     *** Return Network Information including IP Range from a IPv4 CIDR Notation Value
     cidr('10.63.5.183/24')
     returns array(
         'CIDR_Notation' => '10.63.5.183/24',
         'Address_Type' => 'IPv4',
         'IP_Address' => '10.63.5.183',
         'Subnet_Mask' => '255.255.255.0',
         'Subnet_Mask_Bits' => 24,
         'Cisco_Wildcard' => '0.0.0.255',
         'Network_Address' => '10.63.5.0',
         'Broadcast' => '10.63.5.255',
         'Network_Range_First_IP' => '10.63.5.0',
         'Network_Range_Last_IP' => '10.63.5.255',
         'Usable_Range_First_IP' => '10.63.5.1',
         'Usable_Range_Last_IP' => '10.63.5.254',
         'Addresses_in_Network' => 256,
         'Usable_Addresses_in_Network' => 254,
     )

     *** Return Network Information from a IPv6 CIDR Notation Value
     cidr('fe80::b091:1117:497a:9dc1/48')
     returns array(
         'CIDR_Notation' => 'fe80::b091:1117:497a:9dc1/48',
         'Address_Type' => 'IPv6',
         'IP_Address' => 'fe80::b091:1117:497a:9dc1',
         'Subnet_Mask' => 'ffff:ffff:ffff::',
         'Subnet_Mask_Bits' => 48,
         'Network_Address' => 'fe80::',
         'Network_Range_First_IP' => 'fe80::',
         'Network_Range_Last_IP' => 'fe80::ffff:ffff:ffff:ffff:ffff',
         'Addresses_in_Network' => '1208925819614629174706176',
     )

     *** Example error when getting values for a CIDR Notation String
     cidr('abc.abc.abc.abc/24')
     returns array(
         'CIDR_Notation' => null,
         'Error_Message' => 'The value [abc.abc.abc.abc] is not in valid IPv4 format',
     )

     *** Example error when comparing an IP Address with a CIDR Value
     cidr('abc.abc.abc.abc/24', '127.0.0.1')
     throws \InvalidArgumentException('The value [abc.abc.abc.abc] is not in valid IPv4 format')

     *** If an invalid IP Address is specified with a valid CIDR value then
         this function returns false and does not throw an Exception
     false = cidr('10.0.0.0/8', 'abc')

Returns: array | bool

`privateNetworkAddresses()`

Static Function

Return an Array of CIDR Notation Strings that contains Network Addresses that would only be on a private network (for example a Home Office Network or Enterprise LAN). Specific IP Address ranges are assigned for Private networks and in most cases this function will return addresses for both IPv4 and IPv6. This function will only return IPv4 addresses if the server running this function does not support IPv6. This function can be used with the [cidr()] function to test if an IP Address is on a local network.

This function is used internally by FastSitePHP with [Web\Request->clientIp()] and other functions when checking trusted proxy addresses.

The following CIDR Notation Strings are returned:
  [
     '127.0.0.0/8',      // IPv4 localhost
     '10.0.0.0/8',       // IPv4 Private Network, RFC1918 24-bit block
     '172.16.0.0/12',    // IPv4 Private Network, RFC1918 20-bit block
     '192.168.0.0/16',   // IPv4 Private Network, RFC1918 16-bit block
     '169.254.0.0/16',   // IPv4 local-link
     '::1/128',          // IPv6 localhost
     'fc00::/7',         // IPv6 Unique local address (Private Network)
     'fe80::/10',        // IPv6 local-link
  ]

The IPv6 Unique local address 'fc00::/7' also covers the IP Range 'fd00::/8'.

Returns: array