pisotskyi-el/evomi-scraper

Laravel wrapper for Evomi Scraper API

v1.0.1 2025-12-19 18:55 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
• evomi

README

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

Repository: https://gitlab.com/pisotskyi.el/evomi-scraper

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 Evomi Scraper API parameters
• ✅ Easy to use 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 elnopy/evomi-scraper

Publish Configuration

Publish the configuration file to your Laravel application:

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

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

Environment Configuration

Add your Evomi Scraper API key to your .env file:

EVOMI_SCRAPER_API_KEY=your-api-key-here
EVOMI_SCRAPER_BASE_URL=https://scrape.evomi.com

Usage

Basic Usage

use Pisotskyi\EvomiScraper\Facades\EvomiScraper;

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

echo $response->content;
echo $response->statusCode;

POST Request with Browser Mode

use Pisotskyi\EvomiScraper\Facades\EvomiScraper;

$response = EvomiScraper::request('https://example.com/api')
    ->post()
    ->asBrowser()
    ->asMobile()
    ->country('GB')
    ->session('my-session-id')
    ->headers([
        'Accept' => 'application/json',
        'X-Custom-Header' => 'value'
    ])
    ->cookies([
        'tracking_id' => 'abc123'
    ])
    ->body([
        'key' => 'value'
    ])
    ->timeout(60)
    ->send();

if ($response->isSuccessful()) {
    echo $response->content;
}

Advanced Usage with All Parameters

use Pisotskyi\EvomiScraper\Facades\EvomiScraper;

$response = EvomiScraper::request('https://example.com')
    ->get()                                     // HTTP method: get(), post(), put(), patch(), delete()
    ->asBrowser()                               // Mode: asRequest(), asBrowser(), asAuto()
    ->asPremium()                               // Proxy: asDatacenter(), asPremium()
    ->asMobile()                                // Device: asMobile(), asDesktop(), asTablet()
    ->country('US')                             // Country code
    ->region('California')                      // State/region
    ->city('Los Angeles')                       // City name
    ->format('html')                            // Output format: html, markdown, text, json
    ->screenshot()                              // Capture screenshot
    ->headers([                                 // Custom headers
        'Accept-Language' => 'en-US',
        'Custom-Header' => 'value'
    ])
    ->userAgent('Mozilla/5.0...')               // Custom user agent
    ->timeout(30)                               // Timeout in seconds
    ->waitFor(3000)                             // Wait time before capture (ms)
    ->waitForSelector('.content')               // Wait for CSS selector
    ->blockResources()                          // Block images/css/fonts
    ->javascript(true)                          // Enable JavaScript
    ->renderJs()                                // Force JS rendering
    ->session('my-session-id')                  // Session ID for proxy persistence
    ->followRedirects(true)                     // Follow HTTP redirects
    ->aiPrompt('Extract product info')          // AI extraction with custom prompt
    ->autoScroll()                              // Auto-scroll page
    ->scrollDelay(500)                          // Scroll delay in ms
    ->send();

if ($response->isSuccessful()) {
    $html = $response->content;
    
    if ($response->screenshot) {
        // Save screenshot
        file_put_contents('screenshot.png', base64_decode($response->screenshot));
    }
}

Using Dependency Injection

use Pisotskyi\EvomiScraper\EvomiScraperClient;

class MyController extends Controller
{
    public function __construct(
        private EvomiScraperClient $scraper
    ) {}
    
    public function scrape()
    {
        $response = $this->scraper->request('https://example.com')
            ->asBrowser()
            ->country('US')
            ->send();
        
        return response()->json([
            'content' => $response->content,
            'status' => $response->statusCode,
            'credits' => $response->creditsUsed,
        ]);
    }
}

Working with Response

$response = EvomiScraper::request('https://api.example.com/data')
    ->format('json')
    ->send();

// Check if successful
if ($response->isSuccessful()) {
    echo "Success!";
}

// Get content
$html = $response->content;

// Parse JSON response
$data = $response->json();

// Get headers
$headers = $response->headers;

// Get metadata
$credits = $response->creditsUsed;
$time = $response->executionTime;

Configuration

The config/evomi-scraper.php file contains all available configuration options:

return [
    // Your API key from Evomi dashboard
    'api_key' => env('EVOMI_SCRAPER_API_KEY', ''),
    
    // Base URL for API
    'base_url' => env('EVOMI_SCRAPER_BASE_URL', 'https://scrape.evomi.com'),
    
    // Request timeout in seconds
    'timeout' => env('EVOMI_SCRAPER_TIMEOUT', 30),
];

