Skip to content

PHP API Ref: external links #2533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 4 commits into from
Closed

PHP API Ref: external links #2533

wants to merge 4 commits into from

Conversation

@adriendupuis
Copy link
Contributor

@adriendupuis adriendupuis commented Nov 7, 2024 •
edited
Loading

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

@adriendupuis
PHP API Ref: Fix external link CSS
61915b8
@adriendupuis
PHP API Ref: Link Symfony namespace to GitHub
7060ffd
@adriendupuis
Generate PHP API Ref HTML
475ce14
@adriendupuis
Merge branch 'master' into php-api-ref-external-links
9f976f1 
# 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
Copy link
Contributor Author

adriendupuis commented Nov 15, 2024

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 adriendupuis changed the title PHP API Ref external links PHP API Ref: external links Nov 15, 2024
@adriendupuis adriendupuis mentioned this pull request Nov 19, 2024
Merged
7 tasks
@adriendupuis adriendupuis deleted the php-api-ref-external-links branch April 7, 2025 08:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@adriendupuis