Date_Math_ClassA.php

This class has 67 date related functions. Dates can be outside the Linux date() range of 1970- 2039.

Date range for this class is from the year 0032 A.D. to 9999 A.D.

USE:

require_once <path / Date_Math_ClassA.php>;

$dt = new date_math_class;

Documentation and examples are found in files

Date_Math_Class_TestA.php and

Date_Math_ClassA.php.pseudo.

Copyright (C) 2014 Software Installation Services, Inc.

Author: Bob Wedwick, Phoenix, AZ 602-449-8552 bob at wedwick dot com.

This program is free software: you can redistribute it or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License or any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See http://www.gnu.org/licenses/licenses.en.html for a copy of the GNU General Public License.

This class operates by default on dates in string y-m-d format (y= year, m= month, d=day) as used in mySql; however you may opt for input and output formats to be different, and you can change the default output date format.

Input dates as function parameters may be formatted as strings: y-m-d, y/m/d, y.m.d, m-d-y, m/d/y, m.d.y

where 'y' is 4 digits (leading zeros for years before 1000), 'm' and 'd' may be 1 or 2 digits.

Example: AddDays(2, '2013-04-15', 'y/m/d') means 2 days are added to April 15, 2014 and output

is formatted as y/m/d.

Also supported is ymd format as a string or integer for input which must be

 exactly 8 digits: 4-digit year and 2-digit month and 2-digit day.

Output date formats supported include those above as well as d-m-y by including an optional string parameter in the function call. Also included are dmy, mdy and ymd with exactly 8 digits. Examples: 'm/d/y' 'ymd'

Note the 'd-m-y' format is not supported in the input date formats.

Null or blank output date formats revert to the default format as do any other formats that are

 not recognized. Thus null, blank, or unrecognized formats do not generate errors.

Formatting strings are not case sensitive.

Input and output formats do not have to be the same. Thus functions can be

used to convert date formats from one to another.

For functions expecting an integer value as an input parameter, it may be

either an integer or string with or without + or - signs that evaluates to an integer.

When the public variable $useTime = false (the default),

time blocks are not considered for calculations and are removed from the output.

When the public variable $useTime = true,

The input date string may have an optional time component which is preserved and returned.

Time blocks are used in many date comparisons where time may make a difference.

Any dates submitted without a valid time block are set to 00:00 (midnight).

Null and blank time blocks are set to the current Linux local time.

Date comparisons using time blocks operate on 24 hours (86400 seconds) to make one day.

Thus 2012-07-08 09:00:00 versus 2012-07-09 08:59:59 is still the same day

likewise 2012-07-08 09:00 versus 2012-07-07 09:01.

When time blocks are not used, these entries result in different days.

Public variables for months, days of the week and 1st day of the weekmake it easy to change languages.

You can change the abbreviations for month and day of the week in public variables.

When the public variable $exceptions = true, an error throws an exception instead of returning

to the calling script with 'false' result.

Otherwise functions return a boolean false (result === false) whenever invalid input is passed

and should be explicitly tested by using ===.

Some functions may return zero which is different from the boolean false.

Null and blank dates are valid for input in selected functions where replacing them with the

current date and time makes sense.

When internal date calculations result in a non-existent date, such as April 31, the result

is reduced to the last valid day of the month.

Refer to the PHP script Date_Math_Class_Test.php for examples of how these functions

can be used. If the test script is run via the console, the results of various functions are

echoed to the console.

This class was written such that the logical flow of each function is available in

pseudo code form in a text file Date_Math_Class.php.pseudo.

Naming convention: all functions begin with a capital letter;

all variables begin with $ and lower case first letter.

An inherant flaw exists with julian dates where years like 1700, 1800 and 1900 are not leap years

yet there is a PHP julian value for Feb 29 in those years. If you work with dates that span Feb 29

in a non-leap year, this date math class can render results that are off by one day.

Example: adding 2 days to 1900-02-28 (jd 2415091) renders an invalid result of

1900-03-01 (jd 2415093) since jd 2415092 is the non-existant date of 1900-02-29.

The depth count variable keeps track of how many internal function calls are active

and depth 1 serves to identify which function was called from the calling program.

 

Public functions included in this class are:

### Add Days - add (or subtract when negative) days to the given date.

