# phplrt

> phplrt (PHP Language Recognition Tool) is a set of PHP libraries for reading source code: a lexer, a PEG parser, a grammar compiler and an error printer. You describe a format once in a grammar file, and phplrt turns that description into a lexer that cuts the text into tokens and a parser that checks their order and builds whatever result you asked for.

Requires PHP 8.4 or above. Published under the MIT licence.

The library is split in half. The compiler reads `.pp3` grammar files and writes
a parser as plain PHP, which is a job for development time. The runtime, meaning
the lexer, the parser and the source reader, is the only half that ships to
production.

The whole documentation is also available as one file: https://phplrt.org/llms-full.txt

## Prologue

- [Upgrade Guide](/docs/upgrade.md): Version 4.0 is a rewrite, so this is a porting guide rather than a list of renames.
- [Contribution Guide](/docs/contributions.md): To encourage active collaboration, we strongly encourages pull requests, not just bug reports.

## Getting Started

- [Introduction](/docs/guide/introduction.md): Phplrt (PHP Language Recognition Tool) is a set of libraries for reading source code: your own configuration format, a template language, a query syntax, a subset of PHP - anything with rules.
- [Installation](/docs/guide/installation.md): Phplrt is installed with composer.
- [Quick Start](/docs/guide/quick-start.md): Let's build a parser for a small configuration format from scratch: text in, a tree of objects out.

## The Basics

- [PP3 Grammar](/docs/basics/grammar.md): A grammar file describes a language: the words it is made of, and the order they may appear in.
- [Compiling a Grammar](/docs/basics/compiler.md): The compiler reads a grammar file - the tokens, the rules, the reducers - and gives you back a working parser.
- [Results and Reducers](/docs/basics/reducers.md): A parser does two things: it decides whether the input is valid, and it builds something out of it.
- [Source](/docs/basics/source.md): Everything phplrt reads - a grammar file, an expression typed by a user, a template - is wrapped in a source object.
- [Position](/docs/basics/position.md): An offset is what a parser works with: a number of bytes from the beginning of the source.
- [Command Line](/docs/basics/cli.md): A grammar is edited far more often than the code around it, and two things get done over and over while editing: making sure the grammar still holds together, and writing the parser out again.
- [Error Reporting](/docs/basics/errors.md): An error that says "syntax error at offset 137" is technically correct and practically useless.
- [Best Practices](/docs/basics/best-practice.md): What follows is a list of decisions that make a parser pleasant to work with and cheap to run: where your own code goes, how the grammar reaches it, and how much the runtime is willing to say about…

## Digging Deeper

- [Lexer](/docs/advanced/lexer.md): The lexer is the first half of reading source code: it turns a stream of characters into a stream of tokens. 23 + 42 becomes "a number, a plus, a number" - and the parser never has to look at a…
- [Lexer Builder](/docs/advanced/lexer-builder.md): A lexer is described before it can read anything: which tokens there are, what each of them looks like, and what the lexer does with them.
- [Nested Lexers](/docs/advanced/embedding.md): Some fragments of a language are not written in that language.
- [Parser](/docs/advanced/parser.md): The parser is the second half of reading source code.
- [Parser Builder](/docs/advanced/parser-builder.md): Writing the rule array by hand works, but you have to keep track of indices yourself, and one inserted rule renumbers everything.
- [Custom Generator](/docs/advanced/generator.md): A PHP parser is not the only thing a compiled grammar is good for.
- [Analysing an Error](/docs/advanced/analyzer.md): ErrorPrinter turns an exception into a picture.
- [Reading a Snippet](/docs/advanced/snippet-reader.md): SnippetReader is what a renderer reads the source code with.
- [Automation and CI](/docs/advanced/automation.md): Rebuilding the parser after a grammar change is the kind of step that works right up until the day somebody forgets.
- [PP2 Grammar Syntax (Legacy)](/docs/advanced/legacy-grammar.md): This page describes the .pp2 format - the one phplrt 3.x read.

## Contracts

- [Lexer](/docs/contracts/lexer.md): This document describes a common interface for lexical analysis - turning a source into the tokens it consists of - together with the interfaces for the tokens themselves, for the channels those…
- [Parser](/docs/contracts/parser.md): This document describes a common interface for syntax analysis - turning a source into whatever that source means - together with the interfaces for the errors raised along the way.
- [Source](/docs/contracts/source.md): This document describes a common interface for reading source code - a file on disk, a string typed by a user, a stream - together with the interface for creating such a source out of an arbitrary…
- [Position](/docs/contracts/position.md): This document describes a common interface for a human-readable location inside a source - a line and a column - together with the interface for converting between such a location and an offset in…

## Examples

- [Overview](/docs/examples.md): A few complete grammars, picked one per idea.
- [JSON](/docs/examples/json.md): A JSON parser that produces plain PHP values - the result matches json_decode($input, true) exactly.
- [Cron Expression](/docs/examples/cron.md): The five (or six) fields of a crontab line, the @daily shorthands and the extensions almost every scheduler ends up supporting
- [Composer Constraints](/docs/examples/composer-constraints.md): The little language the require section of every composer.json is written in
- [URL](/docs/examples/url.md): Every part of an address, in the order RFC 3986 writes them
- [Graphviz DOT](/docs/examples/dot.md): The language dot, neato and every "render me a graph" tool read - nodes, edges and the attributes hung on both
- [EBNF](/docs/examples/ebnf.md): A grammar for writing grammars: the notation half the specifications on your shelf are written in, read by a grammar of its own.
- [Rule Engine](/docs/examples/rules.md): A rule language of the kind that ends up in the database of every application with permissions or discounts in it - a condition written by someone who is not going to deploy PHP to change it
- [PhpDoc Types (psalm/phpstan)](/docs/examples/phpdoc-types.md): The type language of phpstan and psalm - the one hiding inside @param, @return and @var, which has quietly grown into a language with generics, shapes and conditionals
- [Regular Expressions](/docs/examples/regex.md): A grammar that reads PCRE - the notation the %token lines of every other example here are written in