DatePeriod::__construct

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

DatePeriod::__construct — Cria um novo objeto DatePeriod

Descrição

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

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

Aviso

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

Esta variante do construtor foi descontinuada, use o método DatePeriod::createFromISO8601String().

Cria um objeto DatePeriod.

Objetos DatePeriod podem ser usados como um iterador para gerar um número de objetos DateTimeImmutable ou DateTime a partir de uma data inicial (start), um intervalo (interval), e uma data final (end) ou o número de recorrências (recurrences).

A classe do objeto retornado é equivalente à classe ancestral DateTimeImmutable ou DateTime do objeto do parâmetro start.

Parâmetros

start

A data inicial do período. Incluído por padrão no conjunto de resultados.

interval

A recorrência de intervalos entre os períodos.

recurrences

O número de recorrências. O número do resultado retornado é uma unidade a mais que isto, já que a data de início é incluída no conjunto de resultados por padrão. Deve ser maior que 0.

end

A data final do período.

isostr

Um sobconjunto da » ISO 8601 repeating interval specification.

Exemplos de algumas características de especificação de intervalos ISO 8601 que o PHP não suporta são:

zero ocorrências (R0/)
fusos horários diferentes de UTC (Z), como +02:00.

options

Um campo de bits que pode ser usado para controlar certos comportamentos com datas de início e fim.

Com DatePeriod::EXCLUDE_START_DATE você exclui a data inicial do conjunto de datas recorrentes dentro do período.

Com DatePeriod::INCLUDE_END_DATE você inclui a data final do conjunto de datas recorrentes dentro do período.

Erros/Exceções

Dispara uma exceção DateMalformedPeriodStringException quando o parâmetro isostr não pode ser interpretado como um período ISO 8601 válido. Antes do PHP 8.3, isto era uma Exception.

Registro de Alterações

Versão	Descrição
8.3.0	Agora dispara DateMalformedPeriodStringException em vez de Exception.
8.2.0	A constante `DatePeriod::INCLUDE_END_DATE` foi incluída.
7.2.19, 7.3.6, 7.4.0	O parâmetro `recurrences` agora deve ser maior que `0`.

Exemplos

Exemplo #1 Exemplos de DatePeriod

<?php
$inicio = new DateTime('2012-07-01');
$intervalo = new DateInterval('P7D');
$fim = new DateTime('2012-07-31');
$recorrencias = 4;
$iso = 'R4/2012-07-01T00:00:00Z/P7D';

// Todos estes períodos são equivalentes.
$periodo = new DatePeriod($inicio, $intervalo, $recorrencias);
$periodo = new DatePeriod($inicio, $intervalo, $fim);
$periodo = new DatePeriod($iso);

// Ao iterar sobre o objeto DatePeriod, todas as
// datas recorrentes dentro do período são exibidas.
foreach ($periodo as $data) {
    echo $data->format('Y-m-d')."\n";
}
?>

O exemplo acima produzirá:

Exemplo #2 Exemplo de DatePeriod com DatePeriod::EXCLUDE_START_DATE

<?php
$inicio = new DateTime('2012-07-01');
$intervalo = new DateInterval('P7D');
$fim = new DateTime('2012-07-31');

$periodo = new DatePeriod($inicio, $intervalo, $fim,
                         DatePeriod::EXCLUDE_START_DATE);

// Ao iterar sobre o objeto DatePeriod, todas as
// datas recorrentes dentro do período são exibidas.
// Note que, neste caso, 2012-07-01 não é mostrada.
foreach ($periodo as $data) {
    echo $data->format('Y-m-d')."\n";
}
?>

O exemplo acima produzirá:

Exemplo #3 Exemplo de DatePeriod mostrando todas as últimas quintas-feiras do ano

<?php
$inicio = new DateTime('2021-12-31');
$fim = new DateTime('2022-12-31 23:59:59');

$intervalo = DateInterval::createFromDateString('last thursday of next month');
$periodo = new DatePeriod($inicio, $intervalo, $fim, DatePeriod::EXCLUDE_START_DATE);

foreach ($periodo as $data) {
    echo $data->format('l Y-m-d'), "\n";
}
?>

O exemplo acima produzirá:

Thursday 2022-01-27
Thursday 2022-02-24
Thursday 2022-03-31
Thursday 2022-04-28
Thursday 2022-05-26
Thursday 2022-06-30
Thursday 2022-07-28
Thursday 2022-08-25
Thursday 2022-09-29
Thursday 2022-10-27
Thursday 2022-11-24
Thursday 2022-12-29

Notas

Npumeros de repetições não vinculados como especificado pela ISO 8601 seção 4.5 "Recurring time interval" não são suportados, ex.: nem passando passando "R/..." como parâmetro isostr nem passando null como parâmetro end funcionaria.

add a note

User Contributed Notes 4 notes

down

