vanderlee / comprehend-laravel

1.0.1 2026-10-19 10:06 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0 || ^12.0 || ^13.0
• vanderlee/comprehend: ^2.0

Requires (Dev)

• illuminate/translation: ^11.0 || ^12.0 || ^13.0
• illuminate/validation: ^11.0 || ^12.0 || ^13.0
• phpunit/phpunit: ^10.5.62

MIT

Published on Packagist.org on 2026-10-19 10:07 UTC

README

A standalone Laravel validation bridge for Comprehend 2. Supports Illuminate 11, 12 and 13 on their respective supported PHP versions (PHP 8.2 minimum; Illuminate 13 requires PHP 8.3). The core library has no Laravel dependency.

Installation

From your Laravel application's root directory, install the package with Composer:

composer require vanderlee/comprehend-laravel

Composer installs the Comprehend core dependency automatically. No service provider, facade, configuration file or package discovery is needed.

The source is maintained in vanderlee/comprehend-laravel.

Usage

use Vanderlee\Comprehend\Comprehend as C;
use Vanderlee\Comprehend\Laravel\Rules\MatchesGrammar;

// Inside a Form Request's rules() method:
return [
    'reference' => [
        'required',
        'string',
        new MatchesGrammar(C::text('INV-')->then(C::range('0', '9')->some())),
    ],
];

This accepts references such as INV-123 and rejects INV-, 123 and INV-123-extra.

The constructor accepts a Comprehend facade or a FrozenGrammar object, not a class name. Inject your application's grammar service into the Form Request's rules() method when grammars are registered in Laravel's container.

The rule requires a complete match and rejects recovered syntax. Input must be a UTF-8 string; scalars and objects are never coerced. Syntax failures include the first diagnostic's line, column and byte offset. Source text is not included, but grammar expectations may appear; supply a custom message to hide them.

Semantic validation, limits and messages

new MatchesGrammar(
    $grammar->freeze(),
    validateSemantics: true,
    limits: new \Vanderlee\Comprehend\Runtime\ParseLimits(maxDepth: 100, maxWork: 100000),
    message: __('validation.reference_syntax'),
);

Custom messages replace the entire failure message, including syntax diagnostics, for invalid text, syntax and semantic failures. They support Laravel's :attribute placeholder. Translate the message in the application before passing it. The package does not register translation keys.

Recognition alone runs by default. Set validateSemantics: true to run the grammar's semantic validators; these may evaluate lazy mappings. Mappings and validators should be pure. The rule never calls commit(), even after semantic success, and retains no input or parse result between calls. Grammar errors, application callback exceptions and execution-limit exceptions propagate to the application; they are not converted into ordinary validation failures.

Missing, empty and nullable fields

Laravel normally skips ordinary rules for missing attributes and empty strings. Use required for mandatory input, or nullable for optional null values. Laravel's request middleware may trim strings or convert empty strings to null before validation; configure that middleware if exact input bytes matter.

Reading the parsed value

Validation does not replace the field with a parsed value. After successful validation, parse explicitly through the same grammar and call value():

// In a controller, with the validated Form Request and the same grammar
// used by its MatchesGrammar rule:
$data = $request->validated();
$result = $grammar->parseAll($data['reference']);
$reference = $result->value();

This example assumes reference is required. For an optional field, check that it is present and non-null before parsing. Reuse any parse limits configured on the rule. The value's type depends on the grammar and its mappings; validation alone leaves those mappings unevaluated unless semantic validators need them. Commit effects only at an explicit application boundary.

Development

Install dependencies and run the tests from this package directory:

composer install
composer test

Tests use the real Illuminate validation factory, without booting a Laravel app. The same behavioral cases run against builder and frozen grammars. They cover recognition, UTF-8 and type rejection, multiline diagnostic locations without source excerpts, custom messages, semantic checks, lazy mappings, effect isolation, recovery rejection, execution limits, callback exceptions, rule reuse and Laravel's handling of empty, missing and nullable fields.

MIT licensed; see LICENSE.