Skip to content

Services

All services are in the Drupal\doc_to_html\Services namespace. Use dependency injection to get them.

Service id Class Interface Role
doc_to_html.conversion_manager ConversionManager ConversionManagerInterface Runs the whole conversion and returns a ConversionResult.
doc_to_html.cmd_service CmdService CmdServiceInterface Starts LibreOffice, returns the converted HTML file and reports the version.
doc_to_html.file_service FileService FileServiceInterface Working folders, source and image files, URIs and cleanup.
doc_to_html.markup_service MarkupService MarkupServiceInterface Body extraction, kept for code written against 2.0.1.
doc_to_html.default_service DefaultService Added in 2.1.0 Supported bundles, fields and file extensions.
doc_to_html.file_cleaner FileCleaner Added in 2.1.0 Cleanup of managed files.
logger.channel.doc_to_html LoggerChannel LoggerChannelInterface The doc_to_html log channel.

Convert a file

$result = $container->get('doc_to_html.conversion_manager')->convert($fid, [
  'apply_body_regex' => TRUE,
]);

if ($result->isSuccess()) {
  $html = $result->get('final_html');
}
else {
  $errors = $result->getErrors();
}

$fid is the id of a managed file entity. The options are the ones in Hooks and events.

ConversionResult

A final, read only value object.

Method Returns
isSuccess() bool.
getErrors() List of error messages. Empty on success.
getWarnings() List of warnings, for example a removed image.
get($key, $default) One data value.
getData() All data.

Data keys on success: raw_html, body_html, final_html, body_match_count, dom_match_count, dom_replaced and removed_heading. The last one is the text of the heading that the option remove_first_heading removed, an empty string if none.

Create results with ConversionResult::success() and ConversionResult::failure().

CmdServiceInterface

  • getLibreOfficeVersion(): ?string returns the version, or NULL if LibreOffice cannot be run.
  • convertToHtmlFile(string $sourceUri): ?string runs LibreOffice and returns the URI of the HTML file, or NULL on failure. New in 2.1.0. ConversionManager uses it.
  • convertFile(string $sourceUri, ?string $overrideBodyRegex = NULL, ?int $overrideBodyMatchIndex = NULL): ?string is deprecated in 2.1.0 and removed in 3.0.0. It keeps the contract of 2.0.1: it converts, applies the body regex through MarkupService and returns the HTML. For the whole chain use ConversionManager::convert(). Pass body_regex and body_match_index to it instead of the two parameters, which are deprecated too.

The process is started with proc_open() and an array of arguments, without a shell. Success needs exit code 0 and an .html file.

FileServiceInterface

  • getWorkingRoot() returns temporary://<folder>, the folder that holds the conversions.
  • createWorkingDirectory(bool $prepare = TRUE) returns temporary://<folder>/<uuid> for one conversion. With FALSE it only reserves the name.
  • deleteWorkingDirectory(string $uri, ?string $keepUri = NULL) deletes a conversion folder. Permanent files and files in use stay.
  • cleanFolder() removes the conversion folders untouched for six hours. See How the data flows.
  • storeSourceFile() moves a source document to the upload directory of a file field. The file stays temporary until the node is saved.
  • storeInlineImage() copies an image into a temporary managed file in the image directory.
  • findConvertedHtml() finds the HTML file that LibreOffice wrote.
  • cleanLegacyPublicFolder() and countLegacyPublicFiles() serve the update 8004 and the status report.
  • realPath() resolves a stream wrapper URI.
  • convertUriToHtml() returns the expected HTML URI for a source URI, for every extension, upper or lower case.
  • prepareDirectory() creates a directory inside temporary:// and returns its real path.
  • escapeRealPath() is deprecated and no longer called.

Stability

The interfaces keep the methods of 2.0.1. Parameters that are no longer used are marked @deprecated and not removed.

New methods in the interfaces

FileServiceInterface and CmdServiceInterface have new methods in 2.1.0. Code that only calls the services is not affected. If you implement either interface from scratch, add the new methods. If you extend the classes, nothing changes.

Calling the constructor of ConversionManager without the last three arguments, the module handler, the entity type manager and the file URL generator, is deprecated. Hooks are not invoked and images are not stored in that case.