Behat Gherkin

Behat Gherkin is the PHP parser that reads Gherkin — the business-readable, domain-specific language used to describe software behavior in BDD. It lexes and parses .feature files into a structured node tree (features, backgrounds, scenarios, scenario outlines, steps, examples, and tags) that tools can traverse and execute.

The parser bundles native keyword support for more than 40 languages, ships with loaders and filters for selecting subsets of scenarios, and exposes a clean object-oriented AST. It is the parsing foundation beneath the Behat BDD framework, but it is a standalone library that any PHP tool needing to understand Gherkin can depend on directly.

What You Get

• A lexer and parser that turn Gherkin .feature text into a node tree (features, scenarios, outlines, steps, examples, tags)
• Built-in keyword dialects for more than 40 natural languages
• Loaders for reading features from files, directories, or arrays, plus filters for selecting scenarios by tag, name, or line
• A clean, object-oriented AST with caching for repeated parses

Common Use Cases

• Powering BDD test runners that execute Gherkin scenarios
• Building custom tooling that reads or transforms feature files
• Validating and linting Gherkin syntax across a project

Under The Hood

Architecture — Parsing flows from Lexer.php, which tokenizes source using a resolved Dialect/Keywords set, into Parser.php, which assembles typed Node objects (FeatureNode, ScenarioNode, OutlineNode, StepNode, ExampleTableNode, and more). Loader classes read features from files/directories/arrays, Filter classes narrow the scenario set, and a Cache layer avoids re-parsing unchanged input. The top-level Gherkin.php ties loaders, filters, and the parser together.

Tech Stack — Pure PHP with a compatibility mode for aligning to the Cucumber Gherkin spec, distributed via Composer. Keyword data for 40+ languages is generated into i18n.php.

Code Quality — The tests/ tree mirrors the source structure (Dialect, Filter, Loader, Node, Cache) and includes a Cucumber suite that runs the shared cross-language Gherkin conformance fixtures, giving strong, spec-aligned coverage of the parser’s behavior.

API Design — Consumers typically call a configured Gherkin instance’s load() to get feature nodes, or use the Parser directly on a string. Interfaces like ParserInterface and pluggable loaders/filters keep the API extensible and easy to integrate into larger tools.