Blame view

vendor/nikic/php-parser/doc/2_Usage_of_basic_components.markdown 15.6 KB
c4650843   Etienne Pallier   Ajout du dossier ...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
Usage of basic components
=========================

This document explains how to use the parser, the pretty printer and the node traverser.

Bootstrapping
-------------

To bootstrap the library, include the autoloader generated by composer:

```php
require 'path/to/vendor/autoload.php';
```

Additionally you may want to set the `xdebug.max_nesting_level` ini option to a higher value:

```php
ini_set('xdebug.max_nesting_level', 3000);
```

This ensures that there will be no errors when traversing highly nested node trees. However, it is
preferable to disable XDebug completely, as it can easily make this library more than five times
slower.

Parsing
-------

In order to parse code, you first have to create a parser instance:

```php
use PhpParser\ParserFactory;
$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
```

The factory accepts a kind argument, that determines how different PHP versions are treated:

Kind | Behavior
-----|---------
`ParserFactory::PREFER_PHP7` | Try to parse code as PHP 7. If this fails, try to parse it as PHP 5.
`ParserFactory::PREFER_PHP5` | Try to parse code as PHP 5. If this fails, try to parse it as PHP 7.
`ParserFactory::ONLY_PHP7` | Parse code as PHP 7.
`ParserFactory::ONLY_PHP5` | Parse code as PHP 5.

d06254b2   Etienne Pallier   bugfix plugin mig...
44
Unless you have strong reason to use something else, `PREFER_PHP7` is a reasonable default.
c4650843   Etienne Pallier   Ajout du dossier ...
45
46
47
48
49
50
51
52

The `create()` method optionally accepts a `Lexer` instance as the second argument. Some use cases
that require customized lexers are discussed in the [lexer documentation](component/Lexer.markdown).

Subsequently you can pass PHP code (including the opening `<?php` tag) to the `parse` method in order to
create a syntax tree. If a syntax error is encountered, an `PhpParser\Error` exception will be thrown:

```php
c4650843   Etienne Pallier   Ajout du dossier ...
53
54
55
use PhpParser\Error;
use PhpParser\ParserFactory;

d06254b2   Etienne Pallier   bugfix plugin mig...
56
$code = '<?php // some code';
c4650843   Etienne Pallier   Ajout du dossier ...
57
58
59
60
61
62
63
64
65
66
67
68
$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);

try {
    $stmts = $parser->parse($code);
    // $stmts is an array of statement nodes
} catch (Error $e) {
    echo 'Parse Error: ', $e->getMessage();
}
```

A parser instance can be reused to parse multiple files.

d06254b2   Etienne Pallier   bugfix plugin mig...
69
70
Node tree
---------
c4650843   Etienne Pallier   Ajout du dossier ...
71

d06254b2   Etienne Pallier   bugfix plugin mig...
72
73
If you use the above code with `$code = "<?php echo 'Hi ', hi\\getTarget();"` the parser will
generate a node tree looking like this:
c4650843   Etienne Pallier   Ajout du dossier ...
74
75
76

```
array(
d06254b2   Etienne Pallier   bugfix plugin mig...
77
78
79
80
    0: Stmt_Echo(
        exprs: array(
            0: Scalar_String(
                value: Hi
c4650843   Etienne Pallier   Ajout du dossier ...
81
            )
d06254b2   Etienne Pallier   bugfix plugin mig...
82
83
84
85
86
            1: Expr_FuncCall(
                name: Name(
                    parts: array(
                        0: hi
                        1: getTarget
c4650843   Etienne Pallier   Ajout du dossier ...
87
88
                    )
                )
d06254b2   Etienne Pallier   bugfix plugin mig...
89
                args: array(
c4650843   Etienne Pallier   Ajout du dossier ...
90
91
92
93
94
95
96
                )
            )
        )
    )
)
```

d06254b2   Etienne Pallier   bugfix plugin mig...
97
98
Thus `$stmts` will contain an array with only one node, with this node being an instance of
`PhpParser\Node\Stmt\Echo_`.
c4650843   Etienne Pallier   Ajout du dossier ...
99

