NeleBot | PHP Framework per Bot Telegram

Indice

F.A.Q.

D: Cos'è NeleBot?

R: NeleBot è il primo framework per Bot Telegram in PHP completamente realizzato da zero e da uno sviluppatore con più di 2 anni di esperienza con il linguaggio stesso.

D: Posso usare NeleBot se non so progammare in php?

R: Ma ovviamente no, NeleBot è un framwork, non è un Bot completo.

D: Lo posso usare su altervista?

R: No. NeleBot non supporta e non supporterà mai altervista.

Per 2 semplici motivazioni:

Va contro i termini di servizio di altervista hostare bot/userbot

Il framework darebbe errori in alcuni file e sarebbe rallentato

D: I plugin per altervistabot funzionano con questo framework?

R: No.

D: E tutti gli altri webhosting? (Ad esempio netsons con cPanel?)

R: "Dovrebbe" funzionare correttamente, ma non garantiamo nulla.

D: In cosa cambia dagli altri?

R: NeleBot rivoluziona il mondo dei framework per Bot Telegram in PHP per delle aggiunte e delle migliorie alla base, nei file principali del framework e vi mette a disposizione dei modi nuovi per gestire i vostri Bot.

Ad esempio: possibilità di attivare o disattivare una developer mode, aggiungere una password per autenticare le richieste, migliore gestione di tutte le updates (functions.php), migliore gestione delle richieste in entrata e in uscita, e molto altro da scoprire scaricando il framework!

D: Come setto il webhook?

R: Usando il nostro Bot Webhook Installer e seguendo la guida qui sotto.

D: Se riscontro dei problemi con il framework a chi posso chiedere?

R: Entra nel gruppo di supporto e fai tutte le domande! Ovviamente leggendo prima le /regole e seguendo ciò che dicono.

D: Se non mi piace qualcosa del framework posso modificarlo?

R: Certamente! Purché rispetti i termini della licenza del framework e non ti vieni a lamentare nel gruppo, di errori a file inizialmente funzionanti!

D: Non mi piace come sono state scritte alcune variabili in functions.php/voglio cambiare alcuni parametri della richiesta, è possibile modificarle?

R: Si, vai in functions.php, cerca il nome dell'update che vuoi modificare (aiutati con le docs della BotAPI per i nomi) e carica il file modificato. Ovviamente sii sicuro che quella variabile non venga già utilizzata da qualcosa di interno al framework.

D: Esiste un Bot di test dove provare come funzioni il Framework?

R: Certo! Eccolo qua!

News sul Framework

Il framework è costantemente aggiornato ed al passo con le ultime novità della BotAPI, per informazioni su di esso potete entrare sul Canale Telegram.

I file e gli aggiornamenti vengono pubblicati su GitLab.

Guida aggiornata alla versione 2.6.3

Indice files

index.html

index.php

config.php

functions.php

database.php

antiflood.php

plugin_manager.php

plugins.json

comandi.php

index.html

Pagina di un falso errore 404.

Potete modificarla in base alla pagina not found del vostro sito. Questa pagina serve a nascondere il Bot dalle richieste indesiderate.

index.php

Indice: Dove viene settato il Webhook del Bot.

Nome dei file: Aumenta la sicurezza del tuo Bot cambiando il nome dei file. Per richiamarli basta usare (ad esempio) $f['config'] e il valore sarà "config.php", è consigliato anche cambiare directory.

Informazioni del bot: Qui prende le chiavi API del Bot, l'eventuale password e altre informazioni primarie.

Autenticazione delle request: Se hai una password settata sul config devi settarla anche dal Webhook installer.

In caso di password sbagliata, se la devmode è attiva vi dirà che la password è sbagliata, altrimenti mostrerà la pagina not found.

Telegram json update: Preleva le informazioni inviate da Telegram e le passa in json_decode su $update che poi verra modificato in functions.php, se vuoi la reale update usa la variabile $rupdate.

