messages: PHP implementation

.circleci/config.yml

@@ -66,6 +66,13 @@ executors:
     docker:
       - image: cimg/python:3.10.2
     working_directory: ~/cucumber
+
+  # Php
+  docker-circleci-php:
+    docker:
+      - image: cimg/php:8.1.2
+    working_directory: ~/cucumber
+
 ###
 ### Jobs ###
 ###
@@ -677,6 +684,19 @@ jobs:
   #           cd gherkin/elixir
   #           make
 
+  ### PHP
+
+  messages-php:
+    executor: docker-circleci-php
+    steps:
+      - attach_workspace:
+          at: '~/cucumber'
+      - run:
+          name: messages/php
+          command: |
+            cd messages/php
+            make
+
 ###
 ### Workflows ###
 ###
@@ -888,3 +908,9 @@ workflows:
       # - gherkin-elixir:
       #     requires:
       #       - messages-elixir
+
+      ### PHP
+
+      - messages-php:
+          requires:
+            - prepare-parallel

.templates/php/.gitignore

@@ -0,0 +1,4 @@
+vendor
+composer.lock
+.phpunit.cache
+.php-cs-fixer.cache

.templates/php/default.mk

@@ -0,0 +1,51 @@
+# Please update /.templates/php/default.mk and sync:
+#
+#     source scripts/functions.sh && rsync_files
+#
+SHELL := /usr/bin/env bash
+PHP_SOURCE_FILES = $(shell find . -name "*.php")
+
+### COMMON stuff for all platforms
+
+### Common targets for all functionalities implemented on php
+
+default: .tested
+.PHONY: default
+
+pre-release: update-version update-dependencies
+.PHONY: pre-release
+
+update-version:
+ifdef NEW_VERSION
+# TODO: something here?
+endif
+.PHONY: update-version
+
+update-dependencies:
+.PHONY: update-dependencies
+
+publish:
+# TODO: how to publish?
+.PHONY: publish
+
+post-release:
+# no-op
+.PHONY: post-release
+
+clean:
+	rm -rf vendor composer.lock
+.PHONY: clean
+
+.tested: .deps .codegen $(PHP_SOURCE_FILES)
+	vendor/bin/phpunit
+.PHONY: .tested
+
+.deps: composer.lock
+	touch $@
+
+.codegen:
+	touch $@
+
+composer.lock: composer.json
+	composer install
+	touch $@

messages/jsonschema/scripts/codegen.rb

@@ -51,7 +51,7 @@ def default_value(parent_type_name, property_name, property)
     elsif property['type'] == 'string'
       if property['enum']
         enum_type_name = type_for(parent_type_name, property_name, property)
-        "#{enum_type_name}.#{enum_constant(property['enum'][0])}"
+        default_enum(enum_type_name, property)
       else
         "''"
       end
@@ -67,6 +67,10 @@ def default_value(parent_type_name, property_name, property)
     end
   end
 
+  def default_enum(enum_type_name, property)
+    "#{enum_type_name}.#{enum_constant(property['enum'][0])}"
+  end
+
   def enum_constant(value)
     value.gsub(/[\.\/\+]/, '_').upcase
   end
@@ -76,6 +80,7 @@ def type_for(parent_type_name, property_name, property)
     type = property['type']
     items = property['items']
     enum = property['enum']
+
     if ref
       property_type_from_ref(property['$ref'])
     elsif type
@@ -84,8 +89,7 @@ def type_for(parent_type_name, property_name, property)
       else
         raise "No type mapping for JSONSchema type #{type}. Schema:\n#{JSON.pretty_generate(property)}" unless @language_type_by_schema_type[type]
         if enum
-          enum_type_name = "#{parent_type_name}#{capitalize(property_name)}"
-          @enums.add({ name: enum_type_name, values: enum })
+          enum_type_name = enum_name(parent_type_name, property_name, enum)
           property_type_from_enum(enum_type_name)
         else
           @language_type_by_schema_type[type]
@@ -105,6 +109,12 @@ def property_type_from_enum(enum)
     enum
   end
 
+  def enum_name(parent_type_name, property_name, enum)
+    enum_type_name = "#{parent_type_name}#{capitalize(property_name)}"
+    @enums.add({ name: enum_type_name, values: enum })
+    enum_type_name
+  end
+
   def class_name(ref)
     File.basename(ref, '.json')
   end
