Add markdown parser extension system via MarkdownExtensionRecipe (#7)

Author: Copilot

packages/sprinkle-core/app/src/Core.php

@@ -14,6 +14,9 @@
 
 use Lcharette\WebpackEncoreTwig\EntrypointsTwigExtension;
 use Lcharette\WebpackEncoreTwig\VersionedAssetsTwigExtension;
+use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
+use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
+use League\CommonMark\Extension\GithubFlavoredMarkdownExtension;
 use UserFrosting\Event\AppInitiatedEvent;
 use UserFrosting\Event\BakeryInitiatedEvent;
 use UserFrosting\Event\EventListenerRecipe;
@@ -90,6 +93,7 @@
 use UserFrosting\Sprinkle\Core\ServicesProvider\VersionsService;
 use UserFrosting\Sprinkle\Core\ServicesProvider\ViteService;
 use UserFrosting\Sprinkle\Core\ServicesProvider\WebpackService;
+use UserFrosting\Sprinkle\Core\Sprinkle\Recipe\MarkdownExtensionRecipe;
 use UserFrosting\Sprinkle\Core\Sprinkle\Recipe\MigrationRecipe;
 use UserFrosting\Sprinkle\Core\Sprinkle\Recipe\TwigExtensionRecipe;
 use UserFrosting\Sprinkle\Core\Twig\Extensions\AlertsExtension;
@@ -106,6 +110,7 @@
 class Core implements
     SprinkleRecipe,
     TwigExtensionRecipe,
+    MarkdownExtensionRecipe,
     MigrationRecipe,
     EventListenerRecipe,
     MiddlewareRecipe,
@@ -271,6 +276,20 @@ public function getTwigExtensions(): array
         ];
     }
 
+    /**
+     * Return an array of all registered Markdown Extensions.
+     *
+     * {@inheritDoc}
+     */
+    public function getMarkdownExtensions(): array
+    {
+        return [
+            CommonMarkCoreExtension::class,
+            FrontMatterExtension::class,
+            GithubFlavoredMarkdownExtension::class,
+        ];
+    }
+
     /**
      * Return an array of all registered Migrations.
      *

packages/sprinkle-core/app/src/Markdown/MarkdownRepositoryInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * UserFrosting Core Sprinkle (http://www.userfrosting.com)
+ *
+ * @link      https://github.com/userfrosting/sprinkle-core
+ * @copyright Copyright (c) 2013-2024 Alexander Weissman & Louis Charette
+ * @license   https://github.com/userfrosting/sprinkle-core/blob/master/LICENSE.md (MIT License)
+ */
+
+namespace UserFrosting\Sprinkle\Core\Markdown;
+
+use League\CommonMark\Extension\ExtensionInterface;
+use UserFrosting\Support\ClassRepositoryInterface;
+
+/**
+ * Markdown Extensions Repository Interface.
+ *
+ * @extends ClassRepositoryInterface<ExtensionInterface>
+ */
+interface MarkdownRepositoryInterface extends ClassRepositoryInterface
+{
+}

