Download the PHP package metglobal/dto-bundle without Composer

Metglobal Compass DTO Bundle

This bundle is focused to inject request parameters into data transfer objects.

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

Step 2: Enable the Bundle

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

Step 3: Enable the param converter

How to use

Define a controller method parameter with type hint. The type hint must be instance of \Metglobal\Compass\Domain\DTO\Request. If it is symfony will try to resolve the parameters with default configurations. Using the \Metglobal\DTOBundle\DTOParamConverter.

See: \Metglobal\DTOBundle\DTOParamConverter::supports.

Default parameter resolver parameters (see: \Metglobal\DTOBundle\OptionsResolver\ParameterOptionsResolver, \Metglobal\DTOBundle\OptionsResolver\DateParameterOptionsResolver):

[ 'type' => 'string', 'scope' => 'request', 'disabled' => false, 'options' => [], 'undefined' => false ]

Property annotation example:

@Metglobal\Compass\Annotation\DTO\Parameter(
    type="string",
    scope="request",
    path="pathOfThisParameter",
    disabled=false,
    options={},
    undefined=false
)

Available property annotation options

The converter will try to resolve all the things automatically with defaults but you can configure below parameters using the Metglobal\Compass\Annotation\DTO\Parameter annotation and also if you do not define this annotation to property it'll try to resolve the itself too.

type:

Variable's type. Available types are: 'string', 'boolean', 'bool', 'integer', 'int' and 'mixed'. Mixed type allows you to apply any type of value into property.

Warning: boolean type is exceptional see: \Symfony\Component\HttpFoundation\ParameterBag::getBoolean.

scope:

Variable's scope. Available scopes are: 'request', 'query', 'headers', 'attributes'

path:

Variable's path. It's default is property's name but you can customise the path of variable. Example: Url: *.com?testPath=3

It'll set 3 into $differentName.

Warning: This parameter required per property if you do not define, it'll try to resolve the parameter with its property name. It means in above example path will differentName.

disabled:

Disable injection for the selected parameter.

options:

format:
-------
Available when you set type to date. You can configure input datetime's format with this property.

timezone:
--------
Available when you set type to date. You can configure datetime's timezone with this property.

undefinedable:

Make property undefinedable. This property makes you able to find undefined properties.

Extra annotation tips

This annotation can be use at property or class. If you define this property to class it will effect all the classes properties.

Default parameters overrides --> Class annotation parameters (If exists) overrides --> Property annotation parameters (If exists)

For every parameter it call the method that finds the final injection configs per property. Example:

In above class, the $foo will inject from query scope and the $bar will inject from query with integer type cast.

Null/Undefined variables:

Every defined property that has no default value is nullable and can be undefined.

Warning: If you define a default value to property, converter inject the default value instead of null.

Example:

Results would be:

Life cycle events

\Metglobal\DTOBundle\Annotation\PreSet:

Defining this annotation onto methods allows you to access properties before setting the request parameters into target class.

\Metglobal\DTOBundle\Annotation\PostSet:

Defining this annotation onto methods allows you to access properties after setting the request parameters into target class.

The \Metglobal\DTOBundle\CallableRequest interface

You should inject all the simple parameters using above configurations with the @Metglobal\Compass\Annotation\DTO\Parameter annotation but if there is a complex logic that the annotation can not handle you can use this interface as callback method.

In call() method you can modify the object's properties using ...$args variables. Tip 1: Recommended way to hand basic processes is using the life cycle events. Only use this interface if you need to inject anything into target class. Tip 2: If you dont know what does ...$args mean see the RFC: https://wiki.php.net/rfc/argument_unpacking.

Example usage:

Controller:

Request:

Groups

You can group injected properties using @Metglobal\DTOBundle\Annotation\Group annotation.

Example:

Query: ?foo=fooValue&bar=barValue&baz=bazValue&exampleGroup=bug&nextGroup=bug

$fooGroup will be:

$barGroup will be (defined dynamically):

Available Group annotation options

You can use this annotation on classes (it will apply the group options on every property), or on property

target:

Target group variable. Either the target is defined or not, the converter will put the variables into given target.

disabled:

You can still use property injection but it disables grouping for property or whole class.

Important Notes:

• Group properties are not injectable
• Group annotation can be used on class or property
• You can modify groups with @Metglobal\DTOBundle\Annotation\PostSet event
• If you disable property injection (@Metglobal\DTOBundle\Annotation\Parameter(disabled=true)) it will also set the property into group. To disable set group's disabled option to true.

Contributing

If you're having problems, spot a bug, or have a feature suggestion, please log and issue on Github. If you'd like to have a crack yourself, fork the package and make a pull request. Please include tests for any added or changed functionality. If it's a bug, include a regression test.