laravel google calendar

إدارة الأحداث في تقويم Google

هذه الحزمة تجعل العمل مع تقويم Google نسيمًا. بمجرد إعداده ، يمكنك القيام بهذه الأشياء:

 use Spatie  GoogleCalendar  Event ;

// create a new event
$ event = new Event ;

$ event -> name = ' A new event ' ;
$ event -> description = ' Event description ' ;
$ event -> startDateTime = Carbon Carbon:: now ();
$ event -> endDateTime = Carbon Carbon:: now ()-> addHour ();
$ event -> addAttendee ([
    ' email ' => ' [email protected] ' ,
    ' name ' => ' John Doe ' ,
    ' comment ' => ' Lorum ipsum ' ,
    ' responseStatus ' => ' needsAction ' ,
]);
$ event -> addAttendee ([ ' email ' => ' [email protected] ' ]);
$ event -> addMeetLink (); // optionally add a google meet link to the event

$ event -> save ();

// get all future events on a calendar
$ events = Event:: get ();

// update existing event
$ firstEvent = $ events -> first ();
$ firstEvent -> name = ' updated name ' ;
$ firstEvent -> save ();

$ firstEvent -> update ([ ' name ' => ' updated again ' ]);

// create a new event
Event:: create ([
   ' name ' => ' A new event ' ,
   ' startDateTime ' => Carbon Carbon:: now (),
   ' endDateTime ' => Carbon Carbon:: now ()-> addHour (),
]);

// delete an event
$ event -> delete ();

Spatie هي وكالة تصميم ويب مقرها في أنتويرب ، بلجيكا. ستجد نظرة عامة على جميع مشاريعنا المصدر المفتوحة على موقعنا.

دعمنا

نحن نستثمر الكثير من الموارد لإنشاء أفضل حزم المصدر المفتوح في الفصل. يمكنك دعمنا عن طريق شراء أحد منتجاتنا المدفوعة.

نحن نقدر بشدة أن ترسل لنا بطاقة بريدية من مسقط رأسك ، مع ذكر أي من الحزم (الحزم) التي تستخدمها. ستجد عنواننا على صفحة الاتصال الخاصة بنا. ننشر جميع البطاقات البريدية المستلمة على جدار البطاقة البريدية الافتراضية.

تثبيت

يمكنك تثبيت الحزمة عبر الملحن:

composer require spatie/laravel-google-calendar

يجب عليك نشر التكوين مع هذا الأمر:

php artisan vendor:publish --provider= " SpatieGoogleCalendarGoogleCalendarServiceProvider "

سيقوم هذا بنشر ملف يسمى google-calendar.php في دليل التكوين الخاص بك مع هذه المحتويات:

 return [

    ' default_auth_profile ' => env ( ' GOOGLE_CALENDAR_AUTH_PROFILE ' , ' service_account ' ),

    ' auth_profiles ' => [

        /*
         * Authenticate using a service account.
         */
        ' service_account ' => [
            /*
             * Path to the json file containing the credentials.
             */
            ' credentials_json ' => storage_path ( ' app/google-calendar/service-account-credentials.json ' ),
        ],

        /*
         * Authenticate with actual google user account.
         */
        ' oauth ' => [
            /*
             * Path to the json file containing the oauth2 credentials.
             */
            ' credentials_json ' => storage_path ( ' app/google-calendar/oauth-credentials.json ' ),

            /*
             * Path to the json file containing the oauth2 token.
             */
            ' token_json ' => storage_path ( ' app/google-calendar/oauth-token.json ' ),
        ],
    ],

    /*
     * The id of the Google Calendar that will be used by default.
     */
    ' calendar_id ' => env ( ' GOOGLE_CALENDAR_ID ' ),
];

كيفية الحصول على بيانات الاعتماد للتواصل مع تقويم Google

أول شيء ستحتاج إليه هو الحصول على بيانات اعتماد لاستخدام واجهة برمجة تطبيقات Google. أفترض أنك قمت بالفعل بإنشاء حساب Google وتم تسجيل الدخول إليه. توجه إلى وحدة التحكم في Google API وانقر فوق "تحديد مشروع" في الرأس.

بعد ذلك ، يجب علينا تحديد واجهات برمجة التطبيقات التي قد يستهلكها المشروع. من الرأس ، حدد "تمكين واجهات برمجة التطبيقات والخدمات".

في الصفحة التالية ، ابحث عن "التقويم" وحدد "API Google Calendar" من القائمة.

من هنا ، اضغط على "تمكين" لتمكين واجهة برمجة تطبيقات تقويم Google لهذا المشروع.

الآن بعد أن قمت بإنشاء مشروع لديه إمكانية الوصول إلى واجهة برمجة تطبيقات التقويم ، حان الوقت لتنزيل ملف مع بيانات الاعتماد هذه. انقر فوق "بيانات الاعتماد" في الشريط الجانبي ثم اضغط على رابط "بيانات الاعتماد في واجهات برمجة التطبيقات والخدمات".

