Merge pull request #159 from PHPCSStandards/develop

Release 1.0.0-alpha3

Author: jrfnl

.travis.yml

@@ -1,3 +1,4 @@
+os: linux
 dist: trusty
 
 language: php
@@ -10,6 +11,7 @@ cache:
     - $HOME/.composer/cache/files
     # Cache directory for more recent Composer versions.
     - $HOME/.cache/composer/files
+    - /home/travis/.rvm/
 
 php:
   - 5.5
@@ -31,6 +33,8 @@ env:
 # See: https://docs.travis-ci.com/user/conditions-v1
 stages:
   - name: sniff
+  - name: docs
+    if: branch IN (master)
   - name: quicktest
     if: type = push AND branch NOT IN (master, develop)
   - name: test
@@ -66,6 +70,23 @@ jobs:
         # Check the code-style consistency of the xml files.
         - diff -B ./PHPCSUtils/ruleset.xml <(xmllint --format "./PHPCSUtils/ruleset.xml")
         - diff -B ./PHPCS23Utils/ruleset.xml <(xmllint --format "./PHPCS23Utils/ruleset.xml")
+      after_success: skip
+
+    #### DOCUMENTATION SITE TESTING STAGE ####
+    - stage: docs
+      language: ruby
+      cache: bundler
+      rvm: 2.5.8
+      before_install: skip
+      install:
+        - cd ./docs
+        - gem install bundler
+        - bundle install
+      before_script: skip
+      script:
+        # Test the documentation generation.
+        - bundle exec jekyll build
+      after_success: skip
 
     #### QUICK TEST STAGE ####
     # This is a much quicker test which only runs the unit tests and linting against the low/high
@@ -109,6 +130,9 @@ jobs:
     - php: 7.2
       env: PHPCS_VERSION="3.2.0"
 
+    - php: 7.4
+      env: PHPCS_VERSION="4.0.x-dev@dev"
+
     - php: "nightly"
       env: PHPCS_VERSION="n/a" LINT=1
 
@@ -132,19 +156,20 @@ jobs:
   allow_failures:
     # Allow failures for unstable builds.
     - php: "nightly"
+    - env: PHPCS_VERSION="4.0.x-dev@dev"
 
 
 before_install:
   # Speed up build time by disabling Xdebug when its not needed.
   - |
-    if [[ "$TRAVIS_BUILD_STAGE_NAME" != "Coverage" ]]; then
+    if [[ "${TRAVIS_BUILD_STAGE_NAME^}" != "Coverage" ]]; then
       phpenv config-rm xdebug.ini || echo 'No xdebug config.'
     fi
 
   # On stable PHPCS versions, allow for PHP deprecation notices.
   # Unit tests don't need to fail on those for stable releases where those issues won't get fixed anymore.
   - |
-    if [[ "$TRAVIS_BUILD_STAGE_NAME" != "Sniff" && $PHPCS_VERSION != "dev-master" && "$PHPCS_VERSION" != "n/a" ]]; then
+    if [[ "${TRAVIS_BUILD_STAGE_NAME^}" != "Sniff" && $PHPCS_VERSION != "dev-master" && "$PHPCS_VERSION" != "n/a" ]]; then
       echo 'error_reporting = E_ALL & ~E_DEPRECATED' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
     fi
 
@@ -158,7 +183,7 @@ install:
       composer require --no-update --no-scripts squizlabs/php_codesniffer:${PHPCS_VERSION}
     fi
   - |
-    if [[ "$TRAVIS_BUILD_STAGE_NAME" == "Coverage" ]]; then
+    if [[ "${TRAVIS_BUILD_STAGE_NAME^}" == "Coverage" ]]; then
       composer require --dev --no-update --no-suggest --no-scripts php-coveralls/php-coveralls:${COVERALLS_VERSION}
     fi
   - |
@@ -173,7 +198,7 @@ install:
 
 
 before_script:
-  - if [[ "$TRAVIS_BUILD_STAGE_NAME" == "Coverage" ]]; then mkdir -p build/logs; fi
+  - if [[ "${TRAVIS_BUILD_STAGE_NAME^}" == "Coverage" ]]; then mkdir -p build/logs; fi
   - phpenv rehash
 
 
@@ -183,18 +208,18 @@ script:
 
   # Run the unit tests.
   - |
-    if [[ $PHPCS_VERSION != "n/a" && "$TRAVIS_BUILD_STAGE_NAME" != "Coverage" ]]; then
+    if [[ $PHPCS_VERSION != "n/a" && "${TRAVIS_BUILD_STAGE_NAME^}" != "Coverage" ]]; then
       composer test