packages/sprinkle-core/app/src/Markdown/SprinkleMarkdownRepository.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * UserFrosting Core Sprinkle (http://www.userfrosting.com)
+ *
+ * @link      https://github.com/userfrosting/sprinkle-core
+ * @copyright Copyright (c) 2013-2024 Alexander Weissman & Louis Charette
+ * @license   https://github.com/userfrosting/sprinkle-core/blob/master/LICENSE.md (MIT License)
+ */
+
+namespace UserFrosting\Sprinkle\Core\Markdown;
+
+use League\CommonMark\Extension\ExtensionInterface;
+use Psr\Container\ContainerInterface;
+use UserFrosting\Sprinkle\Core\Sprinkle\Recipe\MarkdownExtensionRecipe;
+use UserFrosting\Sprinkle\SprinkleManager;
+use UserFrosting\Support\ClassRepository;
+use UserFrosting\Support\Exception\BadClassNameException;
+use UserFrosting\Support\Exception\BadInstanceOfException;
+
+/**
+ * Find and returns all registered ExtensionInterface across all sprinkles, using MarkdownExtensionRecipe.
+ *
+ * @extends ClassRepository<ExtensionInterface>
+ */
+final class SprinkleMarkdownRepository extends ClassRepository implements MarkdownRepositoryInterface
+{
+    /**
+     * @param SprinkleManager    $sprinkleManager
+     * @param ContainerInterface $ci
+     */
+    public function __construct(
+        protected SprinkleManager $sprinkleManager,
+        protected ContainerInterface $ci
+    ) {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function all(): array
+    {
+        $instances = [];
+
+        foreach ($this->sprinkleManager->getSprinkles() as $sprinkle) {
+            if (!$sprinkle instanceof MarkdownExtensionRecipe) {
+                continue;
+            }
+            foreach ($sprinkle->getMarkdownExtensions() as $extensionClass) {
+                if (!class_exists($extensionClass)) {
+                    throw new BadClassNameException("Extension class `$extensionClass` not found.");
+                }
+                $instance = $this->ci->get($extensionClass);
+                if (!is_object($instance) || !is_subclass_of($instance, ExtensionInterface::class)) {
+                    throw new BadInstanceOfException("Extension class `$extensionClass` doesn't implement " . ExtensionInterface::class . '.');
+                }
+                $instances[] = $instance;
+            }
+        }
+
+        return $instances;
+    }
+}

packages/sprinkle-core/app/src/ServicesProvider/MarkdownService.php

@@ -14,39 +14,53 @@
 
 use League\CommonMark\ConverterInterface;
 use League\CommonMark\Environment\Environment;
-use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
-use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
-use League\CommonMark\Extension\GithubFlavoredMarkdownExtension;
 use League\CommonMark\MarkdownConverter;
 use UserFrosting\Config\Config;
 use UserFrosting\ServicesProvider\ServicesProviderInterface;
+use UserFrosting\Sprinkle\Core\Markdown\MarkdownRepositoryInterface;
+use UserFrosting\Sprinkle\Core\Markdown\SprinkleMarkdownRepository;
 
 /**
  * Markdown service. Add CommonMark markdown parser with GitHub Flavored Markdown frontmatter support.
  *
- * @see https://commonmark.thephpleague.com
+ * Sprinkles can register custom markdown extensions by implementing the MarkdownExtensionRecipe interface.
  *
- * TODO : Should have a way to extend the markdown parser with custom extensions.
+ * @see https://commonmark.thephpleague.com
  */
 class MarkdownService implements ServicesProviderInterface
 {
     public function register(): array
     {
         return [
-            ConverterInterface::class => function (Config $config) {
+            ConverterInterface::class => function (Config $config, MarkdownRepositoryInterface $extensionLoader) {
                 // Get markdown configuration from config service
                 $markdownConfig = $config->get('markdown', []);
 
                 $environment = new Environment($markdownConfig);
-                $environment->addExtension(new CommonMarkCoreExtension());
-                $environment->addExtension(new FrontMatterExtension());
-                $environment->addExtension(new GithubFlavoredMarkdownExtension());
+
+                // Register markdown extensions from sprinkles
+                $this->registerMarkdownExtensions($environment, $extensionLoader);
 
                 // Instantiate the converter engine and start converting some Markdown!
                 $converter = new MarkdownConverter($environment);
 
                 return $converter;
             },
+
+            MarkdownRepositoryInterface::class => \DI\autowire(SprinkleMarkdownRepository::class),
         ];
     }
+
+    /**
+     * Register all Markdown Extensions defined in Sprinkles MarkdownExtensionRecipe.
+     *
+     * @param Environment                 $environment
+     * @param MarkdownRepositoryInterface $extensionLoader
+     */
+    protected function registerMarkdownExtensions(Environment $environment, MarkdownRepositoryInterface $extensionLoader): void
+    {
+        foreach ($extensionLoader as $extension) {
+            $environment->addExtension($extension);
+        }
+    }
 }

packages/sprinkle-core/app/src/Sprinkle/Recipe/MarkdownExtensionRecipe.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * UserFrosting Core Sprinkle (http://www.userfrosting.com)
+ *
+ * @link      https://github.com/userfrosting/sprinkle-core
+ * @copyright Copyright (c) 2013-2024 Alexander Weissman & Louis Charette
+ * @license   https://github.com/userfrosting/sprinkle-core/blob/master/LICENSE.md (MIT License)
+ */
+
+namespace UserFrosting\Sprinkle\Core\Sprinkle\Recipe;
+
+/**
+ * Sprinkle Markdown Extensions definition Interface.
+ */
+interface MarkdownExtensionRecipe
+{
+    /**
+     * Return an array of all registered Markdown Extensions.
+     *
+     * @return class-string<\League\CommonMark\Extension\ExtensionInterface>[]
+     */
+    public function getMarkdownExtensions(): array;
+}

packages/sprinkle-core/app/tests/Integration/Markdown/Fixtures/DummyMarkdownExtension.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * UserFrosting Core Sprinkle (http://www.userfrosting.com)
+ *
+ * @link      https://github.com/userfrosting/sprinkle-core
+ * @copyright Copyright (c) 2013-2024 Alexander Weissman & Louis Charette
+ * @license   https://github.com/userfrosting/sprinkle-core/blob/master/LICENSE.md (MIT License)
+ */
+
+namespace UserFrosting\Sprinkle\Core\Tests\Integration\Markdown\Fixtures;
+
+use League\CommonMark\Environment\EnvironmentBuilderInterface;
+use League\CommonMark\Extension\ExtensionInterface;
+
+/**
+ * Dummy markdown extension for testing purposes.
+ */
+class DummyMarkdownExtension implements ExtensionInterface
+{
+    public function register(EnvironmentBuilderInterface $environment): void
+    {
+        // This is a dummy extension for testing - it doesn't actually add any functionality
+    }
+}