digital-craftsman / deserializing-connection
Get DTOs directly from the database
Installs: 166
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Type:symfony-bundle
Requires
- php: 8.3.*|8.4.*
- digital-craftsman/self-aware-normalizers: ^0.1.0|^0.2.0
- doctrine/dbal: ^3.3.6
- symfony/framework-bundle: ^7.1
- symfony/serializer: ^7.1
Requires (Dev)
- digital-craftsman/ids: ^1.3
- friendsofphp/php-cs-fixer: ^v3.59.3
- infection/infection: 0.27.*
- phpunit/phpunit: ^10.5
- symfony/property-access: ^7.1
- symfony/property-info: ^7.1
- vimeo/psalm: ^5.25
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).
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
likegetOne
, but returnsnull
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.