Chore/add migration note (#6)

nick-zh · web-flow · commit 671a7f97a326 · 2020-04-08T14:30:13.000+02:00
* add migration hint

* update readme

* update readme version

* fix stan

* fix stan

* fix stan

* fix stan

* fix stan

* fix stan

* fix stan

* fix stan

* fix stan

* fix stan

* fix stan
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,16 @@
+# Migration from messaging-lib to php-kafka-lib
+
+Internally not much has changed, we have mostly gotten rid of,  
+the general interfaces, since we won't implement support for other  
+messaging systems than Kafka.
+
+In most cases you can just:
+1. `composer remove jobcloud/messaging-lib`
+2. `composer require jobcloud/php-kafka-lib ~0.1`
+3. Replace namespace `Jobcloud\Messaging\Kafka` with `Jobcloud\Kafka`
+4. Replace the following:
+ - `ConsumerException` with `KafkaConsumerConsumeException`
+ - `MessageInterface` with `KafkaMessageInterface` or depending on your use case with `KafkaConsumerMessageInterface` and `KafkaProducerMessageInterface`
+ - `ProducerInterface` with `KafkaProducerInterface`
+ - `ConsumerInterface` with `KafkaConsumerInterface`
+ - `ProducerPool` is not supported anymore
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ can help out to understand the internals of this library.
 - ext-rdkafka: ^4.0.0
 
 ## Installation
-```composer require jobcloud/php-kafka-lib "~1.0"```
+```composer require jobcloud/php-kafka-lib "~0.1"```
 
 ## Usage
 
@@ -260,4 +260,5 @@ while (true) {
 ```
 
 ## Additional information
-Replaces [messaging-lib](https://github.com/jobcloud/messaging-lib)
+Replaces [messaging-lib](https://github.com/jobcloud/messaging-lib)  
+Check [Migration.md](MIGRATION.md) for help to migrate.
diff --git a/composer.json b/composer.json
@@ -23,10 +23,10 @@
     "flix-tech/avro-serde-php": "^1.3"
   },
   "require-dev": {
-    "phpunit/phpunit": "^8.4",
-    "squizlabs/php_codesniffer": "^3.4.2",
-    "phpstan/phpstan": "^0.11.12",
-    "php-mock/php-mock-phpunit": "^2.5",
+    "phpunit/phpunit": "^9.1",
+    "squizlabs/php_codesniffer": "^3.5.4",
+    "phpstan/phpstan": "^0.12.18",
+    "php-mock/php-mock-phpunit": "^2.6",
     "kwn/php-rdkafka-stubs": "^2.0.0",
     "rregeer/phpunit-coverage-check": "^0.3.1",
     "johnkary/phpunit-speedtrap": "^3.1"
diff --git a/docker/dev/php/Dockerfile b/docker/dev/php/Dockerfile
@@ -1,4 +1,4 @@
-FROM php:7.3-cli-alpine3.10
+FROM php:7.3-cli-alpine3.11
 
 # https://getcomposer.org/doc/03-cli.md#composer-allow-superuser
 ENV COMPOSER_ALLOW_SUPERUSER 1
diff --git a/src/Callback/KafkaConsumerRebalanceCallback.php b/src/Callback/KafkaConsumerRebalanceCallback.php
@@ -7,6 +7,7 @@
 use RdKafka\KafkaConsumer as RdKafkaConsumer;
 use Jobcloud\Kafka\Exception\KafkaRebalanceException;
 use RdKafka\Exception as RdKafkaException;
+use RdKafka\TopicPartition as RdKafkaTopicPartition;
 
 // phpcs:disable
 require_once __DIR__ . '/../Exception/KafkaRebalanceException.php'; // @codeCoverageIgnore
@@ -18,7 +19,7 @@ final class KafkaConsumerRebalanceCallback
     /**
      * @param RdKafkaConsumer $consumer
      * @param integer         $errorCode
-     * @param array|null      $partitions
+     * @param array|RdKafkaTopicPartition[]|null      $partitions
      * @throws KafkaRebalanceException
      * @return void
      */
diff --git a/src/Conf/KafkaConfiguration.php b/src/Conf/KafkaConfiguration.php
@@ -11,12 +11,12 @@ class KafkaConfiguration extends RdKafkaConf
 {
 
     /**
-     * @var array
+     * @var string[]
      */
     protected $brokers;
 
     /**
-     * @var array
+     * @var array|TopicSubscription[]
      */
     protected $topicSubscriptions;
 
@@ -26,10 +26,10 @@ class KafkaConfiguration extends RdKafkaConf
     protected $timeout;
 
     /**
-     * @param array $brokers
-     * @param array $topicSubscriptions
+     * @param string[] $brokers
+     * @param array|TopicSubscription[] $topicSubscriptions
      * @param integer $timeout
-     * @param array $config
+     * @param mixed[] $config
      */
     public function __construct(array $brokers, array $topicSubscriptions, int $timeout, array $config = [])
     {
@@ -43,7 +43,7 @@ public function __construct(array $brokers, array $topicSubscriptions, int $time
     }
 
     /**
-     * @return array
+     * @return string[]
      */
     public function getBrokers(): array
     {
@@ -67,15 +67,15 @@ public function getTimeout(): int
     }
 
     /**
-     * @return array
+     * @return string[]
      */
     public function getConfiguration(): array
     {
         return $this->dump();
     }
 
     /**
-     * @param array $config
+     * @param mixed[] $config
      * @return void
      */
     protected function initializeConfig(array $config = []): void
diff --git a/src/Consumer/AbstractKafkaConsumer.php b/src/Consumer/AbstractKafkaConsumer.php
@@ -12,7 +12,6 @@
 use Jobcloud\Kafka\Exception\KafkaConsumerConsumeException;
 use Jobcloud\Kafka\Message\KafkaConsumerMessage;
 use RdKafka\Consumer as RdKafkaLowLevelConsumer;
-use RdKafka\ConsumerTopic as RdKafkaConsumerTopic;
 use RdKafka\Exception as RdKafkaException;
 use RdKafka\KafkaConsumer as RdKafkaHighLevelConsumer;
 use RdKafka\Metadata\Topic as RdKafkaMetadataTopic;
@@ -71,7 +70,7 @@ public function isSubscribed(): bool
     /**
      * Returns the configuration settings for this consumer instance as array
      *
-     * @return array
+     * @return string[]
      */
     public function getConfiguration(): array
     {
@@ -140,7 +139,7 @@ public function getMetadataForTopic(string $topicName): RdKafkaMetadataTopic
      *
      * @param array|RdKafkaTopicPartition[] $topicPartitions
      * @param integer                       $timeout
-     * @return array
+     * @return array|RdKafkaTopicPartition[]
      */
     public function offsetsForTimes(array $topicPartitions, int $timeout): array
     {
diff --git a/src/Consumer/KafkaConsumerBuilder.php b/src/Consumer/KafkaConsumerBuilder.php
@@ -19,12 +19,12 @@ final class KafkaConsumerBuilder implements KafkaConsumerBuilderInterface
     public const CONSUMER_TYPE_HIGH_LEVEL = 'high';
 
     /**
-     * @var array
+     * @var string[]
      */
     private $brokers = [];
 
     /**
-     * @var array
+     * @var array<string, mixed>
      */
     private $config = [
         'enable.auto.offset.store' => false,
@@ -33,7 +33,7 @@ final class KafkaConsumerBuilder implements KafkaConsumerBuilderInterface
     ];
 
     /**
-     * @var array
+     * @var array|TopicSubscription[]
      */
     private $topics = [];
 
@@ -120,7 +120,7 @@ public function withAdditionalBroker(string $broker): KafkaConsumerBuilderInterf
      * Add topic name(s) (and additionally partitions and offsets) to subscribe to
      *
      * @param string  $topicName
-     * @param array   $partitions
+     * @param int[]   $partitions
      * @param integer $offset
      * @return KafkaConsumerBuilderInterface
      */
@@ -141,7 +141,7 @@ public function withAdditionalSubscription(
      * subscribe to
      *
      * @param string  $topicName
-     * @param array   $partitions
+     * @param int[]   $partitions
      * @param integer $offset
      * @return KafkaConsumerBuilderInterface
      */
@@ -159,7 +159,7 @@ public function withSubscription(
     /**
      * Add configuration settings, otherwise the kafka defaults apply
      *
-     * @param array $config
+     * @param string[] $config
      * @return KafkaConsumerBuilderInterface
      */
     public function withAdditionalConfig(array $config): KafkaConsumerBuilderInterface
diff --git a/src/Consumer/KafkaConsumerBuilderInterface.php b/src/Consumer/KafkaConsumerBuilderInterface.php
@@ -25,7 +25,7 @@ public function withAdditionalBroker(string $broker): self;
      * Add topic name(s) (and additionally partition(s) and offset(s)) to subscribe to
      *
      * @param string  $topicName
-     * @param array   $partitions
+     * @param int[]   $partitions
      * @param integer $offset
      * @return KafkaConsumerBuilderInterface
      */
@@ -40,7 +40,7 @@ public function withAdditionalSubscription(
      * subscribe to
      *
      * @param string  $topicName
-     * @param array   $partitions
+     * @param int[]   $partitions
      * @param integer $offset
      * @return KafkaConsumerBuilderInterface
      */
@@ -53,7 +53,7 @@ public function withSubscription(
     /**
      * Add configuration settings, otherwise the kafka defaults apply
      *
-     * @param array $config
+     * @param string[] $config
      * @return KafkaConsumerBuilderInterface
      */
     public function withAdditionalConfig(array $config): self;
diff --git a/src/Consumer/KafkaConsumerInterface.php b/src/Consumer/KafkaConsumerInterface.php
@@ -54,7 +54,7 @@ public function commit($messages): void;
     /**
      * Returns the configuration settings for this consumer instance as array
      *
-     * @return array
+     * @return string[]
      */
     public function getConfiguration(): array;
 
@@ -71,7 +71,7 @@ public function getMetadataForTopic(string $topicName): RdKafkaMetadataTopic;
      *
      * @param array|RdKafkaTopicPartition[] $topicPartitions
      * @param integer                       $timeout
-     * @return array
+     * @return array|RdKafkaTopicPartition[]
      */
     public function offsetsForTimes(array $topicPartitions, int $timeout): array;
 
diff --git a/src/Consumer/KafkaHighLevelConsumer.php b/src/Consumer/KafkaHighLevelConsumer.php
@@ -99,7 +99,7 @@ public function commit($messages): void
     /**
      * Assigns a consumer to the given TopicPartition(s)
      *
-     * @param array $topicPartitions
+     * @param string[]|RdKafkaTopicPartition[] $topicPartitions
      * @throws KafkaConsumerAssignmentException
      * @return void
      */
@@ -127,7 +127,7 @@ public function commitAsync($messages): void
     /**
      * Gets the current assignment for the consumer
      *
-     * @return array
+     * @return array|RdKafkaTopicPartition[]
      * @throws KafkaConsumerAssignmentException
      */
     public function getAssignment(): array
@@ -160,7 +160,7 @@ public function getCommittedOffsets(array $topicPartitions, int $timeout): array
      * Get current offset positions of the consumer
      *
      * @param array|RdKafkaTopicPartition[] $topicPartitions
-     * @return array
+     * @return array|RdKafkaTopicPartition[]
      */
     public function getOffsetPositions(array $topicPartitions): array
     {
@@ -211,8 +211,8 @@ private function commitMessages($messages, bool $asAsync = false): void
     }
 
     /**
-     * @param array $messages
-     * @return array
+     * @param array|KafkaConsumerMessageInterface[] $messages
+     * @return array|RdKafkaTopicPartition[]
      */
     private function getOffsetsToCommitForMessages(array $messages): array
     {
diff --git a/src/Consumer/KafkaHighLevelConsumerInterface.php b/src/Consumer/KafkaHighLevelConsumerInterface.php
@@ -12,7 +12,7 @@ interface KafkaHighLevelConsumerInterface extends KafkaConsumerInterface
     /**
      * Assigns a consumer to the given TopicPartition(s)
      *
-     * @param array $topicPartitions
+     * @param string[]|RdKafkaTopicPartition[] $topicPartitions
      * @return void
      */
     public function assign(array $topicPartitions): void;
@@ -45,7 +45,7 @@ public function getCommittedOffsets(array $topicPartitions, int $timeout): array
      * Get current offset positions of the consumer
      *
      * @param array|RdKafkaTopicPartition[] $topicPartitions
-     * @return array
+     * @return array|RdKafkaTopicPartition[]
      */
     public function getOffsetPositions(array $topicPartitions): array;
 
diff --git a/src/Consumer/KafkaLowLevelConsumer.php b/src/Consumer/KafkaLowLevelConsumer.php
@@ -151,7 +151,7 @@ protected function kafkaConsume(int $timeout): ?RdKafkaMessage
 
     /**
      * @param string $topic
-     * @return array
+     * @return int[]
      * @throws RdKafkaException
      */
     private function getAllTopicPartitions(string $topic): array
diff --git a/src/Consumer/TopicSubscription.php b/src/Consumer/TopicSubscription.php
@@ -24,7 +24,7 @@ final class TopicSubscription implements TopicSubscriptionInterface
 
     /**
      * @param string  $topicName
-     * @param array   $partitions
+     * @param int[]   $partitions
      * @param integer $offset
      */
     public function __construct(
@@ -46,7 +46,7 @@ public function getTopicName(): string
     }
 
     /**
-     * @param array $partitions
+     * @param int[] $partitions
      * @return void
      */
     public function setPartitions(array $partitions): void
diff --git a/src/Consumer/TopicSubscriptionInterface.php b/src/Consumer/TopicSubscriptionInterface.php
@@ -13,12 +13,12 @@ interface TopicSubscriptionInterface
     public function getTopicName(): string;
 
     /**
-     * @return array
+     * @return int[]
      */
     public function getPartitions(): array;
 
     /**
-     * @param array $partitions
+     * @param int[] $partitions
      * @return void
      */
     public function setPartitions(array $partitions): void;
diff --git a/src/Message/AbstractKafkaMessage.php b/src/Message/AbstractKafkaMessage.php
@@ -28,7 +28,7 @@ abstract class AbstractKafkaMessage implements KafkaMessageInterface
     protected $partition;
 
     /**
-     * @var array|null
+     * @var string[]|null
      */
     protected $headers;
 
@@ -65,7 +65,7 @@ public function getPartition(): int
     }
 
     /**
-     * @return array|null
+     * @return string[]|null
      */
     public function getHeaders(): ?array
     {
diff --git a/src/Message/KafkaConsumerMessage.php b/src/Message/KafkaConsumerMessage.php
@@ -25,7 +25,7 @@ final class KafkaConsumerMessage extends AbstractKafkaMessage implements KafkaCo
      * @param integer     $timestamp
      * @param string|null $key
      * @param mixed       $body
-     * @param array|null  $headers
+     * @param string[]|null  $headers
      */
     public function __construct(
         string $topicName,
diff --git a/src/Message/KafkaMessageInterface.php b/src/Message/KafkaMessageInterface.php
@@ -23,7 +23,7 @@ public function getTopicName(): string;
     public function getPartition(): int;
 
     /**
-     * @return array|null
+     * @return string[]|null
      */
     public function getHeaders(): ?array;
 
diff --git a/src/Message/KafkaProducerMessage.php b/src/Message/KafkaProducerMessage.php
@@ -54,7 +54,7 @@ public function withBody($body): KafkaProducerMessageInterface
     }
 
     /**
-     * @param array|null $headers
+     * @param string[]|null $headers
      * @return KafkaProducerMessageInterface
      */
     public function withHeaders(?array $headers): KafkaProducerMessageInterface
diff --git a/src/Message/KafkaProducerMessageInterface.php b/src/Message/KafkaProducerMessageInterface.php
diff --git a/src/Message/Registry/AvroSchemaRegistryInterface.php b/src/Message/Registry/AvroSchemaRegistryInterface.php
diff --git a/src/Producer/KafkaProducer.php b/src/Producer/KafkaProducer.php
diff --git a/src/Producer/KafkaProducerBuilder.php b/src/Producer/KafkaProducerBuilder.php
diff --git a/src/Producer/KafkaProducerBuilderInterface.php b/src/Producer/KafkaProducerBuilderInterface.php

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-FROM php:7.3-cli-alpine3.10`
	`1`	`+FROM php:7.3-cli-alpine3.11`
`2`	`2`
`3`	`3`	`# https://getcomposer.org/doc/03-cli.md#composer-allow-superuser`
`4`	`4`	`ENV COMPOSER_ALLOW_SUPERUSER 1`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,6 @@`
`12`	`12`	`use Jobcloud\Kafka\Exception\KafkaConsumerConsumeException;`
`13`	`13`	`use Jobcloud\Kafka\Message\KafkaConsumerMessage;`
`14`	`14`	`use RdKafka\Consumer as RdKafkaLowLevelConsumer;`
`15`		`-use RdKafka\ConsumerTopic as RdKafkaConsumerTopic;`
`16`	`15`	`use RdKafka\Exception as RdKafkaException;`
`17`	`16`	`use RdKafka\KafkaConsumer as RdKafkaHighLevelConsumer;`
`18`	`17`	`use RdKafka\Metadata\Topic as RdKafkaMetadataTopic;`
`@@ -71,7 +70,7 @@ public function isSubscribed(): bool`
`71`	`70`	`/**`
`72`	`71`	`* Returns the configuration settings for this consumer instance as array`
`73`	`72`	`*`
`74`		`- * @return array`
	`73`	`+ * @return string[]`
`75`	`74`	`*/`
`76`	`75`	`public function getConfiguration(): array`
`77`	`76`	`{`
`@@ -140,7 +139,7 @@ public function getMetadataForTopic(string $topicName): RdKafkaMetadataTopic`
`140`	`139`	`*`
`141`	`140`	`* @param array\|RdKafkaTopicPartition[] $topicPartitions`
`142`	`141`	`* @param integer $timeout`
`143`		`- * @return array`
	`142`	`+ * @return array\|RdKafkaTopicPartition[]`
`144`	`143`	`*/`
`145`	`144`	`public function offsetsForTimes(array $topicPartitions, int $timeout): array`
`146`	`145`	`{`