Annotations Reference

[!IMPORTANT] Support for annotations is deprecated and will be removed in 4.0. PHP 8 users are encouraged to migrate and use attributes instead of annotations. To use annotations, you will need the doctrine/annotations library.

Below you will a reference for annotations supported in this extensions library. There will be introduction on usage with examples. For more detailed usage of each extension, refer to the extension's documentation page.

Index

• Blameable Extension
• IP Traceable Extension
• Loggable Extension
• Reference Integrity Extension
• References Extension
• Sluggable Extension
• Soft Deleteable Extension
• Sortable Extension
• Timestampable Extension
• Translatable Extension
• Tree Extension
• Uploadable Extension

Reference

Blameable Extension

The below annotations are used to configure the Blameable extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\Blameable

The Blameable annotation is a property annotation used to identify fields which are updated to show information about the last user to update the mapped object. A blameable field may have either a string value or a one-to-many relationship with another entity.

Required Attributes:

• on - By default, the annotation configures the property to be updated when an object is updated; this can be set to one of [change, create, update]

Optional Attributes:

• field - An optional list of properties to limit updates to the blameable field; this option is only used when the on option is set to "change" and can be a dot separated path to indicate properties on a related object are watched (i.e. user.email to reference the $email property of the $user relation on this object)

• value - An optional value to require the configured field to match to update the blameable field; this option is only used when the on option is set to "change"

[!WARNING] When both the field and value options are set, the field can only be set to a single field; checking the value against multiple fields is not supported at this time

Examples:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 */
class Article
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string", length=128)
     */
    public ?string $title = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string")
     */
    public ?string $body = null;

    /**
     * Blameable field storing a username for the user who created the entity
     *
     * [@ORM](https://github.com/ORM)\Column(type="string")
     * [@Gedmo](https://github.com/Gedmo)\Blameable(on="create")
     */
    public ?string $createdBy = null;

    /**
     * Blameable field storing a User relation for the user who updated the entity
     *
     * [@ORM](https://github.com/ORM)\ManyToOne(targetEntity="App\Entity\User")
     * [@Gedmo](https://github.com/Gedmo)\Blameable(on="update")
     */
    public ?User $updatedBy = null;

    /**
     * Blameable field storing a username for the user who last changed either the title or body fields
     *
     * [@ORM](https://github.com/ORM)\Column(type="string", nullable=true)
     * [@Gedmo](https://github.com/Gedmo)\Blameable(on="change", field={"title", "body"})
     */
    public ?string $contentChangedBy = null;
}

IP Traceable Extension

The below annotations are used to configure the IP Traceable extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\IpTraceable

The IpTraceable annotation is a property annotation used to identify fields which are updated to record the IP address from the last user to update the mapped object. A traceable field must be a string.

Required Attributes:

• on - By default, the annotation configures the property to be updated when an object is updated; this can be set to one of [change, create, update]

Optional Attributes:

• field - An optional list of properties to limit updates to the IP traceable field; this option is only used when the on option is set to "change" and can be a dot separated path to indicate properties on a related object are watched (i.e. user.email to reference the $email property of the $user relation on this object)

• value - An optional value to require the configured field to match to update the IP traceable field; this option is only used when the on option is set to "change"

[!WARNING] When both the field and value options are set, the field can only be set to a single field; checking the value against multiple fields is not supported at this time

Examples:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 */
class Article
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string", length=128)
     */
    public ?string $title = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string")
     */
    public ?string $body = null;

    /**
     * Traceable field storing an IP address for the user who created the entity
     *
     * [@ORM](https://github.com/ORM)\Column(type="string")
     * [@Gedmo](https://github.com/Gedmo)\IpTraceable(on="create")
     */
    public ?string $createdByIp = null;

    /**
     * Traceable field storing an IP address for the user who updated the entity
     *
     * [@ORM](https://github.com/ORM)\Column(type="string")
     * [@Gedmo](https://github.com/Gedmo)\IpTraceable(on="update")
     */
    public ?string $updatedByIp = null;

    /**
     * Traceable field storing an IP address for the user who last changed either the title or body fields
     *
     * [@ORM](https://github.com/ORM)\Column(type="string", nullable=true)
     * [@Gedmo](https://github.com/Gedmo)\IpTraceable(on="change", field={"title", "body"})
     */
    public ?string $contentChangedByIp = null;
}

