Download the PHP package schaefersoft/laravel-swiss-eid without Composer

Laravel Swiss eID

Laravel package for integrating the Swiss eID (swiyu) verification flow: builds the OpenID4VP 1.0 DCQL request, talks to a swiyu Verifier, persists the verification, handles the webhook callback and emits events. UI is intentionally left to you — the package only exposes data primitives (QR code SVG, deeplink, JSON status endpoint) so you can render in Blade, Livewire, Vue, React, or anything else.

5-Minute Quickstart

This package is a client for the swiyu Verifier — the Spring Boot service that speaks OpenID4VP to the wallet app. You need that verifier running before anything else works.

Step 1 — Start the verifier locally

The wallet app on the user's phone must be able to reach the verifier, so expose it through a public tunnel during local development:

Step 2 — Install the package

The installer publishes the config file and migration, prints all required .env variables, and optionally runs php artisan migrate.

Step 3 — Fill in .env

Step 4 — Start a verification and show the QR code

Step 5 — React to the result

Once the wallet has scanned the QR code the verifier fires the webhook. Listen to the event:

Or poll the status endpoint from the frontend:

Verify your setup

Validates all ENV variables, checks DID formats, and probes webhook reachability — in one pass.

Table of Contents

1. Prerequisites
   • PHP & Laravel versions
   • A running swiyu Verifier
   • Public reachability & webhook routing
   • Verifier signing key (PEM)
   • Accepted issuer DIDs
   • Swiss wallet app (for testing)
2. Installation
3. Configuration
4. Usage
   • Localising status labels
5. Database
6. Artisan Commands
   • swiss-eid:doctor
7. Testing
8. Troubleshooting
9. Contributing
10. License

Prerequisites

Before installing the package you need a few pieces of Swiss eID infrastructure in place. Each sub-section below covers exactly one requirement.

1. PHP & Laravel versions

The package itself runs on PHP 8.1+ (uses native enums, readonly DTOs and HasUuids). CI only tests against PHP 8.2+ because the Pest/PHPUnit dev toolchain no longer resolves on PHP 8.1. Consumers on PHP 8.1 can still install and use the package without issue.

2. A running swiyu Verifier

The Swiss eID ecosystem separates the relying party (your Laravel app) from the verifier service, a small Spring Boot process that speaks OpenID4VP to the wallet. This package is a client of that verifier — it does not implement the OpenID4VP protocol itself.

You need to run the official verifier locally (or host it somewhere) before this package can do anything:

• Repository: https://github.com/swiyu-admin-ch/swiyu-verifier
• Minimum version: 4.1.2 — required for the wallet security enforcements active since 2026-08-17 (CD-004) and the critical trust-validation fix (CD-008); 4.1.0/4.1.1 are vulnerable to an issuer-impersonation bypass.
• Default port: 8083
• Expected API base path: /management/api

A minimal docker-compose.yml typically looks like this (see the upstream repo for the full example):

Confirm the verifier is reachable:

3. Public reachability & webhook routing

The verification flow requires two network paths that both have to work:

1. Wallet → Verifier: the swiyu wallet on the user's phone fetches the presentation request from the verifier's public URL. During local development, expose the verifier via a tunnel (e.g. ngrok, Cloudflare Tunnel):

   Put that tunnel URL into your Laravel .env as SWISS_EID_VERIFIER_URL. The verifier itself also needs to know its public URL in its own configuration so it can embed it in the QR-code deeplink.

2. Verifier → Laravel webhook: when the wallet has responded, the verifier POSTs to your Laravel app. If both run in Docker, the verifier must be able to resolve your Laravel host. Two common options:

   • Run the verifier on the same Docker network as your Laravel app (e.g. the DDEV project network) and use the internal hostname in LARAVEL_WEBHOOK_URL, such as http://ddev-myproject-web/swiss-eid/webhook.
   • Or expose Laravel publicly too (another tunnel) and use that URL.

   The webhook is authenticated via a shared secret — the verifier sends X-Verifier-Api-Key: <key> and the package's middleware rejects everything else with 401.

4. Verifier signing key (PEM)

The verifier signs the presentation request it hands to the wallet. It expects an EC P-256 private key in PEM format. Generate one with OpenSSL:

When passing the private key through a .env file, keep the real newlines intact. Use a double-quoted multi-line value — not \n escape sequences, which the verifier will refuse to parse:

5. Accepted issuer DIDs

The Swiss eID beta trust infrastructure uses did:webvh: identifiers. did:tdw: is deprecated: there is no in-place migration, existing did:tdw DIDs are frozen for updates from ~October 2026, and re-onboarding with a new did:webvh DID via the swiyu Service Portal is required (see the onboarding cookbook). For a verification to succeed, the credential presented by the wallet must be issued by a DID that your verifier trusts. In practice you will list at least:

• Your own verifier DID (useful for self-issued test credentials).
• The official Beta-ID issuer DID if you want to accept real beta credentials.

Example for .env (comma-separated):

If you do not know the issuer DID of a credential, you can extract it from a decoded SD-JWT (the iss field) or from the verifier logs when it rejects a presentation with issuer_not_accepted.

Alternatively (or additionally) configure trust anchors — every DID with a trust statement from the anchor is accepted, without listing each issuer. The verifier requires at least one of the two to be non-empty:

