download recurr - download recurr do código-fonte

recurr

Outras categorias

1.0.0

Baixar

Recorrência

Recurr é uma biblioteca PHP para trabalhar com regras de recorrência (RRULE) e convertê-las em objetos DateTime.

Recurr foi desenvolvido como um precursor de um calendário com eventos recorrentes e é fortemente inspirado em rrule.js.

Instalando Recorrência

A forma recomendada de instalar o Recurr é através do Composer.

composer require simshaun/recurr

Usando Recorrência

Criando objetos de regra RRULE

Você pode criar um novo objeto Rule passando a string (RRULE) ou um array com as partes da regra, a data de início, a data de término (opcional) e o fuso horário.

 $ timezone    = ' America/New_York ' ;
$ startDate   = new  DateTime ( ' 2013-06-12 20:00:00 ' , new  DateTimeZone ( $ timezone ));
$ endDate     = new  DateTime ( ' 2013-06-14 20:00:00 ' , new  DateTimeZone ( $ timezone )); // Optional
$ rule        = new  Recurr  Rule ( ' FREQ=MONTHLY;COUNT=5 ' , $ startDate , $ endDate , $ timezone );

Você também pode usar métodos encadeados para criar sua regra programaticamente e obter o RRULE resultante.

 $ rule = ( new  Recurr  Rule )
    -> setStartDate ( $ startDate )
    -> setTimezone ( $ timezone )
    -> setFreq ( ' DAILY ' )
    -> setByDay ([ ' MO ' , ' TU ' ])
    -> setUntil ( new  DateTime ( ' 2017-12-31 ' ))
;

echo $ rule -> getString (); //FREQ = DAILY ; UNTIL=20171231T000000 ; BYDAY=MO , TU

RRULE para objetos DateTime

 $ transformer = new  Recurr  Transformer  ArrayTransformer ();

print_r ( $ transformer -> transform ( $ rule ));

$transformer->transform(...) retorna um RecurrenceCollection de objetos Recurrence .
Cada Recurrence possui métodos getStart() e getEnd() que retornam um objeto DateTime .
Se a Rule transformada não tiver uma data de término, getEnd() retornará um objeto DateTime igual ao de getStart() .

Nota: O transformador possui um limite "virtual" (padrão 732) na quantidade de objetos que gera. Isso evita que o script trave em uma regra infinitamente recorrente. Você pode alterar o limite virtual com um objeto ArrayTransformerConfig que você passa para ArrayTransformer .

Restrições de transformação

As restrições são usadas pelo ArrayTransformer para permitir ou impedir que determinadas datas sejam adicionadas a um RecurrenceCollection . Recurr fornece as seguintes restrições:

AfterConstraint(DateTime $after, $inc = false)
BeforeConstraint(DateTime $before, $inc = false)
BetweenConstraint(DateTime $after, DateTime $before, $inc = false)

$inc define o que acontece se $after ou $before forem recorrências. Se $inc = true , eles serão incluídos na coleção. Por exemplo,

 $ startDate   = new  DateTime ( ' 2014-06-17 04:00:00 ' );
$ rule        = new  Recurr  Rule ( ' FREQ=MONTHLY;COUNT=5 ' , $ startDate );
$ transformer = new  Recurr  Transformer  ArrayTransformer ();

$ constraint = new  Recurr  Transformer  Constraint  BeforeConstraint ( new  DateTime ( ' 2014-08-01 00:00:00 ' ));
print_r ( $ transformer -> transform ( $ rule , $ constraint ));

Nota: Se estiver construindo sua própria restrição, é importante saber que as datas que não atendem aos requisitos da restrição não contam para o limite virtual do transformador. Se você definir manualmente a propriedade $stopsTransformer da sua restrição como false , o transformador poderá travar por meio de um loop infinito. Veja o BetweenConstraint para ver um exemplo de como evitar isso.

Filtros `RecurrenceCollection` pós-transformação

RecurrenceCollection fornece os seguintes métodos auxiliares encadeados para filtrar recorrências:

startsBetween(DateTime $after, DateTime $before, $inc = false)
startsBefore(DateTime $before, $inc = false)
startsAfter(DateTime $after, $inc = false)
endsBetween(DateTime $after, DateTime $before, $inc = false)
endsBefore(DateTime $before, $inc = false)
endsAfter(DateTime $after, $inc = false)

$inc define o que acontece se $after ou $before forem recorrências. Se $inc = true , eles serão incluídos na coleção filtrada. Por exemplo,

 pseudo...
2014-06-01 startsBetween(2014-06-01, 2014-06-20) // false
2014-06-01 startsBetween(2014-06-01, 2014-06-20, true) // true

Nota: RecurrenceCollection estende a classe ArrayCollection do projeto Doctrine.

RRULE para texto

Recurr suporta a transformação de algumas regras de recorrência em texto legível por humanos. Este recurso ainda está em versão beta e oferece suporte apenas a frequências anuais, mensais, semanais e diárias.

 $ rule = new Rule ( ' FREQ=YEARLY;INTERVAL=2;COUNT=3; ' , new  DateTime ());

$ textTransformer = new TextTransformer ();
echo $ textTransformer -> transform ( $ rule );

Se precisar de mais do que inglês, você pode passar um tradutor com uma das localidades suportadas (veja a pasta de traduções) .

 $ rule = new Rule ( ' FREQ=YEARLY;INTERVAL=2;COUNT=3; ' , new  DateTime ());

$ textTransformer = new TextTransformer (
    new  Recurr  Transformer  Translator ( ' de ' )
);
echo $ textTransformer -> transform ( $ rule );

Avisos

**Regras recorrentes mensais ** Por padrão, se a data de início for 29, 30 ou 31, o Recurr pulará os meses seguintes que não tenham pelo menos esse número de dias. (por exemplo, 31 de janeiro + 1 mês = março)

Este comportamento é configurável:

 $ timezone    = ' America/New_York ' ;
$ startDate   = new  DateTime ( ' 2013-01-31 20:00:00 ' , new  DateTimeZone ( $ timezone ));
$ rule        = new  Recurr  Rule ( ' FREQ=MONTHLY;COUNT=5 ' , $ startDate , null , $ timezone );
$ transformer = new  Recurr  Transformer  ArrayTransformer ();

$ transformerConfig = new  Recurr  Transformer  ArrayTransformerConfig ();
$ transformerConfig -> enableLastDayOfMonthFix ();
$ transformer -> setConfig ( $ transformerConfig );

print_r ( $ transformer -> transform ( $ rule ));
// 2013-01-31 , 2013-02-28 , 2013-03-31 , 2013-04-30 , 2013-05-31