d06254b2   Etienne Pallier   bugfix plugin mig...
100
As PHP is a large language there are approximately 140 different nodes. In order to make work
c4650843   Etienne Pallier   Ajout du dossier ...
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
with them easier they are grouped into three categories:

 * `PhpParser\Node\Stmt`s are statement nodes, i.e. language constructs that do not return
   a value and can not occur in an expression. For example a class definition is a statement.
   It doesn't return a value and you can't write something like `func(class A {});`.
 * `PhpParser\Node\Expr`s are expression nodes, i.e. language constructs that return a value
   and thus can occur in other expressions. Examples of expressions are `$var`
   (`PhpParser\Node\Expr\Variable`) and `func()` (`PhpParser\Node\Expr\FuncCall`).
 * `PhpParser\Node\Scalar`s are nodes representing scalar values, like `'string'`
   (`PhpParser\Node\Scalar\String_`), `0` (`PhpParser\Node\Scalar\LNumber`) or magic constants
   like `__FILE__` (`PhpParser\Node\Scalar\MagicConst\File`). All `PhpParser\Node\Scalar`s extend
   `PhpParser\Node\Expr`, as scalars are expressions, too.
 * There are some nodes not in either of these groups, for example names (`PhpParser\Node\Name`)
   and call arguments (`PhpParser\Node\Arg`).

d06254b2   Etienne Pallier   bugfix plugin mig...
116
117
Some node class names have a trailing `_`. This is used whenever the class name would otherwise clash
with a PHP keyword.
c4650843   Etienne Pallier   Ajout du dossier ...
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

Every node has a (possibly zero) number of subnodes. You can access subnodes by writing
`$node->subNodeName`. The `Stmt\Echo_` node has only one subnode `exprs`. So in order to access it
in the above example you would write `$stmts[0]->exprs`. If you wanted to access the name of the function
call, you would write `$stmts[0]->exprs[1]->name`.

All nodes also define a `getType()` method that returns the node type. The type is the class name
without the `PhpParser\Node\` prefix and `\` replaced with `_`. It also does not contain a trailing
`_` for reserved-keyword class names.

It is possible to associate custom metadata with a node using the `setAttribute()` method. This data
can then be retrieved using `hasAttribute()`, `getAttribute()` and `getAttributes()`.

By default the lexer adds the `startLine`, `endLine` and `comments` attributes. `comments` is an array
of `PhpParser\Comment[\Doc]` instances.

The start line can also be accessed using `getLine()`/`setLine()` (instead of `getAttribute('startLine')`).
The last doc comment from the `comments` attribute can be obtained using `getDocComment()`.

Pretty printer
--------------

The pretty printer component compiles the AST back to PHP code. As the parser does not retain formatting
information the formatting is done using a specified scheme. Currently there is only one scheme available,
namely `PhpParser\PrettyPrinter\Standard`.

```php
use PhpParser\Error;
use PhpParser\ParserFactory;
use PhpParser\PrettyPrinter;

$code = "<?php echo 'Hi ', hi\\getTarget();";

$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
$prettyPrinter = new PrettyPrinter\Standard;

try {
    // parse
    $stmts = $parser->parse($code);

    // change
    $stmts[0]         // the echo statement
          ->exprs     // sub expressions
          [0]         // the first of them (the string node)
          ->value     // it's value, i.e. 'Hi '
          = 'Hello '; // change to 'Hello '

    // pretty print
    $code = $prettyPrinter->prettyPrint($stmts);

    echo $code;
} catch (Error $e) {
    echo 'Parse Error: ', $e->getMessage();
}
```

The above code will output:

d06254b2   Etienne Pallier   bugfix plugin mig...
176
    <?php echo 'Hello ', hi\getTarget();
c4650843   Etienne Pallier   Ajout du dossier ...
177
178
179
180
181
182
183
184
185
186

As you can see the source code was first parsed using `PhpParser\Parser->parse()`, then changed and then
again converted to code using `PhpParser\PrettyPrinter\Standard->prettyPrint()`.

The `prettyPrint()` method pretty prints a statements array. It is also possible to pretty print only a
single expression using `prettyPrintExpr()`.

The `prettyPrintFile()` method can be used to print an entire file. This will include the opening `<?php` tag
and handle inline HTML as the first/last statement more gracefully.

c4650843   Etienne Pallier   Ajout du dossier ...
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
Node traversation
-----------------

The above pretty printing example used the fact that the source code was known and thus it was easy to
write code that accesses a certain part of a node tree and changes it. Normally this is not the case.
Usually you want to change / analyze code in a generic way, where you don't know how the node tree is
going to look like.

For this purpose the parser provides a component for traversing and visiting the node tree. The basic
structure of a program using this `PhpParser\NodeTraverser` looks like this:

```php
use PhpParser\NodeTraverser;
use PhpParser\ParserFactory;
use PhpParser\PrettyPrinter;

$parser        = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
$traverser     = new NodeTraverser;
$prettyPrinter = new PrettyPrinter\Standard;

// add your visitor
$traverser->addVisitor(new MyNodeVisitor);

