Framework Laravel Package

Getting Started

1. Install via Composer: composer require laracord/framework
2. Publish config: php artisan vendor:publish --provider="Laracord\Framework\Providers\FrameworkServiceProvider" — this creates config/laracord.php with defaults (token, intents, command prefix)
3. Create your first command: Run php artisan make:command PingCommand — extend Laracord\Framework\Commands\Command and implement handle()
4. Start the bot: php artisan laracord:run — the framework boots a Laravel CLI context with Discord’s ReactPHP event loop
5. Monitor logs: Use --debug flag to enable verbose output during development

Implementation Patterns

• Command-driven architecture: Define all bot functionality as Artisan-style commands under app/Commands/ with auto-discovery
• Service container injection: Inject services (e.g., Http, Cache) into command constructors — full Laravel DI works
• Environment-based config: Store tokens/secrets in .env (use DISCORD_BOT_TOKEN), configure per-environment via config/laracord.php
• Middleware pipeline: Register command/middleware in laracord.php to preprocess commands (e.g., permission checks)
• Event handlers: Use php artisan make:command CommandHandler with @listen attributes to handle MessageCreated, InteractionCreate, etc.
• CLI-friendly development: Commands run within Laravel’s request lifecycle — use dump(), dd(), and tests seamlessly
• Authenticated API requests: Leverage the new tokenable user feature to attach user context to HTTP requests via Http facade or HttpClient (e.g., $this->http->withToken($this->user->token)->get(...)). Useful for OAuth flows or user-specific API calls.

Gotchas and Tips

• Non-blocking I/O is critical: Avoid synchronous HTTP calls or long-running loops; use react/promise/guzzle/react-adapter for async requests
• Token permissions: The DISCORD_BOT_TOKEN must have both bot scope and correct guild permissions — verify in Discord Developer Portal
• Stateless by default: Commands don’t persist context between runs — use Cache or external DB for shared state (not server memory)
• Event loop collisions: Never call React\EventLoop\Loop::run() manually — the framework manages this; doing so causes silent hangs
• Debugging tip: Use --verbose flag to see full stack traces for command errors, or set debug to true in config
• Extensibility: Override core classes (e.g., CommandRunner) by binding interfaces in AppServiceProvider
• Testing: Write unit tests for commands like regular Laravel commands — but mock Discord events using Laracord\Framework\Testing\DiscordTest trait
• Tokenable user context: When using the new tokenable user feature, ensure your commands extend Laracord\Framework\Commands\AuthCommand (if available) or manually resolve the user context via $this->getUser() in your command. Verify the user’s token permissions before making authenticated requests.