digital-craftsman/deserializing-connection

Get DTOs directly from the database

v0.3.1 2024-12-05 12:26 UTC

This package is auto-updated.

Last update: 2024-12-05 12:27:04 UTC


README

A Symfony bundle to get DTOs directly from the database. It's a simple and efficient way to get data from the database and convert it into DTOs without to much noise in your code.

As it's a central part of an application, it's tested thoroughly (including mutation testing).

Latest Stable Version PHP Version Require codecov Packagist Downloads Packagist License

Installation and configuration

Install package through composer:

composer require digital-craftsman/deserializing-connection

⚠️ This bundle can be used (and is being used) in production, but hasn't reached version 1.0 yet. Therefore, there will be breaking changes between minor versions. I'd recommend that you require the bundle only with the current minor version like composer require digital-craftsman/deserializing-connection:0.3.*. Breaking changes are described in the releases and the changelog. Updates are described in the upgrade guide.

Usage

Deserializing connection

When you want DTOs, read models or value objects, you can use the DeserializingConnection to get them directly from the database.

Given the following DTO:

final readonly class User
{
    public function __construct(
        public UserId $userId,
        public string $name,
        public ProjectIdList $accessibleProjects,
    ) {
    }
}

A call for one might look like this:

$user = $this->deserializingConnection->getOne(
    sql: <<<'SQL'
        SELECT
            user_id AS "userId",
            name,
            accessible_projects AS "accessibleProjects"
        FROM
            `user`
        WHERE user_id = :userId
        SQL,
    class: User::class,
    parameters: [
        'userId' => $userId,
    ],
    decoderTypes: [
        'accessibleProjects' => DecoderType::JSON,
    ],
);

These are the offered methods:

  • getOne to return one object or an exception when no result is found.
  • findOne like getOne, but returns null when no result is found.
  • findArray to return an array of objects.
  • findGenerator to return a generator that yields the objects.

Decoding types

Part of the magic is the conversion from database types to PHP types. For example, when your SQL returns a JSON string, you usually need to convert it into an associative array prior to serialization. Here you just need to supply decoderTypes with the column name and the type of decoder you want to use. There are utilities that can handle nullable values or create a empty array when a JSON returns null (relevant for jsonb_agg calls). These are the available decoder types which are all pretty self-explanatory:

  • INT
  • NULLABLE_INT
  • FLOAT
  • NULLABLE_FLOAT
  • JSON
  • NULLABLE_JSON
  • JSON_WITH_EMPTY_ARRAY_ON_NULL

Decoding connection

When you want to get a scalar value or do more complex stuff, you can use the underlying DecodingConnection. It offers the following methods:

  • fetchAssociative
  • fetchAllAssociative
  • fetchInt
  • fetchBool

fetchInt and fetchBool will throw custom exceptions when there are no values or they are not of the expected type.

Normalizers

For easier normalization, use the digital-craftsman/self-aware-normalizers package which is required by this package.

Doctrine types

For easier doctrine types, use the digital-craftsman/self-aware-normalizers package which is required by this package.

Additional documentation