Path.php

<?php


namespace IMATHUZH\Qfq\Core\Helper;

/*
 * Glossar:
 * - App: directory in which the index.php file is located. All urls should be relative to this.
 * - Ext: directory in which the QFQ extension is loacted. e.g. the folder Classes is in there.
 * - API: api folder of qfq extension
 *
 * Naming convention of path constants/functions/variables:
 * 1) name a path by its origin and its destination separated by 'to'. E.g. APP_TO_SYSTEM_LOG, $appToProject.
 * 2) if the destination is a file, append "File". E.g. APP_TO_SYSTEM_QFQ_LOG_FILE.
 * 3) if a path has to be variable, create a setter and getter. E.g. self::setAbsoluteApp(), self::absoluteApp(), private static $absoluteApp.
 * 4) a path getter appends the given arguments to the requested path using self::join(..., func_get_args()). E.g. see absoluteApp().
 * 5) additional path getters may be defined which combine other getters. E.g. see absoluteProject().
 * 6) avoid manually defining new absolute paths. Define paths relative to App then create a getter which joins it with absoluteApp()
 * 7) avoid defining redundant paths in constants. E.g. create appToApi() by combining appToExt() and extToApi() instead of defining APP_TO_API.
 */

use IMATHUZH\Qfq\Core\Exception\Thrower;
use IMATHUZH\Qfq\Core\Store\Config;

class Path
{
    // App
    // This is manually set in self::setMainPaths()
    private static $absoluteApp = null;

    // Extension
    const APP_TO_EXT = 'typo3conf/ext/qfq';

    // API
    const EXT_TO_API = 'Classes/Api';
    const API_TO_APP = '../../../../../'; // TODO: make relatvie to ext instead

    // Javascript
    const EXT_TO_JAVASCRIPT = 'Resources/Public/JavaScript';
    const JAVASCRIPT_TO_EXT = '../../../';

    // Icons
    const EXT_TO_GFX_INFO_FILE = 'Resources/Public/icons/note.gif';
    const EXT_TO_PATH_ICONS = 'Resources/Public/icons';

    // Annotate
    const EXT_TO_HIGHLIGHT_JSON_DIR = 'Resources/Public/Json';  // TODO: refactor: remove DIR at the end of the constant name

    // Twig
    const EXT_TO_TWIG_TEMPLATES = 'Resources/Public/twig_templates';

    // QFQ Project dir
    private static $appToProject = null;
    private const APP_TO_PROJECT_DEFAULT = '../';
    private const APP_TO_FILEADMIN = 'fileadmin';
    private const APP_TO_PROJECT_IN_PROTECTED = 'fileadmin/protected/qfqProject';
    const PROJECT_TO_FORM = 'form';
    const PROJECT_TO_CONF = 'conf';
    const FORM_TO_FORM_BACKUP = '.backup';
    const PROJECT_DIR_TO_REPORT = 'report'; // TODO: refactor: remove DIR from constant name
    const REPORT_FILE_TO_BACKUP = '.backup'; // The path from a directory containing a report file to the directory containing backups of that report file

    // Config
    const APP_TO_TYPO3_CONF = 'typo3conf';

    // Log files
    private static $absoluteLog = null;
    private static $overloadAbsoluteQfqLogFile = null;
    private static $overloadAbsoluteMailLogFile = null;
    private static $overloadAbsoluteSqlLogFile = null;
    private const LOG_TO_QFQ_LOG_FILE_DEFAULT = 'qfq.log';
    private const LOG_TO_MAIL_LOG_FILE_DEFAULT = 'mail.log';
    private const LOG_TO_SQL_LOG_FILE_DEFAULT = 'sql.log';
    private const PROJECT_TO_LOG_DEFAULT = 'log';
    private const APP_TO_LOG_IN_PROTECTED = 'fileadmin/protected/log';

    // Thumbnail
    const APP_TO_SYSTEM_THUMBNAIL_DIR_SECURE_DEFAULT = 'fileadmin/protected/qfqThumbnail';
    const APP_TO_SYSTEM_THUMBNAIL_DIR_PUBLIC_DEFAULT = 'typo3temp/qfqThumbnail';
    const APP_TO_THUMBNAIL_UNKNOWN_TYPE = 'typo3/sysext/frontend/Resources/Public/Icons/FileIcons/';

