Merge pull request #19438 from colemanw/afformDropAttrSupport

[civicrm-core.git] / CRM / Utils / Hook.php

diff --git a/CRM/Utils/Hook.php b/CRM/Utils/Hook.php
index f173abac3bf2955e94aa4e49f799b737de7ddd14..e5f576e408d5daaa8ce5ae707d965438d72e507e 100644 (file)
--- a/CRM/Utils/Hook.php
+++ b/CRM/Utils/Hook.php
@@ -155,7 +155,7 @@ abstract class CRM_Utils_Hook {
     if (!is_array($names)) {
       // We were called with the old contract wherein $names is actually an int.
       // Symfony dispatcher requires some kind of name.
-      Civi::log()->warning("hook_$fnSuffix should be updated to pass an array of parameter names to CRM_Utils_Hook::invoke().", ['civi.tag' => 'deprecated']);
+      CRM_Core_Error::deprecatedWarning("hook_$fnSuffix should be updated to pass an array of parameter names to CRM_Utils_Hook::invoke().");
       $compatNames = ['arg1', 'arg2', 'arg3', 'arg4', 'arg5', 'arg6'];
       $names = array_slice($compatNames, 0, (int) $names);
     }
@@ -1759,6 +1759,26 @@ abstract class CRM_Utils_Hook {
     );
   }
 
+  /**
+   * Register cryptographic resources, such as keys and cipher-suites.
+   *
+   * Ex: $crypto->addSymmetricKey([
+   *   'key' => hash_hkdf('sha256', 'abcd1234'),
+   *   'suite' => 'aes-cbc-hs',
+   * ]);
+   *
+   * @param \Civi\Crypto\CryptoRegistry $crypto
+   *
+   * @return mixed
+   */
+  public static function crypto($crypto) {
+    return self::singleton()->invoke(['crypto'], $crypto, self::$_nullObject,
+      self::$_nullObject, self::$_nullObject, self::$_nullObject,
+      self::$_nullObject,
+      'civicrm_crypto'
+    );
+  }
+
   /**
    * This hook collects the trigger definition from all components.
    *
@@ -2000,7 +2020,7 @@ abstract class CRM_Utils_Hook {
   }
 
   /**
-   * This hook is called when loading CMS permissions; use this hook to modify
+   * This hook is called when exporting Civi's permission to the CMS. Use this hook to modify
    * the array of system permissions for CiviCRM.
    *
    * @param array $permissions
@@ -2017,6 +2037,31 @@ abstract class CRM_Utils_Hook {
     );
   }
 
+  /**
+   * This hook is used to enumerate the list of available permissions. It may
+   * include concrete permissions defined by Civi, concrete permissions defined
+   * by the CMS, and/or synthetic permissions.
+   *
+   * @param array $permissions
+   *   Array of permissions, keyed by symbolic name. Each is an array with fields:
+   *     - group: string (ex: "civicrm", "cms")
+   *     - title: string (ex: "CiviEvent: Register for events")
+   *     - description: string (ex: "Register for events online")
+   *     - is_synthetic: bool (TRUE for synthetic permissions with a bespoke evaluation. FALSE for concrete permissions that registered+granted in the UF user-management layer.
+   *        Default TRUE iff name begins with '@')
+   *     - is_active: bool (TRUE if this permission is defined by. Default: TRUE)
+   *
+   * @return null
+   *   The return value is ignored
+   * @see Civi\Api4\Permission::get()
+   */
+  public static function permissionList(&$permissions) {
+    return self::singleton()->invoke(['permissions'], $permissions,
+      self::$_nullObject, self::$_nullObject, self::$_nullObject, self::$_nullObject, self::$_nullObject,
+      'civicrm_permissionList'
+    );
+  }
+
   /**
    * This hook is called when checking permissions; use this hook to dynamically
    * escalate user permissions in certain use cases (cf. CRM-19256).
@@ -2038,6 +2083,47 @@ abstract class CRM_Utils_Hook {
     );
   }
 
+  /**
+   * Rotate the cryptographic key used in the database.
+   *
+   * The purpose of this hook is to visit any encrypted values in the database
+   * and re-encrypt the content.
+   *
+   * For values encoded via `CryptoToken`, you can use `CryptoToken::rekey($oldToken, $tag)`
+   *
+   * @param string $tag
+   *   The type of crypto-key that is currently being rotated.
+   *   The hook-implementer should use this to decide which (if any) fields to visit.
+   *   Ex: 'CRED'
+   * @param \Psr\Log\LoggerInterface $log
+   *   List of messages about re-keyed values.
+   *
+   * @code
+   * function example_civicrm_rekey($tag, &$log) {
+   *   if ($tag !== 'CRED') return;
+   *
+   *   $cryptoToken = Civi::service('crypto.token');
+   *   $rows = sql('SELECT id, secret_column FROM some_table');
+   *   foreach ($rows as $row) {
+   *     $new = $cryptoToken->rekey($row['secret_column']);
+   *     if ($new !== NULL) {
+   *       sql('UPDATE some_table SET secret_column = %1 WHERE id = %2',
+   *         $new, $row['id']);
+   *     }
+   *   }
+   * }
+   * @endCode
+   *
+   * @return null
+   *   The return value is ignored
+   */
+  public static function cryptoRotateKey($tag, $log) {
+    return self::singleton()->invoke(['tag', 'log'], $tag, $log, self::$_nullObject,
+      self::$_nullObject, self::$_nullObject, self::$_nullObject,
+      'civicrm_cryptoRotateKey'
+    );
+  }
+
   /**
    * @param CRM_Core_Exception $exception
    * @param mixed $request