php-dp

An independent PHP FFI wrapper for the DigitalPersona / Crossmatch U.are.U fingerprint SDK (libdpfj.so / libdpfpdd.so) on Linux x64: feature extraction, multi-sample enrollment fusion, and 1:1 verification/compare — all from plain PHP, no C extension to compile.

Not affiliated with Crossmatch, DigitalPersona, or HID Global. This package ships only original PHP code and does not bundle, vendor, or redistribute any part of the vendor SDK — see NOTICE.md.

Why this exists

The vendor SDK's own docs are Windows-first and light on exact native calling conventions for Linux. This package's NativeMethods bindings were cross-checked directly against DPUruNet.dll (the official .NET wrapper's decompiled source) to get argument layouts and the init sequence right — including a couple of easy-to-miss gotchas that otherwise produce silent memory corruption or a confusing DP_NOT_IMPLEMENTED error. See docs/troubleshooting.md for the full story.

Features

• Extract an FMD (fingerprint minutiae template) from a raw grayscale sample or a PNG/JPEG image.
• Fuse multiple samples of the same finger into one high-quality enrollment template (dpfj_start_enrollment / add_to_enrollment / create_enrollment_fmd, correctly handling the native MORE_DATA signal).
• 1:1 verification and raw FMD-to-FMD comparison with a configurable target False Accept Rate.
• Typed ResultCode / FmdFormat / EngineType enums and a SDKException that carries the typed result code — no magic numbers.
• A low-level API mirroring DPUruNet.dll's static classes 1:1, if you need more control than the high-level Fmd facade.

What this is not

• Not a live-capture library — it doesn't talk to a USB reader directly. Feed it pixel data captured elsewhere (a WebSDK client, a small capture daemon, whatever already gets bytes off your scanner).
• Not cross-platform — Linux x86_64 only. The vendor doesn't ship a macOS SDK for these readers, and Windows uses a completely different binary format (.dll via DPUruNet.dll/P-Invoke) outside this package's scope.

Requirements

• PHP ^8.1 with ext-ffi enabled.
• ext-gd, only if you use the image-based helpers.
• The DigitalPersona / Crossmatch U.are.U SDK for Linux, installed separately by you — see docs/installation.md and the full setup guide at Installation SDK DigitalPersona.

Install

composer require banguncode/php-dp

Then set up the vendor SDK (not bundled — see NOTICE.md):

composer install-sdk -- --sdk-dir /path/to/extracted/vendor/sdk/sdk

See docs/installation.md for what that does and the manual steps if you'd rather run them yourself.

Quick start

use Dp\Fmd;
use Dp\RawSample;

$fmd = new Fmd(); // loads libdpfj.so / libdpfpdd.so, selects the matcher engine

// Enroll from 4 samples of the same finger
$raws = [];
$width = $height = $dpi = 0;
foreach ($fourWebSdkRawJsonSamples as $json) {
    $sample = RawSample::fromWebSdkJson($json);
    $raws[]  = $sample['raw'];
    $width   = $sample['width'];
    $height  = $sample['height'];
    $dpi     = $sample['dpi'];
}
$templateBase64 = $fmd->enrollFourToBase64($raws, $width, $height, $dpi);

// Later: verify a fresh sample against the stored template
$probe = RawSample::fromWebSdkJson($probeJson);
$result = $fmd->verify(
    $probe['raw'], $probe['width'], $probe['height'],
    base64_decode($templateBase64), $probe['dpi']
);

var_dump($result); // ['match' => bool, 'score' => int, 'threshold' => int]

See docs/usage.md for more (image-based enrollment, the lower-level API, error handling).

Documentation

• docs/installation.md — full setup, including the vendor SDK itself.
• docs/usage.md — code examples for every workflow.
• docs/api-reference.md — every public class/method.
• docs/troubleshooting.md — the errors you will actually hit, and why.

Testing

composer install
composer test

Most tests are pure-PHP unit tests (no SDK required). A small integration suite is skipped by default; enable it with a real SDK installed:

DP_TEST_DPFJ_LIB=/lib/libdpfj.so DP_TEST_DPFPDD_LIB=/lib/libdpfpdd.so composer test

License

MIT for the code in this repository — see LICENSE. This does not extend to the DigitalPersona/Crossmatch SDK binaries themselves; see NOTICE.md.