Tckimlik Laravel Package

Product Decisions This Supports

• Turkish-market onboarding and KYC: Every flow that captures a national ID for users in Turkey (sign-up, checkout, marketplace seller onboarding, wallet/PSP registration, HR/payroll intake) needs TCKN validation. This package turns that from an ad-hoc regex into a dependable rule.
• Fraud and fake-account reduction: The TCKN checksum algorithm rejects syntactically plausible but invalid numbers, cutting junk registrations and reducing downstream cost in SMS/OTP verification and manual review queues.
• Build vs. buy: The alternative is writing the 11-digit modulo algorithm in-house plus a SOAP/HTTP integration to the NVI (Turkish civil registry) service for name + birth-year verification. That is a few days of work plus an ongoing maintenance surface for a government endpoint. This package is a small, single-purpose dependency that removes that line item from the roadmap.
• Feature scope decision: The v1.2.0 change (routing trUpper through Transliterator) is a correctness fix in Turkish case folding, which matters specifically where user-entered names are compared against registry data. It signals the package is actively maintained and handles the Turkish i/İ casing trap that silently breaks naive strtoupper() comparisons — a real source of false mismatches in verification flows.
• Compliance positioning: Local ID validation is a cheap, defensible control to cite in a data-quality or anti-abuse posture, even when full identity verification is outsourced to a licensed KYC vendor.
• Not a decision driver: Full identity proofing, document liveness, or sanctions screening. Treat this as an input-validation and light-verification layer, not a compliance product.

When to Consider This Package

Adopt when:

• You ship a Laravel application (or can accept a Laravel service provider/facade) with any user base in Turkey.
• You need a validation rule for TCKN in form requests, plus optional name/surname/birth-year verification against the NVI service.
• You are on a supported PHP/Laravel version and are comfortable with a small, low-surface third-party dependency.
• You want Turkish-aware string normalisation for name matching without hand-rolling locale handling — the point of the v1.2.0 fix.

Look elsewhere or build in-house when:

• You only need the offline checksum. It is a short, well-documented algorithm; a private helper avoids the dependency entirely and is trivially testable.
• You are not on Laravel, or you need a framework-agnostic core you can drop into Symfony, a queue worker, or a Go/Node service.
• You need real identity verification: document capture, liveness, face match, or registry data beyond ID + name + birth year. Use a licensed KYC provider and keep this as a pre-filter.
• You expect high verification volume against the government endpoint and need batching, caching, retry policy, or circuit breaking. Plan to wrap the call in your own job/queue layer with timeouts, since external-service behaviour is outside this package's scope.
• Your compliance team requires a vendor with an SLA, DPA, and audit trail. An open-source package with a single recent contributor does not satisfy that; it can still be used internally, but you own the risk.
• You are pinned to EOL PHP/Laravel versions and cannot track the package's supported matrix.

Watch items before adopting: confirm the maintainer bus factor (v1.2.0 is the first contribution from a new contributor, which is a positive signal but also indicates a very small team), check whether tests cover the new Transliterator path, and verify the Transliterator extension is available in your runtime — it is a PHP intl extension requirement, and a missing intl will surface as a runtime error rather than a validation failure.

How to Pitch It (Stakeholders)

To executives: We serve Turkish users and currently accept national ID numbers at face value. This package adds standard validation of the Turkish national ID at the point of capture, plus optional cross-checking of name and date of birth against the official registry. It is a small, free dependency rather than a build project, so it removes a recurring engineering task and reduces fake sign-ups and downstream manual review cost. The latest release tightens name matching for Turkish characters, which reduces false rejections of legitimate users. It is a hygiene control, not a replacement for a licensed identity-verification vendor — if we need document or biometric checks, that remains a separate procurement.

To engineering: Add the package via Composer; the service provider and facade are auto-discovered. Use the provided validation rule on form requests for cheap, synchronous rejection of malformed IDs, and keep registry verification behind a queued job with explicit timeouts, since it is an external call. The v1.2.0 change replaces the hand-rolled uppercasing in trUpper with PHP's Transliterator, which correctly handles Turkish dotted/dotless i — this is the class of bug that causes valid users to fail verification, so treat it as a correctness fix worth taking. No public API changes and no migration work. Two things to confirm in review: that ext-intl is present in our runtime images, and that we have tests asserting the verification path for names containing i, ı, İ, and ş/ğ. Given the project's small contributor base, pin the version and own a fallback plan — worst case we inline the checksum and drop the external call.