Doctrine Behavioral Extensions

The package provides several behaviors that can be attached to the Doctrine event system.

ORM & MongoDB ODM Extensions

• Blameable: Updates string or reference fields (e.g., a user object) on create, update, or property change.
• Loggable: Tracks changes and history of objects; supports version management.
• Sluggable: Converts specified fields into unique URL-friendly slugs.
• Timestampable: Updates date fields on create, update, or property change.
• Translatable: Provides a solution for translating records into different languages.
• Tree: Automates tree handling (supports closure, nested set, or materialized path). Note: MongoDB ODM only supports materialized path.

ORM Only Extensions

• IpTraceable: Sets the IP address instead of a timestamp.
• SoftDeleteable: Allows for implicit record removal.
• Sortable: Makes any entity or document sortable.
• Uploadable: Handles file uploads in entity fields.

MongoDB ODM Only Extensions

• References: Supports linking Entities in Documents and vice versa.
• ReferenceIntegrity: Constrains ODM MongoDB Document references.

All extensions support Attribute, XML, and Annotation (deprecated) mapping.

To use the Blameable behavior, register the BlameableListener as an event subscriber to your Doctrine Object Manager (either an ORM Entity Manager or a MongoDB ODM Document Manager). After registration, you must provide the user information that should be recorded. You can do this by implementing a Gedmo\\Tool\\ActorProviderInterface and passing it to the listener via setActorProvider(), or by manually calling setUserValue() with the resolved user (which can be an object or a string).

Note: If an actor provider is configured, any values manually set via setUserValue() will be ignored.

use Gedmo\Blameable\BlameableListener;

$listener = new BlameableListener();

// $om is an instance of the ORM's entity manager or the MongoDB ODM's document manager
$om->getEventManager()->addEventSubscriber($listener);

// Option 1: Using an Actor Provider
$listener->setActorProvider($provider);

// Option 2: Setting user value manually
$listener->setUserValue($user);

To process files that are not part of a standard $_FILES upload (such as files from a URL or existing local files), implement the Gedmo\Uploadable\FileInfo\FileInfoInterface.

Crucially, ensure isUploadedFile() returns false. This instructs the extension to use the copy function instead of move_uploaded_file to move the file to its destination.

Alternatively, you can extend FileInfoArray and populate its $fileInfo array with keys: tmp_name, name, size, type, and error.

use Gedmo\
Uploadable\\FileInfo\\FileInfoInterface;

class CustomFileInfo implements FileInfoInterface
{
    protected $path;
    protected $name;
    protected $size;
    protected $type;
    protected $filename;
    protected $error = 0;

    public function __construct($path)
    {
        $this->path = $path;
        // Process the file and fill properties...
    }

    public function getTmpName() { return $this->path; }
    public function getName() { return $this->name; }
    public function getSize() { return $this->size; }
    public function getType() { return $this->type; }
    public function getError() { return $this->error; }

    public function isUploadedFile()
    {
        // Return false to use 'copy' instead of 'move_uploaded_file'
        return false;
    }
}

// Usage:
$listener->setDefaultPath('/my/path');
$file = new File();
$listener->addEntityFileInfo($file, new CustomFileInfo('/path/to/file.txt'));
$em->persist($file);
$em->flush();

Beyond general create/update actions, you can use the change action to log an IP address only when specific conditions are met:

Single Field Changed to Specific Value

Use on: 'change' with field and value parameters to trigger logging when a specific field reaches a specific value. You can use dot notation to watch related objects (e.g., category.archived).

One of Many Fields Changed

Pass an array of field names to the field parameter to trigger logging if any of the specified fields (or related paths via dot notation) are modified.

#[ORM\Entity]
class Article
{
    // Track IP when 'published' becomes 'true'
    #[ORM\Column(type: Types::STRING, nullable: true)]
    #[Gedmo\IpTraceable(on: 'change', field: 'published', value: true)]
    public ?string $publishedFromIp = null;

    // Track IP when any of these fields change
    #[ORM\Column(type: Types::STRING, nullable: true)]
    #[Gedmo\IpTraceable(on: 'change', field: ['metaDescription', 'metaKeywords', 'category.metaDescription'])]
    public ?string $seoMetadataChangedFromIp = null;
}

Extensions that track user values (such as Blameable or Loggable) require an implementation of Gedmo\Tool\ActorProviderInterface to resolve the current user. Since the library does not provide a default implementation, you must create a class in your application that implements this interface. The getActor() method should return the user object, a string identifier, or null if no user is present.

namespace App\ Utils;

use Gedmo\Tool\ActorProviderInterface;
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;

final class SymfonyActorProvider implements ActorProviderInterface
{
    private TokenStorageInterface $tokenStorage;

    public function __construct(TokenStorageInterface $tokenStorage)
    {
        $this->tokenStorage = $tokenStorage;
    }

    /**
     * @return object|string|null
     */
    public function getActor()
    {
        $token = $this->tokenStorage->getToken();

        return $token ? $token->getUser() : null;
    }
}