날짜와 시간

날짜와 시간 (Date/Time)

PHP의 날짜·시간 관련 클래스들을 한곳에 모아 놓은 레퍼런스 페이지예요. DateTimeImmutable과 관련 클래스들이 어떻게 날짜와 시간 정보를 표현하고, 다루고, 형식화하는지 정리되어 있습니다.

출처: PHP: Date/Time - Manual

본문

DateTimeImmutable과 관련 클래스들은 날짜·시간 정보를 표현할 수 있게 해 줍니다. 객체는 날짜·시간 정보를 문자열로 넘겨 만들 수도 있고, 시스템의 현재 시간으로부터 만들 수도 있어요.

시간대(timezone)와 DST(일광 절약 시간) 전환 처리를 포함해, 이 정보를 수정하고 형식화하는 다양한 메서드도 함께 제공됩니다.

PHP의 날짜·시간 기능은 ISO 8601 달력을 구현합니다. ISO 8601 달력은 역산 그레고리력(proleptic Gregorian calendar)으로, 그레고리력이 실제로 시행되기 이전 시점에도 현재의 윤년 규칙을 그대로 적용하는 달력이에요. 또한 기원전 1년(-1)과 서기 1년(1) 사이에 0년(년 0)도 포함합니다. 윤초(leap second)는 지원하지 않아요.

날짜와 시간 정보는 내부적으로 64비트 숫자로 저장되기 때문에, 상상 가능한 모든 날짜(음수 연도 포함)를 지원합니다. 약 과거 2920억 년에서 미래 2920억 년까지의 범위를 다루죠.

참고: 이 섹션에서 언급하는 시간대의 목록은 지원되는 시간대 목록(List of Supported Timezones)에서 확인할 수 있어요.

주요 클래스

날짜·시간 관련 API는 클래스 중심으로 구성되어 있어요. 대표적인 것들부터 살펴볼게요.

DateTime — 변경 가능한(mutable) 날짜·시간 객체를 나타내는 클래스
DateTimeImmutable — 변경 불가능한(immutable) 날짜·시간 객체를 나타내는 클래스
DateTimeInterface — 두 클래스가 공통으로 따르는 인터페이스
DateTimeZone — 시간대(timezone)를 나타내는 클래스
DateInterval — 두 날짜 사이의 간격을 나타내는 클래스
DatePeriod — 날짜의 기간(반복 구간)을 나타내는 클래스

각 클래스가 제공하는 메서드와 설명은 다음과 같아요.

DateTime

메서드	설명
`DateTime::add`	일·월·년·시·분·초를 더한 양만큼 수정한 DateTime 객체를 반환
`DateTime::__construct`	새 DateTime 객체 생성
`DateTime::createFromFormat`	지정한 형식에 따라 시간 문자열을 파싱
`DateTime::createFromImmutable`	주어진 DateTimeImmutable 객체를 감싼 새 DateTime 인스턴스 반환
`DateTime::createFromInterface`	주어진 DateTimeInterface 객체를 감싼 새 DateTime 객체 반환
`DateTime::createFromTimestamp`	Unix 타임스탬프로부터 인스턴스 생성
`DateTime::getLastErrors`	`DateTimeImmutable::getLastErrors`의 별칭
`DateTime::modify`	타임스탬프를 변경
`DateTime::__set_state`	`__set_state` 핸들러
`DateTime::setDate`	날짜를 설정
`DateTime::setISODate`	ISO 날짜를 설정
`DateTime::setMicrosecond`	시간의 마이크로초 부분을 설정
`DateTime::setTime`	시간을 설정
`DateTime::setTimestamp`	Unix 타임스탬프를 기준으로 날짜와 시간을 설정
`DateTime::setTimezone`	DateTime 객체의 시간대를 설정
`DateTime::sub`	일·월·년·시·분·초를 뺀 양만큼 수정
`DateTime::__serialize`	DateTime 직렬화
`DateTime::__unserialize`	DateTime 역직렬화
`DateTime::__wakeup`	`__wakeup` 핸들러

DateTimeImmutable

