CampaignStatistics.php

<?php

namespace MatchBot\Domain;

use Doctrine\ORM\Mapping as ORM;
use MatchBot\Application\Assertion;

/**
 * Holds automatically calculated summary information from donations associated with a {@see Campaign}.
 * We keep copies so search ordering can stay performant, and to keep sync from Salesforce to charity
 * Campaigns one-way.
 *
 * @see Campaign for notes on deferred explicit change tracking.
 *
 * @psalm-suppress UnusedProperty Properties are used in DQL & for manual DB queries
 * @psalm-suppress PossiblyUnusedProperty
 */
#[ORM\Entity(
    repositoryClass: null // we construct our own repository
)]
#[ORM\HasLifecycleCallbacks]
#[ORM\Index(columns: ['amount_raised_amountInPence'], name: 'amount_raised_amountInPence')]
#[ORM\Index(columns: ['match_funds_used_amountInPence'], name: 'match_funds_used_amountInPence')]
#[ORM\Index(columns: ['lastCheck'], name: 'lastCheck')]
#[ORM\Index(columns: ['approxStatus'], name: 'approxStatus')]
#[ORM\ChangeTrackingPolicy('DEFERRED_EXPLICIT')]
class CampaignStatistics
{
    use TimestampsTrait;

    #[ORM\Column(nullable: true, type: 'datetime_immutable')]
    private ?\DateTimeImmutable $lastCheck = null;

    #[ORM\Column(nullable: true, type: 'datetime_immutable')]
    private ?\DateTimeImmutable $lastRealUpdate = null;

    #[ORM\OneToOne(inversedBy: 'campaignStatistics', fetch: 'EAGER')]
    #[ORM\Id]
    private Campaign $campaign;

    #[ORM\Column(length: 18, unique: true)]
    protected string $campaignSalesforceId;

    /**
     * Total of core donation amounts and match funds, without Gift Aid.
     * Set on construct and updated when donations change.
     */
    #[ORM\Embedded(columnPrefix: 'amount_raised_')]
    private Money $amountRaised;

    /**
     * Total of core donation amounts, without match funds or Gift Aid.
     * Set on construct and updated when donations change.
     */
    #[ORM\Embedded(columnPrefix: 'donation_sum_')]
    private Money $donationSum;

    /*
     * Total of all match funds allocated to the campaign, shared or not, including funds
     * that have already been matched to a donation as well as available funds.
     **/
    #[ORM\Embedded(columnPrefix: 'match_funds_total_')]
    private Money $matchFundsTotal;

    /** Total of match funds that have been withdrawn for donations to this campaign. */
    #[ORM\Embedded(columnPrefix: 'match_funds_used_')]
    private Money $matchFundsUsed;

    /** Total of match funds still available to use for donations to this campaign. Should be equal to
     * matchFundsTotal - matchFundsUsed.
     */
    #[ORM\Embedded(columnPrefix: 'match_funds_remaining_')]
    private Money $matchFundsRemaining;

    /**
     * Uses {@see Campaign::$totalFundraisingTarget} on each update.
     * It's set to zero of the Campaign currency when the target is met, which also leads search to exclude the
     * Campaign when sorting by distance ascending.
     */
    #[ORM\Embedded(columnPrefix: 'distance_to_target_')]
    private Money $distanceToTarget;

    /**
     * Roughly what the campaign status is, but as we can't update all campaigns instantaneously, at campaign start time
     * this will be updated to Active shortly before the campaign opens, and not updated to Expired until some time
     * after the campaign closes. Used to determine sort order. For precise status {@see Campaign::getStatus}
     */
    #[ORM\Column]
    protected CampaignStatus $approxStatus;

    /**
     * @param Money $target
     * @param Money $matchFundsTotal
     * @param Campaign $campaign
     * @param Money $matchFundsUsed
     * @param Money $amountRaised
     *
     * $amountRaised must be equal to $matchFundsUsed + $donationSum
     */
    public function __construct(
        \DateTimeImmutable $at,
        Campaign $campaign,
        Money $donationSum,
        Money $amountRaised,
        Money $matchFundsUsed,
        Money $matchFundsTotal,
        Money $target,
    ) {
        $this->createdNow();
        $this->campaign = $campaign;
        $this->campaignSalesforceId = $campaign->getSalesforceId();
        $this->approxStatus = $this->approximateStatus($campaign, $at);

        $this->setTotals(
            at: $at,
            donationSum: $donationSum,
            amountRaised: $amountRaised,
            matchFundsUsed: $matchFundsUsed,
            matchFundsTotal: $matchFundsTotal,
            alwaysConsiderChanged: true,
            target: $target,
        );
    }

