Laravel Comments

https://github.com/beyondcode/laravel-comments
Admin
Laravel Comments is a package that allows you to associate comments to your Laravel Eloquent models,...
Tokens:22,606
Snippets:212
Trust Score:9.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### approve() usage example

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Example usage of approve() on a comment retrieved from a post, then checking is_approved.

```php
$comment = Post::find(1)->comments->first();
$comment->approve();
$comment->is_approved; // true
```

--------------------------------

### Install package via Composer

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Command to install the laravel-comments package via Composer.

```bash
composer require beyondcode/laravel-comments
```

--------------------------------

### disapprove() usage example

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Example usage of disapprove() on a comment, then checking is_approved.

```php
$comment->disapprove();
$comment->is_approved; // false
```

--------------------------------

### Run migrations

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Command to run the published migrations to create the media-table.

```bash
php artisan migrate
```

--------------------------------

### Run tests

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Command to run the package tests.

```bash
composer test
```

--------------------------------

### Example: accessing commentable relation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Shows how to retrieve the owning model via the commentable relation.

```php
$comment = Comment::find(1);
$post = $comment->commentable; // instance of Post
```

--------------------------------

### Publish migrations and run migrate

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comments-service-provider.md

Example workflow: publish the migration file and then run the migrate command to create the comments table.

```bash
php artisan vendor:publish --provider="BeyondCode\Comments\CommentsServiceProvider" --tag="migrations"
php artisan migrate
```

--------------------------------

### Example implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/commentator.md

Example User model implementing Commentator. Moderators are auto-approved; other users' comments are approved only on their own posts.

```php
namespace App\Models;

use BeyondCode\Comments\Contracts\Commentator;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements Commentator
{
    /**
     * Check if a comment for a specific model needs to be approved.
     *
     * @param  mixed  $model
     */
    public function needsCommentApproval($model): bool
    {
        // Moderators never need their comments approved:
        if ($this->isModerator) {
            return false;
        }

        // Everyone else's comments are approved only on their own posts:
        return ! ($model instanceof Post && $model->user_id === $this->id);
    }
}
```

--------------------------------

### Example: accessing commentator relation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Shows how to retrieve the user who wrote the comment, with null-safe access.

```php
$user = $comment->commentator;   // App\Models\User|null
$name = $comment->commentator?->name;
```

--------------------------------

### Approve a comment

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to approve a comment using the approve method on the Comment model.

```php
$post = Post::find(1);
$comment = $post->comments->first();

$comment->approve();
```

--------------------------------

### Using the approved scope

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Shows how to retrieve approved comments using the 'approved' scope, either directly on the model or chained on a relation. The first line gets all approved comments, the second gets approved comments for a specific post.

```php
$comments = \BeyondCode\Comments\Comment::approved()->get();

// Chained on a relation:
$approved = Post::find(1)->comments()->approved()->get();
```

--------------------------------

### Registered listener class example

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-deleted.md

Example of a listener class with a handle method that logs the deletion.

```php
// Registered listener class
class LogCommentDeletion
{
    public function handle(CommentDeleted $event): void
    {
        activity()->log("Comment #{$event->comment->id} was deleted");
    }
}
```

--------------------------------

### Basic comment creation on a model

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to add a comment to a model instance using the comment method and commentAsUser method.

```php
$post = Post::find(1);

$post->comment('This is a comment');

$post->commentAsUser($user, 'This is a comment from someone else');
```

--------------------------------

### Example: creating a comment with Auth::login()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Shows how to authenticate a user and create a comment on a Post model. In a guest context, the comment's user_id and commentator are null.

```php
use Illuminate\Support\Facades\Auth;

Auth::login($user);

$post = Post::find(1);
$comment = $post->comment('Hello world');

// Guest context — no authenticated user:
// $comment->user_id is null, $comment->commentator is null
```

--------------------------------

### Anonymous listener example

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-deleted.md

Example of registering an anonymous listener to invalidate a cache when a comment is deleted.

```php
use BeyondCode\Comments\Events\CommentDeleted;

Event::listen(function (CommentDeleted $event) {
    // e.g. invalidate a rendered comments fragment cache
    Cache::forget("comments.{$event->comment->commentable_id}");
});
```

--------------------------------

### Implement Commentator interface for auto-approval

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to implement the Commentator interface and needsCommentApproval method to control comment approval.

```php
namespace App\Models;

use BeyondCode\Comments\Contracts\Commentator;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements Commentator
{
    /**
     * Check if a comment for a specific model needs to be approved.
     * @param mixed $model
     * @return bool
     */
    public function needsCommentApproval($model): bool
    {
        return false;
    }

}
```

--------------------------------

### Create a comment using comment method

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to create a comment on a model using the comment method, which returns the newly created comment.

```php
$post = Post::find(1);

$comment = $post->comment('This is a comment from a user.');
```

--------------------------------

### Create a comment on behalf of another user

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to create a comment as a specific user using the commentAsUser method.

