Update installation & add upgrade instructions

Includes:
* Composer: add scripts to run when PHPCompatibility is installed as stand-alone app/globally
* Composer: suggest using a composer plugin to set installed paths
* Remove the symlinking from the travis script as it is no longer needed.

.travis.yml

@@ -79,7 +79,6 @@ before_script:
 
 script:
   # Lint all PHP files against parse errors.
-  - if [[ $TRAVIS_PHP_VERSION > "5.2" ]]; then ln -s `pwd` vendor/squizlabs/php_codesniffer/CodeSniffer/Standards/PHPCompatibility; fi
   - if [[ $TRAVIS_PHP_VERSION > "5.2" ]]; then find -L . -path ./PHPCompatibility/Tests/sniff-examples -prune -o -path ./vendor -prune -o -name '*.php' -print0 | xargs -0 -n 1 -P 4 php -l; fi
   - if [[ $TRAVIS_PHP_VERSION < "5.3" ]]; then find -L . -path ./PHPCompatibility/Tests/sniff-examples -prune -o -path ./PHPCompatibility/Tests/PHPUnit6Compat.php -prune -o -path ./vendor -prune -o -name '*.php' -print0 | xargs -0 -n 1 -P 4 php -l; fi
   # Check the code style of the code base.

CHANGELOG.md

@@ -13,6 +13,35 @@ The `patch` version numbers are specific to this library.
 _Nothing yet._
 
 
