Real Name Authentication Bundle Laravel Package

Getting Started

composer require tourze/real-name-authentication-bundle

0.0.1 is the initial tagged release and ships with nothing but a changelog link — there is no README-level API documentation, no upgrade guide, and no stability guarantee. Budget your first hour for reading source, not for wiring it into a feature.

Where to look first, in order:

1. The contract. Tourze bundles of this family are interface-first; expect something like Tourze\RealNameAuthenticationBundle\RealNameAuthenticationInterface with a single authenticate(string $name, string $idNumber): bool-style method. This interface is the only surface you should couple your application to.
2. The shipped implementation(s). Packages like this usually ship a stub or null-object (always-true, always-throws, or a sandbox provider) that is meant to be swapped for a real KYC vendor.
3. The DI wiring. Look for Resources/config/services.yaml or a *Bundle class. If all you find is Symfony service config, there is no Laravel service provider and you will bind everything yourself.
4. composer.json of the package. Check whether it drags in symfony/http-kernel, Doctrine, or an HTTP client. composer show tourze/real-name-authentication-bundle --tree before you commit to it.

First use case: gate a single high-value action — payout, withdrawal, account upgrade, marketplace seller onboarding — behind a one-time name + ID-number check. Do not model your registration flow around it yet.

// app/Providers/AppServiceProvider.php
public function register(): void
{
    $this->app->bind(
        \Tourze\RealNameAuthenticationBundle\RealNameAuthenticationInterface::class,
        \App\Services\RealName\VendorRealNameAuthenticator::class,
    );
}

Implementation Patterns

Wrap the interface, never call it from controllers. The package is an abstraction seam, not a service. Put a thin application-level service in front of it so you can add caching, auditing, and retries without touching vendor code.

final class RealNameVerifier
{
    public function __construct(
        private readonly RealNameAuthenticationInterface $authenticator,
    ) {}

    public function verify(User $user, string $realName, string $idNumber): VerificationResult
    {
        $result = $this->authenticator->authenticate($realName, $idNumber);

        RealNameRecord::create([
            'user_id'    => $user->id,
            'real_name'  => $realName,          // encrypt this cast
            'id_number'  => $idNumber,          // encrypt this cast
            'passed'     => $result,
            'checked_at' => now(),
        ]);

        return new VerificationResult($result);
    }
}

Store your own records. If the bundle ships Doctrine entities, do not try to make them coexist with Eloquent. Keep an real_name_records table of your own — you need it for audit trail, dispute handling, and rate limiting anyway, and a future 0.x bump that reshapes the vendor's entity won't take your schema with it.

Queue it. Real-name checks hit a third-party network and are the slowest thing in an onboarding request. Dispatch a job, return 202, and surface status through a verified_at timestamp or a dedicated status column on users.

VerifyRealName::dispatch($user, $realName, $encryptedIdNumber)
    ->onQueue('verification');

Fire domain events (RealNameVerified, RealNameRejected) from the job rather than from the vendor callback — it keeps the package at arm's length and gives you a single place to add telemetry.

Gate features with middleware, not scattered ifs. Once verified_at is set, a EnsureRealNameVerified middleware plus a Gate::define('payout', ...) covers every call site.

Fake it in tests. Bind a deterministic fake to the interface in TestCase::setUp() so the suite never touches the real provider:

$this->app->bind(RealNameAuthenticationInterface::class, fn () => new class implements RealNameAuthenticationInterface {
    public function authenticate(string $name, string $idNumber): bool
    {
        return $idNumber === '110101199003071234';
    }
});

Keep the provider behind your own port. If you anticipate switching vendors, define App\Contracts\RealNameProvider and write a one-class adapter that implements both your contract and the Tourze interface. The day the bundle is abandoned (a real risk at 0.0.1), you delete the adapter and nothing else.

Gotchas and Tips

• "Bundle" is a Symfony word. This package very likely targets Symfony's DI container. Laravel's package auto-discovery only works for packages that declare extra.laravel.providers, which this almost certainly does not. Expect to bind the interface manually — and expect the shipped service definitions to be inert under Laravel.
• Pin the exact version. "tourze/real-name-authentication-bundle": "0.0.1" — not ^0.0.1. At 0.x, semver explicitly allows breaking changes on any minor bump, and this vendor moves fast. Treat every upgrade as a code review.
• No changelog means no upgrade signal. Until the project starts writing release notes, diff the src/ directory between tags before bumping. composer update --dry-run will not tell you that a method signature changed.
• PII handling is on you, not the package. ID numbers are among the most sensitive data you can store. Use an encrypted cast for id_number and real_name, never log the raw payload, never put an ID number in a queue payload or an exception message, and mask it (110101********1234) in any admin UI. If the package logs request bodies internally, that's a blocker — check its HTTP client usage.
• Assume the result can be null or throw. Stub implementations in early-stage bundles frequently return null, throw LogicException('not implemented'), or return true unconditionally. Do not treat a truthy return as proof of identity until you have read the implementation you actually bound.
• Handle provider outages as "unknown", not "failed". A network error from the vendor is not a rejected identity. Distinguish three states — passed, rejected, errored — or you will permanently lock out legitimate users during a provider incident.
• Idempotency and rate limits. Hash the incoming (name, ID) pair for a short-lived cache key and return the prior result within, say, 24 hours. Vendors bill per call and many throttle aggressively; a user double-tapping "verify" should not cost you two requests.
• Encryption key rotation will bite you. Encrypted casts are tied to APP_KEY. Rotating it makes every historical id_number unreadable. If you need long-term auditability, use a dedicated key or store a salted hash of the ID number alongside the encrypted value.
• Extension points to watch for in 0.x: the interface itself (stable-ish), any RealNameAuthenticationException hierarchy (catch the base class, not the leaves), and any configuration tree. Bind to interfaces and catch base exceptions so a 0.0.2 refactor of leaf classes doesn't break you.
• Have an exit plan. A single-maintainer 0.0.1 package in a compliance-critical path is a supply-chain risk. The wrapper-service pattern above keeps the blast radius to one file plus one composer.json line.