function AddDays($days=0, $date=null, $fmt=null)

### Add Months - add (or subtract when negative) months to the given date.

function AddMonths($months=0, $date=null, $fmt=null)

### Add Weeks - add (or subtract when negative) weeks to the given date.

function AddWeeks($weeks=0, $date=null, $fmt=null)

### Add Years - add (or subtract when negative) years to the given date.

function AddYears($years=0, $date=null, $fmt=null)

### Age In Years - return the absolute age in years for one date versus another.

function AgeInYears($date1=null, $date2=null)

### Date Is Valid - return the valid date. Blank and null default to now.

function DateIsValid($date=null, $fmt=null, $which=1)

### Date To Julian - convert a date to integer julian days. Optional time block.

function DateToJulian($date=null)

### Day Month Year - return the date formatted as day month year like 30 Oct 2013.

function DayMonthYear($date=null)

### Day Of The Month - return the numeric day of the month.

function DayOfTheMonth($date=null)

### Day Of The Week - return the three-character short form for the day of the week for the given date.

function DayOfTheWeek($date=null)

### Day Of The Year - return the numeric day of the year for the given date. 1-365 or 366.

function DayOfTheYear($date=null)

### Day Of The Year To Date - convert the day of the year to a date in the given year.

function DayOfTheYearToDate($dayOfYear = 0, $year = null, $fmt=null)

### Difference In Days - return the difference between two dates in completed days based on Julian days.

function DifferenceInDays($date1=null, $date2=null)

### Difference In Weeks - return the difference in complete weeks for the dates given, not partial weeks.

function DifferenceInWeeks($date1=null, $date2=null)

### Difference In Years - return the difference between two dates in years, may be negative.

function DifferenceInYears($date1= null, $date2= null)

### Dow Month Day Year - return a date formatted as day-of-week, month, day, and year.

function DowMonthDayYear($date=null)

### End Of Next Month - return the end of next month.

function EndOfNextMonth($date=null, $fmt=null)

### End Of Next Week- return the end of next week.

function EndOfNextWeek($date=null, $fmt=null)

### End Of Next Year - return the end of next year.

function EndOfNextYear($date=null, $fmt=null)

### End Of Prior Month - return the end of the prior month.

function EndOfPriorMonth($date=null, $fmt=null)

### End Of Prior Week- return the end of the prior week.

function EndOfPriorWeek($date=null, $fmt=null)

### End Of Prior Year - return the end of the prior year.

function EndOfPriorYear($date=null, $fmt=null)

### End Of This Month - return the end of the month for the given date.

function EndOfThisMonth($date=null, $fmt=null)

### End Of This Week - return the end of the week for the given date.

function EndOfThisWeek($date=null, $fmt=null)

### End Of This Year - return the end of the year for the given date.

function EndOfThisYear($date=null, $fmt=null)

### First Of Given Month - return the next first of the month for the given month.

function FirstOfGivenMonth($mon=null, $date=null, $fmt=null)

### First Of Next Month - return the 1st of next month after the given date.

function FirstOfNextMonth($date=null, $fmt=null)

### First of Next Week - return the 1st of next week after the given date.

function FirstOfNextWeek($date=null, $fmt=null)

### First Of Next Year - return the 1st of next year after the given date.

function FirstOfNextYear($date=null, $fmt=null)

### First Of Prior Month - return the 1st of prior month from the given date.

function FirstOfPriorMonth($date=null, $fmt=null)

### First Of Prior Week- return the 1st of prior week from the given date.

function FirstOfPriorWeek($date=null, $fmt=null)

### First Of Prior Year - return the 1st of prior year from the given date.

function FirstOfPriorYear($date=null, $fmt=null)

### First Of This Month - return 1st of the month for the given date.

function FirstOfThisMonth($date=null, $fmt=null)

### First Of This Week - return 1st of the week for the given date.

function FirstOfThisWeek($date=null, $fmt=null)

### First Of This Year - return 1st of the year for the given date.

function FirstOfThisYear($date=null, $fmt=null)

### Get Last Error - return the last error message.

function GetLastError()

### Greater Date - return the greater of two dates ignoring any null or blank dates. At least one date must be provided.

function GreaterDate($date1=null, $date2=null, $fmt=null)

