Documentation of New Features, Improvements in Package installation (#30)

coolsam726 · web-flow · commit 3daca6f49a7e · 2025-06-07T02:19:22.000+03:00
- Added documentation for the new features
- Added a method to HasComments to fetch the current thread's users for
mentions
- Updated the installation command to back up the config file before
publishing a new one during upgrades
diff --git a/README.md b/README.md
@@ -24,6 +24,11 @@ Run the installation command and follow the prompts:
 ```bash
 php artisan nested-comments:install
 ```
+During the installation, you will be asked if you would like to publish and replace the config file.
+This is important especially if you are upgrading the package to a newer version in which the config file structure has changed.
+No worries, if you have customizations in your config file that you would like to keep, your current config file will be backed up to `config/nested-comments.php.bak` before the new config file is published.
+
+You will also be asked if you would like to re-publish the package's assets. This is also important in case the package's styles and scripts have changed in the new version.
 
 Adjust the configuration file as necessary, then run migrations.
 
@@ -210,8 +215,9 @@ $record = Conference::find(1); // Get your record from the database then,
 ```
 
 ### Mentions
-The package uses Filament TipTap Editor which supports mentions. You can mention users in your comments by typing `@` followed by the user's name. The package will automatically resolve the user and send them a notification.
-You can customize how to fetch mentions by changing the `.closures.getMentionsUsing` closure in the config file. Two sample methods have been included in the main class for getting all users in the DB or only users that have been mentioned in the current thread (default). Customize this however you wish.
+The package uses Filament TipTap Editor which supports mentions. You can mention users in your comments by typing `@` followed by the user's name.
+In the future, the package will support sending notifications to the mentioned users via database notifications if supported.
+For more on how to customize the mentions, see the [Package Customization](#customize-how-to-get-the-mention-items) section below.
 
 **Get only users mentioned in the current thread:**
 
@@ -327,7 +333,70 @@ The two components can be used anywhere, in resource pages, custom pages, action
 
 ## Package Customization
 You can customize the package by changing most of the default values in the config file after publishing it.
+Additionally, you can customize how the package interacts with your models by overriding some methods in your commentable model.
+
+### Customize how to get the Comment Author's Name
+You can customize how to get the comment author's name by overriding the `getUserName` method in your commentable model.
+By default, the package uses the `name` attribute of the user model, but you can change this to any other attribute or method that returns a string.
+
+This name will be displayed in the comment card, and it will also be used to mention the user in the comment text.
+
+```php
+// e.g in your Post model or any other model that uses the HasComments trait
+use Coolsam\NestedComments\Traits\HasComments;
+
+public function getUserName(Model|Authenticatable|null $user): string
+{
+    return $user?->getAttribute('username') ?? $user?->getAttribute('guest_name') ?? 'Guest';
+}
+```
+
+### Customize the User's Avatar
+You can customize the user's avatar by overriding the `getUserAvatar` method in your commentable model.
+
+By default, the package uses [ui-avatars](https://ui-avatars.com) to generate the avatar based on the user's name, but you can change this to any other method that returns a URL to the user's avatar image.
+
+```php
+// e.g in your Post model or any other model that uses the HasComments trait
+use Coolsam\NestedComments\Traits\HasComments;
 
+public function getUserAvatar(Model|Authenticatable|string|null $user): ?string
+{
+//    return 'https://yourprofile.url.png';
+    return $user->getAttribute('profile_url') // get your user's profile url here, assuming you have defined it in your user's model.
+}
+```
+
+### Customize how to get the Mention Items
+You can customize how to get the mention items by overriding and changing the `getMentionsQuery` method in your commentable model.
+By default, the package gets mention items from all users in your database. 
+For example, if you would only like to mention users who have commented on the current thread, you can do so by changing the method to return only those users.
+There is a handy method included in the default class to achieve this. Alternatively, you can go wild and mention fruits instead of users! The choice is within your freedom.
+
+```php
+// e.g in your Post model or any other model that uses the HasComments trait
+use Coolsam\NestedComments\Traits\HasComments;
+
+public function getMentionsQuery(string $query): Builder
+{
+    return app(NestedComments::class)->getCurrentThreadUsersQuery($query, $this);
+}
+```
+
+### Customize the Supported Emoji Reactions
+You can customize the supported emoji reactions by changing the `reactions` array in the config file.
+Decent defaults are provided, but you can change them to any emojis you prefer.
+
+```php
+return [
+    '👍',
+    '❤️',
+    '😂',
+    '😮',
+    '😢',
+    '😡',
+];
+```
 ## Testing
 
 ```bash
diff --git a/src/NestedComments.php b/src/NestedComments.php
@@ -7,6 +7,7 @@
 use FilamentTiptapEditor\Data\MentionItem;
 use Illuminate\Contracts\Auth\Authenticatable;
 use Illuminate\Contracts\View\Factory;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Foundation\Application;
 use Illuminate\Support\Facades\Auth;
@@ -100,7 +101,7 @@ public function getUserMentions(string $query): array
             })->toArray();
     }
 
