Download the PHP package crazy-goat/scanmephp without Composer

ScanMePHP

The fastest pure PHP QR code generator with optional native C++ acceleration.

Generate QR codes in PHP without dependencies — then go 100× faster with a single C++ library. Zero bloat, maximum speed, production-ready.

QR encoding algorithms are based on Nayuki's QR Code generator.

Why ScanMePHP?

🚀 Blazing Fast — 3-Tier Performance

• Fast pure PHP: bitwise mask selection and packed Reed–Solomon — a v10 code in ~60 µs with the JIT, no extensions needed
• Native C++ via FFI / extension: another 6–8× (a v10 code in ~8–9 µs); SIMD mask selection with runtime AVX2/AVX-512 dispatch on x86-64, NEON on arm64
• 64-bit Optimized: 2× faster with int-pair bit packing (no extensions needed)
• Portable Fallback: Works on any PHP 8.2+, 32-bit or 64-bit

Auto-selects the fastest encoder available — no configuration needed.

📦 Zero Dependencies

• No Composer packages to install
• No GD, Imagick, or extensions required
• Single composer require, instant QR codes

🎨 8 Output Formats SVG, PNG (pure PHP, 1-bit), HTML (div/table), ASCII (3 styles). Works in terminals, browsers, emails, and print.

🔧 Full QR Spec Support

• All versions v1–v40 (17 to 2953 bytes)
• All error correction levels (L/M/Q/H)
• Custom styling, colors, labels, dark mode

Features

• Zero dependencies — no external packages, no PHP extensions required
• 8 built-in renderers — SVG, PNG, HTML (div/table), ASCII (full/half/simple blocks)
• All QR versions — v1–v40, all error correction levels (L/M/Q/H)
• High performance — pure PHP encodes v1 in ~15 µs / v10 in ~60 µs (JIT); native C++ extension/FFI adds another 6–8×
• Customizable — module styles, colors, labels, dark mode, margins
• Type-safe — strict types, enums, readonly properties, PHP 8.2+ idioms

Installation

Binary Auto-Download

When you install or update the package via Composer, the library will automatically:

1. Detect your platform (Linux glibc/musl, macOS Intel/ARM)
2. Try to download and install the PHP extension (scanmeqr) — fastest option (190–360× faster)
3. Fall back to FFI library if extension is not available — 90–130× faster
4. Use pure PHP encoder as final fallback — works everywhere

If no binary matches your platform — arm64 Linux, an unusual PHP build — the extension can be compiled on the spot with PIE: pie install crazy-goat/qrcode-ext.

Checksum Verification

A downloaded binary is hashed with SHA-256 right after the transfer, compared with the checksum the installer expects, and deleted again when it does not match. A binary that is already in vendor/crazy-goat/scanmephp/{ext,ffi}-binaries/ is checked the same way whenever the plugin runs, that is when ScanMePHP is installed or updated — not on a plain composer install that leaves the installed version alone. Verification is fail-closed: without a checksum for the requested version and binary, nothing is kept and the plugin prints which binary it wanted.

Checksums are read from extra.scanmephp.checksums in your composer.json — the installer never trusts a digest it fetched next to the binary it is checking. Every release publishes the digests of all its binaries in checksums.txt, so pinning the one for your platform is a copy-paste. That file exists from the first release that ships this feature; earlier releases have none, so there is nothing to copy from them and the pure PHP encoder is used until the release you install has one.

Copy the 64-character digest only. A whole sha256sum line pasted as the value is a pin that never matches, so every install deletes the binary and then refuses to download it again.

The same file verifies a manual download; check just what you have with sha256sum -c --ignore-missing checksums.txt (Linux) or shasum -a 256 -c checksums.txt (macOS).

Until you pin a digest, composer install installs no native code and the pure PHP encoder is used.

PHP Extension Installation (Recommended)

The PHP extension provides the best performance. The Composer plugin will attempt to download it automatically.

Auto-Download

During composer install or composer update, the plugin will:

1. Check if the scanmeqr extension is already loaded
2. Download the appropriate prebuilt binary for your platform
3. Provide instructions to enable it in php.ini

Manual Installation

1. Download the appropriate binary from GitHub Releases:

Note: Binaries are built for specific PHP versions due to ABI compatibility. Make sure to download the binary matching your PHP version (check with php -v).

2. Copy to your PHP extensions directory:

3. Add to your php.ini:

4. Restart your web server or PHP-FPM:

5. Verify installation:

Installing with PIE

The extension is published as a PIE package, which builds it from source for whatever PHP you are running — including platforms no prebuilt binary covers, such as arm64 Linux:

Both halves are needed: the extension builds a CrazyGoat\ScanMePHP\Matrix and can only throw without the library loaded. Building needs a C++20 compiler and takes a few seconds; there is nothing else to install, since the C++ core is compiled into the extension rather than linked against libscanme_qr.