من هذه الصفحة ، افتح "إنشاء بيانات الاعتماد" المنسدلة وحدد "مفتاح حساب الخدمة".

على الشاشة التالية ، يمكنك منح حساب الخدمة اسمًا. يمكنك تسمية أي شيء تريده. في معرف حساب الخدمة ، سترى عنوان بريد إلكتروني. سنستخدم عنوان البريد الإلكتروني هذا لاحقًا في هذا الدليل. حدد "JSON" كنوع المفتاح وانقر فوق "إنشاء" لتنزيل ملف JSON. ستحصل على تحذير من أن حساب الخدمة ليس له دور ، يمكنك تجاهل ذلك بأمان وإنشاء حساب الخدمة دون تعيين دور.

إذا كنت قد قمت بتفويض الوصول على مستوى المجال إلى حساب الخدمة وترغب في انتحال شخصية مستخدم ، حدد عنوان البريد الإلكتروني لحساب المستخدم في ملف التكوين.

احفظ JSON داخل مشروع Laravel الخاص بك في الموقع المحدد في service_account_credentials_json مفتاح ملف التكوين لهذه الحزمة. نظرًا لأن ملف JSON يحتوي على معلومات محتملة حساسة ، لا أوصي بالالتزام بمستودع GIT الخاص بك.

الآن بعد أن تم إعداد كل شيء على موقع API ، سنحتاج إلى تكوين بعض الأشياء في موقع تقويم Google. توجه إلى تقويم Google وعرض إعدادات التقويم الذي تريد العمل معه عبر PHP. في علامة التبويب "مشاركة مع أشخاص محددين" ، اضغط على زر "إضافة الأشخاص" وأضف معرف حساب الخدمة الذي تم عرضه عند إنشاء بيانات الاعتماد على موقع API.

قم بالتمرير لأسفل إلى قسم "دمج التقويم" لرؤية معرف التقويم. تحتاج إلى تحديد هذا المعرف في ملف التكوين.

المصادقة مع OAUTH2

تدعم هذه الحزمة مصادقة OAUTH2. يتيح لك ذلك المصادقة مع حساب Google الفعلي ، وإنشاء وإدارة الأحداث مع حساب Google الخاص بك.

تتطلب مصادقة OAUTH2 ملفًا رمزيًا ، بالإضافة إلى ملف بيانات الاعتماد. أسهل طريقة لإنشاء كلا هذا الملف هي استخدام أداة PHP QuickStart. بعد هذا الدليل ، سيقوم بإنشاء ملفين ، credentials.json و token.json . يجب أن يتم حفظها في مشروعك باسم oauth-credentials.json و oauth-token.json ، على التوالي. تحقق من ملف التكوين في هذه الحزمة للحصول على تفاصيل دقيقة حول مكان حفظ هذه الملفات.

لاستخدام OAUTH2 ، يجب أيضًا تعيين متغير بيئة جديد في ملف .env الخاص بك:

 GOOGLE_CALENDAR_AUTH_PROFILE =oauth

إذا كنت تقوم بالترقية من إصدار أقدم من هذه الحزمة ، فستحتاج إلى فرض نشر للتكوين:

php artisan vendor:publish --provider= " SpatieGoogleCalendarGoogleCalendarServiceProvider " --force

أخيرًا ، للحصول على تجربة أكثر سلاسة في تطبيقك ، بدلاً من استخدام أداة QuickStart ، يمكنك إعداد شاشة موافقة في وحدة التحكم في Google API. هذا من شأنه أن يسمح للمستخدمين غير التقنيين بتطبيقك بإنشاء الرموز الخاصة بهم بسهولة. هذا اختياري تماما.

الاستخدام

الحصول على الأحداث

يمكنك جلب جميع الأحداث ببساطة عن طريق الاتصال Event::get(); هذا سيعود جميع أحداث العام المقبل. يأتي حدث في شكل كائن SpatieGoogleCalendarEvent .

التوقيع الكامل للوظيفة هو:

 public static function get( Carbon $ startDateTime = null , Carbon $ endDateTime = null , array $ queryParameters = [], string $ calendarId = null ): Collection

يتم سرد المعلمات التي يمكنك تمريرها في $queryParameters في الوثائق في list في مستندات API Calendar.

الوصول إلى مواعيد البدء والنهاية لحدث ما

يمكنك استخدام هذه getters لاسترداد تاريخ البدء والانتهاء كمثيلات للكربون:

 $ events = Event:: get ();

$ events [ 0 ]-> startDate ;
$ events [ 0 ]-> startDateTime ;
$ events [ 0 ]-> endDate ;
$ events [ 0 ]-> endDateTime ;

إنشاء حدث

يمكنك فقط جديدة لأعلى SpatieGoogleCalendarEvent -Object

 $ event = new Event ;