In caso di assenza dell'update inviata da Telegram, se la devmode è attiva vi dirà che Telegram non ha inviato alcun contenuto, altrimenti mostrerà la pagina not found.

Gestione logs: Qui vengono gestiti i logs, dal config puoi decidere se attivare o disattivare questa funzione oppure loggare solo l'ultimo update. Sconsigliato per un utilizzo generale.

Gestione permessi: Qui puoi dare dei permessi a tuo piacimento, in questo caso c'è la variabile $isadmin che determina se l'utente è amministratore, oppure no, del Bot in questione.

Whitelist utenti: Questa funzione, se abilitata permette l'accesso al bot solo agli utenti nell'Array e agli admin.

Whitelist chat: Questa funzione, se abilitata permette l'accesso al bot solo alle chat autorizzate nell'Array.

Database: Da qui si hanno le informazioni del database sull'utente che vanno sulla variabile $u. Se attivo l'uso del database redis si attiva anche l'antiflood che protegge dal flood di messaggi e bottoni (callback_data).

Gestione plugins: Qui vengono caricati i plugin ad uno ad uno, se c'è un errore in un plugin sarà chiamato errore e il plugin verrà disattivato, altrimenti se la devmode è attiva invierà solo il messaggio con l'errore. Se ci sono problemi di sintassi o errori php il Bot risponderà con errore 500.

config.php

File dove vengono immagazzinate tutte le configurazioni del Bot.
Per sicurezza ti consigliamo di spostare il file su una directory fuori dal Browser.

cloni: Questo sarà un array che farà da whitelist per i cloni del Bot e prevenire eventuali utenti che potrebberò clonare il tuo Bot tramite Webhook. Es: [123456789 => "Clone1Bot", 123456788 => "Clone2Bot"]

password: Password che autentica le request di Telegram sul Bot. (Che passa dal Webhook)

admins: Lista degli ID degli amministratori da inserire in un array. Es: [244432022, 426538970]

devmode: Modalità developer, se attiva ti aiuta a testare il tuo Bot e ti permette di vedere eventuali errori direttamente sul browser.

method: Metodo usato come predefinito sulla funzione sendRequest. Scegli tra get e post.

response: Decidi se ricevere risposta da curl nelle richieste effettuate tramite sendRequest. Se non richiedi la risposta il Bot andrà più veloce.

usa_il_db: Decidi se usare il database oppure no. Il Ban funziona da 'status' sulla tabella utenti.

usa_redis: Decidi se utilizzare redis. Automaticamente anche l'AntiFlood.

logs: Decidi se memorizzare e come memorizzare le update ricevute da telegram. true salva tutto, 'ultimo' salva solo l'ultimo e false non salvare nulla.

console: Metti qui l'ID della chat in cui vuoi mandare gli errori del Bot. Es: 244432022 oppure metti false per non utilizzarlo.

whitelist_users: Blocca gli utenti che non hanno il permesso di accedere al bot. Questa funzione, se abilitata consente l'accesso solo agli utenti nell'array gli amministratori. Es: [123456789, 244432022] oppure metti false per disattivarla. Puoi anche lasciare [] per dare accesso solo agli admin.

whitelist_chats: Blocca le chat che non hanno il permesso di accedere al Bot. Questa funzione, se abilitata consente l'accesso solo agli utenti nell'array gli amministratori. Es: [123456789, 244432022] oppure metti false per disattivarla. Puoi anche lasciare [] per non fare comunicare il Bot con alcun gruppo.

post_canali: Decidi se ricevere i messaggi dei canali.

modificato: Decidi se far leggere al Bot i messaggi modificati. Questi avranno la variabile $modificato con true.

azioni: Prima che il Bot invii un messaggio, una foto, un video, un video rotondo, una GIF, un file o una posizione comparirà "Sta scrivendo..." oppure "Sta inviando un file...", ecc.

