Installation & setup | laravel-comments | Spatie SPATIE laravel-comments ================ spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-comments](https://spatie.be/docs/laravel-comments/v2) Installation & setup Version v2 v1 Other versions for crawler [v2](https://spatie.be/docs/laravel-comments/v2) [v1](https://spatie.be/docs/laravel-comments/v1) - [ Introduction ](https://spatie.be/docs/laravel-comments/v2/introduction) - [ Getting a license ](https://spatie.be/docs/laravel-comments/v2/getting-a-license) - [ Requirements ](https://spatie.be/docs/laravel-comments/v2/requirements) - [ Installation & setup ](https://spatie.be/docs/laravel-comments/v2/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-comments/v2/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-comments/v2/changelog) - [ Upgrade guide ](https://spatie.be/docs/laravel-comments/v2/upgrade) - [ About us ](https://spatie.be/docs/laravel-comments/v2/about-us) Basic usage ----------- - [ Working with comments ](https://spatie.be/docs/laravel-comments/v2/basic-usage/working-with-comments) - [ Working with reactions ](https://spatie.be/docs/laravel-comments/v2/basic-usage/working-with-reactions) - [ Transforming comments ](https://spatie.be/docs/laravel-comments/v2/basic-usage/transforming-comments) - [ Sending notifications ](https://spatie.be/docs/laravel-comments/v2/basic-usage/sending-notifications) - [ Approving comments ](https://spatie.be/docs/laravel-comments/v2/basic-usage/approving-comments) - [ Listing comments in Laravel Nova ](https://spatie.be/docs/laravel-comments/v2/basic-usage/listing-comments-in-laravel-nova) Livewire components ------------------- - [ Introduction ](https://spatie.be/docs/laravel-comments/v2/livewire-components/introduction) - [ Installation ](https://spatie.be/docs/laravel-comments/v2/livewire-components/installation) - [ Using the components ](https://spatie.be/docs/laravel-comments/v2/livewire-components/using-the-components) - [ Taking care of authorization ](https://spatie.be/docs/laravel-comments/v2/livewire-components/taking-care-of-authorization) - [ Customising the views ](https://spatie.be/docs/laravel-comments/v2/livewire-components/customising-the-views) - [ Mentions ](https://spatie.be/docs/laravel-comments/v2/livewire-components/mentions) - [ Miscellaneous options ](https://spatie.be/docs/laravel-comments/v2/livewire-components/miscellaneous-options) - [ Using Markdown ](https://spatie.be/docs/laravel-comments/v2/livewire-components/using-markdown) Installation & setup ======================== ### On this page 1. [ Getting a license ](#content-getting-a-license) 2. [ Installation via Composer ](#content-installation-via-composer) 3. [ Publishing the config file ](#content-publishing-the-config-file) 4. [ Migrating the database ](#content-migrating-the-database) 5. [ Preparing your models ](#content-preparing-your-models) 6. [ Customising the code highlighting theme ](#content-customising-the-code-highlighting-theme) 7. [ Using the Livewire components ](#content-using-the-livewire-components) Getting a license ----------------------------------------------------------------------------------------------------------- In order to install Laravel comments, you'll need to [get a license](https://spatie.be/products/laravel-comments) first. Installation via Composer ----------------------------------------------------------------------------------------------------------------------------------- First, add the `satis.spatie.be` repository in your `composer.json`. ``` "repositories": [ { "type": "composer", "url": "https://satis.spatie.be" } ], ``` Next, you need to create a file called `auth.json` and place it either next to the `composer.json` file in your project, or in the composer home directory. You can determine the composer home directory on \*nix machines by using this command. ``` composer config --list --global | grep home ``` This is the content you should put in `auth.json`: ``` { "http-basic": { "satis.spatie.be": { "username": "", "password": "" } } } ``` If you are using [Laravel Forge](https://forge.laravel.com), you don't need to create the `auth.json` file manually. Instead, you can set the credentials on the Composer Package Authentication screen of your server. Fill out the fields with these values: - Repository URL: `satis.spatie.be` - Username: Fill this field with your spatie.be account email address - Password: Fill this field with your Laravel Comments license key To validate if Composer can read your `auth.json` you can run this command: ``` composer config --list --global | grep satis.spatie.be ``` If you did everything correctly, the above command should display your credentials. Now, you can install the package via composer: ``` composer require spatie/laravel-comments:^2.1 ``` Publishing the config file -------------------------------------------------------------------------------------------------------------------------------------- Optionally, you can publish the `comments` config file with this command. ``` php artisan vendor:publish --tag="comments-config" ``` This is the content of the published config file: ``` use Spatie\Comments\Notifications\ApprovedCommentNotification; use Spatie\Comments\Notifications\PendingCommentNotification; use Spatie\Comments\Actions\SendNotificationsForApprovedCommentAction; use Spatie\Comments\Actions\RejectCommentAction; use Spatie\Comments\Actions\ApproveCommentAction; use Spatie\Comments\Actions\SendNotificationsForPendingCommentAction; use Spatie\Comments\Actions\ProcessCommentAction; use Spatie\Comments\Models\Reaction; use Spatie\Comments\Models\Comment; use Spatie\Comments\CommentTransformers\MarkdownToHtmlTransformer; use Spatie\Comments\Models\CommentNotificationSubscription; use Spatie\Comments\Support\CommentSanitizer; return [ /* * These are the reactions that can be made on a comment. We highly recommend * only enabling positive ones for getting good vibes in your community. */ 'allowed_reactions' => ['👍', '🥳', '👀', '😍', '💅'], /* * You can allow guests to post comments. They will not be able to use * reactions. */ 'allow_anonymous_comments' => false, /* * A comment transformer is a class that will transform the comment text * for example from Markdown to HTML */ 'comment_transformers' => [ MarkdownToHtmlTransformer::class, ], /* * After all transformers have transformed the comment text, it will * be passed to this class to sanitize it */ 'comment_sanitizer' => CommentSanitizer::class, /* * These attributes will be allowed in the comment text. All other * attributes will be removed by the comment sanitizer. */ 'allowed_attributes' => [ // enabling this could allow for CSS clickjacking attacks: // https://github.com/spatie/laravel-comments/pull/182#issuecomment-2090665892 // 'style' => '*', ], /* * Comments need to be approved before they are shown. You can opt * to have all comments to be approved automatically. */ 'automatically_approve_all_comments' => true, 'models' => [ /* * The class that will comment on other things. Typically, this * would be a user model. */ 'commentator' => null, /* * The field to use to display the name from the commentator model. */ 'name' => 'name', /* * The model you want to use as a Comment model. It needs to be or * extend the `Spatie\Comments\Models\Comment::class` model. */ 'comment' => Comment::class, /* * The model you want to use as a React model. It needs to be or * extend the `Spatie\Comments\Models\Reaction::class` model. */ 'reaction' => Reaction::class, /* * The model you want to use as an subscription model. It needs to be or * extend the `Spatie\Comments\Models\CommentNotificationSubscription::class` model. */ 'comment_notification_subscription' => CommentNotificationSubscription::class, ], 'notifications' => [ /* * When somebody creates a comment, a notification will be sent to other persons * that commented on the same thing. */ 'enabled' => true, 'notifications' => [ 'pending_comment' => PendingCommentNotification::class, 'approved_comment' => ApprovedCommentNotification::class, ], /* * Here you can configure the notifications that will be sent via mail. */ 'mail' => [ 'from' => [ 'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'), 'name' => env('MAIL_FROM_NAME', 'Example'), ], ], ], 'pagination' => [ /* * Here you can configure the number of results to show before * pagination links are displayed. */ 'results' => 10000, /* * If you have multiple paginators on the same page, you can configure the * query string page name to avoid conflicts with the other paginator. * For example, you could set the page_name to be 'comments_page'. */ 'page_name' => 'page', /* * You can choose a different pagination theme like "simple-tailwind" or build * a custom pagination "vendor.livewire.custom-pagination" See the livewire * docs for more information: https://laravel-livewire.com/docs/2.x/pagination#custom-pagination-view */ 'theme' => 'tailwind', ], /* * Unless you need fine-grained customization, you don't need to change * these action classes. If you do change any of them, make sure that your class * extends the original action class. */ 'actions' => [ 'process_comment' => ProcessCommentAction::class, 'send_notifications_for_pending_comment' => SendNotificationsForPendingCommentAction::class, 'approve_comment' => ApproveCommentAction::class, 'reject_comment' => RejectCommentAction::class, 'send_notifications_for_approved_comment' => SendNotificationsForApprovedCommentAction::class, ], 'gravatar' => [ /* * Here you can choose which default image to show when a user does not have a Gravatar profile. * See the Gravatar docs for further information https://en.gravatar.com/site/implement/images/ */ 'default_image' => 'mp', ], ]; ``` Migrating the database -------------------------------------------------------------------------------------------------------------------------- To create the tables used by this package, you must create and run the migration. ``` php artisan vendor:publish --tag="comments-migrations" php artisan migrate ``` Preparing your models ----------------------------------------------------------------------------------------------------------------------- Comments will be associated with Eloquent models. To allow an Eloquent model to have comments associated with it, use the `Spatie\Comments\HasComments` trait on it. ``` use Illuminate\Database\Eloquent\Model; use Spatie\Comments\Models\Concerns\HasComments; class YourModel extends Model { use HasComments; } ``` By using the `HasComments` trait on your model, you are required to add these two methods on the same model. ``` /* * This string will be used in notifications on what a new comment * was made. */ public function commentableName(): string { // } /* * This URL will be used in notifications to let the user know * where the comment itself can be read. */ public function commentUrl(): string { } ``` The object that will comment on Eloquent models is called the commentator. Typically, the commentator is the `User` model in your app. If you only want to use anonymous comments, you can skip this step. You must prepare your commentator model by using the `Spatie\Comments\Models\Concerns\InteractsWithComments` trait on it, and implementing `Spatie\Comments\Models\Concerns\Interfaces\CanComment`. Here's an example for when your user model is `App\Models\User`: ``` namespace App\Models; use Illuminate\Database\Eloquent\Model; use Spatie\Comments\Models\Concerns\InteractsWithComments; use Spatie\Comments\Models\Concerns\Interfaces\CanComment; class User extends Model implements CanComment { use InteractsWithComments; } ``` You must also set the `commentator` key in the `comments` config file to this model. ``` // in the `comments` config file return [ // ... 'commentator' => App\Models\User::class, ] ``` Customising the code highlighting theme ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Code highlighting of the comments is powered by [our spatie/laravel-markdown package](https://github.com/spatie/laravel-markdown), which in its turn uses [Shiki](https://github.com/shikijs/shiki) to highlight code. You can use [any Shiki code highlighting theme](https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes) that you desire. By default `github-light`is used. To use your preferred theme, you must publish the config file of Laravel-markdown using this command: ``` php artisan vendor:publish --tag="markdown-config" ``` In the config file that gets published at `config/markdown.php` you should set the name of or path to a Shiki theme in the `theme` option. ``` // in config/markdown.php return [ 'code_highlighting' => [ /* * The name of or path to a Shiki theme * * More info: https://github.com/spatie/laravel-markdown#specifying-the-theme-used-for-code-highlighting */ 'theme' => 'github-dark', ], ``` Using the Livewire components ----------------------------------------------------------------------------------------------------------------------------------------------- If you want to use the Livewire components to render your comments, proceed to [the installation instruction of the component](https://spatie.be/docs/laravel-comments/v2/livewire-components/installation).