$ event -> name = ' A new event ' ;
$ event -> startDateTime = Carbon Carbon:: now ();
$ event -> endDateTime = Carbon Carbon:: now ()-> addHour ();

$ event -> save ();

يمكنك أيضًا الاتصال create بشكل ثابت:

Event:: create ([
   ' name ' => ' A new event ' ,
   ' startDateTime ' => Carbon Carbon:: now (),
   ' endDateTime ' => Carbon Carbon:: now ()-> addHour (),
]);

سيؤدي ذلك إلى إنشاء حدث مع وقت بداية ونهاية محدد. إذا كنت ترغب في إنشاء حدث ليوم كامل ، فيجب عليك استخدام startDate و endDate بدلاً من startDateTime و endDateTime .

 $ event = new Event ;

$ event -> name = ' A new full day event ' ;
$ event -> startDate = Carbon Carbon:: now ();
$ event -> endDate = Carbon Carbon:: now ()-> addDay ();

$ event -> save ();

يمكنك إنشاء حدث يعتمد على سلسلة نصية بسيطة مثل هذا:

 $ event = new Event ();

$ event -> quickSave ( ' Appointment at Somewhere on April 25 10am-10:25am ' );

// statically
Event:: quickCreate ( ' Appointment at Somewhere on April 25 10am-10:25am ' );

الحصول على حدث واحد

تقوم Google بتعيين معرف فريد لكل حدث واحد. يمكنك الحصول على هذا المعرف عن طريق الحصول على الأحداث باستخدام طريقة get والحصول على خاصية id على SpatieGoogleCalendarEvent -Object:

 // get the id of the first upcoming event in the calendar .
$ eventId = Event:: get ()-> first ()-> id ;

// you can also get the id after creating the event , then you can save it to database .
$ event = new Event ;
$ newEvent = $ event -> save ();
echo $ newEvent -> id ; // display the event id

يمكنك استخدام هذا المعرف لجلب حدث واحد من Google:

Event:: find ( $ eventId );

تحديث حدث

سهل ، فقط قم بتغيير بعض الخصائص واتصل save() :

 $ event = Event:: find ( $ eventId );

$ event -> name = ' My updated title ' ;
$ event -> save ();

بدلاً من ذلك ، يمكنك استخدام طريقة التحديث:

 $ event = Event:: find ( $ eventId );

$ event -> update ([ ' name ' => ' My updated title ' ]);

حذف حدث

لا شيء لذلك!

 $ event = Event:: find ( $ eventId );

$ event -> delete ();

تحديد مصدر

يمكنك تعيين عناوين URL المصدر في الأحداث الخاصة بك ، والتي تكون مرئية فقط لمبدع الحدث (انظر المستندات لمعرفة المزيد على خاصية المصدر). هذه الوظيفة تعمل فقط عند المصادقة عبر OAuth.

 $ yourEvent -> source = [
   ' title ' => ' Test Source Title ' ,
   ' url ' => ' http://testsource.url ' ,
];

وضع لون

يمكنك تعيين ألوان معينة للأحداث الخاصة بك (ColorId من 1 إلى 11). تقتصر الاحتمالات على تعريفات ألوان واجهة برمجة تطبيقات تقويم Google. يمكنك العثور عليها هنا.

 $ yourevent -> setColorId ( 11 );

القيود

يوفر واجهة برمجة تطبيقات تقويم Google العديد من الخيارات. هذه الحزمة لا تدعمهم جميعًا. على سبيل المثال ، لا يمكن إدارة الأحداث المتكررة بشكل صحيح مع هذه الحزمة. إذا التزمت بإنشاء الأحداث باسم وتاريخ ، فيجب أن تكون بخير.

الترقية من V1 إلى V2

الفرق الرئيسي الوحيد بين v1 و v2 هو أنه تحت Hood Google API V2 يتم استخدامه بدلاً من V1. فيما يلي الخطوات المطلوبة للترقية:

• أعد تسمية ملف التكوين من laravel-google-calendar إلى google-calendar
• في ملف التكوين ، قم بإعادة تسمية client_secret_json مفتاح service_account_credentials_json

Changelog

يرجى الاطلاع على changelog لمزيد من المعلومات حول ما تغير مؤخرًا.

الاختبار

composer test 

المساهمة

يرجى الاطلاع على المساهمة للحصول على التفاصيل.

حماية

إذا اكتشفت أي مشكلات متعلقة بالأمان ، فيرجى إرسال بريد إلكتروني إلى [email protected] بدلاً من استخدام تعقب المشكلات.

الاعتمادات

• Freek van der Herten
• جميع المساهمين

شكراً جزيلاً لسيباستيان لوكا لمساعدته الكبيرة في إنشاء V2 من هذه الحزمة.

رخصة

ترخيص معهد ماساتشوستس للتكنولوجيا (MIT). يرجى الاطلاع على ملف الترخيص لمزيد من المعلومات.