├── CHANGELOG.md ├── LICENSE ├── README.md ├── VERSION ├── composer.json └── src └── proxycheck.php /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | CHANGELOG 2 | ========= 3 | 4 | 0.2.4 (June 3rd 2025) 5 | ------------------ 6 | 7 | * Corrected an undefined variable error when supplying a blank RULE_SELECTION 8 | 9 | 0.2.3 (June 3rd 2025) 10 | ------------------ 11 | 12 | * Adds support for manipulating Custom Rules via the library. 13 | 14 | 15 | 0.2.2 (January 4th 2023) 16 | ------------------ 17 | 18 | * Improved the reliability of sending addresses to the API by always using the POST method 19 | This now applies to sending a singular address in addition to multiple addresses. 20 | 21 | 22 | 0.2.1 (October 28th 2022) 23 | ------------------ 24 | 25 | * Corrected an exception when checking an IP which doesn't have Country data available. 26 | 27 | 28 | 0.2.0 (February 18th 2022) 29 | ------------------ 30 | 31 | * Added full support for checking email addresses in addition to ip addresses. 32 | 33 | 34 | 0.1.9 (December 9th 2021) 35 | ------------------ 36 | 37 | * Added support for checking multiple addresses in a single request by passsing an 38 | array as the $ip variable instead of a string. 39 | 40 | 41 | 0.1.8 (November 12th 2021) 42 | ------------------ 43 | 44 | * Moves around the required and optional parameters for our makeRequest() function 45 | to support PHP8+ which has deprecated our previous implementation. 46 | 47 | 48 | 0.1.7 (December 29th 2020) 49 | ------------------ 50 | 51 | * Corrected an issue where custom tags wouldn't be sent with requests. 52 | This bug was introduced by the 0.1.6 release. 53 | 54 | 55 | 0.1.6 (December 9th 2020) 56 | ------------------ 57 | 58 | * Updated code formatting to meet PSR-12 specifications. 59 | * Improved the cURL implementation with GET/POST method arguments. 60 | * Corrected an issue where omitting the DAY_RESTRICTOR within your options 61 | array would cause your API Key to not be sent with your requests. 62 | 63 | 64 | 0.1.5 (June 27th 2019) 65 | ------------------ 66 | 67 | * Added better protection against absent parameters in array options. 68 | 69 | 70 | 0.1.4 (June 25th 2019) 71 | ------------------ 72 | 73 | * Added a new query flag: risk which lets you view both risk scores 74 | and attack history for IP Addresses. 75 | 76 | 77 | 0.1.3 (May 18th 2019) 78 | ------------------ 79 | 80 | * Added a new function called stats which allows you to view the stats 81 | from your dashboard using our official dashboard API's 82 | * Updated the check function to support a new option array called 83 | ALLOWED_COUNTRIES so you can do local country based whitelisting. 84 | * Updated the COUNTRIES feature to allow isocodes to be used in addition 85 | to country names. 86 | * Improved the classes handling of errors when options were not supplied 87 | in the options array. 88 | 89 | 90 | 0.1.2 (November 23rd 2018) 91 | ------------------ 92 | 93 | * Added a new function called listing which allows you to view and modify 94 | your whitelist and blacklist using our official dashboard API. 95 | 96 | 97 | 0.1.1 (June 11th 2018) 98 | ------------------ 99 | 100 | * Added Last Seen, Port and Node flags to the query library. 101 | * Updated README.md with new description of the library and altered the 102 | example result array to include new flag responses. 103 | * Updated composer.json changing "type" from project to library. 104 | 105 | 106 | 0.1.0 (June 9th 2018) 107 | ------------------ 108 | 109 | * Initial release. 110 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 proxycheck.io 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # proxycheck-php 2 | php library for calling the [proxycheck.io](https://proxycheck.io/) v2 API which allows you to check if an IP address is a Proxy or VPN and get the Country, ASN and Provider for the IP address being checked. This library also supports checking email addresses to determine if they belong to a disposable email service or not. 3 | 4 | ## Install via Composer ## 5 | 6 | You can install the library via [Composer](http://getcomposer.org/) by running the following command: 7 | 8 | ```bash 9 | composer require proxycheck/proxycheck-php 10 | ``` 11 | To use the library, use Composer's [autoload](https://getcomposer.org/doc/01-basic-usage.md#autoloading): 12 | 13 | ```php 14 | require_once('vendor/autoload.php'); 15 | ``` 16 | 17 | ## Dependencies ## 18 | 19 | The library requires the following extensions in order to work properly: 20 | 21 | - [`curl`](https://secure.php.net/manual/en/book.curl.php) (Please make sure your [cacert.pem](https://curl.haxx.se/docs/caextract.html) is up to date if you intend to use TLS querying) 22 | - [`json`](https://secure.php.net/manual/en/book.json.php) 23 | 24 | ## Service Limits ## 25 | 26 | * Free users without an API Key = 100 Daily Queries 27 | * Free users with an API Key = 1,000 Daily Queries 28 | * Paid users with an API Key = 10,000 to 10.24 Million+ Daily Queries 29 | 30 | Get your API Key at [proxycheck.io](http://proxycheck.io/) it's free. 31 | 32 | ## Getting Started ## 33 | 34 | Performing a check on an address (IPv4 and IPv6 IP addresses are supported along with email addresses for disposable mailbox checking.). 35 | 36 | ```php 37 | // Get your visitors IP address or email address 38 | // If you're using CloudFlare change $_SERVER["REMOTE_ADDR"] to $_SERVER["HTTP_CF_CONNECTING_IP"] 39 | // You may also supply an array of addresses in $address to check multiple addresses at once. 40 | $address = $_SERVER["REMOTE_ADDR"]; 41 | 42 | // Input your options for this query including your optional API Key and query flags. 43 | $proxycheck_options = array( 44 | 'API_KEY' => '######-######-######-######', // Your API Key. 45 | 'ASN_DATA' => 1, // Enable ASN data response. 46 | 'DAY_RESTRICTOR' => 7, // Restrict checking to proxies seen in the past # of days. 47 | 'VPN_DETECTION' => 1, // Check for both VPN's and Proxies instead of just Proxies. 48 | 'RISK_DATA' => 1, // 0 = Off, 1 = Risk Score (0-100), 2 = Risk Score & Attack History. 49 | 'INF_ENGINE' => 1, // Enable or disable the real-time inference engine. 50 | 'TLS_SECURITY' => 0, // Enable or disable transport security (TLS). 51 | 'QUERY_TAGGING' => 1, // Enable or disable query tagging. 52 | 'MASK_ADDRESS' => 1, // Anonymises the local-part of an email address (e.g. anonymous@domain.tld) 53 | 'CUSTOM_TAG' => '', // Specify a custom query tag instead of the default (Domain+Page). 54 | 'BLOCKED_COUNTRIES' => array('Wakanda', 'WA'), // Specify an array of countries or isocodes to be blocked. 55 | 'ALLOWED_COUNTRIES' => array('Azeroth', 'AJ') // Specify an array of countries or isocodes to be allowed. 56 | ); 57 | 58 | $result_array = \proxycheck\proxycheck::check($address, $proxycheck_options); 59 | ``` 60 | In the above example we have included both countries and isocodes in both the ```BLOCKED_COUNTRIES``` and ```ALLOWED_COUNTRIES``` field. That is because as of 0.1.3 (May 2019) this library now supports both for use in these arrays. You can think of these two fields like a local whitelist/blacklist feature but only for countries. 61 | 62 | ## Viewing the query result ## 63 | 64 | When performing a query you will receive back an array which contains various information. Below is an example of parsing that array to determine if this user should be blocked or not. Please note the block and block_reason results are only populated when checking a single address, when passing an array of addresses to perform a multi-check these variables will both contain ```na```. 65 | 66 | ```php 67 | if ( $result_array['block'] == "yes" ) { 68 | 69 | // Example of a block and the reason why. 70 | echo "Blocked, reason: " . $result_array['block_reason']; 71 | exit; 72 | 73 | } else { 74 | 75 | // No Proxy / VPN / Blocked Country detected. 76 | echo "Not blocked."; 77 | 78 | } 79 | ``` 80 | 81 | ## Extra information included in the query result ## 82 | 83 | When performing a query you will receive not just ```block: yes/no``` and ```block_reason: [reason]``` but also the entirety of the API response from proxycheck.io, we do this so you can either make an easy block system or utilise the data presented by the API as you see fit. A full result example is shown below. 84 | 85 | ```php 86 | Array 87 | ( 88 | [status] => ok/warning/denied/error 89 | [node] => answering_node_name 90 | [###.###.###.###] => Array 91 | ( 92 | [asn] => AS##### 93 | [range] => ###.###.###.###/24 94 | [hostname] => 78-2-adsl.acme.net 95 | [provider] => Acme Incorporated 96 | [organisation] => Acme Net 97 | [country] => Wakanda 98 | [isocode] => WA 99 | [region] => Wakanda North 100 | [regioncode] => WAN 101 | [city] => Birnin Zana 102 | [postcode] => BZ967 103 | [latitude] => 2.5072 104 | [longitude] => -0.1276 105 | [currency] => Array 106 | ( 107 | [code] => VD 108 | [name] => Vibranium Dollar 109 | [symbol] => $ 110 | ) 111 | [proxy] => yes/no 112 | [type] => VPN/SOCKS5/SOCKS4/SOCKS/HTTP/HTTPS/Compromised Server 113 | [risk] => 0 to 100 114 | [port] => ##### 115 | [last seen human] => 6 hours, 18 minutes, 49 seconds ago 116 | [last seen unix] => 1528687645 117 | ) 118 | [block] => yes/no 119 | [block_reason] => proxy/vpn/country 120 | ) 121 | ``` 122 | 123 | In the above example the ```status``` field lets you know the status of this query. You can view all our API responses [here](https://proxycheck.io/api/) within our API documentation page. Also where in our example we show ```###.###.###.###``` you will receive the actual address you sent to the API for checking. 124 | 125 | ## Viewing Statistics from your Dashboard ## 126 | 127 | In version 0.1.3 (May 2019) we added the ability to view statistics from your account dashboard through this library. Below is an example of how to do that. 128 | 129 | ```php 130 | $proxycheck_options = array( 131 | 'API_KEY' => '', // Your API Key. 132 | 'TLS_SECURITY' => 0, // Enable or disable transport security (TLS). 133 | 'STAT_SELECTION' => 'usage', // Stats to view: detections, usage or queries 134 | 'LIMIT' => '10', // Specify how many entries to view (applies to detection stats only) 135 | 'OFFSET' => '0' // Specify an offset in the entries to view (applies to detection stats only) 136 | ); 137 | 138 | $result_array = \proxycheck\proxycheck::stats($proxycheck_options); 139 | ``` 140 | When accessing dashboard API's an API Key is always required as the dashboard is only for registered users (both free and paid have full dashboard access). You will also need to make sure you have Dashboard API access enabled [within your dashboard](https://proxycheck.io/dashboard/) on our website. 141 | 142 | You can see that in the ```STAT_SELECTION``` field we are providing the name of the stat we would like to view. In this example we have selected ```usage``` but you can also check detections or queries. This library will also support future stat types automatically. 143 | 144 | Below is an example of how this result would look. 145 | 146 | ```php 147 | Array 148 | ( 149 | [Queries Today] => 234 150 | [Daily Limit] => 1000 151 | [Queries Total] => 840931 152 | [Plan Tier] => Free 153 | ) 154 | ``` 155 | 156 | When viewing the ```detections``` stat you can also provide a limit (which is how many entries to show you) and offset (which is how many entries to skip over before starting to show you any results). 157 | 158 | So for example if you had 100 entries and you only wanted to view entries 31 to 40 you would supply 10 as a limit and 30 as an offset. 159 | 160 | ## Manipulating your CORS Origins, Whitelist or Blacklist ## 161 | 162 | In version 0.1.2 (Nov 2018) we added the ability to view, add, remove, set and clear your whitelist and blacklist through this library, in December 2020 a CORS API was added to proxycheck.io and the below code also works for that. Below is an example of adding three entries to your whitelist in a single query. 163 | 164 | ```php 165 | $proxycheck_options = array( 166 | 'API_KEY' => '', // Your API Key. 167 | 'TLS_SECURITY' => 0, // Enable or disable transport security (TLS). 168 | 'LIST_SELECTION' => 'whitelist', // Specify the list you're accessing: CORS, whitelist or blacklist 169 | 'LIST_ACTION' => 'add', // Specify an action: list, add, remove, set or clear. 170 | 'LIST_ENTRIES' => array('8.8.8.8', '1.1.1.1/24', 'AS888') // Origins, IPs, Ranges, ASN's or Emails to be added, removed or set 171 | ); 172 | 173 | $result_array = \proxycheck\proxycheck::listing($proxycheck_options); 174 | ``` 175 | 176 | When accessing dashboard API's an API Key is always required as the dashboard is only for registered users (both free and paid have full dashboard access). You will also need to make sure you have Dashboard API access enabled [within your dashboard](https://proxycheck.io/dashboard/) on our website. 177 | 178 | You can see that in the LIST_ENTRIES field we are providing an array of three seperate entries, this field is only used if you're performing an add, remove or set action. When providing entries in the LIST_ENTRIES field you can include comments, for example ```'LIST_ENTRIES' => array('8.8.8.8 #this is google')``` would create a new entry with the comment intact. 179 | 180 | This LIST_ENTRIES field can also be used when adding, setting or removing origins for use with the CORS feature. In this situation comments are not supported, only domains (including wildcard domains such as \*.example.com). All LIST_ACTION types are supported with CORS in the same way they are with Whitelist/Blacklist manipulation. 181 | 182 | If a white or blacklist entry you're removing has a comment next to it you will need to include that comment in the removal request aswell, like in the example above where we included a comment next to the IP address we were adding you would do the same when removing it. 183 | 184 | ## Manipulating your Custom Rules ## 185 | 186 | In version 0.2.3 (Jun 2025) we added the ability to view, enable or disable your Custom Rules by name or ID through this library. Below is an example of disabling a custom rule by its name. 187 | 188 | ```php 189 | $proxycheck_options = array( 190 | 'API_KEY' => '', // Your API Key. 191 | 'TLS_SECURITY' => 0, // Enable or disable transport security (TLS). 192 | 'RULE_SELECTION' => 'Elevate Risk Score Rule', // Specify the rule you're accessing by name or ID (leave blank to print all rule names, ID's and states) 193 | 'RULE_ACTION' => 'disable', // Specify an action: enable, disable or print. 194 | ); 195 | 196 | $result_array = \proxycheck\proxycheck::rules($proxycheck_options); 197 | ``` 198 | 199 | When accessing dashboard API's an API Key is always required as the dashboard is only for registered users (both free and paid have full dashboard access). You will also need to make sure you have Dashboard API access enabled [within your dashboard](https://proxycheck.io/dashboard/) on our website. 200 | 201 | In the above we've performed a disable action on a rule that exists already in the account. We're using the name the rule was given to target it instead of using its ID however you can use the ID instead that you obtained from the print action. 202 | 203 | When you want to print a list of all your custom rules you leave the ```RULE_SELECTION``` field blank and supply print in the ```RULE_ACTION``` field. If instead you want all the data from a specific rule you can supply its name or ID in ```RULE_SELECTION``` with print in the ```RULE_ACTION``` field and you'll receive the same output as if you performed a rule download from within the customer dashboard, this can be saved as a .json file and imported through the dashboard itself. 204 | 205 | Other ```RULE_ACTION``` types including deleting, importing, setting etc are supported by this library but are not yet available from the Dashboard API at proxycheck.io and so these will become available at a later date and this documentation will then be updated to reflect that. 206 | -------------------------------------------------------------------------------- /VERSION: -------------------------------------------------------------------------------- 1 | 0.2.4 2 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "proxycheck/proxycheck-php", 3 | "description": "proxycheck.io PHP Library", 4 | "keywords": [ 5 | "proxycheck", 6 | "proxy checking", 7 | "api" 8 | ], 9 | "homepage": "https://proxycheck.io/", 10 | "license": "MIT", 11 | "authors": [ 12 | { 13 | "name": "proxycheck and contributors", 14 | "homepage": "https://github.com/proxycheck/proxycheck-php/contributors" 15 | } 16 | ], 17 | "type": "library", 18 | "require": { 19 | "php": ">=5.4", 20 | "ext-curl": "*", 21 | "ext-json": "*" 22 | }, 23 | "autoload": { 24 | "psr-4": { 25 | "proxycheck\\": "src" 26 | } 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /src/proxycheck.php: -------------------------------------------------------------------------------- 1 | 30, 285 | CURLOPT_RETURNTRANSFER => true 286 | ); 287 | 288 | if($method === 'POST') { 289 | $curl_options[CURLOPT_POST] = 1; 290 | $curl_options[CURLOPT_POSTFIELDS] = $params; 291 | } 292 | 293 | curl_setopt_array($ch, $curl_options); 294 | $api_json_result = curl_exec($ch); 295 | curl_close($ch); 296 | 297 | return json_decode($api_json_result, true); 298 | 299 | } 300 | 301 | } 302 | --------------------------------------------------------------------------------