```php
$post = Post::find(1);

$comment = $post->commentAsUser($yourUser, 'This is a comment from someone else.');
```

--------------------------------

### Nest comments on a comment

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to comment on a comment using the commentAsUser method, enabling nesting.

```php
$comment = BeyondCode\Comments\Comment::first();
$comment->commentAsUser($user, "Hey there!");
```

--------------------------------

### Example usage of commentAsUser()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Shows how to create a comment on behalf of a specific user and an anonymous comment. The first call attributes the comment to the admin user, the second creates a comment with no user relation.

```php
$post = Post::find(1);
$admin = User::find(7);

$comment = $post->commentAsUser($admin, 'Posted on behalf of admin');

// Anonymous comment:
$anonymous = $post->commentAsUser(null, 'An anonymous comment');
```

--------------------------------

### Example: Using comments() relation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Demonstrates accessing comments as a property and chaining a query for approved comments. The relation returns a MorphMany instance; calling it as a method returns a query builder.

```php
$post = Post::find(1);

// All comments, in relation order
$comments = $post->comments;

// Chained query: only approved comments
$approved = $post->comments()->approved()->get();
```

--------------------------------

### Add HasComments trait to model

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to add the HasComments trait to an Eloquent model to enable comments.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use BeyondCode\Comments\Traits\HasComments;

class Post extends Model
{
    use HasComments;
    ...
}
```

--------------------------------

### Example: commentAsUser() with CanComment

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/can-comment.md

Shows that when a user uses CanComment, calling $post->commentAsUser() stores the comment with is_approved = false, as demonstrated by the $comment->is_approved property being false.

```php
use App\Models\User;

$user = User::first();            // uses CanComment
$post = Post::find(1);

$comment = $post->commentAsUser($user, 'needs a mod to review me');
$comment->is_approved; // false
```

--------------------------------

### Retrieve comments using the comments relation

Source: https://github.com/beyondcode/laravel-comments/blob/master/README.md

Shows how to retrieve all comments and only approved comments using the comments relation.

```php

$post = Post::find(1);

// Retrieve all comments
$comments = $post->comments;

// Retrieve only approved comments
$approved = $post->comments()->approved()->get();

```

--------------------------------

### Listener using Event::listen

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-added.md

Registers a closure listener for CommentAdded, accessing the comment, commentable, and commentator. Example shows notifying the commentable's owner if it's a Post.

```php
// In a service provider's boot() or via EventServiceProvider
use BeyondCode\Comments\Events\CommentAdded;

Event::listen(function (CommentAdded $event) {
    $comment = $event->comment;
    $commentable = $comment->commentable;
    $author = $comment->commentator;

    // e.g. notify the commentable's owner
    if ($commentable instanceof \App\Models\Post) {
        $commentable->author->notify(new NewCommentNotification($comment));
    }
});
```

--------------------------------

### Usage example: Adding HasComments to a model and creating comments

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Shows how to use the HasComments trait on an Eloquent model to enable comments, including creating a comment and a nested reply. The model must be table-backed and use the trait.

```php
namespace App.Models;

use Illuminate\Database\Eloquent\Model;
use BeyondCode\Comments\Traits\HasComments;

class Post extends Model
{
    use HasComments;
}

$post = Post::find(1);
$comment = $post->comment('This is a comment from a user.');

// Comments can also be nested because Comment itself uses HasComments:
$reply = $comment->comment('Nested reply');
```

--------------------------------

### CanComment trait implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

A ready-made Commentator implementation that always returns true for needsCommentApproval, meaning users never get auto-approved comments.

```php
trait CanComment
{
    /**
     * Check if a comment for a specific model needs to be approved.
     *
     * @param  mixed  $model
     */
    public function needsCommentApproval($model): bool
    {
        return true;
    }
}
```

--------------------------------

### User class implementing Commentator contract

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Example of a User model implementing the Commentator contract to control comment approval. The needsCommentApproval method returns true only for Post models, so comments on posts are automatically approved.

```php
class User extends Authenticatable implements Commentator
{
    public function needsCommentApproval($model): bool
    {
        return $model instanceof Post; // only approve comments on posts automatically
    }
}
```

```php
$comment = $post->commentAsUser($user, 'approved automatically'); // is_approved === true
```

--------------------------------

### boot() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comments-service-provider.md

Signature of the boot() method. It has no parameters and returns void. It only runs when runningInConsole() is true, publishing config and migration files.

```php
public function boot()
```

--------------------------------

### Comment boot() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Declares the static boot method that registers model event listeners. Called automatically by Eloquent's model booting mechanism; you normally never call it yourself.

```php
public static function boot(): void
```

--------------------------------

### Default config/config.php

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/configuration.md

The complete default configuration file for the package. It defines the comment class, user model, and whether replies are deleted with comments. The user_model defaults to null, falling back to the auth provider model.

```php
return [

    /*
     * The comment class that should be used to store and retrieve
     * the comments.
     */
    'comment_class' => \BeyondCode\Comments\Comment::class,

    /*
     * The user model that should be used when associating comments with
     * commentators. If null, the default user provider from your
     * Laravel authentication configuration will be used.
     */
    'user_model' => null,

    /**
     * Determines if replies will be deleted when comments are deleted
     */
    'delete_replies_along_comments' => false,
];
```

--------------------------------

### Comment::boot()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Boot method for the Comment model. This method is part of the Comment model and is used to set up model events.

```APIDOC
## Comment::boot()

