PortaDateTime
extends DateTimeImmutable
in package
Immutable class to handle PortaOne billing datetime and date strings as objects
Portaone API always use UTC datetime while local timezone is essential to show/set datetime at the business-logic level.
In addition, some specific task appears like to set correct addon product change overe midnight at local time: last second of one day to end one product and 00:00:00 of the next day for the new product.
This class extends DateTimeImmutable with simple way to translate between porta-formatted UTC strings and DateTime objects in local timezone plus some useful functions to set time at specific boundaries.
Immutable means call of any modification method returns a new instance of the class.
Also, mind that default timezone may be defined in PSR-11 container, see __construct() below.
See the usage example
Table of Contents
- DEFAULT_TIMEZONE_TAG = 'default.timezone'
- Default timezone tag to retrieve default timezone from PSR-11 container
- PORTA_DATE = 'Y-m-d'
- Standart Porta format for date-only string
- PORTA_DATETIME = 'Y-m-d H:i:s'
- Standart Porta format for date-time string
- __construct() : mixed
- Setup the class
- between() : bool
- Return true if object datetime is between $from and $to
- firstDayNextMonth() : PortaDateTime
- return object which set to the fist day of the next month
- firstMoment() : PortaDateTime
- Set time to the first moment of the day in the current timezone
- formatDateTime() : string
- Returns Portaone-format datetime string in UTC for any DateTimeInterface
- formatPorta() : string
- Return Porta-formatted datetime string at UTC timezone
- fromInterface() : PotrtaDateTime
- Create PortaDateTime object from any DateTimeInterface object
- fromPortaDateString() : PortaDateTime
- Creates PortaDateTime object from Portaone date-only string
- fromPortaString() : PortaDateTime
- Creates PortaDateTime object from Porta-formatted string
- inFuture() : bool
- Checks if the datetime in the future or not
- inPast() : bool
- Checks if the datetime in the past or not
- lastDayThisMonth() : PortaDateTime
- Return object which set to the last day of current object's month
- lastMoment() : PortaDateTime
- Set time to the last moment of the day (23:59:59) in the current timezone
- nextDay() : PortaDateTime
- Return object with one day later than this one
- prorateTillEndOfMonth() : float
- Calculates prorated value from given date till the end of the month
Constants
DEFAULT_TIMEZONE_TAG
Default timezone tag to retrieve default timezone from PSR-11 container
public
mixed
DEFAULT_TIMEZONE_TAG
= 'default.timezone'
PORTA_DATE
Standart Porta format for date-only string
public
mixed
PORTA_DATE
= 'Y-m-d'
PORTA_DATETIME
Standart Porta format for date-time string
public
mixed
PORTA_DATETIME
= 'Y-m-d H:i:s'
Methods
__construct()
Setup the class
public
__construct([string $datetime = "now" ][, string|DateTimeZone|ContainerInterface $timezone = "UTC" ][, string $timezoneTag = self::DEFAULT_TIMEZONE_TAG ]) : mixed
The same as standard DateTimeImmutable, but may accept timezone very different ways either DateTimeZone class or just a timezone string.
Parameters
- $datetime : string = "now"
-
The same as basic DateTime parameter
- $timezone : string|DateTimeZone|ContainerInterface = "UTC"
-
Timezone may be supplied different ways:
- By providing DateTimeZone object, same as base class
- By providig string, then DateTimeZone object will be created using this string as timezone argument
- By providing PSR-11 container object, then constructor will use get() method to retrieve DateTimeZone object or timezone string from the container. See $tomezoneTag info below. If it failed to retrieve timezone from container - it will fallbeck to UTC silently.
- $timezoneTag : string = self::DEFAULT_TIMEZONE_TAG
-
optional, only used if PSR-11 container given as timezone argument to use as
$timezone->get($timezoneTag). If omit, class constant PortaDateTime::DEFAULT_TIMEZONE_TAG default tag be used.
Return values
mixed —between()
Return true if object datetime is between $from and $to
public
between(PortaDateTime|null $from, PortaDateTime|null $to) : bool
If $from or $to set to null, it means there no limit on the side.
Parameters
- $from : PortaDateTime|null
- $to : PortaDateTime|null
Return values
bool —firstDayNextMonth()
return object which set to the fist day of the next month
public
firstDayNextMonth() : PortaDateTime
Return values
PortaDateTime —new object with applied changes
firstMoment()
Set time to the first moment of the day in the current timezone
public
firstMoment() : PortaDateTime
Return values
PortaDateTime —new object with applied changes
formatDateTime()
Returns Portaone-format datetime string in UTC for any DateTimeInterface
public
static formatDateTime(DateTimeInterface $datetime) : string
Parameters
- $datetime : DateTimeInterface
Return values
string —formatPorta()
Return Porta-formatted datetime string at UTC timezone
public
formatPorta() : string
Shift timezone to UTC and format to Porta format datetime string.
Return values
string —Porta-formatted datetime string in UTC zone
fromInterface()
Create PortaDateTime object from any DateTimeInterface object
public
static fromInterface(DateTimeInterface $object) : PotrtaDateTime
Timezone of the jbject will match timezone of the given source
Parameters
- $object : DateTimeInterface
-
to convert to PortaDateTime object
Return values
PotrtaDateTime —fromPortaDateString()
Creates PortaDateTime object from Portaone date-only string
public
static fromPortaDateString(string $date[, string|DateTimeZone|ContainerInterface $timezone = 'UTC' ][, string $timezoneTag = self::DEFAULT_TIMEZONE_TAG ]) : PortaDateTime
Creates object from Portaone date-only string with time is set to zero in desired timezone. The difference to create from full datetime porta string is that date string in the billing always related to context-local (example - customer) timzone, then need to be set right way.
Parameters
- $date : string
-
- the date string as you got it form billing
- $timezone : string|DateTimeZone|ContainerInterface = 'UTC'
-
Timezone may be supplied different ways:
- By providing DateTimeZone object, same as base class
- By providig string, then DateTimeZone object will be created using this string as timezone argument
- By providing PSR-11 container object, then constructor will use get() method to retrieve DateTimeZone object or timezone string from the container. See $tomezoneTag info below. If it failed to retrieve timezone from container - it will fallbeck to UTC silently.
- $timezoneTag : string = self::DEFAULT_TIMEZONE_TAG
-
optional, only used if PSR-11 container given as timezone argument to use as
$timezone->get($timezoneTag). If omit, class constant PortaDateTime::DEFAULT_TIMEZONE_TAG default tag be used.
Return values
PortaDateTime —fromPortaString()
Creates PortaDateTime object from Porta-formatted string
public
static fromPortaString(string $datetime[, string|DateTimeZone|ContainerInterface $timezone = 'UTC' ][, string $timezoneTag = self::DEFAULT_TIMEZONE_TAG ]) : PortaDateTime
Creates object from Portaone datetime string with desired timezone. Please, mind the billing always returns datetime in UTC.
Parameters
- $datetime : string
-
- the datetime string as you got it form billing
- $timezone : string|DateTimeZone|ContainerInterface = 'UTC'
-
Timezone may be supplied different ways:
- By providing DateTimeZone object, same as base class
- By providig string, then DateTimeZone object will be created using this string as timezone argument
- By providing PSR-11 container object, then constructor will use get() method to retrieve DateTimeZone object or timezone string from the container. See $tomezoneTag info below. If it failed to retrieve timezone from container - it will fallbeck to UTC silently.
- $timezoneTag : string = self::DEFAULT_TIMEZONE_TAG
-
optional, only used if PSR-11 container given as timezone argument to use as
$timezone->get($timezoneTag). If omit, class constant PortaDateTime::DEFAULT_TIMEZONE_TAG default tag be used.
Return values
PortaDateTime —inFuture()
Checks if the datetime in the future or not
public
inFuture() : bool
Return values
bool —true if datetime in the future
inPast()
Checks if the datetime in the past or not
public
inPast() : bool
Return values
bool —true if datetime in the future
lastDayThisMonth()
Return object which set to the last day of current object's month
public
lastDayThisMonth() : PortaDateTime
Return values
PortaDateTime —new object with applied changes
lastMoment()
Set time to the last moment of the day (23:59:59) in the current timezone
public
lastMoment() : PortaDateTime
Return values
PortaDateTime —new object with applied changes
nextDay()
Return object with one day later than this one
public
nextDay() : PortaDateTime
Return values
PortaDateTime —new object with applied changes
prorateTillEndOfMonth()
Calculates prorated value from given date till the end of the month
public
prorateTillEndOfMonth(float $fee) : float
Parameters
- $fee : float
-
Basic rate to prorate
Return values
float —Prorated value