1Performance
2===========
3
4Parsing is computationally expensive task, to which the PHP language is not very well suited.
5Nonetheless, there are a few things you can do to improve the performance of this library, which are
6described in the following.
7
8Xdebug
9------
10
11Running PHP with Xdebug adds a lot of overhead, especially for code that performs many method calls.
12Just by loading Xdebug (without enabling profiling or other more intrusive Xdebug features), you
13can expect that code using PHP-Parser will be approximately *five times slower*.
14
15As such, you should make sure that Xdebug is not loaded when using this library. Note that setting
16the `xdebug.default_enable=0` ini option does *not* disable Xdebug. The *only* way to disable
17Xdebug is to not load the extension in the first place.
18
19If you are building a command-line utility for use by developers (who often have Xdebug enabled),
20you may want to consider automatically restarting PHP with Xdebug unloaded. The
21[composer/xdebug-handler](https://github.com/composer/xdebug-handler) package can be used to do
22this.
23
24If you do run with Xdebug, you may need to increase the `xdebug.max_nesting_level` option to a
25higher level, such as 3000. While the parser itself is recursion free, most other code working on
26the AST uses recursion and will generate an error if the value of this option is too low.
27
28Assertions
29----------
30
31Assertions should be disabled in a production context by setting `zend.assertions=-1` (or
32`zend.assertions=0` if set at runtime). The library currently doesn't make heavy use of assertions,
33but they are used in an increasing number of places.
34
35Object reuse
36------------
37
38Many objects in this project are designed for reuse. For example, one `Parser` object can be used to
39parse multiple files.
40
41When possible, objects should be reused rather than being newly instantiated for every use. Some
42objects have expensive initialization procedures, which will be unnecessarily repeated if the object
43is not reused. (Currently two objects with particularly expensive setup are parsers and pretty
44printers, though the details might change between versions of this library.)
45