Loggable Extension

The below annotations are used to configure the Loggable extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\Loggable

The Loggable annotation is a class annotation used to identify objects which can have changes logged, all loggable objects MUST have this annotation.

Required Attributes:

• logEntryClass - A custom model class implementing Gedmo\Loggable\LogEntryInterface to use for logging changes; defaults to Gedmo\Loggable\Entity\LogEntry for Doctrine ORM users or Gedmo\Loggable\Document\LogEntry for Doctrine MongoDB ODM users

Example:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 * [@Gedmo](https://github.com/Gedmo)\Loggable(logEntryClass="App\Entity\ArticleLogEntry")
 */
class Article {}

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\Versioned

The Versioned annotation is a property annotation used to identify properties whose changes should be logged. This annotation can be set for properties with a single value (i.e. a scalar type or an object such as DateTimeInterface), but not for collections. Versioned fields can be restored to an earlier version.

Example:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 * [@Gedmo](https://github.com/Gedmo)\Loggable
 */
class Comment
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\ManyToOne(targetEntity="App\Entity\Article", inversedBy="comments")
     * [@Gedmo](https://github.com/Gedmo)\Versioned
     */
    public ?Article $article = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string")
     * [@Gedmo](https://github.com/Gedmo)\Versioned
     */
    public ?string $body = null;
}

Reference Integrity Extension

The below annotations are used to configure the Reference Integrity extension.

[!WARNING] This extension is only usable with the Doctrine MongoDB ODM

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\ReferenceIntegrity

The ReferenceIntegrity annotation is a property annotation used to identify fields where referential integrity should be checked. The annotation must be used on a property which references another document, and the reference configuration must have a mappedBy configuration.

Required Attributes:

• value - The type of action to take for the reference, must be one of [nullify, pull, restrict]

Example:

<?php
namespace App\Document;

use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ODM](https://github.com/ODM)\Document(collection="articles")
 */
class Article
{
    /**
     * [@ODM](https://github.com/ODM)\Id
     */
    public ?string $id = null;

    /**
     * [@ODM](https://github.com/ODM)\Field(type="string")
     */
    public ?string $title = null;

    /**
     * [@ODM](https://github.com/ODM)\ReferenceOne(targetDocument="App\Document\User", mappedBy="articles")
     * [@Gedmo](https://github.com/Gedmo)\ReferenceIntegrity("nullify")
     */
    public ?User $author = null;

    /**
     * [@var](https://github.com/var) Collection<int, Comment>
     *
     * [@ODM](https://github.com/ODM)\ReferenceMany(targetDocument="App\Document\Comment", mappedBy="article")
     * [@Gedmo](https://github.com/Gedmo)\ReferenceIntegrity("nullify")
     */
    private Collection $comments;

    public function __construct()
    {
        $this->comments = new ArrayCollection();
    }
}

References Extension

The below annotations are used to configure the References extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\ReferenceOne

The ReferenceOne annotation is a property annotation used to create a reference between two objects in different databases or object managers. This is similar to a ReferenceOne relationship in the MongoDB ODM.

Required Attributes:

• value - The type of action to take for the reference, must be one of [nullify, pull, restrict]

• type - The type of object manager to use for the reference, must be one of [document, entity]

• class - The class name of the object to reference

Optional Attributes:

• identifier - The name of the property to store the identifier value in

• inversedBy - The name of the property on the inverse side of the reference

Example:

<?php
namespace App\Entity;

use App\Document\Article;
use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 */
class Comment
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@Gedmo](https://github.com/Gedmo)\ReferenceOne(type="document", class="App\Document\Article", inversedBy="comments", identifier="articleId")
     */
    public ?Article $article = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string")
     */
    public ?string $articleId = null;
}

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\ReferenceMany

The ReferenceMany annotation is a property annotation used to create a reference between two objects in different databases or object managers. This is similar to a ReferenceMany relationship in the MongoDB ODM.

Required Attributes:

• value - The type of action to take for the reference, must be one of [nullify, pull, restrict]

• type - The type of object manager to use for the reference, must be one of [document, entity]

• class - The class name of the object to reference

Optional Attributes:

• identifier - The name of the property to store the identifier value in

• mappedBy - The name of the property on the owning side of the reference

Example:

<?php
namespace App\Document;

use App\Entity\Comment;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ODM](https://github.com/ODM)\Document(collection="articles")
 */
class Article
{
    /**
     * [@ODM](https://github.com/ODM)\Id
     */
    public ?string $id = null;

    /**
     * [@var](https://github.com/var) Collection<int, Comment>
     *
     * [@Gedmo](https://github.com/Gedmo)\ReferenceMany(type="entity", class="App\Entity\Comment", mappedBy="comments")
     */
    private Collection $comments;

    public function __construct()
    {
        $this->comments = new ArrayCollection();
    }
}

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\ReferenceManyEmbed

The ReferenceManyEmbed annotation is a property annotation used to create a reference between two objects in different databases or object managers. This is similar to a ReferenceMany relationship in the MongoDB ODM.

Required Attributes:

• value - The type of action to take for the reference, must be one of [nullify, pull, restrict]

• type - The type of object manager to use for the reference, must be one of [document, entity]

• class - The class name of the object to reference

Optional Attributes:

• identifier - The name of the property to store the identifier value in

Example:

<?php
namespace App\Document;

use App\Entity\Comment;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ODM](https://github.com/ODM)\Document(collection="articles")
 */
class Article
{
    /**
     * [@ODM](https://github.com/ODM)\Id
     */
    public ?string $id = null;

    /**
     * [@var](https://github.com/var) Collection<int, Comment>
     *
     * [@Gedmo](https://github.com/Gedmo)\ReferenceManyEmbed(type="entity", class="App\Entity\Comment", identifier="metadata.commentId")
     */
    private Collection $comments;

    public function __construct()
    {
        $this->comments = new ArrayCollection();
    }
}

Sluggable Extension

The below annotations are used to configure the Sluggable extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\Slug

The Slug annotation is a property annotation used to identify the field the slug is stored to.

Required Attributes:

• fields - A list of fields on the object to use for generating a slug, this must be a non-empty list of strings

Optional Attributes:

• updatable - Flag indicating the slug can be automatically updated if any of the fields have changed, defaults to true

• style - The style to use while generating the slug, defaults to default (no style changes) and ignores unsupported styles; supported styles are:

  • camel - Converts the slug to a camel-case string
  • lower - Converts the slug to a fully lowercased string
  • upper - Converts the slug to a fully uppercased string

• unique - Flag indicating the slug must be unique, defaults to true

• unique_base - The name of the object property that should be used as a key when doing a uniqueness check, can only be set when the unique flag is true

• separator - The separator to use between words in the slug, defaults to -

• prefix - An optional prefix for the generated slug

• suffix - An optional suffix for the generated slug

• handlers - A list of [@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\SlugHandler annotations used to further customize the slug generator behavior

Basic Example:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 */
class Article
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string", length=128)
     */
    public ?string $title = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string", unique=true)
     * [@Gedmo](https://github.com/Gedmo)\Slug(fields={"title"})
     */
    public ?string $slug = null;
}

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\SlugHandler

The SlugHandler annotation is used with the Slug annotation's handlers attribute to configure slug handlers for the object. Slug handlers can be used to further manipulate and validate the generated slug. Please see the using slug handlers section of the documentation for more information on how to use these handlers.

Required Attributes:

• class - The class name of a Gedmo\Sluggable\Handler\SlugHandlerInterface implementation to use as a handler

Optional Attributes:

• options - A list of [@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\SlugHandlerOption annotations used to configure the slug handler's behavior

Example:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 */
class Article
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\ManyToOne(targetEntity="App\Entity\Category", inversedBy="articles")
     */
    public ?Category $category = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string", length=128)
     */
    public ?string $title = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="string", unique=true)
     * [@Gedmo](https://github.com/Gedmo)\Slug(
     *   fields={"title"},
     *   handlers={
     *     [@Gedmo](https://github.com/Gedmo)\SlugHandler(
     *       class="Gedmo\Sluggable\Handler\TreeSlugHandler",
     *       options={
     *         [@Gedmo](https://github.com/Gedmo)\SlugHandlerOption(name="parentRelationField", value="category"),
     *         [@Gedmo](https://github.com/Gedmo)\SlugHandlerOption(name="separator", value="/")
     *       }
     *     )
     *   }
     * )
     */
    public ?string $slug = null;
}

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\SlugHandlerOption

The SlugHandlerOption annotation is used with the SlugHandler annotation's options attribute to configure the slug handler.

Required Attributes:

• name - The name of the option for the slug handler, must be a non-empty string

Optional Attributes:

• value - A value for the option, defaults to null

Soft Deleteable Extension

The below annotations are used to configure the Soft Deleteable extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\SoftDeleteable

The SoftDeleteable annotation is a class annotation used to identify objects which are soft deleteable.

Required Attributes:

• fieldName - The name of the property in which the soft delete timestamp is stored, defaults to deletedAt; this field must be a field support a DateTimeInterface

Optional Attributes:

• timeAware - Flag indicating the object supports scheduled soft deletes, defaults to false

• hardDelete - Flag indicating the object supports hard deletes, defaults to true

Examples:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 * [@Gedmo](https://github.com/Gedmo)\SoftDeleteable
 */
class Article
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="datetime_immutable")
     */
    public ?\DateTimeImmutable $deletedAt = null;
}

Sortable Extension

The below annotations are used to configure the Sortable extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\SortableGroup

The SortableGroup annotation is a property annotation used to identify fields which are used to group objects of this type for sorting.

Example:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 */
class Article
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\ManyToOne(targetEntity="App\Entity\Category", inversedBy="articles")
     * [@Gedmo](https://github.com/Gedmo)\SortableGroup
     */
    public ?Category $category = null;
}

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\SortablePosition

The SortablePosition annotation is a property annotation used to identify the field where the sorted position (optionally within a group) is stored for the current object type. This field must be an integer field type.

Example:

<?php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/**
 * [@ORM](https://github.com/ORM)\Entity
 */
class Article
{
    /**
    * [@ORM](https://github.com/ORM)\Id
    * [@ORM](https://github.com/ORM)\GeneratedValue
    * [@ORM](https://github.com/ORM)\Column(type="integer")
    */
    public ?int $id = null;

    /**
     * [@ORM](https://github.com/ORM)\Column(type="integer")
     * [@Gedmo](https://github.com/Gedmo)\SortablePosition
     */
    public ?int $position = null;
}

Timestampable Extension

The below annotations are used to configure the Timestampable extension.

[@Gedmo](https://github.com/Gedmo)\Mapping\Annotation\Timestampable

The Timestampable annotation is a property annotation used to identify fields which are updated to record the timestamp of the update the mapped object. A timestampable field must be a field supporting a DateTimeInterface.

Required Attributes:

• on - By default, the annotation configures the property to be updated when an object is updated; this can be set to one of [change, create, update]

Optional Attributes:

• field - An optional list of properties to limit updates to the timestampable field; this option is only used when the on option is set to "change" and can be a dot separated path to indicate properties on a related object are watched (i.e. user.email to reference the $email property of the $user relation on this object)

• value - An optional value to require the configured field to match to update the timestampable field; this option is only used when the on option is set to "change"

[!WARNING] When both the field and value options are set, the field can only be set to a single field; checking the value against multiple fields is not supported at this time

Examples:

<?php
namespace App\Entity;

u...