Version bump to 1.0.8 - Apply hotfixes

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Fluency for ProcessWire Changelog
 
-## 1.0.8 DEVELOPMENT
+## 1.0.8 2024-24-03
 
 ### New features, Bugfixes, Documentation, Code Improvement, Recommended for all users
 
@@ -23,7 +23,8 @@ Existing content will not be affected.
   it was available
 - Uninstalling the module now deletes the Fluency admin page
 - Fluency config values are now stored as JSON rather than serialized objects which in some
-  instances was causing issues on some servers with ModSecurity and false positives
+  instances was causing issues on some servers with ModSecurity and false positives. Credit to
+  @update-switzerland for finding and reporting.
 - Add fromJson method to FluencyDTO parent class to better handle Data Transfer Object instantiation
   where data may come from storage as JSON
 - Translation cache is now enabled by default as described in the README.md file

Fluency.module.php

@@ -1291,6 +1291,8 @@ public function ___upgrade($fromVersion, $toVersion) {
     }
 
     if (version_compare($fromVersion, '108', '<=')) {
+      // Necessary since changing how Fluency stores data
+      (new FluencyConfig())->resetEngineData();
       $upgradeMessages[] = "Translation engine must be reconfigured after upgrading to Fluency 1.0.8";
     }
 

FluencyConfig.php