try {
    $code = file_get_contents($fileName);

    // parse
    $stmts = $parser->parse($code);

    // traverse
    $stmts = $traverser->traverse($stmts);

    // pretty print
    $code = $prettyPrinter->prettyPrintFile($stmts);

    echo $code;
} catch (PhpParser\Error $e) {
    echo 'Parse Error: ', $e->getMessage();
}
```

The corresponding node visitor might look like this:

```php
use PhpParser\Node;
use PhpParser\NodeVisitorAbstract;

class MyNodeVisitor extends NodeVisitorAbstract
{
    public function leaveNode(Node $node) {
        if ($node instanceof Node\Scalar\String_) {
            $node->value = 'foo';
        }
    }
}
```

The above node visitor would change all string literals in the program to `'foo'`.

All visitors must implement the `PhpParser\NodeVisitor` interface, which defines the following four
methods:

```php
public function beforeTraverse(array $nodes);
public function enterNode(\PhpParser\Node $node);
public function leaveNode(\PhpParser\Node $node);
public function afterTraverse(array $nodes);
```

The `beforeTraverse()` method is called once before the traversal begins and is passed the nodes the
traverser was called with. This method can be used for resetting values before traversation or
preparing the tree for traversal.

The `afterTraverse()` method is similar to the `beforeTraverse()` method, with the only difference that
it is called once after the traversal.

The `enterNode()` and `leaveNode()` methods are called on every node, the former when it is entered,
i.e. before its subnodes are traversed, the latter when it is left.

All four methods can either return the changed node or not return at all (i.e. `null`) in which
case the current node is not changed.

The `enterNode()` method can additionally return the value `NodeTraverser::DONT_TRAVERSE_CHILDREN`,
d06254b2   Etienne Pallier   bugfix plugin mig...
270
which instructs the traverser to skip all children of the current node.
c4650843   Etienne Pallier   Ajout du dossier ...
271
272
273
274
275
276
277
278
279
280

The `leaveNode()` method can additionally return the value `NodeTraverser::REMOVE_NODE`, in which
case the current node will be removed from the parent array. Furthermore it is possible to return
an array of nodes, which will be merged into the parent array at the offset of the current node.
I.e. if in `array(A, B, C)` the node `B` should be replaced with `array(X, Y, Z)` the result will
be `array(A, X, Y, Z, C)`.

Instead of manually implementing the `NodeVisitor` interface you can also extend the `NodeVisitorAbstract`
class, which will define empty default implementations for all the above methods.

c4650843   Etienne Pallier   Ajout du dossier ...
281
282
283
The NameResolver node visitor
-----------------------------

d06254b2   Etienne Pallier   bugfix plugin mig...
284
One visitor is already bundled with the package: `PhpParser\NodeVisitor\NameResolver`. This visitor
c4650843   Etienne Pallier   Ajout du dossier ...
285
286
287
288
289
290
291
292
293
294
helps you work with namespaced code by trying to resolve most names to fully qualified ones.

For example, consider the following code:

    use A as B;
    new B\C();

In order to know that `B\C` really is `A\C` you would need to track aliases and namespaces yourself.
The `NameResolver` takes care of that and resolves names as far as possible.

d06254b2   Etienne Pallier   bugfix plugin mig...
295
After running it most names will be fully qualified. The only names that will stay unqualified are
c4650843   Etienne Pallier   Ajout du dossier ...
296
297
298
299
300
301
302
unqualified function and constant names. These are resolved at runtime and thus the visitor can't
know which function they are referring to. In most cases this is a non-issue as the global functions
are meant.

Also the `NameResolver` adds a `namespacedName` subnode to class, function and constant declarations
that contains the namespaced name instead of only the shortname that is available via `name`.

c4650843   Etienne Pallier   Ajout du dossier ...
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
Example: Converting namespaced code to pseudo namespaces
--------------------------------------------------------

A small example to understand the concept: We want to convert namespaced code to pseudo namespaces
so it works on 5.2, i.e. names like `A\\B` should be converted to `A_B`. Note that such conversions
are fairly complicated if you take PHP's dynamic features into account, so our conversion will
assume that no dynamic features are used.

We start off with the following base code:

```php
use PhpParser\ParserFactory;
use PhpParser\PrettyPrinter;
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitor\NameResolver;

$inDir  = '/some/path';
$outDir = '/some/other/path';

$parser        = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
$traverser     = new NodeTraverser;
$prettyPrinter = new PrettyPrinter\Standard;

$traverser->addVisitor(new NameResolver); // we will need resolved names
$traverser->addVisitor(new NamespaceConverter); // our own node visitor

// iterate over all .php files in the directory
$files = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($inDir));
$files = new \RegexIterator($files, '/\.php$/');

