recurr

Повторять

Recurr — это PHP-библиотека для работы с правилами повторения (RRULE) и преобразования их в объекты DateTime.

Recurr был разработан как предшественник календаря с повторяющимися событиями и во многом вдохновлен rrule.js.

Установка Рекурра

Рекомендуемый способ установки Recurr — через Composer.

composer require simshaun/recurr

Использование повтора

Создание объектов правил RRULE

Вы можете создать новый объект правила, передав строку (RRULE) или массив с частями правила, датой начала, датой окончания (необязательно) и часовым поясом.

 $ 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 );

Вы также можете использовать связанные методы для программного построения правила и получения результирующего RRULE.

 $ 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 для объектов DateTime

 $ transformer = new  Recurr  Transformer  ArrayTransformer ();

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

1. $transformer->transform(...) возвращает RecurrenceCollection объектов Recurrence .
2. Каждый Recurrence имеет методы getStart() и getEnd() которые возвращают объект DateTime .
3. Если в преобразованном Rule отсутствует дата окончания, getEnd() вернет объект DateTime равный объекту getStart() .

Примечание. Трансформатор имеет «виртуальный» лимит (по умолчанию 732) на количество генерируемых объектов. Это предотвращает сбой сценария при бесконечно повторяющемся правиле. Вы можете изменить виртуальный предел с помощью объекта ArrayTransformerConfig , который вы передаете в ArrayTransformer .

Ограничения трансформации

Ограничения используются ArrayTransformer, чтобы разрешить или запретить добавление определенных дат в RecurrenceCollection . Recurr предоставляет следующие ограничения:

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

$inc определяет, что произойдет, если $after или $before сами являются повторениями. Если $inc = true , они будут включены в коллекцию. Например,

 $ 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 ));

Примечание. При создании собственного ограничения важно знать, что даты, не соответствующие требованиям ограничения, не учитываются в виртуальном пределе преобразователя. Если вы вручную установите для свойства $stopsTransformer ограничения значение false , преобразователь может выйти из строя из-за бесконечного цикла. См. пример BetweenConstraint о том, как этого избежать.

Фильтры RecurrenceCollection после преобразования

RecurrenceCollection предоставляет следующие вспомогательные методы для фильтрации повторений:

• 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 определяет, что произойдет, если $after или $before сами являются повторениями. Если $inc = true , они будут включены в отфильтрованную коллекцию. Например,

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

Примечание. RecurrenceCollection расширяет класс ArrayCollection проекта Doctrine.

RRULE в текст

Recurr поддерживает преобразование некоторых правил повторения в удобочитаемый текст. Эта функция все еще находится в стадии бета-тестирования и поддерживает только ежегодную, ежемесячную, еженедельную и ежедневную частоту.

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

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

Если вам нужно больше, чем английский, вы можете использовать переводчик с одной из поддерживаемых локалей (см. папку «Переводы») .

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

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

Предупреждения

• **Правила ежемесячного повторения ** По умолчанию, если ваша дата начала приходится на 29, 30 или 31 число, Recurr пропустит следующие месяцы, в которых не так много дней. (например, 31 января + 1 месяц = ​​март)

Это поведение настраивается:

 $ 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 

Способствовать

Не стесняйтесь комментировать или делать запросы на включение. Пожалуйста, включите тесты в PR.

Лицензия

Recurr лицензируется по лицензии MIT. Подробности смотрите в файле ЛИЦЕНЗИИ.