basement chat
v1.1.1
Fügen Sie Ihrer Laravel-Anwendung ein Echtzeit-Chat-Widget hinzu.
Mit diesem Paket können Sie die Benutzereinbindung verbessern, die Zusammenarbeit fördern und die sofortige Kommunikation innerhalb Ihrer vorhandenen Laravel-Anwendung erleichtern, indem Sie nahtlos integrierte dynamische und interaktive Echtzeit-Chat-Widget-Funktionen bereitstellen.
Der Name Basement wurde von Aechs privatem Chatroom von Ready Player One inspiriert.
Hier ist eine Demo mit Gerüsten mit Laravel Breeze.
php ^8.0 und laravel/framework ^9.0.0 | ^10.0.0 in Ihrem Projekt installiert.chrome >= 80 , edge >= 80 , firefox >= 74 oder gleichwertig. Einzelheiten finden Sie hier.Öffnen Sie ein Terminal und stellen Sie sicher, dass Sie sich in Ihrem Laravel-Projektverzeichnis befinden.
Installieren Sie dieses Paket mit dem folgenden Befehl:
composer require basement-chat/basement-chat
Beginnen Sie mit der Integration basement chat in Ihre Laravel-Anwendung:
php artisan basement:install
Der obige Befehl veröffentlicht die Konfigurations-, Assets- und Migrationsdateien in Ihrer Laravel-Anwendung. Andererseits werden Ihnen auch interaktive Fragen zur Durchführung der Datenbankmigrationen gestellt und Sie werden aufgefordert, den zu verwendenden Broadcast-Treiber zu installieren.
Auswählen eines Broadcast-Treibers
Bevor Sie einen Broadcast-Treiber auswählen, müssen Sie sicherstellen, dass BroadcastServiceProvider::class aktiviert ist, indem Sie ihn auskommentieren oder ihn zu Ihren providers in config/app.php hinzufügen:
/*
* Application Service Providers...
*/
AppProvidersAppServiceProvider::class,
AppProvidersAuthServiceProvider::class,
- // AppProvidersBroadcastServiceProvider::class,
+ AppProvidersBroadcastServiceProvider::class,
AppProvidersEventServiceProvider::class,
AppProvidersRouteServiceProvider::class,Anschließend können Sie einen der folgenden Treiber auswählen:
Wenn Sie die Installation des Treibers im vorherigen Schritt versehentlich verpasst haben, können Sie ihn mit dem Befehl
php artisan basement:install drivererneut installieren.
Nachdem Sie einen neuen Kanal im Pusher-Konto erstellt haben, müssen Sie Laravel .env konfigurieren, indem Sie die relevanten Konfigurationen bereitstellen:
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> Geben Sie relevante Konfigurationen in Ihrer .env an, nachdem Sie eine neue App in Ihrem Ably-Konto erstellt haben:
BASEMENT_BROADCAST_DRIVER =ably
BROADCAST_DRIVER =ably
ABLY_KEY =<replace-with-your-ably-key>
ABLY_PUBLIC_KEY =<replace-with-your-ably-public-key> Konfigurieren Sie zunächst Ihre .env mit der folgenden Konfiguration:
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 =httpHalten Sie dann den Soketi-Server mit dem folgenden Befehl am Laufen, wenn Sie Chat-Funktionen in Ihrer App verwenden möchten:
npx soketi start
Ähnlich wie bei Soketi müssen Sie .env zunächst mit der folgenden Konfiguration konfigurieren:
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 =httpHalten Sie dann den Laravel Websockets-Server mit dem folgenden Befehl am Laufen, wenn Sie Chat-Funktionen in Ihrer App verwenden möchten:
php artisan websockets:serve
Konfigurieren Sie Ihre Sanctum Stateful Domains
Da dieses Paket Laravel Sanctum als primäres Authentifizierungssystem verwendet, müssen Sie Ihre .env so konfigurieren, dass sie die entsprechenden SANCTUM_STATEFUL_DOMAINS mit der Domäne verwendet, die Sie derzeit verwenden:
SANCTUM_STATEFUL_DOMAINS=<your-app-domain>
Beispiel:
basement.up.railway.app,127.0.0.1:8080
Implementiert basement chat Funktionalität in Ihr Benutzermodell
Ändern Sie Ihr Benutzermodell (standardmäßig app/Models/User.php ) so, dass es BasementChatBasementContractsUser implementiert und das Merkmal BasementChatBasementTraitsHasPrivateMessages verwendet
<?php
namespace AppModels;
+ use BasementChatBasementContractsUser as BasementUserContract;
+ use BasementChatBasementTraitsHasPrivateMessages;
...
- class User extends Authenticatable
+ class User extends Authenticatable implements BasementUserContract
{
+ use HasPrivateMessages;
...
}Laden der basement chat Komponente in Ihre Ansichten
Um eine Chatbox-Komponente hinzuzufügen, laden Sie sie in die .blade Ansichtsdatei , in der der Benutzer bereits angemeldet ist . Wenn Sie beispielsweise Laravel Breeze verwenden, sollte sich der Pfad in resources/views/layouts/app.blade.php befinden. Fügen Sie dann die Zeile <x-basement::chat-box /> vor dem schließenden Tag </body> hinzu.
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>Wählen Sie aus, wie Sie Frontend-Assets verwenden
Es gibt zwei Möglichkeiten, die Frontend-Assets dieses Pakets zu verwenden. Sie können eines der folgenden verwenden:
link und script Tags Dies ist die einfachste Möglichkeit, basement chat Frontend-Assets in Ihre bestehende Laravel-Anwendung zu integrieren. Beachten Sie, dass dieses Bundle auch die folgenden Pakete für Ihr globales window festlegt:
window.Alpinewindow.axioswindow.Pusherwindow.Echo In derselben Datei wie im vorherigen Schritt, in der die Chatbox-Komponente hinzugefügt wurde, müssen Sie die .css und .js Dateien basement chat laden:
<!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> Sie können die basement chat Bibliothek auch als Modul in Ihre eigene .js Datei importieren und selbst bündeln.
Stellen Sie zunächst sicher, dass Sie dem globalen window die folgenden Pakete zuweisen:
alpinejs@^3 mit @alpinejs/intersect@^3 Plugin als window.Alpineaxios@^1 als window.axioslaravel-echo@^1 als window.Echopusher-js@^7 als window.PusherUm die oben genannten Abhängigkeiten automatisch zu installieren, können Sie den folgenden Befehl verwenden:
php artisan basement:install frontend_deps
Anschließend müssen Sie die folgenden Module importieren:
vendor/basement-chat/basement-chat/dist/basement.bundle.min.cssvendor/basement-chat/basement-chat/dist/basement.plugin.esm als Alpine.js-Pluginvendor/basement-chat/basement-chat/dist/basement.echo-options.esm als Laravel Echo-ArgumentSie können das Suffix
.esmin.commonändern, wenn Sie das Modul cjs anstelle von esm verwenden.
Ein voll funktionsfähiges Beispiel in resources/js/app.js würde wie folgt aussehen:
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 ( ) Dieses Paket veröffentlicht eine Konfigurationsdatei config/basement.php und bietet Optionen zum Konfigurieren von broadcaster , chat_box_widget_position , user_model , avatar und middleware . Ausführlichere Informationen darüber, was Sie konfigurieren können, finden Sie in dieser Datei.
Neben der Konfiguration über die Datei config/basement.php können Sie weitere Anpassungen vornehmen, indem Sie die Klassenimplementierung ändern oder die Standardmethode überschreiben. Sehen wir uns einige Anwendungsfälle an, die Sie mit dieser Funktion nutzen können:
Standardmäßig zeigt das basement chat Paket den vollständigen Namen des Benutzers in Ihrer Kontaktliste an. Wenn Sie stattdessen den Nachnamen anzeigen möchten, können Sie getNameAttribute wie im folgenden Beispiel überschreiben:
<?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 ();
}
} Zum Beispiel, wenn Sie den in den Kontakten angezeigten Namen ändern. Sie können auch das standardmäßige getAvatarAttribute überschreiben, um den Avatar Ihres Kontakts zu ändern.
<?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 ' ];
}
} Anstatt die Chat-Funktion allen verfügbaren Benutzern zur Verfügung zu stellen, können Sie die Chat-Funktion auch bedingt für bestimmte Benutzer bereitstellen. Wenn Sie beispielsweise die Spatie/Laravel-Berechtigung verwenden und eine Chat-Funktion nur für die administrator bereitstellen möchten:
// 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);
}
}Im Folgenden finden Sie eine Liste von Funktionen, mit denen Sie andere Aktionen und Modelle überschreiben können:
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 >Es ist auch möglich, den Ansichtsstil anzupassen. Sie können beispielsweise die folgenden Schritte ausführen, um die Farbe der Kopfzeile und des Symbols einer Chatbox-Komponente zu ändern:
Veröffentlichen Sie Ansichten mit dem folgenden Befehl:
php artisan vendor:publish --tag=basement-views
Öffnen Sie die Datei resources/views/vendor/basement/components/organisms/header.blade.php und fügen Sie das Stilattribut wie folgt hinzu:
<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> Öffnen Sie die Datei resources/views/vendor/basement/chat-box.blade.php und fügen Sie den Textfarbstil hinzu:
<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> Wenn Sie vorgebündelte Assets verwenden. Jedes Mal, nachdem Sie dieses Paket mit composer update aktualisiert haben, müssen Sie Ihre Assets-Datei mit dem folgenden Befehl auf dem neuesten Stand halten:
php artisan vendor:publish --tag=basement-assets --force
Um den obigen Befehl automatisch nach der Ausführung des update auszuführen, können Sie alternativ composer.json konfigurieren, indem Sie es zu den post-update-cmd Skripten hinzufügen:
"scripts": {
"post-update-cmd": [
"@php artisan vendor:publish --tag=laravel-assets --ansi --force",
+ "@php artisan vendor:publish --tag=basement-assets --ansi --force"
]
}, Wenn Sie den Vite-Entwicklungsserver verwenden und eine sehr hohe Speicherauslastung haben, können Sie Ihre vite.config.js so konfigurieren, dass sie die Überwachung des Vendor-Ordners ignoriert, wie im folgenden Beispiel:
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
+ server: {
+ watch: {
+ ignored: [
+ './vendor/**',
+ ],
+ },
+ },
}); basement chat Paket startet möglicherweise nicht und Sie erhalten möglicherweise einen 403 Forbidden – HTTP-Fehler, wenn Sie in der Browserkonsole auf den broadcasting/auth -Endpunkt zugreifen, wenn Sie den Befehl php artisan route:cache verwenden. Die Lösung dieses Problems wird noch weiter untersucht. Wir empfehlen Ihnen, die Route-Caching-Funktion derzeit nicht zu verwenden.
Bitte besuchen Sie die folgende Seite, um die basement chat Roadmap anzuzeigen.
Detaillierte Informationen zum beitragenden Leitfaden finden Sie auf der folgenden Seite.
Das basement chat Paket ist unter der MIT-Lizenz lizenziert.