### Description
Boot method for the Comment model. Sets up model events.

### Method
boot()

### Parameters
None

### Returns
- **void**
```

--------------------------------

### Comment boot() method implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Registers model event listeners: on deleting, deletes replies if config 'comments.delete_replies_along_comments' is true; on deleted, dispatches CommentDeleted; on created, dispatches CommentAdded. Called automatically by Eloquent's model booting mechanism.

```php
public static function boot(): void
{
    parent::boot();

    static::deleting(function (self $model) {
        if (config('comments.delete_replies_along_comments')) {
            $model->comments()->delete();
        }
    });

    static::deleted(function (self $model) {
        CommentDeleted::dispatch($model);
    });

    static::created(function (self $model) {
        CommentAdded::dispatch($model);
    });
}
```

--------------------------------

### approve() method implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Implementation of approve() that updates is_approved to true and returns the comment instance.

```php
public function approve()
{
    $this->update([
        'is_approved' => true,
    ]);

    return $this;
}
```

--------------------------------

### Publish migrations tag command

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comments-service-provider.md

Artisan command to publish the migration stub to a timestamped migration file under the 'migrations' tag. Guarded by class_exists('CreateCommentsTable') to avoid duplication.

```bash
php artisan vendor:publish --provider="BeyondCode\Comments\CommentsServiceProvider" --tag="migrations"
```

--------------------------------

### Constructor with promoted property

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-added.md

The constructor accepts a Comment instance and promotes it to a public property. No return type.

```php
public function __construct(
    public Comment $comment,
) {
}
```

--------------------------------

### Publish config tag command

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comments-service-provider.md

Artisan command to publish the package's config file to config/comments.php under the 'config' tag. Use this to customize configuration before merging.

```bash
php artisan vendor:publish --provider="BeyondCode\Comments\CommentsServiceProvider" --tag="config"
```

--------------------------------

### register() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comments-service-provider.md

Signature of the register() method. It has no parameters and returns void. It merges package config defaults into the 'comments' config key using mergeConfigFrom.

```php
public function register()
```

--------------------------------

### commentator() method implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Implements commentator() to return a belongsTo relation using the configured user model and user_id key.

```php
public function commentator()
{
    return $this->belongsTo($this->getAuthModelName(), 'user_id');
}
```

--------------------------------

### approve()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Marks the comment as approved by updating is_approved to true, then returns the comment instance.

```APIDOC
## approve()

### Description
Marks the comment as approved by updating `is_approved` to `true`, then returns the comment instance.

### Method
approve()

### Endpoint
`Comment::approve()`

### Parameters
None.

### Return type
`$this` — the same `Comment` instance (with `is_approved === true` after the reload/cast).

### Example
```php
$comment = Post::find(1)->comments->first();
$comment->approve();
$comment->is_approved; // true
```
```

--------------------------------

### commentable() method implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Implements commentable() to return the morphTo relation for the owning model.

```php
public function commentable()
{
    return $this->morphTo();
}
```

--------------------------------

### disapprove() method implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Implementation of disapprove() that updates is_approved to false and returns the comment instance.

```php
public function disapprove()
{
    $this->update([
        'is_approved' => false,
    ]);

    return $this;
}
```

--------------------------------

### CommentsServiceProvider class definition

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comments-service-provider.md

Full source of the CommentsServiceProvider class. It extends Illuminate\Support\ServiceProvider and is auto-discovered via composer.json, so no manual registration in config/app.php is needed. The boot() method publishes config and migration files only when running in console, and register() merges package config defaults under the 'comments' key.

```php
class CommentsServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap the application services.
     */
    public function boot()
    {
        if ($this->app->runningInConsole()) {
            $this->publishes([
                __DIR__.'/../config/config.php' => config_path('comments.php'),
            ], 'config');

            if (! class_exists('CreateCommentsTable')) {
                $this->publishes([
                    __DIR__.'/../database/migrations/create_comments_table.php.stub' => database_path('migrations/'.date('Y_m_d_His', time()).'_create_comments_table.php'),
                ], 'migrations');
            }
        }
    }

    /**
     * Register the application services.
     */
    public function register()
    {
        $this->mergeConfigFrom(__DIR__.'/../config/config.php', 'comments');
    }
}
```

--------------------------------

### CommentsServiceProvider

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Service provider that auto-registers the package. This provider is responsible for booting and registering package services.

```APIDOC
## CommentsServiceProvider

### Description
Service provider that auto-registers the package.

