From 0bdd41186a8cd7b2c3dbec29ef75a32ce10c742a Mon Sep 17 00:00:00 2001 From: jrfnl Date: Sat, 15 Oct 2022 23:08:32 +0200 Subject: [PATCH 1/3] README/Changelog: various improvements Includes: * Updating the "Tested on PHP" badge to include PHP 8.2. * A few `http` to `https` fixes. * Minor formatting improvements. --- CHANGELOG.md | 17 ++++++++++------- README.md | 37 +++++++++++++++++++++++++++---------- 2 files changed, 37 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ca0df267..a1305411 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to this project will be documented in this file. -This projects adheres to [Keep a CHANGELOG](http://keepachangelog.com/) and uses [Semantic Versioning](http://semver.org/). +This projects adheres to [Keep a CHANGELOG](https://keepachangelog.com/) and uses [Semantic Versioning](https://semver.org/). ## [Unreleased] @@ -13,6 +13,7 @@ _Nothing yet._ ## [1.0.0-alpha3] - 2020-06-29 Notes: + * While still in alpha, some BC-breaks may be introduced. These are clearly indicated in the changelog with the :warning: symbol. * Until PHPCS 4.x has been released, PHPCSUtils does not formally support it, though an effort is made to keep up with the changes and anticipate potential compatibility issues. For testing purposes, the composer configuration allows for PHPCSUtils to be installed with PHPCS 4.x. @@ -26,7 +27,7 @@ Notes: * New [`PHPCSUtils\Utils\ControlStructures::getCaughtExceptions()`][ControlStructures::getCaughtExceptions] method. [#114], [#138] * New [`PHPCSUtils\Utils\UseStatements::splitAndMergeImportUseStatement()`][UseStatements::splitAndMergeImportUseStatement] method. [#117] -#### PHPCS Backcompat +#### PHPCS BackCompat * `BCFile::getMethodProperties()`: support for "static" as a return type (PHP 8). [#134], [PHPCS#2952] @@ -60,7 +61,7 @@ Notes: ### Changed -#### PHPCS Backcompat +#### PHPCS BackCompat * `BCFile::getDeclarationName()`: has been made compatible with PHPCS 4.x. [#110] * `BCFile::getMethodProperties()`: has been made compatible with PHPCS 4.x. [#109] @@ -108,7 +109,7 @@ Notes: * `AbstractArrayDeclarationSniff`: improved parse error handling. [#99] -#### PHPCS Backcompat +#### PHPCS BackCompat * `BCFile::findEndOfStatement()`: now supports arrow functions when used as a function argument, in line with the same change made in PHPCS 3.5.5. [#143] * `BcFile::isReference()`: bug fix, the reference operator was not recognized as such for closures declared to return by reference. [#160], [PHPCS#2977] @@ -178,6 +179,7 @@ Notes: ## [1.0.0-alpha2] - 2020-02-16 Note: + * While still in alpha, some BC-breaks may be introduced. These are clearly indicated in the changelog with the :warning: symbol. ### Added @@ -186,7 +188,7 @@ Note: * New [`PHPCSUtils\Utils\FunctionDeclarations::isArrowFunction()`][FunctionDeclarations::isArrowFunction] method. [#77], [#79] * New [`PHPCSUtils\Utils\FunctionDeclarations::getArrowFunctionOpenClose()`][FunctionDeclarations::getArrowFunctionOpenClose] method. [#77], [#79] -#### PHPCS Backcompat +#### PHPCS BackCompat * `BCFile::isReference()`: support for arrow functions returning by reference. [#77] * `BCFile::getMethodParameters()`: support for arrow functions. [#77], [#79] @@ -217,7 +219,7 @@ Note: ### Changed -#### PHPCS Backcompat +#### PHPCS BackCompat * `BCFile::getCondition()`: sync with PHPCS 3.5.4 - added support for new `$first` parameter. [#73] @@ -251,6 +253,7 @@ Note: ## 1.0.0-alpha1 - 2020-01-23 Initial alpha release containing: + * A `PHPCS23Utils` standard which can be used to allow an external PHPCS standard to be compatible with both PHPCS 2.x as well as 3.x. * A `PHPCSUtils` standard which contains generic utilities which can be used when writing sniffs. **_This standard does not contain any sniffs!_** @@ -265,7 +268,7 @@ This initial alpha release contains the following utility classes: * [`AbstractArrayDeclarationSniff`]: to examine array declarations. -### Backcompat +### BackCompat * [`BCFile`]: Backport of the latest versions of PHPCS native utility functions from the `PHP_CodeSniffer\Files\File` class to make them available in older PHPCS versions without the bugs and other quirks that the older versions of the native functions had. * [`BCTokens`]: Backport of the latest versions of PHPCS native token arrays from the `PHP_CodeSniffer\Util\Tokens` class to make them available in older PHPCS versions. diff --git a/README.md b/README.md index 0e743278..a2f56e6d 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ [![Minimum PHP Version](https://img.shields.io/packagist/php-v/phpcsstandards/phpcsutils.svg?maxAge=3600)][phpcsutils-packagist] [![CS Build Status](https://github.com/PHPCSStandards/PHPCSUtils/actions/workflows/basics.yml/badge.svg?branch=develop)](https://github.com/PHPCSStandards/PHPCSUtils/actions/workflows/basics.yml) [![Test Build Status](https://github.com/PHPCSStandards/PHPCSUtils/actions/workflows/test.yml/badge.svg?branch=develop)][phpcsutils-tests-gha] -[![Tested on PHP 5.4 to 8.1](https://img.shields.io/badge/tested%20on-PHP%205.4%20|%205.5%20|%205.6%20|%207.0%20|%207.1%20|%207.2%20|%207.3%20|%207.4%20|%208.0%20|%208.1-brightgreen.svg?maxAge=2419200)][phpcsutils-tests-gha] +[![Tested on PHP 5.4 to 8.2](https://img.shields.io/badge/tested%20on-PHP%205.4%20|%205.5%20|%205.6%20|%207.0%20|%207.1%20|%207.2%20|%207.3%20|%207.4%20|%208.0%20|%208.1%20|%208.2-brightgreen.svg?maxAge=2419200)][phpcsutils-tests-gha] [![Coverage Status](https://coveralls.io/repos/github/PHPCSStandards/PHPCSUtils/badge.svg?branch=develop)](https://coveralls.io/github/PHPCSStandards/PHPCSUtils?branch=develop) [![Docs Build Status](https://github.com/PHPCSStandards/PHPCSUtils/actions/workflows/ghpages.yml/badge.svg)][phpcsutils-web] @@ -33,7 +33,7 @@ ## Features -[PHPCSUtils](https://github.com/PHPCSStandards/PHPCSUtils) is a set of utilities to aid developers of sniffs for [PHP_CodeSniffer] (or "PHPCS" for short). +[PHPCSUtils][phpcsutils-repo] is a set of utilities to aid developers of sniffs for [PHP_CodeSniffer] (or "PHPCS" for short). This package offers the following features: @@ -89,6 +89,7 @@ To see detailed information about all the available abstract sniffs, utility fun If your external PHP_CodeSniffer standard only supports Composer-based installs, integrating PHPCSUtils is pretty straight forward. Run the following from the root of your external PHPCS standard's project: + ```bash composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true composer require phpcsstandards/phpcsutils:^1.0 @@ -104,6 +105,7 @@ No further action needed. You can start using all the utility functions, abstrac > > :information_source: As of Composer 2.2, Composer will [ask for permission](https://blog.packagist.com/composer-2-2/#more-secure-plugin-execution) to allow the Composer PHPCS plugin to execute code. For the plugin to be functional, permission needs to be granted. > This can be done ahead of time by instructing your users to run the following command before installing your standard: +> > ```bash > composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true > ``` @@ -130,10 +132,13 @@ Your installation instructions for a non-Composer based installation will probab > * Download the \[latest _YourStandardName_ release\] and unzip/untar it into an arbitrary directory. > You can also choose to clone the repository using git. > * Add the path to the directory in which you placed your copy of the _YourStandardName_ repo to the PHP_CodeSniffer configuration using the below command: +> > ```bash > phpcs --config-set installed_paths /path/to/YourStandardName > ``` +> > **Warning**: :warning: The `installed_paths` command overwrites any previously set `installed_paths`. If you have previously set `installed_paths` for other external standards, run `phpcs --config-show` first and then run the `installed_paths` command with all the paths you need separated by comma's, i.e.: +> > ```bash > phpcs --config-set installed_paths /path/1,/path/2,/path/3 > ``` @@ -143,10 +148,13 @@ For things to continue working when you add PHPCSUtils to your standard, you nee > * **Next, download the [latest PHPCSUtils release][phpcsutils-releases] and unzip/untar it into an arbitrary directory.** > You can also choose to clone the repository using git. > * Add the path to the **directories** in which you placed your copy of the _YourStandardName_ repo **and the PHPCSUtils repo** to the PHP_CodeSniffer configuration using the below command: +> > ```bash > phpcs --config-set installed_paths /path/to/YourStandardName,/path/to/PHPCSUtils > ``` +> > **Warning**: :warning: The `installed_paths` command overwrites any previously set `installed_paths`. If you have previously set `installed_paths` for other external standards, run `phpcs --config-show` first and then run the `installed_paths` command with all the paths you need separated by comma's, i.e.: +> > ```bash > phpcs --config-set installed_paths /path/1,/path/2,/path/3 > ``` @@ -193,9 +201,11 @@ pointing to the PHPCS directory. -Once that's done, you will need to make a small tweak to your own dev environment to get the unit tests runnning for a non-Composer based install: +Once that's done, you will need to make a small tweak to your own dev environment to get the unit tests running for a non-Composer based install: + * Copy your project's `phpunit.xml.dist` file to `phpunit.xml`. * Add the following to the `phpunit.xml` file within the `` tags, replacing `/path/to/PHPCSUtils` with the path in which you installed PHPCSUtils on your local system: + ```xml @@ -205,7 +215,7 @@ Once that's done, you will need to make a small tweak to your own dev environmen ## Frequently Asked Questions -
+
### Q: How does this all work without an external standard needing to register an autoloader? @@ -219,8 +229,8 @@ If your standard includes both PHPCS native sniffs as well as your own sniffs, y ### Q: Do the utilities work with javascript/CSS files? -A: JS/CSS support will be removed from PHP_CodeSniffer in PHPCS 4.x. -While at this time, some of the utilies _may_ work with JS/CSS files, PHPCSUtils does not offer formal support for JS/CSS sniffing with PHP_CodeSniffer and will stop any existing support once PHPCS 4.x has been released. +A: JS/CSS support will be removed from `PHP_CodeSniffer` in PHPCS 4.x. +While at this time, some of the utilities _may_ work with JS/CSS files, PHPCSUtils does not offer formal support for JS/CSS sniffing with `PHP_CodeSniffer` and will stop any existing support once PHPCS 4.x has been released. ### Q: Are all file encodings supported? @@ -228,11 +238,15 @@ A: No. The UTF-8 file encoding is the only officially supported encoding. Suppor > **It is recommended to advise your users to save their files as UTF-8 encoded for the best results.** -Note: PHP_CodeSniffer 3.x defaults to UTF-8 as the expected file encoding. +Note: `PHP_CodeSniffer` 3.x defaults to UTF-8 as the expected file encoding. + +
## Potential Support Questions from your End-Users +
+ ### Q: A user reports a fatal "class not found" error for a class from PHPCSUtils 1. Check that the version of PHPCSUtils the user has installed complies with the minimum version of PHPCSUtils your standard requires. If not, they will need to upgrade. @@ -244,14 +258,16 @@ Note: PHP_CodeSniffer 3.x defaults to UTF-8 as the expected file encoding. > :bulb: **Pro-tip**: if you want to prevent the fatal error and show a _friendlier_ error message instead, add `` to your standard's `ruleset.xml` file. > -> With that in place, PHP_CodeSniffer will show a _"ERROR: the "PHPCSUtils" coding standard is not installed."_ message if PHPCSUtils is missing as soon as the ruleset loading is finished. +> With that in place, `PHP_CodeSniffer` will show a _"ERROR: the "PHPCSUtils" coding standard is not installed."_ message if PHPCSUtils is missing as soon as the ruleset loading is finished. --- > :bulb: **Pro-tip**: provide upgrade instructions for your end-users. For Composer-based installs, those should look like this: +> > ```bash -> composer update your/cs-package --with-dependencies +> composer update your/cs-package --with-[all-]dependencies > ``` +> > That way, when the user updates your coding standards package, they will automatically also update PHPCSUtils. --- @@ -268,11 +284,12 @@ If you are unsure whether the changes you are proposing would be welcome, please ## License -This code is released under the [GNU Lesser General Public License (LGPLv3)](http://www.gnu.org/copyleft/lesser.html). +This code is released under the [GNU Lesser General Public License (LGPLv3)](https://www.gnu.org/copyleft/lesser.html). [PHP_CodeSniffer]: https://github.com/squizlabs/PHP_CodeSniffer [Composer PHPCS plugin]: https://github.com/PHPCSStandards/composer-installer +[phpcsutils-repo]: https://github.com/PHPCSStandards/PHPCSUtils [phpcsutils-web]: https://phpcsutils.com/ [phpcsutils-packagist]: https://packagist.org/packages/phpcsstandards/phpcsutils [phpcsutils-releases]: https://github.com/PHPCSStandards/PHPCSUtils/releases From 441270a10b2317772317ec83b63fba2922419c86 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Sat, 15 Oct 2022 16:13:24 +0200 Subject: [PATCH 2/3] Misc/configs: update links --- .gitattributes | 4 ++-- phpcs.xml.dist | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitattributes b/.gitattributes index 4a396ff8..298934e4 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,7 +2,7 @@ # Exclude these files from release archives. # This will also make them unavailable when using Composer with `--prefer-dist`. # If you develop for this repo using Composer, use `--prefer-source`. -# https://www.reddit.com/r/PHP/comments/2jzp6k/i_dont_need_your_tests_in_my_production +# https://www.reddit.com/r/PHP/comments/2jzp6k/i_dont_need_your_tests_in_my_production/ # https://blog.madewithlove.be/post/gitattributes/ # .coveralls.yml export-ignore @@ -22,7 +22,7 @@ phpunit.xml.dist export-ignore # # Auto detect text files and perform LF normalization -# http://davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/ +# https://pablorsk.medium.com/be-a-git-ninja-the-gitattributes-file-e58c07c9e915 # * text=auto diff --git a/phpcs.xml.dist b/phpcs.xml.dist index 68d4b315..90596a78 100644 --- a/phpcs.xml.dist +++ b/phpcs.xml.dist @@ -5,7 +5,7 @@ From 97f5dd2e807576b069418b6c5dfa86fa22f9ab14 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Tue, 18 Oct 2022 15:54:08 +0200 Subject: [PATCH 3/3] Composer: remove the `phpcs2` keyword --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index d634265d..7fad0c9f 100644 --- a/composer.json +++ b/composer.json @@ -2,7 +2,7 @@ "name" : "phpcsstandards/phpcsutils", "description" : "A suite of utility functions for use with PHP_CodeSniffer", "type" : "phpcodesniffer-standard", - "keywords" : [ "phpcs", "phpcbf", "standards", "static analysis", "php_codesniffer", "phpcs2", "phpcs3", "tokens", "utility", "phpcodesniffer-standard" ], + "keywords" : [ "phpcs", "phpcbf", "standards", "static analysis", "php_codesniffer", "phpcs3", "tokens", "utility", "phpcodesniffer-standard" ], "license" : "LGPL-3.0-or-later", "homepage": "https://phpcsutils.com/", "authors" : [