From a839235e96c052524007153cc009ed6dcee716f8 Mon Sep 17 00:00:00 2001 From: Laurent Laville Date: Fri, 5 Jul 2024 08:59:46 +0000 Subject: [PATCH] prepare feature release 9.4.0 --- .changes/9.4.0.md | 27 +++ CHANGELOG.md | 27 +++ bin/phplint | 9 + docs/architecture/output.md | 50 +++++- docs/configuration.md | 290 +++++++++++++++++++++++++-------- docs/contributing.md | 10 +- docs/installation.md | 8 +- docs/usage/README.md | 10 +- docs/usage/console.md | 5 +- docs/usage/programmatically.md | 6 +- examples/no-source-to-lint.php | 11 +- src/Console/Application.php | 2 +- 12 files changed, 353 insertions(+), 102 deletions(-) create mode 100644 .changes/9.4.0.md diff --git a/.changes/9.4.0.md b/.changes/9.4.0.md new file mode 100644 index 00000000..6f83f4bc --- /dev/null +++ b/.changes/9.4.0.md @@ -0,0 +1,27 @@ + +## 9.4.0 - 2024-07-05 + +### Added + +- [#208](https://github.com/overtrue/phplint/issues/208) : Add support to more output formats +- support to `checkstyle` format + +### Changed + +- support to `sarif` format is now optional. Requires to install extra package `bartlett/sarif-php-converters`. + +> [!NOTE] +> +> `sarif` format is a good example of how to use custom format not provided by current PHPLint distribution. +> Read how to use it at + +### Removed + +- legacy `log-*` and `sarif-converter` options +- useless help column in configuration table when verbose mode is active + +### Fixed + +- shortcut of `progress` option is now detected on `phplint` binary launcher. + +**Full Changelog**: [9.3.1...9.4.0](https://github.com/overtrue/phplint/compare/9.3.1...9.4.0) diff --git a/CHANGELOG.md b/CHANGELOG.md index 44829d1e..4869ceeb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), and is generated by [Changie](https://github.com/miniscruff/changie). +## 9.4.0 - 2024-07-05 + +### Added + +- [#208](https://github.com/overtrue/phplint/issues/208) : Add support to more output formats +- support to `checkstyle` format + +### Changed + +- support to `sarif` format is now optional. Requires to install extra package `bartlett/sarif-php-converters`. + +> [!NOTE] +> +> `sarif` format is a good example of how to use custom format not provided by current PHPLint distribution. +> Read how to use it at + +### Removed + +- legacy `log-*` and `sarif-converter` options +- useless help column in configuration table when verbose mode is active + +### Fixed + +- shortcut of `progress` option is now detected on `phplint` binary launcher. + +**Full Changelog**: [9.3.1...9.4.0](https://github.com/overtrue/phplint/compare/9.3.1...9.4.0) + ## 9.3.1 - 2024-05-17 ### Fixed diff --git a/bin/phplint b/bin/phplint index b1b5a959..ad5d926b 100755 --- a/bin/phplint +++ b/bin/phplint @@ -1,6 +1,15 @@ #!/usr/bin/env php - + - /path/to/fixtures/syntax_error.php - /path/to/fixtures/php-8.2_syntax.php + /path/to/fixtures/syntax_error.php + /path/to/fixtures/php-8.2_syntax.php ``` -[bartlett/graph-uml]: https://packagist.org/packages/bartlett/graph-uml -[symfony/console]: https://github.com/symfony/console -[symfony-console-events]: https://symfony.com/doc/current/components/console/events.html -[chain-of-responsibility-pattern]: https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern +## `CheckstyleOutput` handler + +This handler is responsible to print PHPLint results on Checkstyle XML format. For example: + +```xml + + + + + + + + + + + + +``` + +## `SarifOutput` handler + +> [!NOTE] +> +> Since version 9.4.0, this format is optional and requires an extra package to be installed. +> +> ```composer require --dev bartlett/sarif-php-converters``` +This handler is responsible to print PHPLint results on SARIF JSON format. +Learn more at ## `LinterOutput` object This object represent the PHPLint results of all file checked. It will allow to easily communicate with other extension or output handler. Thanks to the Event-Dispatcher component. + +[bartlett/graph-uml]: https://packagist.org/packages/bartlett/graph-uml +[symfony/console]: https://github.com/symfony/console +[symfony-console-events]: https://symfony.com/doc/current/components/console/events.html +[chain-of-responsibility-pattern]: https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern + diff --git a/docs/configuration.md b/docs/configuration.md index 12b8e461..b115521e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,38 +1,42 @@ + # Configuration -1. [Path][path] -1. [Exclude][exclude] -1. [Extensions][extensions] -1. [Show Warnings][warning] -1. [Jobs][jobs] -1. [Cache][cache] -1. [No caching][no-cache] -1. [Memory limit][memory-limit] -1. [JSON output][log-json] -1. [XML output][log-xml] -1. [SARIF output][log-sarif] -1. [Exit Code][no-files-exit-code] +## Table Of Contents + +1. [Path](#path) +2. [Exclude](#exclude) +3. [Extensions](#extensions) +4. [Show Warnings](#show-warnings) +5. [Jobs](#jobs) +6. [Cache](#cache) +7. [No caching](#no-caching) +8. [Memory limit](#memory-limit) +9. [JSON output](#json-output) +10. [Junit output](#junit-output) +11. [Checkstyle output](#checkstyle-output) +12. [SARIF output](#sarif-output) +13. [Exit Code](#exit-code) The `phplint` command relies on a configuration file for loading settings. If a configuration file is not specified through the `--configuration|-c` option, following file will be used : `.phplint.yml`. If no configuration file is found, PHPLint will proceed with the default settings. -## Path (`path`) +## Path The `path` (`string`|`string[]` default `.`) setting is used to specify where all directories and files to scan should resolve to. If not specified, the base path used is the current working directory. -## Exclude (`exclude`) +## Exclude The `exclude` (`string[]` default `[]`) setting is a list of directory paths relative to the base `path`. All files listed inside these paths won't be scanned by PHPLint. -## Extensions (`extensions`) +## Extensions The `extensions` (`string[]` default `[php]`) setting will check only files with selected extensions. -## Show Warnings (`warning`) +## Show Warnings Use the `warning` (`bool` default `false`) setting (with `true`) if you want to show PHP Warnings too. For example: @@ -40,13 +44,13 @@ For example: ```php - + /absolute/path/to/tests/fixtures/syntax_error.php @@ -137,9 +162,37 @@ For example: ``` -## SARIF output (`log-sarif`) +## Checkstyle output + +The `format` setting with value `checkstyle` allow to write results in a Checkstyle XML format. + +For example: + +```xml + + + + + + + + + + + + +``` + +## SARIF output + +> [!NOTE] +> +> Since version 9.4.0, this format is optional and requires an extra package to be installed. +> +> ```composer require --dev bartlett/sarif-php-converters``` + +The `format` setting with value `'\Overtrue\PHPLint\Output\SarifOutput'` allow to write results in a SARIF 2.1.0 JSON format. -The `log-sarif` (`null`|`string` default `null` to print results to standard output) setting allow to write results in a SARIF JSON format. For example: ```json @@ -157,13 +210,47 @@ For example: "fullDescription": { "text": "PHPLint is a tool that can speed up linting of php files by running several lint processes at once." }, - "semanticVersion": "9.2.0.0", - "informationUri": "https://github.com/overtrue/phplint" - } + "fullName": "PHPLint version 9.4.0 by overtrue and contributors", + "semanticVersion": "9.4.0", + "informationUri": "https://github.com/overtrue/phplint", + "rules": [ + { + "id": "PHPLINT101", + "shortDescription": { + "text": "Syntax error" + }, + "fullDescription": { + "text": "Syntax error detected when lint a file" + }, + "helpUri": "https://www.php.net/manual/en/langref.php", + "help": { + "text": "https://www.php.net/manual/en/features.commandline.options.php" + } + } + ] + }, + "extensions": [ + { + "name": "bartlett/sarif-php-converters", + "shortDescription": { + "text": "PHPLint SARIF Converter" + }, + "version": "1.0.0" + } + ] }, "invocations": [ { "executionSuccessful": true, + "commandLine": "bin/phplint", + "arguments": [ + "--no-cache", + "--format", + "\\Overtrue\\PHPLint\\Output\\SarifOutput", + "-v", + "src/", + "tests/" + ], "workingDirectory": { "uri": "file:///shared/backups/github/phplint/" } @@ -179,6 +266,7 @@ For example: "message": { "text": "unexpected end of file in line 4" }, + "ruleId": "PHPLINT101", "locations": [ { "physicalLocation": { @@ -187,16 +275,70 @@ For example: "uriBaseId": "WORKINGDIR" }, "region": { - "startLine": 4 + "startLine": 4, + "snippet": { + "rendered": { + "text": "\u001b[31m > \u001b[0m\u001b[90m4| \u001b[0m" + } + } + }, + "contextRegion": { + "startLine": 2, + "endLine": 6, + "snippet": { + "rendered": { + "text": "\u001b[31m > \u001b[0m\u001b[90m2| \u001b[0m\n \u001b[90m3| \u001b[0m\u001b[32mprint(\u001b[0m\u001b[39m$a\u001b[0m\u001b[32m)\u001b[0m\n \u001b[90m4| \u001b[0m" + } + } } } } - ] + ], + "partialFingerprints": { + "PHPLINT101": "9d2c5cee410c5007acb62ee25b9a0dfb740fb8f531235e6abc5dd7535930ef2f" + } + }, + { + "message": { + "text": "False can not be used as a standalone type in line 12" + }, + "ruleId": "PHPLINT101", + "locations": [ + { + "physicalLocation": { + "artifactLocation": { + "uri": "tests/fixtures/php-8.2_syntax.php", + "uriBaseId": "WORKINGDIR" + }, + "region": { + "startLine": 12, + "snippet": { + "rendered": { + "text": "\u001b[31m > \u001b[0m\u001b[90m12| \u001b[0m\u001b[32mfunction \u001b[0m\u001b[39malwaysReturnsFalse\u001b[0m\u001b[32m(): \u001b[0m\u001b[39mfalse\u001b[0m" + } + } + }, + "contextRegion": { + "startLine": 10, + "endLine": 14, + "snippet": { + "rendered": { + "text": "\u001b[31m > \u001b[0m\u001b[90m10| \u001b[0m\u001b[33m */\u001b[0m\n \u001b[90m11| \u001b[0m\n \u001b[90m12| \u001b[0m\u001b[32mfunction \u001b[0m\u001b[39malwaysReturnsFalse\u001b[0m\u001b[32m(): \u001b[0m\u001b[39mfalse\u001b[0m\n \u001b[90m13| \u001b[0m\u001b[32m{\u001b[0m\n \u001b[90m14| \u001b[0m\u001b[32m}\u001b[0m" + } + } + } + } + } + ], + "partialFingerprints": { + "PHPLINT101": "b4f5ba1d66790be578109d251ced990b42fe6117554a275142ab750f50ca39f4" + } }, { "message": { "text": " declare(encoding=...) ignored because Zend multibyte feature is turned off by settings in line 12" }, + "ruleId": "PHPLINT101", "locations": [ { "physicalLocation": { @@ -205,32 +347,42 @@ For example: "uriBaseId": "WORKINGDIR" }, "region": { - "startLine": 12 + "startLine": 12, + "snippet": { + "rendered": { + "text": "\u001b[31m > \u001b[0m\u001b[90m12| \u001b[0m\u001b[32mdeclare(\u001b[0m\u001b[39mencoding\u001b[0m\u001b[32m=\u001b[0m\u001b[31m\"utf8\"\u001b[0m\u001b[32m);\u001b[0m" + } + } + }, + "contextRegion": { + "startLine": 10, + "endLine": 14, + "snippet": { + "rendered": { + "text": "\u001b[31m > \u001b[0m\u001b[90m10| \u001b[0m\u001b[33m */\u001b[0m\n \u001b[90m11| \u001b[0m\n \u001b[90m12| \u001b[0m\u001b[32mdeclare(\u001b[0m\u001b[39mencoding\u001b[0m\u001b[32m=\u001b[0m\u001b[31m\"utf8\"\u001b[0m\u001b[32m);\u001b[0m\n \u001b[90m13| \u001b[0m" + } + } } } } - ] + ], + "partialFingerprints": { + "PHPLINT101": "a1bed88116ad4e69c924107f5fa77a80379a08f2723871f5d0af6eb272dcf3c2" + } } - ] + ], + "automationDetails": { + "id": "Daily run 2024-07-05T08:21:21+00:00" + } } ] } ``` -## Exit Code (`no-files-exit-code`) +## Exit Code The `no-files-exit-code` (`bool` default `false`) setting allow to exit `phplint` command with failure (status code `1`) when no files processed. By default, `phplint` exit with success (status code `0`) -[path]: #path-path -[exclude]: #exclude-exclude -[extensions]: #extensions-extensions -[warning]: #show-warnings-warning -[jobs]: #jobs-jobs -[cache]: #cache-cache -[no-cache]: #no-caching-no-cache -[memory-limit]: #memory-limit-memory-limit -[log-json]: #json-output-log-json -[log-xml]: #xml-output-log-junit -[log-sarif]: #sarif-output-log-sarif -[no-files-exit-code]: #exit-code-no-files-exit-code \ No newline at end of file +[symfony/cache]: https://github.com/symfony/cache/ +[shorthand-byte-options]: https://www.php.net/manual/en/faq.using.php#faq.using.shorthandbytes diff --git a/docs/contributing.md b/docs/contributing.md index 9fe83149..0d669f38 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -18,11 +18,11 @@ This check is only for maintainers of this project to prepare a new release and ## Workflow for Pull Requests 1. Fork the repository. -1. Create your branch from `main` if you plan to implement new functionality or change existing code significantly. -1. Implement your change and add tests for it. -1. Ensure the test suite passes. -1. Ensure the code complies with our coding guidelines. -1. Send your Pull Request +2. Create your branch from `main` if you plan to implement new functionality or change existing code significantly. +3. Implement your change and add tests for it. +4. Ensure the test suite passes. +5. Ensure the code complies with our coding guidelines. +6. Send your Pull Request ## Fork the PHPLint repository diff --git a/docs/installation.md b/docs/installation.md index 7f98c2bc..d48af523 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,10 +1,10 @@ # Installation 1. [Requirements](#requirements) -1. [PHAR](#phar) -1. [Docker](#docker) -1. [Phive](#phive) -1. [Composer](#composer) +2. [PHAR](#phar) +3. [Docker](#docker) +4. [Phive](#phive) +5. [Composer](#composer) ## Requirements diff --git a/docs/usage/README.md b/docs/usage/README.md index 6ac5624a..ee21c8d7 100644 --- a/docs/usage/README.md +++ b/docs/usage/README.md @@ -1,8 +1,8 @@ # Usage 1. [Console CLI](console.md) -1. [Docker CLI](docker.md) -1. [GitHub Actions](github-actions.md) -1. [GitLab CI](gitlab-ci.md) -1. [Other CI Pipelines](other-ci.md) -1. [Programmatically](programmatically.md) +2. [Docker CLI](docker.md) +3. [GitHub Actions](github-actions.md) +4. [GitLab CI](gitlab-ci.md) +5. [Other CI Pipelines](other-ci.md) +6. [Programmatically](programmatically.md) diff --git a/docs/usage/console.md b/docs/usage/console.md index 2aa33d8a..342c9e9a 100644 --- a/docs/usage/console.md +++ b/docs/usage/console.md @@ -45,11 +45,12 @@ Options: --no-cache Ignore cached data -p, --progress=PROGRESS Show the progress output --no-progress Hide the progress output - --log-json[=LOG-JSON] Log scan results in JSON format to file (default: standard output) - --log-junit[=LOG-JUNIT] Log scan results in JUnit XML format to file (default: standard output) + -o, --output=OUTPUT Generate an output to the specified path (default: standard output) + --format=FORMAT Format of requested reports (multiple values allowed) -w, --warning Also show warnings --memory-limit=MEMORY-LIMIT Memory limit for analysis --ignore-exit-code Ignore exit codes so there are no "failure" exit code even when no files processed + --bootstrap=BOOTSTRAP A PHP script that is included before the linter run -h, --help Display help for the given command. When no command is given display help for the lint command -q, --quiet Do not output any message -V, --version Display this application version diff --git a/docs/usage/programmatically.md b/docs/usage/programmatically.md index 317e7d5e..1a5f3204 100644 --- a/docs/usage/programmatically.md +++ b/docs/usage/programmatically.md @@ -1,6 +1,8 @@ # Programmatically ```php + [__DIR__ . '/src', __DIR__ . '/tests'], + 'path' => [dirname(__DIR__) . '/src', dirname(__DIR__) . '/tests'], '--no-configuration' => true, '--no-cache' => true, '--exclude' => ['vendor'], @@ -25,9 +27,7 @@ $input = new ArrayInput($arguments, $definition); $configResolver = new ConsoleOptionsResolver($input); $finder = new Finder($configResolver); - $linter = new Linter($configResolver, $dispatcher); - $results = $linter->lintFiles($finder->getFiles()); var_dump($results->getErrors()); diff --git a/examples/no-source-to-lint.php b/examples/no-source-to-lint.php index 71567b72..ed475eeb 100644 --- a/examples/no-source-to-lint.php +++ b/examples/no-source-to-lint.php @@ -32,12 +32,11 @@ $finder = new Finder($configResolver); $linter = new Linter($configResolver, $dispatcher); -$results = $linter->lintFiles($finder->getFiles()); - -var_dump("Files checked :", count($results)); +try { + $results = $linter->lintFiles($finder->getFiles()); +} catch (Throwable $e) { +} if (count($results) === 0) { - throw new LogicException( - sprintf("Could not find any files to lint with this Finder %s", json_encode($finder)) - ); + printf("Could not find any files to lint with this Finder %s" . PHP_EOL, json_encode($finder)); } diff --git a/src/Console/Application.php b/src/Console/Application.php index 6508aaf3..179ebe6d 100644 --- a/src/Console/Application.php +++ b/src/Console/Application.php @@ -36,7 +36,7 @@ final class Application extends BaseApplication { public const NAME = 'phplint'; - public const VERSION = '9.4.0-dev'; + public const VERSION = '9.4.0'; public function __construct() {