### Is A Date - return true when the given date looks like a date. Null and blank are not dates.

function IsADate($date=null)

### Is The First - true when the given date is the first of the month, zero when not, false when invalid date is sent.

function IsTheFirst($date=null)

### Julian To Date - convert an integer or integer string to a date string.

function JulianToDate($value=null, $fmt=null)

### Last Dow For A Month - return the last day of the week for the given date - for example: find the last Friday of a month.

function LastDowForAMonth($dayOfWeek, $date=null, $fmt=null)

### Lesser Date - return the lesser of two dates ignoring any null or blank dates. At least one date must be passed.

function LesserDate($date1=null, $date2=null, $fmt=null)

### Maximum Date - the maximum of two dates. Null and blank dates default to now.

function MaximumDate($date1=null, $date2=null, $fmt=null)

### Minimum Date - the lesser of two dates. Null and blank dates default to now.

function MinimumDate($date1=null, $date2=null, $fmt=null)

### Month Day Year - return a date formatted as 'month day, year' like Mar 3, 2005.

function MonthDayYear($date=null)

### Month Number - the integer month number for the named month.

function MonthNumber($mon=null)

### Month Str - return the 3-char string for the month of the given date.

function MonthStr($date=null)

### N Days Before End Of The Month - return N days before the end of the month for the given date.

function NDaysBeforeEndOfTheMonth($n=0, $date = null, $fmt= null)

### Next Day Of The Week - return the next date for a named day of the week when given date is not same as the day sent.

function NextDayOfTheWeek($dayOfWeek, $date=null, $fmt=null)

### Next First Of The Month - the next first of the month if the given date is not the 1st.

function NextFirstOfTheMonth($date=null, $fmt=null)

### Next First Of The Year - the next first of the year if the given date is not the 1st.

function NextFirstOfTheYear($date=null, $fmt=null)

### Next Nth Day Of The Month - the next Nth day of the month after the given date, e.g. 3rd Tuesday.

function NextNthDayOfTheMonth($n=1, $dayOfWeek, $date=null, $fmt=null)

### Next Nth Of The Month - advance as needed to the next Nth day of a month limited to 1-31.

function NextNthOfTheMonth($n=0, $date=null, $fmt=null)

### Nth Of The Month - return Nth day of the month for the given date limited to 1-31.

function NthOfTheMonth($n=0, $date=null, $fmt=null)

### Number Of Days In A Month - return a count of the number of days in a month.

function NumberOfDaysInAMonth($date=null)

### Numeric Day Of The Week - return the numeric day of the week 0-6 based on the public day array.

function NumericDayOfTheWeek($date=null)

### Numeric Month - return the numeric month (1-12) for the given date.

function NumericMonth($date = null)

### Numeric Year - return the numeric year for the given date.

function NumericYear($date = null)

### Prior Day Of The Week - return the date for the prior day of the week from the given date. Back up, if needed.

function PriorDayOfTheWeek($dayOfWeek, $date=null, $fmt=null)

### Subtract Days - subtract absolute number of days from the given date.

function SubtractDays($days=0, $date=null, $fmt=null)

### Subtract Months - subtract absolute number of months from the given date.

function SubtractMonths($months=0, $date=null, $fmt=null)

### Subtract Weeks - subtract absolute number of weeks from the given date.

function SubtractWeeks($weeks=0, $date=null, $fmt=null)

### Subtract Years - subtract absolute number of years from the given date.

function SubtractYears($years=0, $date=null, $fmt=null)

### Use Exceptions - opt to set exceptions on or off and return the state.

function UseExceptions($state=null)

### Use Time Blocks - opt to set using time blocks on or off and return the state.

function UseTimeBlocks($state=null)

### Week Number - return the week number (0-53) of the year, weeks begin on the first day in the day array.

function WeekNumber($date=null)

### Ymd - convert a date to an array of year, month, day from a date. Optional time block.

function Ymd($date=null)

### Ymd Array To Date - convert a YMD array to a date string.

function YmdArrayToDate($ymdArray=null, $fmt=null)

### Ymd String To Date - convert a string in the form of yyyymmdd to a date. Optional time block.

function YmdStringToDate($yyyymmdd=null, $fmt=null)