PHP 開發筆記 - 研究 osTicket plugins 架構，以一個可擴充前端資源 plugin 為例

之前團隊在擴充 osTicket 時，主要是下海改他的 code ，但 osTicket 本身也有 plugin 架構，就花點時間看一下資料，感覺比想像中少資料可以看，只好直接看官方的 code 猜有什麼架構可用。

資料:

• https://docs.osticket.com/en/latest/Admin/Manage/Plugins.html
• https://github.com/osTicket/osTicket-plugins
• https://github.com/osTicket/osTicket/blob/develop/setup/doc/signals.md

差不多了，然後看一下這幾個實作，盡量找最簡單的

• https://github.com/osTicket/osTicket-plugins/tree/develop/audit
• https://github.com/osTicket/osTicket-plugins/tree/develop/auth-ldap

剛好團隊內以前也都有開發過 oauth, ldap 整合，所以快速掃一下就可以很快摸索出個大概，重要的資訊: 

• plugin 主要由 3 個檔案組成，分別是 plugin.php, config.php, yourclass.php
• plugin 要儲存一些設定值，只需 config.php 內提供 function getAllOptions() {} 就可以輕鬆達成
• plugin 可以自己再創個 db table 來儲存資料，一樣嘢是在 config.php 中伺機創結構
• plugin 安插自己的程式碼主要是依賴 Signals API 架構很漂亮，但現有 Signals API 的入口點並沒有太多 UI 擴充點
• plugin 可以製作額外的 API ，請參考 audit plugin 內的實作片段

就這樣，可以摸索個大概：

```

osTicket % grep -r "Signal::" * | grep -o 'Signal::[^,]*' | sort | uniq

Signal::connect('api'

Signal::connect('auth.clean'

Signal::connect('cron'

Signal::connect('model.created'

Signal::connect('model.deleted'

Signal::connect('model.updated'

Signal::connect('object.deleted'

Signal::connect('organization.created'

Signal::connect('session.close'

Signal::connect('signal.name'

Signal::connect('staff.header.extra'

Signal::connect('system.install'

Signal::connect('threadentry.created'

Signal::connect('ticket.created'

Signal::connect('user.auth'

Signal::connect('user.created'

Signal::connect() function call

Signal::connect\('([^']+)'/m"

Signal::send($action

Signal::send('agent.audit'

Signal::send('agenttab.audit'

Signal::send('ajax.client'

Signal::send('ajax.scp'

Signal::send('api'

Signal::send('apps.admin'

Signal::send('apps.scp'

Signal::send('auth.clean'

Signal::send('auth.login.failed'

Signal::send('auth.login.succeeded'

Signal::send('auth.logout'

Signal::send('auth.pwchange'

Signal::send('auth.pwreset.email'

Signal::send('auth.pwreset.login'

Signal::send('config.ttfonts'

Signal::send('cron'

Signal::send('export.tables'

Signal::send('mail.decoded'

Signal::send('mail.received'

Signal::send('model.created'

Signal::send('model.deleted'

Signal::send('model.updated'

Signal::send('object.created'

Signal::send('object.deleted'

Signal::send('object.edited'

Signal::send('object.view'

Signal::send('organization.created'

Signal::send('person.login'

Signal::send('person.logout'

Signal::send('session.close'

Signal::send('signal.name'

Signal::send('syslog'

Signal::send('system.install'

Signal::send('task.created'

Signal::send('threadentry.created'

Signal::send('ticket.create.before'

Signal::send('ticket.create.validated'

Signal::send('ticket.created'

Signal::send('ticket.view.more'

Signal::send('user.audit'

Signal::send('user.created'

Signal::send('user.login'

Signal::send('usertab.audit'

Signal::send() for the same named signal.

Signal::send() for the same-named signal.

Signal::send\('([^']+)'/m"

```

以及弄出個簡單的 osTicket plugin 來記錄一下：

https://github.com/changyy/osTicket-plugins-Extra-Frontend-Resources

搭配 osTicket 程式碼變動： 

% cat -n osTicket/include/staff/header.inc.php | head -n 64 | tail -n 10

    55     <link rel="icon" type="image/png" href="<?php echo ROOT_PATH ?>images/oscar-favicon-16x16.png" sizes="16x16" />

    56

    57     <?php

    58     Signal::send('staff.header.extra');

    59     if($ost && ($headers=$ost->getExtraHeaders())) {

    60         echo "\n\t".implode("\n\t", $headers)."\n";

    61     }

    62     ?>

    63 </head>

