Initial commit

.gitignore

@@ -0,0 +1,3 @@
+/vendor/
+/doc/
+/.project

README.md

@@ -0,0 +1,64 @@
+zyberspace/telegram-cli-client
+==============================
+php-client for [telegram-cli](https://github.com/vysheng/tg/)
+
+Requirements
+------------
+ - a running [telegram-cli](https://github.com/vysheng/tg/) listening on a unix-socket (`-S`) or a port (`-P`). Needs to be configured already (phone-number, etc.).
+ - php >= 5.4.0
+
+Usage
+-----
+
+###Setup telegram-cli
+[telegram-cli](https://github.com/vysheng/tg/) needs to run on a unix-socket (`-S`) or a port (`-P`), so *telegram-cli-client* can connect to it.  
+You should also start it with `-W` so the contact-list gets loaded on startup.  
+For this example we will take the following command (execute it from the dir, where you installed telegram-cli, not the php-client), `-d` lets it run as daemon.:
+
+```shell
+./bin/telegram-cli -dWS /tmp/tg.sck &
+```
+
+If you never started telegram-cli before, you need to start it first in normal mode, so you can type in your telegram-phone-number and register it, if needed (`./bin/telegram-cli`).
+
+To stop the daemon use `killall telegram-cli` or `kill -TERM [telegram-pid]`.
+
+###Install telegram-cli-client with composer
+In your project-root:
+
+```shell
+composer require zyberspace/telegram-cli-client
+```
+
+Composer will then automatically add the package to your project requirements and install it (also creates the `composer.json` if you don't have one already).
+
+###Use it
+
+```php
+require('vendor/autoload.php');
+$telegram = new \Zyberspace\Telegram\Cli\Client('unix:///tmp/tg.sck');
+
+$contactList = $telegram->getContactList();
+$telegram->msg($contactList[0], 'Hey man, what\'s up? :D');
+```
+
+Documentation
+-------------
+To create the docs, just run `phpdoc` in the the project-root.  
+An online-version is available at [phpdoc.zyberware.org/zyberspace/telegram-cli-client](http://phpdoc.zyberware.org/zyberspace/telegram-cli-client/).
+
+Supported Commands
+------------------
+You can execute every command with the `exec()`-method, but there are also several command-wrappers available in the `AbstractClientCommands`-Class ([doc-link](http://phpdoc.zyberware.org/zyberspace/telegram-cli-client/classes/Zyberspace.Telegram.Cli.AbstractClientCommands.html)), which the main class extends (see the `example.php`).
+
+If you use `exec()` directly, please don't forget to escape the peer (contacts, chat-names, etc.) with `escapePeer()` and all string-arguments with `escapeStringArgument()` to avoid errors.
+
+API-Stability
+-------------
+The api of the commands wrappers will definitely change in the future, for example `getHistory()` only returns the raw answer of the telegram-cli right now and is not really useful. Therefore you should not use this in production yet.
+
+**If you still want to use this in your project, make sure you stay at the same [minor](http://semver.org/spec/v2.0.0.html)-version (`~0.1.0` or `0.1.*` for example)**.
+
+License
+-------
+This software is licensed under the [Mozilla Public License v. 2.0](http://mozilla.org/MPL/2.0/). For more information, read the file `LICENSE`.

composer.json

@@ -0,0 +1,21 @@
+{
+    "name": "zyberspace/telegram-cli-client",
+    "description": "php-client for telegram-cli",
+    "type": "library",
+    "homepage": "https://github.com/zyberspace/php-telegram-cli-client",
+    "license": "MPL-2.0",
+    "authors": [
+        {
+            "name": "zyberspace",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": ">=5.4.0,<6.0.0"
+    },
+    "autoload": {
+        "psr-0": {
+            "Zyberspace\\Telegram\\Cli\\": "lib/"
+        }
+    }
+}

example.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * Copyright 2015 Eric Enold <[email protected]>
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+require('vendor/autoload.php');
+$telegram = new \Zyberspace\Telegram\Cli\Client('unix:///tmp/tg.sck');
+
+$contactList = $telegram->getContactList();
+var_dump($contactList);
+
+var_dump($telegram->msg($contactList[0], '"Te\'st"' . "\n" . time()));

lib/Zyberspace/Telegram/Cli/AbstractClientCommands.php

@@ -0,0 +1,216 @@
+<?php
+/**
+ * Copyright 2015 Eric Enold <[email protected]>
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+namespace Zyberspace\Telegram\Cli;
+
+//This class should actually be a trait and not abstract, but this way we can support PHP 5.3 and
+//don't rely on PHP 5.4
+
+/**
+ * Defines some command-wrappers, that get extended by the Client.
+ */
+abstract class AbstractClientCommands
+{
+    /**
+     * Sets status as online.
+     *
+     * @return boolean true on success, false otherwise
+     *
+     * @uses exec()
+     */
+    public function setStatusOnline()
+    {
+        return $this->exec('status_online');
+    }
+
+    /**
+     * Sets status as offline.
+     *
+     * @return boolean true on success, false otherwise
+     *
+     * @uses exec()
+     */
+    public function setStatusOffline()
+    {
+        return $this->exec('status_offline');
+    }
+
+    /**
+     * Sends a text message to $peer.
+     *
+     * @param string $peer The peer, gets escaped with escapePeer(),
+     *                     so you can directly use the values from getContactList()
+     * @param string $msg The message to send, gets escaped with escapeStringArgument()
+     *
+     * @return boolean true on success, false otherwise
+     *
+     * @uses exec()
+     * @uses escapePeer()
+     * @uses escapeStringArgument()
+     */
+    public function msg($peer, $msg)
+    {
+        $peer = $this->escapePeer($peer);
+        $msg = $this->escapeStringArgument($msg);
+        return $this->exec('msg ' . $peer . ' ' . $msg);
+    }
+
+    /**
+     * Adds a user to the contact list
+     *
+     * @param int|string $phoneNumber The phone-number of the new contact, needs to be a telegram-user.
+     *                                Can start with or without '+'.
+     * @param string $firstName The first name of the new contact
+     * @param string $lastName The last name of the new contact
+     *
+     * @return string|boolean The new contact "$firstName $lastName"; false if somethings goes wrong
+     *
+     * @uses exec()
+     * @uses escapeStringArgument()
+     */
+    public function addContact($phoneNumber, $firstName, $lastName)
+    {
+        if (is_string($phoneNumber) && $phoneNumber[0] === '+') {
+            $phoneNumber = substr($phoneNumber, 1);
+        }
+        $phoneNumber = (int) $phoneNumber;
+
+        return $this->exec('add_contact ' . $phoneNumber . ' ' . $this->escapeStringArgument($firstName)
+            . ' ' . $this->escapeStringArgument($lastName));
+    }
+
+    /**
+     * Renames a user in the contact list
+     *
+     * @param string $contact The contact, gets escaped with escapePeer(),
+     *                        so you can directly use the values from getContactList()
+     * @param string $firstName The new first name for the contact
+     * @param string $lastName The new last name for the contact
+     *
+     * @return string|boolean The renamed contact "$firstName $lastName"; false if somethings goes wrong
+     *
+     * @uses exec()
+     * @uses escapeStringArgument()
+     */
+    public function renameContact($contact, $firstName, $lastName)
+    {
+        return $this->exec('rename_contact ' . $this->escapePeer($contact)
+            . ' ' . $this->escapeStringArgument($firstName) . ' ' . $this->escapeStringArgument($lastName));
+    }
+
+    /**
+     * Deletes a contact.
+     *
+     * @param string $contact The contact, gets escaped with escapePeer(),
+     *                        so you can directly use the values from getContactList()
+     *
+     * @return boolean true on success, false otherwise
+     *
+     * @uses exec()
+     * @uses escapePeer()
+     */
+    public function deleteContact($contact)
+    {
+        return $this->exec('del_contact ' . $this->escapePeer($contact));
+    }
+
+    /**
+     * Marks all messages with $peer as read.
+     *
+     * @param string $peer The peer, gets escaped with escapePeer(),
+     *                     so you can directly use the values from getContactList()
+     *
+     * @return boolean true on success, false otherwise
+     *
+     * @uses exec()
+     * @uses escapePeer()
+     */
+    public function markRead($peer)
+    {
+        return $this->exec('mark_read ' . $this->escapePeer($peer));
+    }
+
+    /**
+     * Returns an array of all contacts in form of "[firstName] [lastName]".
+     *
+     * @return array|boolean An array with your contacts; false if somethings goes wrong
+     *
+     * @uses exec()
+     */
+    public function getContactList()
+    {
+        return explode(PHP_EOL, $this->exec('contact_list'));
+    }
+
+    /**
+     * Executes the user_info-command and returns it answer (the answer is unformated right now).
+     * Will get better formated in the future.
+     *
+     * @param string $user The user, gets escaped with escapePeer(),
+     *                     so you can directly use the values from getContactList()
+     *
+     * @return string|boolean The answer of the user_info-command; false if somethings goes wrong
+     *
+     * @uses exec()
+     * @uses escapePeer()
+     */
+    public function getUserInfo($user)
+    {
+        return $this->exec('user_info ' . $this->escapePeer($user));
+    }
+
+    /**
+     * Returns an array of all your dialogs in form of
+     * "User [firstName] [lastName]: [number of unread messages] unread". Will get better formated in the future.
+     *
+     * @return array|boolean An array with your dialogs; false if somethings goes wrong
+     *
+     * @uses exec()
+     */
+    public function getDialogList()
+    {
+        return explode(PHP_EOL, $this->exec('dialog_list'));
+    }
+
+    /**
+     * Executes the history-command and returns it answer (the answer is unformated right now).
+     * Will get better formated in the future.
+     *
+     * @param string $peer The peer, gets escaped with escapePeer(),
+     *                     so you can directly use the values from getContactList()
+     * @param int $limit (optional) Limit answer to $limit messages. If not set, there is no limit.
+     * @param int $offset (optional) Use this with the $limit parameter to go through older messages.
+     *                    Can also be negative.
+     *
+     * @return string|boolean The answer of the history-command; false if somethings goes wrong
+     *
+     * @uses exec()
+     * @uses escapePeer()
+     *
+     * @see https://core.telegram.org/method/messages.getHistory
+     */
+    public function getHistory($peer, $limit = null, $offset = null)
+    {
+        if ($limit !== null) {
+            $limit = (int) $limit;
+            if ($limit < 1) { //if limit is lesser than 1, telegram-cli crashes
+                $limit = 1;
+            }
+            $limit = ' ' . $limit;
+        } else {
+            $limit = '';
+        }
+        if ($offset !== null) {
+            $offset = ' ' . (int) $offset;
+        } else {
+            $offset = '';
+        }
+
+        return $this->exec('history ' . $this->escapePeer($peer) . $limit . $offset);
+    }
+}