Socrates Laravel Package

Getting Started

Socrates v2.0.0 is a breaking release. Start by confirming your app runs PHP 8.1+ and that you are not relying on the removed Laravel facade, validation rule, Luxembourg support, Carbon, or old Gender/Country string constants.

1. Review the support matrix before upgrading. Luxembourg ID validation/extraction is gone in v2. If you validate Luxembourg IDs, stay on v1 or implement that support yourself.
2. Install/upgrade with care. For new projects, require the v2 line. For existing projects, read the v1-to-v2 diff first and treat it as a major upgrade.
3. Look at the enums first. Gender and Country are now enums. Use them for type-safe comparisons instead of the removed string constants.
4. Use the package directly in Laravel. There is no Laravel facade or validation rule in v2. Instantiate the validator/extractor classes in your service/action layer or wrap them in your own Laravel validation rule.

First use case: validating a supported national ID during onboarding, then extracting country/gender metadata through the new enums. In Laravel, put this behind a small adapter or custom validation rule rather than calling package classes from controllers.

Implementation Patterns

Wrap package usage behind your own adapter. Since the Laravel integration was removed, keep Socrates calls in one service class. This makes future package changes, country support changes, or a v1 fallback for Luxembourg easier to isolate.

final class IdVerificationService
{
    public function verify(string $id, Country $country): IdResult
    {
        // Use the package validator/extractor here.
        // Normalize input before calling Socrates if the package expects it.
    }
}

Create a custom Laravel validation rule. Replace the removed package validation rule with your own rule that calls Socrates and reports failures through Laravel’s validator.

final class SocratesIdRule implements ValidationRule
{
    public function __construct(private Country $country) {}

    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        $result = app(IdVerificationService::class)->verify((string) $value, $this->country);

        if (! $result->isValid()) {
            $fail('The :attribute is not a valid national ID.');
        }
    }
}

Use it from form requests:

'id_number' => ['required', 'string', new SocratesIdRule(Country::US)],

Use enum casts for persistence. Store the enum value in the database and cast it back in Eloquent:

protected $casts = [
    'country' => Country::class,
    'gender' => Gender::class,
];

When comparing, use enum cases:

if ($result->gender() === Gender::Female) {
    // ...
}

Persist with ->value only when writing to storage/API payloads:

$model->country = $country->value;

Migrate old string constants. Any config, database seed, API response, or validation rule that used the old Gender/Country strings must move to enum cases or enum values. For database rows, add a mapping migration before switching code.

Replace Carbon expectations. v2 removed the Carbon dependency. If your extraction code assumed Carbon instances for dates, update it to work with native date/time objects or convert them at your application boundary.

Handle Luxembourg explicitly. Since the Luxembourg validator and extractor are removed, multi-country flows should either reject Luxembourg at the country-selection step or route it to a separate implementation. Do not rely on a generic “supported country” check returning Luxembourg.

Test against supported countries only. Add tests for each country you actually use, plus a test that unsupported countries fail predictably. This is especially important after removing Luxembourg and changing enum-based APIs.

Gotchas and Tips

• v2 is a hard break for Laravel users. There is no facade alias and no package validation rule. Remove old imports/aliases, and replace Socrates::... or rule-class usage with your own adapter/rule.
• Pin ^1 if you need removed features. If you depend on the Laravel facade, built-in validation rule, Luxembourg support, Carbon, or old string constants, do not upgrade yet.
• Enums are not drop-in replacements for strings. Strict comparisons, database casts, JSON serialization, and API payloads all need review. Use ->value at serialization boundaries and enum cases internally.
• Luxembourg is a functional regression, not just a cleanup. Any LU validation or extraction path will fail or be unavailable in v2. Plan a fallback before upgrading.
• Carbon removal can surface in subtle places. Check DTOs, accessors, presenters, and tests that type-hint Carbon or call Carbon-only methods on extracted dates.
• No Orchestra Testbench means less Laravel test scaffolding. Package-level Laravel integration tests are no longer provided by v2. Test your own wrapper and validation rule inside your application test suite.
• Clear Laravel caches after removing facade/rule references. Run php artisan optimize:clear and composer dump-autoload after upgrading to catch stale aliases or cached config.
• Debug composer conflicts with PHP 8.1 constraints. v2 requires PHP 8.1 minimum, so check your Laravel version, CI matrix, and other dependencies with composer why-not.
• Keep extension points in your app, not the package. The removal of Laravel-specific classes means your best extension points are a custom validation rule, a service adapter, enum casts, and country-specific strategy classes.