xref: /plugin/totext/Extractor/ExtractionResult.php (revision 0fbee1892eb8b7339ce48e27e48e3fc821a8695f) 
1<?php
2
3namespace dokuwiki\plugin\totext\Extractor;
4
5/**
6 * Immutable result of a single extraction: the body text plus a normalised
7 * metadata map, each with its own success/failure status.
8 *
9 * Every extractor produces both halves from one parse of the file. The metadata
10 * keys are a single canonical vocabulary shared across all formats, so consumers
11 * never have to special-case the source format:
12 *
13 *   Title, Author, Subject, Keywords, Description, Created, Modified,
14 *   Language, Producer (all formats) plus Copyright (image-only).
15 *
16 * Values are non-empty UTF-8 strings; empty values are dropped by the
17 * extractor rather than stored as blank keys.
18 *
19 * Text and metadata are extracted independently, so one half can fail while the
20 * other succeeds (e.g. a document whose body part is missing but whose metadata
21 * part is intact). A failed half carries its error in $textError / $metadataError
22 * and the corresponding output is left empty; the salvaged half is still
23 * returned. extract() only throws when *nothing* is recoverable (see the
24 * extractors). An output that is empty *by design* — an image has no body text,
25 * plain text has no metadata — is not a failure and leaves its error null.
26 */
27final class ExtractionResult
28{
29    /**
30     * @param string $text the extracted body text ('' if absent or failed)
31     * @param array<string, string> $metadata canonical key => value map
32     * @param \Throwable|null $textError why text extraction failed, or null on success
33     * @param \Throwable|null $metadataError why metadata extraction failed, or null on success
34     */
35    public function __construct(
36        public readonly string $text,
37        public readonly array $metadata = [],
38        public readonly ?\Throwable $textError = null,
39        public readonly ?\Throwable $metadataError = null,
40    ) {
41    }
42
43    /**
44     * Whether both halves were extracted without error.
45     *
46     * Note this reports the absence of *failure*, not the presence of content:
47     * a result can be complete yet have empty text or empty metadata when the
48     * file simply carried none.
49     *
50     * @return bool
51     */
52    public function isComplete(): bool
53    {
54        return $this->textError === null && $this->metadataError === null;
55    }
56}
57