README.md

dto-handler-bundle

This version of the bundle requires Symfony 3.4+.

The dto-handler-bundle loads the content of a request into a Data Transfer Object (DTO), mapping its properties such as entities from the database. It uses the ParamConverterInterface provided by the SensioLabs Framework Extra Bundle to automatically map the request content to the appropriate variables.

Quick Start

The dto-handler-bundle is simple to use as it requires almost no configuration. To use it in a controller, simply declare the variable in the controller's argument:

public function postAction(DummyDataTransferObject $dto): Response
{
   // ...
}

And add the DTO annotation to your DTO:

/**
 * @DTO
 */
final class DummyDataTransferObject
{
    // ...
}

Table of content

1. Installation
2. Getting started
   • Set up the Data Transfer Object
   • Configure the ParamConverter
   • Some utilities
3. Example
4. Versioning
5. Contributing
6. Hacking
7. License

1. Installation

This bundle required at least Symfony 3.4.

You can use composer to install dto-handler-bundle:

composer require chaplean/dto-handler-bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...
            new Chaplean\Bundle\DtoHandlerBundle\ChapleanDtoHandlerBundle(),
        ];

        // ...
    }

    // ...
}

2. Getting started

• Set up the Data Transfer Object
• Configure the ParamConverter

3. Example

In the following example, the data contained in the request will be loaded in the DTO.

The $property1 and the $property2 will be not changed, so their values will be the one set in the request.

The $property3 will be mapped to the appropriate entity using the field keyname, so the value of the property3 field in the request should be a keyname of the DummyEntity.

The $property4 will be an array of the entities mapped by id, so the property4 value in the request should be an array of id.

Controller:

/**
 * ...
 *
 * @ParamConverter(
 *     name="dtoVariable",
 *     converter="data_transfer_object_converter",
 *     options={"validations": "violationsList"}
 * )
 *
 * @param DummyDataTransferObject          $dummyDataTransferObject
 * @param ConstraintViolationListInterface $violationsList
 *
 * @return Response
 */
public function postAction(
    DummyDataTransferObject $dummyDataTransferObject,
    ConstraintViolationListInterface $violationsList
): Response {
    // ...
}

Data Transfer Object (DummyDataTransferObject):

/**
 * Class DummyDataTransferObject.
 *
 * @DTO
 */
final class DummyDataTransferObject
{
    /**
     * @var string
     */
    public $property1;

    /**
     * @var integer
     *
     * @Assert\Type("integer")
     */
    public $property2;

    /**
     * @var DummyEntity
     *
     * @Assert\Type("Chaplean\Bundle\DtoHandlerBundle\Tests\Resources\Entity\DummyEntity")
     * @MapTo("keyname")
     */
    public $property3;

    /**
     * @var DummyEntity
     *
     * @Assert\All(
     *    @Assert\Type("Chaplean\Bundle\DtoHandlerBundle\Tests\Resources\Entity\DummyEntity")
     * )
     */
    public $property4;
}

4. Versioning

dto-handler-bundle follows semantic versioning. In short the scheme is MAJOR.MINOR.PATCH where

1. MAJOR is bumped when there is a breaking change,
2. MINOR is bumped when a new feature is added in a backward-compatible way,
3. PATCH is bumped when a bug is fixed in a backward-compatible way.

Versions bellow 1.0.0 are considered experimental and breaking changes may occur at any time.

5. Contributing

Contributions are welcomed! There are many ways to contribute, and we appreciate all of them. Here are some of the major ones:

• Bug Reports: While we strive for quality software, bugs can happen and we can't fix issues we're not aware of. So please report even if you're not sure about it or just want to ask a question. If anything the issue might indicate that the documentation can still be improved!
• Feature Request: You have a use case not covered by the current api? Want to suggest a change or add something? We'd be glad to read about it and start a discussion to try to find the best possible solution.
• Pull Request: Want to contribute code or documentation? We'd love that! If you need help to get started, GitHub as documentation on pull requests. We use the "fork and pull model" were contributors push changes to their personnal fork and then create pull requests to the main repository. Please make your pull requests against the master branch.

As a reminder, all contributors are expected to follow our Code of Conduct.

6. Hacking

You might find the following commands usefull when hacking on this project:

# Install dependencies
composer install

# Run tests
bin/phpunit

7. License

dto-handler-bundle is distributed under the terms of the MIT license.

See LICENSE for details.