Ec Validador Cedula Ruc Laravel Package

Getting Started

Install the package with Composer:

composer require tavo1987/ec-validador-cedula-ruc

Laravel should discover the service provider automatically. If it does not, inspect the installed package's composer.json for extra.laravel.providers and register the provider manually in bootstrap/providers.php or config/app.php.

Look first at:

1. The package README for the exact validation aliases or rule classes.
2. vendor/tavo1987/ec-validador-cedula-ruc/src/ for the service provider and validator implementation.
3. The package tests, if present, for valid/invalid examples and edge cases.

The first practical use case is validating identity documents on registration, checkout, or supplier onboarding:

public function rules(): array
{
    return [
        'cedula' => ['required', 'string', 'cedula'],
        'ruc'    => ['required', 'string', 'ruc'],
    ];
}

Smoke-test the rule before wiring it into a form:

validator(
    ['cedula' => '1710034065'],
    ['cedula' => 'cedula']
)->passes(); // true

validator(
    ['ruc' => '1710034065001'],
    ['ruc' => 'ruc']
)->passes(); // true

If your installed version exposes different aliases, such as ec_cedula and ec_ruc, or ships rule objects instead of aliases, use the names documented in that version's README. Pin the package version in composer.json so a future release does not silently change the public rule names.

Implementation Patterns

Use FormRequests as the boundary. Keep document validation in request classes or dedicated rule objects rather than controllers. This keeps API and web validation consistent.

protected function prepareForValidation(): void
{
    $this->merge([
        'cedula' => preg_replace('/\D/', '', (string) $this->cedula),
        'ruc'    => preg_replace('/\D/', '', (string) $this->ruc),
    ]);
}

public function rules(): array
{
    return [
        'tipo_persona' => ['required', 'in:natural,juridica'],
        'cedula'       => ['required_if:tipo_persona,natural', 'string', 'cedula'],
        'ruc'          => ['required_if:tipo_persona,juridica', 'string', 'ruc'],
    ];
}

Normalize, then validate, then store as a string. Users paste documents with spaces, hyphens, or dots. Normalize to digits before validation, but store the normalized value as a string. Never cast Ecuadorian documents to integers.

$user->cedula = $validated['cedula']; // string, preserves leading zeros

Combine checksum validation with database uniqueness. The package validates document structure, not whether the document already belongs to another user or company.

'cedula' => [
    'required',
    'string',
    'cedula',
    Rule::unique('users', 'cedula')->ignore($user?->id),
],

Model the document type explicitly. For mixed person/company flows, avoid two loose nullable fields without business rules. Use an enum or a small value object.

enum DocumentoType: string
{
    case Cedula = 'cedula';
    case Ruc = 'ruc';
}

Then build a conditional rule or dedicated DocumentoIdentificacionRule that delegates to the package and returns one consistent domain error message.

Wrap the package behind your own rule for larger applications. This prevents package aliases from leaking into every FormRequest and makes it easier to swap validators later.

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class DocumentoEcuadorRule implements ValidationRule
{
    public function __construct(private string $tipo) {}

    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        $rule = $this->tipo === 'ruc' ? 'ruc' : 'cedula';

        if (! validator(['documento' => $value], ['documento' => $rule])->passes()) {
            $fail('El documento ingresado no es válido.');
        }
    }
}

Test with data providers. Cover valid cédulas, valid RUCs, altered check digits, wrong lengths, letters, empty strings, and leading-zero cases.

public static function documentosValidos(): array
{
    return [
        ['cedula', '1710034065'],
        ['ruc', '1710034065001'],
    ];
}

Integrate at the edges. Validate on registration, profile updates, invoice recipient creation, and supplier/customer imports. For bulk imports, validate rows before inserting and report row-level errors rather than failing the whole import.

Gotchas and Tips

The package validates format/checksum, not real-world existence. A passing cédula or RUC does not prove the person exists, is alive, or is registered with the SRI. Do not use it as identity verification. For tax status, use SRI web services or an authorized provider.

Store documents as strings. Integer columns and casts strip leading zeros and break values like 0102030405. Use string/varchar columns and string casts.

Normalize carefully. preg_replace('/\D/', '', ...) is useful, but do not normalize away meaningful emptiness before required runs unless you want an empty string to produce a required error. Handle null before passing to preg_replace.

Watch the RUC third digit. Natural-person RUCs usually derive from a cédula plus 001; public companies and private companies have different third-digit conventions. If the package only checks the checksum, add your own business rule for the RUC type you accept.

Do not use the integer validation rule. Use string with digits:10 or digits:13, or rely on the package's rule plus length checks. Numeric casts on the client side can silently corrupt leading zeros.

Rule alias conflicts are possible. If your application already defines a cedula or ruc validator, confirm registration order and behavior. Prefer a custom rule class with a distinct name in large codebases.

Clear caches after installation or upgrades. If the rule is "not found," run:

composer dump-autoload
php artisan config:clear
php artisan optimize:clear

Check package messages and translations. Validation messages may be in Spanish or generic English. Pass custom messages in the FormRequest or publish/override translations if the package supports it.

Debug failures with the raw normalized value. Dump the exact string being validated, including whitespace, non-breaking spaces, and BOM characters. A visually correct cédula can fail because of a trailing space.

Pin the version. This is a small, low-star package. Review the source and tests before relying on it in production, and lock a known-good version. If the package is unmaintained, wrapping it in a local rule makes replacement straightforward.

Validate server-side even if the frontend mirrors the format. Client-side checks improve UX, but the checksum validation must run on the server.

Avoid real personal data in tests. Use synthetic or widely used example documents, and never commit real cédulas/RUCs in fixtures or logs.