Various DevOps improvements (#58)

* PHPUnit: Rename the config file

> If `phpunit.xml` or `phpunit.xml.dist` (in that order) exist in the current working directory and `--configuration` is not used, the configuration will be automatically read from that file.

From: https://phpunit.de/manual/6.5/en/organizing-tests.html#organizing-tests.xml-configuration

In other words, using a `phpunit.xml.dist` file allows individual developers to overrule it with their own version if so desired.
This in turn, allows them to use the `<php ...>` directives to set environment variables, such as `WP_TESTS_DIR`.

It also means that the configuration file does not need to be passed to PHPUnit in the Travis scripts.

Includes adding `phpunit.xml` to the `.gitignore` file to allow devs to use that file for their own custom configuration.

* PHPUnit config: minor tweaks

* Add the XML header.
* Add the schema.
* Add a name for the testsuite. (Required attribute as of PHPUnit 7)

* Travis: clean up the existing config

* Remove duplicate `language` directive.
* Remove sudo.
    `sudo` is no longer a supported directive in Travis.
    Ref: https://blog.travis-ci.com/2018-11-19-required-linux-infrastructure-migration
* Remove duplicate/inconsistent `WP_DEVELOP_DIR` setting.
    `WP_DEVELOP_DIR` is set to something else only two lines before and not used by the test bootstrap, so this shouldn't be needed.
* List the job steps in the order in which they will be run.
    Ref: https://docs.travis-ci.com/user/job-lifecycle/
* Use consistent 2-space indentation for YAML.
* Add some blank lines to improve readability.

* Travis: tweak the PHP version matrix

Simplify for versions which don't need extra settings and only list those which do in the matrix.

* Simplify the list of PHP versions for those versions which don't need extra settings.
* Drop testing against PHP < 5.6.
* Drop special builds with `env: WP_TRAVISCI=travis:js` and `env: WP_TRAVIS_OBJECT_CACHE=true`.
    Looks like those variables come from the [Core script](https://github.com/WordPress/wordpress-develop/blob/master/.travis.yml), but weren't being used here.
    - The `js` testing isn't needed anyway as this repo doesn't contain JS.
    - The object cache testing could be considered, but would need some extra script bits. As it is, the variable was unused, so no needed.
* Replace `nightly` with `7.4snapshot`
    Nightly has become PHP 8.0 since PHP 7.4 has been branched, so to continue to also test against PHP 7.4, it needs to be added separately.
    Refs:
    * https://twitter.com/nikita_ppv/status/1089839541828112384
    * https://twitter.com/nikita_ppv/status/1094897743594770433
    As PHP 8.x - current `nightly` - is not expected to be released until December 2020, with PHP 7.4 expected in December 2019, I've elected to replace the build against `nightly` with a build against `7.4snapshot`.
* Don't require PHPUnit 7 for PHP 7.1
    The Travis image for PHP 7.1 already comes with a supported PHPUnit version, so there is no need to replace it.
    Also see: https://phpunit.de/supported-versions.html
    For that matter, there is no need for the `PHPUNIT_VERSION` environment variable either as a simple compare can take care of that just as easily.

* Travis: disable xdebug

Xdebug is only _needed_ when PHPUnit code coverage is tested via Travis. As that is not the case, disabling Xdebug should speed up the build a little.

* Travis: cache Composer downloads

This should speed up the build a little again.

* Travis: be explicit about what is being tested

Without a `script` section, you are relying on the Travis default for a PHP environment being, the running of PHPUnit.
This may change, however, without notice. So it is always better to be explicit about what tests to run from Travis.

* Travis: lint all PHP files against all supported PHP versions

* Add a `composer.json` file

... making the exiting (development) dependencies explicit and easier to find for anyone looking for them.

Includes validating the `composer.json` file on the Travis builds against the lowest and highest stable PHP versions supported by Composer as well as the plugin.

Includes adding the `composer.lock` file to the `.gitignore` list.
Until there are non-dev dependencies which need to be locked to specific versions, there is no need to commit the `composer.lock` file.

* Add a `.gitattributes` file

... to keep the zip file which can be downloaded from GitHub clean of development specific files.

* CS: remove old-style whitelist comment

I have not replaced this with a new-style comment (yet) as it looks like some valid observations are made by WPCS, so I would recommend checking this thoroughly.

* PHPCS: set it up & add to Travis

* Add the various PHPCS requirements to the `composer.json` `require-dev` section.
    - WPCS for generic code style and best practices.
    - PHPCompatibilityWP for checking code for cross-version PHP compatibility.
    - The DealerDirect Composer plugin to automatically install external standards for PHPCS.
    - Note: PHPCS itself is not a direct dependency, this is a dependency of our dependants, so we don't need to `require` it.
* Set up a fully documented PHPCS ruleset using the `WordPress` and `PHPCompatibilityWP` rulesets, with the minimum PHP version to test cross-version compatibility against set to `5.6`.
* Add a Travis task to test the code base against the PHPCS ruleset.

Includes adding optional developer specific local configuration files to `.gitignore`.

* add missing docblock for _manually_load_plugin

* test-meta-revisions.php: Improve docblocks

* function names should not be prefixed with an underscore to indicate visibility

* add missing doc block parameters

* ignore the naming suggestion - changing the naming would result in a breaking change & named for core

* ignore security data handling reccomendation for these low level handlers

* add the mysql service

* correct phpcs version usage

* try: reverse logic check

* CS: Minor documentation fixes

* Travis: fix issue with Travis images being unstable

The PHPUnit version shipped with Travis natively is currently unusable as someone who wasn't paying attention decided to ship them with incompatible PHPUnit versions.

Always using Composer fixes this.

* explain why we are using @phpcs:disable WordPress.Security


Co-authored-by: Adam Silverstein <[email protected]>

.gitattributes

@@ -0,0 +1,34 @@
+#
+# Exclude these files from release archives.
+# This will also make them unavailable when using Composer with `--prefer-dist`.
+# If you develop using Composer, use `--prefer-source`.
+# https://www.reddit.com/r/PHP/comments/2jzp6k/i_dont_need_your_tests_in_my_production
+# https://blog.madewithlove.be/post/gitattributes/
+#
+.gitattributes export-ignore
+.gitignore export-ignore
+.phpcs.xml export-ignore
+.phpcs.xml.dist export-ignore
+.travis.yml export-ignore
+composer.json export-ignore
+deploy.sh export-ignore
+phpcs.xml export-ignore
+phpcs.xml.dist export-ignore
+phpunit.xml export-ignore
+phpunit.xml.dist export-ignore
+README.md export-ignore
+assets export-ignore
+bin export-ignore
+tests export-ignore
+
+#
+# Auto detect text files and perform LF normalization
+# http://davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/
+#
+* text=auto
+
+#
+# The above will handle all files NOT found below
+#
+*.md text
+*.php text

.gitignore

@@ -1 +1,5 @@
-vendor
+composer.lock
+vendor/*
+.phpcs.xml
+phpcs.xml
+phpunit.xml

.phpcs.xml.dist

@@ -0,0 +1,81 @@
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="WP-Post-Meta-Revisions" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
+
+	<description>The coding standard for the WP-Post-Meta-Revisions plugin.</description>
+
+	<!--
+	#############################################################################
+	COMMAND LINE ARGUMENTS
+	https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
+	#############################################################################
+	-->
+
+	<file>.</file>
+
+	<exclude-pattern>*/vendor/*</exclude-pattern>
+
+	<!-- Only check PHP files. -->
+	<arg name="extensions" value="php"/>
+
+	<!-- Show progress. -->
+	<arg value="p"/>
+
+	<!-- Strip the filepaths down to the relevant bit. -->
+	<arg name="basepath" value="./"/>
+
+
+	<!--
+	#############################################################################
+	USE THE WordPress and the PHPCompatibilityWP RULESETS
+	#############################################################################
+	-->
+
+	<!-- Check code for cross-version PHP compatibility. -->
+	<config name="testVersion" value="5.6-"/>
+	<rule ref="PHPCompatibilityWP"/>
+
+	<!-- Check code against the complete WordPress Coding Standards. -->
+	<rule ref="WordPress">
+		<!-- No need to lint the PHP, this is done in a separate task in the travis script. -->
+		<exclude name="Generic.PHP.Syntax"/>
+	</rule>
+
+
+	<!--
+	#############################################################################
+	SNIFF SPECIFIC CONFIGURATION
+	#############################################################################
+	-->
+
+	<!-- Set minimum supported WP version for all sniffs which use it. -->
+	<config name="minimum_supported_wp_version" value="4.7"/>
+
+	<!-- Verify that all gettext calls use the correct text domain. -->
+	<rule ref="WordPress.WP.I18n">
+		<properties>
+			<property name="text_domain" type="array">
+				<element value="post-meta-revisions"/>
+			</property>
+		</properties>
+	</rule>
+
+	<!-- Verify that everything in the global namespace is prefixed with a theme specific prefix.
+		 Multiple valid prefixes can be provided as a comma-delimited list. -->
+	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
+		<properties>
+			<!-- Provide the prefixes to look for. -->
+			<property name="prefixes" type="array">
+				<element value="wp_post_meta_revisioning"/>
+			</property>
+		</properties>
+
+		<!-- Anything test related does not need to be prefixed as it is not shipped with the plugin. -->
+		<exclude-pattern>/tests/*\.php$</exclude-pattern>
+	</rule>
+
+	<rule ref="WordPress.Files.FileName">
+		<!-- Don't trigger on the main file as renaming it would deactivate the plugin. -->
+		<exclude-pattern>/wp-post-meta-revisions\.php$</exclude-pattern>
+	</rule>
+
+</ruleset>

.travis.yml

@@ -1,49 +1,62 @@
-language: php
+cache:
+  apt: true
+  directories:
+    # Cache directory for older Composer versions.
+    - $HOME/.composer/cache/files
+    # Cache directory for more recent Composer versions.
+    - $HOME/.cache/composer/files
 
 language: php
 
-sudo: false
+services:
+  - mysql
+
+# Declare versions of PHP to use.
+php:
+  - 5.6
+  - 7.0
+  - 7.1
+  - 7.2
+  - "7.4snapshot"
+
+env:
+  global:
+    - WP_VERSION=master # Git equivalent of SVN /trunk
 
 matrix:
   include:
-  - php: 7.1
-    env: PHPUNIT_VERSION="^7"
-    env: WP_TRAVISCI=travis:js
   - php: 7.3
-    env: PHPUNIT_VERSION="^7"
-  - php: 7.2
-    env: PHPUNIT_VERSION="^7"
-  - php: 7.1
-    env: PHPUNIT_VERSION="^7"
-  - php: 7.0
-  - php: 5.6
-  - php: 5.6
-    env: WP_TRAVIS_OBJECT_CACHE=true
-    services: memcached
-  - php: 5.5
-  - php: 5.3
-    dist: precise
-  - php: 5.2
-    dist: precise
-  - php: nightly
+    env: PHPCS=1
+
   allow_failures:
-  - php: nightly
+  - php: "7.4snapshot"
+
   fast_finish: true
-env:
-  global:
-    - WP_VERSION=master # Git equivalent of SVN /trunk
-    - PHPUNIT_VERSION="travis"
+
+# Before install, failures in this section will result in build status 'errored'
+before_install:
+  # Speed up build time by disabling Xdebug when its not needed.
+  - phpenv config-rm xdebug.ini || echo 'No xdebug config.'
+  # clone the WordPress develop repo
+  - WP_DEVELOP_DIR=/tmp/wordpress
+  - git clone --depth=1 --branch="master" git://develop.git.wordpress.org/ $WP_DEVELOP_DIR
+  # Install the dependencies.
+  - composer install
 
 before_script:
   - bash bin/install-wp-tests.sh wordpress_test root '' localhost master
 
-# Before install, failures in this section will result in build status 'errored'
-before_install:
-    # setup WP_DEVELOP_DIR (needed for bbPress to bootstrap WP PHPUnit tests)
-    - WP_DEVELOP_DIR=/tmp/wordpress
-    # clone the WordPress develop repo
-    - git clone --depth=1 --branch="master" git://develop.git.wordpress.org/ $WP_DEVELOP_DIR
-    - WP_DEVELOP_DIR=/tmp/wordpress/src
-    - if [[ $PHPUNIT_VERSION != "travis" ]]; then composer require phpunit/phpunit:${PHPUNIT_VERSION}; fi
+script:
+  # Run the unit tests.
+  - vendor/bin/phpunit
+
+  # Lint the PHP files against parse errors.
+  - find -L . -path ./vendor -prune -o -name '*.php' -print0 | xargs -0 -n 1 -P 4 php -l
+
+  # Validate the composer.json file.
+  # @link https://getcomposer.org/doc/03-cli.md#validate
+  - if [[ $TRAVIS_PHP_VERSION == "5.6" || $TRAVIS_PHP_VERSION == "7.3" ]]; then composer validate --no-check-all; fi
 
+  # Check for code style violations, best practices and PHP cross-version compatibility.
+  - if [[ "$PHPCS" == "1" ]]; then vendor/bin/phpcs --report=full,summary; fi
 

composer.json

@@ -0,0 +1,30 @@
+{
+    "name": "adamsilverstein/wp-post-meta-revisions",
+    "description": "A WordPress plugin which implements a post meta revisioning feature as arrived at in https://core.trac.wordpress.org/ticket/20564.",
+    "homepage"   : "https://wordpress.org/plugins/wp-post-meta-revisions/",
+    "keywords"   : ["wordpress", "plugin" ],
+    "type"       : "wordpress-plugin",
+    "license"    : "GPL-2.0-or-later",
+    "authors": [
+        {
+            "name": "Adam Silverstein",
+            "email": "[email protected]"
+        }
+    ],
+    "support": {
+        "forum" : "https://wordpress.org/support/plugin/wp-post-meta-revisions",
+        "issues": "https://github.com/adamsilverstein/wp-post-meta-revisions/issues",
+        "source": "https://github.com/adamsilverstein/wp-post-meta-revisions"
+    },
+    "require": {
+        "php" : ">=5.6"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^4 | ^5 | ^6 | ^7",
+        "wp-coding-standards/wpcs": "^2.0",
+        "phpcompatibility/phpcompatibility-wp": "^2.0",
+        "dealerdirect/phpcodesniffer-composer-installer": "^0.5.0"
+    },
+    "minimum-stability" : "RC",
+    "prefer-stable": true
+}

phpunit.xml → phpunit.xml.dist

@@ -1,4 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
 <phpunit
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.3/phpunit.xsd"
 	bootstrap="tests/bootstrap.php"
 	backupGlobals="false"
 	colors="true"
@@ -7,7 +10,7 @@
 	convertWarningsToExceptions="true"
 	>
 	<testsuites>
-		<testsuite>
+		<testsuite name="PMR">
 			<directory prefix="test-" suffix=".php">./tests/</directory>
 		</testsuite>
 	</testsuites>

tests/bootstrap.php

@@ -15,6 +15,9 @@
 
 require_once $_tests_dir . '/includes/functions.php';
 
+/**
+ * Load the plugin for testing.
+ */
 function _manually_load_plugin() {
 	require dirname( __FILE__ ) . '/../wp-post-meta-revisions.php';
 }

tests/test-meta-revisions.php

@@ -14,6 +14,10 @@ class MetaRevisionTests extends WP_UnitTestCase {
 
 	/**
 	 * Callback function to add the revisioned keys.
+	 *
+	 * @param array $keys The passed array of keys to revision.
+	 *
+	 * @return array The filtered array of keys to revision, including the key 'meta_revision_test'.
 	 */
 	public function add_revisioned_keys( $keys ) {
 		$keys[] = 'meta_revision_test';
@@ -23,6 +27,9 @@ public function add_revisioned_keys( $keys ) {
 	/**
 	 * Test the revisions system for storage of meta values with slashes.
 	 *
+	 * @param string $passed   The passed data for testing.
+	 * @param string $expected The expected value after storing & retrieving.
+	 *
 	 * @group revision
 	 * @group slashed
 	 * @dataProvider slashed_data_provider
@@ -77,6 +84,9 @@ public function test_revisions_stores_meta_values_with_slashes( $passed, $expect
 		remove_filter( 'wp_post_revision_meta_keys', array( $this, 'add_revisioned_keys' ) );
 	}
 
+	/**
+	 * Provide data for the slashed data tests.
+	 */
 	public function slashed_data_provider() {
 		return array(
 			array(