Tidy setConfig code; add a lot of documentation

Civi/Inlay/Type.php

@@ -388,24 +388,31 @@ abstract class Type {
   }
 
   /**
-   * Sets the config ensuring it's valid.
+   * Sets the config from a stored array.
    *
-   * This implementation simply ensures all the defaults exist, and that no
-   * other keys exist, but you could do other things, especially if you need to
-   * coerce some old config into a new style.
+   * There's some code here to assist with config changes over time and validity checks.
    *
    * @param array $config
    *
    * @return \Civi\Inlay\Type (this)
    */
   public function setConfig(array $config): Type {
+
     // Check if migration needed
     if (!empty(static::CONFIG_VERSION) && ($config['version'] ?? '') !== static::CONFIG_VERSION) {
       $config = $this->migrateConfig($config);
     }
-    // Reasonable fallback method:
+
+    // This simply ensures all the defaults exist, and that no
+    // other top-level keys exist. It's the implementation used up-to inlay 1.3.5 so
+    // seems sensible to keep it. Most configs are fairly simple key => scalar types.
+    // You'll need to use a migration if you need to apply new defaults below the top level keys.
     $this->config = array_intersect_key($config + static::$defaultConfig, static::$defaultConfig);
-    $this->validateConfig(TRUE);
+
+    // Finally, see if we can validate (with some coercion) the config array
+    // against our schema. This does nothing if we don't override getConfigSchema().
+    $this->validateConfig(TRUE, FALSE);
+
     return $this;
   }
 
@@ -413,19 +420,18 @@ abstract class Type {
    * Called with an array of config when an Inlay\Type class has a CONFIG_VERSION set
    * that differs from the 'version' in the $config array.
    *
-   * Override this with suitable migrations. If significant you may wish to put those
-   * in other files.
+   * **Override this** with suitable migrations. If significant you may wish to put this
+   * code in other files.
    *
    * Note: this does not SAVE your migrated config; this will run each time old config is loaded.
    * Your CRM_YourInlay_Upgrader code should do an API call to save migrated config. This is a
-   * precaution against automatically applying a migration in a persisted way. However, migrated
-   * content will get persisted if you edit the inlay's config and hit Save yourself, but it's
-   * assumed that you have then verified everything.
-   *
+   * precaution against automatically applying a migration that doesn't work in a persisted way.
+   * However, migrated content *will* get persisted if you edit the inlay's config and hit Save
+   * yourself, but it's assumed that you have then verified everything manually if you do that.
    */
   protected function migrateConfig(array $config): array {
-    $config['version'] = static::CONFIG_VERSION;
     // ... your migrations here ...
+    $config['version'] = static::CONFIG_VERSION;
     return $config;
   }
 
@@ -433,7 +439,7 @@ abstract class Type {
    * Check the config we have against a schema, if one exists,
    * and return any errors.
    */
-  public function validateConfig($coerce = TRUE): array {
+  public function validateConfig($coerce = TRUE, $throw = TRUE): array {
     $errors = [];
     $schema = $this->getConfigSchema();
     if (!empty($schema)) {
@@ -443,13 +449,26 @@ abstract class Type {
       }
       $errors = $validator->getErrors($this->config);
     }
+    if (!empty($errors)) {
+      $data = [
+          'id' => $this->getID(),
+          'type' => $this->getTypeName(),
+          'errors' => $errors,
+          'config' => $this->config,
+        ];
+      \Civi::log()->critical("Inlay {id} {type} has invalid config! This could mean it is broken, and could (possibly) affect other Inlays.", $data);
+      if ($throw) {
+        throw new \RuntimeException("Invalid configuration in Inlay $data[id] of type $data[type]. See logs.");
+      }
+    }
+
     return $errors;
   }
 
   /**
-   * Optionally you can override this with a schema definition for your config.
+   * Optionally you can **override this** with a schema definition for your config.
    *
-   * @see Civi\Inlay\ArraySchema
+   * @see \Civi\Inlay\ArraySchema
    */
   public function getConfigSchema(): array {
     return [];