Socrates Laravel Package

Product Decisions This Supports

• Identity/KYC verification scope: Socrates underpins national ID number validation and data extraction (country, gender, date of birth). It directly informs whether we can validate document IDs in-house for onboarding, age-gating, or fraud checks without a paid vendor.
• Build vs. buy for identity validation: A maintained, dependency-light parsing library is a credible "buy/adopt" option versus a commercial KYC API. This release strengthens that case (fewer dependencies, PHP 8.1 types) while weakening it for Laravel-native teams (facade and validation rule removed).
• Country coverage roadmap: Dropping Luxembourg validator/extractor is a tangible coverage regression. PM should map current and target markets against supported countries before committing to the library; if LU is on the roadmap, that becomes an in-house build item or a vendor trigger.
• Laravel integration ownership: Since the facade and Validator rule are gone, Laravel teams must now own a thin adapter (service provider binding, custom validation rule, exception mapping). That's a small, explicit engineering task to schedule — not a blocker, but a real line item in any Laravel adoption plan.
• Platform upgrade sequencing: PHP 8.1 minimum and PHPUnit 9 force our runtime and test toolchain forward. This release is a forcing function for the PHP upgrade roadmap and should be sequenced with other 8.1-dependent dependencies.
• Type safety as a product-quality lever: Enum-based Gender and Country removes string-constant ambiguity from our domain models. This supports cleaner downstream data contracts (e.g., profile/gender fields, country codes) and fewer mapping bugs in reporting and analytics.
• Use cases to prioritize: onboarding form validation, data normalization of imported customer records, region-specific compliance checks, and test-data generation for QA.

When to Consider This Package

Adopt when:

• You need offline, deterministic validation/parsing of national ID numbers across multiple countries — no per-call vendor cost or PII leaving your infrastructure (a meaningful compliance/privacy advantage).
• Your stack is PHP 8.1+ and you can absorb the migration (or are already there).
• You want a small, auditable dependency footprint — Carbon and testbench removal plus a leaner dependency tree lowers supply-chain and maintenance risk.
• You are willing to own a ~1-day Laravel adapter (validation rule + container binding) internally.
• Enum-based Gender/Country aligns with your domain models and you want typed outputs rather than magic strings.

Look elsewhere (or fork/vendor) when:

• Luxembourg ID validation is a current requirement — coverage was removed in this release, and the major version bump signals no immediate restoration.
• You need turnkey Laravel integration and have no appetite for maintaining an in-house wrapper.
• You are still on PHP 8.0 or below and cannot upgrade on this cycle — v2.0.0 is a hard break.
• You require vendor-backed SLAs, document-image/OCR handling, or global coverage breadth — a commercial KYC provider remains the better fit for high-assurance regulated onboarding.
• You rely on the old string constants (Gender::MALE-style string usage) in existing code — those are removed, so a migration pass is mandatory.

How to Pitch It (Stakeholders)

For executives (one paragraph): We evaluated Socrates v2.0.0, a PHP library that validates and extracts data from national ID numbers. The new release modernizes the codebase (PHP 8.1, enum-based typing, fewer third-party dependencies, better performance) which lowers our maintenance and security risk. The trade-off is that the built-in Laravel integration was removed and Luxembourg support was dropped — so adoption now requires a small in-house adapter and a coverage check against our target markets. Net: a low-cost, privacy-friendly foundation for ID validation we can adopt in days, provided we are on PHP 8.1+ and do not need Luxembourg.

For engineering leads:

• Upgrade path is mandatory and breaking: PHP 8.1 minimum, PHPUnit 9, string constants for Gender/Country replaced by enums. Budget a migration sweep for any call sites using string literals.
• We must build and own the Laravel glue: service provider binding, a custom ValidationRule, and exception-to-message mapping. Estimate ~1–2 days including tests.
• Dependency reduction (Carbon, Orchestra Testbench dropped) is a genuine win for audit surface and CI speed.
• Coverage matrix must be reviewed before we commit; Luxembourg is a confirmed gap.
• Pin to v2 and track the changelog — the major version and removals suggest ongoing API churn.