PHPackages                             filecheck/filecheck-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. filecheck/filecheck-php

ActiveLibrary[File & Storage](/categories/file-storage)

filecheck/filecheck-php
=======================

Filecheck server SDK for PHP — jobs, uploads, webhooks, and server-side job verification

v0.1.0(today)01↑2900%MITPHPPHP >=8.1CI passing

Since Jul 30Pushed todayCompare

[ Source](https://github.com/PrintApp/filecheck-php)[ Packagist](https://packagist.org/packages/filecheck/filecheck-php)[ Docs](https://filecheck.io)[ RSS](/packages/filecheck-filecheck-php/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (2)Used By (0)

filecheck/filecheck-php
=======================

[](#filecheckfilecheck-php)

Filecheck server SDK for PHP 8.1+ — jobs, uploads, webhooks, and the server-side job verification your fulfillment path must run before trusting a browser-submitted job id. Mirrors [`filecheck-node`](https://github.com/PrintApp/filecheck-integrations/tree/main/packages/node)method-for-method.

HTTP via any PSR-18 client (auto-discovered with `php-http/discovery`, or injected), with a bundled cURL fallback so the package works with zero extra dependencies.

Install
-------

[](#install)

```
composer require filecheck/filecheck-php
```

Quickstart — verify a job in 5 lines
------------------------------------

[](#quickstart--verify-a-job-in-5-lines)

```
$fc = new \Filecheck\FilecheckClient(getenv('FILECHECK_SECRET_KEY'));

$result = $fc->jobs->verify($_POST['filecheck_job_id'], ['workflow_id' => 'wf_…']);
if (!$result->ok) {
    http_response_code(422);
    exit("Files not accepted ({$result->reason})");
}
// fulfil the order; $result->state is 'ready' or 'partial' (warnings accepted by policy)
```

**Laravel**

```
// AppServiceProvider
$this->app->singleton(FilecheckClient::class,
    fn () => new FilecheckClient(config('services.filecheck.secret')));

// CheckoutController
public function store(Request $request, FilecheckClient $fc)
{
    $result = $fc->jobs->verify($request->input('filecheck_job_id'), ['workflow_id' => 'wf_…']);
    abort_unless($result->ok, 422, "Files not accepted ({$result->reason})");
    // …
}
```

`verify()` is the encoded docs checklist: the job must be **terminal**(`status ∈ done|skipped|error`), **proceedable** (the browser Element's `canProceed` equivalent — `ready`/`partial` after applying the job's `onFail` policy), and — with `workflow_id` — must have run the expected workflow. Options: `policy` (override the resolved onFail), `strict` (fail closed on `status: 'error'` jobs).

Uploading + processing files
----------------------------

[](#uploading--processing-files)

```
// Two-leg upload (presign + S3) in one call → fileRef
$upload = $fc->uploads->create('/tmp/artwork.pdf', ['mime_type' => 'application/pdf']);

// Validate against PDF/X profiles — waits for the result by default
$res = $fc->jobs->validate(['sources' => [['fileRef' => $upload->fileRef, 'profile' => ['1b']]]]);
echo $res->job->outcome;

// Preflight + autofix — async by default; 'wait' => true to block until terminal
$fixed = $fc->jobs->fix([
    'sources' => [['fileRef' => $upload->fileRef, 'profileId' => 'default']],
    'wait' => true,
]);
```

### The `wait` option

[](#the-wait-option)

The raw API inconsistently flips sync/async with `sync: true` (create/preflight/previews/fix — async default) and `async: true` (validate/optimize — sync default). The SDK normalizes all six behind `'wait'` / `'wait_timeout'` (seconds, default 120) with defaults matching each endpoint. When the server's ~27 s wait budget expires (HTTP 202), the SDK keeps polling `GET /jobs/{id}`client-side. Every submit returns a `JobResult { job, pending }`.

Blocking waits tie up the PHP worker — mind FPM time limits; prefer webhooks for long jobs.

API surface
-----------

[](#api-surface)

MethodEndpoint`$fc->jobs->create($params)``POST /jobs``$fc->jobs->preflight/previews/fix/validate/optimize($params)``POST /jobs/…` sugar endpoints`$fc->jobs->retrieve($id)``GET /jobs/{id}` → `Data\Job``$fc->jobs->retrieveRuns($id)``GET /jobs/{id}?expand=runs` → `Data\JobRuns``$fc->jobs->list(['limit', 'next_key'])` / `->iterate()``GET /jobs` (+ auto-pagination)`$fc->jobs->delete($id)``DELETE /jobs/{id}``$fc->jobs->waitUntilTerminal($id, $opts)`polling helper`$fc->jobs->verify($id, $opts)`fulfillment gate → `Data\VerifyResult``$fc->uploads->create($pathOrBytesOrStream, $opts)``POST /uploads` + S3 leg → `Data\Upload``$fc->orders->create($orderId, $params)``POST /orders/{id}``$fc->workflows/connectors/rules/profiles/optimizePresets->all()/->get($id)`read-only library`Webhooks::constructEvent($rawBody, $sig, $secret, $opts)`webhook parsing/verificationClient options: `new FilecheckClient('sk_…', ['base_url', 'timeout' /* seconds */, 'max_retries', 'http_client' /* PSR-18 */, 'transport'])`. Secret keys are `sk_…`; passing a publishable `pk_…` key throws immediately. Keys are never echoed in full — masked to `sk_…abc4`.

Responses are readonly value objects (`Data\Job`, `Data\Task`, `Data\Step`, `Data\JobRuns`, `Data\VerifyResult`, …) that keep the raw payload in `->raw` for forward compatibility.

Webhooks
--------

[](#webhooks)

> **Signing status:** Filecheck's per-job `job.completed` webhooks are delivered **unsigned**today; the signature scheme is not finalized. `constructEvent` is structured so verification becomes the default without breaking changes once it ships. Until then, `['verify' => false]`is the explicit, temporary escape hatch.

```
$event = \Filecheck\Webhook\Webhooks::constructEvent(
    file_get_contents('php://input'),          // ALWAYS the raw body
    $_SERVER['HTTP_X_FILECHECK_SIGNATURE'] ?? null,
    null,
    ['verify' => false], // TEMPORARY until Filecheck ships webhook signing
);
if ($event->type === \Filecheck\Data\WebhookEvent::TYPE_JOB_COMPLETED) {
    // $event->payload: id, status, outcome, taskIds, tasks[], finalized, …
}
```

In Laravel, exempt the route from CSRF and use `$request->getContent()` for the raw body. Verification uses `hash_equals()` (constant-time compare).

Errors & retries
--------------------

[](#errors--retries)

Typed exceptions in `Filecheck\Exception`: `AuthenticationException` (401/403 — including API Gateway's bare `{"message":"Forbidden"}` shape), `InvalidRequestException` (400), `NotFoundException` (404), `RateLimitException` (429), `ApiException` (5xx / non-JSON bodies), `ConnectionException` (network/timeout), `WebhookSignatureException`. The API has no machine-readable error codes — branch on exception class, not message text.

Retries: idempotent GETs only (default 2×, full-jitter backoff, `Retry-After` honored) on 429/502/503/504 and connection failures. **POSTs are never auto-retried** — the API has no idempotency keys, and a duplicated `POST /jobs` creates and bills a second job.

Development
-----------

[](#development)

```
composer install
composer test       # PHPUnit
composer phpstan    # level 8
```

Test fixtures in `fixtures/` are a synced copy of the shared fixtures in the `filecheck-integrations` monorepo, so this SDK and `filecheck` assert against identical payloads.

License
-------

[](#license)

MIT

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cc5c131d41571234fb5c7d98833e2cf9478b86f2798184407d946564bac36b5b?d=identicon)[filecheck](/maintainers/filecheck)

---

Top Contributors

[![iocoker](https://avatars.githubusercontent.com/u/81635623?v=4)](https://github.com/iocoker "iocoker (3 commits)")

---

Tags

apipdfvalidationsdkuploadpreflightfilecheck

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/filecheck-filecheck-php/health.svg)

```
[![Health](https://phpackages.com/badges/filecheck-filecheck-php/health.svg)](https://phpackages.com/packages/filecheck-filecheck-php)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k17](/packages/tempest-framework)[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k543.5M2.7k](/packages/aws-aws-sdk-php)[cakephp/cakephp

The CakePHP framework

8.8k19.5M1.8k](/packages/cakephp-cakephp)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

36789.4k2](/packages/telnyx-telnyx-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60316.0M89](/packages/mollie-mollie-api-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)