Skip to content

Commit

Permalink
Refs #4200, tweaked docs for core/IP.php.
Browse files Browse the repository at this point in the history
  • Loading branch information
diosmosis committed Oct 21, 2013
1 parent 31fe034 commit 6eca3fa
Showing 1 changed file with 38 additions and 34 deletions.
72 changes: 38 additions & 34 deletions core/IP.php
View file
Expand Up @@ -12,7 +12,7 @@
namespace Piwik;

/**
* Handling IP addresses (both IPv4 and IPv6).
* Contains IP address helper functions (for both IPv4 and IPv6).
*
* As of Piwik 1.3, IP addresses are stored in the DB has VARBINARY(16),
* and passed around in network address format which has the advantage of
Expand All @@ -34,9 +34,9 @@ class IP
const MAPPED_IPv4_START = '::ffff:';

/**
* Sanitize human-readable IP address.
* Removes the port and the last portion of a CIDR IP address.
*
* @param string $ipString IP address
* @param string $ipString The IP address to sanitize.
* @return string
*/
public static function sanitizeIp($ipString)
Expand Down Expand Up @@ -126,10 +126,10 @@ public static function sanitizeIpRange($ipRangeString)
}

/**
* Convert presentation format IP address to network address format
* Convert presentation format IP address to network address format.
*
* @param string $ipString IP address, either IPv4 or IPv6, e.g., "127.0.0.1"
* @return string Binary-safe string, e.g., "\x7F\x00\x00\x01"
* @param string $ipString IP address, either IPv4 or IPv6, e.g., `"127.0.0.1"`.
* @return string Binary-safe string, e.g., `"\x7F\x00\x00\x01"`.
*/
public static function P2N($ipString)
{
Expand All @@ -139,12 +139,12 @@ public static function P2N($ipString)
}

/**
* Convert network address format to presentation format
* Convert network address format to presentation format.
*
* @see prettyPrint()
* See also [prettyPreint](#prettyPrint).
*
* @param string $ip IP address in network address format
* @return string IP address in presentation format
* @param string $ip IP address in network address format.
* @return string IP address in presentation format.
*/
public static function N2P($ip)
{
Expand All @@ -154,21 +154,22 @@ public static function N2P($ip)
}

/**
* Alias for N2P()
* Alias for [N2P()](#N2P).
*
* @param string $ip IP address in network address format
* @return string IP address in presentation format
* @param string $ip IP address in network address format.
* @return string IP address in presentation format.
*/
public static function prettyPrint($ip)
{
return self::N2P($ip);
}

/**
* Is this an IPv4, IPv4-compat, or IPv4-mapped address?
* Returns true if `$ip` is an IPv4, IPv4-compat, or IPv4-mapped address, false
* if otherwise.
*
* @param string $ip IP address in network address format
* @return bool True if IPv4, else false
* @param string $ip IP address in network address format.
* @return bool True if IPv4, else false.
*/
public static function isIPv4($ip)
{
Expand Down Expand Up @@ -201,8 +202,8 @@ public static function isIPv4($ip)
* This function does not support the long (or its string representation)
* returned by the built-in ip2long() function, from Piwik 1.3 and earlier.
*
* @param string $ip IPv4 address in network address format
* @return string IP address in presentation format
* @param string $ip IPv4 address in network address format.
* @return string IP address in presentation format.
*/
public static function long2ip($ip)
{
Expand Down Expand Up @@ -248,7 +249,10 @@ public static function isMappedIPv4($ip)
}

/**
* Returns
* Returns an IPv4 address from a 'mapped' IPv6 address.
*
* @param string $ip eg, `'::ffff:192.0.2.128'`
* @return string eg, `'192.0.2.128'`
*/
public static function getIPv4FromMappedIPv6($ip)
{
Expand All @@ -258,8 +262,8 @@ public static function getIPv4FromMappedIPv6($ip)
/**
* Get low and high IP addresses for a specified range.
*
* @param array $ipRange An IP address range in presentation format
* @return array|bool Array ($lowIp, $highIp) in network address format, or false if failure
* @param array $ipRange An IP address range in presentation format.
* @return array|bool Array `array($lowIp, $highIp)` in network address format, or false on failure.
*/
public static function getIpsForRange($ipRange)
{
Expand Down Expand Up @@ -338,10 +342,10 @@ public static function isIpInRange($ip, $ipRanges)
}

/**
* Returns the best possible IP of the current user, in the format A.B.C.D
* For example, this could be the proxy client's IP address.
* Returns the most accurate IP address availble for the current user, in
* IPv4 format. This could be the proxy client's IP address.
*
* @return string IP address in presentation format
* @return string IP address in presentation format.
*/
public static function getIpFromHeader()
{
Expand All @@ -360,10 +364,10 @@ public static function getIpFromHeader()
}

/**
* Returns a non-proxy IP address from header
* Returns a non-proxy IP address from header.
*
* @param string $default Default value to return if no matching proxy header
* @param array $proxyHeaders List of proxy headers
* @param string $default Default value to return if there no matching proxy header.
* @param array $proxyHeaders List of proxy headers.
* @return string
*/
public static function getNonProxyIpFromHeader($default, $proxyHeaders)
Expand Down Expand Up @@ -395,9 +399,9 @@ public static function getNonProxyIpFromHeader($default, $proxyHeaders)
/**
* Returns the last IP address in a comma separated list, subject to an optional exclusion list.
*
* @param string $csv Comma separated list of elements
* @param array $excludedIps Optional list of excluded IP addresses (or IP address ranges)
* @return string Last (non-excluded) IP address in the list
* @param string $csv Comma separated list of elements.
* @param array $excludedIps Optional list of excluded IP addresses (or IP address ranges).
* @return string Last (non-excluded) IP address in the list.
*/
public static function getLastIpFromList($csv, $excludedIps = null)
{
Expand All @@ -415,10 +419,10 @@ public static function getLastIpFromList($csv, $excludedIps = null)
}

/**
* Get hostname for a given IP address
* Get hostname for a given IP address.
*
* @param string $ipStr Human-readable IP address
* @return string Hostname or unmodified $ipStr if failure
* @param string $ipStr Human-readable IP address.
* @return string The hostname or unmodified $ipStr on failure.
*/
public static function getHostByAddr($ipStr)
{
Expand All @@ -427,4 +431,4 @@ public static function getHostByAddr($ipStr)
$host = strtolower(@gethostbyaddr($ipStr));
return $host === '' ? $ipStr : $host;
}
}
}

0 comments on commit 6eca3fa

Please sign in to comment.