basement chat
v1.1.1
أضف أداة الدردشة في الوقت الفعلي إلى تطبيق Laravel الخاص بك.
باستخدام هذه الحزمة، يمكنك تحسين مشاركة المستخدم وتعزيز التعاون وتسهيل الاتصال الفوري داخل تطبيق Laravel الحالي الخاص بك من خلال توفير وظيفة عنصر واجهة مستخدم الدردشة الديناميكية والتفاعلية المدمجة بسلاسة في الوقت الفعلي.
اسم الطابق السفلي مستوحى من غرفة الدردشة الخاصة بـ Aech من Ready Player One.
هنا عرض توضيحي للسقالات باستخدام Laravel Breeze.
php ^8.0 و laravel/framework ^9.0.0 | ^10.0.0 مثبت في مشروعك.chrome >= 80 أو edge >= 80 أو firefox >= 74 أو ما يعادله. انظر التفاصيل هنا.افتح محطة، وتأكد من وجودك في دليل مشروع Laravel الخاص بك.
قم بتثبيت هذه الحزمة باستخدام الأمر التالي:
composer require basement-chat/basement-chat
ابدأ في دمج basement chat مع تطبيق Laravel الخاص بك:
php artisan basement:install
سيقوم الأمر أعلاه بنشر ملفات التكوين والأصول والترحيل إلى تطبيق Laravel الخاص بك. ومن ناحية أخرى، سيطرح عليك أيضًا أسئلة تفاعلية لتشغيل عمليات ترحيل قاعدة البيانات ويطلب منك تثبيت برنامج تشغيل البث الذي ستستخدمه.
اختيار برنامج تشغيل البث
قبل تحديد برنامج تشغيل البث، تحتاج إلى التأكد من تمكين BroadcastServiceProvider::class عن طريق إلغاء التعليق عليه أو إضافته إلى providers في config/app.php :
/*
* Application Service Providers...
*/
AppProvidersAppServiceProvider::class,
AppProvidersAuthServiceProvider::class,
- // AppProvidersBroadcastServiceProvider::class,
+ AppProvidersBroadcastServiceProvider::class,
AppProvidersEventServiceProvider::class,
AppProvidersRouteServiceProvider::class,ثم يمكنك اختيار أحد برامج التشغيل التالية:
إذا فاتتك تثبيت برنامج التشغيل عن طريق الخطأ في الخطوة السابقة، فيمكنك تثبيته مرة أخرى باستخدام أمر
php artisan basement:install driver.
بعد إنشاء قناة جديدة في حساب Pusher، تحتاج إلى تكوين Laravel .env من خلال توفير التكوينات ذات الصلة:
BASEMENT_BROADCAST_DRIVER =pusher
BROADCAST_DRIVER =pusher
PUSHER_APP_ID =<replace-with-your-pusher-app-id>
PUSHER_APP_KEY =<replace-with-your-pusher-key>
PUSHER_APP_SECRET =<replace-with-your-pusher-secret>
PUSHER_APP_CLUSTER =<replace-with-your-pusher-cluster> قم بتوفير التكوينات ذات الصلة في .env الخاص بك بعد إنشاء تطبيق جديد في حساب Ably الخاص بك:
BASEMENT_BROADCAST_DRIVER =ably
BROADCAST_DRIVER =ably
ABLY_KEY =<replace-with-your-ably-key>
ABLY_PUBLIC_KEY =<replace-with-your-ably-public-key> قم بتكوين .env الخاص بك أولاً بالتكوين التالي:
BASEMENT_BROADCAST_DRIVER =soketi
BROADCAST_DRIVER =pusher
PUSHER_APP_ID =app-id
PUSHER_APP_KEY =app-key
PUSHER_APP_SECRET =app-secret
PUSHER_HOST =127.0.0.1
PUSHER_PORT =6001
PUSHER_SCHEME =httpبعد ذلك، استمر في تشغيل خادم Soketi باستخدام الأمر التالي عندما تريد استخدام ميزات الدردشة في تطبيقك:
npx soketi start
كما هو الحال مع Soketi، تحتاج إلى تكوين .env أولاً بالتكوين التالي:
BASEMENT_BROADCAST_DRIVER =laravel-websockets
BROADCAST_DRIVER =pusher
PUSHER_APP_ID =app-id
PUSHER_APP_KEY =app-key
PUSHER_APP_SECRET =app-secret
PUSHER_HOST =127.0.0.1
PUSHER_PORT =6001
PUSHER_SCHEME =httpبعد ذلك، استمر في تشغيل خادم Laravel Websockets باستخدام الأمر التالي عندما تريد استخدام ميزات الدردشة في تطبيقك:
php artisan websockets:serve
قم بتكوين نطاقات Sanctum Stateful الخاصة بك
نظرًا لأن هذه الحزمة تستخدم Laravel Sanctum كنظام المصادقة الأساسي، فسوف تحتاج إلى تكوين .env الخاص بك لاستخدام SANCTUM_STATEFUL_DOMAINS المكافئ مع النطاق الذي تستخدمه حاليًا:
SANCTUM_STATEFUL_DOMAINS=<your-app-domain>
مثال:
basement.up.railway.app،127.0.0.1:8080
ينفذ وظيفة basement chat لنموذج المستخدم الخاص بك
في نموذج المستخدم الخاص بك (يستخدم بشكل افتراضي app/Models/User.php )، قم بتعديله بحيث يطبق BasementChatBasementContractsUser ويستخدم سمة BasementChatBasementTraitsHasPrivateMessages
<?php
namespace AppModels;
+ use BasementChatBasementContractsUser as BasementUserContract;
+ use BasementChatBasementTraitsHasPrivateMessages;
...
- class User extends Authenticatable
+ class User extends Authenticatable implements BasementUserContract
{
+ use HasPrivateMessages;
...
}تحميل مكون basement chat في وجهات نظرك
لإضافة مكون مربع دردشة، قم بتحميله في ملف عرض .blade حيث قام المستخدم بتسجيل الدخول بالفعل . على سبيل المثال، إذا كنت تستخدم Laravel Breeze، فيجب أن يكون المسار في resources/views/layouts/app.blade.php . ثم أضف السطر <x-basement::chat-box /> قبل علامة الإغلاق </body> .
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>اختيار كيفية استخدام أصول الواجهة الأمامية
هناك طريقتان لاستخدام أصول الواجهة الأمامية لهذه الحزمة. يمكنك استخدام واحد مما يلي:
link والبرنامج script مباشرةً هذه هي أبسط طريقة لدمج أصول الواجهة الأمامية basement chat مع تطبيق Laravel الموجود لديك. لاحظ أن هذه الحزمة تقوم أيضًا بتعيين الحزم التالية لكائن window العامة الخاص بك:
window.Alpinewindow.axioswindow.Pusherwindow.Echo في نفس الملف مثل الخطوة السابقة التي أضافت مكون مربع الدردشة، تحتاج إلى تحميل ملفات basement chat .css و .js الموجودة في الطابق السفلي:
<!DOCTYPE html>
<html lang="en">
<head>
...
+ <link rel="stylesheet" href="{{ asset('vendor/basement/basement.bundle.min.css') }}">
</head>
<body>
...
<x-basement::chat-box />
+ <script src="{{ asset('vendor/basement/basement.bundle.min.js') }}"></script>
</body>
</html> يمكنك أيضًا استيراد مكتبة basement chat كوحدة نمطية إلى ملف .js الخاص بك وتجميعها بنفسك.
أولاً، تأكد من تعيين الحزم التالية لكائن window العامة:
alpinejs@^3 مع البرنامج المساعد @alpinejs/intersect@^3 كـ window.Alpineaxios@^1 كـ window.axioslaravel-echo@^1 window.Echopusher-js@^7 window.Pusher Pusherلتثبيت التبعيات المذكورة أعلاه تلقائيًا، يمكنك استخدام الأمر التالي:
php artisan basement:install frontend_deps
بعد ذلك، تحتاج إلى استيراد الوحدات التالية:
vendor/basement-chat/basement-chat/dist/basement.bundle.min.cssvendor/basement-chat/basement-chat/dist/basement.plugin.esm كمكون إضافي لـ Alpine.jsvendor/basement-chat/basement-chat/dist/basement.echo-options.esm كوسيطة Laravel Echoيمكنك تغيير اللاحقة
.esmإلى.commonإذا كنت تستخدم وحدة cjs بدلاً من esm.
سيكون المثال العملي بالكامل داخل resources/js/app.js كما يلي:
import '../../vendor/basement-chat/basement-chat/dist/basement.bundle.min.css'
import axios from 'axios'
import Pusher from 'pusher-js'
import Echo from 'laravel-echo'
import Alpine from 'alpinejs'
import intersect from '@alpinejs/intersect'
import echoOptions from '../../vendor/basement-chat/basement-chat/dist/basement.echo-options.esm'
import basement from '../../vendor/basement-chat/basement-chat/dist/basement.plugin.esm'
window . axios = axios
window . Pusher = Pusher
window . Echo = new Echo ( echoOptions )
window . Alpine = Alpine
window . Alpine . plugin ( intersect )
window . Alpine . plugin ( basement )
window . Alpine . start ( ) تنشر هذه الحزمة ملف تكوين config/basement.php وتوفر خيارات لتكوين broadcaster و chat_box_widget_position و user_model avatar middleware . راجع هذا الملف للحصول على معلومات أكثر تفصيلاً حول ما يمكنك تكوينه.
بخلاف التهيئة من خلال ملف config/basement.php ، يمكنك التخصيص بشكل أكبر عن طريق تغيير تطبيق الفئة أو تجاوز الطريقة الافتراضية. دعنا نستكشف بعض حالات الاستخدام التي يمكنك القيام بها باستخدام هذه الميزة:
بشكل افتراضي، ستعرض حزمة basement chat الاسم الكامل للمستخدم في قائمة جهات الاتصال الخاصة بك. إذا كنت تريد إظهار الاسم الأخير بدلاً من ذلك، فيمكنك تجاوز getNameAttribute كما في المثال التالي:
<?php
namespace App Models ;
use BasementChat Basement Contracts User as BasementUserContract ;
use BasementChat Basement Traits HasPrivateMessages ;
class User extends Authenticatable implements BasementUserContract
{
use HasPrivateMessages;
. . .
/**
* Get the user's last name instead of the user's full name.
*/
public function getNameAttribute(): string
{
return str ( $ this -> attributes [ ' name ' ])-> explode ( ' ' )-> last ();
}
} كما هو الحال عندما تقوم بتغيير الاسم الظاهر في جهات الاتصال. يمكنك أيضًا تجاوز getAvatarAttribute الافتراضي لتغيير الصورة الرمزية لجهة الاتصال الخاصة بك.
<?php
namespace App Models ;
use BasementChat Basement Contracts User as BasementUserContract ;
use BasementChat Basement Traits HasPrivateMessages ;
class User extends Authenticatable implements BasementUserContract
{
use HasPrivateMessages;
. . .
/**
* Get the user's avatar url.
*/
public function getAvatarAttribute(): string
{
return $ this -> attributes [ ' image_url ' ];
}
} بدلاً من توفير ميزة الدردشة لجميع المستخدمين المتاحين، يمكنك أيضًا توفير ميزة الدردشة بشكل مشروط لمستخدمين محددين. على سبيل المثال، إذا كنت تستخدم إذن spatie/laravel وتريد توفير ميزة الدردشة لدور administrator فقط:
// app/Actions/AllContacts.php
<?php
namespace App Actions ;
use App Models User ;
use BasementChat Basement Actions AllContacts as BasementAllContactsAction ;
use BasementChat Basement Data ContactData ;
use Illuminate Contracts Auth Authenticatable ;
use Illuminate Database Eloquent Builder as EloquentBuilder ;
use Illuminate Database Eloquent Collection as EloquentCollection ;
use Illuminate Support Collection ;
class AllContacts extends BasementAllContactsAction
{
/**
* Extend and override the default method for getting all contacts.
* Only users with the administrator role will appear in the contact list.
*/
public function all ( Authenticatable $ user ): Collection
{
/** @var EloquentCollection<int,User> $contacts */
$ contacts = User:: addSelectLastPrivateMessageId ( $ user )
-> addSelectUnreadMessages ( $ user )
-> whereHas ( ' roles ' , function ( EloquentBuilder $ query ): void {
$ query -> where ( ' name ' , ' administrator ' );
})
-> get ();
$ contacts -> append ( ' avatar ' );
$ contacts -> load ( ' lastPrivateMessage ' );
return $ contacts
-> sortByDesc ( ' lastPrivateMessage.id ' )
-> values ()
-> map ( fn ( Authenticatable $ contact ): ContactData => $ this -> convertToContactData ( $ contact ));
}
} // app/Providers/AppServiceProvider.php
<?php
namespace App Providers ;
use App Actions AllContacts ;
use BasementChat Basement Basement ;
use Illuminate Support ServiceProvider ;
class AppServiceProvider extends ServiceProvider
{
...
/**
* Bootstrap any application services.
*/
public function boot (): void
{
// Override the default action with your customized AllContacts action.
Basement:: allContactsUsing (AllContacts::class);
}
}فيما يلي قائمة بالوظائف التي يمكنك استخدامها لتجاوز الإجراءات والنماذج الأخرى:
Basement:: useUserModel (User::class); Basement:: usePrivateMessageModel (PrivateMessage::class); PrivateMessage:: observe (PrivateMessageObserver::class); Basement:: allContactsUsing (AllContacts::class); Basement:: allPrivateMessagesUsing (AllPrivateMessages::class); Basement:: markPrivateMessagesAsReadUsing (MarkPrivatesMessagesAsRead::class); Basement:: sendPrivateMessagesUsing (SendPrivateMessage::class);
<!-- resources/views/layouts/app.blade.php -->
<!DOCTYPE html >
< html lang =" en " >
< head >
...
</ head >
< body >
...
<!-- The chat box component button will only be available if the current user is an administrator -->
@role('administrator')
< x-basement::chat-box />
@endrole
</ body >
</ html >من الممكن أيضًا تخصيص نمط العرض. على سبيل المثال، يمكنك القيام بالخطوات التالية لتغيير لون رأس وأيقونة مكون مربع الدردشة:
نشر طرق العرض باستخدام الأمر التالي:
php artisan vendor:publish --tag=basement-views
افتح الملف resources/views/vendor/basement/components/organisms/header.blade.php ، وأضف سمة النمط كما يلي:
<header {{ $attributes->merge([
'class' => 'bm-grid bm-grid-cols-5 bm-border-b bm-border-gray-300 bm-p-3 bm-bg-blue-500 bm-text-white bm-rounded-t-md',
+ 'style' => 'background-color: cornflowerblue;',
]) }}>
...
</header> افتح ملف resources/views/vendor/basement/chat-box.blade.php ، وأضف نمط لون النص:
<div class="basement">
<div ...>
<button
+ style="color: cornflowerblue"
x-on:click="isMinimized = false"
x-bind:class="isMinimized === true ? '' : 'bm-hidden'"
x-bind:data-title="totalUnreadMessages === 0 ? 'Open chat box' : `There are ${totalUnreadMessages} unread messages`"
class="basement-chat-box__open-button bm-w-full bm-h-full bm-rounded-full bm-text-blue-500 bm-border bm-bg-white bm-transition bm-duration-500 hover:bm-text-white hover:bm-bg-blue-500 bm-shadow-lg">
...
</button>
...
</div>
</div> عند استخدام الأصول المجمعة مسبقًا. في كل مرة بعد تحديث هذه الحزمة composer update ، تحتاج إلى تحديث ملف الأصول الخاص بك باستخدام الأمر التالي:
php artisan vendor:publish --tag=basement-assets --force
بدلاً من ذلك، لتشغيل الأمر أعلاه تلقائيًا بعد تنفيذ أمر update ، يمكنك تكوين composer.json عن طريق إضافته إلى البرامج post-update-cmd :
"scripts": {
"post-update-cmd": [
"@php artisan vendor:publish --tag=laravel-assets --ansi --force",
+ "@php artisan vendor:publish --tag=basement-assets --ansi --force"
]
}, عندما تستخدم خادم تطوير Vite وتحصل على استخدام عالي جدًا للذاكرة، يمكنك تكوين vite.config.js الخاص بك لتجاهل مشاهدة مجلد البائع مثل المثال التالي:
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
+ server: {
+ watch: {
+ ignored: [
+ './vendor/**',
+ ],
+ },
+ },
}); قد تفشل حزمة basement chat في البدء وقد تحصل على خطأ 403 Forbidden - HTTP عند الوصول إلى نقطة نهاية broadcasting/auth في وحدة تحكم المتصفح عند استخدام أمر php artisan route:cache . لا يزال حل هذه المشكلة قيد مزيد من البحث، ونوصي بعدم استخدام ميزة التخزين المؤقت للمسار في الوقت الحالي.
يرجى زيارة الصفحة التالية لعرض خريطة طريق basement chat .
يمكنك التحقق من المعلومات التفصيلية حول دليل المساهمة في الصفحة التالية.
حزمة basement chat مرخصة بموجب ترخيص MIT.
