michaelschiemer/docs/discovery-filesystem-integration.md

Integration von Discovery und Filesystem Modulen

Dieses Dokument beschreibt die Integration des Discovery-Moduls mit dem Filesystem-Modul, um Codeduplizierung zu reduzieren, die Robustheit zu verbessern und erweiterte Funktionen zu nutzen.

Überblick

Die Integration umfasst folgende Komponenten:

1. FileMetadata: Eine erweiterte FileMetadata-Klasse im Filesystem-Modul, die Core Value Objects nutzt
2. DiscoveryStorage: Ein spezialisiertes Storage-Interface für Discovery-Operationen
3. FileSystemDiscoveryStorage: Eine Implementierung des DiscoveryStorage-Interfaces
4. FileScannerService: Der bestehende Service, aktualisiert für die Nutzung des Filesystem-Moduls
5. FileScannerServiceBootstrapper: Ein Bootstrapper für den FileScannerService
6. UnifiedDiscoveryService: Der bestehende Service, aktualisiert für die Nutzung des FileScannerServiceBootstrapper

Vorteile der Integration

• Vermeidung von Code-Duplizierung: Einheitliche Abstraktion für Dateisystem-Operationen
• Verbesserte Robustheit: Konsistente Fehlerbehandlung und Ausnahmen
• Leistungsoptimierung: Nutzung von Batch- und Async-Funktionen des Filesystem-Moduls
• Bessere Testbarkeit: Einheitliche Mocking-Strategie für Dateisystem-Operationen
• Erweiterte Funktionalität: Zugriff auf fortschrittliche Features wie Dateisystem-Events

Komponenten im Detail

FileMetadata

Die erweiterte FileMetadata-Klasse im Filesystem-Modul vereint die Funktionalität der vorherigen FileMetadata-Klassen und nutzt Core-ValueObjects für eine robustere Implementierung.

namespace App\Framework\Filesystem;

use App\Framework\Core\ValueObjects\Byte;
use App\Framework\Core\ValueObjects\Hash;
use App\Framework\Core\ValueObjects\HashAlgorithm;
use App\Framework\Core\ValueObjects\Timestamp;

final readonly class FileMetadata
{
    public function __construct(
        public FilePath|string $path = '',
        public Byte|int $size = 0,
        public Timestamp|int $lastModified = 0,
        public ?Hash $checksum = null,
        public ?Timestamp $scanTime = null,
        public string $mimeType = '',
        public bool $isReadable = false,
        public bool $isWritable = false,
        public array $additionalData = []
    ) {
    }
    
    // Methoden für Erstellung, Konvertierung, Prüfung auf Änderungen, etc.
}

DiscoveryStorage Interface

Das DiscoveryStorage-Interface erweitert das Standard-Storage-Interface mit Discovery-spezifischen Methoden.

namespace App\Framework\Discovery\Storage;

use App\Framework\Filesystem\Storage;
use App\Framework\Filesystem\FileMetadata;
use SplFileInfo;

interface DiscoveryStorage extends Storage
{
    /**
     * Findet geänderte Dateien seit dem letzten Scan
     */
    public function findChangedFiles(string $directory, array $fileMetadata): array;
    
    /**
     * Führt einen inkrementellen Scan durch
     */
    public function incrementalScan(string $directory, array $fileMetadata): array;
    
    /**
     * Findet alle Dateien mit einem bestimmten Muster
     */
    public function findFiles(string $directory, string $pattern): array;
    
    /**
     * Erstellt Metadaten für eine Datei
     */
    public function getDiscoveryMetadata(string $filePath, bool $calculateChecksum = true): FileMetadata;
    
    /**
     * Erstellt Metadaten für mehrere Dateien parallel
     */
    public function getDiscoveryMetadataMultiple(array $filePaths, bool $calculateChecksum = true): array;
    
    /**
     * Registriert Dateisystem-Events für Änderungserkennung
     */
    public function registerFileSystemEvents(string $directory, callable $callback): bool;
}

FileSystemDiscoveryStorage

Die FileSystemDiscoveryStorage-Klasse implementiert das DiscoveryStorage-Interface und delegiert Standard-Storage-Operationen an eine zugrundeliegende Storage-Implementierung.

namespace App\Framework\Discovery\Storage;

use App\Framework\Async\FiberManager;
use App\Framework\Filesystem\File;
use App\Framework\Filesystem\Directory;
use App\Framework\Filesystem\FileMetadata;
use App\Framework\Filesystem\PermissionChecker;
use App\Framework\Filesystem\Storage;
use SplFileInfo;

final class FileSystemDiscoveryStorage implements DiscoveryStorage
{
    /**
     * @param Storage $storage Basis-Storage-Implementierung für Delegation
     * @param PermissionChecker $permissions Permissions-Checker
     * @param FiberManager $fiberManager Fiber-Manager für asynchrone Operationen
     */
    public function __construct(
        private readonly Storage $storage,
        public readonly PermissionChecker $permissions = new PermissionChecker(),
        public readonly FiberManager $fiberManager = new FiberManager()
    ) {
    }
    