    // Send Email
    const EXT_TO_SEND_EMAIL_FILE = 'Classes/External/sendEmail';

    /**
     * Manually set the paths which are not constant nor can be inferred by other paths.
     * This function must be called at the beginning of every entry point, to tell the Path class, where things are.
     *
     * @param string|null $absoluteApp
     * @throws \CodeException
     * @throws \UserFormException
     */
    public static function setMainPaths(string $absoluteApp = null)
    {
        if (is_null($absoluteApp)) {
            $absoluteApp = self::findAbsoluteApp();
        }
        self::setAbsoluteApp($absoluteApp);

        // Only executed on first call:
        self::findAppToProject();
        self::findAbsoluteLog();
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteApp(...$pathPartsToAppend): string
    {
        self::enforcePathIsSet(self::$absoluteApp);
        return self::join(self::$absoluteApp, $pathPartsToAppend);
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteExt(...$pathPartsToAppend): string
    {
        return self::absoluteApp(self::appToExt(), $pathPartsToAppend);
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteLog(...$pathPartsToAppend): string
    {
        if (is_null(self::$absoluteLog)) {
            self::findAbsoluteLog();
        }
        self::enforcePathIsSet(self::$absoluteLog);
        return self::join(self::$absoluteLog, $pathPartsToAppend);
    }

    /**
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteSqlLogFile(): string
    {
        if (is_null(self::$overloadAbsoluteSqlLogFile)) {
            return self::absoluteLog(self::LOG_TO_SQL_LOG_FILE_DEFAULT);
        }
        return self::$overloadAbsoluteSqlLogFile;
    }

    /**
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteQfqLogFile(): string
    {
        if (is_null(self::$overloadAbsoluteQfqLogFile)) {
            return self::absoluteLog(self::LOG_TO_QFQ_LOG_FILE_DEFAULT);
        }
        return self::$overloadAbsoluteQfqLogFile;
    }

    /**
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteMailLogFile(): string
    {
        if (is_null(self::$overloadAbsoluteMailLogFile)) {
            return self::absoluteLog(self::LOG_TO_MAIL_LOG_FILE_DEFAULT);
        }
        return self::$overloadAbsoluteMailLogFile;
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function appToProject(...$pathPartsToAppend): string
    {
        self::enforcePathIsSet(self::$appToProject);
        return self::join(self::$appToProject, $pathPartsToAppend);
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteProject(...$pathPartsToAppend): string
    {
        return self::absoluteApp(self::appToProject($pathPartsToAppend));
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function absoluteConf(...$pathPartsToAppend): string
    {
        return self::absoluteProject(self::PROJECT_TO_CONF, $pathPartsToAppend);
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function appToExt(...$pathPartsToAppend): string
    {
        return self::join(self::APP_TO_EXT, $pathPartsToAppend);
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function extToApi(...$pathPartsToAppend): string
    {
        return self::join(self::EXT_TO_API, $pathPartsToAppend);
    }

    /**
     * @param array $pathPartsToAppend
     * @return string
     * @throws \UserFormException
     */
    public static function appToApi(...$pathPartsToAppend): string
    {
        return self::join(self::APP_TO_EXT, self::EXT_TO_API, $pathPartsToAppend);
    }

    /**
     * @param string $newPath
     * @throws \UserFormException
     */
    public static function setAbsoluteSqlLogFile(string $newPath)
    {
        self::enforcePathIsAbsolute($newPath);
        self::$overloadAbsoluteSqlLogFile = $newPath;
    }

    /**
     * @param string $newPath
     * @throws \UserFormException
     */
    public static function setAbsoluteQfqLogFile(string $newPath)
    {
        self::enforcePathIsAbsolute($newPath);
        self::$overloadAbsoluteQfqLogFile = $newPath;
    }

    /**
     * @param string $newPath
     * @throws \UserFormException
     */
    public static function setAbsoluteMailLogFile(string $newPath)
    {
        self::enforcePathIsAbsolute($newPath);
        self::$overloadAbsoluteMailLogFile = $newPath;
    }

    /**
     * Override the paths of sql.log, qfq.log, mail.log using the values from the config file or Typo3.
     *
     * @throws \CodeException
     * @throws \UserFormException
     * @throws \UserReportException
     */
    public static function overrideLogPathsFromConfig()
    {
        // QFQ log
        $absoluteQfqLogFile = Config::get(SYSTEM_QFQ_LOG_PATHFILENAME);
        if (!empty($absoluteQfqLogFile)) {
            self::setAbsoluteQfqLogFile(self::joinIfNotAbsolute(self::absoluteApp(), $absoluteQfqLogFile));
        }

        // Mail log
        $absoluteMailLogFile = Config::get(SYSTEM_MAIL_LOG_PATHFILENAME);
        if (!empty($absoluteMailLogFile)) {
            self::setAbsoluteMailLogFile(self::joinIfNotAbsolute(self::absoluteApp(), $absoluteMailLogFile));
        }

        // SQL log
        $absoluteSqlLogFile = Config::get(SYSTEM_SQL_LOG_PATHFILENAME);
        if (!empty($absoluteSqlLogFile)) {
            self::setAbsoluteSqlLogFile(self::joinIfNotAbsolute(self::absoluteApp(), $absoluteSqlLogFile));
        }
    }

    /**
     * Return the second path if it is absolute. Otherwise concatenate and return the two paths.
     *
     * @param string $path1
     * @param string $path2
     * @return string
     * @throws \UserFormException
     */
    public static function joinIfNotAbsolute (string $path1, string $path2): string
    {
        if ($path2 !== '' && $path2[0] === '/') {
            return $path2;
        }
        return self::join($path1, $path2);
    }

    /**
     * Join the arguments together as a path. Array arguments are flattened!
     * Trailing path parts may not start with '/'.
     *
     * join(['this', 'is'], 'my/wonderful', [['path/of', 'nice'], 'things']) === 'this/is/my/wonderful/path/of/nice/things'
     *
     * @param array $pathPartsToAppend
     * @return string
     */
    public static function join(...$pathPartsToAppend): string
    {
        $parts = $pathPartsToAppend;

        // concatenate all parts (arrays are flattened)
        $path = '';
        array_walk_recursive($parts, function ($part) use (&$path) {

            // filter out empty string and null arguments
            if (is_null($part) || $part === '') {
                return;
            }

            // first part added without '/'
            if ($path === '') {
                $path .= $part;
            } else {

                // trailing path parts may not be absolute
                if ($part[0] === '/') {
                    throw new \UserFormException(json_encode([
                        ERROR_MESSAGE_TO_USER => 'Failed: Join path.',
                        ERROR_MESSAGE_TO_DEVELOPER => "Trailing path parts may not start with '/'. Trailing part: '$part'."]),
                        ERROR_PATH_INVALID);
                }

                $path .= '/' . $part;
            }
        });

        // remove multiple occurrences of '/'
        return preg_replace('/\/{2,}/','/', $path);
    }

    ///////////////////////////////////////////////////  Private  //////////////////////////////////////////////////////

    /**
     * @param string $newPath
     */
    private static function setAbsoluteApp(string $newPath)
    {
        self::$absoluteApp = $newPath;
    }

    /**
     * @param string $newPath
     */
    private static function setAppToProject(string $newPath)
    {
        self::$appToProject = $newPath;
    }

    /**
     * @param string $newPath
     * @return string
     */
    private static function setAbsoluteLog(string $newPath)
    {
        self::$absoluteLog = $newPath;
    }

    /**
     * Searches these places for log directory:
     *   1) project-directory/log
     *   2) fileadmin/protected/log
     * If not found create log dir in: project-directory/log
     *
     * @throws \UserFormException
     */
    private static function findAbsoluteLog()
    {
        if (!is_null(self::$absoluteLog)) {
            // only execute once
            return;
        }

        // search log dir qfqProject/log
        $absoluteLog = self::absoluteApp(self::appToProject(self::PROJECT_TO_LOG_DEFAULT));
        if (file_exists($absoluteLog)) {
            self::setAbsoluteLog($absoluteLog);

        // search log dir fileadmin/protected/log
        } elseif (file_exists(self::absoluteApp(self::APP_TO_LOG_IN_PROTECTED))) {
            self::setAbsoluteLog(self::absoluteApp(self::APP_TO_LOG_IN_PROTECTED));

        // create default log dir qfqProject/log
        } else {
            HelperFile::createPathRecursive($absoluteLog);
            self::setAbsoluteLog($absoluteLog);
        }
    }

    /**
     * Read the project location from qfq.project.path.php or create the file with default path.
     *
     * @throws \CodeException
     * @throws \UserFormException
     */
    private static function findAppToProject()
    {
        if (!is_null(self::$appToProject)) {
            // only execute once
            return;
        }

        // does qfq.project.path.php exist? => read path
        $absoluteProjectPathFile = self::absoluteApp(PROJECT_PATH_PHP_FILE);
        if (HelperFile::isReadableException($absoluteProjectPathFile)) {
            self::setAppToProject(HelperFile::include($absoluteProjectPathFile));

        // does the deprecated config.qfq.php exist? => fileadmin/protected/qfqProject & migrate to qfq.json
        } elseif (HelperFile::isReadableException(self::absoluteApp(self::APP_TO_TYPO3_CONF, CONFIG_QFQ_PHP))) {
            HelperFile::createPathRecursive(self::absoluteApp(self::APP_TO_PROJECT_IN_PROTECTED));
            self::setAppToProject(self::APP_TO_PROJECT_IN_PROTECTED);
            Config::migrateConfigPhpToJson();
            self::writeProjectPathPhp();

        // does fileadmin exist? => fileadmin/protected/qfqProject
        } elseif (file_exists(self::absoluteApp(self::APP_TO_FILEADMIN))) {
            HelperFile::createPathRecursive(self::absoluteApp(self::APP_TO_PROJECT_IN_PROTECTED));
            self::setAppToProject(self::APP_TO_PROJECT_IN_PROTECTED);
            self::writeProjectPathPhp();

        // else => folder above APP
        } else {
            self::setAppToProject(self::APP_TO_PROJECT_DEFAULT);
            self::writeProjectPathPhp();
        }
    }

    /**
     * Find the absolute path of the App directory using the path of this file.
     * Fails if typo3conf is not found in that path.
     *
     * @throws \UserFormException
     */
    private static function findAbsoluteApp()
    {
        $absoluteApp = self::realpath(self::join(__DIR__, '../../../../../../'));
        if (!file_exists(self::join($absoluteApp, self::APP_TO_TYPO3_CONF)))
        {
            Thrower::userFormException('App path seems to be wrong: Directory "typo3conf" not found in app path.'
                , "Current app path: $absoluteApp");
        }

        return $absoluteApp;
    }

    /**
     * Write the project path configuration file to the project directory.
     *
     * @throws \UserFormException
     */
    private static function writeProjectPathPhp()
    {
        $appToProject = self::appToProject();
        $fileContent = <<<EOF
<?php

/**
QFQ project path configuration
!! ATTENTION !!: The files in the project directory should NOT be served by your http server! 
Only exception: The app directory inside the project directory may be served.
*/

return '$appToProject'; // path relative to app directory (i.e. location of this file).
EOF;
        HelperFile::file_put_contents(self::absoluteApp(PROJECT_PATH_PHP_FILE), $fileContent);
    }

    /**
     * Throw an exception if the given path is not set (i.e. === null).
     *
     * @param $path
     * @throws \UserFormException
     */
    private static function enforcePathIsSet($path) {
        if(is_null($path)) {
            Thrower::userFormException('Path accessed before set.', 'Make sure Path::setMainPaths(...) is called before this code is executed..');
        }
    }

    /**
     * Throw exception if path does not start with '/'
     *
     * @param $path
     * @throws \UserFormException
     */
    private static function enforcePathIsAbsolute(string $path) {
        if($path !== '' && $path[0] === '/') {
            return;
        }
        Thrower::userFormException('Path is not absolute', "Path does not start with '/' : $path");
    }

    /**
     * PHP System function: realpath() with QFQ exception.
     * The first argument must be a path to something that exists. Otherwise an exception is thrown!
     *
     * @param string $pathToSomethingThatExists This file/dir MUST exist! Otherwise exception!
     * @param array $pathPartsToAppend The appended path doesnt have to exist.
     * @return string
     * @throws \UserFormException
     */
    private static function realpath(string $pathToSomethingThatExists, ...$pathPartsToAppend): string
    {
        $absolutePath = realpath($pathToSomethingThatExists);
        if ($absolutePath === false) {
            Thrower::userFormException('Path not found.', "Either path does not exist or access not permitted. Make sure the whole path is executable by the current user. Path: $pathToSomethingThatExists.");
        }
        return self::join($absolutePath, $pathPartsToAppend);
    }
}