Skip to content

Commit a8ac130

Browse files
Check-HostCheck-Host
committed
init update
0 parents  commit a8ac130

7 files changed

Lines changed: 608 additions & 0 deletions

File tree

‎.github/workflows/php.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: PHP SDK Tests
2+
3+
on:
4+
push:
5+
branches: [ "main", "master" ]
6+
pull_request:
7+
branches: [ "main", "master" ]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
php-versions: ['8.1', '8.2', '8.3', '8.4']
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Setup PHP
21+
uses: shivammathur/setup-php@v2
22+
with:
23+
php-version: ${{ matrix.php-versions }}
24+
extensions: curl, json
25+
coverage: none
26+
27+
- name: Validate composer.json
28+
run: composer validate --strict
29+
30+
- name: Install dependencies
31+
run: composer install --prefer-dist --no-progress
32+
33+
- name: Run test suite
34+
run: vendor/bin/phpunit

‎README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Check-Host API PHP Library
2+
3+
A lightweight, lightning-fast, and feature-complete PHP 8+ wrapper for the [Check-Host.cc](https://check-host.cc) API. Full documentation is available at [docs.check-host.cc](https://docs.check-host.cc).
4+
5+
Seamlessly integrate global network diagnostics into your backend. Perform remote Ping, TCP, UDP, DNS, and HTTP checks from multiple worldwide locations—straight from your PHP application. Checks from 60+ locations worldwide.
6+
7+
## Features
8+
9+
- **Zero Dependencies:** Built purely on the native PHP cURL extension. No Guzzle, no Symfony HTTP Client, zero package bloat.
10+
- **Bulletproof Payloads:** Strictly utilizes POST requests for all active monitoring endpoints. This completely eliminates nasty URL-encoding issues with complex hostnames or custom UDP payloads.
11+
- **Modern & Clean:** Written for PHP 8.1+ with full type hinting and clean structure.
12+
- **Smart Authentication:** API Key auto-injection. Configure your key once during initialization, and the core SDK seamlessly handles all authentication payloads under the hood.
13+
14+
## Requirements
15+
16+
- **PHP**: ^8.1
17+
- `ext-curl` and `ext-json`
18+
19+
## Installation
20+
21+
Ensure you have PHP 8.1+ installed. You can install the package directly from Packagist using Composer:
22+
```bash
23+
composer require check-hostcc/check-host-api-php
24+
```
25+
26+
## Quickstart
27+
28+
```php
29+
require 'vendor/autoload.php';
30+
31+
use CheckHostCc\CheckHostApi\CheckHost;
32+
33+
// Initialize the client. The API Key is optional.
34+
// Without an API key, standard public rate limits apply.
35+
// $checkHost = new CheckHost('YOUR_API_KEY_HERE');
36+
// Or leave empty: new CheckHost()
37+
$checkHost = new CheckHost();
38+
39+
// Example: Retrieve all current nodes
40+
$locations = $checkHost->locations();
41+
print_r($locations);
42+
```
43+
44+
---
45+
46+
## Complete API Reference & Examples
47+
48+
This library supports both minimal invocations and detailed, options-rich requests for every endpoint. All failures (network issues, API errors, rate limits) throw a `CheckHostException`.
49+
50+
### Common Options Used in Examples
51+
- `region`: Array of Nodes or ISO Country Codes (e.g. `['DE', 'NL']`) or Continents (e.g. `['EU']`).
52+
- `repeatchecks`: Number of repeated probes to perform per node for higher accuracy (Live Check).
53+
- `timeout`: Connection timeout threshold in seconds (Currently disabled on Check-host backend, but supported).
54+
55+
---
56+
57+
### Information & Utilities
58+
59+
#### Get My IP
60+
Returns the requesting client's public IPv4 or IPv6 address.
61+
```php
62+
$ip = $checkHost->myip();
63+
```
64+
65+
#### Get Locations
66+
Fetches a dynamic list of all currently active monitoring nodes across the globe.
67+
```php
68+
$nodes = $checkHost->locations();
69+
```
70+
71+
#### Host Info (GeoIP/ASN)
72+
Retrieves detailed geolocation data, ISP information, and ASN details.
73+
```php
74+
// Minimal Example
75+
$info = $checkHost->info('check-host.cc');
76+
```
77+
78+
#### WHOIS Lookup
79+
Performs a WHOIS registry lookup.
80+
```php
81+
// Minimal Example
82+
$whois = $checkHost->whois('check-host.cc');
83+
```
84+
85+
---
86+
87+
### Active Monitoring (POST Tasks)
88+
89+
Monitoring endpoints initiate tasks asynchronously and return a `Task Object` array containing an `uuid`. Use the `report()` method (documented below) to fetch the actual results.
90+
91+
#### Ping
92+
Dispatches ICMP echo requests to the target from global nodes.
93+
```php
94+
// Minimal Example
95+
$pingMin = $checkHost->ping('8.8.8.8');
96+
97+
// Max Example (With options)
98+
$pingMax = $checkHost->ping('8.8.8.8', [
99+
'region' => ['DE', 'NL'],
100+
'repeatchecks' => 5,
101+
'timeout' => 5
102+
]);
103+
```
104+
105+
#### DNS
106+
Queries global nameservers for specific DNS records.
107+
```php
108+
// Minimal Example
109+
$dnsMin = $checkHost->dns('check-host.cc');
110+
111+
// Max Example (With options - TXT Record)
112+
$dnsMax = $checkHost->dns('check-host.cc', [
113+
'querymethod' => 'TXT', // A, AAAA, MX, TXT, SRV, etc.
114+
'region' => ['US', 'DE']
115+
]);
116+
```
117+
118+
#### TCP
119+
Attempts to establish a 3-way TCP handshake on a specific destination port.
120+
```php
121+
// Minimal Example (Target, Port)
122+
$tcpMin = $checkHost->tcp('1.1.1.1', 443);
123+
124+
// Max Example (With options)
125+
$tcpMax = $checkHost->tcp('1.1.1.1', 80, [
126+
'region' => ['DE', 'NL'],
127+
'repeatchecks' => 3,
128+
'timeout' => 10
129+
]);
130+
```
131+
132+
#### UDP
133+
Sends UDP packets to a specified target and port.
134+
```php
135+
// Minimal Example (Target, Port)
136+
$udpMin = $checkHost->udp('1.1.1.1', 53);
137+
138+
// Max Example (With custom hex payload and options)
139+
$udpMax = $checkHost->udp('1.1.1.1', 123, [
140+
'payload' => '0b', // NTP Request Hex
141+
'region' => ['EU'],
142+
'repeatchecks' => 2,
143+
'timeout' => 5
144+
]);
145+
```
146+
147+
#### HTTP
148+
Executes an HTTP/HTTPS request to the target to measure TTFB and latency.
149+
```php
150+
// Minimal Example
151+
$httpMin = $checkHost->http('https://check-host.cc');
152+
153+
// Max Example (With options)
154+
$httpMax = $checkHost->http('https://check-host.cc', [
155+
'region' => ['US', 'DE'],
156+
'repeatchecks' => 3,
157+
'timeout' => 10
158+
]);
159+
```
160+
161+
#### MTR
162+
Initiates an MTR (My Traceroute) diagnostic.
163+
```php
164+
// Minimal Example
165+
$mtrMin = $checkHost->mtr('1.1.1.1');
166+
167+
// Max Example (With protocols, IP forced, and options)
168+
$mtrMax = $checkHost->mtr('1.1.1.1', [
169+
'repeatchecks' => 15,
170+
'forceIPversion' => 4, // 4 or 6
171+
'forceProtocol' => 'TCP', // default is ICMP
172+
'region' => ['DE', 'US']
173+
]);
174+
```
175+
176+
---
177+
178+
### Fetching Results
179+
180+
#### Report
181+
Fetches the compiled report and real-time statuses from a previously initiated monitoring check (Ping, TCP, HTTP, etc.) using its unique `uuid`. Wait 1-2 seconds after starting a check before polling. Longer checks with multiple repeats take one check per second and can be requested multiple times.
182+
```php
183+
// The check UUID is returned by any monitoring method above
184+
$taskUuid = 'c0b4b0e3-aed7-4ae2-9f53-7bac879697cb';
185+
186+
// Fetch the result payload
187+
$report = $checkHost->report($taskUuid);
188+
```
189+
190+
## License
191+
192+
ISC License

‎composer.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "check-hostcc/check-host-api-php",
3+
"description": "A lightweight, lightning-fast PHP wrapper for the Check-Host.cc API.",
4+
"type": "library",
5+
"require": {
6+
"php": "^8.1",
7+
"ext-curl": "*",
8+
"ext-json": "*"
9+
},
10+
"require-dev": {
11+
"phpunit/phpunit": "^10.5"
12+
},
13+
"license": "ISC",
14+
"authors": [
15+
{
16+
"name": "Check-Host",
17+
"email": "dev@check-host.cc"
18+
}
19+
],
20+
"autoload": {
21+
"psr-4": {
22+
"CheckHostCc\\CheckHostApi\\": "src/"
23+
}
24+
},
25+
"autoload-dev": {
26+
"psr-4": {
27+
"CheckHostCc\\CheckHostApi\\Tests\\": "tests/"
28+
}
29+
}
30+
}

‎example.php‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?php
2+
3+
require_once __DIR__ . '/src/Exceptions/CheckHostException.php';
4+
require_once __DIR__ . '/src/CheckHost.php';
5+
6+
use CheckHostCc\CheckHostApi\CheckHost;
7+
8+
try {
9+
$api = new CheckHost();
10+
11+
echo "Fetching my ip...\n";
12+
$ip = $api->myip();
13+
print_r($ip);
14+
15+
echo "\nFetching locations short count...\n";
16+
$locations = $api->locations();
17+
echo "Active nodes: " . count($locations) . "\n";
18+
19+
echo "\nPinging 8.8.8.8...\n";
20+
$ping = $api->ping('8.8.8.8', ['region' => ['EU']]);
21+
print_r($ping);
22+
23+
if (isset($ping['uuid'])) {
24+
echo "\nWaiting 2 seconds before report...\n";
25+
sleep(2);
26+
$report = $api->report($ping['uuid']);
27+
print_r($report);
28+
}
29+
30+
echo "\nAll basic tests passed.\n";
31+
32+
}
33+
catch (\Exception $e) {
34+
echo "Error: " . $e->getMessage() . "\n";
35+
}

0 commit comments

Comments
 (0)