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:

• Overview
• Architecture
• Built-in Functions
• Xpath object
• FunctionRegistry object
• ExpressionPreparer object
• ExpressionTokenizer object
• ExpressionEvaluator object

Portuguese (Brazil):

• Visão geral
• Arquitetura
• Funções nativas
• Objeto Xpath
• Objeto FunctionRegistry
• Objeto ExpressionPreparer
• Objeto ExpressionTokenizer
• Objeto ExpressionEvaluator

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