pisotskyi-el/infatica-scraper

Laravel wrapper for Infatica Scraper API with DTO support

v1.0.3 2026-03-25 15:10 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/support: ^9.0|^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.0|^10.0

MIT

• Oleksandr

• api
• proxy
• scraper
• laravel
• infatica

README

Laravel wrapper for Infatica Scraper API with full DTO support and easy configuration.

Features

• ✅ Full Laravel integration with Service Provider and Facade
• ✅ DTO (Data Transfer Objects) for type-safe requests and responses
• ✅ Publishable configuration file
• ✅ Built-in retry mechanism with intelligent error handling
• ✅ Support for all Infatica Scraper API parameters
• ✅ Browser rendering mode via /render endpoint
• ✅ Easy to use fluent API with Facade and Dependency Injection
• ✅ PSR-4 autoloading

Requirements

• PHP 8.1 or higher
• Laravel 9.x, 10.x, or 11.x
• Guzzle HTTP Client 7.x

Installation

Install the package via Composer:

composer require pisotskyi-el/infatica-scraper

Publish Configuration

php artisan vendor:publish --tag=infatica-scraper-config

This will create a config/infatica-scraper.php file in your Laravel application.

Environment Configuration

Add your Infatica API key to your .env file:

INFATICA_SCRAPER_API_KEY=your-api-key-here
INFATICA_SCRAPER_BASE_URL=https://scrape.infatica.io

Usage

Basic Usage

use Pisotskyi\InfaticaScraper\Facades\InfaticaScraper;

$response = InfaticaScraper::request('https://example.com')
    ->send();

$html = $response->getDecodedHtml(); // auto base64 decode
echo $response->statusCode;
echo $response->requestsUsed;

With Country & Proxy

use Pisotskyi\InfaticaScraper\Facades\InfaticaScraper;

$response = InfaticaScraper::request('https://example.com')
    ->country('US')
    ->residential()
    ->chrome()
    ->sessionRandom()
    ->send();

Browser Rendering Mode

Uses the /render endpoint — renders JavaScript via a real headless browser.

$response = InfaticaScraper::request('https://example.com')
    ->asBrowser()
    ->country('DE')
    ->language('de-DE')
    ->send();

$html = $response->getDecodedHtml();

POST Request

$response = InfaticaScraper::request('https://example.com/api')
    ->post('{"key":"value"}')
    ->country('GB')
    ->send();

Return Raw HTML

By default the API returns JSON with base64-encoded HTML. Use returnHtml() to get raw HTML directly.

$response = InfaticaScraper::request('https://example.com')
    ->returnHtml()
    ->send();

// $response->html contains raw HTML string
// $response->isRaw === true
echo $response->html;

Advanced Usage

$response = InfaticaScraper::request('https://example.com')
    ->asRequest()                    // Mode: asRequest() (default), asBrowser()
    ->get()                          // HTTP method: get() (default), post($body)
    ->returnHtml()                   // Return raw HTML instead of JSON+base64
    ->country('US')                  // ISO 3166-1 alpha-2 country code
    ->language('en-US')              // Accept-Language header
    ->datacenter()                   // Proxy: datacenter() (default), residential()
    ->desktop()                      // Device: desktop() (default), mobile(), macos(), randomDevice()
    ->chrome()                       // Browser: chrome(), firefox(), randomBrowser()
    ->session('uuid-here')           // Session UUID for persistent proxy
    ->sessionRandom()                // Generate and set a random UUID session
    ->timeout(5000)                  // Timeout in milliseconds (optional)
    ->headers(['X-Custom' => 'val']) // Custom HTTP headers
    ->referer('https://google.com')  // Referer URL
    ->send();

Using Dependency Injection

use Pisotskyi\InfaticaScraper\InfaticaScraperClient;

class MyController extends Controller
{
    public function __construct(
        private InfaticaScraperClient $scraper
    ) {}