### Methods
- **boot()** - Boot the package services.
- **register()** - Register the package services.

### Publish Tags
- **config** - Publishes the configuration file.
```

--------------------------------

### approve() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Signature of the approve() method defined in src/Comment.php:59-66. Marks the comment as approved by updating is_approved to true.

```php
public function approve()
```

--------------------------------

### Testing with Event::fake

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-added.md

Fakes the CommentAdded event and asserts it was dispatched with a comment containing 'hello'.

```php
// Testing with the Laravel event fake
use Illuminate\Support\Facades\Event;

Event::fake([CommentAdded::class]);
$post->comment('hello');
Event::assertDispatched(CommentAdded::class, fn ($event) => $event->comment->comment === 'hello');
```

--------------------------------

### commentator() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Declares the commentator() method that returns a belongsTo relation to the user model.

```php
public function commentator()
```

--------------------------------

### Comment model fillable and casts attributes

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Defines the fillable attributes 'comment', 'user_id', and 'is_approved' for mass assignment, and casts 'is_approved' to boolean so relational checks like `$comment->is_approved === true` work. The 'commentable_id' and 'commentable_type' are filled via the HasComments trait.

```php
protected $fillable = [
    'comment',
    'user_id',
    'is_approved',
];

protected $casts = [
    'is_approved' => 'boolean',
];
```

--------------------------------

### commentable() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Declares the commentable() method that returns a polymorphic morphTo relation to the owning model.

```php
public function commentable()
```

--------------------------------

### Dispatch condition in Comment::boot()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-added.md

Dispatches CommentAdded for every created Comment instance, including nested replies. Not fired for generic commentable models.

```php
static::created(function (self $model) {
    CommentAdded::dispatch($model);
});
```

--------------------------------

### disapprove()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Marks the comment as not approved by updating is_approved to false, then returns the comment instance.

```APIDOC
## disapprove()

### Description
Marks the comment as not approved by updating `is_approved` to `false`, then returns the comment instance.

### Method
disapprove()

### Endpoint
`Comment::disapprove()`

### Parameters
None.

### Return type
`$this` — the same `Comment` instance (with `is_approved === false`).

### Example
```php
$comment->disapprove();
$comment->is_approved; // false
```
```

--------------------------------

### disapprove() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Signature of the disapprove() method defined in src/Comment.php:68-75. Marks the comment as not approved by updating is_approved to false.

```php
public function disapprove()
```

--------------------------------

### Comment scopeApproved() method implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Filters the query to only approved comments by adding a where clause on 'is_approved' set to true. Returns the modified query builder.

```php
public function scopeApproved($query)
{
    return $query->where('is_approved', true);
}
```

--------------------------------

### Dispatch hook in Comment::boot()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-deleted.md

Registers a deleted model event listener that dispatches CommentDeleted for each deleted Comment instance.

```php
static::deleted(function (self $model) {
    CommentDeleted::dispatch($model);
});
```

--------------------------------

### comment()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Factory method for commenting as the currently authenticated user. Creates a new Comment record attached to the model.

```APIDOC
## comment()

### Description
Factory method for commenting as the currently authenticated user. Creates a new Comment record attached to the model.

### Method
comment()

### Endpoint
N/A (Eloquent method)

### Parameters
- **message** (string) - Required - The comment text.

### Return Type
`BeyondCode\Comments\Comment`

### Example
```php
$post = Post::find(1);
$comment = $post->comment('This is a comment from a user.');
```
```

--------------------------------

### comment() delegates to commentAsUser()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Implementation of comment() that passes the authenticated user (or null) to commentAsUser(). If no user is authenticated, the comment is created with a null user_id.

```php
public function comment(string $comment)
{
    return $this->commentAsUser(auth()->user(), $comment);
}
```

--------------------------------

### needsCommentApproval($model)

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/commentator.md

Determines whether a comment the implementing user writes on the given model must be approved before display. Returns false to auto-approve the comment, or true to store it unapproved.

```APIDOC
## needsCommentApproval($model)

### Description
Determines whether a comment the implementing user writes on the given model must be approved before display. Returns false to auto-approve the comment, or true to store it unapproved.

### Method
needsCommentApproval

### Parameters
- `$model` (mixed) - Required - The commentable model instance (an Eloquent model using `HasComments`) that the comment is being attached to

### Return Type
bool

- `false` → comment auto-approved (`is_approved = true`).
- `true` → comment stored unapproved (`is_approved = false`).

### Example Implementation
```php
namespace App\Models;

use BeyondCode\Comments\Contracts\Commentator;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements Commentator
{
    /**
     * Check if a comment for a specific model needs to be approved.
     *
     * @param  mixed  $model
     */
    public function needsCommentApproval($model): bool
    {
        // Moderators never need their comments approved:
        if ($this->isModerator) {
            return false;
        }

        // Everyone else's comments are approved only on their own posts:
        return ! ($model instanceof Post && $model->user_id === $this->id);
    }
}
```
```

--------------------------------

### Catching MassAssignmentException for custom comment class

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/errors.md

When using a custom comment class that lacks required fillable attributes, Eloquent throws MassAssignmentException at save time. Catch it to handle the fillable mismatch gracefully.

```php
use Illuminate\Database\Eloquent\MassAssignmentException;

