@mention prefix isn't working as expected

[shutupflanders]

When using the "@mention" prefix (documented here) , the bot seems to treat it as a string literal and prefixes all the commands with "@mention":

@mentionping              | Send a "Pong" response
@mentionstats             | View verification statistics   

I've tried passing it through as an array as well, but I get the same result. I'd love to use this prefix as it prevents any crosstalk and competing bot commands.

Thanks for all your work on this framework so far, it's been really helpful!

[Log1x]

Hey, thanks for the report! In Laracord v2, the @mention parsing functionality I believe is built-in to DiscordPHP's command client upstream. I will have to double check to see if something changed on their end regarding this.

If you aren't shy at the idea of upgrading, despite there not being an official release, Laracord v3 is quite stable and implements the command client from scratch (including this functionality) so it should work on that branch. #134 has an overview of everything as well as some instructions. You can check the PR on the skeleton at https://github.com/laracord/laracord/pull/16/files to see immediate changes, but it shouldn't be too bad! 🤞

[shutupflanders]

Thanks for the quick response @Log1x 🙌

I'll take a look and get back to you if it solves the issue!

[shutupflanders]

So I've made some progress, managed to upgrade to v3, tested commands on the old ! prefix, and things work great.
However, the @mention prefix still concatenates the prefix and command name (although, it's pulling through the bot user ID now):

<@1419410188515016...>stats │ View verification statistic

(redacted part of the ID as this is a public repo)

[shutupflanders]

Forgive the AI dump, but I had Claude code do a deep dive at 1am, after implementing these changes it now works. I'll be testing on the v2 branch tonight

---

Laracord v3 @mention Prefix Bug Report

Summary

The @mention prefix feature in Laracord v3 (dev-next branch) is broken due to two issues:

1. Commands with a space after the mention prefix are incorrectly rejected
2. The command name extraction doesn't handle the space after mentions properly

Environment

• Laracord Version: dev-next branch (commit e79ea4e)
• Laravel Version: 12.35.0
• PHP Version: 8.4
• Discord.php Version: 10.38.1
• Configuration: DISCORD_COMMAND_PREFIX=@mention

Expected Behavior

When the prefix is set to @mention, users should be able to trigger commands by mentioning the bot followed by a space and the command name:

@BotName verify
@BotName help
@BotName stats

Actual Behavior

1. Display Issue: Commands are shown in the help table as <@123456789>commandname (no space)
2. Execution Issue: Commands do not execute when sent with proper Discord mention format

Debug Logs

[MESSAGE] From: user, Content: <@123456789> verify
[PREFIX] Matched prefix: <@123456789>
[SKIP] No command name found

Root Cause Analysis

Issue 1: Space Rejection After Mention Prefix

Location: vendor/laracord/framework/src/Bot/Concerns/HasCommands.php:86-90

$after = Str::substr($message->content, Str::length($prefix), 1);

if ($after === ' ') {
    return;
}

Problem: This logic rejects ALL commands with a space after the prefix. While this is correct for regular prefixes (to prevent ! verify), it breaks mention prefixes because Discord always formats mentions with a space:

User types:    @BotName verify
Discord sends: <@123456789> verify
                                     ↑ space here is natural!

Issue 2: Command Name Extraction

Location: vendor/laracord/framework/src/Bot/Concerns/HasCommands.php:92-94

$parts = Str::of($message->content)
    ->after($prefix)
    ->explode(' ');

$command = $parts->shift();

Problem: After removing the prefix <@123456789> from <@123456789> verify, we get verify (with leading space). When this is exploded by space, the first element is an empty string, causing "No command name found".

Issue 3: Display Name in Help Table

Location: vendor/laracord/framework/src/Commands/Command.php:80-82

public function getSignature(): string
{
    return Str::start($this->getName(), $this->bot()->getPrefix());
}

Problem: When prefix is <@123456789>, this creates <@123456789>verify without a space, which looks broken in the help table.

The Fix

1. Allow Spaces After Mention Prefixes

$after = Str::substr($message->content, Str::length($prefix), 1);

// Allow spaces after mention prefixes (e.g., <@123456789>), but not regular prefixes (e.g., !)
$isMentionPrefix = Str::startsWith($prefix, '<@') && Str::endsWith($prefix, '>');

if ($after === ' ' && !$isMentionPrefix) {
    return;
}

2. Trim Whitespace Before Extracting Command

$parts = Str::of($message->content)
    ->after($prefix)
    ->trim()  // Remove leading/trailing spaces
    ->explode(' ');

$command = $parts->shift();

3. Improve Command Display for Mention Prefixes

In showCommands() method or getSignature():

$prefix = $this->bot()->getPrefix();
$isMentionPrefix = Str::startsWith($prefix, '<@') && Str::endsWith($prefix, '>');

if ($isMentionPrefix) {
    $botName = $this->discord?->user?->username ?? 'Bot';
    return "@{$botName} {$this->getName()}";
}

return Str::start($this->getName(), $prefix);

Workaround Implementation

Since this is a framework bug, we implemented a workaround by extending the Laracord class:

File: app/Bot.php

<?php

namespace App;

use Discord\Parts\Channel\Message;
use Illuminate\Support\Str;
use Laracord\Laracord;

class Bot extends Laracord
{
    /**
     * Show the commands table with proper formatting for @mention prefix.
     */
    public function showCommands(): self
    {
        if (! $this->showCommands) {
            return $this;
        }

        $commands = [
            ...$this->commands,
            ...$this->slashCommands,
        ];

        $prefix = $this->getPrefix();
        $isMentionPrefix = Str::startsWith($prefix, '<@') && Str::endsWith($prefix, '>');
        $botName = $this->discord?->user?->username ?? $this->getName();

        $this->console->table(
            ['<fg=blue>Command</>', '<fg=blue>Description</>'],
            collect($commands)->map(fn ($command) => [
                $isMentionPrefix
                    ? "@{$botName} {$command->getName()}"
                    : $command->getSignature(),
                $command->getDescription(),
            ])->all(),
            tableStyle: 'box',
        );

        return $this;
    }

    /**
     * Handle the chat commands with fix for @mention prefix.
     */
    protected function handleCommands(): void
    {
        $this->discord->on('message', function (Message $message) {
            if ($message->author->id === $this->discord->id) {
                return;
            }

            $prefix = $this->getPrefixes()->first(fn ($prefix) => Str::startsWith($message->content, $prefix));

            if (! $prefix) {
                return;
            }

            $after = Str::substr($message->content, Str::length($prefix), 1);

            // Allow spaces after mention prefixes (e.g., <@123456789>), but not regular prefixes (e.g., !)
            $isMentionPrefix = Str::startsWith($prefix, '<@') && Str::endsWith($prefix, '>');

            if ($after === ' ' && !$isMentionPrefix) {
                return;
            }

            $parts = Str::of($message->content)
                ->after($prefix)
                ->trim()  // Remove leading/trailing spaces
                ->explode(' ');

            $command = $parts->shift();

            if (! $command) {
                return;
            }

            $command = $this->getCommand($command);

            if (! $command) {
                return;
            }

            rescue(fn () => $command->maybeHandle($message, $parts->all()));
        });
    }
}

File: app/Providers/BotServiceProvider.php

public function register()
{
    // ... (parent setup code)

    // Use Bot::make() instead of Laracord::make()
    $this->app->singleton(Laracord::class, fn () => tap(Bot::make($this->app), function (Laracord $bot) {
        $this
            ->registerDefaultComponents($bot)
            ->registerDefaultPrompts($bot);

        // ... (rest of setup)

        return $this->bot($bot);
    }));

    // ... (aliases)
}

Suggested Framework Changes

1. Update HasCommands Trait

File: src/Bot/Concerns/HasCommands.php

protected function handleCommands(): void
{
    $this->discord->on('message', function (Message $message) {
        if ($message->author->id === $this->discord->id) {
            return;
        }

        $prefix = $this->getPrefixes()->first(fn ($prefix) => Str::startsWith($message->content, $prefix));

        if (! $prefix) {
            return;
        }

        $after = Str::substr($message->content, Str::length($prefix), 1);

        // FIX: Allow spaces after mention prefixes, but not regular prefixes
        $isMentionPrefix = Str::startsWith($prefix, '<@') && Str::endsWith($prefix, '>');

        if ($after === ' ' && !$isMentionPrefix) {
            return;
        }

        // FIX: Trim whitespace before extracting command name
        $parts = Str::of($message->content)
            ->after($prefix)
            ->trim()
            ->explode(' ');

        $command = $parts->shift();

        if (! $command) {
            return;
        }

        $command = $this->getCommand($command);

        if (! $command) {
            return;
        }

        rescue(fn () => $command->maybeHandle($message, $parts->all()));
    });
}

2. Update Command Display

File: src/Commands/Command.php

public function getSignature(): string
{
    $prefix = $this->bot()->getPrefix();

    // Show mention prefixes in a user-friendly format
    if (Str::startsWith($prefix, '<@') && Str::endsWith($prefix, '>')) {
        $botName = $this->bot()->discord?->user?->username ?? 'Bot';
        return "@{$botName} {$this->getName()}";
    }

    return Str::start($this->getName(), $prefix);
}

Testing

After implementing the fix:

# In Discord
@BotName verify
@BotName help
@BotName stats

# Expected logs
[MESSAGE] From: user, Content: <@123456789> verify
[PREFIX] Matched prefix: <@123456789>
[COMMAND] Looking for command: verify
[EXECUTE] Running command: App\Commands\VerifyCommand

Additional Notes

1. The @mention string is correctly converted to the Discord user mention format (<@ID>) in HasCommands::getPrefixes() at line 39
2. The conversion happens correctly - the only issues are with space handling and display
3. This bug exists in v3 (dev-next) but the original issue report was for v2 where @mention was suggested as the solution

Related

• Original issue: @mention prefix isn't working as expected #144
• PR v3 #134: v3 #134 (v3 refactor)

---

Tested and confirmed working with the above workaround on:

• Laracord v3 dev-next (e79ea4e)
• PHP 8.4
• Discord.php 10.38.1

[shutupflanders]

Just a heads up, managed to get this working in V2 as well.

I can get something more concrete together and open a PR if you'd like? Which branch would be best to make changes to?

[Log1x]

Hey! Sorry for no reply here. Feel free to do a PR against next if the issue exists here. If you are using v2, you can do a PR for that as well.