@@ -295,6 +305,98 @@ def array_type_for(type_name)
   end
 end
 
+class Php < Codegen
+  def initialize(paths)
+    template = File.read("#{TEMPLATES_DIRECTORY}/php.php.erb")
+    enum_template = File.read("#{TEMPLATES_DIRECTORY}/php.enum.php.erb")
+
+    language_type_by_schema_type = {
+      'string' => 'string',
+      'integer' => 'int',
+      'boolean' => 'bool',
+    }
+    super(paths, template, enum_template, language_type_by_schema_type)
+  end
+
+  def format_description(raw_description, indent_string: "        ")
+    return '' if raw_description.nil?
+
+    raw_description
+      .split("\n")
+      .map { |line| line.strip() }
+      .filter { |line| line != '*' }
+      .map { |line| " * #{line}" }
+      .join("\n#{indent_string}")
+  end
+
+  def array_type_for(type_name)
+    "array"
+  end
+
+  def enum_name(parent_type_name, property_name, enum)
+    enum_type_name = "#{class_name(parent_type_name)}\\#{capitalize(property_name)}"
+    @enums.add({ name: enum_type_name, values: enum })
+    enum_type_name
+  end
+
+  def array_contents_type(parent_type_name, property_name, property)
+    type_for(parent_type_name, nil, property['items'])
+  end
+
+  def is_nullable(property_name, schema)
+    !(schema['required'] || []).index(property_name)
+  end
+
+  def is_scalar(property)
+    property.has_key?('type') && @language_type_by_schema_type.has_key?(property['type'])
+  end
+
+  def scalar_type_for(property)
+    raise "No type mapping for JSONSchema type #{type}. Schema:\n#{JSON.pretty_generate(property)}" unless @language_type_by_schema_type[property['type']]
+
+    @language_type_by_schema_type[property['type']]
+  end
+
+  def constructor_for(parent_type, property, property_name, schema, arr_name)
+    constr = non_nullable_constructor_for(parent_type, property, property_name, schema, arr_name)
+
+    is_nullable(property_name, schema) ? "isset($#{arr_name}['#{property_name}']) ? #{constr} : null" : constr
+  end
+
+  def non_nullable_constructor_for(parent_type, property, property_name, schema, arr_name)
+    source = property_name.nil? ? "#{arr_name}" : "#{arr_name}['#{property_name}']"
+    if is_scalar(property)
+      if property['enum']
+        "#{enum_name(parent_type, property_name, property['enum'])}::from((#{scalar_type_for(property)}) $#{source})"
+      else
+        "(#{scalar_type_for(property)}) $#{source}"
+      end
+    else
+      type = type_for(parent_type, property_name, property)
+      if type == 'array'
+        constructor = non_nullable_constructor_for(parent_type, property['items'], nil, schema, "member")
+        member_type = (property['items']['type'] ? 'mixed' : 'array')
+        "array_map(fn (#{member_type} $member) => #{constructor}, $#{source})"
+      else
+        "#{type_for(parent_type, property_name, property)}::fromArray($#{source})"
+      end
+    end
+  end
+
+  def default_value(class_name, property_name, property, schema)
+	if is_nullable(property_name, schema)
+	  return 'null'
+	end
+
+	super(class_name, property_name, property)
+  end
+
+  def default_enum(enum_type_name, property)
+    "#{enum_type_name}::#{enum_constant(property['enum'][0])}"
+  end
+end
+
+
 clazz = Object.const_get(ARGV[0])
 path = ARGV[1]
 paths = File.file?(path) ? [path] : Dir["#{path}/*.json"]

messages/jsonschema/scripts/templates/php.enum.php.erb

@@ -0,0 +1,12 @@
+<%- namespaces = enum[:name].split('\\') -%>
+namespace Cucumber\Messages\<%= namespaces.slice(0,1)[0] %>;
+
+// CLASS_START <%= enum[:name].split('\\').join('/') %>.php
+enum <%= namespaces[-1] %> : string
+{
+<%- enum[:values].each_with_index do |value, index| -%>
+  case <%= enum_constant(value) %> = '<%= value %>';
+<%- end -%>
+}
+
+<%# block to preserve linebreaks %>

