PHP API Ref: external links #2533

adriendupuis · 2024-11-07T12:41:52Z

Question	Answer
JIRA Ticket	N/A
Versions	4.6+
Edition	All

Add an external link to extended parents from Symfony namespace.

In ibexa/core#377, I add the link into the class description. But, because of inheritance, it doesn't fit well when a class inherit this doc in cascade.
For example, BeforeAddRelationEvent reference page has the same "Event emitted before action execution." introduction than BeforeEvent ref page by inheritance. BeforeAddRelationEvent.php doesn't have such doc block. It comes from the extended class doc in BeforeEvent.php. BeforeAddRelationEvent shouldn't pretend being linked directly to Symfony\Contracts\EventDispatcher\Event (my PoV here is debatable). So, here is an other approach.

In 7060ffd I propose to link Symfony namespace to https://github.com/symfony/symfony/

It could be safer to only link Symfony\Contracts namespace but I'm optimist.

symfony/symfony isn't a bundle and seems to be a meta repo concatenating several Symfony bundles. But, it's useful as it's the one using Symfony version.

To target Symfony 5.4 branch should be safe, and it's simpler to maintain than targeting a specific patch tag.

I have tested all the generated links and it works find, no broken link.

$grep = explode(PHP_EOL, trim(`grep "https://github.com/symfony/symfony/blob/5.4/src" -R docs/api/php_api/php_api_reference;`));
foreach ($grep as $grepLine) {
    $parts = explode(':', $grepLine, 2);
    $file = $parts[0];
    preg_match('@https://github.com/symfony/symfony/blob/5.4/src[^"]*@', $parts[1], $matches);
    $url = $matches[0];
    $headers = explode(PHP_EOL, `curl -IsS '$url';`);
    if ('HTTP/2 200' != trim($headers[0])) {
        echo "BROKEN LINK IN $file: $url\n";
    //} else {
    //    echo "OK $file: $url\n";
    }
}

PHP API Reference previews of all the enhanced classes:

Checklist

Text renders correctly
Text has been checked with vale
Description metadata is up to date
Redirects cover removed/moved pages
Code samples are working
PHP code samples have been fixed with PHP CS fixer
Added link to this PR in relevant JIRA ticket or code PR

# Conflicts: # docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Test-IbexaKernelTestCase.html # docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Test-IbexaTestKernel.html # docs/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Test-Repository-SetupFactory-Legacy.html

adriendupuis · 2024-11-15T08:45:08Z

After reflexion, this is not very reader-friendly. To have to read PHP in GitHub is what we wanted to avoid in the first place by re-introducing the PHP API Reference.

Plus, it doesn't fix the inheritance issue. For example, Ibexa\Contracts\ActivityLog\Event\PostActivityGroupListLoadEvent still misses the two function inherited from Symfony\Contracts\EventDispatcher\Event, isPropagationStopped() and stopPropagation().

#2542 proposes to add Symfony\Contracts\EventDispatcher\Event to our doc.

adriendupuis added 4 commits November 7, 2024 13:25

PHP API Ref: Fix external link CSS

61915b8

PHP API Ref: Link Symfony namespace to GitHub

7060ffd

Generate PHP API Ref HTML

475ce14

adriendupuis changed the title ~~PHP API Ref external links~~ PHP API Ref: external links Nov 15, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PHP API Ref: external links #2533

PHP API Ref: external links #2533

adriendupuis commented Nov 7, 2024 •

edited

Loading

adriendupuis commented Nov 15, 2024

PHP API Ref: external links #2533

Are you sure you want to change the base?

PHP API Ref: external links #2533

Conversation

adriendupuis commented Nov 7, 2024 • edited Loading

Checklist

adriendupuis commented Nov 15, 2024

adriendupuis commented Nov 7, 2024 •

edited

Loading