TimeInterval
in package
Date & time interval and numeric range handling class for Reporting API.
Table of Contents
- $iso_datetime_format : string
- Format string for ISO DateTime formatter.
- $sql_datetime_format : string
- Format string for use in SQL queries.
- convert_local_datetime_to_gmt() : DateTime
- Converts local datetime to GMT/UTC time.
- db_datetime_format() : mixed
- Returns date format to be used as grouping clause in SQL.
- default_after() : DateTime
- Returns default 'after' parameter for the reports.
- default_before() : DateTime
- Returns default 'before' parameter for the reports.
- expected_intervals_on_page() : float|int
- Returns expected number of items on the page in case of date ordering.
- get_timeframe_dates() : array<string|int, mixed>
- Get dates from a timeframe string.
- intervals_between() : int
- Calculates number of time intervals between two dates, closed interval on both sides.
- intervals_missing() : bool
- Returns true if there are any intervals that need to be filled in the response.
- iterate() : DateTime
- Returns beginning of next time interval for provided DateTime.
- next_day_start() : DateTime
- Returns a new DateTime object representing the next day start, or previous day end if reversed.
- next_hour_start() : DateTime
- Returns a new DateTime object representing the next hour start/previous hour end if reversed.
- next_month_start() : DateTime
- Returns a new DateTime object representing the next month start, or previous month end if reversed.
- next_quarter_start() : DateTime
- Returns a new DateTime object representing the next quarter start, or previous quarter end if reversed.
- next_week_start() : DateTime
- Returns DateTime object representing the next week start, or previous week end if reversed.
- next_year_start() : DateTime
- Return a new DateTime object representing the next year start, or previous year end if reversed.
- normalize_between_params() : array<string|int, mixed>
- Normalize "*_between" parameters to "*_min" and "*_max" for numeric values and "*_after" and "*_before" for date values.
- quarter() : int|null
- Returns quarter for the DateTime.
- rest_validate_between_date_arg() : WP_Error|bool
- Validate a "*_between" range argument (an array with 2 date items).
- rest_validate_between_numeric_arg() : WP_Error|bool
- Validate a "*_between" range argument (an array with 2 numeric items).
- simple_week_number() : int
- Returns simple week number for the DateTime, for week starting on $first_day_of_week.
- time_interval_id() : string
- Returns time interval id for the DateTime.
- week_number() : int
- Returns ISO 8601 week number for the DateTime, if week starts on Monday, otherwise returns simple week number.
Properties
$iso_datetime_format
Format string for ISO DateTime formatter.
public
static string
$iso_datetime_format
= 'Y-m-d\TH:i:s'
$sql_datetime_format
Format string for use in SQL queries.
public
static string
$sql_datetime_format
= 'Y-m-d H:i:s'
Methods
convert_local_datetime_to_gmt()
Converts local datetime to GMT/UTC time.
public
static convert_local_datetime_to_gmt(string $datetime_string) : DateTime
Parameters
- $datetime_string : string
-
String representation of local datetime.
Return values
DateTime —db_datetime_format()
Returns date format to be used as grouping clause in SQL.
public
static db_datetime_format(string $time_interval, string $table_name[, string $date_column_name = 'date_created' ]) : mixed
Parameters
- $time_interval : string
-
Time interval.
- $table_name : string
-
Name of the db table relevant for the date constraint.
- $date_column_name : string = 'date_created'
-
Name of the date table column.
Return values
mixed —default_after()
Returns default 'after' parameter for the reports.
public
static default_after() : DateTime
Return values
DateTime —default_before()
Returns default 'before' parameter for the reports.
public
static default_before() : DateTime
Return values
DateTime —expected_intervals_on_page()
Returns expected number of items on the page in case of date ordering.
public
static expected_intervals_on_page(int $expected_interval_count, int $items_per_page, int $page_no) : float|int
Parameters
- $expected_interval_count : int
-
Expected number of intervals in total.
- $items_per_page : int
-
Number of items per page.
- $page_no : int
-
Page number.
Return values
float|int —get_timeframe_dates()
Get dates from a timeframe string.
public
static get_timeframe_dates(int $timeframe[, DateTime|null $current_date = null ]) : array<string|int, mixed>
Parameters
- $timeframe : int
-
Timeframe to use. One of: last_week|last_month|last_quarter|last_6_months|last_year.
- $current_date : DateTime|null = null
-
DateTime of current date to compare.
Return values
array<string|int, mixed> —intervals_between()
Calculates number of time intervals between two dates, closed interval on both sides.
public
static intervals_between(DateTime $start_datetime, DateTime $end_datetime, string $interval) : int
Parameters
- $start_datetime : DateTime
-
Start date & time.
- $end_datetime : DateTime
-
End date & time.
- $interval : string
-
Time interval increment, e.g. hour, day, week.
Return values
int —intervals_missing()
Returns true if there are any intervals that need to be filled in the response.
public
static intervals_missing(int $expected_interval_count, int $db_records, int $items_per_page, int $page_no, string $order, string $order_by, int $intervals_count) : bool
Parameters
- $expected_interval_count : int
-
Expected number of intervals in total.
- $db_records : int
-
Total number of records for given period in the database.
- $items_per_page : int
-
Number of items per page.
- $page_no : int
-
Page number.
- $order : string
-
asc or desc.
- $order_by : string
-
Column by which the result will be sorted.
- $intervals_count : int
-
Number of records for given (possibly shortened) time interval.
Return values
bool —iterate()
Returns beginning of next time interval for provided DateTime.
public
static iterate(DateTime $datetime, string $time_interval[, bool $reversed = false ]) : DateTime
E.g. for current DateTime, beginning of next day, week, quarter, etc.
Parameters
- $datetime : DateTime
-
Date and time.
- $time_interval : string
-
Time interval, e.g. week, day, hour.
- $reversed : bool = false
-
Going backwards in time instead of forward.
Return values
DateTime —next_day_start()
Returns a new DateTime object representing the next day start, or previous day end if reversed.
public
static next_day_start(DateTime $datetime[, bool $reversed = false ]) : DateTime
Parameters
- $datetime : DateTime
-
Date and time.
- $reversed : bool = false
-
Going backwards in time instead of forward.
Return values
DateTime —next_hour_start()
Returns a new DateTime object representing the next hour start/previous hour end if reversed.
public
static next_hour_start(DateTime $datetime[, bool $reversed = false ]) : DateTime
Parameters
- $datetime : DateTime
-
Date and time.
- $reversed : bool = false
-
Going backwards in time instead of forward.
Return values
DateTime —next_month_start()
Returns a new DateTime object representing the next month start, or previous month end if reversed.
public
static next_month_start(DateTime $datetime[, bool $reversed = false ]) : DateTime
Parameters
- $datetime : DateTime
-
Date and time.
- $reversed : bool = false
-
Going backwards in time instead of forward.
Return values
DateTime —next_quarter_start()
Returns a new DateTime object representing the next quarter start, or previous quarter end if reversed.
public
static next_quarter_start(DateTime $datetime[, bool $reversed = false ]) : DateTime
Parameters
- $datetime : DateTime
-
Date and time.
- $reversed : bool = false
-
Going backwards in time instead of forward.
Return values
DateTime —next_week_start()
Returns DateTime object representing the next week start, or previous week end if reversed.
public
static next_week_start(DateTime $datetime[, bool $reversed = false ]) : DateTime
The next week start is the first day of the next week at 00:00:00. The previous week end is the last day of the previous week at 23:59:59. The start day is determined by the "start_of_week" wp_option.
Parameters
- $datetime : DateTime
-
Date and time.
- $reversed : bool = false
-
Going backwards in time instead of forward.
Return values
DateTime —next_year_start()
Return a new DateTime object representing the next year start, or previous year end if reversed.
public
static next_year_start(DateTime $datetime[, bool $reversed = false ]) : DateTime
Parameters
- $datetime : DateTime
-
Date and time.
- $reversed : bool = false
-
Going backwards in time instead of forward.
Return values
DateTime —normalize_between_params()
Normalize "*_between" parameters to "*_min" and "*_max" for numeric values and "*_after" and "*_before" for date values.
public
static normalize_between_params(array<string|int, mixed> $request, string|array<string|int, mixed> $param_names, bool $is_date) : array<string|int, mixed>
Parameters
- $request : array<string|int, mixed>
-
Query params from REST API request.
- $param_names : string|array<string|int, mixed>
-
One or more param names to handle. Should not include "_between" suffix.
- $is_date : bool
-
Boolean if the param is date is related.
Return values
array<string|int, mixed> — Normalized query values.quarter()
Returns quarter for the DateTime.
public
static quarter(DateTime $datetime) : int|null
Parameters
- $datetime : DateTime
-
Local date & time.
Return values
int|null —rest_validate_between_date_arg()
Validate a "*_between" range argument (an array with 2 date items).
public
static rest_validate_between_date_arg(mixed $value, WP_REST_Request $request, string $param) : WP_Error|bool
Parameters
- $value : mixed
-
Parameter value.
- $request : WP_REST_Request
-
REST Request.
- $param : string
-
Parameter name.
Return values
WP_Error|bool —rest_validate_between_numeric_arg()
Validate a "*_between" range argument (an array with 2 numeric items).
public
static rest_validate_between_numeric_arg(mixed $value, WP_REST_Request $request, string $param) : WP_Error|bool
Parameters
- $value : mixed
-
Parameter value.
- $request : WP_REST_Request
-
REST Request.
- $param : string
-
Parameter name.
Return values
WP_Error|bool —simple_week_number()
Returns simple week number for the DateTime, for week starting on $first_day_of_week.
public
static simple_week_number(DateTime $datetime, int $first_day_of_week) : int
The first week of the year is considered to be the week containing January 1. The second week starts on the next $first_day_of_week.
Parameters
- $datetime : DateTime
-
Local date for which the week number is to be calculated.
- $first_day_of_week : int
-
0 for Sunday to 6 for Saturday.
Return values
int —time_interval_id()
Returns time interval id for the DateTime.
public
static time_interval_id(string $time_interval, DateTime $datetime) : string
Parameters
- $time_interval : string
-
Time interval type (week, day, etc).
- $datetime : DateTime
-
Date & time.
Return values
string —week_number()
Returns ISO 8601 week number for the DateTime, if week starts on Monday, otherwise returns simple week number.
public
static week_number(DateTime $datetime, int $first_day_of_week) : int
Parameters
- $datetime : DateTime
-
Local date for which the week number is to be calculated.
- $first_day_of_week : int
-
0 for Sunday to 6 for Saturday.