messages/jsonschema/scripts/templates/php.php.erb

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This code was auto-generated by {this script}[https://github.com/cucumber/common/blob/main/messages/jsonschema/scripts/codegen.rb]
+ */
+
+namespace Cucumber\Messages;
+
+use JsonSerializable;
+use Cucumber\Messages\DecodingException\SchemaViolationException;
+<%- @schemas.sort.each do |key, schema| -%>
+// CLASS_START <%= class_name(key) %>.php
+/**
+ * Represents the <%= class_name(key) %> message in Cucumber's message protocol
+ * @see https://github.com/cucumber/common/tree/main/messages#readme
+ *
+<%=- format_description(schema['description'], indent_string: '') -%> */
+final class <%= class_name(key) %> implements JsonSerializable
+{
+    use JsonEncodingTrait;
+
+    public function __construct(<%- schema['properties'].each do |property_name, property| -%>
+
+        <%- property_type = type_for(key, property_name, property) -%>
+        <%- if  property['description'] or property_type == 'array' -%>
+        /**
+        <%- if property['description'] -%>
+        <%= format_description(property['description']) %>
+        <%- end -%>
+        <%- if property_type == 'array' -%>
+         * @param <%= is_nullable(property_name, schema) ? '?' : '' %>list<<%= array_contents_type(key, property_name, property) %>> $<%= property_name %>
+        <%- end -%>
+         */
+        <%- end -%>
+        public readonly <%= is_nullable(property_name, schema) ? '?' : '' %><%= property_type %> $<%= property_name %> = <%= default_value(class_name(key), property_name, property, schema) -%>,
+    <%- end -%>
+    ) {
+    }
+
+    /**
+     * @throws SchemaViolationException
+     *
+     * @internal
+     */
+    public static function fromArray(array $arr): self
+    {
+        <%- schema['properties'].each do |property_name, property| -%>
+        self::ensure<%= capitalize(property_name)%>($arr);
+        <%- end -%>
+
+        return new self(
+            <%- schema['properties'].each do |property_name, property| -%>
+            <%= constructor_for(key, property, property_name, schema, 'arr') %>,
+            <%- end -%>
+        );
+    }
+    <%- schema['properties'].each do |property_name, property| -%>
+
+    /**
+        <%- if is_scalar(property) -%>
+     * @psalm-assert array{<%= property_name %><%- if (is_nullable(property_name, schema)) -%>?<%- end -%>: string|int|bool} $arr
+        <%- else -%>
+     * @psalm-assert array{<%= property_name %><%- if (is_nullable(property_name, schema)) -%>?<%- end -%>: array} $arr
+        <%- end -%>
+     */
+    private static function ensure<%= capitalize(property_name)%>(array $arr): void
+    {
+        <%- if (!is_nullable(property_name, schema)) -%>
+        if (!array_key_exists('<%= property_name %>', $arr)) {
+            throw new SchemaViolationException('Property \'<%= property_name %>\' is required but was not found');
+        }
+        <%- end -%>
+        <%- if(is_scalar(property)) -%>
+        if (array_key_exists('<%= property_name %>', $arr) && is_array($arr['<%= property_name %>'])) {
+            throw new SchemaViolationException('Property \'<%= property_name %>\' was array');
+        }
+        <%- else -%>
+        if (array_key_exists('<%= property_name %>', $arr) && !is_array($arr['<%= property_name %>'])) {
+            throw new SchemaViolationException('Property \'<%= property_name %>\' was not array');
+        }
+        <%- end -%>
+    }
+    <%- end -%>
+}
+
+<% end %>

messages/php/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,5 @@
+PLEASE DO NOT CREATE ISSUES IN THIS REPO.
+THIS REPO IS A READ-ONLY MIRROR.
+
+Create your issue in the Cucumber monorepo instead:
+https://github.com/cucumber/cucumber/issues

messages/php/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+PLEASE DO NOT CREATE PULL REAUESTS IN THIS REPO.
+THIS REPO IS A READ-ONLY MIRROR.
+
+Create your pull request in the Cucumber monorepo instead:
+https://github.com/cucumber/cucumber/pulls

messages/php/.gitignore

@@ -0,0 +1,4 @@
+vendor
+composer.lock
+.phpunit.cache
+.php-cs-fixer.cache

messages/php/.rsync

@@ -0,0 +1,3 @@
+../../LICENSE LICENSE
+../../.templates/github/ .github/
+../../.templates/php/ .

messages/php/.subrepo

@@ -0,0 +1 @@
+cucumber/messages-php

messages/php/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Cucumber Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.