There's an elaborate architecture description in Russian at Habrahabr.
The library has several architectural layers:
- protocol layer – MTProto nodes encoding/decoding
- client layer – API calls
- scenario layer – end-to-end scenarios solving some problems
- application layer – we have some examples of using and combining scenarios.
We aim at the following principles while designing the library:
- fail fast – although the protocol documentation is open, the protocol itself is proprietary, so the library should properly react to unexpected API changes
- conformity – the library behaves as close to official clients as possible
- testability – the code should be testable (preferably using end-to-end tests), have low coupling
Suppose, you have a purpose your application should do, for example, would like to get featured stickers.
First of all, you need to implement all TL nodes needed to solve your problem. There are two types of nodes in library:
- client nodes, those we send to Telegram server
- server nodes, those we receive from Telegram server
You can use official API doc as a reference to implement the nodes.
The next step is adding the calls to a client.
The best way would be to extend some base Client (like InfoClient) with your methods.
For example, https://github.com/Postuf/telegram-osint-lib/blob/c4a6fbdd35c2f56f3de3f03d55f5237125459cf0/src/Client/InfoObtainingClient/StickerClient.php – here we added methods to perform get_featured_stickers and get_sticker_set calls.
Implementing an interface with your calls is considered architecturally a good practice, for example, we can add some caching upon your client if needed.
The scenario is a piece of application logic you can use to solve some task. The simplest scenario has some operation it performs (getting featured stickers in our case) and a callback to be called upon completion. See: https://github.com/Postuf/telegram-osint-lib/blob/c4a6fbdd35c2f56f3de3f03d55f5237125459cf0/src/Scenario/FeaturedStickerSetScenario.php
Scenarios can call other scenarios to achieve their goal, for example:
We use a concept of traces to test scenarios. A trace is a sequence of responses from server we receive. To store a sequence (from a real communication session), please use TracingBasicClientImpl:
A text file would be generated, next, you can use it in your test: https://github.com/Postuf/telegram-osint-lib/blob/c4a6fbdd35c2f56f3de3f03d55f5237125459cf0/tests/Integration/Scenario/GeoSearchTest.php
Before being used in your test, file needs to be converted to a readable format, there is a tool for that:
php traceConverter.php -i ../examples/26836dce4e3e1489348b83c536f742ce.txt
The resulting file would be a JSON containing a sequence of nodes received from server in human-readable format.
The file may need some filtering to exclude unnecessary nodes; in whole such test indicates that your scenario achieves some desired result in a real session with Telegram server.