    public function scrape()
    {
        $response = $this->scraper->request('https://example.com')
            ->asBrowser()
            ->country('US')
            ->send();

        return response()->json([
            'html'          => $response->getDecodedHtml(),
            'status'        => $response->statusCode,
            'requests_used' => $response->requestsUsed,
            'elapsed_ms'    => $response->elapsedTime,
        ]);
    }
}

Working with the Response

$response = InfaticaScraper::request('https://example.com')->send();

$response->isSuccessful();    // true if status 2xx
$response->getDecodedHtml();  // decoded HTML string (base64 or raw)
$response->html;              // raw value from API (base64 string or raw HTML)
$response->statusCode;        // HTTP status of the scraped page
$response->requestsUsed;      // API requests consumed
$response->elapsedTime;       // elapsed time in ms
$response->toArray();         // all fields as array

DTO-based API

use Pisotskyi\InfaticaScraper\DTO\ScraperRequestDTO;
use Pisotskyi\InfaticaScraper\Facades\InfaticaScraper;

$request = new ScraperRequestDTO(
    url:       'https://example.com',
    country:   'US',
    proxyType: ScraperRequestDTO::PROXY_RESIDENTIAL,
    browser:   ScraperRequestDTO::BROWSER_CHROME,
);

$response = InfaticaScraper::scrape($request);

// Quick scrape
$response = InfaticaScraper::scrapeUrl('https://example.com');

Configuration

// config/infatica-scraper.php
return [
    'api_key'  => env('INFATICA_SCRAPER_API_KEY', ''),
    'base_url' => env('INFATICA_SCRAPER_BASE_URL', 'https://scrape.infatica.io'),
    'timeout'  => env('INFATICA_SCRAPER_TIMEOUT', 30),
    'retry'    => [
        'enabled'      => env('INFATICA_SCRAPER_RETRY_ENABLED', true),
        'max_attempts' => env('INFATICA_SCRAPER_RETRY_MAX_ATTEMPTS', 3),
        'delay_ms'     => env('INFATICA_SCRAPER_RETRY_DELAY_MS', 1000),
    ],
];

Fluent Builder Reference

Mode

• asRequest() — simple HTTP request, hits POST / (default)
• asBrowser() — headless browser rendering, hits POST /render

HTTP Method

• get() — GET request (default)
• post(string $body = '') — POST request with optional body

Proxy

• datacenter() — datacenter proxy (default)
• residential() — residential proxy
• proxyType(string $type) — explicit: datacenter or residential

Location

• country(string $code) — ISO 3166-1 alpha-2 code (e.g. US, DE)
• language(string $lang) — language tag (e.g. en-US, de-DE)

Device

• desktop(), mobile(), macos() — shortcuts
• device(string $device) — explicit: desktop, mobile, macos
• randomDevice() — random device
• RequestBuilder::randomDeviceValue() — static helper

Browser

• chrome(), firefox()
• browser(string $browser) — explicit: chrome or firefox
• randomBrowser() — random browser
• RequestBuilder::randomBrowserValue() — static helper

Session

• session(string $uuid) — set session UUID
• sessionRandom() — generate and set random UUID v4
• RequestBuilder::randomSessionId() — static UUID generator

Headers

• headers(array $headers) — custom HTTP headers as key-value
• referer(string $url) — Referer URL

Response

• returnHtml(bool $value = true) — return raw HTML instead of JSON+base64

Timeout

• timeout(int $milliseconds) — request timeout in ms (optional)

Execute

• send() — build and send, returns ScraperResponseDTO

Error Handling

use Pisotskyi\InfaticaScraper\Exceptions\InfaticaScraperException;

try {
    $response = InfaticaScraper::request('https://example.com')
        ->asBrowser()
        ->send();

    if (!$response->isSuccessful()) {
        echo 'HTTP Error: ' . $response->statusCode;
    }
} catch (InfaticaScraperException $e) {
    echo 'Error: ' . $e->getMessage();
    echo 'Code: '  . $e->getCode();
}

Security

⚠️ Never expose your API key in client-side code or public repositories. Always store it in environment variables.

Support

For API documentation and support, visit Infatica Documentation.

License

MIT License. See LICENSE for details.