@@ -149,15 +149,15 @@ private function saveModuleConfig(...$newConfigData): void {
    * @return object Config as an object
    */
   private function getModuleConfig(): object {
-    return (object) [...$this->getDefaults(), ...$this->modules->getModuleConfigData('Fluency')];
+    return (object) [...$this->getDefaults(), ...$this->modules->getConfig('Fluency')];
   }
 
   /**
    * Resets all configured engine data by removing the selected engine and it's associated settings
-   * @return [type] [description]
+   * This may be required when upgrading the module
    */
   public function resetEngineData(): void {
-
+    $this->saveModuleConfig(translation_api_ready: false, selected_engine: null);
   }
 
   /**

README.md

@@ -16,6 +16,7 @@ You can help out by filing Github issues when bugs are found, or submit a pull r
 
 - [Requirements](#requirements)
 - [Installing](#installing)
+  - [Configuring](#configuring)
   - [Translation Engines](#translation-engines)
   - [Localizing Fluency](#localizing-fluency)
   - [Upgrading or Removing](#upgrading-or-removing)
@@ -39,6 +40,7 @@ You can help out by filing Github issues when bugs are found, or submit a pull r
   - [Translation Engine Information](#translation-engine-information)
   - [Managing Cache](#managing-cache)
   - [Admin REST API Endpoints](#admin-rest-api-endpoints)
+- [Error Handling and Logging](#error-handling-and-logging)
 - [Known Issues](#known-issues)
 - [Contributing](#contributing)
 - [Cost](#cost)
@@ -58,11 +60,22 @@ You can help out by filing Github issues when bugs are found, or submit a pull r
 
 ## Installing
 
-1. Download and unzip the contents into /site/modules and install, or install from the [ProcessWire Modules directory](https://processwire.com/modules/fluency/).
-2. Open the module configuration page, choose a Translation Engine, save
-3. Complete the Translation Engine setup, save
-4. Create language associations, save
-5. Assign the `fluency-translate` permission where appropriate
+You can install Fluency by adding the module to your ProcessWire project using any of the three following methods.
+
+**Method 1**: Within ProcessWire using 'Add Module From Directory' and the class name `Fluency`
+
+**Method 2**: Via Composer with `composer require firewire/fluency`
+
+**Method 3**: Download from this repository or the [Modules directory](https://processwire.com/modules/fluency/) and unzip the contents into `/site/modules/`
+
+After adding the module, install in ProcessWire.
+
+## Configuring
+
+1. Open the module configuration page, choose a Translation Engine, save
+2. Complete the Translation Engine setup, save
+3. Create language associations, save
+4. Assign the `fluency-translate` permission where appropriate
 
 That's it. All multi-language fields will now feature click to translate buttons and a translator tool available in the Admin menu bar. There is no limit on how many languages may be configured, and new languages can be added at any time.
 
@@ -219,7 +232,7 @@ Output:
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title><?= $page->title; ?></title>
+    <title>Your Awesome Website</title>
     <link rel="alternate" hreflang="https://awesomewebsite.com/" href="x-default" />
     <link rel="alternate" hreflang="https://awesomewebsite.com/" href="en-us" />
     <link rel="alternate" hreflang="https://awesomewebsite.com/fr/" href="fr" />
@@ -232,7 +245,7 @@ Output:
 
 #### Switch Page Language Select Element
 
-You can easily render a `<select>` element that will allow a user to choose the langauge that they are currently viewing the page in. By default, Fluency will also render inline JavaScript that will navigate to the page in the language selected but this can be disabled should you want to control that behavior yourself. All text/labels/values will render in the current language if translated.
+You can easily render a `<select>` element that will allow a user to choose the langauge that they are currently viewing the page in. By default, Fluency will also render inline JavaScript that will navigate to the page in the language selected but this can be disabled should you want to control that behavior yourself. All text/labels/values will render in the current language if translated and as configured in ProcessWire.
 
 ```html
 <div class="language-select"><?= $fluency->renderLanguageSelect() ?></div>
@@ -374,6 +387,11 @@ $translation = $fluency->translate(
   caching: true                                 // Default is true, false disables, overrides module config
 ); // => EngineTranslationData
 
+// Results may be accessed via properties on the return object, see toArray() example below for all
+// properties present in the EngineTranslationData object
+$translation->translations; // => ['Wie geht es Ihnen, liebe Entwickler?']
+$translation->fromCache;    // => true
+
 // $translation->toArray(); Outputs the following:
 //
 // array(10) {
@@ -741,6 +759,15 @@ $endpoints = $fluency->getApiEndpoints(); // => stdClass
 // }
 ```
 
+## Error Handling and Logging
+
+Fluency handles errors encountered when communicating with the translation API and errors experienced in ProcessWire. All Data Transfer Objects contain `error` and `message` properties.
+
+`error` - Will contain an error type string defined as class constants in in `app/FluencyErrors.php`
+`message` - Will contain a human-friendly message for the error type that occurred. These are located in `app/FluencyLocalization.php` and can be translated
+
+Translation Engine and third party service errors are stored under the `fluency-engine` log. If there are issues with translating content, refer to that log first to check whether the translation service is experiencing issues.
+
 ## Known Issues
 
 - The browser plugin for Grammarly may conflict with Fluency and is a known issue for many web apps. If you encounter issues, the solution is to either disable Grammarly while using Fluency in the ProcessWire admin, or log into the admin in a private browser window where Grammarly may not be running. Instructions provided by Grammarly [here](https://support.grammarly.com/hc/en-us/articles/115000091612-Turn-off-Grammarly-on-one-or-more-websites).

app/Functions/fluencyEngineConfigNames.php

@@ -59,9 +59,13 @@ function parseLanguageConfigName(string $configProperty): ?array {
 /**
  * Parses a given config property name to determine if it is a language config name
  *
- * @param  string  $configProperty Config name
+ * @param  mixed  $configProperty Config name
  * @return boolean
  */
-function isLanguageConfigName(string $configProperty): bool {
-    return (bool) parseLanguageConfigName($configProperty);
+function isLanguageConfigName(mixed $configProperty): bool {
+  if (!is_string($configProperty)) {
+    return false;
+  }
+
+  return (bool) parseLanguageConfigName($configProperty);
 }

composer.json

@@ -9,7 +9,7 @@
     "localization"
   ],
   "homepage": "https://processwire.com/modules/fluency/",
-  "license": "GPL-3.0",
+  "license": "GPL-3.0-or-later",
   "authors": [
     {
       "name": "Sky Lundy",