此 plugin 目的是提供引入更多 js, css resources，但如同上述提到的 osTicket plugin 沒有提供太多前端插入的 Signals ，自己得多添加一個 `Signal::send('staff.header.extra', null);` ，再來提 feature requests 來詢問開發團隊，看看是不是自己誤會了

PHP 開發筆記 - 使用 Docker 在 Ubuntu 22.04 和 PHP 8.1 架設 osTicket v1.18.1 環境，研究 Mail Parser 流程

接續上篇追蹤 osTicket 信件處理流程的筆記，這次用 Docker 包裝可運行和測試的獨立環境，主要採用 Ubuntu 22.04 與 PHP 8.1，並且規劃方式，建構出備份原始信件的架構，以及可反覆解析信件的流程。

首先是 Dockerfile ，主要設計從 GitHub.com 取出 v1.18.1.zip 並解壓縮 /var/www/osticket-v1.18.1，其餘是安裝相關套件和資料庫的帳號建立等等，最後再把 MySQL, PHP-FPM 和 nginx 運行起來，並預設把 nginx logs 寫到 stdout 觀看：

RUN wget https://github.com/osTicket/osTicket/releases/download/v1.18.1/osTicket-v1.18.1.zip -O /tmp/osticket.zip \

    && unzip /tmp/osticket.zip -d /var/www/ \

    && mv /var/www/upload /var/www/osticket-v1.18.1 \

    && cp /var/www/osticket-v1.18.1/include/ost-sampleconfig.php /var/www/osticket-v1.18.1/include/ost-config.php \

    && chown -R www-data:www-data /var/www/osticket-v1.18.1 \

    && rm /tmp/osticket.zip

...

RUN service mysql start && \

    mysql -e "CREATE USER 'developer'@'%' IDENTIFIED BY '12345678';" && \

    mysql -e "GRANT ALL PRIVILEGES ON *.* TO 'developer'@'%' WITH GRANT OPTION;" && \

    mysql -e "CREATE DATABASE osticket_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" && \

    mysql -e "GRANT ALL PRIVILEGES ON osticket_dev.* TO 'developer'@'%';" && \

    mysql -e "FLUSH PRIVILEGES;" 

...

CMD service mysql start && service php8.1-fpm start && service nginx start && tail -f /var/log/nginx/access.log /var/log/nginx/error.log;

接下來更動 include/class.mailfetch.php 檔案，讓他下載信件時，可以存一份在 /tmp 方便後續使用：

@file_put_contents("/tmp/debug-mail.$i", $this->mbox->getRawEmail($i));

最後，弄一隻 api/cron-dev.php 檔案，可以指定 RawMail 的格式路徑，從指定位置讀進來解析信件，如此靠 api/cron-dev.php 就可以輕鬆不斷實驗 MIMEDecode 流程：

# php api/cron-dev.php 

[INFO] Input: /tmp/debug-mail

[INFO] Input File not found

# php api/cron-dev.php /tmp/debug-mail.1

[INFO] Input: /tmp/debug-mail.1

Ticket Object

