Issue #3516579 by dydave: Automated testing on GitLab CI: Added initial...

https://www.drupal.org/project/config_perms/issues/3526269

Based on the work from MR !6 by @wylbur.

Fixed all jobs validation errors: CSPELL, PHPCS and PHPSTAN.

Broadened Tests coverage and required all jobs to pass.

src/Form/ConfigPermListForm.php

@@ -10,28 +10,31 @@ use Drupal\Core\Routing\RouteProviderInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
- * Class ConfigPermListForm.
+ * Provides the admin configuration form for managing custom permissions.
+ *
+ * Allows site administrators to enable, disable, edit, add, and delete
+ * route-based permissions for configuration access.
  *
  * @package Drupal\config_perms\Form
  */
 class ConfigPermListForm extends FormBase {
 
   /**
-   * Router Provider service.
+   * The router provider service.
    *
-   * @var \Drupal\Core\Routing\RouteProvider
+   * @var \Drupal\Core\Routing\RouteProviderInterface
    */
   protected $routerProvider;
 
   /**
-   * Router Builder service.
+   * The router builder service.
    *
-   * @var \Drupal\Core\Routing\RouteBuilder
+   * @var \Drupal\Core\Routing\RouteBuilderInterface
    */
   protected $routerBuilder;
 
   /**
-   * Class constructor.
+   * Constructs a new ConfigPermListForm object.
    *
    * @param \Drupal\Core\Routing\RouteProviderInterface $router_provider
    *   The router provider service.
@@ -47,9 +50,7 @@ class ConfigPermListForm extends FormBase {
    * {@inheritdoc}
    */
   public static function create(ContainerInterface $container) {
-    // Instantiates this form class.
     return new static(
-    // Load the service required to construct this class.
       $container->get('router.route_provider'),
       $container->get('router.builder')
     );
@@ -63,25 +64,38 @@ class ConfigPermListForm extends FormBase {
   }
 
   /**
-   * {@inheritdoc}
+   * Builds the permissions administration form.
+   *
+   * Displays a table of custom permissions with options to modify or add new
+   * ones.
+   *
+   * @param array $form
+   *   The form array.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The form state object.
+   *
+   * @return array
+   *   The complete form render array.
    */
   public function buildForm(array $form, FormStateInterface $form_state) {
-
+    // Form initialization and description fieldset.
     $form['perms'] = [
       '#type' => 'fieldset',
       '#title' => $this->t('Custom Permissions'),
       '#description' => '<p>' . $this->t("Please note that the order in which permissions are granted are as follows:") . '</p>' .
       "<ul>
-       <li>" . $this->t("Custom permissions only support routes") . "</li>\n
-       <li>" . $this->t("User 1 still maintains full control") . "</li>\n
-       <li>" . $this->t("Remove the permission 'Administer site configuration' from roles you wish to give access to only specified custom site configuration permissions") . "</li>\n
-      </ul>",
-      '#collapsible' => 1,
-      '#collapsed' => 0,
+         <li>" . $this->t("Custom permissions only support routes") . "</li>\n
+         <li>" . $this->t("User 1 still maintains full control") . "</li>\n
+         <li>" . $this->t("Remove the permission 'Administer site configuration' from roles you wish to give access to only specified custom site configuration permissions") . "</li>\n
+        </ul>",
+      '#collapsible' => TRUE,
+      '#collapsed' => FALSE,
     ];
 
+    // Load all existing custom permissions.
     $perms = CustomPermsEntity::loadMultiple();
 
+    // Table header.
     $header = [
       $this->t('Enabled'),
       $this->t('Name'),
@@ -90,6 +104,7 @@ class ConfigPermListForm extends FormBase {
       '',
     ];
 
+    // Setup the editable table.
     $form['perms']['local'] = [
       '#type' => 'table',
       '#header' => $header,
@@ -97,63 +112,46 @@ class ConfigPermListForm extends FormBase {
       '#suffix' => '</div>',
     ];
 
+    // Populate table rows for each permission.
     /** @var \Drupal\config_perms\Entity\CustomPermsEntity $perm */
     foreach ($perms as $key => $perm) {
-
       $form['perms']['local'][$key] = ['#tree' => TRUE];
 
       $form['perms']['local'][$key]['status'] = [
         '#type' => 'checkbox',
         '#default_value' => $perm->status(),
       ];
-
       $form['perms']['local'][$key]['name'] = [
         '#type' => 'textfield',
         '#default_value' => $perm->label(),
         '#size' => 30,
       ];
-
       $form['perms']['local'][$key]['route'] = [
         '#type' => 'textarea',
         '#default_value' => $perm->getRoute(),
         '#size' => 50,
         '#rows' => 1,
       ];
-
-      // Delete link.
-      $delete_link = $perm->toLink($this->t('Delete'), 'delete-form');
-      $form['perms']['local'][$key]['delete'] = $delete_link->toRenderable();
+      $form['perms']['local'][$key]['delete'] = $perm->toLink($this->t('Delete'), 'delete-form')->toRenderable();
       $form['perms']['local'][$key]['id'] = [
         '#type' => 'hidden',
         '#default_value' => $perm->id(),
       ];
     }
 
-    $num_new = $form_state->getValue('num_new');
-    if (empty($num_new)) {
-      $form_state->setValue('num_new', '0');
-    }
-
-    for ($i = 0; $i < $form_state->getValue('num_new'); $i++) {
-      $form['perms']['local']['new']['status'] = [
-        '#type' => 'checkbox',
-        '#default_value' => '',
-      ];
-      $form['perms']['local']['new']['name'] = [
-        '#type' => 'textfield',
-        '#default_value' => '',
-        '#size' => 30,
-      ];
+    // Initialize new row handling.
+    $num_new = $form_state->getValue('num_new') ?? 0;
+    $form_state->setValue('num_new', $num_new);
 
-      $form['perms']['local']['new']['route'] = [
-        '#type' => 'textarea',
-        '#default_value' => '',
-        '#rows' => 2,
-        '#size' => 50,
+    for ($i = 0; $i < $num_new; $i++) {
+      $form['perms']['local']['new'] = [
+        'status' => ['#type' => 'checkbox'],
+        'name' => ['#type' => 'textfield', '#size' => 30],
+        'route' => ['#type' => 'textarea', '#rows' => 2, '#size' => 50],
       ];
-
     }
 
+    // Add permission button.
     $form['perms']['add']['status'] = [
       '#name' => 'status',
       '#id' => 'edit-local-status',
@@ -166,6 +164,7 @@ class ConfigPermListForm extends FormBase {
       ],
     ];
 
+    // Save button.
     $form['submit'] = [
       '#type' => 'submit',
       '#value' => $this->t('Save'),
@@ -175,14 +174,29 @@ class ConfigPermListForm extends FormBase {
   }
 
   /**
-   * Callback for add button.
+   * AJAX callback to refresh the table after adding a new permission.
+   *
+   * @param array $form
+   *   The form array.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The form state object.
+   *
+   * @return array
+   *   The rendered portion of the form to update.
    */
   public function configPermsAdminFormAddCallback($form, $form_state) {
     return $form['perms']['local'];
   }
 
   /**
-   * Submit for add button.
+   * Submit handler for the "Add permission" button.
+   *
+   * Increments the number of new permission rows.
+   *
+   * @param array $form
+   *   The form array.
+   * @param \Drupal\Core\Form\FormStateInterface $form_state
+   *   The form state object.
    */
   public function configPermsAdminFormAddSubmit($form, &$form_state) {
     $form_state->setValue('num_new', $form_state->getValue('num_new') + 1);
@@ -197,27 +211,24 @@ class ConfigPermListForm extends FormBase {
     $perms = CustomPermsEntity::loadMultiple();
 
     foreach ($values['local'] as $key => $perm) {
-
-      if (empty($perm['name']) && empty($perm['route']) && $key != 'new') {
-        $entity = CustomPermsEntity::load($perm['id']);
-        $entity->delete();
+      if (empty($perm['name']) && empty($perm['route']) && $key !== 'new') {
+        CustomPermsEntity::load($perm['id'])->delete();
       }
       else {
         if (empty($perm['name'])) {
-          $form_state->setErrorByName("local][" . $key . "", $this->t("The name cannot be empty."));
+          $form_state->setErrorByName("local][$key", $this->t("The name cannot be empty."));
         }
-
         if (empty($perm['route'])) {
-          $form_state->setErrorByName("local][" . $key . "", $this->t("The route cannot be empty."));
+          $form_state->setErrorByName("local][$key", $this->t("The route cannot be empty."));
         }
         if (array_key_exists($this->configPermsGenerateMachineName($perm['name']), $perms) && !isset($perm['id'])) {
-          $form_state->setErrorByName("local][" . $key . "", $this->t("A permission with that name already exists."));
+          $form_state->setErrorByName("local][$key", $this->t("A permission with that name already exists."));
         }
         if (!empty($perm['route'])) {
           $routes = config_perms_parse_path($perm['route']);
           foreach ($routes as $route) {
             if (count($this->routerProvider->getRoutesByNames([$route])) < 1) {
-              $form_state->setErrorByName("local][" . $key . "", $this->t("The route @route is invalid.", ['@route' => $perm['route']]));
+              $form_state->setErrorByName("local][$key", $this->t("The route @route is invalid.", ['@route' => $perm['route']]));
             }
           }
         }
@@ -233,15 +244,14 @@ class ConfigPermListForm extends FormBase {
     $perms = CustomPermsEntity::loadMultiple();
 
     foreach ($values['local'] as $key => $data) {
-      // If new permission.
-      if ($key == 'new') {
+      if ($key === 'new') {
         $entity = CustomPermsEntity::create();
         $entity->set('id', $this->configPermsGenerateMachineName($data['name']));
       }
       else {
-        // Update || Insert.
         $entity = $perms[$data['id']];
       }
+
       $entity->set('label', $data['name']);
       $entity->set('route', $data['route']);
       $entity->set('status', $data['status']);
@@ -253,7 +263,16 @@ class ConfigPermListForm extends FormBase {
   }
 
   /**
-   * Generate a machine name given a string.
+   * Generates a machine name from a string.
+   *
+   * Converts a string to a lowercase, underscore-separated format suitable
+   * for use as an ID.
+   *
+   * @param string $string
+   *   The human-readable string.
+   *
+   * @return string
+   *   The machine-friendly identifier.
    */
   public function configPermsGenerateMachineName($string) {
     return strtolower(preg_replace('/[^a-zA-Z0-9_]+/', '_', $string));