[timestampable] add example traits

doc/timestampable.md

@@ -16,6 +16,10 @@ Features:
 [blog_reference]: http://gediminasm.org/article/timestampable-behavior-extension-for-doctrine-2 "Timestampable extension for Doctrine 2 helps automate update of dates"
 [blog_test]: http://gediminasm.org/test "Test extensions on this blog"
 
+Update **2012-03-10**
+
+- Add [Timestampable traits](#traits)
+
 Update **2011-04-04**
  
 - Made single listener, one instance can be used for any object manager
@@ -42,6 +46,7 @@ Content:
 - [Yaml](#yaml-mapping) mapping example
 - [Xml](#xml-mapping) mapping example
 - Advanced usage [examples](#advanced-examples)
+- Using [Traits](#traits)
 
 <a name="including-extension"></a>
 
@@ -564,3 +569,54 @@ Or if the user does not have a timezone, we could expand that to use a system/ap
 [doctrine_custom_datetime_type]: http://www.doctrine-project.org/docs/orm/2.0/en/cookbook/working-with-datetime.html#handling-different-timezones-with-the-datetime-type "Handling different Timezones with the DateTime Type"
 
 This example is based off [Handling different Timezones with the DateTime Type][doctrine_custom_datetime_type] - however that example may be outdated because it contains some obvioulsy invalid PHP from the TimeZone class.
+
+<a name="traits"></a>
+
+## Traits
+
+You can use timestampable traits for quick **createdAt** **updatedAt** timestamp definitions
+when using annotation mapping.
+
+**Note:** this feature is only available since php **5.4.0**. And you are not required
+to use the Traits provided by extensions.
+
+``` php
+<?php
+namespace Timestampable\Fixture;
+
+use Gedmo\Timestampable\Traits\TimestampableEntity;
+use Gedmo\Mapping\Annotation as Gedmo;
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * @ORM\Entity
+ */
+class UsingTrait
+{
+    /**
+     * Hook timestampable behavior
+     * updates createdAt, updatedAt fields
+     */
+    use TimestampableEntity;
+
+    /**
+     * @ORM\Id
+     * @ORM\GeneratedValue
+     * @ORM\Column(type="integer")
+     */
+    private $id;
+
+    /**
+     * @ORM\Column(length=128)
+     */
+    private $title;
+}
+```
+
+**Note:** you must import **Gedmo\Mapping\Annotation as Gedmo** and **Doctrine\ORM\Mapping as ORM**
+annotations. If you use mongodb ODM import **Doctrine\ODM\MongoDB\Mapping\Annotations as ODM** and
+**TimestampableDocument** instead.
+
+Traits are very simple and if you use different field names I recomment to simply create your
+own ones based per project. These ones are standing as an example.
+

lib/Gedmo/Timestampable/Traits/TimestampableDocument.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace Gedmo\Timestampable\Traits;
+
+/**
+ * Timestampable Trait, usable with PHP >= 5.4
+ *
+ * @author Gediminas Morkevicius <gediminas.morkevicius@gmail.com>
+ * @package Gedmo.Timestampable.Traits
+ * @subpackage TimestampableDocument
+ * @link http://www.gediminasm.org
+ * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
+ */
+trait TimestampableDocument
+{
+    /**
+     * @Gedmo\Timestampable(on="create")
+     * @ODM\Date
+     */
+    private $createdAt;
+
+    /**
+     * @Gedmo\Timestampable(on="update")
+     * @ODM\Date
+     */
+    private $updatedAt;
+
+    /**
+     * Sets createdAt.
+     *
+     * @param Datetime $createdAt
+     */
+    public function setCreatedAt(\DateTime $createdAt)
+    {
+        $this->createdAt = $createdAt;
+    }
+
+    /**
+     * Returns createdAt.
+     *
+     * @return DateTime
+     */
+    public function getCreatedAt()
+    {
+        return $this->createdAt;
+    }
+
+    /**
+     * Sets updatedAt.
+     *
+     * @param DateTime $updatedAt
+     */
+    public function setUpdatedAt(\DateTime $updatedAt)
+    {
+        $this->updatedAt = $updatedAt;
+    }
+
+    /**
+     * Returns updatedAt.
+     *
+     * @return Datetime
+     */
+    public function getUpdatedAt()
+    {
+        return $this->updatedAt;
+    }
+}

lib/Gedmo/Timestampable/Traits/TimestampableEntity.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace Gedmo\Timestampable\Traits;
+
+/**
+ * Timestampable Trait, usable with PHP >= 5.4
+ *
+ * @author Gediminas Morkevicius <gediminas.morkevicius@gmail.com>
+ * @package Gedmo.Timestampable.Traits
+ * @subpackage TimestampableEntity
+ * @link http://www.gediminasm.org
+ * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
+ */
+trait TimestampableEntity
+{
+    /**
+     * @Gedmo\Timestampable(on="create")
+     * @ORM\Column(type="datetime")
+     */
+    private $createdAt;
+
+    /**
+     * @Gedmo\Timestampable(on="update")
+     * @ORM\Column(type="datetime")
+     */
+    private $updatedAt;
+
+    /**
+     * Sets createdAt.
+     *
+     * @param DateTime $createdAt
+     */
+    public function setCreatedAt(\DateTime $createdAt)
+    {
+        $this->createdAt = $createdAt;
+    }
+
+    /**
+     * Returns createdAt.
+     *
+     * @return DateTime
+     */
+    public function getCreatedAt()
+    {
+        return $this->createdAt;
+    }
+
+    /**
+     * Sets updatedAt.
+     *
+     * @param DateTime $updatedAt
+     */
+    public function setUpdatedAt(\DateTime $updatedAt)
+    {
+        $this->updatedAt = $updatedAt;
+    }
+
+    /**
+     * Returns updatedAt.
+     *
+     * @return DateTime
+     */
+    public function getUpdatedAt()
+    {
+        return $this->updatedAt;
+    }
+}

tests/Gedmo/Timestampable/Fixture/UsingTrait.php

@@ -0,0 +1,45 @@
+<?php
+namespace Timestampable\Fixture;
+
+use Gedmo\Timestampable\Traits\TimestampableEntity;
+use Gedmo\Mapping\Annotation as Gedmo;
+use Doctrine\ORM\Mapping as ORM;
+
+/**
+ * @ORM\Entity
+ */
+class UsingTrait
+{
+    /**
+     * Hook timestampable behavior
+     * updates createdAt, updatedAt fields
+     */
+    use TimestampableEntity;
+
+    /**
+     * @ORM\Id
+     * @ORM\GeneratedValue
+     * @ORM\Column(type="integer")
+     */
+    private $id;
+
+    /**
+     * @ORM\Column(length=128)
+     */
+    private $title;
+
+    public function getId()
+    {
+        return $this->id;
+    }
+
+    public function setTitle($title)
+    {
+        $this->title = $title;
+    }
+
+    public function getTitle()
+    {
+        return $this->title;
+    }
+}

tests/Gedmo/Timestampable/TraitUsageTest.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace Gedmo\Timestampable;
+
+use Doctrine\Common\EventManager;
+use Tool\BaseTestCaseORM;
+use Timestampable\Fixture\UsingTrait;
+
+/**
+ * These are tests for Timestampable behavior
+ *
+ * @author Gediminas Morkevicius <gediminas.morkevicius@gmail.com>
+ * @package Gedmo.Timestampable
+ * @link http://www.gediminasm.org
+ * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
+ */
+class TraitUsageTest extends BaseTestCaseORM
+{
+    const TARGET = "Timestampable\\Fixture\\UsingTrait";
+
+    protected function setUp()
+    {
+        parent::setUp();
+
+        $evm = new EventManager;
+        $evm->addEventSubscriber(new TimestampableListener);
+
+        $this->getMockSqliteEntityManager($evm);
+    }
+
+    /**
+     * @test
+     */
+    function shouldTimestampUsingTrait()
+    {
+        $sport = new UsingTrait;
+        $sport->setTitle('Sport');
+
+        $this->em->persist($sport);
+        $this->em->flush();
+
+        $this->assertNotNull($sport->getCreatedAt());
+        $this->assertNotNull($sport->getUpdatedAt());
+    }
+
+    protected function getUsedEntityFixtures()
+    {
+        return array(
+            self::TARGET
+        );
+    }
+}