/**
* Parses into a BillForward timestamp the actioning time for some amendment
* @param union[int $timestamp | string_ENUM['Immediate' | 'ServerNow', 'ClientNow', 'AtPeriodEnd']] (Default: 'Immediate') When to action the amendment
*
* int
* Schedule the amendment to occur at the specified UNIX timestamp.
* Examples:
* * time()
* * 1431704624
* * Bf_BillingEntity::makeUTCTimeFromBillForwardDate('2015-04-23T17:13:37Z')
*
* string (within ENUM)
* <Immediate> (Default) | <ServerNow>
* Perform the amendment now (synchronously where possible). Actioning time is set to BillForward's 'now' at the time it parses the request.
*
* <ClientNow>
* Schedule the amendment for 'now' according to this client's clock (which will likely be in the past by the time the request reaches BillForward).
*
* <AtPeriodEnd>
* Schedule the amendment to occur at the end of the subscription's current billing period.
*
* string (outside ENUM)
* Schedule the amendment to occur at the specified BillForward-formatted timestamp.
* Examples:
* * '2015-04-23T17:13:37Z'
* * Bf_BillingEntity::makeBillForwardDate(time())
* * Bf_BillingEntity::makeBillForwardDate(1431704624)
*
* @param union[NULL | union[string $id | Bf_Subscription $entity]] (Default: NULL) (Optional unless 'AtPeriodEnd' actioningTime specified) Reference to subscription <string>: $id of the Bf_Subscription. <Bf_Subscription>: The Bf_Subscription entity.
* @return string The BillForward-formatted time.
*/
public static function parseActioningTime($actioningTime, $subscription = NULL)
{
$intSpecified = NULL;
switch ($actioningTime) {
case 'ServerNow':
case 'Immediate':
return NULL;
case 'AtPeriodEnd':
// we need to consult subscription
if (is_null($subscription)) {
throw new Bf_EmptyArgumentException('Failed to consult subscription to ascertain AtPeriodEnd time, because a null reference was provided to the subscription.');
}
$subscriptionFetched = Bf_Subscription::fetchIfNecessary($subscription);
return $subscriptionFetched->getCurrentPeriodEnd();
case 'ClientNow':
$intSpecified = time();
default:
if (is_int($actioningTime)) {
$intSpecified = $actioningTime;
}
if (!is_null($intSpecified)) {
return Bf_BillingEntity::makeBillForwardDate($intSpecified);
}
if (is_string($actioningTime)) {
return $actioningTime;
}
}
return NULL;
}
