DoctrineExtensions

Doctrine2 behavioral extensions, Translatable, Sluggable, Tree-NestedSet, Timestampable, Loggable, Sortable

4,027

1,264

4,027

View on GitHub

Top Related Projects

StofDoctrineExtensionsBundle

1,886

Integration bundle for DoctrineExtensions by l3pp4rd in Symfony

Quick Overview

The DoctrineExtensions project is a set of Doctrine 2 behavioral extensions that add new functionality to the Doctrine ORM. It provides a variety of extensions, such as Sluggable, Translatable, Timestampable, and more, which can be easily integrated into Doctrine-based applications.

Pros

Extensive Functionality: The project offers a wide range of extensions, covering various common use cases in web development, such as handling slugs, translations, and timestamps.
Easy Integration: The extensions are designed to be easily integrated into Doctrine-based applications, reducing development time and effort.
Active Community: The project has an active community of contributors, ensuring ongoing maintenance and support.
Flexibility: The extensions can be selectively enabled or disabled, allowing developers to choose the functionality they need for their specific use case.

Cons

Potential Complexity: The project's extensive functionality may introduce additional complexity, especially for developers new to Doctrine or the extensions.
Dependency on Doctrine: The extensions are tightly coupled with the Doctrine ORM, which may limit their usefulness for projects not using Doctrine.
Potential Performance Impact: Depending on the extensions used, there may be a slight performance impact on the application.
Versioning Challenges: As the project evolves, there may be compatibility issues when upgrading to newer versions of the extensions or Doctrine.

Code Examples

Sluggable Extension

The Sluggable extension automatically generates a unique slug for an entity based on a specified field.

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

/**
 * @ORM\Entity
 * @Gedmo\Sluggable(fields={"title"})
 */
class Article
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string")
     * @Gedmo\Slug
     */
    private $slug;

    /**
     * @ORM\Column(type="string")
     */
    private $title;
}

Translatable Extension

The Translatable extension allows you to store and retrieve translations for an entity's fields.

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

/**
 * @ORM\Entity
 * @Gedmo\Translatable
 */
class Product
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string")
     * @Gedmo\Translatable
     */
    private $name;

    /**
     * @ORM\Column(type="text")
     * @Gedmo\Translatable
     */
    private $description;
}

Getting Started

To get started with the DoctrineExtensions project, follow these steps:

Install the project using Composer:

composer require doctrine-extensions/doctrine-extensions

Enable the desired extensions in your Doctrine configuration. For example, to enable the Sluggable and Translatable extensions:

use Doctrine\ORM\EntityManager;
use Doctrine\ORM\Configuration;
use Gedmo\Sluggable\SluggableListener;
use Gedmo\Translatable\TranslatableListener;

$config = new Configuration();
$em = EntityManager::create($connectionOptions, $config);

$sluggableListener = new SluggableListener();
$translatableListener = new TranslatableListener();

$em->getEventManager()->addEventSubscriber($sluggableListener);
$em->getEventManager()->addEventSubscriber($translatableListener);

Annotate your entities with the appropriate extensions, as shown in the code examples above.
Use the extensions in your application, leveraging the new functionality provided by the DoctrineExtensions project.

Competitor Comparisons

DoctrineExtensions

2,026

A set of Doctrine 2 extensions

Pros of DoctrineExtensions (beberlei)

Lightweight and focused on SQL function support
Easy to integrate with existing Doctrine projects
Regularly updated and maintained

Cons of DoctrineExtensions (beberlei)

Limited to SQL functions and doesn't provide behavioral extensions
Less comprehensive documentation compared to DoctrineExtensions (doctrine-extensions)
Smaller community and fewer contributors

Code Comparison

DoctrineExtensions (beberlei):

$qb->select('RAND() as rand')
   ->from('Entity')
   ->orderBy('rand');

DoctrineExtensions (doctrine-extensions):

$qb->select('e')
   ->from('Entity', 'e')
   ->orderBy('RAND()');

Both examples achieve similar results, but DoctrineExtensions (beberlei) focuses on providing SQL function support, while DoctrineExtensions (doctrine-extensions) offers a wider range of extensions, including behavioral ones.

DoctrineExtensions (beberlei) is ideal for projects that primarily need SQL function support, while DoctrineExtensions (doctrine-extensions) is better suited for applications requiring more extensive Doctrine enhancements, such as Timestampable, Sluggable, or Tree behaviors.

StofDoctrineExtensionsBundle

1,886

Integration bundle for DoctrineExtensions by l3pp4rd in Symfony

Pros of StofDoctrineExtensionsBundle

Seamless integration with Symfony framework
Simplified configuration through Symfony's bundle system
Automatic listener registration for Doctrine events

Cons of StofDoctrineExtensionsBundle