6. Swiss wallet app (for testing)

To actually scan a QR code and complete a verification end-to-end you need the swiyu wallet app installed on a phone:

• iOS: App Store — search "swiyu"
• Android: Google Play — search "swiyu"

For beta/integration testing against trust-infra.swiyu-int.admin.ch, the app must be in the corresponding environment. Check the official documentation at https://www.eid.admin.ch for environment-specific instructions.

Installation

Run the installer:

This publishes the config file, the migration, prints the required .env variables, and (optionally) runs php artisan migrate.

Manual alternative:

Configuration

All settings live in config/swiss-eid.php and can be overridden with environment variables:

Usage

Starting a verification

Use the SwissEid facade's fluent builder. Each call returns the same manager instance, so you can chain freely. create() persists the record and returns a PendingVerification DTO.

Every SwissEid::verify() call returns a new VerificationRequest, just like Http:: returns a new pending request. Builder methods called directly on the facade (e.g. SwissEid::ageOver18()) start a new request as well, so no state leaks between requests, jobs or Octane workers.

The returned $pending has:

Requesting specific fields

Use the CredentialField enum (preferred) or plain field-name strings:

Available cases: AgeOver18, AgeOver16, GivenName, FamilyName, DateOfBirth (resolves to the JSON key birth_date), Nationality, PlaceOfBirth, Gender.

You can also pass a single field by name, dotted path or legacy JSONPath. All forms are normalised to a DCQL claim path:

Overriding credential type / accepted issuers per request

Verification purpose (vqPS)

The productive e-ID requires verifiers to register their data queries and purpose at the trust infrastructure. Set it globally via the verification_purpose config key or per request:

Presenting to the user

The package is UI-agnostic. Render the primitives in any frontend:

The polling endpoint returns JSON:

label is resolved via Laravel's translation system and automatically respects App::getLocale(). See Localising status labels below for details.

Poll every 2–3 seconds until is_terminal === true. If the TTL has passed, the endpoint will also flip pending → expired on the first call after expiry and dispatch the VerificationExpired event.

Localising status labels

The polling endpoint's label field and VerificationState::label() are driven by Laravel's translation system under the swiss-eid::states namespace. The package ships translations for German (de), French (fr), Italian (it), and English (en).

The active locale (App::getLocale()) is used automatically — no configuration needed. If the locale falls through to a string that does not exist in the package's files (e.g. es), Laravel's fallback locale applies next, and then the translation key itself is returned as-is.

Customising or adding languages

Publish the translation files once:

This copies the four files to lang/vendor/swiss-eid/{de,en,fr,it}/states.php. Published files take priority over the package originals. Edit them freely:

To support an additional language, add a new locale directory alongside the existing ones — e.g. lang/vendor/swiss-eid/es/states.php with Spanish labels.

Using label() directly

VerificationState::label() resolves the same translation keys, so it works anywhere — not just in the polling JSON:

Handling the webhook

The webhook route (POST /swiss-eid/webhook by default) is registered automatically by the package's service provider. It:

1. Validates the X-Verifier-Api-Key header via middleware.
2. Reads the verification_id from the payload.
3. Calls the verifier's GET endpoint to fetch the full result.
4. Writes state, credential_data (encrypted at rest) and webhook_received_at to the DB.
5. Dispatches VerificationCompleted or VerificationFailed.

You do not register this route yourself. Just make sure:

• SWISS_EID_WEBHOOK_API_KEY matches what the verifier sends.
• Your firewall / reverse proxy allows the verifier to reach that path.
• CSRF is not a concern — the route lives in the api middleware group.

Retrieving results

VerificationResult methods:

If the ID is not found a VerificationNotFoundException is thrown.

Refreshing without the webhook

getVerification() only reads your database. If the webhook cannot reach your app (local development, firewall, lost retry), pull the state from the verifier instead:

refresh() updates the record and dispatches the same events as the webhook. Terminal verifications are returned without contacting the verifier. To refresh all pending verifications at once, run or schedule php artisan swiss-eid:refresh.

Events

Listen in your EventServiceProvider or with #[AsEventListener]:

Each event carries a single $verification property of type EidVerification (the Eloquent model). Use its toResult() method if you want the DTO view.

Database

The package ships a single table (default name eid_verifications) with:

Useful Eloquent scopes on EidVerification:

Override the table name with SWISS_EID_TABLE_NAME in .env. The migration and the model both read from config('swiss-eid.table_name'), so renaming is a single-line change.

Artisan Commands

Schedule the cleanup in App\Console\Kernel (or routes/console.php on Laravel 11+):

swiss-eid:doctor

A self-contained diagnostic that works through every aspect of the configuration in one pass and exits with a non-zero code if any check fails — useful in CI pipelines or as a post-deploy smoke test.

Checks performed

Exit codes

Example output

Testing

Use the built-in SwissEidFake to avoid real HTTP calls in your tests:

Run the package's own test suite:

Troubleshooting

Quick sanity checks:

Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/my-feature.
3. Run composer test and composer analyse — both must pass.
4. Open a Pull Request. Conventional-commit messages are appreciated; they drive the automated release workflow.

License

MIT. See LICENSE for details.