-    elif [[ $PHPCS_VERSION != "n/a" && "$TRAVIS_BUILD_STAGE_NAME" == "Coverage" ]]; then
+    elif [[ $PHPCS_VERSION != "n/a" && "${TRAVIS_BUILD_STAGE_NAME^}" == "Coverage" ]]; then
       composer coverage
     fi
 
 after_success:
   - |
-    if [[ "$TRAVIS_BUILD_STAGE_NAME" == "Coverage" && $COVERALLS_VERSION == "^1.0" ]]; then
+    if [[ "${TRAVIS_BUILD_STAGE_NAME^}" == "Coverage" && $COVERALLS_VERSION == "^1.0" ]]; then
       php vendor/bin/coveralls -v -x build/logs/clover.xml
     fi
   - |
-    if [[ "$TRAVIS_BUILD_STAGE_NAME" == "Coverage" && $COVERALLS_VERSION == "^2.0" ]]; then
+    if [[ "${TRAVIS_BUILD_STAGE_NAME^}" == "Coverage" && $COVERALLS_VERSION == "^2.0" ]]; then
       php vendor/bin/php-coveralls -v -x build/logs/clover.xml
     fi

CHANGELOG.md

@@ -68,10 +68,14 @@ abstract class AbstractArrayDeclarationSniff implements Sniff
      * A multi-dimentional array with information on each array item.
      *
      * The array index is 1-based and contains the following information on each array item:
-     * - 'start' : The stack pointer to the first token in the array item.
-     * - 'end'   : The stack pointer to the first token in the array item.
-     * - 'raw'   : A string with the contents of all tokens between `start` and `end`.
-     * - 'clean' : Same as `raw`, but all comment tokens have been stripped out.
+     * ```php
+     * 1 => array(
+     *   'start' => int,    // The stack pointer to the first token in the array item.
+     *   'end'   => int,    // The stack pointer to the last token in the array item.
+     *   'raw'   => string, // A string with the contents of all tokens between `start` and `end`.
+     *   'clean' => string, // Same as `raw`, but all comment tokens have been stripped out.
+     * )
+     * ```
      *
      * @since 1.0.0
      *