try {
    $post->comment('this will throw if the custom class is not fillable');
} catch (MassAssignmentException $e) {
    // fillable mismatch
}
```

--------------------------------

### getAuthModelName() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Signature of the protected helper getAuthModelName() defined in src/Comment.php:77-87. Resolves the user model class for the commentator() relation.

```php
protected function getAuthModelName()
```

--------------------------------

### Comment scopeApproved() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment.md

Declares the Eloquent query scope that filters to approved comments only. Registered as the 'approved' scope, so the callable syntax is `Comment::approved()` or `$relation->approved()`.

```php
public function scopeApproved($query)
```

--------------------------------

### Interface definition

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/commentator.md

Defines the Commentator interface with the needsCommentApproval() method. Implementations must return a boolean indicating whether a comment on the given model needs approval.

```php
namespace BeyondCode\Comments\Contracts;

interface Commentator
{
    /**
     * Check if a comment for a specific model needs to be approved.
     *
     * @param  mixed  $model
     */
    public function needsCommentApproval($model): bool;
}
```

--------------------------------

### commentAsUser() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Defines the method signature for creating a comment on behalf of a specific user or anonymously. The method accepts a user model or null and a comment string.

```php
public function commentAsUser(?Model $user, string $comment)
```

--------------------------------

### comment() method signature

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Declares the public method that creates a comment for the currently authenticated user. The method accepts a string comment and returns the newly created model instance.

```php
public function comment(string $comment)
```

--------------------------------

### CommentAdded event

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Event dispatched after a comment is created. This event is part of the package and is used to notify listeners when a comment is added.

```APIDOC
## CommentAdded event

### Description
Event dispatched after a comment is created.

### Properties
- **comment** (Comment) - The comment instance.
```

--------------------------------

### CommentAdded class definition

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-added.md

The CommentAdded event class implements ShouldDispatchAfterCommit and uses Dispatchable, InteractsWithSockets, and SerializesModels traits. The promoted constructor property exposes the comment via $event->comment.

```php
class CommentAdded implements ShouldDispatchAfterCommit
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    /**
     * Create a new event instance.
     */
    public function __construct(
        public Comment $comment,
    ) {
    }
}
```

--------------------------------

### Comment payload construction in commentAsUser()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Builds the comment model with approval logic based on the Commentator contract. If the user implements Commentator, approval is determined by needsCommentApproval(); otherwise defaults to false. The comment is saved via the comments relationship.

```php
$comment = new $commentClass([
    'comment' => $comment,
    'is_approved' => ($user instanceof Commentator) ? ! $user->needsCommentApproval($this) : false,
    'user_id' => is_null($user) ? null : $user->getKey(),
    'commentable_id' => $this->getKey(),
    'commentable_type' => get_class($this),
]);

return $this->comments()->save($comment);
```

--------------------------------

### Comment::approve()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Approves the comment by setting the is_approved flag to true. This method is part of the Comment model and is used for moderation.

```APIDOC
## Comment::approve()

### Description
Approves the comment by setting the is_approved flag to true.

### Method
approve()

### Parameters
None

### Returns
- **bool** - True if the approval was successful.
```

--------------------------------

### Usage in HasComments::commentAsUser()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/commentator.md

Shows how the Commentator contract is consumed in HasComments::commentAsUser() to set the 'is_approved' attribute. If the user is not a Commentator, the comment is stored unapproved; if it is, the result of needsCommentApproval() determines approval.

```php
'is_approved' => ($user instanceof Commentator) ? ! $user->needsCommentApproval($this) : false,
```

--------------------------------

### HasComments trait implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

The trait making a model commentable. Provides methods for retrieving and adding comments.

```php
trait HasComments
{
    public function comments() { /* MorphMany */ }
    public function comment(string $comment) { /* Model */ }
    public function commentAsUser(?Model $user, string $comment) { /* Model */ }
}
```

--------------------------------

### Comment Class

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

The default comment record type extending Eloquent Model. Provides methods for managing comments, including approval status and nested replies.

```APIDOC
## Comment Class

### Description
The default comment record type extending Eloquent Model. Provides methods for managing comments, including approval status and nested replies.

### Public Methods

#### comments()
- **Description**: Get the nested comments relation (replies)
- **Returns**: Relation instance

#### comment(string $comment)
- **Description**: Create a reply as the authenticated user
- **Parameters**:
  - **$comment** (string) - Required - The comment body
- **Returns**: Model instance

#### commentAsUser(?Model $user, string $comment)
- **Description**: Create a reply as a given user
- **Parameters**:
  - **$user** (?Model) - Required - The user to attribute the comment to
  - **$comment** (string) - Required - The comment body
- **Returns**: Model instance

