Socrates Laravel Package

Technical Evaluation

Architecture fit

• Socrates is a domain/data-validation library (person identity primitives: Gender and Country enums, national ID validators/extractors) rather than a Laravel-native extension point. After v2.0.0 it is explicitly framework-agnostic: the facade and Laravel validation rule are gone, so the package no longer participates in Laravel's container, validation pipeline, or auto-discovery.
• Best fit is as a Composer dependency consumed inside the application's domain layer, with a thin in-house adapter (service provider binding + custom validation rule) owned by our team. Treat the package boundary as "pure PHP," and Laravel as our integration concern.
• The enum-based API is a net architectural improvement for us: Gender/Country become typed domain values rather than loose strings, which composes well with Eloquent casts, DTOs, and API resources.

Integration feasibility

• Install is standard Composer on PHP 8.1+. The removal of Carbon shrinks the transitive dependency graph and reduces version-conflict risk with Laravel's own dependency constraints.
• Feasibility is high for a greenfield adoption; for existing consumers this is a hard major bump. Any use of the removed facade, the validation rule string, the old string constants, the Luxembourg validator/extractor, or Carbon return types will break at runtime or fail static analysis.
• Because the Laravel glue is removed, we must supply it: container binding, a validation rule wrapping the package validators, enum casts on models, and serialization rules for API output.

Technical risk

• High, contained: breaking API removal (facade, validator rule, string constants, Luxembourg classes, Carbon). Contained because the library is narrow and the blast radius is limited to identity-validation call sites.
• Medium: enum migration changes value representation. Code comparing against 'male'/'LU'-style strings, DB columns, JSON payloads, seeders, and fixtures must be audited. Backed vs. pure enum behavior determines serialization impact — confirm.
• Medium: loss of the Laravel validation rule means input can silently go unvalidated if a call site is missed during migration; this is a correctness/security risk for PII-adjacent flows.
• Low: PHPUnit 9 and code-style churn are dev-only. Testbench removal affects only package-level testing, not our runtime.

Key questions

• Which Laravel/Illuminate versions are supported (constraint on illuminate/* or none at all)? Does the package still ship a service provider?
• Are the Gender/Country enums backed (string/int) and what are the case values? This drives DB, JSON, and API contract changes.
• Is Luxembourg support intentionally dropped or relocated to a sibling package? Do we currently depend on it?
• Is there an UPGRADE/changelog guide and a documented support window for the 1.x line?
• Maintenance model and bus factor: who maintains the package, what is the release cadence, and is there a security disclosure path?
• Does the package handle PII in logs/exceptions (relevant to our data-handling obligations)?

Integration Approach

Stack fit

• Fits any Laravel application on PHP 8.1+ (Laravel 9/10 comfortably; Laravel 11 requires PHP 8.2, so confirm the runtime floor before locking). No framework coupling remains, so it also fits non-Laravel PHP services and CLI workers — a plus if we share identity logic across services.
• Requires an app-owned adapter layer: one service provider, one custom validation rule, enum casts, and an API serialization convention. Budget this as first-class work, not glue afterthought.

Migration path

1. Inventory usage: grep for facade imports, the validation rule key, string constants, Luxembourg classes, and any Carbon assumptions on returned values.
2. Pin the current 1.x version; create an upgrade branch; raise the platform to PHP 8.1 first and confirm CI parity.
3. Replace string constants with enum cases; update model casts, DB columns/enum storage, factories, seeders, and fixtures.
4. Reimplement the Laravel validation rule in-house against the package API; add feature tests asserting parity with prior behavior.
5. Replace facade calls with constructor-injected services; remove any Luxembourg code paths or confirm a replacement.
6. Run golden-file/snapshot tests on validation outputs, then canary.

Compatibility

• PHP 8.1 is a hard floor; anything pinned below blocks adoption.
• Enum adoption is a data-contract change: API consumers and persisted rows must be reconciled in the same release. Plan a compatibility shim (accessor/mutator or API resource mapping) if external consumers exist.
• Dropping Carbon removes a shared dependency that may currently be the reason for version conflicts — verify no code relies on Carbon instances flowing out of the package.

Sequencing

• Platform upgrade (PHP 8.1) → dependency bump on a branch → enum/data migration → in-house validation rule → facade removal → test parity → staged rollout. Expect days, not weeks, for a small integration surface; scale effort with the number of call sites and any persisted enum data.

Operational Impact

Maintenance

• Supply-chain surface improves: fewer runtime dependencies and no Carbon version pinning. The offsetting cost is that the Laravel integration is now ours to maintain — a small but permanent ownership item, including keeping the custom validation rule aligned with package releases.
• Enum types reduce defect classes (invalid country/gender strings become unrepresentable), lowering long-term maintenance in identity flows.

Support

• The package is now a generic PHP library; upstream will not answer Laravel-integration questions. Our internal documentation must cover the adapter layer.
• Confirm the 1.x support/EOL window so we can schedule the upgrade rather than being forced into it. Assess maintainer responsiveness and release history before deepening dependence.

Scaling

• Validation is CPU-light and stateless; enums and the stated performance improvements are marginal at our volumes. No horizontal-scaling concerns.
• If identity validation runs in request paths at high throughput, cache/avoid redundant validation; keep PII out of logs and exception messages.

Failure modes

• ValueError/TypeError on invalid enum construction from unvalidated input or legacy DB rows.
• Silent under-validation where the removed Laravel rule was relied upon and not replaced — highest-severity risk.
• Missing-class fatal errors for Luxembourg call sites.
• Serialization drift: enums emitting different JSON/DB values than the old strings, breaking API consumers or reports.
• Autoload/container errors if code still resolves the removed facade.

Ramp-up

• Low for engineers familiar with PHP 8.1 enums (half-day to a day); the conceptual load is the adapter pattern, not the library.
• The real ramp-up is migration diligence: auditing call sites, reconciling persisted enum values, and proving validation parity with tests. Assign a single owner for the in-house Laravel adapter to prevent drift.