Submit a Pull Request Report a Bug

DatePeriod 类

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

简介

DatePeriod 类表示一个时间周期。

时间周期内允许对一组日期和时间进行迭代，在指定的时间间隔内定期重复。

类摘要

class DatePeriod implements IteratorAggregate {

/* 常量 */

public const int EXCLUDE_START_DATE;

public const int INCLUDE_END_DATE;

/* 属性 */

public readonly ?DateTimeInterface $start;

public readonly ?DateTimeInterface $current;

public readonly ?DateTimeInterface $end;

public readonly ?DateInterval $interval;

public readonly int $recurrences;

public readonly bool $include_start_date;

public readonly bool $include_end_date;

/* 方法 */

public __construct(
    DateTimeInterface $start,
    DateInterval $interval,
    int $recurrences,
    int $options = 0
)

public __construct(
    DateTimeInterface $start,
    DateInterval $interval,
    DateTimeInterface $end,
    int $options = 0
)

public __construct(string $isostr, int $options = 0)

public static createFromISO8601String(string $specification, int $options = 0): static

public getDateInterval(): DateInterval

public getEndDate(): ?DateTimeInterface

public getRecurrences(): ?int

public getStartDate(): DateTimeInterface

}

预定义常量

DatePeriod::EXCLUDE_START_DATE: 在 DatePeriod::__construct() 构造函数中使用，排除开始时间。
DatePeriod::INCLUDE_END_DATE: 在 DatePeriod::__construct() 构造函数中使用，包含结束时间。

属性

recurrences

迭代器返回的最小实例数。

如果在 DatePeriod 实例的构造函数中显式通过 recurrences 参数传递重复次数，然后此属性将包含该值，如果开始时间没有通过 DatePeriod::EXCLUDE_START_DATE 禁用，则该属性加 1，如果结束时间已经通过 DatePeriod::INCLUDE_END_DATE 启用，则该属性加 1。

如果没有显式传递重复次数，则此属性包含返回实例的最小数量。这将是 0，如果开始时间没有通过 DatePeriod::EXCLUDE_START_DATE 禁用，则该属性加 1，如果结束时间已经通过 DatePeriod::INCLUDE_END_DATE 启用，则该属性加 1。

<?php
$start = new DateTime('2018-12-31 00:00:00');
$end   = new DateTime('2021-12-31 00:00:00');
$interval = new DateInterval('P1M');
$recurrences = 5;

// 通过构造函数显式设置重复次数
$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
echo $period->recurrences, "\n";

$period = new DatePeriod($start, $interval, $recurrences);
echo $period->recurrences, "\n";

$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
echo $period->recurrences, "\n";

// 构造函数中没有设置重复次数
$period = new DatePeriod($start, $interval, $end);
echo $period->recurrences, "\n";

$period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
echo $period->recurrences, "\n";
?>

以上示例会输出：

5
6
7
1
0

参见：DatePeriod::getRecurrences()。

include_end_date

在循环过程中，是否包含结束时间。

include_start_date

在循环过程中，是否包含开始时间。

start

时间周期的开始时间。

current

表示在时间周期内迭代的时候，当前的时间。

end

时间周期的结束时间。

interval

ISO 8601 格式的间隔。

更新日志

版本	说明
8.2.0	新增 `DatePeriod::INCLUDE_END_DATE` 常量和 include_end_date 属性。
8.0.0	现在 DatePeriod 实现了（implement） IteratorAggregate。之前实现的是 Traversable。

DatePeriod::__construct — Creates a new DatePeriod object
DatePeriod::createFromISO8601String — Creates a new DatePeriod object from an ISO8601 string
DatePeriod::getDateInterval — Gets the interval
DatePeriod::getEndDate — Gets the end date
DatePeriod::getRecurrences — Gets the number of recurrences
DatePeriod::getStartDate — Gets the start date

add a note

User Contributed Notes 11 notes

down

144

josh dot love at verizon dot net ¶

11 years ago


