README

Description

Tempcord is a modern, elegant PHP framework designed specifically for building Discord bots with ease. Built on top of the powerful Tempest Console framework and Ragnarok Fenrir Discord library, Tempcord provides a clean, attribute-based approach to creating sophisticated Discord bots with minimal boilerplate code.

The framework leverages PHP 8.5+ features and modern development practices to deliver a robust foundation for Discord bot development, featuring automatic command registration, event handling, and seamless integration with Discord's API.

Getting Started: Use the tempcord/tempcord boilerplate to quickly create new Discord bot applications. This repository contains the core framework - for building applications, use composer create-project tempcord/tempcord your-bot-name.

Features

🚀 Modern PHP 8.5+ - Leverages the latest PHP features and syntax
🎯 Attribute-Based Commands - Define Discord commands using PHP attributes
📡 Event-Driven Architecture - Handle Discord events with clean, organized handlers
🔧 Auto-Discovery - Automatic command and event registration
🏗️ Dependency Injection - Built-in container for clean architecture
📝 Console Integration - Rich console output and logging capabilities
🔌 Extensible - Easy to extend with custom functionality
🛡️ Type Safety - Full type hints and strict typing throughout
📊 Logging Support - Comprehensive logging with multiple channels
⚡ Performance Optimized - Efficient command and event handling

Installation

Prerequisites

PHP 8.5 or higher
Composer
A Discord Bot Token (from Discord Developer Portal)

Step 1: Create New Application

Use the Tempcord application boilerplate to create a new Discord bot project:

composer create-project tempcord/tempcord my-discord-bot
cd my-discord-bot

Step 2: Configure Your Bot

Copy the example environment file and configure your bot:

cp .env.example .env

Edit the .env file with your Discord bot credentials:

DISCORD_TOKEN=your_bot_token_here

Step 3: Install Dependencies

composer install

Step 4: Create Your First Command

The boilerplate includes example commands. Create a new command in any folder, for example inside app/Commands/:

<?php

namespace App\Commands;

use Tempcord\Attributes\Command;
use CyberWolf\Discord\Gateway\Events\InteractionCreate;

#[Command(name: 'hello', description: 'Say hello!')]
class HelloCommand
{
    public function __invoke(InteractionCreate $interaction): void
    {
        $interaction->respondWithMessage([
            'content' => 'Hello, World! 👋'
        ]);
    }
}

Usage

Running Your Bot

Use the built-in console commands to manage your bot:

# Boot the bot
php tempcord boot

# Boot and register commands with Discord
php tempcord boot --register

# Register commands only (without starting the bot)
php tempcord register

Creating Commands

Commands are defined using the #[Command] attribute:

#[Command(
    name: 'ping',
    description: 'Check bot latency'
)]
class PingCommand
{
    public function __invoke(InteractionCreate $interaction): void
    {
        $interaction->respondWithMessage([
            'content' => 'Pong! 🏓'
        ]);
    }
}

Handling Events

Create event handlers using the #[Event] attribute:

use Tempcord\Attributes\Event;
use CyberWolf\Discord\Gateway\Events\MessageCreate;

#[Event(name: 'message_create')]
class MessageHandler
{
    public function __invoke(MessageCreate $message): void
    {
        // Handle message events
        if ($message->content === '!hello') {
            // Respond to the message
        }
    }
}

Command Options and Subcommands

#[Command(name: 'user', description: 'User management commands')]
class UserCommand
{
    #[Subcommand(name: 'info', description: 'Get user information')]
    public function info(
        #[Option(description: 'Target user')]
        User $user
    ): void {
        // Handle user info command
    }
}

Whether an option is required comes from whether its parameter has a default, so $user above is required without saying so.

Documentation

See docs/ — guides for getting started, commands, autocomplete, events and translations, plus a reference generated from the source.

Run composer docs after changing the public API; the test suite fails if the committed documentation no longer matches the code.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to contribute to Tempcord.

Development Setup

Fork the repository
Clone your fork: git clone https://github.com/your-username/framework.git
Install dependencies: composer install
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: composer test
Commit your changes: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Open a Pull Request

Reporting Issues

When reporting issues, please include:

PHP version
Framework version
Steps to reproduce
Expected vs actual behavior
Error messages or logs

Feature Requests

We're always looking for ways to improve Tempcord. Feel free to:

Open an issue with the enhancement label
Discuss your ideas in our community channels
Submit a pull request with your implementation

Credits & Acknowledgements

Tempcord stands on the shoulders of excellent open-source projects. It does not bundle their source code — they are pulled in as Composer dependencies at install time, each under its own license — but the framework would not exist without them:

Discord PHP by CyberWolf.Studio — the underlying Discord API/gateway library Tempcord builds upon; itself a maintained fork of Fenrir by Ragnarök (MIT License).
Tempest — the console, core, event-bus and logging foundation Tempcord integrates with (MIT License).
ReactPHP — the async runtime powering the gateway connection (MIT License).

License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ by CyberWolf.Studio team. using Tempest

For more information, visit our documentation or join our Discord community.

tempcord / framework

Maintainers

Package info

Statistics

Security