diff --git a/docs/40_Data_format.md b/docs/40_Data_format.md new file mode 100644 index 0000000000000000000000000000000000000000..184b86fe61d2c00b0d72fac37212f02b91348500 --- /dev/null +++ b/docs/40_Data_format.md @@ -0,0 +1,17 @@ +Data are written when a new email was catched by `php-sendmail.php`. If the output does not exist, it will be created. If it exists, a new line will be added. + +The format of `[emailcatcher]/data/emaildata.txt` is quite simple. + +For an email a single line will be created. It is a single json object per line. +Keys are + +| Key | Type | Description | +| -- | -- | -- | +| date | {timestamp} | time when email was fetched | +| mail | {string} | value from stdin. It contains email header + `\r\n\r\n` + email body | + +Example: + +```text +{"date":"2024-10-08 08:07:04","mail":"To: john@example.com\r\nSubject: Text message\r\n\r\n\nHello\n\nHere is a text message.\n\nAxel\n\r\n"} +``` diff --git a/docs/90_PHP-classes/emailcatcher.class.php.md b/docs/90_PHP-classes/emailcatcher.class.php.md new file mode 100644 index 0000000000000000000000000000000000000000..f30058a3dbb4d31d1a1c47c89f5f9c8d9adfbff7 --- /dev/null +++ b/docs/90_PHP-classes/emailcatcher.class.php.md @@ -0,0 +1,128 @@ +## 📦 Class \emailcatcher + +```txt +/** + * ======================================================================= + * + * PHP EMAIL CATCHER + * Read emails sent by mail() and browse them + * + * 👤 Author: Axel Hahn, Institute for Medical Education, University of Bern + * 📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/php-emailcatcher> + * 📗 Docs: <https://os-docs.iml.unibe.ch/php-emailcatcher/> + * 📜 License: GNU GPL 3.0 + * + * ---------------------------------------------------------------------- + * 2024-10-08 v0.1 initial version + * 2024-10-16 v0.2 detect parse error when reading email data + * ======================================================================= + */ +``` + +## 🔶 Properties + +(none) + +## 🔷 Methods + +### 🔹 public __construct() + + + +**Return**: `` + +**Parameters**: **0** + + +### 🔹 public catchEmail() + +Fetch email of a single email from stdin and store it.It returns the return value of file_put_contents().used in php-sendmail.php + +**Return**: `bool|int *` + +**Parameters**: **0** + + +### 🔹 public getBody() + +Get message body of the selected email + +**Return**: `mixed` + +**Parameters**: **0** + + +### 🔹 public getEmail() + +Get hash for a single email with all metadata and body + +**Return**: `array` + +**Parameters**: **1** + +| Parameter | Type | Description +|-- |-- |-- +| \<optional\> $sEmail2Show = '' | `optional: *` | optional: email id to show + + +### 🔹 public getField() + +Get a Meta value of the selected email + +**Return**: `mixed` + +**Parameters**: **1** + +| Parameter | Type | Description +|-- |-- |-- +| \<required\> string $sField | `string` | + + +### 🔹 public getHeader() + +get message header of the selected email + +**Return**: `mixed` + +**Parameters**: **0** + + +### 🔹 public readEmails() + +Get a list of emails to render an inbox like selection.It doesn't contain header and body - just metadata + +**Return**: `array` + +**Parameters**: **0** + + +### 🔹 public setId() + +Set a single email by id.It returns a bool for success: false = failed + +**Return**: `bool` + +**Parameters**: **1** + +| Parameter | Type | Description +|-- |-- |-- +| \<required\> string $sId | `string` | + + +### 🔹 public storeEmail() + +Store a new email. It returns the return value of file_put_contents(). + +**Return**: `int|bool` + +**Parameters**: **1** + +| Parameter | Type | Description +|-- |-- |-- +| \<required\> $sMaildata | `maildata *` | maildata with header and body + + + + +--- +Generated with Axels PHP class doc parser. \ No newline at end of file diff --git a/scripts/generate_class_docs.sh b/scripts/generate_class_docs.sh new file mode 100755 index 0000000000000000000000000000000000000000..79ede501260f8a2d494a083cfd9d2553bda388f9 --- /dev/null +++ b/scripts/generate_class_docs.sh @@ -0,0 +1,59 @@ +#!/bin/bash +# ====================================================================== +# +# Generate markdown docs for selected php classes +# +# ---------------------------------------------------------------------- +# 2024-10-16 v0.1 <axel.hahn@unibe.ch> initial version +# ====================================================================== + +# ---------------------------------------------------------------------- +# CONFIG +# ---------------------------------------------------------------------- + +cd "$( dirname $0)/.." +APPDIR=$(pwd) +DOCDIR=$APPDIR/docs/90_PHP-classes + +# works on axels dev env only ... this class is not published yet +cd /home/axel/data/opensource/php-class/class-phpdoc || exit + +# list of files to generate a class documentation +Classfiles=" + classes/emailcatcher.class.php + +" + +# ---------------------------------------------------------------------- +# FUNCTIONS +# ---------------------------------------------------------------------- + +# generate a doc file for a single class file +# global DOCDIR path for doc page +# param string filename of class file +function docgen(){ + local myfile=$1 + outfile=$DOCDIR/$( basename "$myfile" ).md + + echo "----- $myfile" + echo " $outfile" + ./parse-class.php --out md "$APPDIR/$myfile" > "$outfile" + echo +} + +# ---------------------------------------------------------------------- +# MAIN +# ---------------------------------------------------------------------- + + +# ./parse-class.php --out md "$APPDIR/public_html/server/classes/appmonitor-server.class.php"; exit + +# generate all docs +for myfile in $Classfiles +do + docgen "$myfile" +done + +echo "Done" + +# ----------------------------------------------------------------------