@@ -100,6 +104,8 @@ abstract class AbstractArrayDeclarationSniff implements Sniff
     /**
      * List of tokens which can safely be used with an eval() expression.
      *
+     * This list gets enhanced with additional token groups in the constructor.
+     *
      * @since 1.0.0
      *
      * @var array
@@ -161,7 +167,7 @@ public function register()
      * Processes this test when one of its tokens is encountered.
      *
      * This method fills the properties with relevant information for examining the array
-     * and then passes off to the `processArray()` method.
+     * and then passes off to the {@see AbstractArrayDeclarationSniff::processArray()} method.
      *
      * @since 1.0.0
      *
@@ -203,7 +209,19 @@ final public function process(File $phpcsFile, $stackPtr)
     /**
      * Process every part of the array declaration.
      *
-     * This contains the default logic for the sniff, but can be overloaded in a concrete child class
+     * Controller which calls the individual `process...()` methods for each part of the array.
+     *
+     * The method starts by calling the {@see AbstractArrayDeclarationSniff::processOpenClose()} method
+     * and subsequently calls the following methods for each array item:
+     *
+     * Unkeyed arrays | Keyed arrays
+     * -------------- | ------------
+     * processNoKey() | processKey()
+     * -              | processArrow()
+     * processValue() | processValue()
+     * processComma() | processComma()
+     *
+     * This is the default logic for the sniff, but can be overloaded in a concrete child class
      * if needed.
      *
      * @since 1.0.0
@@ -224,7 +242,12 @@ public function processArray(File $phpcsFile)
         }
 
         foreach ($this->arrayItems as $itemNr => $arrayItem) {
-            $arrowPtr = Arrays::getDoubleArrowPtr($phpcsFile, $arrayItem['start'], $arrayItem['end']);
+            try {
+                $arrowPtr = Arrays::getDoubleArrowPtr($phpcsFile, $arrayItem['start'], $arrayItem['end']);
+            } catch (RuntimeException $e) {
+                // Parse error: empty array item. Ignore.
+                continue;
+            }
 
             if ($arrowPtr !== false) {
                 if ($this->processKey($phpcsFile, $arrayItem['start'], ($arrowPtr - 1), $itemNr) === true) {
@@ -260,7 +283,7 @@ public function processArray(File $phpcsFile)
     /**
      * Process the array opener and closer.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
      * @since 1.0.0
      *
@@ -271,7 +294,9 @@ public function processArray(File $phpcsFile)
      * @param int                         $openPtr   The position of the array opener token in the token stack.
      * @param int                         $closePtr  The position of the array closer token in the token stack.
      *
-     * @return true|void Returning `true` will short-circuit the sniff and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the sniff and stop processing.
+     *                   In effect, this means that the sniff will not examine the individual
+     *                   array items if `TRUE` is returned.
      */
     public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
     {
@@ -280,10 +305,10 @@ public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
     /**
      * Process the tokens in an array key.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
-     * The $startPtr and $endPtr do not discount whitespace or comments, but are all inclusive to
-     * allow examining all tokens in an array key.
+     * Note: The `$startPtr` and `$endPtr` do not discount whitespace or comments, but are all inclusive
+     * to allow for examining all tokens in an array key.
      *
      * @since 1.0.0
      *
@@ -300,7 +325,9 @@ public function processOpenClose(File $phpcsFile, $openPtr, $closePtr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the double arrow, the array
+     *                   value or comma for this array item and will not process any array items after this one.
      */
     public function processKey(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     {
@@ -309,12 +336,17 @@ public function processKey(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     /**
      * Process an array item without an array key.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
+     *
+     * Note: This method is _not_ intended for processing the array _value_. Use the
+     * {@see AbstractArrayDeclarationSniff::processValue()} method to implement processing of the array value.
      *
      * @since 1.0.0
      *
      * @codeCoverageIgnore
      *
+     * @see \PHPCSUtils\AbstractSniffs\AbstractArrayDeclarationSniff::processValue() Method to process the array value.
+     *
      * @param \PHP_CodeSniffer\Files\File $phpcsFile The PHP_CodeSniffer file where the
      *                                               token was found.
      * @param int                         $startPtr  The stack pointer to the first token in the array item,
@@ -323,7 +355,9 @@ public function processKey(File $phpcsFile, $startPtr, $endPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the array value or
+     *                   comma for this array item and will not process any array items after this one.
      */
     public function processNoKey(File $phpcsFile, $startPtr, $itemNr)
     {
@@ -332,7 +366,7 @@ public function processNoKey(File $phpcsFile, $startPtr, $itemNr)
     /**
      * Process the double arrow.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
      * @since 1.0.0
      *
@@ -344,7 +378,9 @@ public function processNoKey(File $phpcsFile, $startPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the array value or
+     *                   comma for this array item and will not process any array items after this one.
      */
     public function processArrow(File $phpcsFile, $arrowPtr, $itemNr)
     {
@@ -353,10 +389,10 @@ public function processArrow(File $phpcsFile, $arrowPtr, $itemNr)
     /**
      * Process the tokens in an array value.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
-     * The $startPtr and $endPtr do not discount whitespace or comments, but are all inclusive to
-     * allow examining all tokens in an array value.
+     * Note: The `$startPtr` and `$endPtr` do not discount whitespace or comments, but are all inclusive
+     * to allow for examining all tokens in an array value.
      *
      * @since 1.0.0
      *
@@ -371,7 +407,9 @@ public function processArrow(File $phpcsFile, $arrowPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not examine the comma for this
+     *                   array item and will not process any array items after this one.
      */
     public function processValue(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     {
@@ -380,7 +418,7 @@ public function processValue(File $phpcsFile, $startPtr, $endPtr, $itemNr)
     /**
      * Process the comma after an array item.
      *
-     * Optional method to be implemented in concrete child classes.
+     * Optional method to be implemented in concrete child classes. By default, this method does nothing.
      *
      * @since 1.0.0
      *
@@ -392,7 +430,9 @@ public function processValue(File $phpcsFile, $startPtr, $endPtr, $itemNr)
      * @param int                         $itemNr    Which item in the array is being handled.
      *                                               1-based, i.e. the first item is item 1, the second 2 etc.
      *
-     * @return true|void Returning `true` will short-circuit the array item loop and stop processing.
+     * @return true|void Returning `TRUE` will short-circuit the array item loop and stop processing.
+     *                   In effect, this means that the sniff will not process any array items
+     *                   after this one.
      */
     public function processComma(File $phpcsFile, $commaPtr, $itemNr)
     {
@@ -401,7 +441,8 @@ public function processComma(File $phpcsFile, $commaPtr, $itemNr)
     /**
      * Determine what the actual array key would be.
      *
-     * Optional helper function for processsing array keys in the processKey() function.
+     * Helper function for processsing array keys in the processKey() function.
+     * Using this method is up to the sniff implementation in the child class.
      *
      * @since 1.0.0
      *