README

The Core Package is a reusable library that provides essential functionality and common classes for building microservices within our project. It serves as a foundation for developing consistent and efficient microservices by promoting code reuse and maintaining shared functionality.

Installation

To install this package in the Symfony project, run composer require healios/core

Purpose

The Core Package aims to:

Reduce code duplication across microservices.
Ensure consistency in class structures, interfaces, and common operations.
Provide a centralized location for commonly used classes and utilities.

Key Classes

Query and QueryHandler

The Query interface represents read-only operations or data retrieval requests within a microservice.

How to Use: To implement a new query, create a class that implements the Query interface and define the necessary properties and methods. The corresponding QueryHandler should implement the logic for executing the query and returning the requested data.

Command and CommandHandler

The Command interface represents write operations or actions that modify the system state or trigger side effects within a microservice.

How to Use: To implement a new command, create a class that implements the Command interface and define the required properties and methods. The corresponding CommandHandler should implement the logic for handling the command and performing the necessary operations.

Repository

The AbstractDoctrineRepository is a base class that provides a foundation for implementing repositories using Doctrine ORM (Object-Relational Mapping). It includes common functionality and boilerplate code, reducing the effort required to set up and manage repositories.

How to Use: To create a repository for a specific entity, extend the AbstractDoctrineRepository class and customize it based on your microservice's requirements. Implement additional methods for querying, filtering, sorting, and pagination as needed.

QueryParams

The QueryParams class provides a standardized way to pass query parameters to the query handlers. It encapsulates the various filter, sorting, and pagination options that can be applied to query results.

How to Use: Extend the BaseQueryParams class to create a custom QueryParams class specific to your microservice's query requirements. Customize the class by adding properties and methods to represent the supported query parameters and their validation rules.

Messenger + fan-out Events and Commands

For our events, we use a fan-out type in RabbitMQ so that we can propagate messages across different microservices and an event can be consumed in multiple microservices, but not all of them.

To handle the case where a message does not need to be consumed in a specific microservice, we use a custom Serializer + UnknownEvent + UnknownEventListener (you can extend it if necessary). And the same for Commands.

Here is an example using a custom serializer:

NNNN_amqp_command_transport:
  dsn: '%env(ENQUEUE_DSN)%'
  serializer: healios_core.messenger.command_serializer
  options:
    exchange:
      name: ex_command
      type: fanout
    queues:
      NNNN_amqp_command_transport: ~
NNNN_amqp_event_transport:
  dsn: '%env(ENQUEUE_DSN)%'
  serializer: healios_core.messenger.event_serializer
  options:
    exchange:
      name: ex_event
      type: fanout
    queues:
      NNNN_amqp_event_transport: ~

Note: Minimum version of symfony/amqp-messenger 6.3.4 is required.

Guidelines for Implementation and Extension

Consistency: Ensure that the implementation of new classes adheres to the conventions and patterns established in the Core Package. Follow consistent naming conventions, use appropriate interfaces, and maintain a clear separation of concerns.

Modularity: Strive for loose coupling between components and maintain a modular structure. Avoid excessive dependencies and promote reusability by keeping classes independent and focused on specific responsibilities.

Extensibility: Design classes and interfaces with extensibility in mind. Consider potential future requirements and allow for easy extension and customization without modifying the core functionality.

Documentation: Document the purpose, usage, and any specific considerations for each class or utility added to the Core Package. Provide clear examples and guidelines to facilitate understanding and adoption by developers working on microservices.

Testing: Ensure proper test coverage for the Core Package and any new classes or modifications introduced. Write unit tests to validate the behavior and functionality of the classes and utilities.

healios / cqrs

Maintainers

Details