feat: improve validation

Author: raphaelstolt

CHANGELOG.md

@@ -7,6 +7,11 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## [Unreleased]
 
+## [v3.4.0] - 2025-10-15
+
+### Added
+- Improved `LlmsTxt::validation` by providing more information about the validation errors. Closes issue [8](https://github.com/raphaelstolt/llms-txt-php/issues/8).
+
 ## [v3.3.0] - 2025-09-20
 
 ### Added
@@ -123,7 +128,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.3.0...HEAD
+[Unreleased]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.4.0...HEAD
+[v3.4.0]: https://github.com/raphaelstolt/llms-txt-php/compare/v3.3.0...v3.4.0
 [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

README.md

@@ -64,6 +64,26 @@ if ($llmsText->validate()) {
     $sections = $llmsText->getSections();
 }
 ```
+In case you want to get the exact validation errors, you can need to call `validate` with the `detailed` flag sat to 
+`true` and than use the `errors()` method.
+
+```php
+use Stolt\LlmsTxt\LlmsTxt;
+
+$llmsText = (new LlmsTxt())->parse('/path/to/llmsTxt.md'); // OR parse('markdown-string')
+
+$validationResult = $llmsTxt->validate(true);
+if ($validationResult->isValid()) {
+    $title = $llmsText->getTitle();
+    $description = $llmsText->getDescription();
+    $details = $llmsText->getDetails();
+    $sections = $llmsText->getSections();
+} else {
+    $validationErrors = $validationResult->errors();
+    // ...
+}
+```
+
 > [!TIP]
 > To interact with `llms.txt` files from the console, the complement package [llms-txt-php-cli](https://github.com/raphaelstolt/llms-txt-php-cli) might come in handy.
 

src/LlmsTxt.php

@@ -6,6 +6,8 @@
 
 use \Exception;
 use Stolt\LlmsTxt\Section\Link;
+use Stolt\LlmsTxt\Validation\ValidationError;
+use Stolt\LlmsTxt\Validation\ValidationResult;
 
 final class LlmsTxt
 {
@@ -112,15 +114,55 @@ public function toString(): string
     }
 
     /**
+     * Validates a given llms.txt file content.
+     *
+     * If `$detailed` is false (default), it returns a simple boolean for backward compatibility.
+     * If `$detailed` is true, returns a `ValidationResult` object with rich diagnostics.
+     *
+     * @param bool $detailed Whether to return a ValidationResult instead of a boolean.
+     *
      * @throws Exception
+     * @return bool|ValidationResult
      */
-    public function validate(): bool
+    public function validate(bool $detailed = false): bool|ValidationResult
     {
         if ($this->hasBeenParsed) {
+
+
             if ($this->title !== '' && $this->description !== '' && $this->details !== '' && \count($this->sections) > 0 && \count($this->sections[0]->getLinks()) > 0) {
+                if ($detailed) {
+                    return new ValidationResult();
+                }
                 return true;
             }
 
+            if ($detailed) {
+                $result = new ValidationResult();
+
+                if (!isset($this->title) || empty($this->title)) {
+                    $result->addError(new ValidationError('Missing title'));
+                }
+
+                if (!isset($this->description) || empty($this->description)) {
+                    $result->addError(new ValidationError('Missing description'));
+                }
+
+                if (!isset($this->details) || empty($this->details)) {
+                    $result->addError(new ValidationError('Missing details'));
+                }
+
+                if (\count($this->sections) === 0) {
+                    $result->addError(new ValidationError('Missing at least one section'));
+                    $result->addError(new ValidationError('Missing at least one section link'));
+                }
+
+                if (\count($this->sections) > 0 && \count($this->sections[0]->getLinks()) === 0) {
+                    $result->addError(new ValidationError('Missing at least one section link'));
+                }
+
+                return $result;
+            }
+
             return false;
         }
 

src/Validation/ValidationError.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stolt\LlmsTxt\Validation;
+
+final class ValidationError
+{
+    public function __construct(
+        private readonly string $message
+    ) {
+    }
+
+    public function message(): string
+    {
+        return $this->message;
+    }
+}

src/Validation/ValidationResult.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stolt\LlmsTxt\Validation;
+
+final class ValidationResult
+{
+    /** @var ValidationError[] */
+    private array $errors = [];
+
+    public function addError(ValidationError $error): void
+    {
+        $this->errors[] = $error;
+    }
+
+    public function isValid(): bool
+    {
+        return empty($this->errors);
+    }
+
+    /**
+     * @return ValidationError[]
+     */
+    public function errors(): array
+    {
+        return $this->errors;
+    }
+}

tests/LlmsTxtTest.php

@@ -135,6 +135,27 @@ public function itValidatesLlmsTxtAsExpected(): void
         $this->assertTrue($llmsTxt->validate());
     }
 
+    #[Test]
+    public function itValidatesLlmsTxtWithAValidationResultAsExpected(): void
+    {
+        $llmsTxt = new LlmsTxt();
+        $llmsTxt = $llmsTxt->parse(\realpath(__DIR__ . '/fixtures/uv.llms.md'));
+
+        $validationResult = $llmsTxt->validate(true);
+        $this->assertTrue($validationResult->isValid());
+    }
+
+    #[Test]
+    public function itValidatesLlmsTxtWithAValidationResultAsExpectedWithMissingElements(): void
+    {
+        $llmsTxt = new LlmsTxt();
+        $llmsTxt = $llmsTxt->parse(\realpath(__DIR__ . '/fixtures/invalid.md'));
+
+        $validationResult = $llmsTxt->validate(true);
+        $this->assertFalse($validationResult->isValid());
+        $this->assertCount(4, $validationResult->errors());
+    }
+
     #[Test]
     public function itThrowsExpectedExceptionWhenNotParsedBeforeValidating(): void
     {

tests/fixtures/invalid.md

@@ -0,0 +1 @@
+# Title