basement chat
v1.1.1
Добавьте виджет чата в реальном времени в свое приложение Laravel.
С помощью этого пакета вы можете повысить вовлеченность пользователей, улучшить совместную работу и облегчить мгновенное общение в существующем приложении Laravel, предоставляя легко интегрированные динамические и интерактивные функции виджета чата в реальном времени.
Название «Подвал» было вдохновлено личным чатом Эйча из «Первому игроку приготовиться».
Вот демо со скаффолдингом с использованием Laravel Breeze.
php ^8.0 и laravel/framework ^9.0.0 | ^10.0.0 установлен в вашем проекте.chrome >= 80 , edge >= 80 , firefox >= 74 или эквивалент. Подробности смотрите здесь.Откройте терминал и убедитесь, что вы находитесь в каталоге проекта Laravel.
Установите этот пакет с помощью следующей команды:
composer require basement-chat/basement-chat
Начните интегрировать basement chat с вашим приложением Laravel:
php artisan basement:install
Приведенная выше команда опубликует файлы конфигурации, ресурсов и миграции в вашем приложении Laravel. С другой стороны, он также задаст вам интерактивные вопросы для запуска миграции базы данных и попросит установить, какой драйвер широковещания вы будете использовать.
Выбор драйвера трансляции
Прежде чем выбирать драйвер широковещания, вам необходимо убедиться, что BroadcastServiceProvider::class включен, раскомментировав его или добавив к своим providers в config/app.php :
/*
* Application Service Providers...
*/
AppProvidersAppServiceProvider::class,
AppProvidersAuthServiceProvider::class,
- // AppProvidersBroadcastServiceProvider::class,
+ AppProvidersBroadcastServiceProvider::class,
AppProvidersEventServiceProvider::class,
AppProvidersRouteServiceProvider::class,Затем вы можете выбрать один из следующих драйверов:
Если вы случайно пропустили установку драйвера на предыдущем шаге, вы можете установить его снова, используя команду
php artisan basement:install driver.
После создания нового канала в учетной записи Pusher вам необходимо настроить Laravel .env предоставив соответствующие конфигурации:
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> Укажите соответствующие конфигурации в своем .env после создания нового приложения в своей учетной записи Aly:
BASEMENT_BROADCAST_DRIVER =ably
BROADCAST_DRIVER =ably
ABLY_KEY =<replace-with-your-ably-key>
ABLY_PUBLIC_KEY =<replace-with-your-ably-public-key> Сначала настройте свой .env со следующей конфигурацией:
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 =httpЗатем оставьте сервер Soketi работающим с помощью следующей команды, если вы хотите использовать функции чата в своем приложении:
npx soketi start
Как и в случае с Soketi, вам необходимо сначала настроить .env со следующей конфигурацией:
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 =httpЗатем оставьте сервер Laravel Websockets работающим с помощью следующей команды, если вы хотите использовать функции чата в своем приложении:
php artisan websockets:serve
Настройте свои домены Sanctum с отслеживанием состояния
Поскольку этот пакет использует Laravel Sanctum в качестве основной системы аутентификации, вам необходимо настроить ваш .env для использования эквивалента SANCTUM_STATEFUL_DOMAINS с доменом, который вы используете в данный момент:
SANCTUM_STATEFUL_DOMAINS=<your-app-domain>
Пример:
basement.up.railway.app,127.0.0.1:8080
Реализует функциональность basement chat для вашей пользовательской модели.
В вашей пользовательской модели (по умолчанию используется app/Models/User.php ) измените ее так, чтобы она реализовала BasementChatBasementContractsUser и использовала черту BasementChatBasementTraitsHasPrivateMessages
<?php
namespace AppModels;
+ use BasementChatBasementContractsUser as BasementUserContract;
+ use BasementChatBasementTraitsHasPrivateMessages;
...
- class User extends Authenticatable
+ class User extends Authenticatable implements BasementUserContract
{
+ use HasPrivateMessages;
...
}Загрузка компонента basement chat в ваши представления
Чтобы добавить компонент окна чата, загрузите его в файл представления .blade , где пользователь уже вошел в систему . Например, если вы используете Laravel Breeze, путь должен находиться в resources/views/layouts/app.blade.php . Затем добавьте строку <x-basement::chat-box /> перед закрывающим тегом </body> .
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>Выбор способа использования ресурсов внешнего интерфейса
Есть два способа использования ресурсов внешнего интерфейса этого пакета. Вы можете использовать одно из следующих действий:
link и теги script . Это самый простой способ интегрировать ресурсы внешнего интерфейса basement chat с существующим приложением Laravel. Обратите внимание, что этот пакет также устанавливает следующие пакеты для вашего глобального объекта window :
window.Alpinewindow.axioswindow.Pusherwindow.Echo В тот же файл, что и на предыдущем шаге, в котором был добавлен компонент окна чата, вам необходимо загрузить файлы .css и .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> Вы также можете импортировать библиотеку basement chat в виде модуля в свой собственный файл .js и связать ее самостоятельно.
Сначала убедитесь, что вы назначили следующие пакеты глобальному объекту window :
alpinejs@^3 с плагином @alpinejs/intersect@^3 в качестве window.Alpineaxios@^1 как window.axioslaravel-echo@^1 как window.Echopusher-js@^7 как window.PusherЧтобы автоматически установить вышеуказанные зависимости, вы можете использовать следующую команду:
php artisan basement:install frontend_deps
Затем вам необходимо импортировать следующие модули:
vendor/basement-chat/basement-chat/dist/basement.bundle.min.cssvendor/basement-chat/basement-chat/dist/basement.plugin.esm как плагин Alpine.jsvendor/basement-chat/basement-chat/dist/basement.echo-options.esm в качестве аргумента Laravel EchoВы можете изменить суффикс
.esmна.commonесли вы используете модуль cjs вместо esm.
Полностью рабочий пример внутри resources/js/app.js будет выглядеть следующим образом:
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 ( ) Этот пакет публикует файл конфигурации config/basement.php и предлагает параметры для настройки broadcaster , chat_box_widget_position , user_model , avatar и middleware . См. этот файл для получения более подробной информации о том, что вы можете настроить.
Помимо настройки через файл config/basement.php , вы можете выполнить дополнительную настройку, изменив реализацию класса или переопределив метод по умолчанию. Давайте рассмотрим некоторые варианты использования этой функции:
По умолчанию пакет basement chat отображает полное имя пользователя в вашем списке контактов. Если вы хотите вместо этого отображать фамилию, вы можете переопределить getNameAttribute как показано в следующем примере:
<?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 ();
}
} Например, когда вы меняете имя, отображаемое в контактах. Вы также можете переопределить getAvatarAttribute по умолчанию, чтобы изменить аватар вашего контакта.
<?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 ' ];
}
} Вместо предоставления функции чата всем доступным пользователям вы также можете условно предоставить функцию чата конкретным пользователям. Например, если вы используете spatie/laravel-permission и хотите предоставить функцию чата только для роли 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);
}
}Ниже приведен список функций, которые можно использовать для переопределения других действий и моделей:
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 >Также можно настроить стиль просмотра. Например, вы можете выполнить следующие шаги, чтобы изменить цвет заголовка и значка компонента окна чата:
Опубликуйте представления с помощью следующей команды:
php artisan vendor:publish --tag=basement-views
Откройте файл resources/views/vendor/basement/components/organisms/header.blade.php и добавьте атрибут стиля, как показано ниже:
<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> Откройте файл resources/views/vendor/basement/chat-box.blade.php и добавьте стиль цвета текста:
<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> Когда вы используете предварительно связанные ресурсы. Каждый раз после обновления этого пакета с помощью composer update вам необходимо поддерживать файл ресурсов в актуальном состоянии, используя следующую команду:
php artisan vendor:publish --tag=basement-assets --force
В качестве альтернативы, чтобы автоматически запускать указанную выше команду после выполнения команды update , вы можете настроить composer.json , добавив его в сценарии 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"
]
}, Если вы используете сервер разработки Vite и используете очень много памяти, вы можете настроить свой vite.config.js так, чтобы он игнорировал просмотр папки поставщика, как показано в следующем примере:
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
+ server: {
+ watch: {
+ ignored: [
+ './vendor/**',
+ ],
+ },
+ },
}); Пакет basement chat может не запуститься, и вы можете получить ошибку 403 Forbidden — HTTP при доступе к конечной точке broadcasting/auth в консоли браузера при использовании команды php artisan route:cache . Решение этой проблемы все еще находится в стадии изучения, поэтому мы рекомендуем вам не использовать функцию кэширования маршрутов в настоящее время.
Посетите следующую страницу, чтобы просмотреть план развития basement chat .
Вы можете проверить подробную информацию о руководстве по участию на следующей странице.
Пакет basement chat лицензируется по лицензии MIT.