Limited to Symfony projects, less flexible for other PHP applications
Adds an extra layer of abstraction, potentially complicating troubleshooting
May have a slight performance overhead due to the bundle integration

Code Comparison

StofDoctrineExtensionsBundle configuration:

stof_doctrine_extensions:
    orm:
        default:
            timestampable: true
            sluggable: true

DoctrineExtensions configuration:

$evm = new \Doctrine\Common\EventManager();
$timestampableListener = new \Gedmo\Timestampable\TimestampableListener();
$sluggableListener = new \Gedmo\Sluggable\SluggableListener();
$evm->addEventSubscriber($timestampableListener);
$evm->addEventSubscriber($sluggableListener);

StofDoctrineExtensionsBundle is tailored for Symfony projects, offering easier configuration and integration. DoctrineExtensions provides more flexibility for various PHP applications but requires manual setup. The choice depends on your project's framework and specific needs.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Doctrine Behavioral Extensions

This package contains extensions for Doctrine ORM and MongoDB ODM that offer new functionality or tools to use Doctrine more efficiently. These behaviors can be easily attached to the event system of Doctrine and handle the records being flushed in a behavioral way.

Doctrine Extensions 3.0 Released :tada:

3.0 focuses on refreshing this package for today's PHP. This includes:

Bumping minimum version requirements of PHP, Doctrine, and other dependencies
Implementing support for the latest Doctrine MongoDB & Common packages
Updating the test suite, add code and style standards, and other needed build tools
Cleaning up documentation, code, comments, etc.

Read the Upgrade Doc for more info.

Installation

composer require gedmo/doctrine-extensions

Upgrading

From 2.4.x to 3.0

Extensions

ORM & MongoDB ODM

Blameable - updates string or reference fields on create, update and even property change with a string or object (e.g. user).
Loggable - helps tracking changes and history of objects, also supports version management.
Sluggable - urlizes your specified fields into single unique slug
Timestampable - updates date fields on create, update and even property change.
Translatable - gives you a very handy solution for translating records into different languages. Easy to setup, easier to use.
Tree - automates the tree handling process and adds some tree-specific functions on repository. (closure, nested set or materialized path) (MongoDB ODM only supports materialized path)

ORM Only

IpTraceable - inherited from Timestampable, sets IP address instead of timestamp
SoftDeleteable - allows to implicitly remove records
Sortable - makes any document or entity sortable
Uploadable - provides file upload handling in entity fields

MongoDB ODM Only

References - supports linking Entities in Documents and vice versa
ReferenceIntegrity - constrains ODM MongoDB Document references

All extensions support Attribute, XML and Annotation (deprecated) mapping. Additional mapping drivers can be easily implemented using Mapping extension to handle the additional metadata mapping.

Version Compatibility

DBAL: ^3.2
ORM: ^2.14 or ^3.0
MongoDB ODM: ^2.3

If you are setting up the Entity Manager without a framework, see the example to prevent issues like #1310

XML Mapping

XML mapping needs to be in a different namespace, the declared namespace for Doctrine extensions is http://gediminasm.org/schemas/orm/doctrine-extensions-mapping So root node now looks like this:

<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
                 xmlns:gedmo="http://gediminasm.org/schemas/orm/doctrine-extensions-mapping">
...
</doctrine-mapping>

XML mapping xsd schemas are also versioned and can be used by version suffix:

Latest version - http://gediminasm.org/schemas/orm/doctrine-extensions-mapping
2.2.x version - http://gediminasm.org/schemas/orm/doctrine-extensions-mapping-2-2
2.1.x version - http://gediminasm.org/schemas/orm/doctrine-extensions-mapping-2-1

Running Tests

To set up and run the tests, follow these steps:

Install Docker and ensure you have docker compose
From the project root, run docker compose up -d to start containers in daemon mode
Enter the container via docker compose exec php bash (you are now in the root directory: /var/www)
Install Composer dependencies via composer install
Run the tests: vendor/bin/phpunit

Running the Example

To set up and run example, follow these steps:

go to the root directory of extensions
download composer
install dev libraries: composer install
edit example/em.php and configure your database on top of the file
run: php example/bin/console or php example/bin/console for console commands
run: php example/bin/console orm:schema-tool:create to create the schema
run: php example/bin/console app:print-category-translation-tree to run the example to print the category translation tree

Contributors

Thanks to everyone participating in the development of these great Doctrine extensions!

And especially ones who create and maintain new extensions:

Lukas Botsch lbotsch
Gustavo Adrian comfortablynumb
Boussekeyt Jules gordonslondon
Kudryashov Konstantin everzet
David Buchmann dbu

Top Related Projects

DoctrineExtensions

2,026

A set of Doctrine 2 extensions

StofDoctrineExtensionsBundle

1,886

Integration bundle for DoctrineExtensions by l3pp4rd in Symfony

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot