----------------------------------------------------------------------------------------------------------------------------------------------------------------
COPYRIGHT INFORMATION ...
HRConvert2, Copyright on 3/12/2024 by Justin Grimes, www.github.com/zelon88

LICENSE INFORMATION ...
This project is protected by the GNU GPLv3 Open-Source license.
https://www.gnu.org/licenses/gpl-3.0.html

APPLICATION INFORMATION ...
This application is designed to provide a web-interface for converting file formats on a server for users of any web browser without authentication. 

FILE INFORMATION ...
v3.3.3.
This plain text file describes the process for creating, formatting, and installing additional GUIs into HRConvert2.

HARDWARE REQUIREMENTS ... 
This application requires at least a Raspberry Pi Model B+ or greater. 
This application will run on just about any x86 or x64 computer.

DEPENDENCY REQUIREMENTS ... 
This application requires Debian Linux (w/3rd Party audio license), Apache 2.4, PHP 8+, LibreOffice, Unoconv, ClamAV, Tesseract, Rar, Unrar, Unzip, 7zipper, 
Ffmpeg, PdfToText, Dia, PopplerUtils, MeshLab, Mkisofs & ImageMagick.

ADDITIONAL INFORMATION
HRConvert2 has one default GUI set in config.php and additional GUIs can be installed by administrators and selected by the user at runtime.
The default GUI used by HRConvrt2 can be selected by adjusting the --Default GUI-- section of config.php.
Administrators can prevent user GUI selection by adjusting the --Allow User Selectable GUI-- section of config.php.
If --Allow User Selectable GUI-- is set to TRUE in config.php, users can adjust GUI output using a 'gui' GET request.
To send a GET request, append the following string to the end of the HRConvert2 URL (without quotes):  '?gui=<GUI_CODE>'
Substitute <GUI_CODE> in the string above for the name of the GUI defined by the name of the folder where it's files are contained.
If a user submits an unsupported GUI the default will be used instead.
It a supported GUI is missing required files a fatal error will occur.

<3 Open-Source
----------------------------------------------------------------------------------------------------------------------------------------------------------------



----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About GUIs--

The HRConvert2 GUI is modular and separate from the core logic of the application. 
This design makes modifying the look and feel of HRConvert2 easy.
This document will teach administrator and developers how GUIs are handled and structured.
In this document when we refer to a GUI, we refer to a set of files required to render HRConvert2.
In this document when we refer to a language pack, we refer to the files required to localize a GUI into a specific language.

An HRConvert2 GUI is made up of 7 components. Each component serves a specific function. The 7 components of a GUI are;

  1. header.php
  2. convertGui1.php
  3. convertGui2.php
  4. footer.php
  5. styleCore.php
  6. index.html
  7. A 'Languages' folder with at least one ISO 639-1 supported Language Pack.

These components are stored in a folder named after the ISO 639-1 language code for the language.
The ISO-639-1 named folder is then placed inside the 'Languages' subdirectory of the installation location.
The supported ISO 639-1 language code must also be added to the --Supported Languages-- section of config.php or it will be ignored.
If --Allow User Selectable Language-- is enabled, users will be able to select this language pack by sendiing a GET request.
Users should not access the GUI directly. All requests should be directed to convertCore.php which will construct the GUI on-demand.

During operation, HRConvert2 initializes the language using the following process;

  1. Initialize the language to english.
  2. Build an array of languages that are included with HRConvert2.
  3. Check if the $SupportedLanguages variable from config.php is set properly.
    3a. If not, use the included array of default languages instead.
  4. If a language was specified via GET input, sanitize it.
  5. Check if the $DefaultLanguage variable from config.php is set & supported.
    5a. If not, use english instead.
  6. Check if the $AllowUserSelectableLanguage variable from config.php is set.
    6a. If not, use $DefaultLanguage instead.
  7. Check if a language was specified via GET input.
    7a. If not, use $DefaultLanguage instead.
  8. Check if the specified language is supported.
    8a. If not, use $DefaultLanguage instead.
  9. If all checks have passed and the specified language is supported, set the language to use to the one specified via GET request.
  10. Reset the language GET variable to the currently specified language so future requests will continue using the same language.
  11. Define all required language related files & folders.
  12. Check for the existence of all required language related files & folders.
    12a. If not, terminate the application.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Administration Tips--

Language Packs are contained within GUIs. GUIs typically contain multiple language packs.
Errors will occur if an installed GUI does not support every language listed in the --Supported Languages-- section of the config.php file.
Errors will occur if an installed GUI does not support the following colors: Red, Green, Blue, Grey.
Server administrators can; 
  Enable or disable GUIs by modifying the --Supported GUIs-- section of the config.php file.
  Add or remove language packs to a GUI by creating a folder in the 'Languages' subdirectory of each enabled GUI folder.
  Allow or prevent GUI selection via GET request by modifying the --Allow User Selectable GUIs-- section of the config.php file.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Development Tips--

The modular design of HRConvert2 is designed to make adding new GUIs and/or languages simple for administrators to manage and easy for developers to maintain.
If you are maintaining a branch of HRConvert2 and are focusing on a single language pack you can build your logic directly into the GUI pages themselves.
Any GUI files that are not needed can be left blank after the opening PHP tag.
To create a new GUI, copy & paste an existing GUI from the UI folder and modify the files with your favorite text editor.
To install a new GUI, place a folder in the 'UI' subdirectory of the installation location.
To enable or disable a GUI, update the --Supported GUIs-- section of the config.php file.
GUIs can utilize the icons and scripts in the default Resources directory or include their own.
If any non-stock directories are added to HRConvert2, a copy of index.html must be pasted into the directory.
Do not create any files named index.html. This filename is reserved by the application for document root protection mechanisms.
Upper Case variables are Global in scope. Lower case variables are severely limited in scope. 
Limited scope variables should be manually nulled & unset after they are no longer required.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--Maintenance Tips--

The 'Languages\<LANGUAGE_CODE>\languageStrings.php' file should be used to contain all localization specific code.
By placing localization specific code into 'Languages\<LANGUAGE_CODE>\languageStrings.php', GUI updates can be easily applied from one language pack to another.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About header.php--

This file contains the start of the GUI including the stylesheets, html, & head tags. 
This file is always displayed.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run at the beginning of every page that HRConvert2 renders.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About convertGui1.php--

This file contains the upload field as well as some information about the application.
This file provides tokens to the user which must be included with any subsequent request by the user.
This file is displayed when no valid tokens have been supplied by the user.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run before the user has uploaded any files.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About convertGui2.php--

This file contains the available options for each submitted file.
This file dynamically selects which options to display for which files.
This file is displayed when valid tokens were supplied by the user.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run after the user has uploaded files.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About footer.php--

This file contains the end of the GUI including the Terms of Service & Privacy Policy links, when enabled.
This file is always displayed.
Localized text for this file is contained in the 'Languages\<LANGUAGE_CODE>\languageStrings.php' file of the language pack.
Insert code here that should run at the end of every page that HRConvert2 renders.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About index.html--

This file serves to act as reliable and predictable document root protection for the server.
If users are allowed to view the document root of the server they could navigate manually to other users hosted scratch space.
This would allow users to see some temporary files of other users while they were in the process of working on them.
This file simply redirects the user to the main HRConvert2 landing page with a message asking them to wait.
The visual effect of the loading text is that a malicious actor knows they have hit some protection mechanism.
If you want to modify the global index.html file, modify the one in the installation location and then copy & paste to all other subdirectories.
HRConvert2 will automatically create new index.html files in folders it creates using the one from the installation location as a template.
This file must be manually copied & pasted into any folders that are manually created by administrators or developers of HRConvert2.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About 'Languages' Folder--

The 'Languages' folder must exist in each GUI.
The 'Languages' folder contains the major language-specific files for the GUI.
Each subdirectory of the 'Languages' folder represents a different language pack.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About 'Resources' Folder--

The 'Resources' folder is optional, but it makes the life of the HRConvert2 developer much easier.
The 'Resources' folder contains & organizes the scripts, stylesheets, & images required by the GUI.
The HRConvert2 core will not check for the existence of the 'Resources' folder.
The HRConvert2 core will define the following variables which map to subdirectories of the 'Resources' folder;
  $GuiResourcesDir, Maps to 'Resources/' folder.
  $GuiImageDir, Maps to 'Resources/Images' folder.
  $GuiCSSDir, Maps to 'Resources/CSS' folder.
  $GuiJSDir, Maps to 'Resources/JS' folder.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Variable Scope--

This GUI only has access to certain variables. Variables that are available to the GUI include;
  $GuiFiles, $LanguageFiles, $LanguageStringsFile, $GuiHeaderFile, $GuiFooterFile, $GuiUI1File, $GuiUI2File, $CoreLoaded, $ConvertDir, $ConvertTempDir, 
  $Token1, $Token2, $SesHash, $SesHash2, $SesHash3, $SesHash4, $Date, $Time, $TOSURL, $PPURL, $ShowFinePrint, $PDFWorkArr, $ArchiveArray, $DearchiveArray, 
  $DocumentArray, $SpreadsheetArray, $ImageArray, $ModelArray, $DrawingArray, $VideoArray, $SubtitleArray, $StreamArray, $MediaArray, $PresentationArray, 
  $ConvertGuiCounter1, $ConsolidatedLogFileName, $Alert, $Alert1, $Alert2, $Alert3, $FCPlural, $FCPlural1, $FCPlural2, $FCPlural3, $File, $Files, $FileCount, 
  $SpinnerStyle, $SpinnerColor, $PacmanLoc, $Allowed, $AllowUserVirusScan, $AllowUserShare, $SupportedConversionTypes, $FullURL, $LanguageDir, $FaviconPath, 
  $DropzonePath, $DropzoneStylesheetPath, $StylesheetPath, $JsLibraryPath, $JqueryPath, $GUIDirection, $SupportedFormatCount, $GUIAlignment, $HeaderDisplayed, 
  $UIDisplayed, $FooterDisplayed, $LanguageStringsLoaded, $GUIDisplayed, $GuiResourcesDir, $GuiImageDir, $GuiCSSDir, $GuiJSDir
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Colors--

The GUI gets color specific styles from the $ButtonCode variable.
The $ButtonCode variable contains the color specific CSS for the GUI.
The $ButtonCode variable is set by the UI/<SELECTED_GUI>/styleCore.php file.
There are 4 supported colors, and the code for each color is contained in styleCore.php.
The loading spinner will change color as well. There is one spinner .gif file for each style & supported color.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Loading Spinners--

There are 6 loading spinners to choose from that can be set in config.php.
Each spinner is available in 4 colors.
The color of the spinner can be adjusted separately from the color of the rest of the GUI.
The $PacmanLoc variable contains the relative path to use for the selected spinner.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Uploaded Files--

The $Files variable contains an array of all valid uploaded filenames that exist in the users scratch space.
The GUI must iterate through this array, determine what format it is, & display the correct options.
When submitting a file as input, only submit it's name with extension. HRConver2 will determine the path.
When redirecting the user to a download you must send them to the proper filename and hosted file path.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About File Sharing Operations--

File sharing can be implemented entirely client-side by submitting a 'download' POST request which returns a URL that can be copied to the users clipboard.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About The API--

HRConvert2 supports inputs through POST and GET requests.
All requests should be submitted to convertCore.php & all POST requests must be encoded as "multipart/form-data".
If Token1 and Token2 are not submitted via POST input, then convertGui1.php will be displayed prompting for file uploads.
If Token1 and Token2 are both submitted via POST input, then convertGui2.php will be displayed providing conversion options.
The included GUIs makes extensive use of JQuery + Ajax to submit requests & process responses.
GUI files cannot handle API requests and will generate an error if they receive API requests.
All API inputs are sanitized by the core for special characters to prevent malicious or unintentional code injection.
As a result of sanitization the filename may change after upload.

To use HRConvert2 via POST & GET requests only;
  1. Submit a blank GET request to convertCore.php to retrieve the value of Token1 and Token2.
  2. Submit a file upload along with Token1 and Token2 to convertCore.php via POST input.
  3. Submit an uploaded filename, a new filename, a file extension, Token1, Token2, and a valid set of conversion options to convertCore.php via POST input.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About User Supplied GET Requests--

The following is a list of supported GET inputs with description & supported values for each;

  noGui
      GUI Operation
      Display the minimal amount of GUI elements to accomplish the mission.
      Set this input to any value to trigger the UI to display the least amount of elements that is possible.
      This input can also be specified by POST request, but GET will always take precedence.

  gui
      GUI Operation
      Select the GUI to use.
      Can be enabled/disabled in config.php.
      Supported GUI's can be added/removed in config.php.
      Set this input to the name of a UI that is installed to the UI folder & defined in config.php.
      This input can also be specified by POST request, but GET will always take precedence.

  language
      GUI Operation
      Select the language to use.
      Can be enabled/disabled in config.php to.
      Supported languages can be added/removed in config.php.
      Set this input to the nane of an installed ISO 639-1 language defined in config.php.
      This input can also be specified by POST request, but GET will always take precedence.
  
  color
      GUI Operation
      Select the color to use.
      Can be enabled/disabled in config.php to.
      Supported colors can be added/removed in config.php.
      Set this input to a supported color scheme defined in config.php.
      This input can also be specified by POST request, but GET will always take precedence.
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About User Supplied POST Requests--