-    public function getUserMentionsQuery(string $query): \Illuminate\Database\Eloquent\Builder
+    public function getUserMentionsQuery(string $query): Builder
     {
         $userModel = config('nested-comments.models.user', config('auth.providers.users.model', 'App\\Models\\User'));
 
@@ -109,7 +110,22 @@ public function getUserMentionsQuery(string $query): \Illuminate\Database\Eloque
             ->orWhere('email', 'like', "%{$query}%");
     }
 
-    public function getCurrentThreadUsers(string $searchQuery, $commentable): mixed
+    public function getCurrentThreadUsers(string $searchQuery, $commentable): array
+    {
+        return $this->getCurrentThreadUsersQuery($searchQuery, $commentable)
+            ->take(20)
+            ->get()
+            ->map(function ($user) {
+                return new MentionItem(
+                    id: $user->getKey(),
+                    label: $this->getUserName($user),
+                    image: $this->getDefaultUserAvatar($user),
+                    roundedImage: true,
+                );
+            })->toArray();
+    }
+
+    public function getCurrentThreadUsersQuery(string $searchQuery, $commentable): Builder
     {
         $userModel = config('nested-comments.models.user', config('auth.providers.users.model', 'App\\Models\\User'));
         $ids = [];
@@ -123,17 +139,7 @@ public function getCurrentThreadUsers(string $searchQuery, $commentable): mixed
                 fn ($q) => $q
                     ->where('name', 'like', "%{$searchQuery}%")
                     ->orWhere('email', 'like', "%{$searchQuery}%")
-            )
-            ->take(20)
-            ->get()
-            ->map(function ($user) {
-                return new MentionItem(
-                    id: $user->getKey(),
-                    label: $this->getUserName($user),
-                    image: $this->getDefaultUserAvatar($user),
-                    roundedImage: true,
-                );
-            })->toArray();
+            );
     }
 
     public function renderCommentsComponent(Model $record): \Illuminate\Contracts\View\View | Application | Factory | View
diff --git a/src/NestedCommentsServiceProvider.php b/src/NestedCommentsServiceProvider.php
@@ -25,6 +25,8 @@
 use Spatie\LaravelPackageTools\Package;
 use Spatie\LaravelPackageTools\PackageServiceProvider;
 
+use function Laravel\Prompts\confirm;
+
 class NestedCommentsServiceProvider extends PackageServiceProvider
 {
     public static string $name = 'nested-comments';
@@ -44,14 +46,20 @@ public function configurePackage(Package $package): void
                 $command
                     ->startWith(function (Command $command) {
                         $command->comment('Publishing config file...');
-                        $forceConfig = $command->confirm(__('Do you want to override existing config file?'), false);
-                        Artisan::call('vendor:publish', [
-                            '--tag' => 'nested-comments-config',
-                            '--force' => $forceConfig,
-                        ]);
-                        $command->info('Config file published successfully.');
-
-                        $forceAssets = $command->confirm(__('Do you want to override existing assets with new assets?'), true);
+                        if (confirm(__('Do you want to publish and overwrite the config file? (The existing file will be backed up to .bak)'))) {
+                            // check if the config file exists and back it up by copying to .bak
+                            if (file_exists(config_path('nested-comments.php'))) {
+                                $command->info('Backing up existing config to .bak file');
+                                // copy the config file to .bak
+                                copy(config_path('nested-comments.php'), config_path('nested-comments.php.bak'));
+                            }
+                            $command->call('vendor:publish', [
+                                '--tag' => 'nested-comments-config',
+                                '--force' => true,
+                            ]);
+                        }
+
+                        $forceAssets = confirm(__('Do you want to override existing assets with new assets? (important if you are doing an upgrade)'), true);
                         if ($forceAssets) {
                             // Delete the existing assets in public/css/coolsam and public/js/coolsam
                             $filesystem = app(Filesystem::class);
@@ -60,6 +68,7 @@ public function configurePackage(Package $package): void
                             Artisan::call('filament:assets');
                         }
                     })
+                    ->publishConfigFile()
                     ->publishAssets()
                     ->publishMigrations()
                     ->askToRunMigrations()
