Doctrine Templates

softspring/doctrine-templates is a small toolbox of reusable Doctrine model pieces.

It is useful when many entities in an application repeat the same kinds of fields: ids, names, slugs, timestamps, addresses, or simple contact-card data.

Instead of rewriting those pieces in each project, this component gives you embeddables, traits, interfaces, and form types that you can compose into your own entities.

Why Use It

Use this package when:

several entities need the same small field sets
you want a reusable Address or HCard embeddable
you want matching Symfony form types for those embeddables
you prefer lightweight traits over a bigger shared base entity hierarchy

This package does not try to define your full domain model. It gives you reusable building blocks.

Installation

composer require softspring/doctrine-templates:^6.0

What The Package Provides

The component has three main parts:

embeddables for structured address and contact data
traits for recurring Doctrine fields and ids
Symfony form types for editing those embeddables

Embeddables

The package includes these embeddables:

Address
HAddress
HCard

They implement matching interfaces and are designed to be embedded into your own entities.

Address

Address stores:

postOfficeBox
streetAddress
extendedAddress
locality
region
postalCode
countryCode

Typical usage:

<?php

use Doctrine\ORM\Mapping as ORM;
use Softspring\Component\DoctrineTemplates\Entity\Embeddable\Address;

#[ORM\Entity]
class Customer
{
    #[ORM\Embedded(class: Address::class)]
    protected Address $billingAddress;
}

HAddress And HCard

HAddress extends the address contract and HCard adds:

name
surname
tel

Use HCard when you want contact-style data stored together with the address.

Form Types

The package includes:

AddressType
HAddressType
HCardType

These form types are useful when your entity embeds one of the provided value objects and you want a ready-to-use form layer.

AddressType

AddressType builds a practical address form and adds useful browser autocomplete hints.

Typical usage:

<?php

use Softspring\Component\DoctrineTemplates\Form\AddressType;

$builder->add('billingAddress', AddressType::class);

By default it includes:

streetAddress
extendedAddress
postalCode
locality
region
countryCode

It hides postOfficeBox unless you enable it.

Useful AddressType Options

AddressType includes a few practical options:

address_lines
show_post_office_box
show_country
country_choices
autocomplete_section

Example:

<?php

$builder->add('shippingAddress', AddressType::class, [
    'address_lines' => 1,
    'show_post_office_box' => true,
    'country_choices' => ['ES', 'FR', 'PT'],
    'autocomplete_section' => 'shipping',
]);

This is useful when:

you want a single street-address line
you only support a small set of countries
you want clean browser autocomplete for multiple address groups in the same page

HCardType

HCardType builds on top of AddressType and adds:

name
surname
tel

That makes it a good fit for contact persons, shipping contacts, or business contact data stored as an embeddable inside a larger entity.

Traits For Entity Fields

The package also provides many reusable traits for common entity fields.

The important point is that these traits represent different modeling choices. You should pick only the ones that fit your entity.

Identity Traits

Examples:

AutoId
Guid
KeyIdTrait
UniqId
UniqIdString
ToStringIdTrait

Use them when you want a ready-made id strategy without rewriting the same field and accessor in many entities.

Do not combine multiple id traits in the same entity.

Naming And Slug Traits

Examples:

Named
NamedString
SlugTrait
CurrencyTrait

These are simple traits for small recurring fields.

They are useful in admin-heavy applications where many entities need the same handful of columns.

Timestamp Traits

The package offers two timestamp styles:

TimestampMarks: stores DateTime values
Timestamps: stores Unix timestamps and exposes them as DateTime

That means the package supports both styles, but you should choose one approach per entity model.

Do not mix both timestamp systems blindly in the same entity tree.

Recommended Usage Pattern

This component works best when you treat it as a toolbox.

A good pattern is:

choose one id strategy
choose whether the entity needs a reusable embeddable such as Address or HCard
add only the small field traits that really belong to the entity
use the matching Symfony form type where it saves time

That keeps your entity readable and avoids trait combinations that fight each other.

Extending The Package

The safest way to extend this package is composition, not modification.

Good extension patterns are:

create your own embeddable that reuses one of the traits
extend AddressType or HCardType when you need extra fields or project-specific options
implement your own interfaces or validation rules on top of the provided model contracts

This is usually better than forking the package just to add a few project-specific fields.

Practical Limits

Keep these limits in mind:

the package gives you templates, not a complete persistence architecture
some traits are alternatives to each other, not pieces to stack together blindly
validation rules are mostly your responsibility
lifecycle strategy still belongs to your application and Doctrine mapping decisions

In short: it saves repetition, but it does not remove the need to design your own domain model carefully.

Summary

Choose doctrine-templates when your application repeatedly needs the same Doctrine embeddables, id styles, timestamp traits, and matching form types, and you want to reuse those pieces without building a bigger abstract model layer.