chore: add support for extracting inline LLM instructions into an already parsed object

raphaelstolt · raphaelstolt · commit 88a04449e657 · 2025-09-30T12:11:19.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,11 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## [Unreleased]
 
+## [v3.3.0] - 2025-09-20
+
+### Added
+- Optional parameter `$parsed` for extraction via `extractFromFile` or `extractFromHtml` as an already parsed llms.txt object.
+
 ## [v3.2.0] - 2025-08-28
 
 ### Added
@@ -118,7 +123,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 - Initial release.
 
-[Unreleased]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.2.0...HEAD
+[Unreleased]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.3.0...HEAD
+[v3.3.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.2.0...v3.3.0
 [v3.2.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.1.0...v3.2.0
 [v3.1.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.0.0...v3.1.0
 [v3.0.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v2.1.1...v3.0.0
diff --git a/src/Extractor.php b/src/Extractor.php
@@ -6,6 +6,7 @@
 
 use DOMDocument;
 use DOMXPath;
+use Exception;
 use RuntimeException;
 
 final class Extractor
@@ -14,11 +15,11 @@ final class Extractor
      * Extracts the contents of all <script type="text/llms.txt"> blocks from a given HTML file.
      *
      * @param string $filePath Path to the HTML file.
-     * @throws RuntimeException If a file isn't found or unreadable.
+     * @param bool $parsed Whether the llms.txt should be parsed or not.
+     * @throws RuntimeException|Exception If a file isn't found or unreadable.
      * @return string[] Extracted contents.
-     *
      */
-    public function extractFromFile(string $filePath): array
+    public function extractFromFile(string $filePath, bool $parsed = false): array
     {
         if (!\is_readable($filePath)) {
             throw new RuntimeException("HTML file {$filePath} not found or not readable");
@@ -30,16 +31,18 @@ public function extractFromFile(string $filePath): array
             throw new RuntimeException("Failed to read HTML file {$filePath}");
         }
 
-        return $this->extractFromHtml($html);
+        return $this->extractFromHtml($html, $parsed);
     }
 
     /**
      * Extracts the contents of all <script type="text/llms.txt"> blocks from raw HTML.
      *
      * @param string $html Raw HTML string.
-     * @return string[] Extracted contents.
+     * @param bool $parsed Whether the llms.txt should be parsed or not.
+     * @throws Exception If the llmxt.txt parsing fails.
+     * @return array Extracted contents.
      */
-    public function extractFromHtml(string $html): array
+    public function extractFromHtml(string $html, bool $parsed = false): array
     {
         $dom = new DOMDocument();
         // Suppress warnings from malformed HTML
@@ -50,7 +53,11 @@ public function extractFromHtml(string $html): array
 
         $contents = [];
         foreach ($nodes as $node) {
-            $contents[] = \trim($node->textContent);
+            $content = \trim($node->textContent);
+            if ($parsed) {
+                $content = (new LlmsTxt)->parse($node->textContent);
+            }
+            $contents[] = $content;
         }
 
         return $contents;
diff --git a/tests/ExtractorTest.php b/tests/ExtractorTest.php
@@ -7,6 +7,7 @@
 use PHPUnit\Framework\Attributes\Test;
 use RuntimeException;
 use Stolt\LlmsTxt\Extractor;
+use Stolt\LlmsTxt\LlmsTxt;
 
 final class ExtractorTest extends TestCase
 {
@@ -64,6 +65,28 @@ public function extractsMultipleBlocksFromHtml(): void
         $this->assertSame(['first-block', 'second-block'], $this->extractor->extractFromHtml($html));
     }
 
+    #[Test]
+    public function parsesLlmsTxtBlocksFromHtml(): void
+    {
+        $html = <<<HTML
+        <html>
+          <body>
+            <script type="text/llms.txt"># Title one</script>
+            Some other content.
+            <p>And some more content.</p>
+            <br />
+            <script type="text/llms.txt"># Title two</script>
+          </body>
+        </html>
+        HTML;
+
+        $this->assertInstanceof(LlmsTxt::class, $this->extractor->extractFromHtml($html, true)[0]);
+
+        $secondLlmsTxtBlock = $this->extractor->extractFromHtml($html, true)[1];
+
+        $this->assertEquals('Title two', $secondLlmsTxtBlock->getTitle());
+    }
+
     #[Test]
     public function returnsAnEmptyArrayWhenNoBlocksAreFound(): void
     {
