Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: miscellanuous other updates #395

Merged
merged 3 commits into from
Oct 25, 2022
Merged

Docs: miscellanuous other updates #395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0bdd411
README/Changelog: various improvements
jrfnl Oct 15, 2022
441270a
Misc/configs: update links
jrfnl Oct 15, 2022
97f5dd2
Composer: remove the `phpcs2` keyword
jrfnl Oct 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
17 changes: 10 additions & 7 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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.
Expand All @@ -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]

Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand All @@ -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]
Expand Down Expand Up @@ -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]

Expand Down Expand Up @@ -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!_**
Expand All @@ -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.
Expand Down
37 changes: 27 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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
> ```
Expand All @@ -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
> ```
Expand All @@ -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
> ```
Expand Down Expand Up @@ -193,9 +201,11 @@ pointing to the PHPCS directory.

</details>

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 `<phpunit>` tags, replacing `/path/to/PHPCSUtils` with the path in which you installed PHPCSUtils on your local system:

```xml
<php>
<env name="PHPCSUTILS_DIR" value="/path/to/PHPCSUtils"/>
Expand All @@ -205,7 +215,7 @@ Once that's done, you will need to make a small tweak to your own dev environmen

## Frequently Asked Questions

<div id="faq">
<div class="faq">

### Q: How does this all work without an external standard needing to register an autoloader?

Expand All @@ -219,20 +229,24 @@ 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?

A: No. The UTF-8 file encoding is the only officially supported encoding. Support for other encodings may incidentally work, but is not officially supported.

> **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.

</div>


## Potential Support Questions from your End-Users

<div class="faq">

### 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.
Expand All @@ -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 `<rule ref="PHPCSUtils"/>` 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.

---
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" : [
Expand Down
2 changes: 1 addition & 1 deletion phpcs.xml.dist
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<!--
#############################################################################
COMMAND LINE ARGUMENTS
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset
#############################################################################
-->

Expand Down