Extending DocParser‐PHP

Adding support for a new language

This guide explains how to extend DocParser-PHP to support a new markup language (e.g. Markdown, XML, LaTeX, etc...). By following these steps, you can integrate new parsers and validators while keeping the project’s modular architecture intact.

---

Step 1: Create the Parser and Validator

1. Define Parser and Validator Classes:

   • Create a new folder Language within src/Model/Parser, e.g. src/Model/Parser/XML;
   • Create two new folders Element and Validator inside of the folder, e.g. src/Model/Parser/XML/Element and src/Model/Parser/XML/Validator;
   • Element folder should contain the parsing logic and its classes must implement ParserInterface interface;
   • Validator folder should contain the validation logic and its classes must extend AbstractValidator class.

2. Implement Validation Logic:

   • Check the document structure (e.g., required headings, mandatory attributes).
   • Generate errors and warnings via ElementValidationResult.

3. Implement Parsing Logic:

   • Parse the document content into a structured data format using the class Node.
   • Ensure the parser output is compatible with the JSON view.

---

Step 2: Update the config

1. Within folder config/Parser create a yaml file that contains the element roots from which the parser should start. These are classes contained in the folder Element previously defined. More than one root is allowed. The file must be name with the format parser_language.yaml.

Example:

rootElements:
  - Niccolo\DocparserPhp\Model\Parser\XML\Element\ParserClass

2. Within folder config/Validator create a yaml file that contains the validation classes whose validation is to be executed. These are classes contained in the folder Validator previously defined. More than one class is allowed. The file must be name with the format validator_language.yaml.

Example:

validators:
  - Niccolo\DocparserPhp\Model\Parser\HTML\Validator\DoctypeValidator
  - Niccolo\DocparserPhp\Model\Parser\HTML\Validator\HtmlValidator
  - Niccolo\DocparserPhp\Model\Parser\HTML\Validator\HeadValidator
  - Niccolo\DocparserPhp\Model\Parser\HTML\Validator\BodyValidator
  - Niccolo\DocparserPhp\Model\Parser\HTML\Validator\TitleValidator
  - Niccolo\DocparserPhp\Model\Parser\HTML\Validator\HeadingValidator
  - Niccolo\DocparserPhp\Model\Parser\HTML\Validator\ParagraphValidator

---

Step 3: Add new supported type

1. Within the class src/Model/Utils/Parser/Enum/InputType add a new case for the new supported language, e.g. case XML = 'xml';
2. In the same class add the extension for file written in that language (which may vary, e.g. md for Markdown), e.g. self::XML->value => '.xml'.

---

Step 4: Write Tests

1. Validation Tests: Ensure the validator correctly detects errors and warnings.
2. Parsing Tests: Check that the parser produces the correct data structure.
3. Integration Tests: Verify the full flow: input → validation → parsing → output.
4. Regression Tests: Ensure adding the new language does not break existing parsers.

---

Step 5: Update the UI

1. Modify the User Interface:

   • Add a new option in the input form to select the new language.

2. Handle User Selection:

   • Ensure the selection is passed correctly to the controller to create the appropriate parser.

---

Step 6: Run Tests

1. Run PHPUnit Tests to verify all tests pass.
2. Test the UI to ensure the new language works as expected.

---