care-book-block-ultimate/src/Security/ValidationLayerResult.php

<?php
/**
 * Validation Layer Result - Individual Security Layer Result Container
 * 
 * Holds results from individual security validation layers
 * 
 * @package CareBook\Ultimate\Security
 * @since 1.0.0
 */

declare(strict_types=1);

namespace CareBook\Ultimate\Security;

/**
 * Validation Layer Result
 * 
 * Contains results from individual security validation layer
 * 
 * @since 1.0.0
 */
final class ValidationLayerResult
{
    /** @var bool Layer validation result */
    private bool $valid = false;
    
    /** @var string Error message if validation failed */
    private string $error = '';
    
    /** @var array<string, mixed> Layer metadata */
    private array $metadata = [];
    
    /** @var array<string> Layer warnings */
    private array $warnings = [];
    
    /** @var array<string, mixed> Sanitized data from this layer */
    private array $sanitizedData = [];
    
    /** @var string Layer name/identifier */
    private string $layerName = '';
    
    /**
     * Set validation result
     * 
     * @param bool $valid Whether validation passed
     * @return void
     * @since 1.0.0
     */
    public function setValid(bool $valid): void
    {
        $this->valid = $valid;
    }
    
    /**
     * Check if validation passed
     * 
     * @return bool
     * @since 1.0.0
     */
    public function isValid(): bool
    {
        return $this->valid;
    }
    
    /**
     * Set error message
     * 
     * @param string $error Error message
     * @return void
     * @since 1.0.0
     */
    public function setError(string $error): void
    {
        $this->error = $error;
    }
    
    /**
     * Get error message
     * 
     * @return string
     * @since 1.0.0
     */
    public function getError(): string
    {
        return $this->error;
    }
    
    /**
     * Set metadata
     * 
     * @param array<string, mixed> $metadata Metadata array
     * @return void
     * @since 1.0.0
     */
    public function setMetadata(array $metadata): void
    {
        $this->metadata = $metadata;
    }
    
    /**
     * Get metadata
     * 
     * @return array<string, mixed>
     * @since 1.0.0
     */
    public function getMetadata(): array
    {
        return $this->metadata;
    }
    
    /**
     * Add metadata item
     * 
     * @param string $key Metadata key
     * @param mixed $value Metadata value
     * @return void
     * @since 1.0.0
     */
    public function addMetadata(string $key, mixed $value): void
    {
        $this->metadata[$key] = $value;
    }
    
    /**
     * Add warning
     * 
     * @param string $warning Warning message
     * @return void
     * @since 1.0.0
     */
    public function setWarning(string $warning): void
    {
        $this->warnings[] = $warning;
    }
    
    /**
     * Add warning
     * 
     * @param string $warning Warning message
     * @return void
     * @since 1.0.0
     */
    public function addWarning(string $warning): void
    {
        $this->warnings[] = $warning;
    }
    
    /**
     * Get warnings
     * 
     * @return array<string>
     * @since 1.0.0
     */
    public function getWarnings(): array
    {
        return $this->warnings;
    }
    
    /**
     * Check if result has warnings
     * 
     * @return bool
     * @since 1.0.0
     */
    public function hasWarnings(): bool
    {
        return !empty($this->warnings);
    }
    
    /**
     * Set sanitized data
     * 
     * @param array<string, mixed> $data Sanitized data
     * @return void
     * @since 1.0.0
     */
    public function setSanitizedData(array $data): void
    {
        $this->sanitizedData = $data;
    }
    
    /**
     * Get sanitized data
     * 
     * @return array<string, mixed>
     * @since 1.0.0
     */
    public function getSanitizedData(): array
    {
        return $this->sanitizedData;
    }
    
    /**
     * Set layer name
     * 
     * @param string $name Layer name
     * @return void
     * @since 1.0.0
     */
    public function setLayerName(string $name): void
    {
        $this->layerName = $name;
    }
    
    /**
     * Get layer name
     * 
     * @return string
     * @since 1.0.0
     */
    public function getLayerName(): string
    {
        return $this->layerName;
    }
    
    /**
     * Convert result to array
     * 
     * @return array<string, mixed>
     * @since 1.0.0
     */
    public function toArray(): array
    {
        return [
            'valid' => $this->valid,
            'error' => $this->error,
            'warnings' => $this->warnings,
            'metadata' => $this->metadata,
            'sanitized_data' => $this->sanitizedData,
            'layer_name' => $this->layerName
        ];
    }
    
    /**
     * Create successful result
     * 
     * @param array<string, mixed> $metadata Optional metadata
     * @return self
     * @since 1.0.0
     */
    public static function success(array $metadata = []): self
    {
        $result = new self();
        $result->setValid(true);
        $result->setMetadata($metadata);
        return $result;
    }
    
    /**
     * Create failed result
     * 
     * @param string $error Error message
     * @param array<string, mixed> $metadata Optional metadata
     * @return self
     * @since 1.0.0
     */
    public static function failure(string $error, array $metadata = []): self
    {
        $result = new self();
        $result->setValid(false);
        $result->setError($error);
        $result->setMetadata($metadata);
        return $result;
    }
    
    /**
     * Create result with warning
     * 
     * @param string $warning Warning message
     * @param array<string, mixed> $metadata Optional metadata
     * @return self
     * @since 1.0.0
     */
    public static function warning(string $warning, array $metadata = []): self
    {
        $result = new self();
        $result->setValid(true);
        $result->addWarning($warning);
        $result->setMetadata($metadata);
        return $result;
    }
    
    /**
     * Merge with another layer result
     * 
     * @param ValidationLayerResult $other Other result to merge
     * @return self New merged result
     * @since 1.0.0
     */
    public function merge(ValidationLayerResult $other): self
    {
        $merged = new self();
        
        // Both must be valid for merged result to be valid
        $merged->setValid($this->valid && $other->isValid());
        
        // Combine errors
        $errors = array_filter([$this->error, $other->getError()]);
        $merged->setError(implode('; ', $errors));
        
        // Combine warnings
        $merged->warnings = array_merge($this->warnings, $other->getWarnings());
        
        // Merge metadata
        $merged->setMetadata(array_merge($this->metadata, $other->getMetadata()));
        
        // Merge sanitized data
        $merged->setSanitizedData(array_merge($this->sanitizedData, $other->getSanitizedData()));
        
        return $merged;
    }
    
    /**
     * Check if result is acceptable (valid or has only warnings)
     * 
     * @return bool
     * @since 1.0.0
     */
    public function isAcceptable(): bool
    {
        return $this->valid || (!$this->valid && !empty($this->warnings) && empty($this->error));
    }
}