Rework the PHP compactor (#315)

Closes #263

Goal: remove the need of the deprecated dependency [herrera-io/annotations](https://github.com/kherge-abandoned/php-annotations) and the underlying [doctrine/lexer 1.x](https://packagist.org/packages/doctrine/lexer) which is bound to disappear at some point.

- Remove the deprecated dependency  [herrera-io/annotations](https://github.com/kherge-abandoned/php-annotations) and soon deprecated underlying dependency [doctrine/lexer 1.x](https://packagist.org/packages/doctrine/lexer) in favour of [HoaCompiler](https://hoa-project.net/En/Literature/Hack/Compiler.html) and an annotation grammar which should land in doctrine/annotations or lexer at some point.
- Changes to the `Php` compactor:
    - Invalid annotations are no longer recognised as annotations:
        ```php
        /**
          * @annotation ()
          * @namespaced\ Annotation
          */
        ```
        
        Will be transformed into:
        
        ```php
        /**
          * @annotation
          * @namespaced
          */
        ```
- The removal of common annotations is enabled by default
- The setting `annotation#ignore` no longer accepts a `string` value, only `string[]` and `null` are allowed
- Upon some annotation parsing failures, the error is thrown to the user in order to identify and fix those cases instead of always silently ignore the error.
- Add recommendations and warnings when relevant
- Update the documentation

UPGRADE.md

@@ -1,3 +1,43 @@
+# From 3.1.3 to 3.2.0
+
+- Changes to the `Php` compactor:
+    - Invalid annotations are no longer recognised as annotations:
+        ```php
+        /**
+          * @Annotation ()
+          * @Namespaced\ Annotation
+          */
+        ```
+
+        Will be transformed into:
+
+        ```php
+        /**
+          * @Annotation
+          * @Namespaced
+          */
+        ```
+- The removal of common annotations is enabled by default
+- The setting `annotation#ignore` no longer accepts a `string` value, only `string[]` and `null` are allowed
+- Upon some annotation parsing failures, the error is thrown to the user in order to identify and fix those cases
+  instead of always silently ignore the error.
+- Annotations can no longer be escaped like so:
+
+    ```php
+    /**
+      * \@NotEscaped
+      */
+    ```
+
+    Indeed it will be compacted to:
+
+    ```php
+    /**
+    @NotEscaped
+    */
+    ```
+
+
 # From 2.7 to 3.0
 
 The change from 2.x to 3.x is quite significant but should be really smooth for the user. The main changes are:

box.json.dist

@@ -9,7 +9,10 @@
         "with this source code in the file LICENSE."
     ],
 
-    "files": ["res/schema.json"],
+    "files": [
+        "res/annotation-grammar.pp",
+        "res/schema.json"
+    ],
     "directories-bin": [".requirement-checker"],
 
     "compression": "GZ",

composer.json

@@ -47,7 +47,7 @@
         "beberlei/assert": "^3.0",
         "composer/composer": "^1.6",
         "composer/xdebug-handler": "^1.1.0",
-        "herrera-io/annotations": "~1.0",
+        "hoa/compiler": "^3.17",
         "humbug/php-scoper": "^0.11",
         "justinrainbow/json-schema": "^5.2",
         "nikic/iter": "^1.6",