support custom fields for timesheets, customers, projects and activities (#871)

src/Entity/Activity.php

@@ -18,7 +18,7 @@ use Symfony\Component\Validator\Constraints as Assert;
  * @ORM\Table(name="kimai2_activities")
  * @ORM\Entity(repositoryClass="App\Repository\ActivityRepository")
  */
-class Activity
+class Activity implements EntityWithMetaFields
 {
     /**
      * @var int
@@ -73,9 +73,17 @@ class Activity
     use ColorTrait;
     use BudgetTrait;
 
+    /**
+     * @var ActivityMeta[]|Collection
+     *
+     * @ORM\OneToMany(targetEntity="App\Entity\ActivityMeta", mappedBy="activity", cascade={"persist"})
+     */
+    private $meta;
+
     public function __construct()
     {
         $this->timesheets = new ArrayCollection();
+        $this->meta = new ArrayCollection();
     }
 
     public function getId(): ?int
@@ -139,6 +147,55 @@ class Activity
         return $this->visible;
     }
 
+    /**
+     * @internal only here for symfony forms
+     * @return Collection|MetaTableTypeInterface[]
+     */
+    public function getMetaFields(): Collection
+    {
+        return $this->meta;
+    }
+
+    /**
+     * @return MetaTableTypeInterface[]
+     */
+    public function getVisibleMetaFields(): array
+    {
+        $all = [];
+        foreach ($this->meta as $meta) {
+            if ($meta->isVisible()) {
+                $all[] = $meta;
+            }
+        }
+
+        return $all;
+    }
+
+    public function getMetaField(string $name): ?MetaTableTypeInterface
+    {
+        foreach ($this->meta as $field) {
+            if ($field->getName() === $name) {
+                return $field;
+            }
+        }
+
+        return null;
+    }
+
+    public function setMetaField(MetaTableTypeInterface $meta): EntityWithMetaFields
+    {
+        if (null === ($current = $this->getMetaField($meta->getName()))) {
+            $meta->setEntity($this);
+            $this->meta->add($meta);
+
+            return $this;
+        }
+
+        $current->merge($meta);
+
+        return $this;
+    }
+
     /**
      * @return string
      */

src/Entity/ActivityMeta.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * @ORM\Entity()
+ * @ORM\Table(name="kimai2_activities_meta",
+ *      uniqueConstraints={
+ *          @ORM\UniqueConstraint(columns={"activity_id", "name"})
+ *      }
+ * )
+ */
+class ActivityMeta implements MetaTableTypeInterface
+{
+    use MetaTableTypeTrait;
+
+    /**
+     * @var Activity
+     *
+     * @ORM\ManyToOne(targetEntity="App\Entity\Activity", inversedBy="meta")
+     * @ORM\JoinColumn(onDelete="CASCADE")
+     * @Assert\NotNull()
+     */
+    private $activity;
+
+    public function setEntity(EntityWithMetaFields $entity): MetaTableTypeInterface
+    {
+        if (!($entity instanceof Activity)) {
+            throw new \InvalidArgumentException(
+                sprintf('Expected instanceof Activity, received "%s"', get_class($entity))
+            );
+        }
+        $this->activity = $entity;
+
+        return $this;
+    }
+
+    public function getEntity(): ?EntityWithMetaFields
+    {
+        return $this->activity;
+    }
+}

src/Entity/Customer.php

@@ -18,7 +18,7 @@ use Symfony\Component\Validator\Constraints as Assert;
  * @ORM\Table(name="kimai2_customers")
  * @ORM\Entity(repositoryClass="App\Repository\CustomerRepository")
  */
-class Customer
+class Customer implements EntityWithMetaFields
 {
     public const DEFAULT_CURRENCY = 'EUR';
 
@@ -154,9 +154,17 @@ class Customer
     use ColorTrait;
     use BudgetTrait;
 
+    /**
+     * @var CustomerMeta[]|Collection
+     *
+     * @ORM\OneToMany(targetEntity="App\Entity\CustomerMeta", mappedBy="customer", cascade={"persist"})
+     */
+    private $meta;
+
     public function __construct()
     {
         $this->projects = new ArrayCollection();
+        $this->meta = new ArrayCollection();
     }
 
     public function getId(): ?int
@@ -352,6 +360,55 @@ class Customer
         return $this->projects;
     }
 
+    /**
+     * @internal only here for symfony forms
+     * @return Collection|MetaTableTypeInterface[]
+     */
+    public function getMetaFields(): Collection
+    {
+        return $this->meta;
+    }
+
+    /**
+     * @return MetaTableTypeInterface[]
+     */
+    public function getVisibleMetaFields(): array
+    {
+        $all = [];
+        foreach ($this->meta as $meta) {
+            if ($meta->isVisible()) {
+                $all[] = $meta;
+            }
+        }
+
+        return $all;
+    }
+
+    public function getMetaField(string $name): ?MetaTableTypeInterface
+    {
+        foreach ($this->meta as $field) {
+            if ($field->getName() === $name) {
+                return $field;
+            }
+        }
+
+        return null;
+    }
+
+    public function setMetaField(MetaTableTypeInterface $meta): EntityWithMetaFields
+    {
+        if (null === ($current = $this->getMetaField($meta->getName()))) {
+            $meta->setEntity($this);
+            $this->meta->add($meta);
+
+            return $this;
+        }
+
+        $current->merge($meta);
+
+        return $this;
+    }
+
     /**
      * @return string
      */

src/Entity/CustomerMeta.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * @ORM\Entity()
+ * @ORM\Table(name="kimai2_customers_meta",
+ *      uniqueConstraints={
+ *          @ORM\UniqueConstraint(columns={"customer_id", "name"})
+ *      }
+ * )
+ */
+class CustomerMeta implements MetaTableTypeInterface
+{
+    use MetaTableTypeTrait;
+
+    /**
+     * @var Customer
+     *
+     * @ORM\ManyToOne(targetEntity="App\Entity\Customer", inversedBy="meta")
+     * @ORM\JoinColumn(onDelete="CASCADE")
+     * @Assert\NotNull()
+     */
+    private $customer;
+
+    public function setEntity(EntityWithMetaFields $entity): MetaTableTypeInterface
+    {
+        if (!($entity instanceof Customer)) {
+            throw new \InvalidArgumentException(
+                sprintf('Expected instanceof Customer, received "%s"', get_class($entity))
+            );
+        }
+        $this->customer = $entity;
+
+        return $this;
+    }
+
+    public function getEntity(): ?EntityWithMetaFields
+    {
+        return $this->customer;
+    }
+}

src/Entity/EntityWithMetaFields.php

@@ -0,0 +1,25 @@
+<?php
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Entity;
+
+use Doctrine\Common\Collections\Collection;
+
+interface EntityWithMetaFields
+{
+    /**
+     * @internal only here for symfony forms
+     * @return Collection|MetaTableTypeInterface[]
+     */
+    public function getMetaFields(): Collection;
+
+    public function getMetaField(string $name): ?MetaTableTypeInterface;
+
+    public function setMetaField(MetaTableTypeInterface $meta): EntityWithMetaFields;
+}

src/Entity/MetaTableTypeInterface.php

@@ -0,0 +1,136 @@
+<?php
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Entity;
+
+use Symfony\Component\Validator\Constraint;
+
+interface MetaTableTypeInterface
+{
+    /**
+     * Returns the name of this entry.
+     *
+     * @return string|null
+     */
+    public function getName(): ?string;
+
+    /**
+     * Sets the name of this entry.
+     *
+     * @param string $name
+     * @return MetaTableTypeInterface
+     */
+    public function setName(string $name): MetaTableTypeInterface;
+
+    /**
+     * @return mixed|null
+     */
+    public function getValue();
+
+    /**
+     * Value will not be serialized before its stored, so it should be a primitive type.
+     *
+     * @param mixed|null $value
+     * @return MetaTableTypeInterface
+     */
+    public function setValue($value): MetaTableTypeInterface;
+
+    /**
+     * Get the linked entity.
+     *
+     * @return EntityWithMetaFields|null
+     */
+    public function getEntity(): ?EntityWithMetaFields;
+
+    /**
+     * Set the linked entity of this entry.
+     *
+     * @param EntityWithMetaFields $entity
+     * @return MetaTableTypeInterface
+     */
+    public function setEntity(EntityWithMetaFields $entity): MetaTableTypeInterface;
+
+    /**
+     * This will merge the current object with the values from the given $meta instance.
+     * It should NOT update the name or value, but only the form settings.
+     *
+     * @param MetaTableTypeInterface $meta
+     * @return MetaTableTypeInterface
+     */
+    public function merge(MetaTableTypeInterface $meta): MetaTableTypeInterface;
+
+    /**
+     * Whether this field can be displayed in "public" places like API results or export.
+     *
+     * @param bool $include
+     * @return MetaTableTypeInterface
+     */
+    public function setIsVisible(bool $include): MetaTableTypeInterface;
+
+    /**
+     * Whether this field can be displayed in "public" places like API results or export.
+     *
+     * @return bool
+     */
+    public function isVisible(): bool;
+
+    /**
+     * Whether this field is required to be filled out in the form.
+     *
+     * @param bool $isRequired
+     * @return MetaTableTypeInterface
+     */
+    public function setIsRequired(bool $isRequired): MetaTableTypeInterface;
+
+    /**
+     * Whether the form field is required.
+     *
+     * @return bool
+     */
+    public function isRequired(): bool;
+
+    /**
+     * The form type for this field.
+     * If this method returns null, it will not be shown on the form.
+     *
+     * @return string|null
+     */
+    public function getType(): ?string;
+
+    /**
+     * Sets the form type.
+     *
+     * @param string $type
+     * @return MetaTableTypeInterface
+     */
+    public function setType(string $type): MetaTableTypeInterface;
+
+    /**
+     * Get all constraints that should be attached to the form type.
+     *
+     * @return Constraint[]
+     */
+    public function getConstraints(): array;
+
+    /**
+     * Adds a constraint to the form type.
+     *
+     * @param Constraint $constraint
+     * @return MetaTableTypeInterface
+     */
+    public function addConstraint(Constraint $constraint): MetaTableTypeInterface;
+
+    /**
+     * Sets all constraints for the form type, overwriting all previously attached.
+     *
+     * @param Constraint[] $constraints
+     * @return MetaTableTypeInterface
+     */
+    public function setConstraints(array $constraints): MetaTableTypeInterface;
+}

src/Entity/MetaTableTypeTrait.php

@@ -0,0 +1,179 @@
+<?php
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
+use Symfony\Component\Form\Extension\Core\Type\IntegerType;
+use Symfony\Component\Validator\Constraint;
+use Symfony\Component\Validator\Constraints as Assert;
+
+trait MetaTableTypeTrait
+{
+    /**
+     * @var int
+     *
+     * @ORM\Id
+     * @ORM\GeneratedValue
+     * @ORM\Column(name="id", type="integer")
+     */
+    private $id;
+
+    /**
+     * @var string
+     *
+     * @ORM\Column(name="name", type="string", length=50, nullable=false)
+     * @Assert\Length(min=2, max=50)
+     */
+    private $name;
+
+    /**
+     * @var string
+     *
+     * @ORM\Column(name="value", type="string", length=255, nullable=true)
+     */
+    private $value;
+
+    /**
+     * @var bool
+     *
+     * @ORM\Column(name="visible", type="boolean", nullable=false)
+     * @Assert\NotNull()
+     */
+    private $visible = false;
+
+    /**
+     * @var string
+     */
+    private $type;
+
+    /**
+     * @var bool
+     */
+    private $required = false;
+
+    /**
+     * @var Constraint[]
+     */
+    private $constraints = [];
+
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    public function setName(string $name): MetaTableTypeInterface
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    /**
+     * @return mixed|null
+     */
+    public function getValue()
+    {
+        switch ($this->type) {
+            case CheckboxType::class:
+                return (bool) $this->value;
+            case IntegerType::class:
+                return (int) $this->value;
+        }
+
+        return $this->value;
+    }
+
+    /**
+     * Value will not be serialized before its stored, so it should be a primitive type.
+     *
+     * @param mixed $value
+     * @return MetaTableTypeInterface
+     */
+    public function setValue($value): MetaTableTypeInterface
+    {
+        $this->value = $value;
+
+        return $this;
+    }
+
+    public function setConstraints(array $constraints): MetaTableTypeInterface
+    {
+        $this->constraints = [];
+
+        foreach ($constraints as $constraint) {
+            $this->addConstraint($constraint);
+        }
+
+        return $this;
+    }
+
+    public function getType(): ?string
+    {
+        return $this->type;
+    }
+
+    public function setType(string $type): MetaTableTypeInterface
+    {
+        $this->type = $type;
+
+        return $this;
+    }
+
+    public function addConstraint(Constraint $constraint): MetaTableTypeInterface
+    {
+        $this->constraints[] = $constraint;
+
+        return $this;
+    }
+
+    /**
+     * @return Constraint[]
+     */
+    public function getConstraints(): array
+    {
+        return $this->constraints;
+    }
+
+    public function isRequired(): bool
+    {
+        return $this->required;
+    }
+
+    public function setIsRequired(bool $isRequired): MetaTableTypeInterface
+    {
+        $this->required = $isRequired;
+
+        return $this;
+    }
+
+    public function isVisible(): bool
+    {
+        return $this->visible;
+    }
+
+    public function setIsVisible(bool $visible): MetaTableTypeInterface
+    {
+        $this->visible = $visible;
+
+        return $this;
+    }
+
+    public function merge(MetaTableTypeInterface $meta): MetaTableTypeInterface
+    {
+        $this
+            ->setType($meta->getType())
+            ->setConstraints($meta->getConstraints())
+            ->setIsRequired($meta->isRequired())
+            ->setIsVisible($meta->isVisible());
+
+        return $this;
+    }
+}

src/Entity/Project.php

@@ -18,7 +18,7 @@ use Symfony\Component\Validator\Constraints as Assert;
  * @ORM\Table(name="kimai2_projects")
  * @ORM\Entity(repositoryClass="App\Repository\ProjectRepository")
  */
-class Project
+class Project implements EntityWithMetaFields
 {
     /**
      * @var int
@@ -89,10 +89,18 @@ class Project
      */
     private $timesheets;
 
+    /**
+     * @var ProjectMeta[]|Collection
+     *
+     * @ORM\OneToMany(targetEntity="App\Entity\ProjectMeta", mappedBy="project", cascade={"persist"})
+     */
+    private $meta;
+
     public function __construct()
     {
         $this->activities = new ArrayCollection();
         $this->timesheets = new ArrayCollection();
+        $this->meta = new ArrayCollection();
     }
 
     public function getId(): ?int
@@ -190,6 +198,55 @@ class Project
         return $this;
     }
 
+    /**
+     * @internal only here for symfony forms
+     * @return Collection|MetaTableTypeInterface[]
+     */
+    public function getMetaFields(): Collection
+    {
+        return $this->meta;
+    }
+
+    /**
+     * @return MetaTableTypeInterface[]
+     */
+    public function getVisibleMetaFields(): array
+    {
+        $all = [];
+        foreach ($this->meta as $meta) {
+            if ($meta->isVisible()) {
+                $all[] = $meta;
+            }
+        }
+
+        return $all;
+    }
+
+    public function getMetaField(string $name): ?MetaTableTypeInterface
+    {
+        foreach ($this->meta as $field) {
+            if ($field->getName() === $name) {
+                return $field;
+            }
+        }
+
+        return null;
+    }
+
+    public function setMetaField(MetaTableTypeInterface $meta): EntityWithMetaFields
+    {
+        if (null === ($current = $this->getMetaField($meta->getName()))) {
+            $meta->setEntity($this);
+            $this->meta->add($meta);
+
+            return $this;
+        }
+
+        $current->merge($meta);
+
+        return $this;
+    }
+
     /**
      * @return string
      */

src/Entity/ProjectMeta.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * @ORM\Entity()
+ * @ORM\Table(name="kimai2_projects_meta",
+ *      uniqueConstraints={
+ *          @ORM\UniqueConstraint(columns={"project_id", "name"})
+ *      }
+ * )
+ */
+class ProjectMeta implements MetaTableTypeInterface
+{
+    use MetaTableTypeTrait;
+
+    /**
+     * @var Project
+     *
+     * @ORM\ManyToOne(targetEntity="App\Entity\Project", inversedBy="meta")
+     * @ORM\JoinColumn(onDelete="CASCADE")
+     * @Assert\NotNull()
+     */
+    private $project;
+
+    public function setEntity(EntityWithMetaFields $entity): MetaTableTypeInterface
+    {
+        if (!($entity instanceof Project)) {
+            throw new \InvalidArgumentException(
+                sprintf('Expected instanceof Project, received "%s"', get_class($entity))
+            );
+        }
+        $this->project = $entity;
+
+        return $this;
+    }
+
+    public function getEntity(): ?EntityWithMetaFields
+    {
+        return $this->project;
+    }
+}

src/Entity/Timesheet.php

@@ -25,7 +25,7 @@ use Symfony\Component\Validator\Constraints as Assert;
  * @ORM\HasLifecycleCallbacks()
  * @App\Validator\Constraints\Timesheet
  */
-class Timesheet
+class Timesheet implements EntityWithMetaFields
 {
     /**
      * @var int
@@ -138,7 +138,14 @@ class Timesheet
      *  }
      * )
      */
-    protected $tags;
+    private $tags;
+
+    /**
+     * @var TimesheetMeta[]|Collection
+     *
+     * @ORM\OneToMany(targetEntity="App\Entity\TimesheetMeta", mappedBy="timesheet", cascade={"persist"})
+     */
+    private $meta;
 
     /**
      * Default constructor, initializes collections
@@ -146,6 +153,7 @@ class Timesheet
     public function __construct()
     {
         $this->tags = new ArrayCollection();
+        $this->meta = new ArrayCollection();
     }
 
     /**
@@ -405,6 +413,7 @@ class Timesheet
     /**
      * BE WARNED: this method should NOT be used programmatically, there is very likely no reason for it!
      *
+     * @internal
      * @deprecated since it was introduced, only meant for the initial migration. Will be removed with 1.0.
      * @param string $timezone
      * @return Timesheet
@@ -415,4 +424,53 @@ class Timesheet
 
         return $this;
     }
+
+    /**
+     * @internal only here for symfony forms
+     * @return Collection|MetaTableTypeInterface[]
+     */
+    public function getMetaFields(): Collection
+    {
+        return $this->meta;
+    }
+
+    /**
+     * @return MetaTableTypeInterface[]
+     */
+    public function getVisibleMetaFields(): array
+    {
+        $all = [];
+        foreach ($this->meta as $meta) {
+            if ($meta->isVisible()) {
+                $all[] = $meta;
+            }
+        }
+
+        return $all;
+    }
+
+    public function getMetaField(string $name): ?MetaTableTypeInterface
+    {
+        foreach ($this->meta as $field) {
+            if ($field->getName() === $name) {
+                return $field;
+            }
+        }
+
+        return null;
+    }
+
+    public function setMetaField(MetaTableTypeInterface $meta): EntityWithMetaFields
+    {
+        if (null === ($current = $this->getMetaField($meta->getName()))) {
+            $meta->setEntity($this);
+            $this->meta->add($meta);
+
+            return $this;
+        }
+
+        $current->merge($meta);
+
+        return $this;
+    }
 }

src/Entity/TimesheetMeta.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Kimai time-tracking app.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * @ORM\Entity()
+ * @ORM\Table(name="kimai2_timesheet_meta",
+ *      uniqueConstraints={
+ *          @ORM\UniqueConstraint(columns={"timesheet_id", "name"})
+ *      }
+ * )
+ */
+class TimesheetMeta implements MetaTableTypeInterface
+{
+    use MetaTableTypeTrait;
+
+    /**
+     * @var Timesheet
+     *
+     * @ORM\ManyToOne(targetEntity="App\Entity\Timesheet", inversedBy="meta")
+     * @ORM\JoinColumn(onDelete="CASCADE")
+     * @Assert\NotNull()
+     */
+    private $timesheet;
+
+    public function setEntity(EntityWithMetaFields $entity): MetaTableTypeInterface
+    {
+        if (!($entity instanceof Timesheet)) {
+            throw new \InvalidArgumentException(
+                sprintf('Expected instanceof Timesheet, received "%s"', get_class($entity))
+            );
+        }
+        $this->timesheet = $entity;
+
+        return $this;
+    }
+
+    public function getEntity(): ?EntityWithMetaFields
+    {
+        return $this->timesheet;
+    }
+}