Add in software files and templates

root/opt/dmarc-srg/classes/Settings/Setting.php

@@ -0,0 +1,242 @@
+<?php
+
+/**
+ * dmarc-srg - A php parser, viewer and summary report generator for incoming DMARC reports.
+ * Copyright (C) 2020 Aleksey Andreev (liuch)
+ *
+ * Available at:
+ * https://github.com/liuch/dmarc-srg
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of  MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * =========================
+ *
+ * This file contains implementation of the class Setting
+ *
+ * @category API
+ * @package  DmarcSrg
+ * @author   Aleksey Andreev (liuch)
+ * @license  https://www.gnu.org/licenses/gpl-3.0.html GNU/GPLv3
+ */
+
+namespace Liuch\DmarcSrg\Settings;
+
+use Liuch\DmarcSrg\Core;
+use Liuch\DmarcSrg\Exception\SoftException;
+use Liuch\DmarcSrg\Exception\DatabaseNotFoundException;
+
+/**
+ * It's a class for accessing to settings item data
+ *
+ * This class is designed for storing and manipulating one item of settings data.
+ * All queries to the datatabase are made in lazy mode.
+ */
+abstract class Setting
+{
+    public const TYPE_STRING        = 1;
+    public const TYPE_INTEGER       = 2;
+    public const TYPE_STRING_SELECT = 3;
+
+    protected $db      = null;
+    protected $name    = null;
+    protected $value   = null;
+    protected $wignore = false;
+
+    /**
+     * Returns the type of the setting
+     *
+     * @return int Type of the setting
+     */
+    abstract public function type(): int;
+
+    /**
+     * Checks if the value is correct
+     *
+     * @return bool True if the value is correct or false otherwise
+     */
+    abstract protected function checkValue(): bool;
+
+    /**
+     * Converts a string to the value
+     *
+     * @param string $s String for conversion
+     *
+     * @return void
+     */
+    abstract protected function stringToValue(string $s): void;
+
+    /**
+     * Returns a string representation of the value
+     *
+     * @return string The string value
+     */
+    abstract protected function valueToString(): string;
+
+    /**
+     * It's a constructor of the class
+     *
+     * Some examples of using:
+     * (new Setting('some.setting'))->value(); - will return the value of the setting 'some.setting'.
+     * (new Setting([ 'name' => 'some.setting', 'value' => 'some string value' ])->save(); - will add
+     * this setting to the database if it does not exist in it or update the value of the setting.
+     *
+     * @param string|array       $data    Some setting data to identify it
+     *                                    string value is treated as a name
+     *                                    array has these fields: `name`, `value`
+     *                                    and usually uses for creating a new setting item.
+     * @param boolean            $wignore If true the wrong value is reset to the default
+     *                                    or it throws an exception otherwise.
+     * @param DatabaseController $db      The database controller
+     *
+     * @return void
+     */
+    public function __construct($data, bool $wignore = false, $db = null)
+    {
+        $this->wignore = $wignore;
+        $this->db      = $db ?? Core::instance()->database();
+        switch (gettype($data)) {
+            case 'string':
+                $this->name = $data;
+                SettingsList::checkName($this->name);
+                return;
+            case 'array':
+                if (!isset($data['name']) || gettype($data['name']) !== 'string') {
+                    break;
+                }
+                $this->name = $data['name'];
+                SettingsList::checkName($this->name);
+                if (isset($data['value'])) {
+                    $this->value = $data['value'];
+                    if (!$this->checkValue()) {
+                        if (!$wignore) {
+                            break;
+                        }
+                        $this->resetToDefault();
+                    }
+                }
+                return;
+        }
+        throw new SoftException('Wrong setting data');
+    }
+
+    /**
+     * Returns the name of the setting
+     *
+     * @return string The name of the setting
+     */
+    public function name(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Returns the value of the setting
+     *
+     * @return mixed The value of the setting
+     */
+    public function value()
+    {
+        if (is_null($this->value)) {
+            $this->fetchData();
+        }
+        return $this->value;
+    }
+
+    /**
+     * Assigns the passed value to the setting
+     *
+     * @param mixed Value to assign
+     *
+     * @return void
+     */
+    public function setValue($value): void
+    {
+        $this->value = $value;
+        if (!$this->checkValue()) {
+            if (!$this->wignore) {
+                throw new SoftException('Wrong setting value');
+            }
+            $this->resetToDefault();
+        }
+    }
+
+    /**
+     * Returns an array with setting data
+     *
+     * @return array Setting data
+     */
+    public function toArray(): array
+    {
+        if (is_null($this->value)) {
+            $this->fetchData();
+        }
+        switch ($this->type()) {
+            case self::TYPE_STRING:
+                $type = 'string';
+                break;
+            case self::TYPE_INTEGER:
+                $type = 'integer';
+                break;
+            case self::TYPE_STRING_SELECT:
+                $type = 'select';
+                break;
+        }
+        return [
+            'type'    => $type,
+            'name'    => $this->name,
+            'value'   => $this->value,
+            'default' => SettingsList::$schema[$this->name]['default']
+        ];
+    }
+
+    /**
+     * Saves the setting to the database
+     *
+     * Updates the value of the setting in the database if the setting exists there or insert a new record otherwise.
+     *
+     * @return void
+     */
+    public function save(): void
+    {
+        $this->db->getMapper('setting')->save($this->name, $this->valueToString());
+    }
+
+    /**
+     * Fetches the setting data from the database by its name
+     *
+     * @return void
+     */
+    private function fetchData(): void
+    {
+        try {
+            $res = $this->db->getMapper('setting')->value($this->name);
+        } catch (DatabaseNotFoundException $e) {
+            $this->resetToDefault();
+            return;
+        }
+        $this->stringToValue($res);
+        if (!$this->checkValue()) {
+            $this->resetToDefault();
+        }
+    }
+
+    /**
+     * Resets the setting value to its default value
+     *
+     * @return void
+     */
+    private function resetToDefault(): void
+    {
+        $this->value = SettingsList::$schema[$this->name]['default'];
+    }
+}

root/opt/dmarc-srg/classes/Settings/SettingInteger.php

@@ -0,0 +1,109 @@
+<?php
+
+/**
+ * dmarc-srg - A php parser, viewer and summary report generator for incoming DMARC reports.
+ * Copyright (C) 2020 Aleksey Andreev (liuch)
+ *
+ * Available at:
+ * https://github.com/liuch/dmarc-srg
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of  MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * =========================
+ *
+ * This file contains implementation of the class SettingInteger
+ *
+ * @category API
+ * @package  DmarcSrg
+ * @author   Aleksey Andreev (liuch)
+ * @license  https://www.gnu.org/licenses/gpl-3.0.html GNU/GPLv3
+ */
+
+namespace Liuch\DmarcSrg\Settings;
+
+/**
+ * It's a class for accessing to settings item data
+ *
+ * This class contains the implementation of the setting for integer values.
+ */
+class SettingInteger extends Setting
+{
+    /**
+     * Returns the type of the setting
+     *
+     * @return int Type of the setting
+     */
+    public function type(): int
+    {
+        return Setting::TYPE_INTEGER;
+    }
+
+    /**
+     * Checks if the value is correct
+     *
+     * @return bool True if the value is correct or false otherwise
+     */
+    protected function checkValue(): bool
+    {
+        if (gettype($this->value) === 'integer') {
+            $sch = &SettingsList::$schema[$this->name];
+            if (!isset($sch['minimum']) || $this->value >= $sch['minimum']) {
+                if (!isset($sch['maximum']) || $this->value <= $sch['maximum']) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Converts a string to the value
+     *
+     * @param string $s String for conversion
+     *
+     * @return void
+     */
+    protected function stringToValue(string $s): void
+    {
+        $this->value = intval($s);
+    }
+
+    /**
+     * Returns a string representation of the value
+     *
+     * @return string The string value
+     */
+    protected function valueToString(): string
+    {
+        return strval($this->value);
+    }
+
+    /**
+     * Returns an array with setting data
+     *
+     * @return array Setting data
+     */
+    public function toArray(): array
+    {
+        $res = parent::toArray();
+        $sch = &SettingsList::$schema[$this->name];
+        if (isset($sch['minimum'])) {
+            $res['minimum'] = $sch['minimum'];
+        }
+        if (isset($sch['maximum'])) {
+            $res['maximum'] = $sch['maximum'];
+        }
+        return $res;
+    }
+}
+

root/opt/dmarc-srg/classes/Settings/SettingString.php

@@ -0,0 +1,83 @@
+<?php
+
+/**
+ * dmarc-srg - A php parser, viewer and summary report generator for incoming DMARC reports.
+ * Copyright (C) 2020 Aleksey Andreev (liuch)
+ *
+ * Available at:
+ * https://github.com/liuch/dmarc-srg
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of  MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * =========================
+ *
+ * This file contains implementation of the class SettingString
+ *
+ * @category API
+ * @package  DmarcSrg
+ * @author   Aleksey Andreev (liuch)
+ * @license  https://www.gnu.org/licenses/gpl-3.0.html GNU/GPLv3
+ */
+
+namespace Liuch\DmarcSrg\Settings;
+
+/**
+ * It's a class for accessing to settings item data
+ *
+ * This class contains the implementation of the setting for string values.
+ */
+class SettingString extends Setting
+{
+    /**
+     * Returns the type of the setting
+     *
+     * @return int Type of the setting
+     */
+    public function type(): int
+    {
+        return Setting::TYPE_STRING;
+    }
+
+    /**
+     * Checks if the value is correct
+     *
+     * @return bool True if the value is correct or false otherwise
+     */
+    protected function checkValue(): bool
+    {
+        return (gettype($this->value) === 'string');
+    }
+
+    /**
+     * Converts a string to the value
+     *
+     * @param string $s String for conversion
+     *
+     * @return void
+     */
+    protected function stringToValue(string $s): void
+    {
+        $this->value = $s;
+    }
+
+    /**
+     * Returns a string representation of the value
+     *
+     * @return string The string value
+     */
+    protected function valueToString(): string
+    {
+        return $this->value;
+    }
+}
+

root/opt/dmarc-srg/classes/Settings/SettingStringSelect.php

@@ -0,0 +1,78 @@
+<?php
+
+/**
+ * dmarc-srg - A php parser, viewer and summary report generator for incoming DMARC reports.
+ * Copyright (C) 2020 Aleksey Andreev (liuch)
+ *
+ * Available at:
+ * https://github.com/liuch/dmarc-srg
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of  MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * =========================
+ *
+ * This file contains implementation of the class SettingStringSelect
+ *
+ * @category API
+ * @package  DmarcSrg
+ * @author   Aleksey Andreev (liuch)
+ * @license  https://www.gnu.org/licenses/gpl-3.0.html GNU/GPLv3
+ */
+
+namespace Liuch\DmarcSrg\Settings;
+
+/**
+ * It's a class for accessing to settings item data
+ *
+ * This class contains the implementation of the setting for string with a limited set of values.
+ */
+class SettingStringSelect extends SettingString
+{
+    /**
+     * Returns the type of the setting
+     *
+     * @return int Type of the setting
+     */
+    public function type(): int
+    {
+        return Setting::TYPE_STRING_SELECT;
+    }
+
+    /**
+     * Checks if the value is correct
+     *
+     * @return bool True if the value is correct or false otherwise
+     */
+    protected function checkValue(): bool
+    {
+        if (parent::checkValue()) {
+            if (in_array($this->value, SettingsList::$schema[$this->name]['options'])) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Returns an array with setting data
+     *
+     * @return array Setting data
+     */
+    public function toArray(): array
+    {
+        $res = parent::toArray();
+        $res['options'] = SettingsList::$schema[$this->name]['options'];
+        return $res;
+    }
+}
+

root/opt/dmarc-srg/classes/Settings/SettingsList.php

@@ -0,0 +1,207 @@
+<?php
+
+/**
+ * dmarc-srg - A php parser, viewer and summary report generator for incoming DMARC reports.
+ * Copyright (C) 2020 Aleksey Andreev (liuch)
+ *
+ * Available at:
+ * https://github.com/liuch/dmarc-srg
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation, either version 3 of the License.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of  MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * =========================
+ *
+ * This file contains the class SettingsList
+ *
+ * @category API
+ * @package  DmarcSrg
+ * @author   Aleksey Andreev (liuch)
+ * @license  https://www.gnu.org/licenses/gpl-3.0.html GNU/GPLv3
+ */
+
+namespace Liuch\DmarcSrg\Settings;
+
+use Liuch\DmarcSrg\Core;
+use Liuch\DmarcSrg\Exception\SoftException;
+
+/**
+ * This class is designed to work with the list of the settings
+ */
+class SettingsList
+{
+    public const ORDER_ASCENT  = 0;
+    public const ORDER_DESCENT = 1;
+
+    private $db    = null;
+    private $order = self::ORDER_ASCENT;
+
+    /**
+     * The constructor
+     *
+     * @param DatabaseController $db Connector to the current database
+     */
+    public function __construct($db = null)
+    {
+        $this->db = $db ?? Core::instance()->database();
+    }
+
+    /**
+     * Returns a list of the settings
+     *
+     * It returns a list of the settings that are marked public.
+     * The value is taken from the database, if any, or the default.
+     *
+     * @return array Array with instances of Setting class
+     */
+    public function getList(): array
+    {
+        $db_map = $this->db->getMapper('setting')->list();
+        foreach (static::$schema as $name => &$sch_data) {
+            if ($sch_data['public'] ?? false) {
+                $value = $db_map[$name] ?? $sch_data['default'];
+                switch ($sch_data['type']) {
+                    case 'select':
+                        $list[] = new SettingStringSelect([
+                            'name'  => $name,
+                            'value' => $value
+                        ], true, $this->db);
+                        break;
+                    case 'integer':
+                        $list[] = new SettingInteger([
+                            'name'  => $name,
+                            'value' => intval($value)
+                        ], true, $this->db);
+                        break;
+                    case 'string':
+                        $list[] = new SettingString([
+                            'name'  => $name,
+                            'value' => $value
+                        ], true, $this->db);
+                        break;
+                }
+            }
+        }
+        unset($sch_data);
+
+        $dir = $this->order == self::ORDER_ASCENT ? 1 : -1;
+        usort($list, static function ($a, $b) use ($dir) {
+            return ($a->name() <=> $b->name()) * $dir;
+        });
+
+        return [
+            'list' => $list,
+            'more' => false
+        ];
+    }
+
+    /**
+     * Sets the sorting direction for the list
+     *
+     * @param int $direction The sorting direction. ORDER_ASCENT or ORDER_DESCENT must be used here.
+     *
+     * @return SettingsList $this
+     */
+    public function setOrder(int $direction)
+    {
+        if ($direction !== self::ORDER_DESCENT) {
+            $direction = self::ORDER_ASCENT;
+        }
+        $this->order = $direction;
+        return $this;
+    }
+
+    /**
+     * Throws an exception if there is no setting with name $name
+     *
+     * @param string $name Setting name to check
+     *
+     * @return void
+     */
+    public static function checkName($name): void
+    {
+        if (!isset(self::$schema[$name])) {
+            throw new SoftException('Unknown setting name: ' . $name);
+        }
+    }
+
+    /**
+     * Returns an instance of the Setting class by its name
+     *
+     * It returns an instance of the Setting class but only if it is marked public.
+     *
+     * @param string $name Setting name
+     *
+     * @return Setting
+     */
+    public static function getSettingByName(string $name)
+    {
+        self::checkName($name);
+        if (!(self::$schema[$name]['public'] ?? false)) {
+            throw new SoftException('Attempt to access an internal variable');
+        }
+
+        switch (self::$schema[$name]['type']) {
+            case 'string':
+                return new SettingString($name);
+            case 'select':
+                return new SettingStringSelect($name);
+            case 'integer':
+                return new SettingInteger($name);
+        }
+    }
+
+    /**
+     * List of the possible setting items that must be returned in getList method, their types and other data
+     */
+    public static $schema = [
+        'version' => [
+            'type'    => 'string',
+            'default' => ''
+        ],
+        'status.emails-for-last-n-days' => [
+            'type'    => 'integer',
+            'public'  => true,
+            'minimum' => 1,
+            'maximum' => 365,
+            'default' => 30
+        ],
+        'report-view.sort-records-by' => [
+            'type'    => 'select',
+            'public'  => true,
+            'options' => [ 'ip,ascent', 'ip,descent', 'message-count,ascent', 'message-count,descent' ],
+            'default' => 'message-count,descent'
+        ],
+        'log-view.sort-list-by' => [
+            'type'    => 'select',
+            'public'  => true,
+            'options' => [ 'event-time,ascent', 'event-time,descent' ],
+            'default' => 'event-time,ascent'
+        ],
+        'ui.datetime.offset' => [
+            'type'    => 'select',
+            'public'  => true,
+            'options' => [ 'auto', 'utc', 'local' ],
+            'default' => 'auto'
+        ],
+        'ui.ipv4.url' => [
+            'type'    => 'string',
+            'public'  => true,
+            'default' => 'https://who.is/whois-ip/ip-address/{$ip}'
+        ],
+        'ui.ipv6.url' => [
+            'type'    => 'string',
+            'public'  => true,
+            'default' => 'https://who.is/whois-ip/ip-address/{$ip}'
+        ]
+    ];
+}