www.aleph1.co.uk Git - yaffs-website/blob - vendor/nikic/php-parser/doc/component/Error_handling.markdown

   1 Error handling
   2 ==============
   3
   4 Errors during parsing or analysis are represented using the `PhpParser\Error` exception class. In addition to an error
   5 message, an error can also store additional information about the location the error occurred at.
   6
   7 How much location information is available depends on the origin of the error and how many lexer attributes have been
   8 enabled. At a minimum the start line of the error is usually available.
   9
  10 Column information
  11 ------------------
  12
  13 In order to receive information about not only the line, but also the column span an error occurred at, the file
  14 position attributes in the lexer need to be enabled:
  15
  16 ```php
  17 $lexer = new PhpParser\Lexer(array(
  18     'usedAttributes' => array('comments', 'startLine', 'endLine', 'startFilePos', 'endFilePos'),
  19 ));
  20 $parser = (new PhpParser\ParserFactory)->create(PhpParser\ParserFactory::PREFER_PHP7, $lexer);
  21
  22 try {
  23     $stmts = $parser->parse($code);
  24     // ...
  25 } catch (PhpParser\Error $e) {
  26     // ...
  27 }
  28 ```
  29
  30 Before using column information its availability needs to be checked with `$e->hasColumnInfo()`, as the precise
  31 location of an error cannot always be determined. The methods for retrieving column information also have to be passed
  32 the source code of the parsed file. An example for printing an error:
  33
  34 ```php
  35 if ($e->hasColumnInfo()) {
  36     echo $e->getRawMessage() . ' from ' . $e->getStartLine() . ':' . $e->getStartColumn($code)
  37         . ' to ' . $e->getEndLine() . ':' . $e->getEndColumn($code);
  38     // or:
  39     echo $e->getMessageWithColumnInfo();
  40 } else {
  41     echo $e->getMessage();
  42 }
  43 ```
  44
  45 Both line numbers and column numbers are 1-based. EOF errors will be located at the position one past the end of the
  46 file.
  47
  48 Error recovery
  49 --------------
  50
  51 The error behavior of the parser (and other components) is controlled by an `ErrorHandler`. Whenever an error is
  52 encountered, `ErrorHandler::handleError()` is invoked. The default error handling strategy is `ErrorHandler\Throwing`,
  53 which will immediately throw when an error is encountered.
  54
  55 To instead collect all encountered errors into an array, while trying to continue parsing the rest of the source code,
  56 an instance of `ErrorHandler\Collecting` can be passed to the `Parser::parse()` method. A usage example:
  57
  58 ```php
  59 $parser = (new PhpParser\ParserFactory)->create(PhpParser\ParserFactory::ONLY_PHP7);
  60 $errorHandler = new PhpParser\ErrorHandler\Collecting;
  61
  62 $stmts = $parser->parse($code, $errorHandler);
  63
  64 if ($errorHandler->hasErrors()) {
  65     foreach ($errorHandler->getErrors() as $error) {
  66         // $error is an ordinary PhpParser\Error
  67     }
  68 }
  69
  70 if (null !== $stmts) {
  71     // $stmts is a best-effort partial AST
  72 }
  73 ```
  74
  75 The `NameResolver` visitor also accepts an `ErrorHandler` as a constructor argument.