maintenance: use enum for matching endpoint in api requests (elabftw#4937)

This way, when we want to list all available endpoints, we can't miss
one!

* add new ApiEndpoint enum
* add a new InvalidEndpointException that will list all available endpoints in the error message to the user
* don't use static function for passwordcomplexity enum
* add two tests for enums
* rename src/enums to src/Enums

Author: NicolasCARPi

codeception.yml

@@ -8,7 +8,7 @@ coverage:
         - src/classes/*
         - src/commands/*
         - src/controllers/*
-        - src/enums/*
+        - src/Enums/*
         - src/exceptions/*
         - src/factories/*
         - src/Import/*

composer.json

@@ -83,7 +83,7 @@
         "src/exceptions"
       ],
       "Elabftw\\Enums\\": [
-        "src/enums"
+        "src/Enums"
       ],
       "Elabftw\\Factories\\": [
         "src/factories"

src/enums/Action.php renamed to src/Enums/Action.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types=1);
+/**
+ * @author Nicolas CARPi <[email protected]>
+ * @copyright 2024 Nicolas CARPi
+ * @see https://www.elabftw.net Official website
+ * @license AGPL-3.0
+ * @package elabftw
+ */
+
+namespace Elabftw\Enums;
+
+enum ApiEndpoint: string
+{
+    case ApiKeys = 'apikeys';
+    case Config = 'config';
+    case Idps = 'idps';
+    case Info = 'info';
+    case Experiments = 'experiments';
+    case Items = 'items';
+    case ExperimentsTemplates = 'experiments_templates';
+    case ItemsTypes = 'items_types';
+    case Event = 'event';
+    case Events = 'events';
+    case ExtraFieldsKeys = 'extra_fields_keys';
+    case FavTags = 'favtags';
+    case TeamTags = 'team_tags';
+    case Teams = 'teams';
+    case Todolist = 'todolist';
+    case UnfinishedSteps = 'unfinished_steps';
+    case Users = 'users';
+
+    public static function getCases(): array
+    {
+        return array_map(fn ($case) => $case->value, ApiEndpoint::cases());
+    }
+}

src/Enums/ApiEndpoint.php

@@ -0,0 +1,65 @@
+<?php declare(strict_types=1);
+/**
+ * @author Nicolas CARPi <[email protected]>
+ * @copyright 2024 Nicolas CARPi
+ * @see https://www.elabftw.net Official website
+ * @license AGPL-3.0
+ * @package elabftw
+ */
+
+namespace Elabftw\Enums;
+
+use function array_column;
+use function array_combine;
+use function array_map;
+
+enum PasswordComplexity: int
+{
+    case None = 0;
+    case Weak = 10;
+    case Medium = 20;
+    case Strong = 30;
+
+    public function toHuman(): string
+    {
+        return match ($this) {
+            self::None => _('Minimum password length'),
+            self::Weak => _('Must have at least one upper and one lower case letter, if your alphabet allows'),
+            self::Medium => _('Must have at least one upper and one lower case letter, if your alphabet allows, and one digit'),
+            self::Strong => _('Must have at least one upper and one lower case letter, if your alphabet allows, one special character, and one digit'),
+        };
+    }
+
+    public function toPattern(): string
+    {
+        // we need Lo for unicase/unicameral alphabets like Chinese, Japanese, and Korean
+        $letters = '(?:(?=.*\p{Ll})(?=.*\p{Lu})|(?=.*\p{Lo}))';
+        $digits = '(?=.*\d)';
+        return match ($this) {
+            self::None => '.*',
+            self::Weak => "^$letters.*$",
+            self::Medium => "^$letters$digits.*$",
+            self::Strong => "^$letters$digits(?=.*[\p{P}\p{S}]).*$",
+        };
+    }
+
+    /**
+     * For php, we need to add / as pre+suffix
+     * @return non-empty-string
+     */
+    public function toPhPattern(): string
+    {
+        return '/' . $this->toPattern() . '/u';
+    }
+
+    public static function getAssociativeArray(): array
+    {
+        $cases = self::cases();
+        $values = array_column($cases, 'value');
+        $descriptions = array_map(function ($case) {
+            return $case->toHuman();
+        }, $cases);
+
+        return array_combine($values, $descriptions);
+    }
+}

src/enums/AuditCategory.php renamed to src/Enums/AuditCategory.php

@@ -9,7 +9,9 @@
 
 namespace Elabftw\Controllers;
 
+use Elabftw\Enums\ApiEndpoint;
 use Elabftw\Exceptions\ImproperActionException;
+use Elabftw\Exceptions\InvalidEndpointException;
 use Elabftw\Interfaces\ControllerInterface;
 use Elabftw\Models\Users;
 use Elabftw\Services\Check;
@@ -28,7 +30,7 @@ abstract class AbstractApiController implements ControllerInterface
 
     protected string $search = '';
 
-    protected string $endpoint;
+    protected ApiEndpoint $endpoint;
 
     public function __construct(protected Users $Users, protected Request $Request, protected bool $canWrite = false)
     {
@@ -76,9 +78,9 @@ protected function parseReq(): array
             $this->search = trim($this->Request->query->getString('search'));
         }
 
-        // assign the endpoint (experiments, items, uploads, items_types, status)
-        // 0 is "", 1 is "api", 2 is "v1"
-        $this->endpoint = $req[3] ?? 'invalid_endpoint';
+        // assign the endpoint, see ApiEndpoint enum
+        // req array: 0 is "", 1 is "api", 2 is "v2"
+        $this->endpoint = ApiEndpoint::tryFrom((string) $req[3]) ?? throw new InvalidEndpointException();
 
         // assign the id if there is one
         if (Check::id((int) ($req[4] ?? 0)) !== false) {

src/enums/BasePermissions.php renamed to src/Enums/BasePermissions.php

@@ -10,6 +10,7 @@
 namespace Elabftw\Controllers;
 
 use Elabftw\Enums\Action;
+use Elabftw\Enums\ApiEndpoint;
 use Elabftw\Enums\EntityType;
 use Elabftw\Enums\ExportFormat;
 use Elabftw\Exceptions\IllegalActionException;
@@ -222,32 +223,31 @@ private function handlePatch(): array
     private function getModel(): RestInterface
     {
         return match ($this->endpoint) {
-            'apikeys' => new ApiKeys($this->Users, $this->id),
-            'config' => Config::getConfig(),
-            'idps' => new Idps($this->id),
-            'info' => new Info(),
-            'experiments',
-            'items',
-            'experiments_templates',
-            'items_types' => EntityType::from($this->endpoint)->toInstance($this->Users, $this->id),
+            ApiEndpoint::ApiKeys => new ApiKeys($this->Users, $this->id),
+            ApiEndpoint::Config => Config::getConfig(),
+            ApiEndpoint::Idps => new Idps($this->id),
+            ApiEndpoint::Info => new Info(),
+            ApiEndpoint::Experiments,
+            ApiEndpoint::Items,
+            ApiEndpoint::ExperimentsTemplates,
+            ApiEndpoint::ItemsTypes => EntityType::from($this->endpoint->value)->toInstance($this->Users, $this->id),
             // for a single event, the id is the id of the event
-            'event' => new Scheduler(new Items($this->Users), $this->id),
+            ApiEndpoint::Event => new Scheduler(new Items($this->Users), $this->id),
             // otherwise it's the id of the item
-            'events' => new Scheduler(
+            ApiEndpoint::Events => new Scheduler(
                 new Items($this->Users, $this->id),
                 null,
                 $this->Request->query->getString('start', Scheduler::EVENT_START),
                 $this->Request->query->getString('end', Scheduler::EVENT_END),
                 $this->Request->query->getInt('cat'),
             ),
-            'extra_fields_keys' => new ExtraFieldsKeys($this->Users, trim($this->Request->query->getString('q')), $this->Request->query->getInt('limit')),
-            'favtags' => new FavTags($this->Users, $this->id),
-            'team_tags' => new TeamTags($this->Users, $this->id),
-            'teams' => new Teams($this->Users, $this->id),
-            'todolist' => new Todolist($this->Users->userData['userid'], $this->id),
-            'unfinished_steps' => new UnfinishedSteps($this->Users, $this->Request->query->get('scope') === 'team'),
-            'users' => new Users($this->id, $this->Users->team, $this->Users),
-            default => throw new ImproperActionException('Invalid endpoint: available endpoints: apikeys, config, experiments, info, items, experiments_templates, items_types, event, events, extra_fields_keys, team_tags, teams, todolist, unfinished_steps, users.'),
+            ApiEndpoint::ExtraFieldsKeys => new ExtraFieldsKeys($this->Users, trim($this->Request->query->getString('q')), $this->Request->query->getInt('limit')),
+            ApiEndpoint::FavTags => new FavTags($this->Users, $this->id),
+            ApiEndpoint::TeamTags => new TeamTags($this->Users, $this->id),
+            ApiEndpoint::Teams => new Teams($this->Users, $this->id),
+            ApiEndpoint::Todolist => new Todolist($this->Users->userData['userid'], $this->id),
+            ApiEndpoint::UnfinishedSteps => new UnfinishedSteps($this->Users, $this->Request->query->get('scope') === 'team'),
+            ApiEndpoint::Users => new Users($this->id, $this->Users->team, $this->Users),
         };
     }
 

src/enums/DisplayMode.php renamed to src/Enums/DisplayMode.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types=1);
+/**
+ * @author Nicolas CARPi <[email protected]>
+ * @copyright 2024 Nicolas CARPi
+ * @see https://www.elabftw.net Official website
+ * @license AGPL-3.0
+ * @package elabftw
+ */
+
+namespace Elabftw\Exceptions;
+
+use Elabftw\Enums\ApiEndpoint;
+
+/**
+ * For invalid api endpoint
+ */
+class InvalidEndpointException extends ImproperActionException
+{
+    public function __construct()
+    {
+        parent::__construct(sprintf('Invalid endpoint: available endpoints: %s', implode(', ', ApiEndpoint::getCases())));
+    }
+}

src/enums/EmailTarget.php renamed to src/Enums/EmailTarget.php

@@ -21,7 +21,7 @@
  */
 class PasswordValidator
 {
-    public function __construct(private int $minLength, private PasswordComplexity $passwordComplexity)
+    public function __construct(private readonly int $minLength, private readonly PasswordComplexity $passwordComplexity)
     {
     }
 
@@ -30,9 +30,9 @@ public function validate(string $password): bool
         if (mb_strlen($password) < $this->minLength) {
             throw new ImproperActionException(sprintf(_('Password must contain at least %d characters.'), $this->minLength));
         }
-        $pattern = PasswordComplexity::toPhPattern($this->passwordComplexity);
+        $pattern = $this->passwordComplexity->toPhPattern();
         if (((bool) preg_match($pattern, $password)) === false) {
-            throw new ImproperActionException(sprintf(_('Password does not match requirement: %s'), PasswordComplexity::toHuman($this->passwordComplexity)));
+            throw new ImproperActionException(sprintf(_('Password does not match requirement: %s'), $this->passwordComplexity->toHuman()));
         }
         return true;
     }

src/enums/EnforceMfa.php renamed to src/Enums/EnforceMfa.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types=1);
+/**
+ * @author Nicolas CARPi <[email protected]>
+ * @copyright 2024 Nicolas CARPi
+ * @see https://www.elabftw.net Official website
+ * @license AGPL-3.0
+ * @package elabftw
+ */
+
+namespace Elabftw\Enums;
+
+class EnumsTest extends \PHPUnit\Framework\TestCase
+{
+    public function testApiEndpoint(): void
+    {
+        $this->assertIsArray(ApiEndpoint::getCases());
+    }
+
+    public function testEntrypoint(): void
+    {
+        array_map(fn ($case) => $this->assertStringEndsWith('.php', $case->toPage()), Entrypoint::cases());
+    }
+}

src/enums/EntityType.php renamed to src/Enums/EntityType.php

@@ -120,8 +120,8 @@
         'statusArr' => $statusArr,
         'experimentsCategoriesArr' => $experimentsCategoriesArr,
         'itemsStatusArr' => $itemsStatusArr,
-        'passwordInputHelp' => PasswordComplexity::toHuman($passwordComplexity),
-        'passwordInputPattern' => PasswordComplexity::toPattern($passwordComplexity),
+        'passwordInputHelp' => $passwordComplexity->toHuman(),
+        'passwordInputPattern' => $passwordComplexity->toPattern(),
         'teamGroupsArr' => $teamGroupsArr,
         'visibilityArr' => $PermissionsHelper->getAssociativeArray(),
         'remoteDirectoryUsersArr' => $remoteDirectoryUsersArr,

src/enums/Entrypoint.php renamed to src/Enums/Entrypoint.php

@@ -42,8 +42,8 @@
     $passwordComplexity = PasswordComplexity::from((int) $App->Config->configArr['password_complexity_requirement']);
     $renderArr = array(
         'key' => $App->Request->query->getAlnum('key'),
-        'passwordInputHelp' => PasswordComplexity::toHuman($passwordComplexity),
-        'passwordInputPattern' => PasswordComplexity::toPattern($passwordComplexity),
+        'passwordInputHelp' => $passwordComplexity->toHuman(),
+        'passwordInputPattern' => $passwordComplexity->toPattern(),
     );
 } catch (Exception $e) {
     $template = 'error.html';

src/enums/ExportFormat.php renamed to src/Enums/ExportFormat.php

@@ -51,8 +51,8 @@
     $template = 'register.html';
     $renderArr = array(
         'hideTitle' => true,
-        'passwordInputHelp' => PasswordComplexity::toHuman($passwordComplexity),
-        'passwordInputPattern' => PasswordComplexity::toPattern($passwordComplexity),
+        'passwordInputHelp' => $passwordComplexity->toHuman(),
+        'passwordInputPattern' => $passwordComplexity->toPattern(),
         'privacyPolicy' => $App->Config->configArr['privacy_policy'] ?? '',
         'teamsArr' => $teamsArr,
     );

src/enums/FileFromString.php renamed to src/Enums/FileFromString.php

@@ -131,8 +131,8 @@
         'elabimgVersion' => $elabimgVersion,
         'idpsArr' => $idpsArr,
         'isSearching' => $isSearching,
-        'passwordInputHelp' => PasswordComplexity::toHuman($passwordComplexity),
-        'passwordInputPattern' => PasswordComplexity::toPattern($passwordComplexity),
+        'passwordInputHelp' => $passwordComplexity->toHuman(),
+        'passwordInputPattern' => $passwordComplexity->toPattern(),
         'phpInfos' => $phpInfos,
         'remoteDirectoryUsersArr' => $remoteDirectoryUsersArr,
         'samlSecuritySettings' => $samlSecuritySettings,

src/enums/FilterableColumn.php renamed to src/Enums/FilterableColumn.php

@@ -120,8 +120,8 @@
         'metadataGroups' => $metadataGroups,
         'allTeamgroupsArr' => $TeamGroups->readGroupsFromUser(),
         'notificationsSettings' => $notificationsSettings,
-        'passwordInputHelp' => PasswordComplexity::toHuman($passwordComplexity),
-        'passwordInputPattern' => PasswordComplexity::toPattern($passwordComplexity),
+        'passwordInputHelp' => $passwordComplexity->toHuman(),
+        'passwordInputPattern' => $passwordComplexity->toPattern(),
         'statusArr' => $Status->readAll(),
         'teamTagsArr' => $TeamTags->readAll(),
         'templatesArr' => $Templates->readAll(),