basement chat
v1.1.1
Ajoutez un widget de chat en temps réel à votre application Laravel.
Avec ce package, vous pouvez améliorer l'engagement des utilisateurs, stimuler la collaboration et faciliter la communication instantanée au sein de votre application Laravel existante en fournissant une fonctionnalité de widget de chat en temps réel dynamique et interactive parfaitement intégrée.
Le nom Basement a été inspiré par le salon de discussion privé d'Aech de Ready Player One.
Voici une démo avec un échafaudage utilisant Laravel Breeze.
php ^8.0 et laravel/framework ^9.0.0 | ^10.0.0 installé dans votre projet.chrome >= 80 , edge >= 80 , firefox >= 74 ou équivalent. Voir les détails ici.Ouvrez un terminal et assurez-vous que vous êtes dans le répertoire de votre projet Laravel.
Installez ce package à l'aide de la commande suivante :
composer require basement-chat/basement-chat
Commencez à intégrer basement chat avec votre application Laravel :
php artisan basement:install
La commande ci-dessus publiera les fichiers de configuration, d'actifs et de migration sur votre application Laravel. D'autre part, il vous posera également des questions interactives pour exécuter les migrations de bases de données et vous demandera d'installer le pilote de diffusion que vous utiliserez.
Sélection d'un pilote de diffusion
Avant de sélectionner un pilote de diffusion, vous devez vous assurer que BroadcastServiceProvider::class est activé en le décommentant ou en l'ajoutant à vos providers dans config/app.php :
/*
* Application Service Providers...
*/
AppProvidersAppServiceProvider::class,
AppProvidersAuthServiceProvider::class,
- // AppProvidersBroadcastServiceProvider::class,
+ AppProvidersBroadcastServiceProvider::class,
AppProvidersEventServiceProvider::class,
AppProvidersRouteServiceProvider::class,Ensuite, vous pouvez sélectionner l'un des pilotes suivants :
Si vous avez accidentellement manqué d'installer le pilote à l'étape précédente, vous pouvez le réinstaller à l'aide de la commande
php artisan basement:install driver.
Après avoir créé un nouveau canal dans le compte Pusher, vous devez configurer Laravel .env en fournissant les configurations appropriées :
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> Fournissez les configurations pertinentes dans votre .env après avoir créé une nouvelle application dans votre compte Ably :
BASEMENT_BROADCAST_DRIVER =ably
BROADCAST_DRIVER =ably
ABLY_KEY =<replace-with-your-ably-key>
ABLY_PUBLIC_KEY =<replace-with-your-ably-public-key> Configurez d'abord votre .env avec la configuration suivante :
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 =httpEnsuite, laissez le serveur Soketi fonctionner avec la commande suivante lorsque vous souhaitez utiliser les fonctionnalités de chat dans votre application :
npx soketi start
Semblable à Soketi, vous devez d'abord configurer .env avec la configuration suivante :
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 =httpEnsuite, laissez le serveur Laravel Websockets fonctionner avec la commande suivante lorsque vous souhaitez utiliser les fonctionnalités de chat dans votre application :
php artisan websockets:serve
Configurez vos domaines avec état Sanctum
Étant donné que ce package utilise Laravel Sanctum comme système d'authentification principal, vous devrez configurer votre .env pour utiliser l'équivalent SANCTUM_STATEFUL_DOMAINS avec le domaine que vous utilisez actuellement :
SANCTUM_STATEFUL_DOMAINS=<your-app-domain>
Exemple :
basement.up.railway.app,127.0.0.1:8080
Implémente la fonctionnalité basement chat pour votre modèle utilisateur
Dans votre modèle utilisateur (utilise par défaut app/Models/User.php ), modifiez-le pour qu'il implémente BasementChatBasementContractsUser et utilise le trait BasementChatBasementTraitsHasPrivateMessages
<?php
namespace AppModels;
+ use BasementChatBasementContractsUser as BasementUserContract;
+ use BasementChatBasementTraitsHasPrivateMessages;
...
- class User extends Authenticatable
+ class User extends Authenticatable implements BasementUserContract
{
+ use HasPrivateMessages;
...
}Chargement du composant basement chat dans vos vues
Pour ajouter un composant de boîte de discussion, chargez-le dans le fichier de vue .blade où l'utilisateur est déjà connecté . Par exemple, si vous utilisez Laravel Breeze, le chemin doit être dans resources/views/layouts/app.blade.php . Ensuite, ajoutez la ligne <x-basement::chat-box /> avant la balise de fermeture </body> .
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>Choisir la façon dont vous utilisez les ressources frontend
Il existe deux manières d'utiliser les ressources frontales de ce package. Vous pouvez utiliser l'un des éléments suivants :
link et script Il s'agit du moyen le plus simple d'intégrer les ressources frontales basement chat à votre application Laravel existante. Notez que ce bundle définit également les packages suivants sur votre objet window global :
window.Alpinewindow.axioswindow.Pusherwindow.Echo Dans le même fichier que l'étape précédente qui a ajouté le composant de boîte de discussion, vous devez charger les fichiers .css et .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> Vous pouvez également importer la bibliothèque basement chat en tant que module dans votre propre fichier .js et la regrouper vous-même.
Tout d’abord, assurez-vous d’attribuer les packages suivants à l’objet window global :
alpinejs@^3 avec le plugin @alpinejs/intersect@^3 en tant que window.Alpineaxios@^1 comme window.axioslaravel-echo@^1 comme window.Echopusher-js@^7 en tant que window.PusherPour installer automatiquement les dépendances ci-dessus, vous pouvez utiliser la commande suivante :
php artisan basement:install frontend_deps
Ensuite, vous devez importer les modules suivants :
vendor/basement-chat/basement-chat/dist/basement.bundle.min.cssvendor/basement-chat/basement-chat/dist/basement.plugin.esm en tant que plugin Alpine.jsvendor/basement-chat/basement-chat/dist/basement.echo-options.esm comme argument Laravel EchoVous pouvez remplacer le suffixe
.esmpar.commonsi vous utilisez le module cjs au lieu d'esm.
Un exemple entièrement fonctionnel dans resources/js/app.js ressemblerait à ce qui suit :
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 ( ) Ce package publie un fichier de configuration config/basement.php et propose des options pour configurer broadcaster , chat_box_widget_position , user_model , avatar et middleware . Consultez ce fichier pour des informations plus détaillées sur ce que vous pouvez configurer.
Outre la configuration via le fichier config/basement.php , vous pouvez personnaliser davantage en modifiant l'implémentation de la classe ou en remplaçant la méthode par défaut. Explorons quelques-uns des cas d'utilisation que vous pouvez réaliser avec cette fonctionnalité :
Par défaut, le package basement chat affichera le nom complet de l'utilisateur dans votre liste de contacts. Si vous souhaitez afficher le nom de famille à la place, vous pouvez remplacer getNameAttribute comme dans l'exemple suivant :
<?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 ();
}
} Comme lorsque vous modifiez le nom affiché dans les contacts. Vous pouvez également remplacer le getAvatarAttribute par défaut pour modifier l'avatar de votre contact.
<?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 ' ];
}
} Au lieu de fournir la fonctionnalité de chat à tous les utilisateurs disponibles, vous pouvez également fournir la fonctionnalité de chat sous certaines conditions à des utilisateurs spécifiques. Par exemple, si vous utilisez spatie/laravel-permission et souhaitez fournir une fonctionnalité de discussion uniquement pour le rôle 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);
}
}Voici une liste de fonctions que vous pouvez utiliser pour remplacer d'autres actions et modèles :
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 >Il est également possible de personnaliser le style d'affichage. Par exemple, vous pouvez effectuer les étapes suivantes pour modifier la couleur de l'en-tête et de l'icône d'un composant de boîte de discussion :
Publiez des vues avec la commande suivante :
php artisan vendor:publish --tag=basement-views
Ouvrez le fichier resources/views/vendor/basement/components/organisms/header.blade.php et ajoutez l'attribut de style comme suit :
<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> Ouvrez le fichier resources/views/vendor/basement/chat-box.blade.php et ajoutez le style de couleur du texte :
<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> Lorsque vous utilisez des actifs pré-regroupés. Chaque fois après la mise à jour de ce package avec composer update , vous devez maintenir votre fichier d'actifs à jour à l'aide de la commande suivante :
php artisan vendor:publish --tag=basement-assets --force
Alternativement, pour exécuter automatiquement la commande ci-dessus après l'exécution de la commande update , vous pouvez configurer composer.json en l'ajoutant aux scripts 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"
]
}, Lorsque vous utilisez le serveur de développement Vite et que vous utilisez une mémoire très élevée, vous pouvez configurer votre vite.config.js pour ignorer la surveillance du dossier du fournisseur, comme dans l'exemple suivant :
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
+ server: {
+ watch: {
+ ignored: [
+ './vendor/**',
+ ],
+ },
+ },
}); Le package basement chat peut ne pas démarrer et vous pouvez obtenir une erreur 403 Forbidden - HTTP lors de l'accès au point de terminaison broadcasting/auth dans la console du navigateur lorsque vous utilisez la commande php artisan route:cache . La solution à ce problème fait encore l'objet d'études plus approfondies. Nous vous recommandons de ne pas utiliser la fonction de mise en cache d'itinéraire pour le moment.
Veuillez visiter la page suivante pour consulter la feuille de route basement chat .
Vous pouvez consulter des informations détaillées sur le guide de contribution sur la page suivante.
Le package basement chat est sous licence MIT.
