AfformScanner - Update code comments & type hints

diff --git a/ext/afform/core/CRM/Afform/AfformScanner.php b/ext/afform/core/CRM/Afform/AfformScanner.php
index 5a27b5e71dcde2933bd36f3e6446242c236748a2..427c255b5f59756b79c3e3feacfdab7af11f9abc 100644 (file)
--- a/ext/afform/core/CRM/Afform/AfformScanner.php
+++ b/ext/afform/core/CRM/Afform/AfformScanner.php
@@ -3,8 +3,8 @@
 /**
  * Class CRM_Afform_AfformScanner
  *
- * The AfformScanner searches the extensions and `civicrm.files` for subfolders
- * named `afform`. Each item in there is interpreted as a form instance.
+ * The AfformScanner searches the `ang` directory of extensions and `civicrm.files` for files
+ * named `*.aff.*`. Each item is interpreted as a form instance.
  *
  * To reduce file-scanning, we keep a cache of file paths.
  */
@@ -36,7 +36,7 @@ class CRM_Afform_AfformScanner {
    * Get a list of all forms and their file paths.
    *
    * @return array
-   *   Ex: ['view-individual' => ['/var/www/foo/afform/view-individual']]
+   *   Ex: ['afformViewIndividual' => ['/var/www/foo/ang/afformViewIndividual']]
    */
   public function findFilePaths(): array {
     if ($this->isUseCachedPaths()) {
@@ -86,16 +86,16 @@ class CRM_Afform_AfformScanner {
   }
 
   /**
-   * Get the full path to the given file.
+   * Get the absolute path to the given file.
    *
    * @param string $formName
-   *   Ex: 'view-individual'
+   *   Ex: 'afformViewIndividual'
    * @param string $suffix
    *   Ex: 'aff.json'
    * @return string|NULL
-   *   Ex: '/var/www/sites/default/files/civicrm/afform/view-individual.aff.json'
+   *   Ex: '/var/www/sites/default/files/civicrm/ang/afform/afformViewIndividual.aff.json'
    */
-  public function findFilePath($formName, $suffix) {
+  public function findFilePath(string $formName, string $suffix): ?string {
     $paths = $this->findFilePaths();
 
     if (isset($paths[$formName])) {
@@ -110,21 +110,21 @@ class CRM_Afform_AfformScanner {
   }
 
   /**
-   * Determine the path where we can write our own customized/overriden
+   * Determine the path where we can write our own customized/overridden
    * version of a file.
    *
    * @param string $formName
-   *   Ex: 'view-individual'
-   * @param string $file
+   *   Ex: 'afformViewIndividual'
+   * @param string $fileType
    *   Ex: 'aff.json'
-   * @return string|NULL
-   *   Ex: '/var/www/sites/default/files/civicrm/afform/view-individual.aff.json'
+   * @return string
+   *   Ex: '/var/www/sites/default/files/civicrm/afform/afformViewIndividual.aff.json'
    */
-  public function createSiteLocalPath($formName, $file) {
-    return $this->getSiteLocalPath() . DIRECTORY_SEPARATOR . $formName . '.' . $file;
+  public function createSiteLocalPath(string $formName, string $fileType): string {
+    return $this->getSiteLocalPath() . DIRECTORY_SEPARATOR . $formName . '.' . $fileType;
   }
 
-  public function clear() {
+  public function clear(): void {
     $this->cache->delete('afformAllPaths');
   }
 
@@ -132,12 +132,12 @@ class CRM_Afform_AfformScanner {
    * Get the effective metadata for a form.
    *
    * @param string $name
-   *   Ex: 'view-individual'
+   *   Ex: 'afformViewIndividual'
    * @return array
    *   An array with some mix of the following keys: name, title, description, server_route, requires, is_public.
    *   NOTE: This is only data available in *.aff.json. It does *NOT* include layout.
    *   Ex: [
-   *     'name' => 'view-individual',
+   *     'name' => 'afformViewIndividual',
    *     'title' => 'View an individual contact',
    *     'server_route' => 'civicrm/view-individual',
    *     'requires' => ['afform'],
@@ -185,9 +185,9 @@ class CRM_Afform_AfformScanner {
    *
    * @param array $record
    */
-  public function addComputedFields(&$record) {
+  public function addComputedFields(array &$record) {
     $name = $record['name'];
-    // Ex: $allPaths['viewIndividual']['org.civicrm.foo'] == '/var/www/foo/afform/view-individual'].
+    // Ex: $allPaths['viewIndividual']['org.civicrm.foo'] == '/var/www/foo/ang/afformViewIndividual'].
     $allPaths = $this->findFilePaths()[$name] ?? [];
     // Empty string key refers to the site local path
     $record['has_local'] = isset($allPaths['']);
@@ -210,14 +210,14 @@ class CRM_Afform_AfformScanner {
   }
 
   /**
-   * Get the effective metadata for all forms.
+   * Get the effective metadata for all file-based forms.
    *
    * @return array
    *   A list of all forms, keyed by form name.
-   *   NOTE: This is only data available in *.aff.json. It does *NOT* include layout.
-   *   Ex: ['view-individual' => ['title' => 'View an individual contact', ...]]
+   *   NOTE: This is only data available in metadata files. It does *NOT* include layout.
+   *   Ex: ['afformViewIndividual' => ['title' => 'View an individual contact', ...]]
    */
-  public function getMetas() {
+  public function getMetas(): array {
     $result = [];
     foreach (array_keys($this->findFilePaths()) as $name) {
       $result[$name] = $this->getMeta($name);
@@ -226,7 +226,7 @@ class CRM_Afform_AfformScanner {
   }
 
   /**
-   * @param array $formPaths
+   * @param array[] $formPaths
    *   List of all form paths.
    *   Ex: ['foo' => [0 => '/var/www/org.example.foobar/ang']]
    * @param string $parent
@@ -234,7 +234,7 @@ class CRM_Afform_AfformScanner {
    * @param string $module
    *   Name of module or '' empty string for local files.
    */
-  private function appendFilePaths(&$formPaths, $parent, $module) {
+  private function appendFilePaths(array &$formPaths, string $parent, string $module) {
     $files = preg_grep(self::FILE_REGEXP, (array) glob("$parent/*"));
 
     foreach ($files as $file) {
@@ -249,10 +249,10 @@ class CRM_Afform_AfformScanner {
   /**
    * Get the path where site-local form customizations are stored.
    *
-   * @return mixed|string
+   * @return string
    *   Ex: '/var/www/sites/default/files/civicrm/afform'.
    */
-  public function getSiteLocalPath() {
+  public function getSiteLocalPath(): string {
     // TODO Allow a setting override.
     // return Civi::paths()->getPath(Civi::settings()->get('afformPath'));
     return Civi::paths()->getPath('[civicrm.files]/ang');