هل تريد إنشاء تقويمات عبر الإنترنت حتى تتمكن من عرضها على تطبيق تقويم iPhone أو في تقويم Google؟ يمكن القيام بذلك عن طريق إنشاء تقويمات بتنسيق icalendar (RFC 5545) ، وهو تنسيق نصي يمكن تحميله بواسطة تطبيقات مختلفة.
يتم تعريف تنسيق مثل هذه التقويمات في RFC 5545 ، والتي ليست تجربة قراءة ممتعة. تنفذ هذه الحزمة RFC 5545 وبعض الامتدادات من RFC 7986 لتزويدك واجهة برمجة تطبيقات سهلة الاستخدام لإنشاء التقويمات. ليس نيتنا هي تنفيذ هذه RFC بالكامل ولكن لتوفير واجهة برمجة تطبيقات مباشرة سهلة الاستخدام.
إليك مثال على كيفية استخدامه:
use Spatie IcalendarGenerator Components Calendar ;
use Spatie IcalendarGenerator Components Event ;
Calendar :: create ( ' Laracon online ' )
-> event ( Event :: create ( ' Creating calender feeds ' )
-> startsAt ( new DateTime ( ' 6 March 2019 15:00 ' ))
-> endsAt ( new DateTime ( ' 6 March 2019 16:00 ' ))
)
-> get ();
سوف يولد الرمز أعلاه هذه السلسلة:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:spatie/icalendar-generator
NAME:Laracon online
X-WR-CALNAME:Laracon online
BEGIN:VEVENT
UID:5ef5c3f64cb2c
DTSTAMP;TZID=UTC:20200626T094630
SUMMARY:Creating calendar feeds
DTSTART:20190306T150000Z
DTEND:20190306T160000Z
DTSTAMP:20190419T135034Z
END:VEVENT
END:VCALENDAR
نحن نستثمر الكثير من الموارد لإنشاء أفضل حزم المصدر المفتوح في الفصل. يمكنك دعمنا عن طريق شراء أحد منتجاتنا المدفوعة.
نحن نقدر بشدة أن ترسل لنا بطاقة بريدية من مسقط رأسك ، مع ذكر أي من الحزم (الحزم) التي تستخدمها. ستجد عنواننا على صفحة الاتصال الخاصة بنا. ننشر جميع البطاقات البريدية المستلمة على جدار البطاقة البريدية الافتراضية.
يمكنك تثبيت الحزمة عبر الملحن:
composer require spatie/icalendar-generator
كانت هناك بعض التغييرات الكبيرة بين V1 و V2 من الحزمة. تحقق من دليل الترقية لمزيد من المعلومات.
إليك كيف يمكنك إنشاء تقويم:
$ calendar = Calendar :: create ();
يمكنك إعطاء اسم للتقويم:
$ calendar = Calendar :: create ( ' Laracon Online ' );
يمكن إضافة وصف إلى التقويم:
$ calendar = Calendar :: create ()
-> name ( ' Laracon Online ' )
-> description ( ' Experience Laracon all around the world ' );
في النهاية ، تريد تحويل التقويم الخاص بك إلى رسالة نصية بحيث يمكن بثه أو تنزيله إلى المستخدم. إليك كيف تفعل ذلك:
Calendar :: create ( ' Laracon Online ' )-> get (); // BEGIN:VCALENDAR ...
عند دفق التقويم إلى تطبيق ما ، من الممكن ضبط فاصل تحديث التقويم بمقدار المدة في دقائق. عند تعيين هذا ، سيقوم تطبيق التقويم بالتحقق من الخادم الخاص بك في كل مرة بعد المدة المحددة للتغييرات في التقويم:
Calendar :: create ( ' Laracon Online ' )
-> refreshInterval ( 5 )
. . .
يمكن إنشاء حدث على النحو التالي. لا يلزم الاسم ، ولكن يجب دائمًا إعطاء تاريخ البدء:
Event :: create ( ' Laracon Online ' )
-> startsAt ( new DateTime ( ' 6 march 2019 ' ));
يمكنك تعيين الخصائص التالية في حدث ما:
Event :: create ()
-> name ( ' Laracon Online ' )
-> description ( ' Experience Laracon all around the world ' )
-> uniqueIdentifier ( ' A unique identifier can be set here ' )
-> createdAt ( new DateTime ( ' 6 march 2019 ' ))
-> startsAt ( new DateTime ( ' 6 march 2019 15:00 ' ))
-> endsAt ( new DateTime ( ' 6 march 2019 16:00 ' ));
هل تريد إنشاء حدث بسرعة مع تاريخ البدء والانتهاء؟
Event :: create ( ' Laracon Online ' )
-> period ( new DateTime ( ' 6 march 2019 ' ), new DateTime ( ' 7 march 2019 ' ));
يمكنك إضافة موقع إلى حدث من هذا القبيل:
Event :: create ()
-> address ( ' Kruikstraat 22, 2018 Antwerp, Belgium ' )
-> addressName ( ' Spatie HQ ' )
-> coordinates ( 51.2343 , 4.4287 )
. . .
يمكنك تعيين منظم الحدث ، وعنوان البريد الإلكتروني مطلوب ، ولكن يمكن حذف الاسم:
Event :: create ()
-> organizer ( ' [email protected] ' , ' Ruben ' )
. . .
يمكن إضافة الحاضرين في الحدث على هذا النحو:
Event :: create ()
-> attendee ( ' [email protected] ' ) // only an email address is required
-> attendee ( ' [email protected] ' , ' Brent ' )
. . .
يمكنك أيضًا تعيين حالة مشاركة الحاضر:
Event :: create ()
-> attendee ( ' [email protected] ' , ' Ruben ' , ParticipationStatus :: accepted ())
. . .
هناك خمسة حالات مشاركة:
ParticipationStatus::accepted()
ParticipationStatus::declined()
ParticipationStatus::tentative()
ParticipationStatus::needs_action()
ParticipationStatus::delegated()
يمكنك الإشارة إلى أن الحاضر مطلوب إلى RSVP إلى حدث ما:
Event :: create ()
-> attendee ( ' [email protected] ' , ' Ruben ' , ParticipationStatus :: needs_action (), requiresResponse: true )
. . .
يمكن أن يكون حدثًا شفافًا ، لذلك لا يتداخل بصريًا مع أحداث أخرى في التقويم:
Event :: create ()
-> transparent ()
. . .
من الممكن إنشاء حدث يمتد يومًا كاملاً:
Event :: create ()
-> fullDay ()
. . .
يمكن تعيين حالة الحدث:
Event :: create ()
-> status ( EventStatus :: cancelled ())
. . .
هناك ثلاثة حالات حدث:
EventStatus::confirmed()
EventStatus::cancelled()
EventStatus::tentative()
يمكن تصنيف حدث ( public
، private
، confidential
) على هذا النحو:
Event :: create ()
-> classification ( Classification :: private ())
. . .
يمكنك إضافة مرفق عنوان URL على هذا النحو:
Event :: create ()
-> attachment ( ' https://spatie.be/logo.svg ' )
-> attachment ( ' https://spatie.be/feed.xml ' , ' application/json ' )
. . .
يمكنك إضافة مرفق مضمن (BASE64) على هذا النحو:
Event :: create ()
-> embeddedAttachment ( $ file -> toString ())
-> embeddedAttachment ( $ fileString , ' application/json ' )
-> embeddedAttachment ( $ base64String , ' application/json ' , needsEncoding: false )
. . .
يمكنك إضافة صورة على هذا النحو:
Event :: create ()
-> image ( ' https://spatie.be/logo.svg ' )
-> image ( ' https://spatie.be/logo.svg ' , ' text/svg+xml ' )
-> image ( ' https://spatie.be/logo.svg ' , ' text/svg+xml ' , Display :: badge ())
. . .
هناك أربعة أنواع مختلفة من عرض الصور:
Display::badge()
Display::graphic()
Display::fullsize()
Display::thumbnail()
بعد إنشاء الحدث الخاص بك ، يجب إضافته إلى التقويم. هناك خيارات متعددة للقيام بذلك:
// As a single event parameter
$ event = Event :: create ( ' Creating calendar feeds ' );
Calendar :: create ( ' Laracon Online ' )
-> event ( $ event )
. . .
// As an array of events
Calendar :: create ( ' Laracon Online ' )
-> event ([
Event :: create ( ' Creating calender feeds ' ),
Event :: create ( ' Creating contact lists ' ),
])
. . .
// As a closure
Calendar :: create ( ' Laracon Online ' )
-> event ( function ( Event $ event ){
$ event -> name ( ' Creating calender feeds ' );
})
. . .
يمكنك استخدام مكتبة الكربون الشهيرة:
use Carbon Carbon ;
Event :: create ( ' Laracon Online ' )
-> startsAt ( Carbon :: now ())
. . .
ستستخدم الأحداث المناطق الزمنية المحددة في كائنات DateTime
التي تقدمها. PHP دائمًا يضبط هذه المناطق الزمنية في كائن DateTime
. بشكل افتراضي ، سيكون هذا هو المنطقة الزمنية للتوقيت العالمي ، ولكن من الممكن تغيير هذا.
مجرد تذكير: لا تستخدم وظيفة PHP's setTimezone
على كائن DateTime
، فستغير الوقت وفقًا لـ TimeZone! من الأفضل إنشاء كائن DateTime
جديد مع منطقة زمنية على هذا النحو:
new DateTime ( ' 6 march 2019 15:00 ' , new DateTimeZone ( ' Europe/Brussels ' ))
يمكن أن تُشير إلى حذف المناطق الزمنية. على سبيل المثال ، عندما تريد إظهار حدث ظهراً في العالم. نحدد الظهر في الساعة 12 ، لكن ذلك الوقت نسبي. ليس هو نفسه بالنسبة للأشخاص في بلجيكا أو أستراليا أو أي دولة أخرى في العالم.
لهذا السبب يمكنك تعطيل المناطق الزمنية على الأحداث:
$ starts = new DateTime ( ' 6 march 2019 12:00 ' )
Event :: create ()
-> startsAt ( $ starts )
-> withoutTimezone ()
. . .
يمكنك حتى تعطيل المناطق الزمنية لتقويم كامل:
Calendar :: create ()
-> withoutTimezone ()
. . .
يجب أن يكون لكل تقويم مكونات مناطق زمنية تصف المناطق الزمنية المستخدمة في التقويم الخاص بك. على الرغم من أن جميع عملاء التقويم لا يحتاجون إلى ذلك ، إلا أنه يوصى بإضافة هذه المكونات.
إن إنشاء مكونات المنطقة الزمنية هذه معقدة للغاية. لهذا السبب ستضيفها هذه الحزمة تلقائيًا بدون تكوين.
يمكنك تعطيل هذا السلوك على هذا النحو:
Calendar :: create ()
-> withoutAutoTimezoneComponents ()
. . .
يمكنك إضافة مناطق زمنية يدويًا إلى تقويم إذا رغبت في ذلك:
$ timezoneEntry = TimezoneEntry :: create (
TimezoneEntryType :: daylight (),
new DateTime ( ' 23 march 2020 ' ),
' +00:00 ' ,
' +02:00 '
);
$ timezone = Timezone :: create ( ' Europe/Brussels ' )
-> entry ( $ timezoneEntry )
. . .
Calendar :: create ()
-> timezone ( $ timezone )
. . .
المزيد عن هذه المناطق الزمنية في وقت لاحق.
تسمح التنبيهات لعملاء التقويم بإرسال تذكيرات حول أحداث محددة. على سبيل المثال ، سترسل Apple Mail على iPhone المستخدمين إشعارًا حول الحدث. إن التنبيه ينتمي دائمًا إلى حدث ما لديه وصف وعدد من دقائق قبل الحدث الذي سيتم تشغيله:
Event :: create ( ' Laracon Online ' )
-> alertMinutesBefore ( 5 , ' Laracon online is going to start in five minutes ' );
يمكنك أيضًا تشغيل تنبيه بعد الحدث:
Event :: create ( ' Laracon Online ' )
-> alertMinutesAfter ( 5 , ' Laracon online has ended, see you next year! ' );
أو تشغيل تنبيه في تاريخ محدد:
Event :: create ( ' Laracon Online ' )
-> alertAt (
new DateTime ( ' 05/16/2020 12:00:00 ' ),
' Laracon online has ended, see you next year! '
);
سيؤدي إزالة المناطق الزمنية على التقويم أو الحدث أيضًا إلى إزالة المناطق الزمنية في التنبيه.
من الممكن أن تكرر الأحداث ، على سبيل المثال عشاء شركتك الشهري. يمكن القيام بذلك على هذا النحو:
Event :: create ( ' Laracon Online ' )
-> repeatOn ( new DateTime ( ' 05/16/2020 12:00:00 ' ));
ويمكنك أيضًا تكرار الحدث في مجموعة من التواريخ:
Event :: create ( ' Laracon Online ' )
-> repeatOn ([ new DateTime ( ' 05/16/2020 12:00:00 ' ), new DateTime ( ' 08/13/2020 15:00:00 ' )]);
قواعد التكرار أو RRULE باختصار ، تتيح إضافة حدث متكرر في التقويم الخاص بك من خلال وصف عندما يتكرر داخل RRULE. أولاً ، علينا إنشاء rrule:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: daily ());
تصف هذه القاعدة حدثًا سيتكرر يوميًا. يمكنك أيضًا تعيين التردد إلى secondly
أو minutely
أو hourly
أو weekly
أو monthly
أو yearly
.
يمكن إضافة rrule إلى حدث على هذا النحو:
Event :: create ( ' Laracon Online ' )
-> rrule ( RRule :: frequency ( RecurrenceFrequency :: monthly ()));
من الممكن أن تكون رعايتها لذوقك الشخصي ؛ دعونا نلقي نظرة!
يمكن أن يبدأ rrule من نقطة معينة في الوقت المناسب:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: daily ())-> starting ( new DateTime ( ' now ' ));
وتوقف عند نقطة معينة:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: daily ())-> until ( new DateTime ( ' now ' ));
لا يمكن تكراره إلا لبضع مرات ، 10 مرات على سبيل المثال:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: daily ())-> times ( 10 );
يمكن تغيير فاصل التكرار:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: daily ())-> interval ( 2 );
عندما يبدأ هذا الحدث يوم الاثنين ، على سبيل المثال ، لن يحدث التكرار التالي لهذا الحدث يوم الثلاثاء ولكن الأربعاء. يمكنك أن تفعل الشيء نفسه لجميع الترددات.
من الممكن أيضًا تكرار الحدث في يوم أسبوعي محدد:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> onWeekDay (
RecurrenceDay :: friday ()
);
أو في أيام الأسبوع المحددة من الأسبوع في الشهر:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> onWeekDay (
RecurrenceDay :: friday (), 3
);
أو في الأسبوع الأخير من شهر:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> onWeekDay (
RecurrenceDay :: sunday (), - 1
);
يمكنك التكرار في يوم معين في الشهر:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> onMonthDay ( 16 );
حتى أنه من الممكن إعطاء مجموعة من الأيام في الشهر:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> onMonthDay (
[ 5 , 10 , 15 , 20 ]
);
يمكن أن يتم التكرار لأشهر معينة (على سبيل المثال فقط في الربع الثاني):
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> onMonth (
[ RecurrenceMonth :: april (), RecurrenceMonth :: may (), RecurrenceMonth :: june ()]
);
أو فقط في شهر واحد فقط:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> onMonth (
RecurrenceMonth :: october ()
);
من الممكن ضبط اليوم الذي يبدأ فيه الأسبوع:
$ rrule = RRule :: frequency ( RecurrenceFrequency :: monthly ())-> weekStartsOn (
ReccurenceDay :: monday ()
);
يمكنك توفير تاريخ محدد لا يتكرر فيه الحدث:
Event :: create ( ' Laracon Online ' )
-> rrule ( RRule :: frequency ( RecurrenceFrequency :: daily ()))
-> doNotRepeatOn ( new DateTime ( ' 05/16/2020 12:00:00 ' ));
من الممكن أيضًا إعطاء مجموعة من التواريخ التي لن يتكرر فيها الحدث:
Event :: create ( ' Laracon Online ' )
-> rrule ( RRule :: frequency ( RecurrenceFrequency :: daily ()))
-> doNotRepeatOn ([ new DateTime ( ' 05/16/2020 12:00:00 ' ), new DateTime ( ' 08/13/2020 15:00:00 ' )]);
بدلاً من ذلك ، يمكنك إضافة rrules كسلسلة:
Event :: create ( ' SymfonyCon ' )
-> rruleAsString ( ' FREQ=DAILY;INTERVAL=1 ' );
إذا قمت بإضافة RRULES كسلسلة ، فإن المناطق الزمنية المدرجة في DTSTART وحتى غير معروفة للحزمة لأن السلسلة لا يتم تحليلها وتقييمها. إذا كانوا معروفين ، يمكنك إضافة DTSTART وحتى بشكل منفصل لمساعدة الحزمة على اكتشاف المناطق الزمنية:
Event :: create ( ' SymfonyCon ' )
-> rruleAsString (
' DTSTART=20231207T090000Z;FREQ=DAILY;INTERVAL=1;UNTIL=20231208T090000Z ' ,
new DateTime ( ' 7 december 2023 09:00:00 ' , new DateTimeZone ( ' UTC ' )),
new DateTime ( ' 8 december 2023 09:00:00 ' , new DateTimeZone ( ' UTC ' ))
);
يمكنك استخدام ردود Laravel للدفق إلى تطبيقات التقويم:
$ calendar = Calendar :: create ( ' Laracon Online ' );
return response ( $ calendar -> get ())
-> header ( ' Content-Type ' , ' text/calendar; charset=utf-8 ' );
إذا كنت ترغب في إضافة إمكانية للمستخدمين لتنزيل تقويم واستيراده إلى تطبيق تقويم:
$ calendar = Calendar :: create ( ' Laracon Online ' );
return response ( $ calendar -> get (), 200 , [
' Content-Type ' => ' text/calendar; charset=utf-8 ' ,
' Content-Disposition ' => ' attachment; filename="my-awesome-calendar.ics" ' ,
]);
إذا كنت ترغب في صياغة مكونات المنطقة الزمنية بنفسك ، فأنت في المكان الصحيح ، على الرغم من أننا ننصحك بقراءة القسم في المناطق الزمنية من RFC أولاً.
يمكنك إنشاء منطقة زمنية على هذا النحو:
$ timezone = Timezone :: create ( ' Europe/Brussels ' );
من الممكن توفير آخر تاريخ تم تعديله:
$ timezone = Timezone :: create ( ' Europe/Brussels ' )
-> lastModified ( new DateTime ( ' 16 may 2020 12:00:00 ' ));
أو إضافة عنوان URL مع مزيد من المعلومات حول المنطقة الزمنية:
$ timezone = Timezone :: create ( ' Europe/Brussels ' )
-> url ( ' https://spatie.be ' );
تتكون المنطقة الزمنية من إدخالات متعددة حيث يتغير وقت المنطقة الزمنية بالنسبة إلى UTC ، ويمكن إنشاء هذا الإدخال لوقت وضفي النهار:
$ entry = TimezoneEntry :: create (
TimezoneEntryType :: standard (),
new DateTime ( ' 16 may 2020 12:00:00 ' ),
' +00:00 ' ,
' +02:00 '
);
أولاً ، يمكنك تقديم نوع الإدخال ( standard
أو daylight
). ثم DateTime
عندما يتغير الوقت. أخيرًا ، إزاحة بالنسبة إلى UTC من قبل التغيير والإزاحة بالنسبة إلى UTC بعد التغيير.
من الممكن أيضًا إعطاء هذا الإدخال اسمًا ووصفًا:
$ entry = TimezoneEntry :: create (...)
-> name ( ' Europe - Brussels ' )
-> description ( ' Belgian timezones ftw! ' );
يمكن إعطاء rrule للإدخال على هذا النحو:
$ entry = TimezoneEntry :: create (...)
-> rrule ( RRule :: frequency ( RecurrenceFrequency :: daily ()));
في النهاية ، يمكنك إضافة إدخال إلى منطقة زمنية:
$ timezone = Timezone :: create ( ' Europe/Brussels ' )
-> entry ( $ timezoneEntry );
أو حتى إضافة إدخالات متعددة:
$ timezone = Timezone :: create ( ' Europe/Brussels ' )
-> entry ([ $ timezoneEntryOne , $ timezoneEntryTwo ]);
الآن قمنا ببناء المنطقة الزمنية لدينا حان الوقت (؟) لإضافة هذه المنطقة الزمنية إلى التقويم الخاص بنا:
$ calendar = Calendar :: create ( ' Calendar with timezones ' )
-> timezone ( $ timezone );
من الممكن أيضًا إضافة مناطق زمنية متعددة:
$ calendar = Calendar :: create ( ' Calendar with timezones ' )
-> timezone ([ $ timezoneOne , $ timezoneTwo ]);
نحاول الحفاظ على هذه الحزمة واضحة قدر الإمكان. لهذا السبب لم يتم تضمين الكثير من الخصائص والملاحق الفرعية من RFC في هذه الحزمة. لقد جعلنا من الممكن إضافة خصائص أو أدوات فرعية أخرى إلى كل مكون إذا كنت قد تحتاج إلى شيء غير مدرج في الحزمة. لكن كن حذرا! من هذه اللحظة ، أنت وحدك تنفيذ RFC بشكل صحيح.
يمكنك إضافة خاصية جديدة إلى مكون مثل هذا:
Calendar :: create ()
-> appendProperty (
TextProperty :: create ( ' ORGANIZER ' , ' [email protected] ' )
)
. . .
لقد أضفنا هنا نوعًا من TextProperty
، وهذا نوع خاصية القيمة الافتراضية ذات القيمة الرئيسية مع نص كقيمة. يمكنك أيضًا استخدام إحدى الخصائص الافتراضية المضمنة في الحزمة أو إنشاء خاص بك عن طريق توسيع فئة Property
.
في بعض الأحيان ، يمكن أن تحتوي خاصية على بعض المعلمات الإضافية ، فهذه إدخالات ذات قيمة رئيسية ويمكن إضافتها إلى خصائص على هذا النحو:
$ property = TextProperty :: create ( ' ORGANIZER ' , ' [email protected] ' )
-> addParameter ( Parameter :: create ( ' CN ' , ' RUBEN VAN ASSCHE ' ));
Calendar :: create ()
-> appendProperty ( $ property )
. . .
يمكن إلحاق المكون الفرعي على هذا النحو:
Calendar :: create ()
-> appendSubComponent (
Event :: create ( ' Extending icalendar-generator ' )
)
. . .
من الممكن إنشاء أصحاب الفروق الخاصة بك عن طريق توسيع فئة Component
.
composer test
نحن نسعى جاهدين للحصول على واجهة برمجة تطبيقات بسيطة وسهلة الاستخدام. تريد شيئا أكثر؟ ثم تحقق من هذه الحزمة بواسطة Markus Poerschke.
يرجى الاطلاع على Changelog لمزيد من المعلومات حول ما تغير مؤخرًا.
يرجى الاطلاع على المساهمة للحصول على التفاصيل.
إذا كنت قد عثرت على خطأ فيما يتعلق بالأمان ، فيرجى mail [email protected] بدلاً من استخدام تعقب المشكلات.
أنت حر في استخدام هذه الحزمة ، ولكن إذا وصل الأمر إلى بيئة الإنتاج الخاصة بك ، فإننا نقدر بشدة أن ترسل لنا بطاقة بريدية من مسقط رأسك ، مع ذكر أي من الحزم (الحزم) التي تستخدمها.
عنواننا هو: Spatie ، Kruikstraat 22 ، Box 12 ، 2018 Antwerp ، Belgium.
ننشر جميع البطاقات البريدية المستلمة على موقع شركتنا.
ترخيص معهد ماساتشوستس للتكنولوجيا (MIT). يرجى الاطلاع على ملف الترخيص لمزيد من المعلومات.