메서드	설명
`DateTimeImmutable::add`	일·월·년·시·분·초를 더한 새 객체 반환
`DateTimeImmutable::__construct`	새 DateTimeImmutable 객체 생성
`DateTimeImmutable::createFromFormat`	지정한 형식에 따라 시간 문자열을 파싱
`DateTimeImmutable::createFromInterface`	주어진 DateTimeInterface 객체를 감싼 새 DateTimeImmutable 객체 반환
`DateTimeImmutable::createFromMutable`	주어진 DateTime 객체를 감싼 새 DateTimeImmutable 인스턴스 반환
`DateTimeImmutable::createFromTimestamp`	Unix 타임스탬프로부터 인스턴스 생성
`DateTimeImmutable::getLastErrors`	경고와 오류를 반환
`DateTimeImmutable::modify`	수정된 타임스탬프를 가진 새 객체 생성
`DateTimeImmutable::__set_state`	`__set_state` 핸들러
`DateTimeImmutable::setDate`	날짜 설정
`DateTimeImmutable::setISODate`	ISO 날짜 설정
`DateTimeImmutable::setMicrosecond`	시간의 마이크로초 부분 설정
`DateTimeImmutable::setTime`	시간 설정
`DateTimeImmutable::setTimestamp`	Unix 타임스탬프를 기준으로 날짜와 시간 설정
`DateTimeImmutable::setTimezone`	시간대 설정
`DateTimeImmutable::sub`	일·월·년·시·분·초를 뺀 양만큼 수정

DateTimeInterface

메서드	설명
`DateTimeInterface::diff`	두 DateTime 객체 사이의 차이를 반환
`DateTimeInterface::format`	주어진 형식에 따라 날짜를 형식화해 반환
`DateTimeInterface::getMicrosecond`	Unix 타임스탬프의 마이크로초 부분을 가져옴
`DateTimeInterface::getOffset`	시간대 오프셋을 반환
`DateTimeInterface::getTimestamp`	Unix 타임스탬프를 가져옴
`DateTimeInterface::getTimezone`	주어진 DateTime에 상대적인 시간대 반환

DateTimeZone

메서드	설명
`DateTimeZone::__construct`	새 DateTimeZone 객체 생성
`DateTimeZone::getLocation`	시간대의 위치 정보 반환
`DateTimeZone::getName`	시간대의 이름 반환
`DateTimeZone::getOffset`	GMT로부터의 시간대 오프셋 반환
`DateTimeZone::getTransitions`	시간대의 모든 전환 반환
`DateTimeZone::listAbbreviations`	dst, offset, 시간대 이름을 담은 연관 배열 반환
`DateTimeZone::listIdentifiers`	정의된 모든 시간대 식별자를 담은 숫자 인덱스 배열 반환

DateInterval

메서드	설명
`DateInterval::__construct`	새 DateInterval 객체 생성
`DateInterval::createFromDateString`	문자열의 상대적 부분으로부터 DateInterval 생성
`DateInterval::format`	간격을 형식화

DatePeriod

메서드	설명
`DatePeriod::__construct`	새 DatePeriod 객체 생성
`DatePeriod::createFromISO8601String`	ISO8601 문자열로부터 새 DatePeriod 객체 생성
`DatePeriod::getDateInterval`	간격을 가져옴
`DatePeriod::getEndDate`	종료 날짜를 가져옴
`DatePeriod::getRecurrences`	반복 횟수를 가져옴
`DatePeriod::getStartDate`	시작 날짜를 가져옴

날짜/시간 함수 (Date/Time Functions)

절차적(procedural) 함수들도 있어요. 그중 상당수는 위 클래스 메서드의 별칭(alias)이에요.

