Public API.

Use this page when you need an exact method signature, return type, or event property. The package release tests cover the listed traits, contracts, lifecycle events, Mention model, and SyncResult. Parser and resolver contracts also use three supporting value objects.

HasMentions

Source models use Byrcsc\Mentions\Concerns\HasMentions.

public static function bootHasMentions(): void;
public function mentions(): MorphMany;
public function mentioned(): Collection;
public function syncMentions(): SyncResult;
public function scopeWhereMentions(Builder $query, Model $target): Builder;

The trait also provides these protected override hooks:

protected function mentionableAttributes(): array;
protected function mentionParser(): ?string;
protected function syncsMentionsAutomatically(): bool;

The default mentionableAttributes() reads a protected $mentionableAttributes array from the model. mentionParser() returns null, which selects default_parser. syncsMentionsAutomatically() returns whether mentions.auto_sync is the boolean true.

bootHasMentions() is Eloquent's trait boot hook. Eloquent calls it when the model boots; application code does not call it directly.

Mentionable

Target models use Byrcsc\Mentions\Concerns\Mentionable.

public function mentionedIn(): MorphMany;

Mention model

Byrcsc\Mentions\Models\Mention extends Eloquent Model.

public function getTable(): string;
public function source(): MorphTo;
public function target(): MorphTo;
public function scopeFromSourceType(
    Builder $query,
    string $sourceType,
): Builder;

The fillable fields are source_type, source_id, target_type, target_id, and handle.

Parser contract

Byrcsc\Mentions\Contracts\MentionParser defines:

/** @return list<MentionCandidate> */
public function parse(string $text): array;

MentionCandidate is readonly. Its constructor is private; create values with:

public static function fromHandle(
    string $raw,
    string $handle,
): MentionCandidate;

public static function fromTarget(
    string $raw,
    string $targetId,
    ?string $targetType = null,
): MentionCandidate;

Each candidate exposes readonly raw, handle, targetId, and targetType properties.

The shipped parser implementations both expose the contract method:

RegexMentionParser::parse(string $text): array;
MarkupMentionParser::parse(string $text): array;

Resolver contract

Byrcsc\Mentions\Contracts\MentionResolver defines:

/** @param list<MentionCandidate> $candidates */
public function resolve(array $candidates): ResolutionResult;

ResolutionResult is readonly:

public function __construct(
    public array $resolved,
    public array $unresolved,
) {}

resolved is a list of ResolvedMention. unresolved is a list of MentionCandidate.

ResolvedMention pairs one candidate with its Eloquent target:

public function __construct(
    public MentionCandidate $candidate,
    public Model $target,
) {}

The shipped column resolver has this public constructor and contract method:

public function __construct(
    string $modelClass,
    string $column,
);

public function resolve(array $candidates): ResolutionResult;

Synchronization result

Byrcsc\Mentions\ValueObjects\SyncResult is readonly:

public function __construct(
    public array $created,
    public array $removed,
    public array $retained,
    public array $unresolved,
) {}

created, removed, and retained contain lists of Mention. unresolved contains a list of MentionCandidate.

Lifecycle events

Both event classes are final and readonly:

final readonly class MentionCreated
{
    public function __construct(public Mention $mention) {}
}

final readonly class MentionRemoved
{
    public function __construct(public Mention $mention) {}
}

No facade or commands

The package does not define a facade, Artisan command, route, controller, or HTTP endpoint. Use the model traits and Laravel's container bindings.

MentionParser resolves to the configured default parser. MentionResolver resolves to the ordered resolver manager. Resolving the base Mention class returns an instance of the configured mention model.

What to read next

• Configuration for container-backed registrations.
• Published assets for the database contract.
• Testing for assertions against this API.