+## [7.1.5] - 2017-xx-xx
+
+**IMPORTANT**: This release contains a **breaking change**. Please read this carefully!
+
+The directory layout of the PHPCompatibility standard has been changed for improved compatibility with Composer.
+This means that the PHPCompatibility standard no longer extends from the root directory of the repository, but now lives in its own subdirectory `/PHPCompatibility`.
+
+* If you are using a PEAR install of PHP_CodeSniffer and had PHPCompatibility checked out to the `PHP/CodeSniffer/Standards/PHPCompatibility` directory, you will now need to **_add_** the `PHP/CodeSniffer/Standards/PHPCompatibility` directory to the PHPCS `installed_paths`. This is a one-time-only action.
+    - Check the currently registered paths by running `phpcs --config-show`.
+    - Run `phpcs --config-set installed_paths ...` and include all previously installed paths and add the path for the PHPCompatibility standard.
+        For example, if the previous value of `installed_paths` was `/path/to/MyStandard`, you should now set it to `phpcs --config-set installed_paths /path/to/MyStandard,/path/to/PHPCompatibility`.
+* If you are using a PEAR/phar/git install of PHP_CodeSniffer with PHPCompatibility in an arbitrary secundary directory, you will have previously run the `phpcs --config-set installed_paths ...` command.
+    You will need to run the command again for the changed directory layout. This is a one-time-only action.
+    - Check the currently registered paths by running `phpcs --config-show`.
+    - Run `phpcs --config-set installed_paths ...` and include all previously installed paths including the _adjusted_ path for the PHPCompatibility standard.
+        For example, if the previous value of `installed_paths` was `/path/to/MyStandard,/path/to/dir/abovePHPCompatibility`, you should now set it to `phpcs --config-set installed_paths /path/to/MyStandard,/path/to/PHPCompatibility`.
+* If you are using a Composer installation with PHPCompatibility installed globally and have run the `installed_paths` command previously to get PHP_CodeSniffer to recognize the PHPCompatibility standard, you will need to verify the `installed_paths` after the upgrade using `phpcs --config-set`.
+    **Note**: The `composer.json` for PHPCompatibility contains the necessary scripts to set the `installed_paths`, however this may be problematic if you have several standards installed globally via Composer.
+* If you are using a Composer installation with the PHPCompatibility installed globally and have the standard symlinked into the PHP_CodeSniffer `Standards` directory, you can remove the symlink as PHPCompatibility will register itself with PHPCS through the `installed_paths` command.
+* If you are using a project-based Composer installation and you have previously added scripts to your own `composer.json` in your project root to symlink or move the standard, or to set the `installed_paths`, these scripts will need to be adjusted accordingly.
+    Alternatively - and strongly recommended -, you can remove your own scripts and use one of the - as of yet unofficial - Composer plugins for PHPCS to handle this for you. For some suggestions, see the [README](https://github.com/wimg/PHPCompatibility/blob/master/README.md).
+
+To check that the PHPCompatibility standard is recognized correctly by PHP_CodeSniffer after you've made these changes, run `phpcs -i` and verify that `PHPCompatibility` is listed.
+
+**Side-note**: If you had previously forked this repository to solve this issue, you may want to consider reverting your fork to the official version.
+
+
+
+
 ## [7.1.4] - 2017-05-06
 
 See all related issues and PRs in the [7.1.4 milestone].

CONTRIBUTING.md

@@ -53,12 +53,9 @@ on the sniffs, the following installation steps are required.
 
         $ export PATH=~/.composer/vendor/bin:$PATH
 
-4. Be sure that the `PHPCompatibility` directory is symlinked into
-   `PHP_Codesniffer`'s standards directory:
+4. Ensure that the `PHPCompatibility` standard is recognized by PHP CodeSniffer by following the instructions in the [README](https://github.com/wimg/PHPCompatibility/blob/master/README.md#installation-in-composer-project-method-1).
 
-        $ ln -s /path/to/PHPCompatibility ~/.composer/vendor/squizlabs/php_codesniffer/CodeSniffer/Standards/PHPCompatibility
-
-5. Verify standard is available with `phpcs -i`. The output should include
+5. Verify the standard is available with `phpcs -i`. The output should include
    `PHPCompatibility`
 
 6. Run the tests by running `phpunit` in the root directory of

README.md

@@ -36,51 +36,67 @@ Thanks to all contributors for their valuable contributions.
 Thanks to [WP Engine](https://wpengine.com) for their support on the PHP 7.0 sniffs.
 
 
-Installation using PEAR (method 1)
------------------------
+Important Upgrade Notice
+--------
+As of version 7.1.5, the installation instructions have changed. For most users, this means they will have to run a one-time-only extra command or make a change to their Composer configuration.
 
-* Install [PHP_CodeSniffer](http://pear.php.net/PHP_CodeSniffer) with `pear install PHP_CodeSniffer-2.9.0`.
-* Checkout the latest release from https://github.com/wimg/PHPCompatibility/releases into the `PHP/CodeSniffer/Standards/PHPCompatibility` directory.
+Please read the changelog for version [7.1.5](https://github.com/wimg/PHPCompatibility/releases/tag/7.1.5) for more details.
 
 
-Installation in Composer project (method 2)
+Installation in Composer project (method 1)
 -------------------------------------------
 
-* Add the following lines to the `require-dev` section of your composer.json file.
-
-```json
-"require-dev": {
-   "squizlabs/php_codesniffer": "^2.0",
-   "wimg/php-compatibility": "*",
-   "simplyadmire/composer-plugins" : "@dev"
-},
-"prefer-stable" : true
-
+* Add the following lines to the `require-dev` section of your `composer.json` file.
+    ```json
+    "require-dev": {
+        "squizlabs/php_codesniffer": "^2.0",
+        "wimg/php-compatibility": "*"
+    },
+    "prefer-stable" : true
 ```
-* Run `composer update --lock` to install both phpcs and PHPCompatibility coding standard.
+* Next, PHPCS has to be informed of the location of the standard.
+    - If you use just one external PHPCS standard, you can add the following to your `composer.json` file to automatically run the necessary command:
+        ```json
+        "scripts": {
+            "post-install-cmd": "\"vendor/bin/phpcs\" --config-set installed_paths /vendor/wimg/php-compatibility",
+            "post-update-cmd" : "\"vendor/bin/phpcs\" --config-set installed_paths /vendor/wimg/php-compatibility"
+        }
+        ```
+    - Alternatively - and **_strongly recommended_** if you use more than one external PHPCS standard - you can use any of the following Composer plugins to handle this for you.
+	   Add the Composer plugin you prefer to the `require-dev` section of your `composer.json` file.
+            * [DealerDirect/phpcodesniffer-composer-installer](https://github.com/DealerDirect/phpcodesniffer-composer-installer)
+            * [higidi/composer-phpcodesniffer-standards-plugin](https://github.com/higidi/composer-phpcodesniffer-standards-plugin)
+            * [SimplyAdmire/ComposerPlugins](https://github.com/SimplyAdmire/ComposerPlugins)
+    - As a last alternative in case you use a custom ruleset, _and only if you use PHPCS version 2.6.0 or higher_, you can tell PHP_CodeSniffer the path to the PHPCompatibility standard by adding the following snippet to your custom ruleset:
+        ```xml
+        <config name="installed_paths" value="/vendor/wimg/php-compatibility" />
+        ```
+* Run `composer update --lock` to install both PHP CodeSniffer, the PHPCompatibility coding standard and - optionally - the Composer plugin.
+* Verify that the PHPCompatibility standard is registered correctly by running `phpcs -i`. PHPCompatibility should be listed as one of the available standards.
 * Use the coding standard with `./vendor/bin/phpcs --standard=PHPCompatibility`
 
 
-Installation via a git check-out to an arbitrary directory (method 3)
+Installation via a git check-out to an arbitrary directory (method 2)
 -----------------------
 
-* Install the latest `2.x` version of [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) via [your preferred method](https://github.com/squizlabs/PHP_CodeSniffer#installation) (Composer, PEAR, Phar file, Git checkout).
-* Checkout the latest release from https://github.com/wimg/PHPCompatibility/releases into an arbitrary directory.
-* Add the path to the directory **_above_** the directory in which you cloned the PHPCompability repo to the PHPCS configuration using the below command.
+* Install the latest `2.x` version of [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) via [your preferred method](https://github.com/squizlabs/PHP_CodeSniffer#installation) (Composer, [PEAR](http://pear.php.net/PHP_CodeSniffer), Phar file, Git checkout).
+* Checkout the [latest PHPCompatibility release](https://github.com/wimg/PHPCompatibility/releases) into an arbitrary directory.
+* Add the path to the directory in which you cloned the PHPCompatibility repo to the PHPCS configuration using the below command.
    ```bash
-   phpcs --config-set installed_paths /path/to/dir/above
+   phpcs --config-set installed_paths /path/to/PHPCompatibility
    ```
-   I.e. if you cloned the `PHPCompatibility` repository to the `/my/custom/standards/PHPCompatibility` directory, you will need to add the `/my/custom/standards` directory to the PHPCS [`installed_paths` configuration variable](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-installed-standard-paths).
+   I.e. if you cloned the `PHPCompatibility` repository to the `/my/custom/standards/PHPCompatibility` directory, you will need to add that directory to the PHPCS [`installed_paths` configuration variable](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-installed-standard-paths).
 
    **Pro-tip:** Alternatively, _and only if you use PHPCS version 2.6.0 or higher_, you can tell PHP_CodeSniffer the path to the PHPCompatibility standard by adding the following snippet to your custom ruleset:
    ```xml
-   <config name="installed_paths" value="/path/to/dir/above" />
+   <config name="installed_paths" value="/path/to/PHPCompatibility" />
    ```
+* Verify that the PHPCompatibility standard is registered correctly by running `phpcs -i`. PHPCompatibility should be listed as one of the available standards.
+* Use the coding standard with `phpcs --standard=PHPCompatibility`
 
 
-Using the compatibility sniffs
+Sniffing your code for compatibility with specific PHP version
 ------------------------------
-* Use the coding standard with `phpcs --standard=PHPCompatibility`
 * You can specify which PHP version you want to test against by specifying `--runtime-set testVersion 5.5`.
 * You can also specify a range of PHP versions that your code needs to support.  In this situation, compatibility issues that affect any of the PHP versions in that range will be reported:
 `--runtime-set testVersion 5.3-5.5`.  You can omit one or other part of the range if you want to support everything above/below a particular version (e.g. `--runtime-set testVersion 7.0-` to support PHP 7 and above).

composer.json

@@ -9,13 +9,20 @@
   "require-dev" : {
     "satooshi/php-coveralls" : "dev-master"
   },
+  "suggest" : {
+    "dealerdirect/phpcodesniffer-composer-installer": "*"
+  },
   "license" : "LGPL-3.0",
   "keywords" : [ "compatibility", "phpcs", "standards" ],
   "autoload" : {
     "psr-4" : {
       "PHPCompatibility\\" : "PHPCompatibility/"
     }
   },
+  "scripts" : {
+    "post-install-cmd": "\"vendor/bin/phpcs\" --config-set installed_paths ../../..",
+    "post-update-cmd" : "\"vendor/bin/phpcs\" --config-set installed_paths ../../.."
+  },
   "type" : "phpcodesniffer-standard",
   "support" : {
     "issues" : "https://github.com/wimg/PHPCompatibility/issues",