함수	설명
`checkdate`	그레고리력 날짜 검증
`date`	Unix 타임스탬프 형식화
`date_add`	`DateTime::add`의 별칭
`date_create`	새 DateTime 객체 생성
`date_create_from_format`	`DateTime::createFromFormat`의 별칭
`date_create_immutable`	새 DateTimeImmutable 객체 생성
`date_create_immutable_from_format`	`DateTimeImmutable::createFromFormat`의 별칭
`date_date_set`	`DateTime::setDate`의 별칭
`date_default_timezone_get`	스크립트의 모든 날짜·시간 함수에서 사용하는 기본 시간대 가져옴
`date_default_timezone_set`	스크립트의 모든 날짜·시간 함수에서 사용하는 기본 시간대 설정
`date_diff`	`DateTime::diff`의 별칭
`date_format`	`DateTime::format`의 별칭
`date_get_last_errors`	`DateTimeImmutable::getLastErrors`의 별칭
`date_interval_create_from_date_string`	`DateInterval::createFromDateString`의 별칭
`date_interval_format`	`DateInterval::format`의 별칭
`date_isodate_set`	`DateTime::setISODate`의 별칭
`date_modify`	`DateTime::modify`의 별칭
`date_offset_get`	`DateTime::getOffset`의 별칭
`date_parse`	주어진 날짜·시간에 대한 상세 정보를 담은 연관 배열 반환
`date_parse_from_format`	지정한 형식에 따라 형식화된 주어진 날짜 정보 가져옴
`date_sub`	`DateTime::sub`의 별칭
`date_sun_info`	일출·일몰 및 박명(황혼) 시작·종료 정보를 담은 배열 반환
`date_sunrise`	주어진 날짜와 위치의 일출 시각 반환
`date_sunset`	주어진 날짜와 위치의 일몰 시각 반환
`date_time_set`	`DateTime::setTime`의 별칭
`date_timestamp_get`	`DateTime::getTimestamp`의 별칭
`date_timestamp_set`	`DateTime::setTimestamp`의 별칭
`date_timezone_get`	`DateTime::getTimezone`의 별칭
`date_timezone_set`	`DateTime::setTimezone`의 별칭
`getdate`	날짜·시간 정보 가져옴
`gettimeofday`	현재 시간 가져옴
`gmdate`	GMT/UTC 날짜·시간 형식화
`gmmktime`	GMT 날짜에 대한 Unix 타임스탬프 가져옴
`gmstrftime`	로케일 설정에 따라 GMT/UTC 시간·날짜 형식화
`idate`	로컬 시간·날짜 부분을 정수로 형식화
`localtime`	로컬 시간 가져옴
`microtime`	마이크로초가 포함된 현재 Unix 타임스탬프 반환
`mktime`	날짜에 대한 Unix 타임스탬프 가져옴
`strftime`	로케일 설정에 따라 로컬 시간·날짜 형식화
`strptime`	`strftime`으로 생성된 시간·날짜 파싱
`strtotime`	거의 모든 영어 문장 형태의 날짜·시간 설명을 Unix 타임스탬프로 파싱
`time`	현재 Unix 타임스탬프 반환
`timezone_abbreviations_list`	`DateTimeZone::listAbbreviations`의 별칭
`timezone_identifiers_list`	`DateTimeZone::listIdentifiers`의 별칭
`timezone_location_get`	`DateTimeZone::getLocation`의 별칭
`timezone_name_from_abbr`	약어와 UTC 오프셋으로 추정해 시간대 이름 반환
`timezone_name_get`	`DateTimeZone::getName`의 별칭
`timezone_offset_get`	`DateTimeZone::getOffset`의 별칭
`timezone_open`	`DateTimeZone::__construct`의 별칭
`timezone_transitions_get`	`DateTimeZone::getTransitions`의 별칭
`timezone_version_get`	timezonedb의 버전 가져옴

날짜/시간 오류와 예외 (Date/Time Errors and Exceptions)

PHP 8.3부터 날짜·시간 관련 오류가 세분화된 예외 클래스로 정리됐어요.

DateError — 날짜·시간 작업에서 발생하는 일반적인 오류
DateObjectError — 날짜·시간 객체를 대상으로 하는 작업의 오류
DateRangeError — 날짜·시간 값이 허용 범위를 벗어났을 때의 오류
DateException — 날짜·시간 작업에서 발생하는 예외
DateInvalidOperationException — 잘못된 작업을 수행하려 할 때의 예외
DateInvalidTimeZoneException — 잘못된 시간대를 다룰 때의 예외
DateMalformedIntervalStringException — 잘못된 형태의 간격 문자열을 다룰 때의 예외
DateMalformedPeriodStringException — 잘못된 형태의 기간 문자열을 다룰 때의 예외
DateMalformedStringException — 잘못된 형태의 날짜 문자열을 다룰 때의 예외

참고로 이 페이지가 다루는 구체적인 형식들과 지원되는 시간대 역시 PHP 매뉴얼의 관련 섹션(지원되는 날짜와 시간 형식, 지원되는 시간대 목록)에서 확인할 수 있어요.

날짜와 시간