optimize query for current address + documentation

src/Bundle/ChillPersonBundle/Entity/Person.php

@@ -35,6 +35,7 @@ use Chill\PersonBundle\Entity\Household\HouseholdMember;
 use Chill\MainBundle\Entity\HasCenterInterface;
 use Chill\MainBundle\Entity\Address;
 use Chill\MainBundle\Entity\Embeddable\CommentEmbeddable;
+use Chill\PersonBundle\Entity\Person\PersonCurrentAddress;
 use DateTime;
 use Doctrine\ORM\Mapping as ORM;
 use Doctrine\Common\Collections\Collection;
@@ -412,6 +413,15 @@ class Person implements HasCenterInterface, TrackCreationInterface, TrackUpdateI
      */
     private $addresses;
 
+    /**
+     * The current person address.
+     *
+     * This is computed through database and is optimized on database side.
+     *
+     * @var PersonCurrentAddress|null
+     */
+    private ?PersonCurrentAddress $currentPersonAddress = null;
+
     /**
      * fullname canonical. Read-only field, which is calculated by
      * the database.
@@ -564,6 +574,8 @@ class Person implements HasCenterInterface, TrackCreationInterface, TrackUpdateI
                 return $participation->getAccompanyingPeriod();
             }
         }
+
+        return null;
     }
 
     /**
@@ -1242,13 +1254,31 @@ class Person implements HasCenterInterface, TrackCreationInterface, TrackUpdateI
         return $this->addresses;
     }
 
+    /**
+     * @deprecated Use `getCurrentPersonAddress` instead
+     * @param DateTime|null $from
+     * @return false|mixed|null
+     * @throws \Exception
+     */
     public function getLastAddress(DateTime $from = null)
     {
-        $from ??= new DateTime('now');
+        return $this->getCurrentPersonAddress($from);
+    }
+
+    /**
+     * get the address associated with the person at the given date
+     *
+     * @param DateTime|null $at
+     * @return Address|null
+     * @throws \Exception
+     */
+    public function getCurrentPersonAddress(?\DateTime $at = null): ?Address
+    {
+        $at ??= new DateTime('now');
 
         /** @var ArrayIterator $addressesIterator */
         $addressesIterator = $this->getAddresses()
-            ->filter(static fn (Address $address): bool => $address->getValidFrom() <= $from)
+            ->filter(static fn (Address $address): bool => $address->getValidFrom() <= $at)
             ->getIterator();
 
         $addressesIterator->uasort(
@@ -1496,7 +1526,16 @@ class Person implements HasCenterInterface, TrackCreationInterface, TrackUpdateI
 
     public function getCurrentHouseholdAddress(?\DateTimeImmutable $at = null): ?Address
     {
-        $at = $at === null ? new \DateTimeImmutable('today') : $at;
+        if (
+            NULL === $at
+            ||
+            $at->format('Ymd') === (new \DateTime('today'))->format('Ymd')
+        ) {
+            return $this->currentPersonAddress instanceof PersonCurrentAddress
+                ? $this->currentPersonAddress->getAddress() : NULL;
+        }
+
+        // if not now, compute the date from history
         $criteria = new Criteria();
         $expr = Criteria::expr();