#### scopeApproved($query)
- **Description**: Query scope filtering `is_approved = true`
- **Parameters**:
  - **$query** - Required - The query builder
- **Returns**: Query builder

#### commentable()
- **Description**: Polymorphic owner relation
- **Returns**: MorphTo relation

#### commentator()
- **Description**: BelongsTo the resolved user model
- **Returns**: BelongsTo relation

#### approve()
- **Description**: Set `is_approved = true`
- **Returns**: `$this`

#### disapprove()
- **Description**: Set `is_approved = false`
- **Returns**: `$this`

### Persisted Attributes
- **id** (increments) - Primary key, auto-increment
- **commentable_id** (polymorphic morph) - ID of the owning model
- **commentable_type** (polymorphic morph) - Class name of the owning model
- **comment** (text) - The comment body
- **is_approved** (boolean, default `false`) - Approval flag, cast to `bool`
- **user_id** (unsignedBigInteger, nullable) - Author ID; `null` for anonymous comments
- **created_at** / **updated_at** (timestamps) - Managed by Laravel
```

--------------------------------

### Commentator interface with needsCommentApproval method

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

Defines the contract for user models to control comment approval. Implement this interface to specify whether a comment on a given model requires approval. The method returns true if approval is needed, false for auto-approval.

```php
interface Commentator
{
    /**
     * Check if a comment for a specific model needs to be approved.
     *
     * @param  mixed  $model
     */
    public function needsCommentApproval($model): bool;
}
```

--------------------------------

### getAuthModelName() method throwing Exception

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/errors.md

This method determines the commentator model name from configuration. It throws a generic Exception with message 'Could not determine the commentator model name.' when neither 'comments.user_model' nor 'auth.providers.users.model' is set.

```php
protected function getAuthModelName()
{
    if (config('comments.user_model')) {
        return config('comments.user_model');
    }

    if (! is_null(config('auth.providers.users.model'))) {
        return config('auth.providers.users.model');
    }

    throw new Exception('Could not determine the commentator model name.');
}
```

--------------------------------

### Catching the undetermined commentator model exception

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/errors.md

Wrap access to the commentator relation in a try-catch to handle the case where the model name cannot be determined. The exception message is 'Could not determine the commentator model name.' and it is a PHP built-in Exception, not a framework wrapper.

```php
use Exception;

try {
    $user = $comment->commentator;
} catch (Exception $e) {
    // $e->getMessage() === 'Could not determine the commentator model name.'
    $user = null;
}
```

--------------------------------

### CommentAdded Event

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

Event dispatched when a comment is added. Contains the comment instance and implements ShouldDispatchAfterCommit.

```APIDOC
## CommentAdded Event

### Description
Event dispatched when a comment is added.

### Import Path
`BeyondCode\Comments\Events\CommentAdded`

### Payload
- **comment** (Comment) - The comment instance.

### Interfaces
- Implements `Illuminate\Contracts\Events\ShouldDispatchAfterCommit`
- Uses `Dispatchable`, `InteractsWithSockets`, `SerializesModels`

### Example
```php
use BeyondCode\Comments\Events\CommentAdded;

// Dispatching the event
CommentAdded::dispatch($comment);
```
```

--------------------------------

### Commentator contract

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Contract that allows user models to opt into automatic approval per commentable model. This contract is implemented by user models to control comment approval behavior.

```APIDOC
## Commentator contract

### Description
Contract that allows user models to opt into automatic approval per commentable model.

### Methods
- **needsCommentApproval(\Illuminate\Database\Eloquent\Model $commentable): bool** - Determines whether a comment needs approval for the given commentable model.
```

--------------------------------

### Comment::disapprove()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Disapproves the comment by setting the is_approved flag to false. This method is part of the Comment model and is used for moderation.

```APIDOC
## Comment::disapprove()

### Description
Disapproves the comment by setting the is_approved flag to false.

### Method
disapprove()

### Parameters
None

### Returns
- **bool** - True if the disapproval was successful.
```

--------------------------------

### comment(string $comment)

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Creates a new comment attributed to the currently authenticated user and saves it against the model. Delegates to commentAsUser() internally.

```APIDOC
## comment(string $comment)

### Description
Creates a new comment attributed to the currently authenticated user (`auth()->user()`) and saves it against this model. If no user is authenticated, the comment is created with a `null` `user_id`. When called on a `Comment` model, the reply is attached to the parent comment's `commentable` morph relation.

### Method
comment

### Signature
`public function comment(string $comment)`

### Parameters
- **$comment** (string) - Required - The comment text stored in the `comment` column

### Return Type
`Illuminate\Database\Eloquent\Model` - The newly created instance of the class configured in `comments.comment_class` (default `BeyondCode\Comments\Comment`), returned by `MorphMany::save()`.

### Throws / Rejects
- Throws if the underlying Eloquent save fails (e.g. validation on the comment model).
- Throws an `Exception` if the comment is attributed to the authenticated user (a `Commentator`) and the `Comment` model's `commentator()` relation cannot resolve a model name.
- Changing `comments.comment_class` to a class without the required fillable attributes causes a `MassAssignmentException` at save time.

