1ca76a2e6SAndreas Gohr<?php 2ca76a2e6SAndreas Gohr 3*0fbee189SAndreas Gohruse dokuwiki\plugin\totext\Extractor\ExtractionResult; 4ca76a2e6SAndreas Gohruse dokuwiki\plugin\totext\Extractor\ExtractorFactory; 5ca76a2e6SAndreas Gohr 6ca76a2e6SAndreas Gohr/** 7ca76a2e6SAndreas Gohr * DokuWiki Plugin totext (Helper Component) 8ca76a2e6SAndreas Gohr * 9*0fbee189SAndreas Gohr * Gives other plugins a simple API to extract plain text and metadata from 10*0fbee189SAndreas Gohr * documents. 11ca76a2e6SAndreas Gohr * 12ca76a2e6SAndreas Gohr * @license GPL-2.0-only 13ca76a2e6SAndreas Gohr * @author Andreas Gohr <gohr@cosmocode.de> 14ca76a2e6SAndreas Gohr */ 15ca76a2e6SAndreas Gohrclass helper_plugin_totext extends \dokuwiki\Extension\Plugin 16ca76a2e6SAndreas Gohr{ 17ca76a2e6SAndreas Gohr /** 18*0fbee189SAndreas Gohr * Extract body text and metadata from the given file. 19*0fbee189SAndreas Gohr * 20*0fbee189SAndreas Gohr * @param string $path absolute path to the file 21*0fbee189SAndreas Gohr * @return ExtractionResult the extracted body text and canonical metadata 22*0fbee189SAndreas Gohr * @throws \dokuwiki\plugin\totext\Exception\ExtractionException on failure 23*0fbee189SAndreas Gohr * @throws \dokuwiki\plugin\totext\Exception\UnsupportedFormatException on unsupported format 24*0fbee189SAndreas Gohr */ 25*0fbee189SAndreas Gohr public function extract($path) 26*0fbee189SAndreas Gohr { 27*0fbee189SAndreas Gohr return ExtractorFactory::extract($path); 28*0fbee189SAndreas Gohr } 29*0fbee189SAndreas Gohr 30*0fbee189SAndreas Gohr /** 31ca76a2e6SAndreas Gohr * Extract plain text from the given file. 32ca76a2e6SAndreas Gohr * 33*0fbee189SAndreas Gohr * Unlike extract(), this throws when text extraction itself failed (even if 34*0fbee189SAndreas Gohr * metadata was salvaged), so callers that want only the text — e.g. the 35*0fbee189SAndreas Gohr * docsearch plugin, which falls back to its own converters on failure — keep 36*0fbee189SAndreas Gohr * their throw-on-failure contract. 37*0fbee189SAndreas Gohr * 38ca76a2e6SAndreas Gohr * @param string $path absolute path to the file 39ca76a2e6SAndreas Gohr * @return string the extracted plain text 40ca76a2e6SAndreas Gohr * @throws \dokuwiki\plugin\totext\Exception\ExtractionException on failure 41ca76a2e6SAndreas Gohr * @throws \dokuwiki\plugin\totext\Exception\UnsupportedFormatException on unsupported format 42ca76a2e6SAndreas Gohr */ 43ca76a2e6SAndreas Gohr public function extractText($path) 44ca76a2e6SAndreas Gohr { 45*0fbee189SAndreas Gohr $result = $this->extract($path); 46*0fbee189SAndreas Gohr if ($result->textError !== null) { 47*0fbee189SAndreas Gohr throw $result->textError; 48*0fbee189SAndreas Gohr } 49*0fbee189SAndreas Gohr return $result->text; 50*0fbee189SAndreas Gohr } 51*0fbee189SAndreas Gohr 52*0fbee189SAndreas Gohr /** 53*0fbee189SAndreas Gohr * Extract the canonical metadata map from the given file. 54*0fbee189SAndreas Gohr * 55*0fbee189SAndreas Gohr * Throws when metadata extraction itself failed (even if the body text was 56*0fbee189SAndreas Gohr * extracted), mirroring extractText(). 57*0fbee189SAndreas Gohr * 58*0fbee189SAndreas Gohr * @param string $path absolute path to the file 59*0fbee189SAndreas Gohr * @return array<string, string> canonical key => value map 60*0fbee189SAndreas Gohr * @throws \dokuwiki\plugin\totext\Exception\ExtractionException on failure 61*0fbee189SAndreas Gohr * @throws \dokuwiki\plugin\totext\Exception\UnsupportedFormatException on unsupported format 62*0fbee189SAndreas Gohr */ 63*0fbee189SAndreas Gohr public function extractMetadata($path) 64*0fbee189SAndreas Gohr { 65*0fbee189SAndreas Gohr $result = $this->extract($path); 66*0fbee189SAndreas Gohr if ($result->metadataError !== null) { 67*0fbee189SAndreas Gohr throw $result->metadataError; 68*0fbee189SAndreas Gohr } 69*0fbee189SAndreas Gohr return $result->metadata; 70ca76a2e6SAndreas Gohr } 71ca76a2e6SAndreas Gohr 72ca76a2e6SAndreas Gohr /** 73ca76a2e6SAndreas Gohr * List the file extensions this plugin can handle. 74ca76a2e6SAndreas Gohr * 75ca76a2e6SAndreas Gohr * @return string[] supported extensions (without leading dot) 76ca76a2e6SAndreas Gohr */ 77ca76a2e6SAndreas Gohr public function supportedExtensions() 78ca76a2e6SAndreas Gohr { 79ca76a2e6SAndreas Gohr return ExtractorFactory::supportedExtensions(); 80ca76a2e6SAndreas Gohr } 81ca76a2e6SAndreas Gohr 82ca76a2e6SAndreas Gohr /** 83ca76a2e6SAndreas Gohr * Whether the given file is supported, based on its extension. 84ca76a2e6SAndreas Gohr * 85ca76a2e6SAndreas Gohr * @param string $path file name or path 86ca76a2e6SAndreas Gohr * @return bool 87ca76a2e6SAndreas Gohr */ 88ca76a2e6SAndreas Gohr public function isSupported($path) 89ca76a2e6SAndreas Gohr { 90ca76a2e6SAndreas Gohr return in_array( 91ca76a2e6SAndreas Gohr strtolower(pathinfo($path, PATHINFO_EXTENSION)), 92ca76a2e6SAndreas Gohr $this->supportedExtensions(), 93ca76a2e6SAndreas Gohr true 94ca76a2e6SAndreas Gohr ); 95ca76a2e6SAndreas Gohr } 96ca76a2e6SAndreas Gohr} 97