Gherkin PHP implementation (#1911)

* Gherkin PHP folder with testdata

* Generated parser with correct types

* Working tokeniser

* Emit Source messages

* Emit ASTs

* Emit Pickles

* Emit Error messages

* Update changelog, license, readme, package description

* Change GherkinParser::parse API to remove responsibility for file reading

* Fix rsync issues

* Add local messages repository for Composer

This allows us to 'install' messages from local, which is useful when working across project

* Support UUID IDs

* Removed redundant lines, fixed some incorrect docblocks

* Check public-facing parse() receives Source objects

* Remove redundant getters

* Scan tokens progressively rather than splitting into a big array

* Fix some wrong imports

* Don't throw logic exceptions during parsing

* Stricter return type for AstNode::getSingle

* Regex for efficiently splitting table cells

Thanks to Gregor Harlan <[email protected]>

* Refactor GherkinLIne handling to more idiomatic PHP (and regex for cell parsing)

* Rationalise the Makefile setup

* Remove unused Token::detach method

* Remove local path repository for pre-release

* Add parallel PHP gherkin job

* Scripts to update the composer dependencies pre and post-release

* Add Gherkin-php subrepo

* Enforce trailing commas

* Various refactorings from code review

* Better makefiles

Author: ciaranmcnulty

php/.gitignore

@@ -4,3 +4,4 @@ composer.lock
 .php-cs-fixer.cache
 .codegen
 .deps
+.tested

php/.php-cs-fixer.php

@@ -0,0 +1,11 @@
+<?php
+$finder = PhpCsFixer\Finder::create()
+    ->in([
+        __DIR__ . '/src',
+        __DIR__ . '/src-generated',
+        __DIR__ . '/tests',
+    ])
+;
+
+$config = new PhpCsFixer\Config();
+return $config->setFinder($finder);

php/Makefile

@@ -4,11 +4,20 @@ JSONSCHEMAS = $(shell find ../jsonschema -name "*.json")
 
 clean: clean-build
 
-.codegen: $(JSONSCHEMAS) ../jsonschema/scripts/codegen.rb ../jsonschema/scripts/templates/php.php.erb
+.codegen: $(JSONSCHEMAS) ../jsonschema/scripts/codegen.rb ../jsonschema/scripts/templates/php.php.erb build/messages.php
+
+post-release: update-gherkin-dependency
+
+update-gherkin-dependency:
+	php scripts/update-gherkin-dependency.php ../../gherkin/php/composer.json > gherkin-composer.json
+	jq --indent 4 < gherkin-composer.json > ../../gherkin/php/composer.json
+	rm gherkin-composer.json
+.PHONY: update-gherkin-dependency
+
+build/messages.php:
 	ruby ../jsonschema/scripts/codegen.rb Php ../jsonschema php.php.erb > build/messages.php
 	ruby ../jsonschema/scripts/codegen.rb Php ../jsonschema php.enum.php.erb >> build/messages.php
 	csplit --quiet --prefix=build/Generated --suffix-format=%02d.php.tmp --elide-empty-files build/messages.php /^.*[.]php$$/ {*}
-	rm build/messages.php
 	rm -rf src-generated/*
 	for file in build/Generated**; do mkdir -p src-generated/$$(head -n 1 $$file | sed 's/[^/]*.php$$//'); done
 	for file in build/Generated**; do tail -n +2 $$file > src-generated/$$(head -n 1 $$file); rm $$file; done
@@ -17,10 +26,3 @@ clean: clean-build
 clean-build:
 	rm -rf build/messages.php
 	rm -rf src-generated/*
-
-.tested: .cs-fixer
-
-.cs-fixer:
-	vendor/bin/php-cs-fixer --dry-run --diff fix src
-	vendor/bin/php-cs-fixer --dry-run --diff fix src-generated
-	vendor/bin/php-cs-fixer --dry-run --diff fix tests

php/composer.json

@@ -6,7 +6,8 @@
     "type": "library",
     "require": {
         "php": "^8.1",
-        "ext-json": "*"
+        "ext-json": "*",
+        "ramsey/uuid": "^4.2"
     },
     "require-dev": {
         "vimeo/psalm": "^4.18",
@@ -16,7 +17,19 @@
     },
     "autoload": {
         "psr-4": {
-            "Cucumber\\Messages\\": ["src","src-generated"]
+            "Cucumber\\Messages\\": [
+                "src",
+                "src-generated"
+            ]
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Cucumber\\Messages\\": [
+                "src",
+                "src-generated",
+                "tests"
+            ]
         }
     }
 }

php/default.mk

@@ -7,6 +7,15 @@ PHP_SOURCE_FILES = $(shell find . -name "*.php")
 
 ### COMMON stuff for all platforms
 
+BERP_VERSION = 1.3.0
+BERP_GRAMMAR = gherkin.berp
+
+define berp-generate-parser =
+-! dotnet tool list --tool-path /usr/bin | grep "berp\s*$(BERP_VERSION)" && dotnet tool update Berp --version $(BERP_VERSION) --tool-path /usr/bin
+berp -g $(BERP_GRAMMAR) -t $< -o $@ --noBOM
+endef
+
+
 ### Common targets for all functionalities implemented on php
 
 default: .tested
@@ -22,6 +31,7 @@ endif
 .PHONY: update-version
 
 update-dependencies:
+	composer update
 .PHONY: update-dependencies
 
 publish:
@@ -33,20 +43,21 @@ post-release:
 .PHONY: post-release
 
 clean:
+	rm -rf .tested .deps .codegen
 	rm -rf vendor composer.lock
 .PHONY: clean
 
-.tested: .deps .codegen $(PHP_SOURCE_FILES)
+.tested: .deps $(PHP_SOURCE_FILES)
+	vendor/bin/php-cs-fixer --dry-run --diff fix
+	vendor/bin/psalm --no-cache
 	vendor/bin/phpunit
-	vendor/bin/psalm
-.PHONY: .tested
+	touch $@
 
-.deps: composer.lock
+.deps: vendor .codegen
 	touch $@
 
 .codegen:
 	touch $@
 
-composer.lock: composer.json
+vendor: composer.json
 	composer install
-	touch $@

php/scripts/update-gherkin-dependency.php

@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * Updates the dependency in the Composer repo (outputs unindented string)
+ */
+
+if ($argc !== 2) {
+    fwrite(STDERR, 'Please provide a single JSON file path' . "\n");
+    exit(1);
+}
+
+$composerFile = $argv[1];
+
+if(!$newVersion = getenv('NEW_VERSION')) {
+    fwrite(STDERR, 'NEW_VERSION env var must be set' . "\n");
+    exit(1);
+}
+
+try {
+    $json = json_decode(@file_get_contents($composerFile), true, flags: JSON_THROW_ON_ERROR);
+}
+catch (\Throwable $t)
+{
+    fwrite(STDERR, 'Could not read JSON from ' . $composerFile . "\n");
+    exit(1);
+}
+
+if (!isset($json['require']['cucumber/messages'])) {
+    fwrite(STDERR, 'Provided JSON does not have a dependency on cucumber/messages' . "\n");
+    exit(1);
+}
+
+$dependencyString = $json['require']['cucumber/messages'];
+
+if (!preg_match('/^(?<major>\\d+)\\.\\d+\\.\\d+$/', $newVersion, $matches)) {
+    fwrite(STDERR, 'New version was not in the format XX.XX.XX' . "\n");
+    exit(1);
+}
+
+// like ^21.0 (same as >=21.0.0 <22.0.0)
+$newDependency = ',^'.$matches['major'].'.0';
+
+if (str_contains($dependencyString, $newDependency)) {
+    fwrite(STDERR, 'Nothing to update, already depends on ' . $newDependency . "\n");
+    $newDependency = '';
+}
+
+$newDependencyString = $dependencyString . $newDependency;
+
+$json['require']['cucumber/messages'] = $newDependencyString;
+
+echo json_encode($json);

php/src/Id/UuidIdGenerator.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cucumber\Messages\Id;
+
+use Ramsey\Uuid\Uuid;
+
+final class UuidIdGenerator implements IdGenerator
+{
+    public function newId(): string
+    {
+        return Uuid::uuid4()->toString();
+    }
+}

php/tests/Cucumber/Messages/Id/IncrementingIdGeneratorTest.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Cucumber\Messages\Id;
+
+trait IdGeneratorTestTrait
+{
+    private IdGenerator $idGenerator;
+
+    public function testItDoesNotGenerateEmptyIds(): void
+    {
+        self::assertNotEquals('', $this->idGenerator->newId());
+    }
+
+    public function testItDoesNotRepeatIds(): void
+    {
+        $id1 = $this->idGenerator->newId();
+        $id2 = $this->idGenerator->newId();
+
+        self::assertNotEquals($id1, $id2);
+    }
+}

php/tests/Id/IdGeneratorTestTrait.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cucumber\Messages\Id;
+
+use PHPUnit\Framework\TestCase;
+
+final class IncrementingIdGeneratorTest extends TestCase
+{
+    use IdGeneratorTestTrait;
+
+    public function setUp(): void
+    {
+        $this->idGenerator = new IncrementingIdGenerator();
+    }
+
+    public function testItIncrementsFromZero(): void
+    {
+        self::assertSame('0', $this->idGenerator->newId());
+        self::assertSame('1', $this->idGenerator->newId());
+        self::assertSame('2', $this->idGenerator->newId());
+        self::assertSame('3', $this->idGenerator->newId());
+    }
+}