Improve UX for invoice template management (#4121)

change translations and to explain that calculator actually group items by fields

src/Form/Type/InvoiceCalculatorType.php

@@ -36,6 +36,7 @@ final class InvoiceCalculatorType extends AbstractType
             'choice_label' => function ($renderer) {
                 return $renderer;
             },
+            'help' => 'invoice_calculator.help',
             'translation_domain' => 'invoice-calculator',
         ]);
     }

src/Invoice/Calculator/AbstractSumInvoiceCalculator.php

@@ -18,7 +18,29 @@ use App\Invoice\InvoiceItem;
  */
 abstract class AbstractSumInvoiceCalculator extends AbstractMergedCalculator implements CalculatorInterface
 {
-    abstract protected function calculateSumIdentifier(ExportableItem $invoiceItem): string;
+    protected function calculateSumIdentifier(ExportableItem $invoiceItem): string
+    {
+        $ids = $this->getIdentifiers($invoiceItem);
+
+        $identifier = '';
+        foreach ($ids as $id) {
+            if ($id === null) {
+                $id = '__NULL__';
+            }
+            $identifier .= $id;
+        }
+
+        return $identifier;
+    }
+
+    /**
+     * @param ExportableItem $invoiceItem
+     * @return array<int|string|null>
+     */
+    public function getIdentifiers(ExportableItem $invoiceItem): array
+    {
+        return [];
+    }
 
     protected function calculateIdentifier(ExportableItem $entry): string
     {

src/Invoice/Calculator/ActivityInvoiceCalculator.php

@@ -18,13 +18,11 @@ use App\Invoice\InvoiceItem;
  */
 final class ActivityInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
 {
-    protected function calculateSumIdentifier(ExportableItem $invoiceItem): string
+    public function getIdentifiers(ExportableItem $invoiceItem): array
     {
-        if (null === $invoiceItem->getActivity()) {
-            return '__NULL__';
-        }
-
-        return (string) $invoiceItem->getActivity()->getId();
+        return [
+            $invoiceItem->getActivity()?->getId()
+        ];
     }
 
     protected function mergeSumInvoiceItem(InvoiceItem $invoiceItem, ExportableItem $entry): void

src/Invoice/Calculator/ActivityUserInvoiceCalculator.php

@@ -0,0 +1,50 @@
+<?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\Invoice\Calculator;
+
+use App\Entity\ExportableItem;
+use App\Invoice\CalculatorInterface;
+use App\Invoice\InvoiceItem;
+
+/**
+ * A calculator that sums up the invoice item records by activity and user.
+ */
+final class ActivityUserInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
+{
+    public function getIdentifiers(ExportableItem $invoiceItem): array
+    {
+        if ($invoiceItem->getUser()?->getId() === null) {
+            throw new \Exception('Cannot handle un-persisted users');
+        }
+
+        return [
+            $invoiceItem->getActivity()?->getId(),
+            $invoiceItem->getUser()->getId()
+        ];
+    }
+
+    protected function mergeSumInvoiceItem(InvoiceItem $invoiceItem, ExportableItem $entry): void
+    {
+        if (null === $entry->getActivity()) {
+            return;
+        }
+
+        if ($entry->getActivity()->getInvoiceText() !== null) {
+            $invoiceItem->setDescription($entry->getActivity()->getInvoiceText());
+        } else {
+            $invoiceItem->setDescription($entry->getActivity()->getName());
+        }
+    }
+
+    public function getId(): string
+    {
+        return 'activity_user';
+    }
+}

src/Invoice/Calculator/DateInvoiceCalculator.php

@@ -17,13 +17,15 @@ use App\Invoice\CalculatorInterface;
  */
 final class DateInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
 {
-    protected function calculateSumIdentifier(ExportableItem $invoiceItem): string
+    public function getIdentifiers(ExportableItem $invoiceItem): array
     {
         if (null === $invoiceItem->getBegin()) {
             throw new \Exception('Cannot handle invoice items without start date');
         }
 
-        return $invoiceItem->getBegin()->format('Y-m-d');
+        return [
+            $invoiceItem->getBegin()->format('Y-m-d')
+        ];
     }
 
     public function getId(): string

src/Invoice/Calculator/DateUserInvoiceCalculator.php

@@ -0,0 +1,40 @@
+<?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\Invoice\Calculator;
+
+use App\Entity\ExportableItem;
+use App\Invoice\CalculatorInterface;
+
+/**
+ * A calculator that sums up the invoice item records for each day and user.
+ */
+final class DateUserInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
+{
+    public function getIdentifiers(ExportableItem $invoiceItem): array
+    {
+        if (null === $invoiceItem->getBegin()) {
+            throw new \Exception('Cannot handle invoice items without start date');
+        }
+
+        if ($invoiceItem->getUser()?->getId() === null) {
+            throw new \Exception('Cannot handle un-persisted users');
+        }
+
+        return [
+            $invoiceItem->getBegin()->format('Y-m-d'),
+            $invoiceItem->getUser()->getId()
+        ];
+    }
+
+    public function getId(): string
+    {
+        return 'date_user';
+    }
+}

src/Invoice/Calculator/PriceInvoiceCalculator.php

@@ -17,13 +17,13 @@ use App\Invoice\CalculatorInterface;
  */
 final class PriceInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
 {
-    protected function calculateSumIdentifier(ExportableItem $invoiceItem): string
+    public function getIdentifiers(ExportableItem $invoiceItem): array
     {
         if (null !== $invoiceItem->getFixedRate()) {
-            return 'fixed_' . $invoiceItem->getFixedRate();
+            return ['fixed_' . $invoiceItem->getFixedRate()];
         }
 
-        return 'hourly_' . $invoiceItem->getHourlyRate();
+        return ['hourly_' . $invoiceItem->getHourlyRate()];
     }
 
     public function getId(): string

src/Invoice/Calculator/ProjectInvoiceCalculator.php

@@ -18,17 +18,27 @@ use App\Invoice\InvoiceItem;
  */
 final class ProjectInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
 {
-    protected function calculateSumIdentifier(ExportableItem $invoiceItem): string
+    public function getIdentifiers(ExportableItem $invoiceItem): array
     {
-        if (null === $invoiceItem->getProject()->getId()) {
+        if ($invoiceItem->getProject() === null) {
+            throw new \Exception('Cannot handle invoice items without project');
+        }
+
+        if ($invoiceItem->getProject()->getId() === null) {
             throw new \Exception('Cannot handle un-persisted projects');
         }
 
-        return (string) $invoiceItem->getProject()->getId();
+        return [
+            $invoiceItem->getProject()->getId()
+        ];
     }
 
     protected function mergeSumInvoiceItem(InvoiceItem $invoiceItem, ExportableItem $entry): void
     {
+        if ($entry->getProject() === null) {
+            return;
+        }
+
         if ($entry->getProject()->getInvoiceText() !== null) {
             $invoiceItem->setDescription($entry->getProject()->getInvoiceText());
         } else {

src/Invoice/Calculator/ProjectUserInvoiceCalculator.php

@@ -0,0 +1,62 @@
+<?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\Invoice\Calculator;
+
+use App\Entity\ExportableItem;
+use App\Invoice\CalculatorInterface;
+use App\Invoice\InvoiceItem;
+
+/**
+ * A calculator that sums up the invoice item records by project and user.
+ */
+final class ProjectUserInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
+{
+    public function getIdentifiers(ExportableItem $invoiceItem): array
+    {
+        if ($invoiceItem->getProject() === null) {
+            throw new \Exception('Cannot handle invoice items without project');
+        }
+
+        if ($invoiceItem->getProject()->getId() === null) {
+            throw new \Exception('Cannot handle un-persisted projects');
+        }
+
+        if ($invoiceItem->getUser() === null) {
+            throw new \Exception('Cannot handle invoice items without user');
+        }
+
+        if ($invoiceItem->getUser()->getId() === null) {
+            throw new \Exception('Cannot handle un-persisted users');
+        }
+
+        return [
+            $invoiceItem->getProject()->getId(),
+            $invoiceItem->getUser()->getId()
+        ];
+    }
+
+    protected function mergeSumInvoiceItem(InvoiceItem $invoiceItem, ExportableItem $entry): void
+    {
+        if ($entry->getProject() === null) {
+            return;
+        }
+
+        if ($entry->getProject()->getInvoiceText() !== null) {
+            $invoiceItem->setDescription($entry->getProject()->getInvoiceText());
+        } else {
+            $invoiceItem->setDescription($entry->getProject()->getName());
+        }
+    }
+
+    public function getId(): string
+    {
+        return 'project_user';
+    }
+}

src/Invoice/Calculator/ShortInvoiceCalculator.php

@@ -32,9 +32,9 @@ final class ShortInvoiceCalculator extends AbstractMergedCalculator implements C
         $keys = [];
 
         foreach ($entries as $entry) {
-            $key = 'hourly_' . (string) $entry->getHourlyRate();
+            $key = 'hourly_' . $entry->getHourlyRate();
             if (null !== $entry->getFixedRate()) {
-                $key = 'fixed_' . (string) $entry->getFixedRate();
+                $key = 'fixed_' . $entry->getFixedRate();
             }
             if (!\in_array($key, $keys)) {
                 $keys[] = $key;

src/Invoice/Calculator/UserInvoiceCalculator.php

@@ -17,13 +17,15 @@ use App\Invoice\CalculatorInterface;
  */
 final class UserInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
 {
-    protected function calculateSumIdentifier(ExportableItem $invoiceItem): string
+    public function getIdentifiers(ExportableItem $invoiceItem): array
     {
-        if (null === $invoiceItem->getUser()->getId()) {
+        if (null === $invoiceItem->getUser()?->getId()) {
             throw new \Exception('Cannot handle un-persisted user');
         }
 
-        return (string) $invoiceItem->getUser()->getId();
+        return [
+            $invoiceItem->getUser()->getId()
+        ];
     }
 
     public function getId(): string

src/Invoice/Calculator/WeeklyInvoiceCalculator.php

@@ -17,9 +17,15 @@ use App\Invoice\CalculatorInterface;
  */
 final class WeeklyInvoiceCalculator extends AbstractSumInvoiceCalculator implements CalculatorInterface
 {
-    protected function calculateSumIdentifier(ExportableItem $invoiceItem): string
+    public function getIdentifiers(ExportableItem $invoiceItem): array
     {
-        return $invoiceItem->getBegin()->format('W');
+        if (null === $invoiceItem->getBegin()) {
+            throw new \Exception('Cannot handle invoice items without start date');
+        }
+
+        return [
+            $invoiceItem->getBegin()->format('W')
+        ];
     }
 
     public function getId(): string