    public static function zeroPlaceholder(Campaign $campaign, \DateTimeImmutable $at): self
    {
        $zero = Money::zero($campaign->getCurrency());

        return new self($at, $campaign, $zero, $zero, $zero, $zero, $zero);
    }

    public function getDonationSum(): Money
    {
        return $this->donationSum;
    }

    public function getAmountRaised(): Money
    {
        return $this->amountRaised;
    }

    public function getMatchFundsUsed(): Money
    {
        return $this->matchFundsUsed;
    }

    public function getMatchFundsRemaining(): Money
    {
        return $this->matchFundsRemaining;
    }

    public function getMatchFundsTotal(): Money
    {
        return $this->matchFundsTotal;
    }

    public function getDistanceToTarget(): Money
    {
        return $this->distanceToTarget;
    }

    /**
     * We manually set $lastCheck and $lastRealUpdate, since we need the former to avoid wasting resources and
     * changing that will cause lifecycle hooks to change $updatedAt.
     *
     * @param Money $target
     * @param bool $alwaysConsiderChanged Hacky prop for now to avoid sa & runtime confusion about uninitialised
     *                                    props. Constructor sets true, other callers false.
     * @return bool Whether anything changed vs. the previously persisted stats.
     */
    final public function setTotals(
        \DateTimeImmutable $at,
        Money $donationSum,
        Money $amountRaised,
        Money $matchFundsUsed,
        Money $matchFundsTotal,
        bool $alwaysConsiderChanged,
        Money $target,
    ): bool {
        Assertion::greaterOrEqualThan(
            $matchFundsTotal->toNumericString(),
            $matchFundsUsed->toNumericString(),
            'Match funds total must be greater than or equal to match funds used',
        );

        Assertion::eq(
            $amountRaised->toNumericString(),
            $donationSum->plus($matchFundsUsed)->toNumericString(),
            'Amount raised must equal donation sum plus match funds used',
        );

        /** @var ?CampaignStatistics $previousStats */
        $previousStats = null;
        if (!$alwaysConsiderChanged) {
            $previousStats = clone $this;
        }

        $this->amountRaised = $amountRaised;
        $this->donationSum = $donationSum;
        $this->matchFundsUsed = $matchFundsUsed;
        $this->matchFundsTotal = $matchFundsTotal;

        if ($matchFundsUsed->greaterThan($matchFundsTotal)) {
            // possibly we should say the matchFundsRemaining is negative in this case due to an error
            // but various systems may not support negative, setting to zero is better than
            // not updating at all in this case. The Money Constructor does not currently allow constructing
            // negative sums.
            $this->matchFundsRemaining = Money::zero($matchFundsTotal->currency);
        } else {
            $this->matchFundsRemaining = $matchFundsTotal->minus($matchFundsUsed);
        }

        $this->distanceToTarget = $target->lessThan($amountRaised)
            ? Money::zero($this->campaign->getCurrency())
            : $target->minus($amountRaised);

        $didRealUpdate = true;
        if ($previousStats instanceof self) {
            $didRealUpdate = (
                $previousStats->getAmountRaised() != $amountRaised
                || $previousStats->getDonationSum() != $donationSum
                || $previousStats->getMatchFundsUsed() != $matchFundsUsed
                || $previousStats->getMatchFundsTotal() != $matchFundsTotal
                || $previousStats->getMatchFundsRemaining() != $this->matchFundsRemaining
                || $previousStats->getDistanceToTarget() != $this->distanceToTarget
            );
        }

        $this->lastCheck = $at;
        if (!$didRealUpdate) {
            return false;
        }

        $this->lastRealUpdate = $at;

        return true;
    }

    /**
      * Returns a status based on a very rough approximation of the time, with a bias towards making the campaign
     *  appear open for longer than it really is not shorter, to make sure it's easy to find before and after opening.
     */
    private function approximateStatus(Campaign $campaign, \DateTimeImmutable $at): CampaignStatus
    {
        $oneDay = new \DateInterval('P1D');

        if ($at < $campaign->getStartDate()->sub($oneDay)) {
            return CampaignStatus::Preview;
        } elseif ($at <= $campaign->getEndDate()) { // no need to approximate this part, it's not expected to change again
            return CampaignStatus::Active;
        } else {
            return CampaignStatus::Expired;
        }
    }
}