Weave Code
Gherkin Laravel Package
behat/gherkin
Behat's PHP Gherkin parser for reading .feature files, with support for 40+ native languages and a clean, extensible architecture. Parse features, scenarios, backgrounds, outlines, and examples into structured objects for your test suite.
Gherkin parser, written in PHP for Behat project
Frequently asked questions about Gherkin
- What is behat/gherkin used for in a Laravel application?
- It is a pure PHP parser that turns Gherkin .feature files into an object tree of features, scenarios, steps, examples, and data tables. In a typical Laravel CRUD or API codebase it is not needed; it makes sense when you are building tooling such as feature-file linting, requirement traceability, spec-to-ticket sync, or documentation generation. Most often it appears as a transitive dependency of Behat rather than something you install directly.
- How do I install behat/gherkin with Composer?
- Run composer require behat/gherkin and the library becomes available through Composer autoloading. There is no service provider to register and no configuration file to publish, because the package has no Laravel coupling. You instantiate the Lexer and Parser yourself or wrap them in a small adapter class in your application.
- Does behat/gherkin work with Laravel 10, 11, and 12?
- Yes. The package is framework-agnostic and does not depend on any Laravel component, so it works with any Laravel version running on a supported PHP 8.x runtime. Compatibility is driven by your PHP version rather than your Laravel version, and PHP 8.5 support landed in release 4.15. Nothing needs to be registered in the framework.
- How do I parse a .feature file into PHP objects?
- Create a keywords or dialect provider, pass it to Behat\Gherkin\Lexer, then pass that lexer into Behat\Gherkin\Parser and call parse() with the file contents. The result is a FeatureNode tree containing BackgroundNode, ScenarioNode, StepNode, ExampleNode, and TableNode objects. In a Laravel app, bind the parser in a service provider or container singleton instead of constructing it at every call site.
- Which Gherkin compatibility mode should I use: LEGACY, GHERKIN_32, or GHERKIN_42?
- The mode changes parsed output: how descriptions are trimmed, whether the @ prefix is kept on tags, whether Rule nodes survive, whether docstrings and data tables can coexist on one step, and whether unknown language tags throw or fall back to English. LEGACY is still the default but is explicitly not recommended for new projects. Pick one mode deliberately, document it as a semantic contract, and pin it in configuration so your tooling stays stable across upgrades.
- Does behat/gherkin support feature files written in languages other than English?
- Yes, it ships with keyword definitions for more than 40 native languages and lets you supply custom keyword sets through a keywords or dialect provider. That is useful for multilingual teams that write specifications in their own language. If you only ever parse English features, treat the i18n support as a bonus rather than a deciding factor.
- Can I filter scenarios by tags, names, or line numbers?
- Yes, the package includes filters such as TagFilter, NameFilter, LineFilter, LineRangeFilter, and RoleFilter that operate over the parsed node tree. You apply them after parsing, which is handy for building subset reports, exports, or targeted tooling. Filtering is a parsing-side convenience, not test execution.
- Does behat/gherkin execute tests, or is it only a parser?
- It is a lexer and parser only; it converts .feature text into an AST of node objects and does not run steps or drive a browser. Step execution is Behat's responsibility, or your own runner if you are building custom tooling. Installing this package alone gives you parsing, not a BDD test framework.
- Is behat/gherkin production-ready and actively maintained?
- It is MIT-licensed, powers the Behat framework, and is held to PHPStan level 10 with an automated backwards-compatibility check in CI. Maintenance is volunteer-run by a small team of named maintainers with a sponsorship model, so plan for community-level support rather than a vendor SLA. The main risks are the LEGACY default mode and active deprecations around extending the core Lexer, Parser, and Node classes instead of using the interfaces.
- How do I test code that parses Gherkin, and what are the alternatives?
- Because the parser is deterministic and has no framework dependencies, you can unit test it with fixture .feature strings and assert on the returned node types and values; no database or HTTP layer is needed. The realistic alternative is Behat itself, which bundles this parser, or a non-PHP Gherkin tool in your pipeline such as Cucumber's parsers. Within PHP, behat/gherkin is the de facto implementation, which also means independent production validation outside Behat is limited.
Weaver
How can I help you explore Laravel packages today?