Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 30 ยท Projects

Project: Order Export Task

Build a scheduled task that pages through orders with the DAL, writes a safe CSV file, reads its target from plugin config and can be re-run without duplicates.

Shops often need a regular export: new orders as a CSV for the accounting team, a file dropped into a folder for a warehouse tool, a nightly snapshot for a spreadsheet. It sounds trivial, and the first version usually is: load all orders, write a file. The trouble starts at 50,000 orders, when the job runs out of memory, or when it fails halfway and the next run exports the first half again.

In this project you build the job properly. It runs as a scheduled task, reads orders in pages through the DAL with the associations it needs, writes a CSV that spreadsheets cannot abuse, takes its target folder from the plugin configuration, and remembers where it stopped, so running it twice never exports an order twice.

Shopware cannot run on this site. The real plugin code is read-only, and each part is followed by a runnable stand-in in plain PHP with SQLite. The stand-ins show the technique (paging, escaping, cursors), not Shopware's classes.

The shape of the job

flowchart TD
    S["Scheduler<br/>every hour"] --> H["Task handler"]
    H --> L["Load cursor<br/>(last exported order)"]
    L --> P["Read one page<br/>of orders"]
    P --> W["Append rows<br/>to CSV"]
    W --> M["Save cursor"]
    M --> P
    P -->|"page is empty"| D["Done"]

Read a page, write it, move the cursor, repeat. The cursor is saved after each page, not at the end.

Four rules shape everything below:

  1. Bounded memory. Never ask for all orders. Read a fixed page, write it, forget it.
  2. Stable paging. Page by a sorted key, so rows that arrive during the run do not shift the pages.
  3. Safe output. A customer controls their own name and address. Treat every cell as untrusted.
  4. Idempotent runs. Saving a cursor makes a repeat or a resume harmless.

The task and its handler

A scheduled task is two small classes: a definition (name and interval) and a handler that does the work. The scheduler dispatches the task as a message; the handler runs in the worker.

PHP
<?php declare(strict_types=1);

namespace Acme\OrderExport\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask;

class OrderExportTask extends ScheduledTask
{
    public static function getTaskName(): string
    {
        return 'acme.order_export';
    }

    public static function getDefaultInterval(): int
    {
        return 3600; // seconds
    }
}
PHP
<?php declare(strict_types=1);

namespace Acme\OrderExport\ScheduledTask;

use Acme\OrderExport\Service\OrderExporter;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler(handles: OrderExportTask::class)]
class OrderExportTaskHandler extends ScheduledTaskHandler
{
    public function __construct(
        EntityRepository $scheduledTaskRepository,
        private readonly OrderExporter $exporter,
    ) {
        parent::__construct($scheduledTaskRepository);
    }

    public function run(): void
    {
        $this->exporter->export(Context::createCLIContext());
    }
}

The task class is tagged shopware.scheduled.task in services.xml, and the handler is a normal service. Older versions needed the messenger.message_handler tag instead of the attribute, and the base class constructor has gained an optional logger argument over time, so check the base class in the version you target. Tasks are registered when the plugin is activated (or with scheduled-task:register), and a worker has to be running for them to execute; see Scheduled Tasks and the Message Queue.

The handler stays thin on purpose. All logic lives in OrderExporter, a plain service that you can test without the scheduler.

Reading orders in pages

The exporter builds a Criteria with exactly the associations the CSV needs. Loading associations you do not use is the quickest way to make this job slow. Here the CSV needs the customer's email and the line items.

PHP
public function export(Context $context): int
{
    $targetDir = $this->config->getString('AcmeOrderExport.config.targetDirectory');
    $cursor = $this->state->load();            // e.g. ['2030-01-05 10:00:00.000', 'a1b2...']
    $written = 0;

    do {
        $criteria = new Criteria();
        $criteria->setLimit(200);
        $criteria->addAssociation('orderCustomer');
        $criteria->addAssociation('lineItems');
        $criteria->addSorting(new FieldSorting('createdAt', FieldSorting::ASCENDING));
        $criteria->addSorting(new FieldSorting('id', FieldSorting::ASCENDING));

        if ($cursor !== null) {
            [$createdAt, $id] = $cursor;
            $criteria->addFilter(new MultiFilter(MultiFilter::CONNECTION_OR, [
                new RangeFilter('createdAt', [RangeFilter::GT => $createdAt]),
                new MultiFilter(MultiFilter::CONNECTION_AND, [
                    new EqualsFilter('createdAt', $createdAt),
                    new RangeFilter('id', [RangeFilter::GT => $id]),
                ]),
            ]));
        }

        $orders = $this->orderRepository->search($criteria, $context)->getEntities();
        if ($orders->count() === 0) {
            break;
        }

        $this->csv->append($targetDir, $orders);
        $last = $orders->last();
        $cursor = [$last->getCreatedAt()->format('Y-m-d H:i:s.v'), $last->getId()];
        $this->state->save($cursor);
        $written += $orders->count();
    } while (true);

    return $written;
}