### Example
```php
use Illuminate\Support\Facades\Auth;

Auth::login($user);

$post = Post::find(1);
$comment = $post->comment('Hello world');

// Guest context — no authenticated user:
// $comment->user_id is null, $comment->commentator is null
```
```

--------------------------------

### CanComment::needsCommentApproval()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Determines whether a comment needs approval. This method is part of the CanComment trait and is used to check if comments from this user require approval.

```APIDOC
## CanComment::needsCommentApproval()

### Description
Determines whether a comment needs approval.

### Method
needsCommentApproval()

### Parameters
- **commentable** (\Illuminate\Database\Eloquent\Model) - Required - The commentable model.

### Returns
- **bool** - True if the comment needs approval, false otherwise.
```

--------------------------------

### Commentator Interface

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

Interface that user models can implement to control comment approval behavior. The needsCommentApproval method determines whether a comment by this user on a given model requires approval.

```APIDOC
## Commentator Interface

### Description
Interface that user models can implement to control comment approval behavior. The needsCommentApproval method determines whether a comment by this user on a given model requires approval.

### Method
needsCommentApproval

### Signature
`public function needsCommentApproval($model): bool`

### Parameters
- **$model** (mixed) - Required - The model on which the comment is being made

### Returns
- **bool** - `true` if the comment requires approval, `false` if auto-approved

### Usage
Implement this interface on your user model to customize approval logic. The package's `CanComment` trait always returns `true`.
```

--------------------------------

### Method signature: needsCommentApproval()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/commentator.md

The method signature for needsCommentApproval(). It takes a commentable model instance and returns a boolean: false auto-approves the comment, true stores it unapproved.

```php
public function needsCommentApproval($model): bool;
```

--------------------------------

### Comment::commentable()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Defines the polymorphic relationship to the commentable model. This method is part of the Comment model and is used to retrieve the model that the comment belongs to.

```APIDOC
## Comment::commentable()

### Description
Defines the polymorphic relationship to the commentable model.

### Method
commentable()

### Parameters
None

### Returns
- **Illuminate\Database\Eloquent\Relations\MorphTo** - The morphTo relationship instance.
```

--------------------------------

### needsCommentApproval() default implementation

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/can-comment.md

Default implementation of needsCommentApproval() that always returns true, meaning comments by this user always require approval. This is the behavior that causes comments to be stored with is_approved = false.

```php
public function needsCommentApproval($model): bool
{
    return true;
}
```

--------------------------------

### commentAsUser()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Factory method for commenting on behalf of an arbitrary user (or null). Creates a new Comment record attached to the model with the specified user as the author.

```APIDOC
## commentAsUser()

### Description
Factory method for commenting on behalf of an arbitrary user (or null). Creates a new Comment record attached to the model with the specified user as the author.

### Method
commentAsUser()

### Endpoint
N/A (Eloquent method)

### Parameters
- **user** (User|null) - Required - The user to attribute the comment to, or null for anonymous.
- **message** (string) - Required - The comment text.

### Return Type
`BeyondCode\Comments\Comment`

### Example
```php
$post = Post::find(1);
$comment = $post->commentAsUser($user, 'This is a comment from a user.');
```
```

--------------------------------

### commentAsUser()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Creates a new comment on behalf of a specific user, or anonymously when null is passed. The approval status is determined by the user's Commentator contract implementation, defaulting to false if not implemented.

```APIDOC
## commentAsUser()

### Description
Creates a new comment on behalf of a specific user, or anonymously when null is passed. The approval status is determined by the user's Commentator contract implementation, defaulting to false if not implemented.

### Method
commentAsUser

### Signature
public function commentAsUser(?Model $user, string $comment)

### Parameters
- `$user` (Illuminate\Database\Eloquent\Model|null) - Required - The user model to attribute the comment to, or null for an anonymous comment (no user relation)
- `$comment` (string) - Required - The comment text stored in the `comment` column

### Return Type
Illuminate\Database\Eloquent\Model - the persisted comment instance (class from `comments.comment_class`)

### Throws
- Exception - "Could not determine the commentator model name." when resolving the relation later fails
- Eloquent save exceptions as with `comment()`

### Example
```php
$post = Post::find(1);
$admin = User::find(7);

$comment = $post->commentAsUser($admin, 'Posted on behalf of admin');

// Anonymous comment:
$anonymous = $post->commentAsUser(null, 'An anonymous comment');
```

### Behavior with the Commentator contract
If `User` implements `BeyondCode\Comments\Contracts\Commentator`:

```php
class User extends Authenticatable implements Commentator
{
    public function needsCommentApproval($model): bool
    {
        return $model instanceof Post; // only approve comments on posts automatically
    }
}

$comment = $post->commentAsUser($user, 'approved automatically'); // is_approved === true
```
```

--------------------------------

### Comment::commentator()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Defines the relationship to the user who made the comment. This method is part of the Comment model and is used to retrieve the user who authored the comment.

```APIDOC
## Comment::commentator()