Just an example to include the end date using the DateTime method 'modify'

<?php

$begin = new DateTime( '2012-08-01' );
$end = new DateTime( '2012-08-31' );
$end = $end->modify( '+1 day' ); 

$interval = new DateInterval('P1D');
$daterange = new DatePeriod($begin, $interval ,$end);

foreach($daterange as $date){
    echo $date->format("Ymd") . "<br>";
}
?>

down

logos-php at kith dot org ¶

11 years ago


Thanks much to those of you who supplied sample code; that helps a lot.

I wanted to mention another thing that helped me: when you do that foreach ( $period as $dt ), the $dt values are DateTime objects.

That may be obvious to those of you with more experience, but I wasn't sure until I looked it up on Stack Overflow. So I figured it was worth posting here to help others like me who might've been confused or uncertain.

down

mike at saymikeo dot com ¶

6 years ago


Calculating business days can be cumbersome. Here is an iterator for handling business days. Usage examples below for adding # of business days and calculating how many business days between two dates.

Here is the iterator class
https://gist.github.com/styks1987/29dd0f6a68e3b07ba70fec18f732eb86

Usage

Counting # of Business Days between two dates

<?php
function countBusinessDays($start, $stop)
    {
        if($start > $stop){
            $tmpStart = clone $start;
            $start = clone $stop;
            $stop = clone $tmpStart;
        }

        // Adding the time to the end date will include it
        $period = new \DatePeriod($start->setTime(0,0,0), new \DateInterval('P1D'), $stop->setTime(23,59,59), \DatePeriod::EXCLUDE_START_DATE);
        $periodIterator = new BusinessDayPeriodIterator($period);
        $businessDays = 0;
        while($periodIterator->valid()){
            // If we run into a weekend, don't count it
            if(!$periodIterator->isWeekend()){
                $businessDays++;
            }
            $periodIterator->next();
        }

        return $businessDays;
    }
?>

Add # of business days

<?php
function addBusinessDays(\DateTime $startDateTime, $daysToAdd)
    {
        $endDateTime = clone $startDateTime;
        $endDateTime->add(new \DateInterval('P' . $daysToAdd . 'D'))->setTime(23,59,59);
        $period = new \DatePeriod($startDateTime, new \DateInterval('P1D'), $endDateTime);

        $periodIterator = new BusinessDayPeriodIterator($period);
        $adjustedEndingDate = clone $startDateTime;
        while($periodIterator->valid()){
            $adjustedEndingDate = $periodIterator->current();
            // If we run into a weekend, extend our days
            if($periodIterator->isWeekend()){
                $periodIterator->extend();
            }
            $periodIterator->next();
        }

        return $adjustedEndingDate;
    }
?>

down

mail at pascalhofmann dot de ¶

7 years ago


When looping over a DatePeriod object, the returned objects always implement DateTimeInterface. The exact type returned depends on how the DatePeriod was created. If $start was a DateTimeImmutable, the objects returned will be of type DateTimeImmutable. If a DateTime object was used, the objects returned will be of type DateTime.

down

php at karlsruler dot de ¶

8 years ago


The iterator seems to check the time as well, it excludes the end element if its time is 00:00:00. So the slightly safer version (to compare it against joshs suggestion) is to use $date->setTime(23, 59, 59) instead of $date->modify("+1 day").

down

jkaatz at gmx dot de ¶

14 years ago


Nice example from PHP Spring Conference (thanks to Johannes Schlüter and David Zülke)

<?php
$begin = new DateTime( '2007-12-31' );
$end = new DateTime( '2009-12-31 23:59:59' );

$interval = DateInterval::createFromDateString('last thursday of next month');
$period = new DatePeriod($begin, $interval, $end, DatePeriod::EXCLUDE_START_DATE);

foreach ( $period as $dt )
  echo $dt->format( "l Y-m-d H:i:s\n" );
?>

DateInterval specs could be found at http://en.wikipedia.org/wiki/ISO_8601#Time_intervals

down