simon dot kohlmeyer at mayflower dot de ¶

14 years ago


I found two things useful to know that aren't covered here.



1. endDate is excluded:



<?php

$i = new DateInterval('P1D');

$d1 = new Datetime();

$d2 = clone $d1; $d2->add($i);

foreach(new DatePeriod($d1, $i, $d2) as $d) {

    echo $d->format('Y-m-d H:i:s') . "\n";

}

?>



Will output:

2010-11-03 12:39:53



(Another one because I got it wrong at first)

2. For the first form, recurrences really means REcurrences, not occurences.



<?php

$i = new DateInterval('P1D');

$d = new Datetime();

foreach(new DatePeriod($d, $i, 1) as $d) {

    echo $d->format('Y-m-d H:i:s') . "\n";

}

?>



Will output:

2010-11-03 12:41:05

2010-11-04 12:41:05

down

lars at hp-designs dot com ¶

12 years ago


When you add the time 23:59:59 to the end DateTime object something like the following then the end date will be included in the period:



<?php

$date_start = new DateTime('2012-03-12');

$date_end = new DateTime('2012-03-22 23:59:59');



$interval = '+2 days';

$date_interval = DateInterval::createFromDateString($interval);



$period = new DatePeriod($date_start, $date_interval, $date_end, DatePeriod::EXCLUDE_START_DATE);



foreach($period as $dt) {

 echo $dt->format('d/m');

}

?>



OUTPUT:

14/03

16/03

18/03

20/03

22/03

down

bill at bwi dot com ¶

3 years ago


With reference to the Changelog above, 'recurrences' must be greater than 0 now.

This was not the case in PHP5 ( >= 5.3.0). A foreach loop over a DatePeriod with recurrences == 0 would
execute one time. A function could accept a $count parameter which represented the number of times to execute
the code in a foreach loop, and then initialize a DatePeriod with 'recurrences' == ($count-1) to get the desired
number of iterations.

The following example adds a special case for PHP7 and above to handle the situation where a single
iteration is desired.

Note that an alternative solution to subracting 1 from the desired count is to subtract one month from the desired starting month,       
and then intialize the DatePeriod with the option DatePeriod::EXCLUDE_START_DATE.

<?php
        // displayCalender() is a stub.
        // In a real application, this would generate a displayable calendar for the specified month.
        // 
        // $tp is a DateTime object used to specify the month for which a calendar will be displayed
        function displayCalendar($tp)
        {
                $format = "F, Y";
                echo "Display Calendar for " . $tp->format($format) . "\n";
        }

        // $date is the first month to show
        // $count is the number of months to show
        // NOTE: the number of "recurrences" is one less than the number of months to display
        function showMonths($date = false, $count = 1)
        {
                $format = "Y-m-d 00:00:00";
                $init = ($date ? $date : date($format));
                $one_month = new DateInterval("P1M");

                // get the starting month and day
                $start = new DateTime($init);

                echo "Show $count month" . ($count > 1 ? "s" : "") . "\n";
                //check for PHP7 or greater
                if ($count == 1 && (substr(phpversion(), 0, 1) >= 7) )
                {
                        // Special case for PHP7 when $count == 1
                        displayCalendar($start);
                }   
                else
                {
                        // PHP5 does not need special case, because 0 is accepted value
                        //      for number of recurrences
                        $time_period = new DatePeriod($start, $one_month, ($count-1));
                        foreach ($time_period as $tp)
                        {
                                displayCalendar($tp);
                        }
                }
                echo "\n";
        }
        
        // Show calendar for specific month
        $first_month = "2021-11";
        showMonths($first_month);
        
        // Show calendars for a full year
        $first_month = "2021-01";
        showMonths($first_month, 12);
?>

The above example will output:

Show 1 month
Display Calendar for November, 2021

Show 12 months
Display Calendar for January, 2021
Display Calendar for February, 2021
Display Calendar for March, 2021
Display Calendar for April, 2021
Display Calendar for May, 2021
Display Calendar for June, 2021
Display Calendar for July, 2021
Display Calendar for August, 2021
Display Calendar for September, 2021
Display Calendar for October, 2021
Display Calendar for November, 2021
Display Calendar for December, 2021

down

youssef dot benhssaien at gmail dot com ¶

4 years ago


The parameter isostr should accept an ISO 8601 format, but doing this is not work :
<?php
      $dateStart = date_create('first day of next month this year');

      $isoStr = $dateStart ->format(DateTimeInterface::ISO8601);
      $datePeriod = new DatePeriod("R10/{$isoStr}/P1M");
     // Throw Exception : DatePeriod::__construct(): Unknown or bad format (R10/2020-02-01T22:52:26+0000Z/P1M)
     
     // While doing it by this way works
    $datePeriod = new DatePeriod($dateStart , \DateInterval::createFromDateString("+1 month"), 10);
?>

add a note