    // Implementierung der Storage-Methoden durch Delegation
    
    /**
     * {@inheritdoc}
     */
    public function getDiscoveryMetadata(string $filePath, bool $calculateChecksum = true): FileMetadata
    {
        return FileMetadata::fromFile($filePath, $this, $calculateChecksum);
    }
    
    // Weitere Implementierungen der Discovery-spezifischen Methoden
}

FileScannerService

Der FileScannerService wurde aktualisiert, um das DiscoveryStorage-Interface zu nutzen, wenn verfügbar, mit Fallback auf die alte Implementierung für Abwärtskompatibilität.

namespace App\Framework\Discovery;

use App\Framework\Discovery\Storage\DiscoveryStorage;

final class FileScannerService
{
    public function __construct(
        private readonly FileScannerInterface $fileScanner,
        private readonly PathProvider $pathProvider,
        private readonly Cache $cache,
        private readonly bool $useCache = true,
        // weitere Parameter
        private readonly ?DiscoveryStorage $storage = null
    ) {
        // Initialisierung
    }
    
    // Methoden für Scanning, Verarbeitung, Caching, etc.
    // mit Nutzung von DiscoveryStorage wenn verfügbar
}

FileScannerServiceBootstrapper

Der FileScannerServiceBootstrapper erstellt und konfiguriert den FileScannerService mit den richtigen Abhängigkeiten.

namespace App\Framework\Discovery;

use App\Framework\Filesystem\FilesystemManager;

final class FileScannerServiceBootstrapper
{
    public function __construct(
        private readonly FilesystemManager $filesystemManager,
        // weitere Parameter
    ) {
    }
    
    public function create(
        bool $useCache = true,
        // weitere Parameter
    ): FileScannerService {
        // Erstelle DiscoveryStorage und FileScannerService
    }
    
    public static function createDefault(
        FilesystemManager $filesystemManager,
        // weitere Parameter
    ): FileScannerService {
        // Factory-Methode für einfache Erstellung
    }
}

UnifiedDiscoveryService

Der UnifiedDiscoveryService wurde aktualisiert, um den FileScannerServiceBootstrapper zu nutzen.

namespace App\Framework\Discovery;

use App\Framework\Filesystem\FilesystemManager;

final readonly class UnifiedDiscoveryService
{
    public function __construct(
        FilesystemManager $filesystemManager,
        // weitere Parameter
    ) {
        // Erstelle FileScannerService mit Bootstrapper
    }
    
    // Methoden für Discovery, Caching, Health-Checks, etc.
}

Verwendung

Einfache Verwendung mit Standard-Konfiguration

// Container-Konfiguration
$container->singleton(UnifiedDiscoveryService::class, function (Container $container) {
    return new UnifiedDiscoveryService(
        $container->get(FilesystemManager::class),
        $container->get(PathProvider::class),
        $container->get(Cache::class),
        $container->get(Clock::class),
        // weitere Parameter mit Standardwerten
    );
});

// Verwendung
$discoveryService = $container->get(UnifiedDiscoveryService::class);
$results = $discoveryService->discover();

Erweiterte Konfiguration

// Manuelle Erstellung mit angepasster Konfiguration
$bootstrapper = new FileScannerServiceBootstrapper(
    $filesystemManager,
    $pathProvider,
    $cache,
    $logger
);

$fileScannerService = $bootstrapper->create(
    useCache: true,
    asyncProcessing: true,
    chunkSize: 200,
    maxRetries: 5,
    enableAdaptiveChunking: true,
    storageName: 'custom_storage'
);

// Verwendung des FileScannerService direkt
$fileScannerService->scan(true); // mit Fortschrittsanzeige

Verwendung des DiscoveryStorage direkt

// Erstelle DiscoveryStorage
$storage = new FileSystemDiscoveryStorage(
    $filesystemManager->storage('default')
);

// Finde geänderte Dateien
$changedFiles = $storage->findChangedFiles('/path/to/directory', $existingMetadata);

// Hole Metadaten für eine Datei
$metadata = $storage->getDiscoveryMetadata('/path/to/file.php', true);

// Hole Metadaten für mehrere Dateien parallel
$metadataMap = $storage->getDiscoveryMetadataMultiple([
    '/path/to/file1.php',
    '/path/to/file2.php',
    '/path/to/file3.php'
]);

Fazit

Die Integration des Discovery-Moduls mit dem Filesystem-Modul bietet zahlreiche Vorteile in Bezug auf Codeduplizierung, Robustheit, Leistung und Funktionalität. Die Implementierung ist abwärtskompatibel, sodass bestehender Code weiterhin funktioniert, während neue Code die verbesserte Funktionalität nutzen kann.