README

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('your-email@example.com', '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:

Membuka halaman login Histats
Mengisi form dan submit
Menunggu JavaScript selesai render
Mengambil HTML yang sudah ter-render
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.

galangwijaya / histats-wrapper-api

Maintainers

Details