/**
* Gets Bf_Notifications that occurred during the given time range. Optionally, the search can be constrained (by ID) to a specific webhook.
* Time range is at granularity of seconds, and is exclusive of timeStart but inclusive of timeEnd
* i.e. 'Second at which notification was created' > $timeStart
* && 'Second at which notification was created' <= $timeEnd
* As with all GETs, by default 10 records are returned, so use the `options` field if you want to page through using for example array('records' => 10, `offset`=30)
* @param union[int|string] <int>: Unix timestamp (for example generated by time()). <string>: UTC ISO8601 string
* @param union[int|string|NULL] (Default: NULL) <int>: Unix timestamp (for example generated by time()). <string>: UTC ISO8601 string. <NULL>: Interpreted as 'Now'.
* @param union[string $id | Bf_Webhook $entity | NULL] (Default: NULL) The webhook for which you wish to GET notifications. <string>: ID of the Bf_Webhook. <Bf_Webhook>: The Bf_Webhook. <NULL>: GET notifications of all types.
* @return Bf_Notification[]
*/
public static function getForTimeRange($timeStart, $timeEnd = NULL, $webhook = NULL, $options = NULL, $customClient = NULL)
{
if (is_null($timeEnd)) {
$timeEnd = time();
}
$webhookID = is_null($webhook) ? NULL : Bf_Webhook::getIdentifier($webhook);
// empty IDs are no good!
if (!$timeStart) {
throw new Bf_EmptyArgumentException("Cannot lookup empty start time!");
}
if (!$timeEnd) {
throw new Bf_EmptyArgumentException("Cannot lookup empty end time!");
}
if (is_int($timeStart)) {
$timeStart = Bf_BillingEntity::makeBillForwardDate($timeStart);
}
if (is_int($timeEnd)) {
$timeEnd = Bf_BillingEntity::makeBillForwardDate($timeEnd);
}
// path param expects format like: '2015-04-23T11:05:53'
$timeStart = rtrim($timeStart, "Z");
$timeEnd = rtrim($timeEnd, "Z");
$endpoint = sprintf("%s/%s%s", $timeStart, $timeEnd, is_null($webhookID) ? "" : sprintf("/%s", rawurlencode($webhookID)));
return static::getCollection($endpoint, $options, $customClient);
}
/**
* Parses into a BillForward timestamp the Bf_TimeRequest 'From' time
* @param union[int $timestamp | string_ENUM['Now', 'CurrentPeriodEnd']] (Default: 'Immediate') When to action the amendment
*
* int
* 'From' the specified UNIX timestamp.
* Examples:
* * time()
* * 1431704624
* * Bf_BillingEntity::makeUTCTimeFromBillForwardDate('2015-04-23T17:13:37Z')
*
* string (within ENUM)
* <Immediate> (Default)
* 'To' the time at which the request reaches the server
*
* <ClientNow>
* 'To' the current time by this client's clock.
*
* <CurrentPeriodEnd>
* 'To' 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 'CurrentPeriodEnd' 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 parseTimeRequestToTime($fromTime, $subscription = NULL)
{
$intSpecified = NULL;
switch ($fromTime) {
case 'ServerNow':
case 'Immediate':
return NULL;
case 'CurrentPeriodEnd':
// we need to consult subscription
if (is_null($subscription)) {
throw new Bf_EmptyArgumentException('Failed to consult subscription to ascertain CurrentPeriodEnd 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($fromTime)) {
$intSpecified = $fromTime;
}
if (!is_null($intSpecified)) {
return Bf_BillingEntity::makeBillForwardDate($intSpecified);
}
if (is_string($fromTime)) {
return $fromTime;
}
}
return NULL;
}
/**
* Returns a Bf_AmendmentPriceRequest model with 'componentValues' mapped to the input key-value pairs.
* @param array List of pricing component properties; array(array('name' => 'Bandwidth usage'), array('name' => 'CPU usage'))
* @param array List of values to assign to respective pricing components; array(103, 2)
* @param string (option 1) The ID of the subscription for which to generate a price request
* @param Bf_Subscription (option 2) The model of the subscription for which to generate an upgrade price request; provide this to avoid fetching from API
* @return Bf_AmendmentPriceRequest The constructed Bf_AmendmentPriceRequest
*/
public static function forPricingComponentsByProperties(array $propertiesList, array $valuesList, $subscriptionID = null, Bf_Subscription $subscriptionModel = null)
{
if (!is_array($propertiesList)) {
throw new Bf_MalformedInputException('Expected input to be an array (a list of entity property maps). Instead received: ' + $propertiesList);
}
if (!is_array($valuesList)) {
throw new Bf_MalformedInputException('Expected input to be an array (a list of integer values). Instead received: ' + $valuesList);
}
$subscription;
if (is_null($subscriptionModel)) {
if (is_null($subscriptionID)) {
throw new Bf_EmptyArgumentException('Received null subscription, and null subscription ID.');
}
// fetch from API
$subscription = Bf_Subscription::getByID($subscriptionID);
} else {
$subscription = $subscriptionModel;
}
$componentValues = array();
$productRatePlan = $subscription->getProductRatePlan();
foreach ($propertiesList as $key => $value) {
if (!is_array($value)) {
throw new Bf_MalformedInputException('Expected each element of input array to be an array (a map of expected properties on entity, to values). Instead received: ' + $value);
}
$pricingComponent = $productRatePlan->getPricingComponentWithProperties($value);
$updatedPricingComponentValue = new Bf_PricingComponentValue(array('pricingComponentID' => $pricingComponent->id, 'value' => $valuesList[$key]));
array_push($componentValues, $updatedPricingComponentValue);
}
$model = new Bf_AmendmentPriceRequest(array('subscription' => $subscription, 'componentValues' => $componentValues, 'asOfDate' => Bf_BillingEntity::makeBillForwardDate(time())));
return $model;
}