Retry Mechanism

The package includes an automatic retry mechanism with intelligent error handling:

• Automatically retries failed requests (default: up to 3 attempts)
• Does not retry on client errors (4xx status codes)
• Configurable delay between retries (default: 1 second)
• Configurable via retry config key if you publish and modify the config file

Available Modes

Request Mode

Simple HTTP request. Fast and efficient.

• Datacenter: 1 credit
• Premium: 2 credits

Browser Mode

Full browser rendering with JavaScript support.

• Premium only: 5 credits

Auto Mode

Automatically chooses between request and browser based on the website.

• Request succeeds: 2 credits
• Upgraded to browser: 6 credits

Proxy Types

• datacenter: Fast and cheap, works only with request mode
• premium (residential): More expensive but works with all modes, better for avoiding detection

Error Handling

use Pisotskyi\EvomiScraper\Exceptions\EvomiScraperException;

try {
    $response = EvomiScraper::request('https://example.com')
        ->asBrowser()
        ->send();
        
    if (!$response->isSuccessful()) {
        echo "HTTP Error: " . $response->statusCode;
    }
} catch (EvomiScraperException $e) {
    echo "Error: " . $e->getMessage();
    echo "Code: " . $e->getCode();
}

Fluent Builder Methods Reference

HTTP Methods

• get(), post(), put(), patch(), delete() - Set HTTP method

Modes

• asRequest() - Simple HTTP request (fast)
• asBrowser() - Full browser rendering
• asAuto() - Automatically choose mode

Proxy Types

• asDatacenter() - Datacenter proxies (works with request mode only)
• asPremium() - Premium residential proxies (works with all modes)

Devices

• asMobile(), asDesktop(), asTablet() - Device emulation

Geo Location

• country(string $code) - Country code (e.g., 'US', 'GB')
• region(string $region) - State/region name
• city(string $city) - City name

Content & Format

• format(string $format) - Output format: 'html', 'markdown', 'text', 'json'
• screenshot(bool $enabled = true) - Capture screenshot

Headers & Cookies

• headers(array $headers) - Set multiple headers
• header(string $key, string $value) - Set single header
• cookies(array $cookies) - Set multiple cookies
• cookie(string $name, string $value) - Set single cookie
• userAgent(string $ua) - Custom user agent

Request Configuration

• body(array $data) - Request body (for POST/PUT/PATCH)
• timeout(int $seconds) - Request timeout in seconds
• session(string $id) - Session ID for proxy persistence
• followRedirects(bool $enabled = true) - Follow HTTP redirects

Browser Features

• javascript(bool $enabled = true) - Enable/disable JavaScript
• renderJs(bool $enabled = true) - Force JavaScript rendering
• waitFor(int $milliseconds) - Wait time before capture
• waitForSelector(string $selector) - Wait for CSS selector
• blockResources(bool $enabled = true) - Block images/css/fonts
• autoScroll(bool $enabled = true) - Auto-scroll page
• scrollDelay(int $milliseconds) - Scroll delay

AI Features

• aiExtract(bool $enabled = true) - Enable AI extraction
• aiPrompt(string $prompt) - Custom AI extraction prompt

Execution

• send() - Build and send the request, returns ScraperResponseDTO

Credits & Pricing

Transparent credit-based pricing:

• Request + Datacenter: 1 credit
• Request + Premium: 2 credits
• Browser + Premium: 5 credits
• Auto + Premium (request succeeds): 2 credits
• Auto + Premium (upgraded to browser): 6 credits
• Screenshot: +1 credit
• AI Enhancement: +10 credits

Security

⚠️ Important: Never expose your API key in client-side code or public repositories. Always store it in environment variables and use HTTPS for all requests.

Backward Compatibility

The old DTO-based API is still supported for backward compatibility:

use Pisotskyi\EvomiScraper\Facades\EvomiScraper;
use Pisotskyi\EvomiScraper\DTO\ScraperRequestDTO;

// Using DTO directly
$request = new ScraperRequestDTO(
    url: 'https://example.com',
    mode: ScraperRequestDTO::MODE_BROWSER,
    country: 'US'
);

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

// Simple scraping
$response = EvomiScraper::scrapeUrl('https://example.com');

Support

For API documentation and support, visit Evomi Documentation.

License

MIT License