basement chat
v1.1.1
Agregue un widget de chat en tiempo real a su aplicación Laravel.
Con este paquete, puede mejorar la participación del usuario, impulsar la colaboración y facilitar la comunicación instantánea dentro de su aplicación Laravel existente al proporcionar una funcionalidad de widget de chat en tiempo real, dinámico e interactivo perfectamente integrado.
El nombre del Sótano se inspiró en la sala de chat privada de Hache de Ready Player One.
Aquí hay una demostración con andamios usando Laravel Breeze.
php ^8.0 y laravel/framework ^9.0.0 | ^10.0.0 instalado en su proyecto.chrome >= 80 , edge >= 80 , firefox >= 74 o equivalente. Ver detalles aquí.Abra una terminal y asegúrese de estar en el directorio de su proyecto Laravel.
Instale este paquete usando el siguiente comando:
composer require basement-chat/basement-chat
Comience a integrar basement chat con su aplicación Laravel:
php artisan basement:install
El comando anterior publicará los archivos de configuración, activos y migración en su aplicación Laravel. Por otro lado, también le hará preguntas interactivas para ejecutar las migraciones de la base de datos y le pedirá que instale qué controlador de transmisión utilizará.
Seleccionar un controlador de transmisión
Antes de seleccionar un controlador de transmisión, debe asegurarse de que BroadcastServiceProvider::class esté habilitado descomentándolo o agregándolo a sus providers en config/app.php :
/*
* Application Service Providers...
*/
AppProvidersAppServiceProvider::class,
AppProvidersAuthServiceProvider::class,
- // AppProvidersBroadcastServiceProvider::class,
+ AppProvidersBroadcastServiceProvider::class,
AppProvidersEventServiceProvider::class,
AppProvidersRouteServiceProvider::class,Luego puede seleccionar uno de los siguientes controladores:
Si accidentalmente no instaló el controlador en el paso anterior, puede instalarlo nuevamente usando el comando
php artisan basement:install driver.
Después de crear un nuevo canal en la cuenta Pusher, debe configurar Laravel .env proporcionando las configuraciones relevantes:
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> Proporcione configuraciones relevantes en su .env después de crear una nueva aplicación en su cuenta de Ably:
BASEMENT_BROADCAST_DRIVER =ably
BROADCAST_DRIVER =ably
ABLY_KEY =<replace-with-your-ably-key>
ABLY_PUBLIC_KEY =<replace-with-your-ably-public-key> Configure su .env primero con la siguiente configuración:
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 =httpLuego, mantenga el servidor Soketi ejecutándose con el siguiente comando cuando desee utilizar funciones de chat en su aplicación:
npx soketi start
De manera similar a Soketi, primero debe configurar .env con la siguiente configuración:
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 =httpLuego, mantenga el servidor Laravel Websockets ejecutándose con el siguiente comando cuando desee utilizar funciones de chat en su aplicación:
php artisan websockets:serve
Configure sus dominios con estado de Sanctum
Dado que este paquete utiliza Laravel Sanctum como sistema de autenticación principal, necesitará configurar su .env para usar el SANCTUM_STATEFUL_DOMAINS equivalente con el dominio que está usando actualmente:
SANCTUM_STATEFUL_DOMAINS=<your-app-domain>
Ejemplo:
basement.up.railway.app,127.0.0.1:8080
Implementa la funcionalidad basement chat en su modelo de usuario.
En su modelo de usuario (de forma predeterminada usa app/Models/User.php ), modifíquelo para que implemente BasementChatBasementContractsUser y use el rasgo BasementChatBasementTraitsHasPrivateMessages
<?php
namespace AppModels;
+ use BasementChatBasementContractsUser as BasementUserContract;
+ use BasementChatBasementTraitsHasPrivateMessages;
...
- class User extends Authenticatable
+ class User extends Authenticatable implements BasementUserContract
{
+ use HasPrivateMessages;
...
}Cargando el componente basement chat en sus vistas
Para agregar un componente de cuadro de chat, cárguelo en el archivo de vista .blade donde el usuario ya inició sesión . Por ejemplo, si usa Laravel Breeze, la ruta debe estar en resources/views/layouts/app.blade.php . Luego, agregue la línea <x-basement::chat-box /> antes de la etiqueta </body> de cierre.
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>Elegir cómo utilizar los activos de frontend
Hay dos formas de utilizar los recursos de interfaz de este paquete. Puede utilizar uno de los siguientes:
link y las etiquetas script Esta es la forma más sencilla de integrar los recursos de la interfaz basement chat con su aplicación Laravel existente. Tenga en cuenta que este paquete también establece los siguientes paquetes para su objeto window global:
window.Alpinewindow.axioswindow.Pusherwindow.Echo En el mismo archivo que en el paso anterior que agregó el componente del cuadro de chat, debe cargar los archivos .css y .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> También puede importar la biblioteca basement chat como un módulo en su propio archivo .js y agruparlo usted mismo.
Primero, asegúrese de asignar los siguientes paquetes al objeto window global:
alpinejs@^3 con el complemento @alpinejs/intersect@^3 como window.Alpineaxios@^1 como window.axioslaravel-echo@^1 como window.Echopusher-js@^7 como window.PusherPara instalar automáticamente las dependencias anteriores, puede utilizar el siguiente comando:
php artisan basement:install frontend_deps
Luego, necesita importar los siguientes módulos:
vendor/basement-chat/basement-chat/dist/basement.bundle.min.cssvendor/basement-chat/basement-chat/dist/basement.plugin.esm como complemento de Alpine.jsvendor/basement-chat/basement-chat/dist/basement.echo-options.esm como argumento de Laravel EchoPuede cambiar el sufijo
.esma.commonsi está utilizando el módulo cjs en lugar de esm.
Un ejemplo completamente funcional dentro resources/js/app.js sería como el siguiente:
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 ( ) Este paquete publica un archivo de configuración config/basement.php y ofrece opciones para configurar broadcaster , chat_box_widget_position , user_model , avatar y middleware . Consulte este archivo para obtener información más detallada sobre lo que puede configurar.
Además de configurar a través del archivo config/basement.php , puede personalizar aún más cambiando la implementación de la clase o anulando el método predeterminado. Exploremos algunos de los casos de uso que puede hacer con esta característica:
De forma predeterminada, el paquete basement chat mostrará el nombre completo del usuario en su lista de contactos. Si desea mostrar el apellido, puede anular getNameAttribute como en el siguiente ejemplo:
<?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 ();
}
} Como cuando estás cambiando el nombre que se muestra en los contactos. También puedes anular el getAvatarAttribute predeterminado para cambiar el avatar de tu contacto.
<?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 ' ];
}
} En lugar de proporcionar la función de chat a todos los usuarios disponibles, también puede proporcionar la función de chat de forma condicional a usuarios específicos. Por ejemplo, si está utilizando el permiso spatie/laravel y desea proporcionar una función de chat solo para el rol 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);
}
}La siguiente es una lista de funciones que puede utilizar para anular otras acciones y modelos:
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 >También es posible personalizar el estilo de vista. Por ejemplo, puede realizar los siguientes pasos para cambiar el color del encabezado y el ícono de un componente del cuadro de chat:
Publique vistas con el siguiente comando:
php artisan vendor:publish --tag=basement-views
Abra el archivo resources/views/vendor/basement/components/organisms/header.blade.php y agregue el atributo de estilo como el siguiente:
<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> Abra el archivo resources/views/vendor/basement/chat-box.blade.php y agregue el estilo de color del texto:
<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> Cuando utiliza activos preagrupados. Cada vez que actualice este paquete con composer update , deberá mantener actualizado su archivo de activos usando el siguiente comando:
php artisan vendor:publish --tag=basement-assets --force
Alternativamente, para ejecutar el comando anterior automáticamente después de ejecutar el comando update , puede configurar composer.json agregándolo a los 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"
]
}, Cuando utiliza el servidor de desarrollo de Vite y obtiene un uso de memoria muy alto, puede configurar su vite.config.js para ignorar la visualización de la carpeta del proveedor como en el siguiente ejemplo:
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
+ server: {
+ watch: {
+ ignored: [
+ './vendor/**',
+ ],
+ },
+ },
}); Es posible que el paquete basement chat no se inicie y es posible que obtenga un error 403 Prohibido - HTTP al acceder al punto final broadcasting/auth en la consola del navegador cuando utiliza el comando php artisan route:cache . La solución a este problema aún está bajo investigación; le recomendamos que no utilice la función de almacenamiento en caché de rutas en este momento.
Visite la siguiente página para ver la hoja de ruta basement chat .
Puede consultar información detallada sobre la guía contribuyente en la siguiente página.
El paquete basement chat tiene la licencia MIT.