The following is a list of supported POST inputs, organized into sections based on when they are used, with description & supported values for each;

  General Use
      Token1
          String.
          This input is used whenever a user intends to use HRConvert2.
          This input is provided to the user by HRConvert2 via a hidden form field.
          This value must be stored & resubmitted with every subsequent request that is part of the same session.
          Set this input to the value of the hidden form field from convertGui1.php that has an 'id' of 'Token1'.
      Token2
          String.
          This input is used whenever a user intends to use HRConvert2.
          This input is provided to the user by HRConvert2 via a hidden form field.
          This value must be stored & resubmitted with every subsequent request that is part of the same session.
          Set this input to the value of the hidden form field from convertGui1.php that has an 'id' of 'Token2'.

  General File Operations
      download
          String or JSON Array.
          This input is used at any time to download user files.
          This input is used to generate file URLs for sharing operations.
          Set this input to a name or list of names to use for input files.
      filesToDelete
          String or JSON Array.
          This input is used at any time to delete user files.
          Set this input to a name or list of names to use for input files.

  File Conversion Operations
      convertSelected
          String or JSON Array.
          This input is used during File Conversions (excluding OCR & bulk archiving)
          Set this input to a name or list of names to use for input files.
      extension
          String.
          This input is used during File Conversions (excluding OCR & bulk archiving)
          Set this input to an extension to use for the output file.
      userconvertfilename
          String.
          This input is used during File Conversions (excluding OCR & bulk archiving)
          Set this input to a name to use for the output file.

  Image Conversions
      height
          Integer.
          This input is used during Image Conversions.
          Image height in number of pixels to use for the output file.
          Set this input to 0 to not resize the original image.
      width
          Integer.
          This input is used during Image Conversions.
          Image width in number of pixels to use for the output file.
          Set this input to 0 to not resize the original image.
      rotate 
          Integer.
          This input is used during Image Conversions.
          Number of degrees to rotate the image clockwise.
          Set this input to 0 to not rotate the original image.

  Audio Conversions
      bitrate
          Integer.
          This input is used during Audio Conversions.
          Bitrate to use for the output file.
          Set this input to 0 to use automatic bitrate detection.

  Archive Operations
      archive
          String.
          This input is used during Archive Operations (excluding conversions).
          Set this input to any value to trigger archive operations.
      userfilename
          String.
          This input is used during Archive Operations (excluding conversions).
          Set this input to the name to use for the output file.
      archExtension
          String.
          This input is used during Archive Operations (excluding conversions).
          Set this input to an extension to use for the output file.
      filesToArchive
          String or JSON Array.
          This input is used during Archive Operations (excluding conversions).
          Set this input to a name or list of names to use for input files.

  Optical Character Recognition (OCR) Operations
      pdfworkSelected
          String or JSON Array.
          This input is used during OCR Operations.
          Set this input to a name or list of names to use for input files.
      userpdfconvertfilename
          String.
          This input is used during OCR Operations.
          Set this input to a name to use for the output file.
      pdfextension
          String.
          This input is used during OCR Operations.
          Set this input to an extension to use for the output file.
      method
          Integer, 0 or 1.
          This input is used during OCR Operations.
          This input determines the internal method to use for performing the conversion.
          Set this input to 0 to use a simple approach to OCR.
          Set this input to 1 to use a more advanced approach to OCR.

  Virus Scanning Operations
      scantype
          String (clamav or scancore or all).
          This input is used during Virus Scanning Operations to scan a specific file.
          Set this input to 'clamav' to perform a virus scan with ClamAV Virus Scanner.
          Set this input to 'scancore' to perform a virus scan with ScanCore Virus Scanner.
          Set this input to 'all' to perform a virus scan with all installed Virus Scanners.
      filestoscan
          String or JSON Array.
          This input is used during Virus Scanning Operations.
          Set this input to a name or list of names to use for input files.
      clamScanButton
          String.
          This input is used during Virus Scanning Operations to scan all files with ClamAV.
          Set this input to any value to trigger virus scanning operations.
      scancorebutton
          String.
          This input is used during Virus Scanning Operations to scan all files with ScanCore.
          Set this input to any value to trigger virus scanning operations.
      scanallbutton
          String.
          This input is used during Virus Scanning Operations to scan all files with all installed virus scanners.
          Set this input to any value to trigger virus scanning operations. 
----------------------------------------------------------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------------------------------------------------------------
--About Open Source--

This application is open-source under the terms of the GPLv3 license, meaning anybody can obtain a copy and put it to use for personal or business use.
If you modify this application and use it to make money or offer it to your users as a product, you MUST make the source code with your changes available.
The ideal way to do this would be to fork the official zelon88/HRConvert2 repository on Github and make changes there.
Alternatively you can submit a pull request and have your changes added to the official repository (with credit due to you, of course).
By reciprocating changes & improvements with one another we can all enjoy the best, most capable and bug free version HRConvert2.
If you modify this codebase please consider making your changes public so everyone can benefit from them. 
----------------------------------------------------------------------------------------------------------------------------------------------------------------