Download the PHP package rkdhatterwal/decodo-scraper without Composer

Decodo Scraper for Laravel

A clean, well-tested Laravel wrapper for the Decodo Web Scraping API — supports both real-time (v2) and async/batch (v3) scraping.

Requirements

• PHP 8.1+
• Laravel 10, 11, 12, or 13

Installation

Publish the config and migrations:

Add credentials to .env:

Your token is in the Decodo dashboard under Scraping APIs → Username / Token.

Real-time Scraping (v2)

Use the Decodo facade or inject DecodoClient.

Full control with PayloadBuilder

Database Tracking

When database.enabled is true (default), the package automatically tracks every async task and batch in your database using the decodo_tasks and decodo_batches tables.

Models

• Rkdhatterwal\DecodoScraper\Models\DecodoTask
• Rkdhatterwal\DecodoScraper\Models\DecodoBatch

You can associate a task with one of your own models (e.g., a Product or Lead) by passing it to queueTask:

Async Scraping (v3)

Use the DecodoAsync facade or inject AsyncDecodoClient.

Queue a single task

Queue with PayloadBuilder

You can also use the PayloadBuilder with async tasks for a more fluent experience:

Queue a batch

Decodo enforces a 1-request-per-second rate limit on batch submissions. The package handles this for you automatically.

Check status & retrieve results

v3 Batch Format

Decodo v3 supports passing an array of URLs in a single request. The package handles this via queueBatch or by passing URLs to buildBatch() in the PayloadBuilder:

Webhooks

The package includes a built-in webhook handler that automatically updates your local database records when Decodo tasks complete.

Setup

1. Ensure webhook.enabled is true in your config.
2. Configure a DECODO_WEBHOOK_SECRET in your .env to enable passthrough verification.
3. Exempt the webhook path from CSRF protection in app/Http/Middleware/VerifyCsrfToken.php (Laravel 10) or your bootstrap/app.php (Laravel 11+):

Security

The built-in webhook handler uses the VerifyDecodoWebhook middleware to ensure callbacks are authentic. It compares the passthrough value from the request against your configured secret using hash_equals.

Automatic Injection

When webhook.auto_inject_callback is enabled, the package will automatically append the correct callback_url to every async request. You don't need to pass it manually unless you want to override it.

Result Caching

To avoid redundant API calls and save credits, enable the DecodoResultCache. It caches results for "done" tasks (which are immutable) for up to 23 hours.

Logging

The package includes a DecodoLogger that routes all package-specific activities to a Laravel log channel. By default, it uses your application's default channel.

To isolate Decodo logs, set the channel in config/decodo.php:

And add the channel to your config/logging.php:

Events

You can listen for the following events to trigger your own logic:

• Rkdhatterwal\DecodoScraper\Events\DecodoTaskCompleted
• Rkdhatterwal\DecodoScraper\Events\DecodoTaskFaulted
• Rkdhatterwal\DecodoScraper\Events\DecodoTaskExpired
• Rkdhatterwal\DecodoScraper\Events\DecodoBatchCompleted

Artisan Commands

• php artisan decodo:status {taskId} — Check the status of a specific task.
• php artisan decodo:retry {taskId} — Retry a faulted task.
• php artisan decodo:prune — Clean up old database records.

Pruning Configuration

Configure retention periods in config/decodo.php:

DTOs & Public Properties

All DTOs in this package use PHP 8.1+ public readonly properties for a better developer experience. You can access properties directly: echo $result->content;.

ScrapeResult DTO

TaskResponse DTO

Returned by queueTask() and getTaskStatus().

BatchTaskResponse DTO

Returned by queueBatch().

All Payload Parameters

See the Decodo parameters docs.

Testing

The package provides a powerful DecodoFake helper to mock API responses and assert that requests were sent.

For async tasks:

For batches:

Other Assertions & Helpers

Changelog

See CHANGELOG.md.

License

MIT