tolerant-php-parser/GettingStarted.md

Getting Started

Set up your PHP Environment (PHP 7.1 and Composer)

Any version of PHP 7 should work, but as we are still in our early stages, the "golden path" for now will be PHP 7.1

Windows

1. Download PHP 7.1
2. Download and install Composer

Ensure your version of PHP is properly configured by running php -v in the command prompt. If it's not PHP 7.1, then you have a few different options for how to access it:

1. reference it directly: c:\PHP7.1\php.exe -v
2. Prepend the directory to your system PATH
3. create an alias using doskey: doskey php7="C:\PHP7.1\php.exe" $*

Mac

1. Install Homebrew
2. Install PHP 7.1 and Composer

brew tap homebrew/php
brew install php71
brew install composer

Ensure your version of PHP is properly configured by running php -v. If it's not PHP7, then you have a few different options for how to access it:

1. reference it directly: /usr/local/Cellar/php71/7.1.0_11/bin/php -v
2. alias it in your ~/.bash_profile: alias php7=/usr/local/Cellar/php71/7.1.0_11/bin/php
3. add it to your PATH in ~/.bash_profile: export PATH="/usr/local/sbin:$PATH"

Reference tolerant-php-parser from your PHP project

The parser is not yet available on packagist, so you'll instead have to specify the location to the github repository.

In your project's composer.json, specify the minimum-stability, repositories, and require attributes as follows:

{
    "minimum-stability": "dev",
    "repositories": [
        {
            "type": "git",
            "url": "https://github.com/mousetraps/tolerant-php-parser.git"
        }
    ],
    "require": {
        "mousetraps/tolerant-php-parser": "master"
    }
}

Once you've referenced the parser from your project, run composer install, and be on your way!

Ready, set, parse!

<?php
$parser = new \PhpParser\Parser();
$fileContents = file_get_contents($myFilename);
$ast = $parser->parseSourceFile($fileContents); # returns an AST representing source file
$errors =  \PhpParser\Utilities::getDiagnostics($ast); # get errors from AST Node

Play around with the AST!

In order to help you get a sense for the features and shape of the tree, we've also included a Parser Playground Extension that makes use of the parser to provide error tooltips.

1. Download the VSIX
2. Point it to your PHP Path
3. Disable other extensions in the workspace to ensure minimal interference

If you see something that looks off, please file an issue, or better yet, contribute as a test case.

Contributing

Building and Running

1. Fork and clone the repository.
2. composer-install
3. vendor\bin\phpunit from the root project directory to run the tests to run all the test suites defined in phpunit.xml. To run individual suites, run vendor\bin\phpunit --testsuite <test suite name>. Note that the validation test suite requires you to also include relevant submodules: git submodule update --init --recursive

Debugging

For debugging, we recommend you install and configure Felix Becker's PHP Debug extension. For debugging the tests in this project, you can run the Listen for XDebug launch configuration included in this project, and then from the command line:

php -debug -d zend_extension=<my-path-to-extension> -d xdebug.remote_enable=1 -d xdebug.remote_autostart=1 vendor\phpunit\phpunit\phpunit <my-phpunit-arguments>

Additionally some of the tests output files for failed tests to make it easier to debug. See the notes in phpunit.xml for more info about this behavior.

Running code coverage

After enabling xdebug, run code coverage by executing:

php -d memory_limit=500M vendor/bin/phpunit --coverage-html tmp/ tests/