(

    [ht] => Array

        (

            [ticket_id] => 2

            [ticket_pid] => 

...

            [lastupdate] => 2024-03-27 21:35:52

            [created] => 2024-03-27 21:35:52

            [updated] => 2024-03-27 21:35:52

            [topic] => 

            [staff] => 

            [user] => User Object

                (

                    [ht] => Array

                        (

                            [id] => 2

                            [org_id] => 0

                            [default_email_id] => 2

                            [status] => 0

                            [name] => UserName

                            [created] => 2024-03-27 21:35:52

                            [updated] => 2024-03-27 21:35:52

                            [default_email] => UserEmailModel Object

                                (

                                    [ht] => Array

                                        (

                                            [id] => 2

                                            [user_id] => 2

                                            [flags] => 0

                                            [address] => user@example.com

...

完整資訊擺在 github.com/changyy/osticket-study

PHP 開發筆記 - 追蹤 osTicket v1.18.1 在 PHP8 環境處理信件的流程

公司用 osTicket 系統幾年了，最近把環境升級到 PHP8 和最新版 osTicket v1.18.1 後，同事回報踩到信件內容的 cid 圖片沒正常處理，就先追蹤一下信件處理流程，主要先追到 MIMEDecode 即可。

從官網文件 POP3/IMAP Settings Guide 得知，信件處理的觸發有從 crontab 和 api 的管道，目前就從 crontab 來追：

$ lsb_release -a

No LSB modules are available.

Distributor ID: Ubuntu

Description:    Ubuntu 20.04.6 LTS

Release:        20.04

Codename:       focal

$ php -v

PHP 8.2.17 (cli) (built: Mar 16 2024 08:41:44) (NTS)

Copyright (c) The PHP Group

Zend Engine v4.2.17, Copyright (c) Zend Technologies

    with Zend OPcache v8.2.17, Copyright (c), by Zend Technologies

$ php api/cron.php

接著開始看 api/cron.php 程式碼，大概追到 include/class.cron.php 時，就可以看到 osTicket\Mail\Fetcher::run(); 和 include/class.email.php 檔案了，從 include/class.mailfetch.php 可以看到：

```php

 78     function processMessage(int $i, array $defaults = []) {

 79         try {

 80             // Please note that the returned object could be anything from

 81             // ticket, task to thread entry or a boolean.

 82             // Don't let TicketApi call fool you!

 83             return $this->getTicketsApi()->processEmail(

 84                     $this->mbox->getRawEmail($i), $defaults);

 85         } catch (\TicketDenied $ex) {

 86             // If a ticket is denied we're going to report it as processed

 87             // so it can be moved out of the Fetch Folder or Deleted based

 88             // on the MailBox settings.

 89             return true;

 90         } catch (\EmailParseError $ex) {

 91             // Upstream we try to create a ticket on email parse error - if

 92             // it fails then that means we have invalid headers.

 93             // For Debug purposes log the parse error + headers as a warning

 94             $this->logWarning(sprintf("%s\n\n%s",

 95                         $ex->getMessage(),

 96                         $this->mbox->getRawHeader($i)));

 97         }

 98         return false;

 99     }

```

接著在 processEmail 前埋一個 @file_put_contents('/tmp/debug-mail', print_r($this->mbox->getRawEmail($i), true)); ，如此處理信件時，原始格式就會被記錄在 /tmp/debug-mail 裡，下一刻就能再重現信件格式的處理流程

小改後面：

$ sudo cp api/cron.php  api/cron-debug.php

$ tail -n 5 api/cron-debug.php 

//LocalCronApiController::call();

//

$obj = new \TicketApiController('cli');

print_r($obj->processEmail(file_get_contents('/tmp/debug-mail'), []));

?>

如此運行時就可以看資訊：

$ php api/cron-debug.php 

Ticket Object

(

    [ht] => Array

        (

            [ticket_id] => #

            [ticket_pid] => 

            [number] => #####

...

接著要來研究信件處理流程，就來到了 include/api.tickets.php 檔案：

```php

    function processEmail($data=false, array $defaults = []) {

        try {

            if (!$data)

                $data = $this->getEmailRequest();

            elseif (!is_array($data))

                $data = $this->parseEmail($data);

            print_r($data);

        } catch (Exception $ex)  {

            throw new EmailParseError($ex->getMessage());

        }

...

```

繼續追 include/class.api.php 檔案：

```php

238     function parseRequest($stream, $format, $validate=true) {

239         $parser = null;

240         switch(strtolower($format)) {

241             case 'xml':

242                 if (!function_exists('xml_parser_create'))

243                     return $this->exerr(501, __('XML extension not supported'));

244                 $parser = new ApiXmlDataParser();

245                 break;

246             case 'json':

247                 $parser = new ApiJsonDataParser();

248                 break;

249             case 'email': 

250                 $parser = new ApiEmailDataParser();

251                 break;

252             default:

253                 return $this->exerr(415, __('Unsupported data format'));

254         }

255         

256         if (!($data = $parser->parse($stream)) || !is_array($data)) {

257             $this->exerr(400, $parser->lastError());

258         }

259         

260         //Validate structure of the request.

261         if ($validate && $data)

262             $this->validate($data, $format, false);

263         

264         return $data;

265     }

266     

267     function parseEmail($content) {

268         return $this->parseRequest($content, 'email', false);

269     }

```

繼續追 include/class.mailparse.php 檔案，主要是追蹤 EmailDataParser -> Mail_Parse -> Mail_mimeDecode ，最後就是 include/pear/Mail/mimeDecode.php 的處理 MIMEDecode 的實作了。

剩下的工作就是研究它解析原始信件的流程，看看是 MIMEDecode 是否少了遞迴解，還是有什麼限制了：

github.com/osTicket/osTicket/blob/develop/include/pear/Mail/mimeDecode.php