parse_mode: Decidi qui la formattazione dei messaggi. Es: html o markdown. (Consigliato HTML)

disabilita_anteprima_link: Decidi se di default il Bot lascia o nasconde l'anteprima link. true per nascondere l'anteprima link e false per lasciarla.

Configurazione Database

type: Scegli il tipo di database: SQLite, MySQL o PostgreSQL. mysql / postgre/ sqlite

nome_database: Nome del database. O nel caso di SQLite sarà il nome del file.

utente: Nome dell'utente MySQL/PostgreSQL.

password: Password dell'utente MySQL/PostgreSQL.

host: IP/dominio del server MySQL/PostgreSQL. Puoi lasciare localhost se il server MySQL/PostgreSQL è sulla stessa macchina del bot.

Configurazione Redis

database: Selezione del database (numerico). Lascia false per usare il database di default.

host: IP/dominio del server Redis. Puoi lasciare localhost se il server redis è sulla stessa macchina del bot.

port: Porta del server Redis. La porta predefinita è 6379.

password: Password dell'utente. (Opzionale)

NB: puoi testare il funzionamento di Redis tramite il comando /redis.

functions.php

Gestione degli update: Controlla le variabili già esistenti per utilizzare al meglio il Framework. Puoi modificare i nomi delle variabili a tuo piacimento, ma assicurati che non siano incluse ad altro.

Funzioni del Bot: Le principali funzioni permettono il funzionamento del Bot.

sendRequest: Questa è la funzione cURL e Json-Payload usata per prelevare dati da internet.

Utilizzo: sendRequest(url, args, response, method);

botlog: Questa funzione può richiamare un errore mandando un messaggio all'eventuale console. e lo scrive anche sul file $f['logs'] . "/NBF_$botID.log" se esiste.

Utilizzo: logbot("Errore di prova", ['argomento1', 'argomento2'], 'file_in_uso.php');

db_query: Query in PDO.

Utilizzo per unico risultato: db_query("SELECT nome FROM utenti WHERE user_id = ?", [244432022], true);

Utilizzo per più risultati: db_query("SELECT nome FROM utenti WHERE page = ?", ['comando_in_esecuzione'], false);

Utilizzo senza risultato: db_query("UPDATE utenti SET name = ? WHERE user_id = ?", ['Nele', 244432022], 'no');

JsonResponse: Risposta in Json di un link.

Utilizzo: JsonResponse('https://example.com', "GET", $args);

Funzioni per Telegram: da questo punto in poi tutte le funzioni elencate saranno riguardanti le Bot API Telegram, ogni funzione sara elencata con "Descrizione | Metodo" e in seguito la funzione. Aggiornato alle Bot API 4.3.

plugin_manager.php

In questo file puoi gestire i plugins del bot gestendo il file plugins.json direttamente da Telegram.

Comandi:

• /isadmin - Verifica se sei amministratore del Bot.
• /ping - Verifica il tempo che impiega il Bot a richiamare i metodi sulle API.
• /nbflog - Crea il file log per NeleBot.
• /logs - Visualizza i logs di NeleBot.
• /plugins - Prendi la lista dei plugins del bot per poi modificarla.
• /addpl file.php - Aggiungi un plugin alla lista.
• /getlasterror - Visualizza l'ultimo errore del Webhook.
• /error - Test degli errori, usala per fare il primo test della console.

plugins.json

Questo file in Json contiene le informazioni dei plugins ad esempio: {"file.php":true,"file2.php":false}

In questo caso sta a significare che il plugin file.php è attivo, mentre file2.php è disattivato. Un plugin può anche disattivarsi se la devmode è spenta e quel plugin da errori.

NB: Ti consigliamo caldamente di nascondere questo file rinominandolo da index.php

database.php

Questo file permette la connessione al database MySQL, PostgreSQL o SQLite e Redis. Se inesistente, crea la tabella utenti, gruppi e canali.

