date_isodate_set()

The date_isodate_set() function sets the date of a DateTime object using the ISO 8601 week-based calendar — that is, by year, week number, and day of the week instead of by month and day. It is the procedural alias of the DateTime::setISODate() method, so both do exactly the same thing.

This page covers the function syntax, how the ISO week calendar differs from the ordinary calendar, runnable examples, and the common gotchas.

Syntax

The date_isodate_set() function has the following syntax:

The PHP date_isodate_set() function syntax

date_isodate_set(DateTime $object, int $year, int $week, int $dayOfWeek = 1): DateTime

where:

• $object — the DateTime object to modify (it is changed in place).
• $year — the ISO year.
• $week — the ISO week number, 1–53.
• $dayOfWeek — the day of the week, 1 for Monday through 7 for Sunday (optional, defaults to 1).

The function returns the same DateTime object, so calls can be chained. The equivalent object-oriented call is:

$date->setISODate($year, $week, $dayOfWeek);

Why use ISO week dates

Unlike the ordinary calendar, ISO 8601 numbers each week of the year and identifies a date by (year, week, weekday). This is handy for business reporting, scheduling, and any system that thinks in weeks rather than months.

Two rules are worth remembering:

• Week 1 is the week containing the year's first Thursday — equivalently, the week containing January 4th. Because of this, the first days of January can belong to the previous ISO year, and the last days of December can belong to the next one.
• Out-of-range values overflow rather than throwing an error. Asking for week 53 or day 7 of a week that doesn't exist simply rolls the date forward into the next week or year. For example, date_isodate_set($d, 2022, 52, 7) lands on 2023-01-01, because the 52nd week of 2022 ends on Sunday, January 1st, 2023.

Note: date_isodate_set() only changes the date part. The time of day stays whatever the DateTime already had (the current time for a freshly created object).

Examples

Basic usage

Set a date to the 3rd day (Wednesday) of the 10th ISO week of 2023:

The function changes $date in place. We start from a fixed time so the output is the same every run; only the date portion is replaced.

Week numbers can cross the year boundary

Asking for the last day of the last week of 2022 lands you in January 2023 — that's the ISO calendar at work, not a bug:

The 52nd week of 2022 ends on Sunday, January 1st, 2023, so that is the date returned.

Object-oriented equivalent

DateTime::setISODate() does the same job and returns the object, which lets you chain a format() call directly:

This sets the date to the 1st day (Monday) of the 24th week of 2023.

Related functions

• date_create() — create a DateTime object to pass in.
• date_format() — format the resulting date for display.

Conclusion

date_isodate_set() sets a DateTime to a specific (year, week, weekday) using the ISO 8601 week calendar. Remember that ISO week 1 contains the year's first Thursday, that week and day values overflow into the next week or year rather than erroring, and that only the date — not the time — is changed.

Practice