patrick at adrichem dot nu ¶

10 years ago


DatePeriod is not compatible with negative intervals.

To do so you can simply use DateInterval and loop through it yourself like this: (not start should be ahead of end if you use a negative interval

    class DateRange extends ArrayIterator
    {

        protected $oDate = null;
        protected $oStartDate = null;
        protected $oEndDate = null;
        protected $oInterval = null;

        public function __construct( DateTime $oStartDate, DateTime $oEndDate, DateInterval $oInterval = null )
        {
            $this->oStartDate = $oStartDate;
            $this->oDate = clone $oStartDate;
            $this->oEndDate = $oEndDate;
            $this->oInterval = $oInterval;
        }

        public function next()
        {
            $this->oDate->add($this->oInterval);
            return $this->oDate;
        }

        public function current()
        {
            return $this->oDate;
        }

        public function valid()
        {
            if ($this->oStartDate > $this->oEndDate)
            {
                return $this->oDate >= $this->oEndDate;
            }
            return $this->oDate <= $this->oEndDate;
        }

    }

$oRange = new DateRange(new DateTime("2013-10-01"), new DateTime("2013-01-01"), DateInterval::createFromDateString("-1 month") );
    foreach ($oRange as $oDate)
    {
        echo $oDate->format("Y-m-d") . "<br />";
    }

down

Memori ¶

13 years ago


If you want to include the end-date, add one day to it:

<?php
$startDate = new DateTime();
$endDate = new DateTime();

$startDateInt = new DateInterval( "P1Y" );
$endDateInt = new DateInterval( "P1D" );

$startDate->sub( $startDateInt );
$endDate->add( $endDateInt );

$periodInt = new DateInterval( "P1M" );
$period = new DatePeriod( $startDate, $periodInt, $endDate );

// At februari 2011:
// $period = (8,9,10,11,12,1,2)
?>

down

Joey ¶

4 years ago


This class isn't always intuitive. End is exclusive. All you need to do to include it is to add a second (the smallest amount).

Microseconds are ignored.

php -r '
/***/$p1d = new DateInterval("P1D");
/***/$b = (new DateTime())->setTime(0, 0, 0, 0);
/***/$a = (clone $b)->sub($p1d);

/***/$f = function(DateTime $b)use($a, $p1d):void {
/***//***/$p = new DatePeriod($a, $p1d, $b);
/***//***/$i = iterator_to_array($p);
/***//***/print_r([$i[0], end($i), $a, $b]);
/***/};

/***/$f($b);
/***/$f($b->setTime(0, 0, 0, 1));
/***/$f($b->setTime(0, 0, 1, 0));
'

It is a sign of the end times.

down

johnzenith71(at)gmail.com ¶

5 years ago


An extra piece of information on how to use the (modify method) to easily get date ranges:

<?php
$subscription_start_date = new DateTime( 'now' );

// Modify the $subscription_start_date date value to required date range, 
// this could be in days or months depending on how your application is designed

// Days
$subscription_expiration = $subscription_start_date->modify( '+60 days' ); 
echo $subscription_expiration->format( 'Y-m-d' ) . "\n";

// Months
$subscription_expiration = $subscription_start_date->modify( '+2 Months' );
echo $subscription_expiration->format( 'Y-m-d' ) . "\n";

// Or even in years
$subscription_expiration = $subscription_start_date->modify( '+2 years' );
echo $subscription_expiration->format( 'Y-m-d' ) . "\n";
?>

down

-1

joseph dot cardwell at jbcwebservices dot com ¶

5 years ago


As someone noted, at least in 7.2, dates with time 0 are excluded from the start and end. 

To get a regular span of dates I ended up with:

$dates = new DatePeriod(
    ( new DateTime($date_start) )->setTime(0,0,1),
    new DateInterval('P1D'),
    ( new DateTime($date_end) )->setTime(0,0,1)
);

add a note

DatePeriod 类

简介

类摘要

预定义常量

属性

更新日志

目录

User Contributed Notes 11 notes