basement chat
v1.1.1
Adicione um widget de chat em tempo real à sua aplicação Laravel.
Com este pacote, você pode aprimorar o envolvimento do usuário, aumentar a colaboração e facilitar a comunicação instantânea dentro de seu aplicativo Laravel existente, fornecendo funcionalidade de widget de chat em tempo real dinâmico e interativo perfeitamente integrado.
O nome Basement foi inspirado na sala de chat privada de Aech do Ready Player One.
Aqui está uma demonstração com andaimes usando Laravel Breeze.
php ^8.0 e laravel/framework ^9.0.0 | ^10.0.0 instalado em seu projeto.chrome >= 80 , edge >= 80 , firefox >= 74 ou equivalente. Veja detalhes aqui.Abra um terminal e certifique-se de estar no diretório do projeto Laravel.
Instale este pacote usando o seguinte comando:
composer require basement-chat/basement-chat
Comece a integrar basement chat com sua aplicação Laravel:
php artisan basement:install
O comando acima publicará os arquivos de configuração, ativos e migração em seu aplicativo Laravel. Por outro lado, também fará perguntas interativas para você executar as migrações de banco de dados e solicitará que você instale qual driver de transmissão irá utilizar.
Selecionando um driver de transmissão
Antes de selecionar um driver de transmissão, você precisa garantir que BroadcastServiceProvider::class esteja habilitado removendo o comentário ou adicionando-o aos seus providers em config/app.php :
/*
* Application Service Providers...
*/
AppProvidersAppServiceProvider::class,
AppProvidersAuthServiceProvider::class,
- // AppProvidersBroadcastServiceProvider::class,
+ AppProvidersBroadcastServiceProvider::class,
AppProvidersEventServiceProvider::class,
AppProvidersRouteServiceProvider::class,Então você pode selecionar um dos seguintes drivers:
Se você acidentalmente perdeu a instalação do driver na etapa anterior, poderá instalá-lo novamente usando o comando
php artisan basement:install driver.
Após criar um novo canal na conta Pusher, você precisa configurar o Laravel .env fornecendo as configurações 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> Forneça configurações relevantes em seu .env após criar um novo aplicativo em sua conta 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 seu .env primeiro com a seguinte configuração:
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 =httpEm seguida, mantenha o servidor Soketi em execução com o seguinte comando quando quiser usar os recursos de chat em seu aplicativo:
npx soketi start
Semelhante ao Soketi, você precisa primeiro configurar .env com a seguinte configuração:
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 =httpEm seguida, mantenha o servidor Laravel Websockets em execução com o seguinte comando quando quiser usar recursos de chat em seu aplicativo:
php artisan websockets:serve
Configure seus domínios com estado do Sanctum
Como este pacote usa Laravel Sanctum como sistema de autenticação primário, você precisará configurar seu .env para usar o SANCTUM_STATEFUL_DOMAINS equivalente com o domínio que você está usando atualmente:
SANCTUM_STATEFUL_DOMAINS=<your-app-domain>
Exemplo:
basement.up.railway.app,127.0.0.1:8080
Implementa a funcionalidade basement chat em seu modelo de usuário
Em seu modelo de usuário (por padrão usa app/Models/User.php ), modifique-o para que ele implemente BasementChatBasementContractsUser e use BasementChatBasementTraitsHasPrivateMessages trait
<?php
namespace AppModels;
+ use BasementChatBasementContractsUser as BasementUserContract;
+ use BasementChatBasementTraitsHasPrivateMessages;
...
- class User extends Authenticatable
+ class User extends Authenticatable implements BasementUserContract
{
+ use HasPrivateMessages;
...
}Carregando o componente basement chat em suas visualizações
Para adicionar um componente de caixa de bate-papo, carregue-o no arquivo de visualização .blade onde o usuário já está logado . Por exemplo, se você usar o Laravel Breeze, o caminho deve estar em resources/views/layouts/app.blade.php . Em seguida, adicione a linha <x-basement::chat-box /> antes da tag de fechamento </body> .
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>Escolhendo como você usa ativos de front-end
Existem duas maneiras de usar os ativos frontend deste pacote. Você pode usar um dos seguintes:
link e das tags script Esta é a maneira mais simples de integrar ativos de front-end basement chat com seu aplicativo Laravel existente. Observe que este pacote também define os seguintes pacotes para seu objeto window global:
window.Alpinewindow.axioswindow.Pusherwindow.Echo No mesmo arquivo da etapa anterior que adicionou o componente da caixa de bate-papo, você precisa carregar os arquivos .css e .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> Você também pode importar a biblioteca basement chat como um módulo em seu próprio arquivo .js e agrupá-lo você mesmo.
Primeiro, certifique-se de atribuir os seguintes pacotes ao objeto window global:
alpinejs@^3 com o plugin @alpinejs/intersect@^3 como window.Alpineaxios@^1 como window.axioslaravel-echo@^1 como window.Echopusher-js@^7 como window.PusherPara instalar automaticamente as dependências acima você pode usar o seguinte comando:
php artisan basement:install frontend_deps
Então, você precisa importar os seguintes módulos:
vendor/basement-chat/basement-chat/dist/basement.bundle.min.cssvendor/basement-chat/basement-chat/dist/basement.plugin.esm como um plugin Alpine.jsvendor/basement-chat/basement-chat/dist/basement.echo-options.esm como um argumento Laravel EchoVocê pode alterar o sufixo
.esmpara.commonse estiver usando o módulo cjs em vez de esm.
Um exemplo totalmente funcional dentro resources/js/app.js seria assim:
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 pacote publica um arquivo de configuração config/basement.php e oferece opções para configurar broadcaster , chat_box_widget_position , user_model , avatar e middleware . Consulte este arquivo para obter informações mais detalhadas sobre o que você pode configurar.
Além de configurar por meio do arquivo config/basement.php , você pode personalizar ainda mais alterando a implementação da classe ou substituindo o método padrão. Vamos explorar alguns dos casos de uso que você pode fazer com esse recurso:
Por padrão, o pacote basement chat exibirá o nome completo do usuário em sua lista de contatos. Se quiser mostrar o sobrenome, você pode substituir getNameAttribute como no exemplo a seguir:
<?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 quando você altera o nome mostrado nos contatos. Você também pode substituir o getAvatarAttribute padrão para alterar o avatar do seu contato.
<?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 ' ];
}
} Em vez de fornecer o recurso de chat a todos os usuários disponíveis, você também pode fornecer condicionalmente o recurso de chat a usuários específicos. Por exemplo, se você estiver usando spatie/laravel-permission e quiser fornecer um recurso de chat apenas para a função 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);
}
}A seguir está uma lista de funções que você pode usar para substituir outras ações e 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 >Também é possível personalizar o estilo de visualização. Por exemplo, você pode executar as seguintes etapas para alterar a cor do cabeçalho e do ícone de um componente da caixa de bate-papo:
Publique visualizações com o seguinte comando:
php artisan vendor:publish --tag=basement-views
Abra o arquivo resources/views/vendor/basement/components/organisms/header.blade.php e adicione o atributo de estilo como o seguinte:
<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 o arquivo resources/views/vendor/basement/chat-box.blade.php e adicione o estilo de cor do 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> Quando você estiver usando ativos pré-agrupados. Sempre que atualizar este pacote com composer update , você precisará manter seu arquivo de ativos atualizado usando o seguinte comando:
php artisan vendor:publish --tag=basement-assets --force
Alternativamente, para executar o comando acima automaticamente após a execução do comando update , você pode configurar composer.json adicionando-o aos 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"
]
}, Quando você está usando o servidor de desenvolvimento Vite e obtém um uso de memória muito alto, você pode configurar seu vite.config.js para ignorar a observação da pasta do fornecedor, como no exemplo a seguir:
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
+ server: {
+ watch: {
+ ignored: [
+ './vendor/**',
+ ],
+ },
+ },
}); O pacote basement chat pode falhar ao iniciar e você pode obter um erro 403 Forbidden - HTTP ao acessar o endpoint broadcasting/auth no console do navegador ao usar o comando php artisan route:cache . A solução para este problema ainda está sob investigação. Recomendamos que você não use o recurso de cache de rota neste momento.
Por favor, visite a página a seguir para ver o roteiro basement chat .
Você pode verificar informações detalhadas sobre o guia de contribuição na página seguinte.
O pacote basement chat é licenciado sob a licença do MIT.