Why not just setOffset()? Offset paging has two flaws here. A new order inserted while the job runs shifts every later page, so one row can be exported twice or skipped. And MySQL still has to walk past all skipped rows, so late pages get slower. Keyset paging (also called cursor paging) asks for "the rows after this one" using the sort key, which stays correct and fast. The id is a tie-breaker, because several orders can share one timestamp. Ids are stored as bytes in MySQL; the DAL handles the conversion for you when you filter with hex ids, but compare how your version orders ids before relying on id alone. Shopware also ships a RepositorySearchIterator that pages a criteria for you; it is a good choice for plain "visit everything once" jobs, but it does not remember a position between runs, which is what this job needs.

Two more details. A Context::createCLIContext() is the right context for jobs, because there is no logged-in user. And the filter should usually also limit the order state, for example only paid orders, so that unfinished carts-turned-orders are not exported before they are final.

Try it: keyset paging and a cursor

The stand-in keeps orders in SQLite and a one-row cursor table. It also simulates a crash after the first page, to show why the cursor is saved per page. Each run writes into its own in-memory "file".

PHP Paging with a saved cursor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Run 2 starts after the third order, even though run 1 died, and run 3 finds nothing. The two orders that share the timestamp 10:07 are told apart by the id, so neither is skipped nor repeated.

Writing a safe CSV

PHP's fputcsv() handles commas, quotes and line breaks. It does not handle CSV injection: a cell that starts with =, +, - or @ is treated as a formula by spreadsheet programs. A customer who types =HYPERLINK("https://example.org","click") as their last name has put a formula into your accountant's spreadsheet. The usual defense is to prefix such text cells with a single quote. Apply it to free text (names, addresses, notes), and decide deliberately about numbers: keep amounts as real numbers in a number column, and do not prefix a legitimate negative value like a refund.

Note also that since PHP 8.4, fputcsv() expects you to pass the $escape argument explicitly; the examples below pass an empty string, which switches the old backslash escape off and follows the standard CSV rules.

Try it: a CSV writer you can trust

PHP A CSV line writer with a formula guard

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The comma and quote in the second name are quoted and doubled, the newline in the fourth stays inside its cell, the formula in the third is defused, and the negative number in the last row is left alone because it is a number, not text.

Config and the output file

The target folder should not be hard-coded. Add an input field to config.xml (a text field named targetDirectory) and read it with SystemConfigService, using the key AcmeOrderExport.config.targetDirectory. Validate it at the start of each run: the folder must exist, be writable and sit inside a path you allow. Use a file name that includes the date and a counter, write to a temporary name, and rename when the page loop finishes, so a reader never opens a half-written file. Log the number of orders and the file name through the injected logger; a job nobody can see is a job nobody trusts.

Making repeat runs safe

Your options, from simplest to strongest:

  • Cursor (this lesson): remember the last exported (createdAt, id). Cheap, no schema change on orders.
  • Marker: a custom field acme_exported_at on the order, set after export. It survives a lost cursor but costs a write per order.
  • Export log table: one row per file with the order range and checksum, which also gives you an audit trail.

Whatever you choose, decide what happens on failure. Here the cursor moves per page, so a crash can leave a partial file, but never a duplicate order in later files. If the consumer needs all-or-nothing files, write to a temporary file and only move the cursor after the rename. The general idea of safe repeats is the subject of Idempotency.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is keyset paging preferred over offset paging for this job?

    Keyset paging asks for rows after a known sort position. Offset paging can skip or repeat rows when data changes, and gets slower as the offset grows.
  2. 2. Why does the cursor include the id as well as the timestamp?

    With only the timestamp, rows with an identical value could be skipped or repeated at a page boundary. The pair gives a total order.
  3. 3. What does CSV injection protection protect against?

    Cells starting with =, +, - or @ may be evaluated as formulas. Prefixing free text with a quote prevents that.
  4. 4. Which context is the natural choice inside a scheduled task handler?

    Jobs run without a logged-in user or sales channel. A CLI context says so explicitly.

Summary

  • A scheduled task is a definition plus a thin handler; the logic lives in a testable service.
  • Load only the associations the CSV needs and read orders in bounded pages.
  • Use keyset paging with a tie-breaker and save the cursor after every page.
  • Treat customer text as untrusted in CSV output, and pass the escape argument explicitly in modern PHP.
  • Read the target folder from plugin config, write to a temporary name and rename when finished.

Next, connect the shop to another system in Project: Syncing Stock from an ERP.