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 pisotskyi-el/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()
    ->device('android')
    ->country('GB')
    ->sessionRandom() // generate 8-char session id
    ->waitFor(3000)
    ->blockResources()
    ->aiPrompt('Extract product info')
    ->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()
    ->randomDevice()                            // Device: device('windows'|'macos'|'android'), asWindows(), asMacos(), asAndroid(), randomDevice()
    ->country('US')                             // Country code
    ->format('html')                            // Output format: html, markdown, text, json
    ->screenshot()                              // Capture screenshot
    ->waitFor(3000)                             // Wait time before capture (ms)
    ->waitForSelector('.content')               // Wait for CSS selector
    ->blockResources()                          // Block images/css/fonts
    ->session('my-session-id')                  // Session ID for proxy persistence
    ->async()                                   // Submit task asynchronously
    ->aiPrompt('Extract product info')          // AI extraction with custom prompt
    ->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

• device(string $device) - Set device explicitly (windows, macos, android)
• asWindows(), asMacos(), asAndroid(), randomDevice() - Shortcuts / helper methods
• Helpers: RequestBuilder::randomDeviceValue() returns random device string

Geo Location

• country(string $code) - Country code (e.g., 'US', 'GB')

Content & Format

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

Request Configuration

• session(string $id) - Session ID for proxy persistence
• sessionRandom(int $length = 8) - Set random session id (6-8 alnum)
• async(bool $enabled = true) - Submit task for background processing
• waitFor(int $milliseconds) - Wait time before capture
• waitForSelector(string $selector) - Wait for CSS selector
• blockResources(bool $enabled = true) - Block images/css/fonts

Helpers

• RequestBuilder::randomSessionId(int $length = 8) - Generate session id (8 chars)
• RequestBuilder::randomDeviceValue() - Generate random device value

AI Features

• 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