README

Reusable camera- and file-based barcode scanning for other extensions. The intended use cases are media archiving (books, DVDs, CDs) and household management (recording purchases).

Requirements

TYPO3: 13.4 or 14.3
PHP: 8.3 or newer
Live camera scanning requires a secure context (HTTPS or localhost)
Browser: getUserMedia for live camera scanning. The native BarcodeDetector is used where available; the fallback decodes with the vendored zxing-wasm reader (about 1 MB wasm binary, loaded on first use)

Installation

composer require psbits/scanner

Integration

Add the scanner partials to your view configuration:

plugin.tx_<your_extension> {
    view {
        partialRootPaths.20 = EXT:scanner/Resources/Private/Partials
    }
}

Render the partial in a Fluid template:
```
<f:render partial="Scanner" />
```

Listen to the scanner events on the root element (data-psbits-scanner). Scan results are submitted to the API automatically unless disabled:

document
    .querySelector('[data-psbits-scanner]')
    .addEventListener('psbits-scanner:scan', (event) => {
        // event.detail = { content, format, source, clientTimestamp, meta }
    });

Events emitted by the component:

psbits-scanner:ready
psbits-scanner:capabilities
psbits-scanner:permission
psbits-scanner:scan
psbits-scanner:submitted
psbits-scanner:error
psbits-scanner:stopped

API contract (v1)

All responses share this envelope:

{
  "success": true,
  "data": {},
  "error": null
}

For errors:

{
  "success": false,
  "data": null,
  "error": {
    "code": "validation_failed",
    "message": "...",
    "details": {}
  }
}

`GET /scanner/api/v1/health`

Health endpoint.

`GET /scanner/api/v1/capabilities`

Returns supported formats, modes and endpoint references.

`POST /scanner/api/v1/result`

Accepts scan results:

{
  "content": "9780201379624",
  "format": "ean_13",
  "source": "camera",
  "clientTimestamp": "2026-01-01T12:00:00+00:00",
  "meta": {}
}

content is required (1–1024 characters)
format is required and must be one of the supported formats
source is either camera or image (defaults to camera)
clientTimestamp is optional, any date/time string the server can parse
meta is optional, any JSON object

Supported formats:

ean_13
ean_8
upc_a
upc_e
code_128
code_39
itf
codabar

Security and privacy

Live camera mode only works in secure contexts (HTTPS/localhost).
The frontend checks browser support and permission state and emits explicit events.
The backend validates incoming result payloads and does not persist scan contents by default.

Development

composer install
composer qa

composer qa fixes everything that can be fixed automatically and afterwards runs all linters and the static analysis. The same checks run in the CI GitHub Actions workflow and in the pre-commit hook that is installed by composer install.

The workflow also runs a support matrix that checks the supported TYPO3 and PHP combinations still resolve their dependencies, and publishes the extension to TER when a semver tag is pushed. Publishing requires the TYPO3_API_TOKEN repository secret.

psbits / scanner

Package info

Security

Statistics