basement chat
v1.1.1
リアルタイム チャット ウィジェットを Laravel アプリケーションに追加します。
このパッケージを使用すると、シームレスに統合された動的でインタラクティブなリアルタイム チャット ウィジェット機能を提供することで、ユーザー エンゲージメントを強化し、コラボレーションを促進し、既存の Laravel アプリケーション内でのインスタント コミュニケーションを容易にすることができます。
Basement という名前は、『レディ・プレイヤー 1』の Aech のプライベート チャット ルームからインスピレーションを得たものです。
これは、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
Laravel アプリケーションとbasement chatの統合を開始します。
php artisan basement:install
上記のコマンドは、構成、アセット、および移行ファイルを Laravel アプリケーションに公開します。一方で、データベースの移行を実行するための対話型の質問も表示され、使用するブロードキャスト ドライバーをインストールするように求められます。
ブロードキャストドライバーの選択
ブロードキャスト ドライバーを選択する前に、 BroadcastServiceProvider::classコメントを解除するか、 config/app.phpのprovidersに追加して、それが有効になっていることを確認する必要があります。
/*
* 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> Ably アカウントで新しいアプリを作成した後、 .envで関連する構成を指定します。
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 をプライマリ認証システムとして使用するため、現在使用しているドメインと同等のSANCTUM_STATEFUL_DOMAINS使用するように.envを構成する必要があります。
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にある必要があります。次に、 </body>終了タグの前に<x-basement::chat-box />行を追加します。
<!DOCTYPE html>
<html lang="en">
<head>
...
</head>
<body>
...
+ <x-basement::chat-box />
</body>
</html>フロントエンドアセットの使用方法の選択
このパッケージのフロントエンド アセットを使用するには 2 つの方法があります。次のいずれかを使用できます。
linkとscriptタグを介して事前にバンドルされたアセットを直接使用しますこれは、 basement chatフロントエンド アセットを既存の Laravel アプリケーションと統合する最も簡単な方法です。このバンドルは次のパッケージもグローバルwindowオブジェクトに設定することに注意してください。
window.Alpinewindow.axioswindow.Pusherwindow.Echoチャット ボックス コンポーネントを追加した前の手順と同じファイルで、 basement chat .cssおよび.jsファイルをロードする必要があります。
<!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.Alpineとして使用axios@^1としてwindow.axioslaravel-echo@^1 as window.Echowindow.Pusherとしてのpusher-js@^7上記の依存関係を自動的にインストールするには、次のコマンドを使用できます。
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.js プラグインとして)vendor/basement-chat/basement-chat/dist/basement.echo-options.esmesm の代わりに cjs モジュールを使用している場合は、
.esmサフィックスを.commonに変更できます。
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ファイルを開き、次のような style 属性を追加します。
<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コマンドの実行後に上記のコマンドを自動的に実行するには、 post-update-cmdスクリプトにcomposer.jsonを追加して構成できます。
"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/**',
+ ],
+ },
+ },
});php artisan route:cacheコマンドを使用してブラウザ コンソールでbroadcasting/authエンドポイントにアクセスすると、 basement chatパッケージの開始に失敗し、403 Forbidden - HTTP エラーが発生する場合があります。この問題の解決策はまだ調査中です。現時点ではルート キャッシュ機能を使用しないことをお勧めします。
basement chatロードマップを表示するには、次のページにアクセスしてください。
投稿ガイドの詳細情報は以下のページで確認できます。
basement chatパッケージは、MIT ライセンスに基づいてライセンスされています。
