Add status constants and extension point for flexible user status management

[Copilot]

Overview

This PR implements a more flexible approach to managing YCom user status options by introducing status constants, a callable method, and an extension point for project-specific customization.

Problem

Previously, status options were hardcoded as a long string in the YForm table definition:

"choices": "translate:ycom_account_inactive_termination=-3,translate:ycom_account_inactive_logins=-2,..."

This made it difficult to:

• Use status values programmatically without magic numbers
• Customize status options per project
• Add project-specific status values
• Maintain code readability

Solution

Following the pattern from FriendsOfREDAXO/warehouse, this PR adds:

1. Status Constants

// In rex_ycom_user class
public const STATUS_INACTIVE_TERMINATION = -3;
public const STATUS_INACTIVE_LOGINS = -2;
public const STATUS_INACTIVE = -1;
public const STATUS_REQUESTED = 0;
public const STATUS_CONFIRMED = 1;
public const STATUS_ACTIVE = 2;

2. Status Options Method with Extension Point

public static function getStatusOptions(): array
{
    $statusOptions = rex_extension::registerPoint(
        new rex_extension_point('YCOM_USER_STATUS_OPTIONS', self::DEFAULT_STATUS_OPTIONS)
    );
    if (!is_array($statusOptions)) {
        $statusOptions = self::DEFAULT_STATUS_OPTIONS;
    }
    return $statusOptions;
}

3. Callable in YForm Definition

"choices": "callable::rex_ycom_user::getStatusOptions"

Usage Examples

Using constants in code:

// Instead of magic numbers
$user->setValue('status', rex_ycom_user::STATUS_CONFIRMED);

// Check status programmatically
if ($user->getValue('status') >= rex_ycom_user::STATUS_CONFIRMED) {
    // User is confirmed and can login
}

Extending status options via extension point:

rex_extension::register('YCOM_USER_STATUS_OPTIONS', function (rex_extension_point $ep) {
    $statusOptions = $ep->getSubject();
    
    // Add custom status
    $statusOptions[3] = 'translate:ycom_account_premium';
    $statusOptions[4] = 'translate:ycom_account_vip';
    
    return $statusOptions;
});

Benefits

• ✅ Better Code Readability: Named constants instead of magic numbers
• ✅ Flexibility: Projects can add custom status values via extension point
• ✅ Maintainability: Centralized status definitions
• ✅ Backward Compatible: All existing functionality remains unchanged
• ✅ Well Documented: Comprehensive documentation and examples added

Changes

• Added status constants to rex_ycom_user class
• Created getStatusOptions() method with YCOM_USER_STATUS_OPTIONS extension point
• Updated YForm table definition to use callable
• Enhanced documentation with status constants table and usage examples
• Added comprehensive examples file (docs/12_status_examples.md)
• Created unit tests for new functionality

Testing

Unit tests verify:

• All constants are defined with correct values
• DEFAULT_STATUS_OPTIONS contains all expected entries
• getStatusOptions() returns proper array structure

Fixes #XXX

