1# ANTLR4 Runtime for PHP
2[![Travis CI](https://api.travis-ci.org/antlr/antlr-php-runtime.svg?branch=master)](https://travis-ci.org/antlr/antlr-php-runtime)
3[![Latest Stable Version](https://poser.pugx.org/antlr/antlr4-php-runtime/v/stable)](https://packagist.org/packages/antlr/antlr4-php-runtime)
4[![License](https://poser.pugx.org/antlr/antlr4-php-runtime/license)](https://packagist.org/packages/antlr/antlr4-php-runtime)
5
6### First steps
7
8#### 1. Install ANTLR4
9
10[The getting started guide](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md)
11should get you started.
12
13#### 2. Install the PHP ANTLR runtime
14
15Each target language for ANTLR has a runtime package for running parser
16generated by ANTLR4. The runtime provides a common set of tools for using your parser.
17
18Install the runtime with Composer:
19
20```bash
21composer require antlr/antlr4-php-runtime
22```
23
24#### 3. Generate your parser
25
26You use the ANTLR4 "tool" to generate a parser. These will reference the ANTLR
27runtime, installed above.
28
29Suppose you're using a UNIX system and have set up an alias for the ANTLR4 tool
30as described in [the getting started guide](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md).
31To generate your PHP parser, run the following command:
32
33```bash
34antlr4 -Dlanguage=PHP MyGrammar.g4
35```
36
37For a full list of antlr4 tool options, please visit the
38[tool documentation page](https://github.com/antlr/antlr4/blob/master/doc/tool-options.md).
39
40### Complete example
41
42Suppose you're using the JSON grammar from https://github.com/antlr/grammars-v4/tree/master/json.
43
44Then, invoke `antlr4 -Dlanguage=PHP JSON.g4`. The result of this is a
45collection of `.php` files in the `parser` directory including:
46```
47JsonParser.php
48JsonBaseListener.php
49JsonLexer.php
50JsonListener.php
51```
52
53Another common option to the ANTLR tool is `-visitor`, which generates a parse
54tree visitor, but we won't be doing that here. For a full list of antlr4 tool
55options, please visit the [tool documentation page](tool-options.md).
56
57We'll write a small main func to call the generated parser/lexer
58(assuming they are separate). This one writes out the encountered
59`ParseTreeContext`'s:
60
61```php
62<?php
63
64namespace JsonParser;
65
66use Antlr\Antlr4\Runtime\CommonTokenStream;
67use Antlr\Antlr4\Runtime\Error\Listeners\DiagnosticErrorListener;
68use Antlr\Antlr4\Runtime\InputStream;
69use Antlr\Antlr4\Runtime\ParserRuleContext;
70use Antlr\Antlr4\Runtime\Tree\ErrorNode;
71use Antlr\Antlr4\Runtime\Tree\ParseTreeListener;
72use Antlr\Antlr4\Runtime\Tree\ParseTreeWalker;
73use Antlr\Antlr4\Runtime\Tree\TerminalNode;
74
75final class TreeShapeListener implements ParseTreeListener {
76    public function visitTerminal(TerminalNode $node) : void {}
77    public function visitErrorNode(ErrorNode $node) : void {}
78    public function exitEveryRule(ParserRuleContext $ctx) : void {}
79
80    public function enterEveryRule(ParserRuleContext $ctx) : void {
81        echo $ctx->getText();
82    }
83}
84
85$input = InputStream::fromPath($argv[1]);
86$lexer = new JSONLexer($input);
87$tokens = new CommonTokenStream($lexer);
88$parser = new JSONParser($tokens);
89$parser->addErrorListener(new DiagnosticErrorListener());
90$parser->setBuildParseTree(true);
91$tree = $parser->json();
92
93ParseTreeWalker::default()->walk(new TreeShapeListener(), $tree);
94```
95
96Create a `example.json` file:
97```json
98{"a":1}
99```
100
101Parse the input file:
102
103```
104php json.php example.json
105```
106
107The expected output is:
108
109```
110{"a":1}
111{"a":1}
112"a":1
1131
114```
115
116### Useful information
117
118* [Official site](http://www.antlr.org/)
119* [Documentation](https://github.com/tunnelvisionlabs/antlr4/blob/master/doc/index.md)
120* [Getting started with v4](https://github.com/tunnelvisionlabs/antlr4/blob/master/doc/getting-started.md)
121* [PHPStan Exension](https://github.com/antlr/antlr-php-runtime-phpstan)
122* [FAQ](https://github.com/tunnelvisionlabs/antlr4/blob/master/doc/faq/index.md)
123
124### The Definitive ANTLR 4 Reference
125
126Programmers run into parsing problems all the time. Whether it’s a data format like JSON, a network protocol like SMTP, a server configuration file for Apache, a PostScript/PDF file, or a simple spreadsheet macro language—ANTLR v4 and this book will demystify the process. ANTLR v4 has been rewritten from scratch to make it easier than ever to build parsers and the language applications built on top. This completely rewritten new edition of the bestselling Definitive ANTLR Reference shows you how to take advantage of these new features.
127
128You can buy the book [The Definitive ANTLR 4 Reference](http://amzn.com/1934356999) at amazon or an [electronic version at the publisher's site](https://pragprog.com/book/tpantlr2/the-definitive-antlr-4-reference).
129
130You will find the [Book source code](http://pragprog.com/titles/tpantlr2/source_code) useful.
131
132### Additional grammars
133
134[This repository](https://github.com/antlr/grammars-v4) is a collection of grammars without actions where the
135root directory name is the all-lowercase name of the language parsed by the grammar.
136