Feature: Add endpoint for Campaign Overview Statistics

[kjohnson]

Related GIVE-1221
Related GIVE-1222

Description

This PR adds the GET \give-api\v2\campaign-overview-statistics endpoint for fetching campaign statistics, such as Amount Raised, Donation Count, and Donor Count.

If a range in days (rangeInDays) is provided then a pair of values are returned to include the previous period of the range.

Affects

• Campaigns\CampaignDonationQuery has been updated with support for immutability.

• Framework\Support\Facades\DateTime\TemporalFacade has been updated to include new helper methods withStartOfDay and withEndOfDay, which set the appropriate time for inclusively querying dates in a range. Additionally, the immutableOrClone method has been added to encapsulate support for immutability that accounts for either DateTime or DateTimeImmutable, both of which implement the DateTimeInterface.

• Framework\Support\Facades\DateTime\Temporal has been updated with available methods using @method annotations in the docblock.

Visuals

// "All time"
[
    [
        'amountRaised' => 20,
        'donationCount' => 2,
        'donorCount' => 2,
    ],
]

// Period of time with previous period
[
    [
        // Current period
        'amountRaised' => 20,
        'donationCount' => 2,
        'donorCount' => 2,
    ],
    [
        // Previous period
        'amountRaised' => 10,
        'donationCount' => 1,
        'donorCount' => 1,
    ],
]

Pre-review Checklist

• Relevant @unreleased tags included in DocBlocks
• Includes unit tests
• Self Review of code and UX completed

[glaubersilva]

@kjohnson Great work! I left a few comments related to some minor changes, but also would like to suggest something that I think would be helpful.

I think we need to add a dateRange property in the route returns, something like this:

// "All time"
[
    [
        'dateRange' => ['startDate' => '0', 'endDate' => '0']
        'amountRaised' => 20,
        'donationCount' => 2,
        'donorCount' => 2,
    ],
]

// Period of time with previous period
[
    [
        // Current period
        'dateRange' => ['startDate' => 'value', 'endDate' => 'value']
        'amountRaised' => 20,
        'donationCount' => 2,
        'donorCount' => 2,
    ],
    [
        // Previous period
        'dateRange' => ['startDate' => 'value', 'endDate' => 'value']
        'amountRaised' => 10,
        'donationCount' => 1,
        'donorCount' => 1,
    ],
]

I was checking the code using PHP XDebug and took a while to understand the testReturnsPeriodStatisticsWithPreviousPeriod() without this information, so I think it can be used in future debug sessions and also can be helpful to have this information on the JS side.

[kjohnson]

@glaubersilva the intention of the data format is to be a queue of data, so the current is always first and moves backwards one period per item in the array. This could be better documented or made more clear.

[glaubersilva]

@kjohnson Great work!