Download the PHP package towoju5/basement-chat without Composer

basement-chat.webm

Table of Contents

• Introduction
• Features
• Demo
• Installation
• Configurations
• Advanced Customizations
• Extra Notes and Troubleshooting
• Roadmap
• Contributing
• License

Introduction

With this package, you can enhance user engagement, boost collaboration, and facilitate instant communication within your existing Laravel application by providing seamlessly integrated dynamic and interactive real-time chat widget functionality.

Features

• Real-time messages
• User's online status
• User's typing indicator
• Messages have been read status
• Configurable push notifications from the client side
• Searchable contacts and messages
• Extendable and customizable actions behavior
• Lazy loading with infinite scroll messages
• Intuitive and attractive design using TailwindCSS and Alpine.js
• Can be used with various CSS frontend frameworks such as Bootstrap and TailwindCSS without worrying about style conflicts
• Flexible broadcast driver support, Pusher, Ably, Soketi, Laravel Websockets, or any other Laravel supported broadcast driver, it's up to you to decide.

Demo

Here is a demo with scaffolding using Laravel Breeze.

Installation

Requirements:

• Server-side: php ^8.0 and laravel/framework ^9.0.0 | ^10.0.0 installed in your project.
• Client-side: chrome >= 80, edge >= 80, firefox >= 74, or equivalent. See details here.

Installation steps:

• Open a terminal, and make sure you are in your Laravel project directory.

• Install this package using the following command:

• Start integrating Basement Chat with your Laravel application:

  The above command will publish the configuration, assets, and migration files to your Laravel application. On the other hand, it will also ask interactive questions for you to run the database migrations and ask you to install which broadcast driver you will use.

• Selecting a broadcast driver

  Before selecting a broadcast driver, you need to ensure that BroadcastServiceProvider::class is enabled by uncommenting it or adding it to your providers in config/app.php:

  Then you can select one of the following drivers:

  If you accidentally missed installing the driver in the previous step, you can install it again using the php artisan basement:install driver command.

  • Pusher (Click here to expand)

  After creating a new channel in the Pusher account, you need to configure Laravel .env by providing the relevant configurations:

  • Ably (Click here to expand)

  Provide relevant configurations in your .env after creating a new app in your Ably account:

  • Soketi (Click here to expand)

  Configure your .env first with the following configuration:

  Then, keep the Soketi server running with the following command when you want to use chat features in your app:

  • Laravel Websockets (Click here to expand)

  Similar to Soketi, you need to configure .env first with the following configuration:

  Then, keep the Laravel Websockets server running with the following command when you want to use chat features in your app:

• Configure your Sanctum Stateful Domains

  Since this package uses Laravel Sanctum as the primary authentication system, you will need to configure your .env to use the equivalent SANCTUM_STATEFUL_DOMAINS with the domain you are currently using:

  Example: basement.up.railway.app, 127.0.0.1:8080

• Implements Basement Chat functionality to your user model

  In your user model (by default uses app/Models/User.php), modify it so it implements BasementChat\Basement\Contracts\User and uses BasementChat\Basement\Traits\HasPrivateMessages trait

• Loading the Basement Chat component into your views

  To add a chat box component, load it in the .blade view file where the user is already logged in. For example, if you use Laravel Breeze, the path should be in resources/views/layouts/app.blade.php. Then, add the <x-basement::chat-box /> line before the closing </body> tag.

• Choosing how you use frontend assets

  There are two ways to use the frontend assets of this package. You can use one of the following:

  • Use pre-bundled assets via the link and script tags directly

  This is the simplest way to integrate Basement Chat frontend assets with your existing Laravel application. Note that this bundle also sets the following packages to your global window object:

  • window.Alpine
  • window.axios
  • window.Pusher
  • window.Echo

  In the same file as the previous step that added the chat box component, you need to load the Basement Chat .css and .js files:

  • More robust approach by importing into a bundle

  You can also import the Basement Chat library as a module into your own .js file and bundle it yourself.

  • First, make sure you assign the following packages to the global window object:
    • alpinejs@^3 with @alpinejs/intersect@^3 plugin as window.Alpine
    • axios@^1 as window.axios
    • laravel-echo@^1 as window.Echo
    • pusher-js@^7 as window.Pusher

      To automatically install the above dependencies you can use the following command:

  • Then, you need to import the following modules:
    • vendor/basement-chat/basement-chat/dist/basement.bundle.min.css
    • vendor/basement-chat/basement-chat/dist/basement.plugin.esm as an Alpine.js plugin
    • vendor/basement-chat/basement-chat/dist/basement.echo-options.esm as a Laravel Echo argument

      You can change the .esm suffix to .common if you are using cjs module instead of esm.

  • A fully working example inside resources/js/app.js would be like the following:

Configurations

This package publishes a config/basement.php configuration file and offers options to configure broadcaster, chat_box_widget_position, user_model, avatar, and middleware. See this file for more detailed information on what you can configure.

Advanced Customizations

Other than configuring through the config/basement.php file, you can customize further by changing the class implementation or overriding the default method. Let's explore some of the use cases you can do with this feature:

Changing the name shown in the contacts

By default, the Basement Chat package will display the user's full name in your contacts list. If you want to show the last name instead, you can override the getNameAttribute as in the following example:

Using custom avatars

Like when you are changing the name shown in the contacts. You can also override the default getAvatarAttribute to change your contact's avatar.

Providing the chat feature to specific users

Instead of providing the chat feature to all available users, you can also conditionally provide the chat feature to specific users. For example, if you are using spatie/laravel-permission and want to provide a chat feature only for the administrator role:

The following is a list of functions that you can use to override other actions and models:

Customizing view styles

It is also possible to customize the view style. For example, you can do the following steps to change the color of the header and icon of a chat box component:

• Publish views with the following command:

• Open the resources/views/vendor/basement/components/organisms/header.blade.php file, and add the style attribute like the following:

• Open the resources/views/vendor/basement/chat-box.blade.php file, and add text color style:

Extra Notes and Troubleshooting

Updating package

When you are using pre-bundled assets. Every time after updating this package with composer update, you need to keep your assets file up to date using the following command:

Alternatively, to run the above command automatically after the update command is executed, you can configure composer.json by adding it to the post-update-cmd scripts:

Fixing Vite memory leaks

When you are using the Vite development server and get very high memory usage, you can configure your vite.config.js to ignore watching the vendor folder like the following example:

Broadcasting auth error when using route cache

Basement Chat package may fail to start and you may get a 403 Forbidden - HTTP Error when accessing the broadcasting/auth endpoint in the browser console when you use the php artisan route:cache command. The solution to this problem is still under further investigation, we recommend that you do not use route caching feature at this time.

Roadmap

Please visit the following page to view the Basement Chat roadmap.

Contributing

You can check detailed information about the contributing guide on the following page.

License

The Basement Chat package is licensed under the MIT license.