Histats Wrapper API

PHP wrapper untuk mengakses statistik dari Histats.com. Library ini menggunakan headless browser (Chrome) untuk mengambil data karena Histats menggunakan JavaScript untuk render konten.

Requirements

• PHP 8.1+
• Chrome/Chromium browser installed
• ChromeDriver (auto-installed via composer script)

Installation

composer require galangwijaya/histats-wrapper-api

Setelah install, jalankan untuk menginstall ChromeDriver:

composer run install-driver

Atau manual:

vendor/bin/bdi detect drivers

Usage

Basic Usage

<?php

use Histats\HistatsClient;

$client = new HistatsClient();

// Login
$client->login('[email protected]', 'your-password');

// Get all sites
$sites = $client->getSites();

foreach ($sites as $site) {
    echo "{$site->name}: {$site->visitorsToday} visitors today\n";
}

// Select a site and get summary
$client->selectSite($sites[0]->id);
$summary = $client->getSummary();

echo "Total visitors: {$summary->totalVisitors}\n";
echo "Total page views: {$summary->totalPageViews}\n";
echo "Users online: {$summary->usersOnline}\n";

// Logout
$client->logout();

Laravel Integration

<?php

namespace App\Services;

use Histats\HistatsClient;

class HistatsService
{
    private HistatsClient $client;

    public function __construct()
    {
        $this->client = new HistatsClient();
    }

    public function getStats(string $email, string $password, int $siteId): array
    {
        $this->client->login($email, $password);
        $this->client->selectSite($siteId);
        
        $summary = $this->client->getSummary();
        
        $this->client->logout();
        
        return [
            'total_visitors' => $summary->totalVisitors,
            'total_page_views' => $summary->totalPageViews,
            'today_visitors' => $summary->todayVisitors,
            'today_page_views' => $summary->todayPageViews,
            'users_online' => $summary->usersOnline,
        ];
    }
}

Available Methods

HistatsClient

| Method | Description | |--------|-------------| | login(string $email, string $password): bool | Login ke Histats | | logout(): void | Logout dan tutup browser | | isAuthenticated(): bool | Cek status login | | getSites(): Site[] | Ambil semua site | | selectSite(int $siteId): void | Pilih site untuk operasi selanjutnya | | getSummary(): Summary | Ambil summary statistik | | getTrafficStats(): TrafficStats | Ambil statistik traffic harian | | getOnlineVisitors(): OnlineVisitors | Ambil data pengunjung online | | getGeolocation(): GeolocationStats | Ambil statistik lokasi | | getReferrers(): ReferrerStats | Ambil statistik referrer | | getSearchEngines(): SearchEngineStats | Ambil statistik search engine |

Site Model

$site->id;              // int - Site ID
$site->name;            // string - Site name/domain
$site->url;             // string - Site URL
$site->visitorsToday;   // int - Visitors today
$site->pageViewsToday;  // int - Page views today
$site->totalVisitors;   // int - Total visitors
$site->totalPageViews;  // int - Total page views
$site->usersOnline;     // int - Users currently online

Summary Model

$summary->totalVisitors;      // int - Total visitors
$summary->totalPageViews;     // int - Total page views
$summary->todayVisitors;      // int - Visitors today
$summary->todayPageViews;     // int - Page views today
$summary->usersOnline;        // int - Users online
$summary->uniqueVisitors;     // int - First time visitors today
$summary->returningVisitors;  // int - Returning visitors today
$summary->pageViewsPerVisit;  // float - Average page views per visit
$summary->avgTimeOnSite;      // float - Average visit length (seconds)

Configuration

use Histats\Config;
use Histats\HistatsClient;

$config = new Config();
$config->timeout = 60;        // Request timeout in seconds
$config->retryAttempts = 3;   // Number of retry attempts
$config->retryDelay = 1000;   // Delay between retries (ms)

$client = new HistatsClient($config);

How It Works

Histats.com menggunakan JavaScript untuk memuat data statistik secara dinamis. Library ini menggunakan headless Chrome browser melalui php-webdriver untuk:

1. Membuka halaman login Histats
2. Mengisi form dan submit
3. Menunggu JavaScript selesai render
4. Mengambil HTML yang sudah ter-render
5. Parse data dari HTML

Troubleshooting

ChromeDriver not found

Pastikan ChromeDriver sudah terinstall:

composer run install-driver

Chrome not installed

Install Chrome/Chromium di sistem:

# Ubuntu/Debian
sudo apt install chromium-browser

# macOS
brew install --cask google-chrome

# Windows
# Download dari https://www.google.com/chrome/

Timeout errors

Tingkatkan timeout di config:

$config = new Config();
$config->timeout = 120;
$client = new HistatsClient($config);

License

MIT License

Contributing

Pull requests are welcome. For major changes, please open an issue first.