Automated type checking of code samples in docs #7380

New Issue

admin · 2026-01-22T15:50:58+01:00

admin commented

2026-01-22 15:50:58 +01:00

Originally created by @SamMousa on GitHub (Jun 11, 2024).

          True. I don't know how to do that however.

Originally posted by @greg0ire in https://github.com/doctrine/orm/issues/11492#issuecomment-2160922838

I might be able to help set this up.
Started on a proof of concept extractor already.

<?php

$lines = file(__DIR__ . '/en/tutorials/composite-primary-keys.rst', FILE_IGNORE_NEW_LINES);

$indent = null;
$blockCounter = 0;
$block = [];
foreach($lines as $i => $line) {
    // Check if this is the start of a php block.
    if ($indent === null && preg_match('/^(\s*)\<\?php/', $line, $matches)) {
        echo "Start PHP block\n";
        $indent = strlen($matches[1]);
        $block[] = "<?php //Extracted from line $i\n";
    } elseif ($indent !== null && preg_match("/^\s{{$indent}}(.*)|^()$/", $line, $matches)) {
        $block[] = ($matches[1] ?? ''); // . "\t\t\t\t# Extracted from line $i";
    } elseif ($indent !== null) {
        $indent = null;
        print_r($block);
        file_put_contents("/tmp/check/block{$blockCounter}.php", implode("\n", $block));
        $blockCounter++;
        $block = [];

    }

}

The idea is simple:

Parse each .rst file crudely extracting PHP code blocks.
Add missing imports automatically (or decide that we want copy paste friendly docs and just add missing imports to the examples)
Run phpstan to analyse the code.

The extractor above also adds a comment to know where we got it from:

<?php //Extracted from line 112

namespace VehicleCatalogue\Model;

// $em is the EntityManager

$car = new Car("Audi A8", 2010);
$em->persist($car);
$em->flush();

I'll look into creating a github action that just does this for all RST files in a directory.

Originally created by @SamMousa on GitHub (Jun 11, 2024). True. I don't know how to do that however. _Originally posted by @greg0ire in https://github.com/doctrine/orm/issues/11492#issuecomment-2160922838_ I might be able to help set this up. Started on a proof of concept extractor already. ```php <?php $lines = file(__DIR__ . '/en/tutorials/composite-primary-keys.rst', FILE_IGNORE_NEW_LINES); $indent = null; $blockCounter = 0; $block = []; foreach($lines as $i => $line) { // Check if this is the start of a php block. if ($indent === null && preg_match('/^(\s*)\<\?php/', $line, $matches)) { echo "Start PHP block\n"; $indent = strlen($matches[1]); $block[] = "<?php //Extracted from line $i\n"; } elseif ($indent !== null && preg_match("/^\s{{$indent}}(.*)|^()$/", $line, $matches)) { $block[] = ($matches[1] ?? ''); // . "\t\t\t\t# Extracted from line $i"; } elseif ($indent !== null) { $indent = null; print_r($block); file_put_contents("/tmp/check/block{$blockCounter}.php", implode("\n", $block)); $blockCounter++; $block = []; } } ``` The idea is simple: - Parse each `.rst` file crudely extracting PHP code blocks. - Add missing imports automatically (or decide that we want copy paste friendly docs and just add missing imports to the examples) - Run `phpstan` to analyse the code. The extractor above also adds a comment to know where we got it from: ```php <?php //Extracted from line 112 namespace VehicleCatalogue\Model; // $em is the EntityManager $car = new Car("Audi A8", 2010); $em->persist($car); $em->flush(); ``` I'll look into creating a github action that just does this for all RST files in a directory.

admin commented

2026-01-22 15:50:59 +01:00

@greg0ire commented on GitHub (Jun 11, 2024):

Add missing imports automatically (or decide that we want copy paste friendly docs and just add missing imports to the examples)

I think we should have copy/paste friendly docs

@greg0ire commented on GitHub (Jun 11, 2024): > Add missing imports automatically (or decide that we want copy paste friendly docs and just add missing imports to the examples) I think we should have copy/paste friendly docs

admin commented

2026-01-22 15:51:00 +01:00

@SamMousa commented on GitHub (Jun 12, 2024):

I'm ready to push the PR, what branch should I target?

@SamMousa commented on GitHub (Jun 12, 2024): I'm ready to push the PR, what branch should I target?

admin commented

2026-01-22 15:51:00 +01:00

@greg0ire commented on GitHub (Jun 12, 2024):

2.19.x please.

@greg0ire commented on GitHub (Jun 12, 2024): 2.19.x please.

admin referenced this issue

2026-01-22 16:07:37 +01:00