PHPackages                             vectorface/whip - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. vectorface/whip

ActiveLibrary

vectorface/whip
===============

A PHP class for retrieving accurate IP address information for the client.

v0.5.0(2y ago)3781.1M↓13.7%19[1 PRs](https://github.com/Vectorface/whip/pulls)14MITPHPPHP >=8.0

Since Oct 3Pushed 1y ago26 watchersCompare

[ Source](https://github.com/Vectorface/whip)[ Packagist](https://packagist.org/packages/vectorface/whip)[ Docs](https://github.com/Vectorface/whip)[ RSS](/packages/vectorface-whip/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (7)Dependencies (3)Versions (10)Used By (14)

Whip
====

[](#whip)

[![Build Status](https://github.com/Vectorface/whip/actions/workflows/ci.yml/badge.svg)](https://github.com/Vectorface/whip/actions)[![Code Coverage](https://camo.githubusercontent.com/7de36808bd2537a64f342e7026c915e728f3286432bc63a2b6a57d7f4ddf0da2/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f566563746f72666163652f776869702f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Vectorface/whip/?branch=master)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/f66e42cf3beea8b2a1c776d54f742dacf24b7b504b547e90822c717ebeec1fdd/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f566563746f72666163652f776869702f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Vectorface/whip/?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/3753ebbe3b02f6647ad97327c7aef82bad7c76a4f59d9e8f1c9e7d1134ea3f32/68747470733a2f2f706f7365722e707567782e6f72672f766563746f72666163652f776869702f762f737461626c652e737667)](https://packagist.org/packages/vectorface/whip)[![License](https://camo.githubusercontent.com/365db43bec7d8752dabdeed92a773d04b51a0d0289a0e984dc8faf7f0e60e17b/68747470733a2f2f706f7365722e707567782e6f72672f766563746f72666163652f776869702f6c6963656e73652e737667)](https://packagist.org/packages/vectorface/whip)

Whip (stands for Which Ip) is a lightweight class for returning a client's IP address in PHP.

The Problem
-----------

[](#the-problem)

It may seem trivial to simply pull the client's IP address from `$_SERVER['REMOTE_ADDR']` but this address is not always accurate. For example, if your web servers are behind a reverse proxy like Varnish, the IP address listed will be that of your proxy and not the client.

Many solutions propose checking multiple headers but those headers can be spoofed as well and we want to present a final solution anyone can deploy.

Installing Whip.
----------------

[](#installing-whip)

Simply run the following [composer](https://getcomposer.org/) command:

```
$ composer require vectorface/whip
```

Using Whip
----------

[](#using-whip)

Add the required `use` statement to your class

```
use Vectorface\Whip\Whip;
```

To fetch an IP address using every implemented method, you can simply do

```
$whip = new Whip();
$clientAddress = $whip->getValidIpAddress();
```

The class will attempt every method to retrieve the client's IP address starting with very specific use cases and falling back to more general use cases.

Note, that the method `Whip::getValidIpAddress` will return `false` if no valid IP address could be determined, so it is important to check for errors.

```
$whip = new Whip();
if (false === ($clientAddress = $whip->getValidIpAddress())) {
    // handle the error
}
```

To fetch an IP address using a specific method, you can pass a bitmask of enabled methods to the constructor. Here is an example of looking up the IP address using CloudFlare's custom HTTP header, and falling back to `$_SERVER['REMOTE_ADDR']` otherwise.

```
$whip = new Whip(Whip::CLOUDFLARE_HEADERS | Whip::REMOTE_ADDR);
$clientAddress = $whip->getValidIpAddress();
```

This method works, but there is the problem that the custom HTTP header can easily be spoofed if your sites accept traffic not from CloudFlare. To prevent this, Whip allows you to specify a whitelist of IP addresses (or address ranges) that you accept per method.

Using Whip Behind a Trusted Proxy
---------------------------------

[](#using-whip-behind-a-trusted-proxy)

A common use case is to deploy a trusted proxy (nginx, varnish, and many others) in front of an application server. To forward the correct client IP, the trusted proxy should be configured to inject a header for Whip to read with the custom headers method.

If the trusted proxy is configured to send a X-My-Client-IP header, Whip could be used as follows:

```
$whip = new Whip(
    Whip::CUSTOM_HEADERS,
    [Whip::CUSTOM_HEADERS => [ // Whitelist your proxies.
        Whip::IPV4 => ['10.0.0.2', '10.0.0.3']
    ]]
);
$whip->addCustomHeader('HTTP_X_MY_CLIENT_IP');
$ip = $whip->getValidIpAddress();
```

Using the CloudFlare IP Range Whitelist
---------------------------------------

[](#using-the-cloudflare-ip-range-whitelist)

As a common example, Whip can accept a whitelist of IP ranges for CloudFlare when using their custom header and fall back to `$_SERVER['REMOTE_ADDR']` if the custom header was not found or if the source IP address does match any in the whitelist.

```
$whip = new Whip(
    Whip::CLOUDFLARE_HEADERS | Whip::REMOTE_ADDR,
    [
        Whip::CLOUDFLARE_HEADERS => [
            Whip::IPV4 => [
                '199.27.128.0/21',
                '173.245.48.0/20',
                '103.21.244.0/22',
                '103.22.200.0/22',
                '103.31.4.0/22',
                '141.101.64.0/18',
                '108.162.192.0/18',
                '190.93.240.0/20',
                '188.114.96.0/20',
                '197.234.240.0/22',
                '198.41.128.0/17',
                '162.158.0.0/15',
                '104.16.0.0/12'
            ],
            Whip::IPV6 => [
                '2400:cb00::/32',
                '2606:4700::/32',
                '2803:f800::/32',
                '2405:b500::/32',
                '2405:8100::/32'
            ]
        ]
    ]
);
$clientAddress = $whip->getValidIpAddress();
```

Please be sure to use the actual list of IP ranges from CloudFlare for [IPv4](https://www.cloudflare.com/ips-v4) and [IPv6](https://www.cloudflare.com/ips-v6).

List of Methods
---------------

[](#list-of-methods)

The individual methods are stored as integer constants on the `Whip` class. To combine methods, use the bitwise OR operator `|`. The current methods are:

- `Whip::REMOTE_ADDR` - Uses the standard `$_SERVER['REMOTE_ADDR']`.
- `Whip::PROXY_HEADERS` - Uses any of the following values:
    - `$_SERVER['HTTP_CLIENT_IP']`
    - `$_SERVER['HTTP_X_FORWARDED_FOR']`
    - `$_SERVER['HTTP_X_FORWARDED']`
    - `$_SERVER['HTTP_X_CLUSTER_CLIENT_IP']`
    - `$_SERVER['HTTP_FORWARDED_FOR']`
    - `$_SERVER['HTTP_FORWARDED']`
    - `$_SERVER['HTTP_X_REAL_IP']`
- `Whip::CLOUDFLARE_HEADERS` - Uses the CloudFlare provided HTTP header "CF-Connecting-IP".
- `Whip::INCAPSULA_HEADERS` - Use the Incapsula provided HTTP header "Incap-Client-IP".
- `Whip::CUSTOM_HEADERS` - Uses a custom list of HTTP headers passed into `Whip::addCustomHeader`.

Please note that the proxy headers method can be susceptible to client spoofing because it extracts addresses from several possible HTTP headers. This means that using the proxy headers method is not appropriate where trust is required, like in the context of authentication.

Using a Custom Header
---------------------

[](#using-a-custom-header)

Whip can also allow you to specify a custom header to use. For example, you may configure your own proxy to send a unique obfuscated header internally that would be hard to spoof. In this example, we assume Varnish is run locally and we use a custom HTTP header "X-SECRET-REAL-IP" (and fall back to `$_SERVER['REMOTE_ADDR']` if the custom header doesn't work).

```
$whip = new Whip(
    Whip::CUSTOM_HEADERS | Whip::REMOTE_ADDR,
    [
        Whip::CUSTOM_HEADERS => [
            Whip::IPV4 => [
                '127.0.0.1'
            ],
            Whip::IPV6 => [
                '::1'
            ]
        ]
    ]
);
$whip->addCustomHeader('X-SECRET-REAL-IP');
$clientAddress = $whip->getValidIpAddress();
```

Valid IP Ranges
---------------

[](#valid-ip-ranges)

For IPv4, Whip accepts three types of IP ranges:

- Asterisk wildcard (192.168.\*)
- Dashed range (192.168.0.0-192.168.255.255)
- CIDR bitmask notation (192.168.0.0/16)

For IPv6, Whip only accepts the CIDR bitmask notation (fc00::/7).

Furthermore, you can specify a list of exact IP addresses instead of a list of ranges.

IP Range Filtering
------------------

[](#ip-range-filtering)

Whip can also be used to provide simple IP range matching. For example,

```
$range = new Vectorface\Whip\IpRange\Ipv4Range('10.0.*');
if ($range->containsIp($ipv4Address)) {
    // handle the IP address being within the range
}

$range = new Vectorface\Whip\IpRange\Ipv6Range('::1/32');
if ($range->containsIp($ipv6Address)) {
    // handle the IP address being within the range
}
```

PSR-7 Requests, and Others
--------------------------

[](#psr-7-requests-and-others)

Whip supports using [PSR-7 (http-message)](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md) request instances in place of the `$_SERVER` superglobal. For example,

```
// Get a Psr\Http\Message\ServerRequestInterface implementation from somewhere.
$request = ServerRequestFactory::fromGlobals();

// You can pass the request in the constructor.
$whip = new Whip(Whip::REMOTE_ADDR, [], $request);

// ... or set the request as the source of data.
$whip->setSource($request);

// ... or pass it to any function accepting a source argument.
$ip = $whip->getValidIpAddress($request);
```

Other request formats can be supported via a RequestAdapter (src/Request/RequestAdapter) implementation.

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance27

Infrequent updates — may be unmaintained

Popularity57

Moderate usage in the ecosystem

Community37

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 52.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~485 days

Recently: every ~730 days

Total

8

Last Release

848d ago

PHP version history (3 changes)v0.1.0PHP >=5.3.0

v0.4.0PHP >=5.6.0

v0.5.0PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/df4da5988e7543fce193f4554a6bb30fda64a716fb922cddd36612f82ab7e5a3?d=identicon)[janderson](/maintainers/janderson)

![](https://www.gravatar.com/avatar/5e91da343ca33a49bdd0235cef63881127a8dc7ac38755a8678b0765f17ac80e?d=identicon)[danbruce](/maintainers/danbruce)

![](https://www.gravatar.com/avatar/7a6bd4b7a52a1ed056c6d597c4124a62da080137edd42cc34355ac2c28e4a154?d=identicon)[francislavoie](/maintainers/francislavoie)

---

Top Contributors

[![jdpanderson](https://avatars.githubusercontent.com/u/4468291?v=4)](https://github.com/jdpanderson "jdpanderson (38 commits)")[![ckdarby](https://avatars.githubusercontent.com/u/220283?v=4)](https://github.com/ckdarby "ckdarby (20 commits)")[![bryanagee](https://avatars.githubusercontent.com/u/290124?v=4)](https://github.com/bryanagee "bryanagee (4 commits)")[![danbruce](https://avatars.githubusercontent.com/u/562593?v=4)](https://github.com/danbruce "danbruce (3 commits)")[![fullpipe](https://avatars.githubusercontent.com/u/929659?v=4)](https://github.com/fullpipe "fullpipe (2 commits)")[![francislavoie](https://avatars.githubusercontent.com/u/2111701?v=4)](https://github.com/francislavoie "francislavoie (1 commits)")[![denirun](https://avatars.githubusercontent.com/u/1577779?v=4)](https://github.com/denirun "denirun (1 commits)")[![neeckeloo](https://avatars.githubusercontent.com/u/1768645?v=4)](https://github.com/neeckeloo "neeckeloo (1 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (1 commits)")[![WyriHaximus](https://avatars.githubusercontent.com/u/147145?v=4)](https://github.com/WyriHaximus "WyriHaximus (1 commits)")

---

Tags

IPcloudflarecdn

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/vectorface-whip/health.svg)

```
[![Health](https://phpackages.com/badges/vectorface-whip/health.svg)](https://phpackages.com/packages/vectorface-whip)
```

###  Alternatives

[akrabat/ip-address-middleware

PSR-15 middleware that determines the client IP address and stores it as a ServerRequest attribute

1702.5M18](/packages/akrabat-ip-address-middleware)[nexxai/laravel-cfcache

A handful of Cloudflare cache helpers for Laravel

1317.7k](/packages/nexxai-laravel-cfcache)[akrabat/proxy-detection-middleware

PSR-7/PSR-15 Middleware that determines the scheme, host and port from the 'X-Forwarded-Proto', 'X-Forwarded-Host' and 'X-Forwarded-Port' headers and updates the Request's Uri object.

3190.4k1](/packages/akrabat-proxy-detection-middleware)[mantoufan/yzhangateway

Developing PHP SDK for any API. 为任何 API 快速开发 PHP SDK.

331.4k1](/packages/mantoufan-yzhangateway)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)