crazy-goat/qrcode-ext is generated from php-ext/ and clib/ by bin/build-ext-mirror.sh — issues and pull requests belong in this repository.

Building from Source

Requirements:

• PHP 8.2+ with php-dev/phpize
• C++20 compiler (GCC 10+ or Clang 12+)
• Make

Then add extension=scanmeqr.so to your php.ini.

CMake is only needed for the FFI library and the C++ test suite; the extension does not use it.

FFI Library Installation

If the PHP extension is not available, the plugin will download the FFI library instead.

Requirements for Auto-Download

• FFI extension (extension=ffi in php.ini)
• cURL extension for downloading
• Write permissions to ffi-binaries/ directory in your project

Manual Binary Installation

If auto-download doesn't work, you can manually download binaries from the GitHub releases page and place them in your project directory.

Prebuilt FFI library binaries are available for:

Windows: no prebuilt binaries are published. ScanMePHP still works — it falls back to the pure-PHP encoder, which needs no extension and no FFI. For native speed on Windows, build clib/ from source with MSVC and point FfiEncoder at the resulting scanme_qr.dll.

Quick Start

Renderers

ScanMePHP ships with 8 renderers. Each implements RendererInterface and can be passed as the engine parameter.

ASCII — FullBlocksRenderer (default)

Example: qrcode_fullblocks.txt

ASCII — HalfBlocksRenderer

Example: qrcode_halfblocks.txt

Compact output — two rows per character using ▀▄█ half-block characters.

ASCII — SimpleRenderer

Example: qrcode_simple.txt

Uses ● dots. Works in terminals without full Unicode block support.

SVG — SvgRenderer

Examples: qrcode_with_label.svg

PNG — PngRenderer

Examples: qrcode_high_ecc.png

Generates valid PNG files in pure PHP — no GD, no Imagick, no external libraries. Black and white only, 1-bit monochrome. Ideal for email attachments, API responses, and print. Repeated pixel rows are stored with the PNG Up filter, so the default zlib level 1 already gives ~2 KB files in ~0.1 ms; pass compressionLevel: 6 for the smallest output.

Note: Labels are not supported in PNG output (no font engine). Passing a label will throw a RenderException.

HTML — HtmlDivRenderer

Examples: qrcode_div_label.html

Renders QR as a <div> flexbox grid with inline styles. No external CSS needed.

HTML — HtmlTableRenderer

Examples: qrcode_table_label.html

Same as above but uses <table> with <td> elements.

Configuration

All options are set via QRCodeConfig:

Dark Mode (Inverted)

For SVG/HTML renderers, set explicit colors:

Output Methods

Custom Renderer

Implement RendererInterface:

Performance

ScanMePHP includes four encoder implementations. QRCode auto-selects the fastest available:

Capacity (Byte Mode)

Maximum data length for URL/text encoding (Byte mode) at different QR versions:

Note: FastEncoder supports up to v27 (1465 bytes max). For larger data, the portable Encoder's v28–v40 pipeline is automatically used.

Benchmark Results

Measured on PHP 8.5 (opcache.jit=tracing) / Apple M-series, 500 iterations per case, median latency:

Before the 2026-08 optimisation pass pure PHP took 0.425 ms (v1) and 3.2 ms (v10); the pure-PHP encoders are now 20–50× faster, so the native tiers matter mostly for high-volume generation. Without the JIT pure PHP is ~4× slower.

The C++ library alone encodes v1 in ~1.5 µs, v10 in ~6 µs and v40 in ~80 µs (clib/bench/scanme_bench); the rest is the PHP boundary.

All four encoders produce identical, spec-compliant QR codes verified against nayuki's reference implementation.

Run the benchmark yourself:

See BENCHMARK.md for full results, the C++-only benchmark and a description of the SIMD mask-selection kernel.

Building the C++ Library (optional)

The native C++ encoder is optional — ScanMePHP works without it. To enable FfiEncoder:

Then pass the library path when creating the encoder:

Or let QRCode auto-detect it (looks for clib/build/libscanme_qr.so in the project root).

Prebuilt Binaries

Prebuilt binaries are available from GitHub Releases. Download the appropriate binary for your platform:

PHP Extension Binaries (Recommended)

FFI Library Binaries

Windows: no prebuilt binaries are published. ScanMePHP still works — it falls back to the pure-PHP encoder, which needs no extension and no FFI. For native speed on Windows, build clib/ from source with MSVC and point FfiEncoder at the resulting scanme_qr.dll.

Place the downloaded binary in your project directory. The FfiEncoder will automatically detect and load it.

Requirements

• PHP >= 8.2
• No extensions required
• No external dependencies
• Optional: C++20 compiler + CMake for native FFI encoder

Testing

Examples

See the examples/ directory. Run any example:

Generated output files are saved to examples/generated-assets/.

License

MIT — see LICENSE.

Contributing

See CONTRIBUTING.md.