- Se è presente un utente le informazioni di esso vanno nella variabile $u.

- Se si trova in un gruppo le informazioni di esso vanno nella variabile $g.

- Se si trova in un canale le informazioni di esso vanno nella variabile $c.

Comandi:

• /redis - Verifica il funzionamento di Redis e la sua velocità.
• [/postgre, /mysql, /sqlite]- Verifica il funzionamento del database e la sua velocità.
• /database - Ottieni il contenuto JSON di te stesso sul database.
• /query - Puoi fare una query al database MySQL/PostgreSQL/SQLite manuale direttamente da Telegram.
• /ban - Banna un utente dal Bot via username/ID anche a tempo. Es: /ban @Username for 1 day
• /unban - Sbanna un utente dal Bot via username/ID.

NB: Se hai intenzione di interagire con Redis ti consigliamo di leggere le docs di Redis.

antiflood.php

Questo file previene il rallentamento del bot e l'utilizzo eccessivo delle risorse da parte degli utenti.

Configurazioni Anti-Flood

Messaggi: Numero di messaggi che un utente può inviare entro i secondi stabiliti per poi essere punito.

Secondi: Secondi disponibili per inviare il numero di messaggi per poi essere punito.

Punizioni disponibili: 'forever' per sempre, oppure, inserisci il tempo di ban in secondi, ad esempio: 60(secondi) * 60(minuti) * 2(ore) che vale per 2 ore (7200 secondi).

Ban-Message: Messaggio che l'utente riceve quando viene punito.

UnBan-Message: Messaggio che l'utente riceve quando la punizione si finisce.

Comando per sbannare manualmente: /unban 123456789

NB: Questo si attiva solo se è attivo il database Redis e MySQL/PostgreSQL/SQLite.

comandi.php

Questo, come gli altri plugin di esempio contiene dei comandi eseguibili dagli utenti.

- I comandi in callback_data si prendono da $cbdata.

- I messaggi normali si prendono da $msg. (senza formattazione)

- I comandi si prendono da $cmd. Questi valgono per messaggi come: !start, /start o .start.

Guida

Guida su come attivare un nuovo bot con NeleBot sul vostro VPS / WebHost.

Requisiti di sistema:

VPS

• Distro linux
• NGINX (consigliato)
• Dominio con certificato SSL valido
• PHP 7
• cURL
• MySQL/MariaDB (opzionale)
• PostgreSQL (opzionale)
• SQLite (opzionale)
• Redis (opzionale, obbligatorio se si vuole utilizzare l'antiflood integrato)
• Git (opzionale)

WebHost

• Dominio con certificato SSL valido
• PHP 7
• MySQL/MariaDB (opzionale)
• PostGreSQL (opzionale)
• SQLite (opzionale)

Files

Crea una cartella e inserisci i Files di NeleBot.

La cartella la potrai rinominare a tuo piacimento.

Configurazione del Bot

Ci rechiamo sul file config.php e lo configuriamo secondo queste indicazioni.

Nell'installazione del Bot ti consigliamo di tenere attivare la devmode.

Settaggio del Webhook

Setta il Webhook con il nostro Bot.

1. Dai /start. (Se non parte dai /cancel)

2. Clicca su ➕Nuovo Bot➕.

3. Inserisci le chiavi API date data da BotFather.

4. Vai su config.php e inserisci l'ID e l'Username del Bot come indicato.

5. Inserisci la password che hai impostato sulla configurazione oppure dai /skip per non settare la password.

6. Invia il link del webhook in questo formato: https://tuohost.ip/cartellabot/index.php

7. Se il risultato è true il vostro webhook sarà settato, altrimenti riceverete l'errore che ha riscontrato Telegram nel settarlo.

Avvia il Bot

Ora il Bot dovrebbe essere operativo!

Il Bot non risponde? Vai sul nostro Gruppo di Supporto e richiedi aiuto.