#3527544 - Improve Hook Alterations and Cache Metadata Handling in Markdownify Module

markdownify.api.php

@@ -5,6 +5,8 @@
  * Hooks specific to the Markdownify module.
  */
 
+use Drupal\Core\Render\BubbleableMetadata;
+
 /**
  * Alter the supported entity types for Markdown conversion.
  *
@@ -27,6 +29,31 @@ function hook_markdownify_supported_entity_types_alter(array &$supported_entity_
   }
 }
 
+/**
+ * Alter the render array of an entity before rendering to HTML.
+ *
+ * This hook allows other modules to modify the render array of an entity
+ * before it is rendered to HTML during Markdown transformation.
+ *
+ * @param array &$build
+ *   The render array for the entity.
+ * @param array $context
+ *   An associative array containing additional context:
+ *   - entity: The entity being rendered (\Drupal\Core\Entity\EntityInterface).
+ *   - view_mode: The view mode used to render the entity (string).
+ *   - langcode: The language code for rendering (string).
+ * @param \Drupal\Core\Render\BubbleableMetadata|null $metadata
+ *   (optional) Cacheable metadata for the rendering process.
+ */
+function hook_markdownify_entity_build_alter(array &$build, array $context, ?BubbleableMetadata $metadata): void {
+  // Example: Add a custom class to all entities of type 'node'.
+  $entity = $context['entity'];
+  // Example: Add metadata to cache tags for 'article' node bundles.
+  if ($entity->getEntityTypeId() === 'node' && $entity->bundle() === 'article' && $metadata) {
+    $metadata->addCacheTags(['custom_article_tag']);
+  }
+}
+
 /**
  * Alter the rendered HTML of an entity before conversion to Markdown.
  *
@@ -40,8 +67,10 @@ function hook_markdownify_supported_entity_types_alter(array &$supported_entity_
  *   - entity: The entity being converted (\Drupal\Core\Entity\EntityInterface).
  *   - view_mode: The view mode used to render the entity (string).
  *   - langcode: The language code of the entity's content (string).
+ * @param \Drupal\Core\Render\BubbleableMetadata|null $metadata
+ *   (optional) Cacheable metadata for the rendering process.
  */
-function hook_markdownify_entity_html_alter(string &$html, array $context): void {
+function hook_markdownify_entity_html_alter(string &$html, array $context, ?BubbleableMetadata $metadata): void {
   // Example: Add a custom wrapper around the HTML.
   $html = '<div class="custom-wrapper">' . $html . '</div>';
   // Example: Modify the HTML for a specific entity type.

src/Service/MarkdownifyEntityRenderer.php

@@ -76,15 +76,15 @@ class MarkdownifyEntityRenderer implements MarkdownifyEntityRendererInterface {
    */
   public function toHtml(EntityInterface $entity, string $view_mode = 'full', ?string $langcode = NULL, ?BubbleableMetadata $metadata = NULL): string {
     try {
-      // Set the render context.
+      // Set the render context to capture cacheable metadata.
       $context = new RenderContext();
       // Render entity in context and collect cacheable metadata.
-      $html = $this->renderer->executeInRenderContext($context, function () use ($entity, $view_mode, $langcode) {
-        return $this->renderEntity($entity, $view_mode, $langcode);
+      $html = $this->renderer->executeInRenderContext($context, function () use ($entity, $view_mode, $langcode, $metadata) {
+        return $this->renderEntity($entity, $view_mode, $langcode, $metadata);
       });
       // Merge any bubbled cacheable metadata.
       $this->applyCacheableMetadata($entity, $context, $metadata);
-      // Return the rendered output.
+      // Returns the fully rendered HTML output.
       return $html;
     }
     catch (\Exception $e) {
@@ -95,37 +95,46 @@ class MarkdownifyEntityRenderer implements MarkdownifyEntityRendererInterface {
   }
 
   /**
-   * Builds and renders the entity view array.
+   * Builds and renders the entity view array into an HTML string.
    *
-   * This method constructs the render array for the entity using the specified
-   * view mode and language, then renders it to an HTML string. Other modules
-   * can alter the final output using the 'markdownify_entity_html' alter hook.
+   * This method integrates with Drupal's rendering pipeline, invokes alter
+   * hooks for both render arrays and HTML strings, and ensures proper
+   * cache metadata handling.
    *
    * @param \Drupal\Core\Entity\EntityInterface $entity
    *   The entity to render.
    * @param string $view_mode
-   *   The view mode to use.
+   *   The view mode for rendering the entity.
    * @param string|null $langcode
-   *   The language code to render in.
+   *   (optional) The language code for rendering.
+   * @param \Drupal\Core\Render\BubbleableMetadata|null $metadata
+   *   (optional) Cacheable metadata for the rendering process.
    *
    * @return string
    *   The rendered HTML output.
    */
-  protected function renderEntity(EntityInterface $entity, string $view_mode, ?string $langcode): string {
+  protected function renderEntity(EntityInterface $entity, string $view_mode, ?string $langcode, ?BubbleableMetadata $metadata = NULL): string {
+    // Context for hook alterations.
+    $alter_context = [
+      'entity' => $entity,
+      'view_mode' => $view_mode,
+      'langcode' => $langcode,
+    ];
     // Obtain the appropriate view builder for the entity type.
     $view_builder = $this->entityTypeManager->getViewBuilder($entity->getEntityTypeId());
     // Build the render array for the entity.
     $build = $view_builder->view($entity, $view_mode, $langcode);
+    // Allow modules to alter the render array before rendering as HTML.
+    $this->moduleHandler->alter('markdownify_entity_build', $build, $alter_context, $metadata);
     // Render the build array into an HTML string.
-    $html = $this->renderer->render($build);
+    $html = $this->renderer->render($build, TRUE);
     // Allow modules to alter the rendered HTML output.
-    $alter_context = [
-      'entity' => $entity,
-      'view_mode' => $view_mode,
-      'langcode' => $langcode,
-    ];
-    $this->moduleHandler->alter('markdownify_entity_html', $html, $alter_context);
-    // Return the rendered output.
+    $this->moduleHandler->alter('markdownify_entity_html', $html, $alter_context, $metadata);
+    // Adds cacheable metadata to ensure proper caching of the rendered output.
+    if ($metadata instanceof BubbleableMetadata) {
+      $metadata->addCacheableDependency($build);
+    }
+    // Returns the fully rendered HTML output.
     return $html;
   }