README

A Symfony Bundle to use when you want to assert that messages used with Message brokers such like RabbitMQ are compliant with the Zero Downtime Deployment.

Getting started

Installation

You can easily install Zdd Message bundle by composer

$ composer require yousign/zdd-message-bundle

Then, bundle should be registered. Just verify that config\bundles.php is containing :

Yousign\ZddMessageBundle\ZddMessageBundle::class => ['all' => true],

Configuration

Once the bundle is installed, you should create a class to configure the messages to assert and how to create them:

<?php

namespace App\Message;

use Yousign\ZddMessageBundle\Config\ZddMessageConfigInterface;

class MessageConfig implements ZddMessageConfigInterface
{
    /**
     * Return the list of messages to assert.
     */
    public function getMessageToAssert(): array
    {
        return [
            App\Message\MyMessage::class,
            App\Message\AnotherMessage::class,
            //...
        ];
    }

    /**
     * If your message contains no scalar value as parameter such like value enums, value object more complex object,
     * you should use this method to return value for each type hint.
     */
    public function generateValueForCustomPropertyType(string $type): mixed
    {
        return match ($type) {
            'App\ValueObject\Email' => new App\ValueObject\Email('dummy@email.fr'),
            'App\Enum\MyEnum' => App\Enum\MyEnum::MY_VALUE,
            default => null,
        };
    }
}

When the class is created, you can register it as a service.

# config/services.yaml
  App\Message\MessageConfig: ~

Then, you should register it in the configuration (config/packages/zdd_message.yaml) :

# config/packages/zdd_message.yaml
  zdd_message:
    serialized_messages_dir: 'var/serialized_messages' # The directory where the serialized messages will be stored (default: '%kernel.logs_dir%')

Optional configuration

Use a custom serializer

Option to use different serializer. Possible options :

Yousign\ZddMessageBundle\Serializer\ZddMessageMessengerSerializer (default, already configured for messenger serialization in messenger.yaml)
Define your own serializer
- Create a service that implement Yousign\ZddMessageBundle\Serializer\SerializerInterface
- Use it in the configuration

# config/packages/zdd_message.yaml
  zdd_message:
    serializer: '<your-service-id>'

Detect messages not tracked

Option to write a log message if an asynchronous message has been sent (using symfony messenger) and is not present in your configuration.

# config/packages/zdd_message.yaml
zdd_message:
  # ...
  log_untracked_messages:
    messenger:
      enable: true # false by default
      level: 'error' # warning by default

Usage

The bundle comes with commands to assert that your messages are compliant with the Zero Downtime Deployment:

$ bin/console yousign:zdd-message:generate # Generate serialized messages in files.
$ bin/console yousign:zdd-message:validate # Assert that the messages are compliant by deserializing them from files and call the properties.
$ bin/console yousign:zdd-message:debug # Output all tracked messages.

💡 You should run bin/console yousign:zdd-message:generate with the production version code and bin/console yousign:zdd-message:validate with the version code you want to merge.

Example from the version you want to merge:

$ git checkout [production_version]
$ bin/console yousign:zdd-message:generate
$ git checkout - # Go back to the version you want to merge
$ bin/console yousign:zdd-message:validate

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

After writing your fix/feature, you can run following commands to make sure that everything is still ok.

# Install dev dependencies
$ composer install

# Running tests and quality tools locally
$ make all

If you want to use your local fork to develop in your projects, you can use the link command to replace the vendor installation by your local version.

$ ./link /home/yousign/dev/my-project

Authors

Smaine Milianni - ismail1432 - <smaine(dot)milianni@gmail(dot)com>
Simon Mutricy - Inkod - <ink0d@pm(dot)me>

yousign / zdd-message-bundle

Maintainers

Details