<?php

declare(strict_types=1);

namespace App\Framework\Performance\Contracts;

use App\Framework\Performance\PerformanceCategory;
use App\Framework\Performance\PerformanceMetric;

interface PerformanceCollectorInterface
{
    /**
     * Start timing an operation
     */
    public function startTiming(string $key, PerformanceCategory $category, array $context = []): void;

    /**
     * End timing an operation
     */
    public function endTiming(string $key): void;

    /**
     * Measure a callable's execution time and memory usage
     */
    public function measure(string $key, PerformanceCategory $category, callable $callback, array $context = []): mixed;

    /**
     * Record a metric value
     */
    public function recordMetric(string $key, PerformanceCategory $category, float $value, array $context = []): void;

    /**
     * Increment a counter
     */
    public function increment(string $key, PerformanceCategory $category, int $amount = 1, array $context = []): void;

    /**
     * Get all metrics, optionally filtered by category
     *
     * @return array<string, PerformanceMetric>
     */
    public function getMetrics(?PerformanceCategory $category = null): array;

    /**
     * Get a specific metric by key
     */
    public function getMetric(string $key): ?PerformanceMetric;

    /**
     * Get total request time in milliseconds
     */
    public function getTotalRequestTime(): float;

    /**
     * Get total request memory usage in bytes
     */
    public function getTotalRequestMemory(): int;

    /**
     * Get peak memory usage in bytes
     */
    public function getPeakMemory(): int;

    /**
     * Reset all collected metrics
     */
    public function reset(): void;

    /**
     * Check if performance tracking is enabled
     */
    public function isEnabled(): bool;

    /**
     * Enable or disable performance tracking
     */
    public function setEnabled(bool $enabled): void;
}