basement chat
v1.1.1
Tambahkan widget obrolan real-time ke aplikasi Laravel Anda.
Dengan paket ini, Anda dapat meningkatkan keterlibatan pengguna, meningkatkan kolaborasi, dan memfasilitasi komunikasi instan dalam aplikasi Laravel yang ada dengan menyediakan fungsionalitas widget obrolan real-time yang dinamis dan interaktif.
Nama Basement terinspirasi dari ruang obrolan pribadi Aech dari Ready Player One.
Berikut ini demo scaffolding menggunakan Laravel Breeze.
php ^8.0 dan laravel/framework ^9.0.0 | ^10.0.0 dipasang di proyek Anda.chrome >= 80 , edge >= 80 , firefox >= 74 , atau setara. Lihat detailnya di sini.Buka terminal, dan pastikan Anda berada di direktori proyek Laravel Anda.
Instal paket ini menggunakan perintah berikut:
composer require basement-chat/basement-chat
Mulai integrasikan basement chat dengan aplikasi Laravel Anda:
php artisan basement:install
Perintah di atas akan mempublikasikan file konfigurasi, aset, dan migrasi ke aplikasi Laravel Anda. Di sisi lain, ia juga akan menanyakan pertanyaan interaktif bagi Anda untuk menjalankan migrasi database dan meminta Anda menginstal driver siaran mana yang akan Anda gunakan.
Memilih driver siaran
Sebelum memilih driver siaran, Anda perlu memastikan bahwa BroadcastServiceProvider::class diaktifkan dengan menghapus komentar atau menambahkannya ke providers Anda di config/app.php :
/*
* Application Service Providers...
*/
AppProvidersAppServiceProvider::class,
AppProvidersAuthServiceProvider::class,
- // AppProvidersBroadcastServiceProvider::class,
+ AppProvidersBroadcastServiceProvider::class,
AppProvidersEventServiceProvider::class,
AppProvidersRouteServiceProvider::class,Kemudian Anda dapat memilih salah satu driver berikut:
Jika Anda tidak sengaja melewatkan instalasi driver pada langkah sebelumnya, Anda dapat menginstalnya kembali menggunakan perintah
php artisan basement:install driver.
Setelah membuat saluran baru di akun Pusher, Anda perlu mengkonfigurasi Laravel .env dengan menyediakan konfigurasi yang relevan:
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> Berikan konfigurasi yang relevan di .env Anda setelah membuat aplikasi baru di akun Ably Anda:
BASEMENT_BROADCAST_DRIVER =ably
BROADCAST_DRIVER =ably
ABLY_KEY =<replace-with-your-ably-key>
ABLY_PUBLIC_KEY =<replace-with-your-ably-public-key> Konfigurasikan .env Anda terlebih dahulu dengan konfigurasi berikut:
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 =httpKemudian, biarkan server Soketi tetap berjalan dengan perintah berikut ketika Anda ingin menggunakan fitur chat di aplikasi Anda:
npx soketi start
Mirip dengan Soketi, Anda perlu mengkonfigurasi .env terlebih dahulu dengan konfigurasi berikut:
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 =httpKemudian, biarkan server Laravel Websockets tetap berjalan dengan perintah berikut ketika Anda ingin menggunakan fitur chat di aplikasi Anda:
php artisan websockets:serve
Konfigurasikan Domain Stateful Sanctum Anda
Karena paket ini menggunakan Laravel Sanctum sebagai sistem autentikasi utama, Anda perlu mengonfigurasi .env Anda untuk menggunakan SANCTUM_STATEFUL_DOMAINS yang setara dengan domain yang sedang Anda gunakan:
SANCTUM_STATEFUL_DOMAINS=<your-app-domain>
Contoh:
basement.up.railway.app,127.0.0.1:8080
Menerapkan fungsionalitas basement chat ke model pengguna Anda
Dalam model pengguna Anda (secara default menggunakan app/Models/User.php ), modifikasi sehingga mengimplementasikan BasementChatBasementContractsUser dan menggunakan sifat BasementChatBasementTraitsHasPrivateMessages
<?php
namespace AppModels;
+ use BasementChatBasementContractsUser as BasementUserContract;
+ use BasementChatBasementTraitsHasPrivateMessages;
...
- class User extends Authenticatable
+ class User extends Authenticatable implements BasementUserContract
{
+ use HasPrivateMessages;
...
}Memuat komponen basement chat ke dalam tampilan Anda
Untuk menambahkan komponen kotak obrolan, muat di file tampilan .blade tempat pengguna sudah login . Misalnya, jika Anda menggunakan Laravel Breeze, jalurnya harus di resources/views/layouts/app.blade.php . Lalu, tambahkan baris <x-basement::chat-box /> sebelum tag </body> penutup.
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>Memilih bagaimana Anda menggunakan aset frontend
Ada dua cara untuk menggunakan aset frontend paket ini. Anda dapat menggunakan salah satu dari yang berikut ini:
link dan tag script secara langsung Ini adalah cara paling sederhana untuk mengintegrasikan aset frontend basement chat dengan aplikasi Laravel Anda yang sudah ada. Perhatikan bahwa bundel ini juga menyetel paket berikut ke objek window global Anda:
window.Alpinewindow.axioswindow.Pusherwindow.Echo Dalam file yang sama dengan langkah sebelumnya yang menambahkan komponen kotak obrolan, Anda perlu memuat file .css dan .js basement chat :
<!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> Anda juga dapat mengimpor perpustakaan basement chat sebagai modul ke dalam file .js Anda sendiri dan menggabungkannya sendiri.
Pertama, pastikan Anda menetapkan paket berikut ke objek window global:
alpinejs@^3 dengan plugin @alpinejs/intersect@^3 sebagai window.Alpineaxios@^1 sebagai window.axioslaravel-echo@^1 sebagai window.Echopusher-js@^7 sebagai window.PusherUntuk menginstal dependensi di atas secara otomatis Anda dapat menggunakan perintah berikut:
php artisan basement:install frontend_deps
Kemudian, Anda perlu mengimpor modul berikut:
vendor/basement-chat/basement-chat/dist/basement.bundle.min.cssvendor/basement-chat/basement-chat/dist/basement.plugin.esm sebagai plugin Alpine.jsvendor/basement-chat/basement-chat/dist/basement.echo-options.esm sebagai argumen Laravel EchoAnda dapat mengubah akhiran
.esmmenjadi.commonjika Anda menggunakan modul cjs, bukan esm.
Contoh yang berfungsi penuh di dalam resources/js/app.js adalah seperti berikut:
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 ( ) Paket ini menerbitkan file konfigurasi config/basement.php dan menawarkan opsi untuk mengonfigurasi broadcaster , chat_box_widget_position , user_model , avatar , dan middleware . Lihat file ini untuk informasi lebih rinci tentang apa yang dapat Anda konfigurasi.
Selain mengonfigurasi melalui file config/basement.php , Anda dapat melakukan penyesuaian lebih lanjut dengan mengubah implementasi kelas atau mengganti metode default. Mari jelajahi beberapa kasus penggunaan yang dapat Anda lakukan dengan fitur ini:
Secara default, paket basement chat akan menampilkan nama lengkap pengguna di daftar kontak Anda. Jika Anda ingin menampilkan nama belakang, Anda dapat mengganti getNameAttribute seperti pada contoh berikut:
<?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 ();
}
} Seperti saat Anda mengganti nama yang tertera di kontak. Anda juga dapat mengganti getAvatarAttribute default untuk mengubah avatar kontak Anda.
<?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 ' ];
}
} Daripada menyediakan fitur chat kepada semua pengguna yang tersedia, Anda juga dapat menyediakan fitur chat secara kondisional kepada pengguna tertentu. Misalnya, jika Anda menggunakan spatie/laravel-permission dan ingin menyediakan fitur chat hanya untuk role 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);
}
}Berikut ini adalah daftar fungsi yang dapat Anda gunakan untuk mengganti tindakan dan model lainnya:
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 >Dimungkinkan juga untuk menyesuaikan gaya tampilan. Misalnya, Anda dapat melakukan langkah-langkah berikut untuk mengubah warna header dan ikon komponen kotak obrolan:
Publikasikan tampilan dengan perintah berikut:
php artisan vendor:publish --tag=basement-views
Buka file resources/views/vendor/basement/components/organisms/header.blade.php , dan tambahkan atribut style seperti berikut:
<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> Buka file resources/views/vendor/basement/chat-box.blade.php , dan tambahkan gaya warna teks:
<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> Saat Anda menggunakan aset yang telah dipaketkan sebelumnya. Setiap kali setelah memperbarui paket ini dengan composer update , Anda harus selalu memperbarui file aset Anda menggunakan perintah berikut:
php artisan vendor:publish --tag=basement-assets --force
Alternatifnya, untuk menjalankan perintah di atas secara otomatis setelah perintah update dijalankan, Anda dapat mengonfigurasi composer.json dengan menambahkannya ke skrip 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"
]
}, Saat Anda menggunakan server pengembangan Vite dan mendapatkan penggunaan memori yang sangat tinggi, Anda dapat mengonfigurasi vite.config.js Anda untuk mengabaikan pengawasan folder vendor seperti contoh berikut:
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
+ server: {
+ watch: {
+ ignored: [
+ './vendor/**',
+ ],
+ },
+ },
}); paket basement chat mungkin gagal dimulai dan Anda mungkin mendapatkan 403 Forbidden - HTTP Error saat mengakses titik akhir broadcasting/auth di konsol browser saat Anda menggunakan perintah php artisan route:cache . Solusi untuk masalah ini masih dalam penyelidikan lebih lanjut, sebaiknya Anda tidak menggunakan fitur cache rute saat ini.
Silakan kunjungi halaman berikut untuk melihat peta jalan basement chat .
Anda dapat memeriksa informasi rinci tentang panduan berkontribusi di halaman berikut.
Paket basement chat dilisensikan di bawah lisensi MIT.
