README

machinima-bot

Telegram bot bundle for the Machinima platform.

Features · Architecture · Requirements · Installation · Usage · Contributing

machinima-bot is the official Telegram management bundle for the Machinima platform. It provides role and content management features for the platform's administrators.

Features

Interactive Screen-Based UI: Provides a rich admin panel experience directly inside Telegram using inline keyboards with callback-driven navigation, visual panels with images, and domain-organised screen flows (authors, projects, categories, roles, staff).
Role & Permission Management: Full RBAC workflow via Telegram — create, assign, and revoke roles for platform users, powered by the shared RoleService from machinima-core.
Flexible Update Handling: Supports both a production-ready Webhook endpoint (POST /webhook/telegram) and a long-polling CLI command for local development, with automatic user authentication and locale detection on every incoming update.
Content Administration Commands: A set of slash-commands (/start, /help, /admin, role management) that serve as entry points into the screen-based management panels, each with built-in i18n support through the bundle's Translator.

Architecture

This bundle implements a screen-and-command pattern on top of the morfeditorial/telegram-bot-bundle abstraction layer. It contains no domain entities or repositories of its own — all data access is delegated to morfeditorial/machinima-core via its shared services (AuthorRepository, UserRepository, RoleService, etc.).

Commands (src/Commands/) — Telegram bot commands (/start, /help, role assignment, admin panel entry point) that extend BaseMachinimaCommand and interact with the user through messages.
Screens (src/Screens/) — interactive inline-keyboard panels for domain management (authors, projects, categories, roles, staff), organised by domain subdirectory. Each screen extends BaseMachinimaScreen and renders a visual panel with callback-driven navigation.
Webhook Controller (src/Controller/Webhook/) — receives Telegram updates via POST /webhook/telegram, authenticates the calling user through the Security token storage, sets the locale, and delegates to the UpdateDispatcher from telegram-bot-bundle.
Service Providers (src/Service/) — Telegram-specific implementations of core contracts such as AvatarProviderInterface and MediaProviderInterface, which resolve avatars and media through the Telegram Bot API.

Requirements

PHP 8.2 or higher
Composer for dependency management
Symfony Framework 7.1+

Installation

This package is intended to be used as a bundle within the machinima-app host application. Require it via Composer:

composer require morfeditorial/machinima-bot

Usage

The bot runs as part of the host application ecosystem. To run the Telegram bot polling loop locally, use the Symfony console:

php bin/console morf:bot:poll

For production, the bot interacts with Telegram via the configured Webhook route in the host app.

Screenshot of the admin panel showing the management capabilities of the Telegram bot.

Contributing

Contributions are welcome and appreciated! Here's how you can contribute:

Fork the project
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This project is licensed under the CSSM Unlimited License v2.0 (CSSM-ULv2). See the LICENSE file for details.

morfeditorial / machinima-bot

Maintainers

Package info

Statistics

Security