README

Português do Brasil

A small PHP library for validating and evaluating a focused XPath-like expression dialect against a value and an optional context array.

This project was inspired by the API style of the Python library znc-sistemas/xpath_validator. The PHP implementation in this repository is independent, but the public usage style follows the same idea of validating expressions against runtime values.

Why this project exists

This repository isolates XPath-style validation behavior that was previously embedded in another project. The goal is to keep expression validation small, testable, reusable, and safe to evolve on its own.

Features

Static convenience API via Xpath::validate(...)
Instance-based execution via new Xpath(...)->execute()
Value placeholder support with .
Context interpolation with ${name}
Built-in XPath-like functions mapped to PHP handlers
Custom expression parser and evaluator
No eval()
Positive and rejection-oriented test coverage

Installation

If the package is published to Packagist, you can install it with:

composer require icmbio/validate-xpath-expression

If you are consuming the repository directly before publication, add it as a VCS repository in your composer.json and require the package from there.

Quick start

<?php

use Icmbio\ValidateXpathExpression\Xpath;

$isValid = Xpath::validate('. >= ${min} and . <= ${max}', 10, [
    'min' => 1,
    'max' => 100,
]);

var_dump($isValid); // true

Returning the raw evaluated result instead of a boolean:

<?php

use Icmbio\ValidateXpathExpression\Xpath;

$length = Xpath::validate('string-length(.)', 'abacate', [], false);

var_dump($length); // 7

If you prefer a function-style API similar to the Python-inspired usage style, the package also exposes namespaced helpers:

<?php

use function Icmbio\ValidateXpathExpression\validate;

$isValid = validate('. >= ${min} and . <= ${max}', 10, [
    'min' => 1,
    'max' => 100,
]);

Supported expression model

This library intentionally supports a focused subset instead of full XPath.

Supported pieces include:

Numbers and quoted strings
true, false, and null
Arithmetic: +, -, *, div, mod
Comparison: =, !=, <, <=, >, >=
Boolean operators: and, or
Parentheses
Function calls registered in FunctionRegistry

Built-in functions

selected
string-length
string_length
int
floor
ceiling
number
string
contains
starts-with
normalize-space
choose
not
true
false
uuid
format-date-time
substring-after
substring-before

Architecture overview

The library is intentionally split into small objects:

Xpath: public entry point and orchestrator
ExpressionPreparer: normalizes placeholders and operators
ExpressionTokenizer: converts the prepared expression into tokens
ExpressionEvaluator: parses and evaluates tokens
FunctionRegistry: maps XPath-like function names to handler classes
src/Functions: executable function handlers

Documentation

The repository includes deeper documentation in two languages.

English:

Portuguese (Brazil):

These pages are also suitable as a base for a GitHub Wiki.

Development

Useful commands:

composer repl
composer test
composer test:coverage
composer stan
composer check

composer test:coverage requires a local coverage driver such as pcov or xdebug.

Local guard rails

This repository includes a few guard rails for safer development:

phpstan for static analysis
PHPUnit for automated tests
coverage generation when pcov or xdebug is available locally
versioned Git hooks under .githooks
GitHub Actions CI under .github/workflows/ci.yml

To enable the local Git hooks:

git config core.hooksPath .githooks

REPL

The repository ships with a simple REPL for trying expressions against the loaded project runtime:

composer repl

Inside the REPL you can call:

validate(...)
escape_expression(...)
Xpath::validate(...)
new Xpath(...)->execute()

Special commands:

:help
:clear
:quit

If readline is available, the REPL also provides command history and basic autocomplete.

License

MIT

icmbio/validate-xpath-expression

包简介

README 文档