README

A Symfony bundle for generating type-safe transfer objects (DTOs) from XML schema definitions. Supports OpenAPI attribute generation for API documentation.

Table of Contents

• Installation
• Configuration
• Usage
  • Defining Transfers
  • Property Attributes
  • Generating Transfers
• OpenAPI Integration
• Development

Installation

composer require philipphermes/transfer-bundle

Register the bundle in config/bundles.php:

return [
    // ...
    PhilippHermes\TransferBundle\PhilippHermesTransferBundle::class => ['all' => true],
];

Configuration

Create config/packages/transfer.yaml to customize the bundle:

transfer:
    schema_dirs:
        - '%kernel.project_dir%/transfers'
    exclude_dirs: []
    output_dir: '%kernel.project_dir%/src/Generated/Transfers'
    namespace: 'App\Generated\Transfers'

Configuration Options

Vendor-Level Discovery

To include transfers from vendor packages:

transfer:
    schema_dirs:
        - '%kernel.project_dir%/transfers'
        - '%kernel.project_dir%/vendor/*/*/transfers'
    exclude_dirs:
        - '%kernel.project_dir%/vendor/*/tests'
        - '%kernel.project_dir%/vendor/*/*/tests'

Usage

Defining Transfers

Create XML schema files in your configured schema directories (default: transfers/).

<?xml version="1.0" encoding="UTF-8"?>
<transfers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="vendor/philipphermes/transfer-bundle/src/Resources/schema/transfer.xsd">

    <transfer name="User">
        <property name="email" type="string" description="The email of the user"/>
        <property name="password" type="string" description="The password of the user"/>
        <property name="addresses" type="Address[]" singular="address" isNullable="true"/>
        <property name="roles" type="string[]"/>
    </transfer>

    <transfer name="Address">
        <property name="street" type="string"/>
    </transfer>

</transfers>

Key features:

• Multiple XML files are supported and will be merged
• Transfers with the same name across files are combined
• First definition of a property takes precedence

Property Attributes

Generating Transfers

Run the generator command:

php bin/console transfer:generate

Options:

• --clean-disable - Skip cleaning the output directory before generation

OpenAPI Integration

Add api="true" to transfers to automatically generate OpenAPI attributes.

Transfer Attributes

Example

<transfer name="User" api="true" apiAlias="UserResource">
    <property name="email" type="string" description="The email of the user"/>
    <property name="password" type="string" description="The password of the user"/>
</transfer>

<transfer name="Error" api="true">
    <property name="status" type="int"/>
    <property name="message" type="string"/>
</transfer>

Use in your controllers with NelmioApiDocBundle:

use App\Generated\Transfers\UserTransfer;
use App\Generated\Transfers\ErrorTransfer;
use Nelmio\ApiDocBundle\Annotation\Model;
use OpenApi\Attributes as OA;

class UserApiController extends AbstractController
{
    #[OA\Tag(name: 'user')]
    #[OA\Response(
        response: 200,
        description: 'Returns a user by id',
        content: new Model(type: UserTransfer::class)
    )]
    #[OA\Response(
        response: 404,
        description: 'User not found',
        content: new Model(type: ErrorTransfer::class)
    )]
    #[Route('/api/user/{id}', methods: ['GET'])]
    public function getUserById(int $id): Response
    {
        // ...
    }
}

Note

Child transfers do not inherit api="true" - you must set it explicitly on each transfer.

Development

Static Analysis

vendor/bin/phpstan analyse --memory-limit=1G

Testing

vendor/bin/phpunit

With coverage report:

XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage-report