Developer documentation - question & answers

[cm-schl]

Hi,

because I'm trying to write a plugin for SnappyMail I tried to understand the logic how everything is connected - as at the moment there is no documentation for developers I would like to ask if my thoughts are correct. Maybe this could be the first step to produce some documentation regarding the development of plugins etc. 🙂.

Please correct me if I'm wrong (and as I'm new to this, this could happen often 🙈😄). It's also possible that I'm using some wrong words - sorry about that...

History of SnappyMail / Rainloop

For me it made some things clearer to understand how SnappyMail was created.
Rainloop initially was written by Timur Usenko who worked at AfterLogic. He wrote the library MailSo that handles the main part of the IMAP functions in SnappyMail.
As Rainloop does not seem to be under heavy development the project was took by @the-djmaze to create SnappyMail.
SnappyMail therefore contains the code of Rainloop, but has been modified a lot to bring it to a next level.

How SnappyMail gets started and how Hooks work

1. The include.php file (https://github.com/the-djmaze/snappymail/blob/efbc7563ac14ab0747b50af179654303042b3c74/snappymail/v/0.0.0/include.php) calls Rainloop\Service::Handle()
   

   snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Service.php

   Line 10 in efbc756

   public static function Handle() : bool

2. Service.php (https://github.com/the-djmaze/snappymail/blob/efbc7563ac14ab0747b50af179654303042b3c74/snappymail/v/0.0.0/app/libraries/RainLoop/Service.php) calls Api::Actions().
   

   snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Api.php

   Line 19 in efbc756

   public static function Actions() : Actions

   • Additional info: Service.php afterwards goes ahead initializing for example the caching functions etc. and ends with a launch of the function BootEnd() in Actions.php
3. Api.php creates $oActions by the class Rainloop/Actions.php.
   

   snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Actions.php

   Line 122 in efbc756

   function __construct()

4. The constructor of /RainLoop/Actions.php creates an object $oPlugins by RainLoop/Plugins/Manager.php
   

   snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Actions.php

   Line 154 in efbc756

   $this->oPlugins = new Plugins\Manager($this);

5. The constructor of RainLoop/Plugins/Manager.php searches for active plugins. It then calls the Init() function of every active plugin.

As the Init() function of every plugin is called by Manager.php inside this function each plugin can register itself to be launched (=callback function) at various points in the code of SnappyMail (=hooks).
SnappyMail calls the functions registered by the single plugins by launching the function RunHook:

snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Plugins/Manager.php

Line 313 in efbc756

public function RunHook(string $sHookName, array $aArg = array(), bool $bLogHook = true) : self

The function fabrica

snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Actions.php

Line 179 in efbc756

protected function fabrica(string $sName, ?Model\Account $oAccount = null)

This functions seems to be a central part of the code. It returns needed objects by checking the passed variable $sName. For example it returns a FileStorage Object when $sName contains 'files'. Also fabrica calls RunHook twice (hook name main.fabrica and filter.fabrica). fabricais called often and therefore a plugin inside his callback function should check for example the content of$sName` that is also passed to the callback function.

Searching for the best hook

As at the moment there is no detailed documentation it is possible to search for hooks by doing a fulltext search for the string RunHook( this returns every active hook and his circumstances.

[the-djmaze]

More info can be found at plugins/README.md

[MI-KY]

...so is everything true what was written in the first post? Cause the readme did not helped me before... (#576)

By the way thanks for your update of that readme - these comments are useful.

[the-djmaze]

Yes what you wrote is correct.

There are some caveats though. Most can be found in existing plugins, but a good documentation for each would be nice.

I've also made a big change in the smtp/imap/sieve hooks to make them more powerfull.
This requires v2.21 but will make future development also flexible.

[cm-schl]

Hi,

thanks for your reply!
Should I create a new wiki page for the developer documentation or do we put everything into the readme file inside the plugin folder?
Maybe the wiki is better as other developer informations could be added that do not have to do with plugins?

[the-djmaze]

Wiki would be better and then split into multiple pages

[the-djmaze]

At the moment this issues could "loose" their "documentation" tag because the info is now inside the wiki

It would be best to keep the "documentation" tag so that people know it is documented (now or later).
We could additionally add a link to the wiki page, but what if changed in the future?

As you can imagine this is a lot of work and therefore I hope you could also throw an eye on this to make sure that the information there is not completely wrong... I'm doing my best to check things before writing them, but you never know...

You are doing great! I will keep an eye on them 😉

[MI-KY]

Hi, thanks for the response!
Adding a link maybe would also trigger notifications to people involved in this issue (i think) - so this could get a bit annoying when I response to old issues with a wiki link 🙂 also you're right that this could change again...
I'm ok with this when you would like to leave the flag also if I don't see the use case after porting it to the wiki 😉. It's possible that someone would search for this flags - I personally would look into the wiki instead because I never thought that these flags could be used to mark interesting issues. But I see that there are different approaches for this 🙂 👍

[MI-KY]

Hi @the-djmaze ,
a question about the "Domain" popup in the admin panel: there exists an option "Use login as sender" but it seams this is not used anymore? It seams that this isn't used anymore?

snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Actions/Messages.php

Line 982 in ea3eff5

$oFromIdentity = $this->GetIdentityByID($oAccount, $this->GetActionParam('IdentityID', ''));

[the-djmaze]

it seams this is not used anymore? It seams that this isn't used anymore?

Actually, it is off/broken at the moment. Should be enabled again later.

snappymail/snappymail/v/0.0.0/app/libraries/RainLoop/Actions/Messages.php

Line 987 in ea3eff5

if ($oAccount->Domain()->OutSetSender()) {

Basically the option sets the Sender header for outgoing messages that have a different From then the actual login sender.
Example:

1. Login as [email protected]
2. Send mail with identity [email protected]
3. The option sets:

Sender: [email protected]
From: [email protected]

[MI-KY]

perfect, thanks for the clarification 🙂

[MI-KY]

Hi @the-djmaze
I'm at a good point with the Admin Documentation (at least I think so 😆).
At the moment I've began to write the docs for the Config menu / application.ini settings. The idea would be to create a table that contains the setting, the default value (from Application.php), a link to a eventual setting inside the admin panel and a description what the setting is doing.
Now there are some questions that I could not answer myself:

1. do we need other columns with additional information?
2. is empty ok when the setting inside the application.ini will be ''? Should I maybe add a type of legend that says empty inside the config menu is '' inside the application.ini?
3. I'm not sure about the setting app_path. I know it comes from issue Web resources absolute path #379 and I know that with it you can edit the path of the app. But what is it doing exactly? Does SnappyMail always looks for files inside the directory ./snappymail/ and this setting substitutes this path to something other?

[the-djmaze]

1. i can't think of any at the moment
2. better to say something like '' (empty string) to indicate it is a string.
3. In your browser address bar you may see https://snappymail.domain.tld/ but through a proxy it goes to https://domain.tld/snappymail then there is a conflict in the path that PHP code returns.
   With app_path you can define which (/ or /snappymail) to use so that everything works.