philipphermes/transfer-bundle

generates transfers from xml

1.4.0 2026-03-09 12:11 UTC

Requires

• php: >=8.3
• ext-simplexml: *
• nette/php-generator: ^4.2
• symfony/config: >=7.4
• symfony/console: >=7.4
• symfony/dependency-injection: >=7.4
• symfony/filesystem: >=7.4
• symfony/finder: >=7.4
• symfony/framework-bundle: >=7.4

Requires (Dev)

• nelmio/api-doc-bundle: ^v5.8.3
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.1

Suggests

• nelmio/api-doc-bundle: For API Documentation

MIT

• Philipp Hermes

• generator
• transfer
• dto

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

Option	Default	Description
schema_dirs	['%kernel.project_dir%/transfers']	Directories to scan for XML schema files (supports glob patterns)
exclude_dirs	[]	Directories to exclude from scanning
output_dir	%kernel.project_dir%/src/Generated/Transfers	Output directory for generated transfer classes
namespace	App\Generated\Transfers	PHP namespace for generated classes

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

Attribute	Required	Description
name	Yes	Property name
type	Yes	PHP type (string, int, bool, float, array, Transfer, Transfer[])
description	No	Property description (used in OpenAPI docs)
singular	No	Singular name for array properties (enables addX() method)
isNullable	No	Whether the property can be null (true/false)

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

Attribute	Required	Description
name	Yes	Transfer name (generates {name}Transfer class)
api	No	Set to true to generate OpenAPI attributes
apiAlias	No	Custom name for OpenAPI documentation (default: transfer name without "Transfer" suffix)

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