foreach ($files as $file) {
    try {
        // read the file that should be converted
d06254b2   Etienne Pallier   bugfix plugin mig...
336
        $code = file_get_contents($file);
c4650843   Etienne Pallier   Ajout du dossier ...
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367

        // parse
        $stmts = $parser->parse($code);

        // traverse
        $stmts = $traverser->traverse($stmts);

        // pretty print
        $code = $prettyPrinter->prettyPrintFile($stmts);

        // write the converted file to the target directory
        file_put_contents(
            substr_replace($file->getPathname(), $outDir, 0, strlen($inDir)),
            $code
        );
    } catch (PhpParser\Error $e) {
        echo 'Parse Error: ', $e->getMessage();
    }
}
```

Now lets start with the main code, the `NodeVisitor\NamespaceConverter`. One thing it needs to do
is convert `A\\B` style names to `A_B` style ones.

```php
use PhpParser\Node;

class NamespaceConverter extends \PhpParser\NodeVisitorAbstract
{
    public function leaveNode(Node $node) {
        if ($node instanceof Node\Name) {
d06254b2   Etienne Pallier   bugfix plugin mig...
368
            return new Node\Name($node->toString('_'));
c4650843   Etienne Pallier   Ajout du dossier ...
369
370
371
372
373
374
375
        }
    }
}
```

The above code profits from the fact that the `NameResolver` already resolved all names as far as
possible, so we don't need to do that. We only need to create a string with the name parts separated
d06254b2   Etienne Pallier   bugfix plugin mig...
376
by underscores instead of backslashes. This is what `$node->toString('_')` does. (If you want to
c4650843   Etienne Pallier   Ajout du dossier ...
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
create a name with backslashes either write `$node->toString()` or `(string) $node`.) Then we create
a new name from the string and return it. Returning a new node replaces the old node.

Another thing we need to do is change the class/function/const declarations. Currently they contain
only the shortname (i.e. the last part of the name), but they need to contain the complete name including
the namespace prefix:

```php
use PhpParser\Node;
use PhpParser\Node\Stmt;

class NodeVisitor_NamespaceConverter extends \PhpParser\NodeVisitorAbstract
{
    public function leaveNode(Node $node) {
        if ($node instanceof Node\Name) {
d06254b2   Etienne Pallier   bugfix plugin mig...
392
            return new Node\Name($node->toString('_'));
c4650843   Etienne Pallier   Ajout du dossier ...
393
394
395
        } elseif ($node instanceof Stmt\Class_
                  || $node instanceof Stmt\Interface_
                  || $node instanceof Stmt\Function_) {
d06254b2   Etienne Pallier   bugfix plugin mig...
396
            $node->name = $node->namespacedName->toString('_');
c4650843   Etienne Pallier   Ajout du dossier ...
397
398
        } elseif ($node instanceof Stmt\Const_) {
            foreach ($node->consts as $const) {
d06254b2   Etienne Pallier   bugfix plugin mig...
399
                $const->name = $const->namespacedName->toString('_');
c4650843   Etienne Pallier   Ajout du dossier ...
400
401
402
403
404
405
406
407
408
409
410
411
412
            }
        }
    }
}
```

There is not much more to it than converting the namespaced name to string with `_` as separator.

The last thing we need to do is remove the `namespace` and `use` statements:

```php
use PhpParser\Node;
use PhpParser\Node\Stmt;
c4650843   Etienne Pallier   Ajout du dossier ...
413
414
415
416
417

class NodeVisitor_NamespaceConverter extends \PhpParser\NodeVisitorAbstract
{
    public function leaveNode(Node $node) {
        if ($node instanceof Node\Name) {
d06254b2   Etienne Pallier   bugfix plugin mig...
418
            return new Node\Name($node->toString('_'));
c4650843   Etienne Pallier   Ajout du dossier ...
419
420
421
        } elseif ($node instanceof Stmt\Class_
                  || $node instanceof Stmt\Interface_
                  || $node instanceof Stmt\Function_) {
d06254b2   Etienne Pallier   bugfix plugin mig...
422
            $node->name = $node->namespacedName->toString('_');
c4650843   Etienne Pallier   Ajout du dossier ...
423
424
        } elseif ($node instanceof Stmt\Const_) {
            foreach ($node->consts as $const) {
d06254b2   Etienne Pallier   bugfix plugin mig...
425
                $const->name = $const->namespacedName->toString('_');
c4650843   Etienne Pallier   Ajout du dossier ...
426
427
428
429
430
            }
        } elseif ($node instanceof Stmt\Namespace_) {
            // returning an array merges is into the parent array
            return $node->stmts;
        } elseif ($node instanceof Stmt\Use_) {
d06254b2   Etienne Pallier   bugfix plugin mig...
431
432
            // returning false removed the node altogether
            return false;
c4650843   Etienne Pallier   Ajout du dossier ...
433
434
435
436
437
438
        }
    }
}
```

That's all.