Your first PHP collection script

A collection script answers three questions: which page to open, where to find its values, and which record to save. Write one in Collection scenarios, or start with a draft from the AI assistant.

Collection scripts run in PHP, JavaScript, TypeScript, and Python. This page shows a PHP example; see the JavaScript introduction for a JavaScript scenario. See TypeScript for typed scenarios and Python for synchronous def run(ctx): scenarios. Go and other languages are planned. Examples in the API section are for external integrations.

Prepare the source

1. Create a site and enter its address.
2. Add the site fields sku (string, key), name (string), price (decimal), and url (link).
3. Create a collection scenario for the site. The default entry point is run.
4. Paste the code below and replace its CSS selectors with those from your catalog. Set catalog_url to the catalog address in the run parameters.

Example: one catalog page

<?php
function run(\Sdk\Context $ctx): void
{
    $url = (string) $ctx->param('catalog_url', '');
    if ($url === '') {
        $ctx->abort('Set catalog_url in the run parameters');
    }
    $ctx->log('Opening catalog', ['url' => $url]);
    $response = $ctx->http()->get($url);
    if (!$response->ok()) {
        $ctx->abort('Catalog returned HTTP ' . $response->status);
    }
    $cards = $response->dom()->qa('.product-card');
    if (count($cards) === 0) {
        $ctx->abort('No cards found. Check the selector and loading mode');
    }
    $done = 0;
    foreach ($cards as $card) {
        $sku = $card->attr('data-sku');
        if ($sku === null || $sku === '') {
            $ctx->log('Card skipped: no SKU', [], 'warning');
            continue;
        }
        $ctx->emit([
            'sku' => $sku,
            'name' => $card->q('.product-title')?->text(),
            'price' => $ctx->text()->money($card->q('.price')?->text()),
            'url' => $card->q('a.product-link')?->abs(),
        ], $sku);
        $done++;
        $ctx->progress($done, count($cards), 'Reading products');
    }
    $ctx->log('Page processed', ['saved' => $done]);
}

$ctx provides HTTP, HTML, logging, and result methods. qa() finds all cards; q() finds one nested element; text() reads text; attr() reads an attribute; abs() resolves a relative link.

emit() passes a record to the platform. The $sku key identifies the same product in a later run. Do not use a card's position as its key: product order can change. money() parses a price such as 1,500.50, preserving its fraction. A missing price remains null instead of becoming zero.

Find the right selectors

Open the visual mapper and select a card and its fields. .product-card and the other selectors above are examples; they will not work for every site. Inspect the page snapshot in the run log to make sure the expected elements were loaded.

Verify the script

Check the code, save a version, and run a trial. Inspect the log and results. Compare several records with the source site, including a product without a price. Publish the version after a successful check.

This example reads one page. To cover the entire catalog, add pagination. If cards appear after JavaScript runs, use the browser.