/cc @j4ceee

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/composer/semver/zipball/c51258e759afdb17f1fd1fe83bc12baaef6309d6
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/LulFZE /usr/bin/composer install (http block)
• https://api.github.com/repos/composer/xdebug-handler/zipball/6c1925561632e83d60a44492e0b344cf48ab85ef
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/LulFZE /usr/bin/composer install (http block)
• https://api.github.com/repos/sebastianbergmann/object-reflector/zipball/b4f479ebdbf63ac605d183ece17d8d7fe49c15c7
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/LulFZE /usr/bin/composer install (http block)
• https://api.github.com/repos/sebastianbergmann/recursion-context/zipball/e75bd0f07204fec2a0af9b0f3cfe97d05f92efc1
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/LulFZE /usr/bin/composer install (http block)
• https://api.github.com/repos/sebastianbergmann/resource-operations/zipball/05d5692a7993ecccd56a03e40cd7e5b09b1d404e
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/LulFZE /usr/bin/composer install (http block)
• https://api.github.com/repos/sebastianbergmann/type/zipball/75e2c2a32f5e0b3aef905b9ed0b179b953b3d7c7
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/LulFZE /usr/bin/composer install (http block)
• https://api.github.com/repos/sebastianbergmann/version/zipball/c6c1022351a901512170118436c764e473f6de8c
  • Triggering command: /usr/bin/php8.3 -n -c /tmp/LulFZE /usr/bin/composer install (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>status-Choice-Feld an rex_user in ein Callable mit Extension Point ändern</issue_title>
<issue_description>Es wäre hilfreich, die von YCom definierten Status-Optionen flexibler machen zu können und auch im Label an das Projekt anzupassen.

ycom/install/tablesets/yform_user.json

Line 180 in 096da17

"choices": "translate:ycom_account_inactive_termination=-3,translate:ycom_account_inactive_logins=-2,translate:ycom_account_inactive=-1,translate:ycom_account_requested=0,translate:ycom_account_confirm=1,translate:ycom_account_active=2",

                "choices": "translate:ycom_account_inactive_termination=-3,translate:ycom_account_inactive_logins=-2,translate:ycom_account_inactive=-1,translate:ycom_account_requested=0,translate:ycom_account_confirm=1,translate:ycom_account_active=2",

In diesem Szenario gibt es verschiedene Gründe, weshalb man einen Status (oder auch nur eine Übersetzung davon) projektspezifisch anpassen möchte und ggf. programmatisch auf den richtigen Wert in einer Konstante zurückgreifen möchte.

Mein Vorschlag wäre dazu:

1. Konstanten einsetzen, die widerspiegeln, was die Werte bedeuten, z.B. User::STATUS_ACTIVATED = 1, User::STATUS_INACTIVE = -1, User::STATUS_REGISTERED = 0, User::STATUS_VERIFIED = 2 ...
2. Eine Methode, die Status-Optionen zurückgibt, z.B. getStatusOptions()
3. Ein Callable in der YForm-Tabellenfeld-Definition hinterlegen, z.B. YCom\User::getStatusOptions()
4. Ein EP innerhalb, der weitere Optionen ergänzt.

Konzeptionell sollte sich alles >= 1 einloggen dürfen, alles <= -1 nicht und 0 ist reserviert für die registriert-aber-Nutzungsbedingungen-fehlen-Variante, wobei sich diese Information m.E. auch im Zeitstempel der Nutzungsbedingungen widerspiegelt.

Beispiel so einer Umsetzung (hier eigene Steuersätze ergänzen - das auf das Thema "Status" münzen):
https://github.com/FriendsOfREDAXO/warehouse/blob/ec6aef56f806731c06852b61f98cd2c051253064/lib/Article.php#L55-L59

    public const DEFAULT_TAX_OPTIONS = [
        '19' => '19%',
        '7' => '7%',
        '0' => '0%',
    ];

https://github.com/FriendsOfREDAXO/warehouse/blob/ec6aef56f806731c06852b61f98cd2c051253064/lib/Article.php#L407-L416

    public static function getTaxOptions() : array
    {
        // Statt statischer Werte können zusätzlich über einen Extension Point weitere Steuersätze hinzugefügt werden.
        $taxOptions = rex_extension::registerPoint(new rex_extension_point('WAREHOUSE_TAX_OPTIONS', self::DEFAULT_TAX_OPTIONS));
        if (!is_array($taxOptions)) {
            $taxOptions = self::DEFAULT_TAX_OPTIONS;
        }
        return $taxOptions;
    }

// EP für WAREHOUSE_TAX verwenden und weitere Steuersätze hinzufügen

rex_extension::register('WAREHOUSE_TAX_OTIONS', function (rex_extension_point $ep) {
    /** @var array<int,string> $taxes */
    $taxes = $ep->getSubject();
    $taxes[42] = '42%';
    krsort($taxes);
    return $taxes;
});

/cc @j4ceee </issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #524

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Copilot]

Pull Request Overview

This PR implements a flexible approach to managing YCom user status options by introducing status constants, a callable method with an extension point, and comprehensive documentation.

• Added status constants to replace magic numbers in code
• Implemented getStatusOptions() method with YCOM_USER_STATUS_OPTIONS extension point
• Updated YForm table definition to use callable for dynamic status options

Reviewed Changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lib/ycom_user.php	Added status constants, default options array, and getStatusOptions() method with extension point
install/tablesets/yform_user.json	Updated choices field to use callable instead of hardcoded string
tests/unit/user_status_test.php	Added comprehensive unit tests for new status functionality
docs/12_status_examples.md	Created new documentation with usage examples and status table
docs/05_passwords.md	Enhanced existing documentation with status constants and extension examples
docs/03_login_logout_profile_register.md	Added informational note about status constants for form usage

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The placeholder 'X.X' should be replaced with the actual version number when this feature is released.

Suggested change

	Seit Version X.X werden die Status-Werte als Konstanten in der Klasse `rex_ycom_user` definiert. Diese können im Code verwendet werden, um die Lesbarkeit zu erhöhen:
	Seit Version 2.7 werden die Status-Werte als Konstanten in der Klasse `rex_ycom_user` definiert. Diese können im Code verwendet werden, um die Lesbarkeit zu erhöhen:

[AWqxKAWERbXo]

Von meiner Seite aus so vorbereitet, wie ich denke, dass es eine Verbesserung ist.