<?php

declare(strict_types=1);

namespace backend\traits;

/**
 * StatusManagementTrait provides common status management functionality.
 * 
 * This trait adds status-related methods for models that use a 'status' field
 * with common values like 'Active', 'Inactive', 'Deleted', etc.
 * 
 * Usage:
 * ```php
 * class MyModel extends ActiveRecord
 * {
 *     use StatusManagementTrait;
 * }
 * 
 * $model->activate();
 * $model->deactivate();
 * if ($model->isActive()) { ... }
 * ```
 * 
 * @author Andrew Pickstock
 * @since 1.0
 */
trait StatusManagementTrait
{
    /**
     * Status constants
     */
    public const STATUS_ACTIVE = 'Active';
    public const STATUS_INACTIVE = 'Inactive';
    public const STATUS_DELETED = 'Deleted';
    public const STATUS_PENDING = 'Pending';
    public const STATUS_SUSPENDED = 'Suspended';
    
    /**
     * Gets all available status values.
     * 
     * @return array<string, string> Status values
     */
    public static function getStatusList(): array
    {
        return [
            self::STATUS_ACTIVE => 'Active',
            self::STATUS_INACTIVE => 'Inactive',
            self::STATUS_DELETED => 'Deleted',
            self::STATUS_PENDING => 'Pending',
            self::STATUS_SUSPENDED => 'Suspended',
        ];
    }
    
    /**
     * Checks if the record is active.
     * 
     * @return bool
     */
    public function isActive(): bool
    {
        return $this->status === self::STATUS_ACTIVE;
    }
    
    /**
     * Checks if the record is inactive.
     * 
     * @return bool
     */
    public function isInactive(): bool
    {
        return $this->status === self::STATUS_INACTIVE;
    }
    
    /**
     * Checks if the record is deleted.
     * 
     * @return bool
     */
    public function isDeleted(): bool
    {
        return $this->status === self::STATUS_DELETED;
    }
    
    /**
     * Checks if the record is pending.
     * 
     * @return bool
     */
    public function isPending(): bool
    {
        return $this->status === self::STATUS_PENDING;
    }
    
    /**
     * Checks if the record is suspended.
     * 
     * @return bool
     */
    public function isSuspended(): bool
    {
        return $this->status === self::STATUS_SUSPENDED;
    }
    
    /**
     * Activates the record.
     * 
     * @param bool $save Whether to save the model immediately
     * @return bool Success status
     */
    public function activate(bool $save = true): bool
    {
        $this->status = self::STATUS_ACTIVE;
        return $save ? $this->save(false, ['status']) : true;
    }
    
    /**
     * Deactivates the record.
     * 
     * @param bool $save Whether to save the model immediately
     * @return bool Success status
     */
    public function deactivate(bool $save = true): bool
    {
        $this->status = self::STATUS_INACTIVE;
        return $save ? $this->save(false, ['status']) : true;
    }
    
    /**
     * Soft deletes the record by setting status to deleted.
     * 
     * @param bool $save Whether to save the model immediately
     * @return bool Success status
     */
    public function softDelete(bool $save = true): bool
    {
        $this->status = self::STATUS_DELETED;
        return $save ? $this->save(false, ['status']) : true;
    }
    
    /**
     * Sets status to pending.
     * 
     * @param bool $save Whether to save the model immediately
     * @return bool Success status
     */
    public function setPending(bool $save = true): bool
    {
        $this->status = self::STATUS_PENDING;
        return $save ? $this->save(false, ['status']) : true;
    }
    
    /**
     * Suspends the record.
     * 
     * @param bool $save Whether to save the model immediately
     * @return bool Success status
     */
    public function suspend(bool $save = true): bool
    {
        $this->status = self::STATUS_SUSPENDED;
        return $save ? $this->save(false, ['status']) : true;
    }
    
    /**
     * Gets a CSS class name for the status badge.
     * 
     * @return string CSS class name
     */
    public function getStatusBadgeClass(): string
    {
        return match($this->status) {
            self::STATUS_ACTIVE => 'badge-success',
            self::STATUS_INACTIVE => 'badge-secondary',
            self::STATUS_DELETED => 'badge-danger',
            self::STATUS_PENDING => 'badge-warning',
            self::STATUS_SUSPENDED => 'badge-dark',
            default => 'badge-light',
        };
    }
    
    /**
     * Gets a human-readable status label.
     * 
     * @return string Status label
     */
    public function getStatusLabel(): string
    {
        return self::getStatusList()[$this->status] ?? $this->status;
    }
}
