tolerant-php-parser/Contributing.md

Contributing

We would love to have you as a contributor! There are many ways to contribute to the project, including: reporting issues, requesting features, submitting suggestions, and making pull requests.

Reporting Issues

Please include enough information in each issue to reproduce the bug. Extra points if you submit a failing test case to the tests/cases folder, and also include the test in tests/skipped.json - this will not run as part of the testsuite by default, but make it very easy for others to contribute a fix (or read on if you want to do it yourself 😉).

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

💡 looking for your first PR? Take a look through the issue tracker, search the codebase for TODOs, or try enabling one of the test cases in skipped.json.

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/

Running performance tests

php -d memory_limit=500M validation/ParserPerformance.php

Note that there will be a lot of variance between runs. In the future, we plan to set up an environment that can provide assurance of statistical significance.

Example PRs

💡 Note - These examples aren't perfect... they were from early "exploratory" stages of the project, and the codebase has changed a bit since then. If you spot a particularly educational PR, feel free to suggest it for the list!

Adding a Feature

This commit adds return-statement support. There are a few things to note.

1. Naming consistency with the PHP language spec
2. Formatting consistency with rest of codebase.
3. TODO comment for any missing functionality (now that we're on GitHub, a reference to a filed issue would also be nice)
4. Test cases that provide an input .php file and output .tree file (any cases in tests/cases)

Fixing an issue

This commit fixes a simple issue related to if-statement parsing. Note that there are more test case changes than lines of code.

Adding a Test Case

The more tests the better, so we also accept test contributions without any functional code changes.

• Adding tests - Parser test cases provide an input .php file and an output .tree file (Lexical test cases provide an output .tokens file). The output .tree file need not be generated by hand, and will be overwritten if the test is failing. To generate the tree file, run the "grammar" test suite. If you've made edits to the file that you'd like to keep, make sure you stage your changes in git so that they are not reverted.
• Skipping a failing test - we like to keep all of our tests green to to make it easier to detect regressions, so this list keeps track of everything we want to come back to.