### Description
Defines the relationship to the user who made the comment.

### Method
commentator()

### Parameters
None

### Returns
- **Illuminate\Database\Eloquent\Relations\BelongsTo** - The belongsTo relationship instance.
```

--------------------------------

### HasComments::commentAsUser()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Creates a new comment as a specific user. This method is part of the HasComments trait and is used to add a comment on behalf of a given user.

```APIDOC
## HasComments::commentAsUser()

### Description
Creates a new comment as a specific user.

### Method
commentAsUser()

### Parameters
- **comment** (string) - Required - The comment text.
- **user** (\Illuminate\Contracts\Auth\Authenticatable) - Required - The user who is commenting.

### Returns
- **Comment** - The created comment instance.
```

--------------------------------

### Listener class for CommentAdded

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/comment-added.md

A listener class with a handle method that notifies the commentable's owner using null-safe operators.

```php
// With an event listener class registered in EventServiceProvider
class NotifyCommentableOwner
{
    public function handle(CommentAdded $event): void
    {
        $event->comment->commentable?->author?->notify(
            new NewCommentNotification($event->comment)
        );
    }
}
```

--------------------------------

### HasComments::comment()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Creates a new comment on the model. This method is part of the HasComments trait and is used to add a comment to the model.

```APIDOC
## HasComments::comment()

### Description
Creates a new comment on the model.

### Method
comment()

### Parameters
- **comment** (string) - Required - The comment text.
- **user** (\Illuminate\Contracts\Auth\Authenticatable|null) - Optional - The user who is commenting. Defaults to the currently authenticated user.

### Returns
- **Comment** - The created comment instance.
```

--------------------------------

### Comment::scopeApproved()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Query scope to filter only approved comments. This method is part of the Comment model and is used to retrieve only comments that have been approved.

```APIDOC
## Comment::scopeApproved()

### Description
Query scope to filter only approved comments.

### Method
scopeApproved()

### Parameters
- **query** (\Illuminate\Database\Eloquent\Builder) - Required - The query builder instance.

### Returns
- **\Illuminate\Database\Eloquent\Builder** - The modified query builder.
```

--------------------------------

### HasComments::comment

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

Creates a new comment for the model. This method is part of the HasComments trait that makes a model commentable.

```APIDOC
## HasComments::comment

### Description
Creates a new comment for the model.

### Method
`comment`

### Signature
```php
public function comment(string $comment)
```

### Parameters
- **$comment** (string) - Required - The comment text.

### Return Value
- **Model** - The created comment model.

### Example
```php
$post->comment('This is a comment');
```
```

--------------------------------

### Method: comments() - definition

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/api-reference/has-comments.md

Defines the polymorphic morphMany relation for comments. The related class is resolved from the 'comments.comment_class' config value, and the relation name is 'commentable'.

```php
public function comments()
```

```php
return $this->morphMany(config('comments.comment_class'), 'commentable');
```

--------------------------------

### Comment model class with fillable and casts

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

Default comment record type extending Eloquent Model. Uses the HasComments trait for nesting and defines fillable attributes and boolean casting for is_approved.

```php
class Comment extends Model
{
    use HasComments;

    protected $fillable = [
        'comment',
        'user_id',
        'is_approved',
    ];

    protected $casts = [
        'is_approved' => 'boolean',
    ];
}
```

--------------------------------

### HasComments::commentAsUser

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/types.md

Creates a new comment for the model as a specific user. This method is part of the HasComments trait that makes a model commentable.

```APIDOC
## HasComments::commentAsUser

### Description
Creates a new comment for the model as a specific user.

### Method
`commentAsUser`

### Signature
```php
public function commentAsUser(?Model $user, string $comment)
```

### Parameters
- **$user** (?Model) - Required - The user who is commenting. Can be null.
- **$comment** (string) - Required - The comment text.

### Return Value
- **Model** - The created comment model.

### Example
```php
$post->commentAsUser($user, 'This is a comment');
```
```

--------------------------------

### HasComments::comments()

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Defines a polymorphic one-to-many relationship to retrieve all comments for the model. This method is part of the HasComments trait and is used to access the comments associated with the model.

```APIDOC
## HasComments::comments()

### Description
Defines a polymorphic one-to-many relationship to retrieve all comments for the model.

### Method
comments()

### Parameters
None

### Returns
- **Illuminate\Database\Eloquent\Relations\MorphMany** - The morphMany relationship instance.
```

--------------------------------

### CommentDeleted event

Source: https://github.com/beyondcode/laravel-comments/blob/master/_autodocs/README.md

Event dispatched after a comment is deleted. This event is part of the package and is used to notify listeners when a comment is deleted.

```APIDOC
## CommentDeleted event

### Description
Event dispatched after a comment is deleted.

### Properties
- **comment** (Comment) - The comment instance.
```
Tokens:
Raw