DevHub: Support viewing source on GitHub mirror

[netweb]

Currently when looking up references in devhub links to the source only link to Trac source, it would be great to add support to also link to the GitHub mirror.

For example, looking at ​https://developer.wordpress.org/reference/functions/add_theme_support/#source, there is a link to the Trac source at:

• ​https://core.trac.wordpress.org/browser/tags/5.8/src/wp-includes/theme.php#L2519

And it would be great to also link to the GitHub mirror source at:

• ​https://github.com/WordPress/wordpress-develop/blob/5.8/src/wp-includes/theme.php#L2519

---

A quick look at the code, here's an initial quick patch duplicating the existing get_source_file_link() function:

wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php

@@ -1180 +1180 @@
                 return esc_url( $url );
         }
 
+        /**
+         * Retrieve the URL to the GitHub source file and line.
+         *
+         * @param null $post_id     Post ID.
+         * @param bool $line_number Whether to append the line number to the URL.
+         *                          Default true.
+         * @return string Source file URL with or without line number.
+         */
+        function get_github_source_file_link( $post_id = null, $line_number = true ) {
+
+                $post_id = empty( $post_id ) ? get_the_ID() : $post_id;
+                $url     = '';
+
+                // Source file.
+                $source_file = get_source_file( $post_id );
+                if ( ! empty( $source_file ) ) {
+                        $url = 'https://github.com/WordPress/wordpress-develop/blob/' . get_current_version() . '/src/' . $source_file;
+                        // Line number.
+                        if ( $line_number = get_post_meta( get_the_ID(), '_wp-parser_line_num', true ) ) {
+                                $url .= "#L{$line_number}";
+                        }
+                }
+
+                return esc_url( $url );
+        }
+
+
         /**
          * Compare two objects by name for sorting.
          *

wordpress.org/public_html/wp-content/themes/pub/wporg-developer/reference/template-source.php

@@ -30 +30 @@
                                         <a href="#" class="less-complete-source"><?php _e( 'Collapse full source code', 'wporg' ); ?></a>
                                 </span>
                                 <span><a href="<?php echo get_source_file_link(); ?>"><?php _e( 'View on Trac', 'wporg' ); ?></a></span>
+                                <span><a href="<?php echo get_github_source_file_link(); ?>"><?php _e( 'View on GitHub', 'wporg' ); ?></a></span>
                         </p>
                 <?php else : ?>
                         <p>

[netweb]

p.s: Props to @stuartshields for the idea

[dd32]

In 11311:

Code Reference: Include a link to view the source on GitHub.

Props stuartshields, netweb, dd32.
Fixes #5942.

[dd32]

I added the end line number to the link too, so that it highlights the entire function: ​https://github.com/WordPress/wordpress-develop/blob/5.8/src/wp-includes/post-template.php#L243-L256

Oh, and uh removed the $line_number arg since well, it didn't do what it said it does on the box, and isn't used anywhere.

[dd32]

This only applied to functions and not other locations, like hooks: ​https://developer.wordpress.org/reference/hooks/comment_text/

The above hook also shows a parser bug, as it's unable to extract the PHP for the hook, this affects a number of hooks and functions that I've seen over the last few months.

[coffee2code]

Replying to dd32:

The above hook also shows a parser bug, as it's unable to extract the PHP for the hook, this affects a number of hooks and functions that I've seen over the last few months.

Hooks are (and have always been) explicitly excluded^* from having their PHP source shown since doing so is not meaningful (it'd just be a duplicate of the hook definition at the top of the page), so it merely links to the source.

Functions should always show their source code though, so I'd be happy to look into any that are failing to do so.

This only applied to functions and not other locations, like hooks:

Following on from my explanation above, the change made by the patch to reference/template-source.php needs to also be applied in the nearby else.

---

^* In the template reference/template-source.php, which uses post_type_has_source_code() which uses get_post_types_with_source_code().

[dd32]

Replying to coffee2code:

Replying to dd32:

The above hook also shows a parser bug, as it's unable to extract the PHP for the hook, this affects a number of hooks and functions that I've seen over the last few months.

Hooks are (and have always been) explicitly excluded^* from having their PHP source shown since doing so is not meaningful (it'd just be a duplicate of the hook definition at the top of the page), so it merely links to the source.

Huh, you're right.. okay that certainly makes sense.

Kind of seems weird that the source-code for the hook isn't displayed within the "Source" heading though, given it's only a single line usually, it might be worth duplicating it there?

Functions should always show their source code though, so I'd be happy to look into any that are failing to do so.

​twenty_fourteen_ephemera_widget::__construct and similar theme class methods are probably a good example, I'm sure I've seen another one but I can't think of it off the top of my head.

​the class definition doesn't even exist

[coffee2code]

Replying to dd32:

Kind of seems weird that the source-code for the hook isn't displayed within the "Source" heading though, given it's only a single line usually, it might be worth duplicating it there?

For consistency and completeness, I wouldn't be opposed to having the line of code for each hook to be included. I can include them in the parsing of 5.8.2 (at the latest) when it lands, or sooner if I get a chance. It requires a CLI run to pre-cache source code after a necessary code adjustment has been committed.

​twenty_fourteen_ephemera_widget::__construct and similar theme class methods are probably a good example, I'm sure I've seen another one but I can't think of it off the top of my head.

Ah, thanks. Those shouldn't exist and have been deleted. In the early days of the Code Reference, parsings included bundled themes, but were quickly deemed not to be included. Much of those parsed theme resources had since been deleted. Looks like a handful of methods (including the one you mentioned) and a couple hooks still persisted, but are gone now.

So I'm not surprised that with those methods existing that their source codes were understandably missing. However, any legitimate functions/methods/classes should have the proper source code embeds.

​the class definition doesn't even exist

As noted, this is the proper situation since theme-specific data shouldn't exist.

[dd32]

Replying to coffee2code:

So I'm not surprised that with those methods existing that their source codes were understandably missing. However, any legitimate functions/methods/classes should have the proper source code embeds.

I went and dug up some more examples:
​https://developer.wordpress.org/reference/classes/wp_matchesmapregex/wp_matchesmapregex/
​https://developer.wordpress.org/reference/classes/wp_customize_custom_css_setting/validate_equal_characters/
​https://developer.wordpress.org/reference/classes/ixr_server/multicall/
​https://developer.wordpress.org/reference/functions/upgrade_101/

I'll DM you on slack with a SQL query to pull up the 175 items.

[coffee2code]

This is fixed. The OP request for 'View on GitHub' link was long ago added.

The two follow-on tasks have also both been long addressed:

1. Display of the source code line for hooks was enabled (so the 'View on GitHub' link appears for hooks as well).
2. The functions Dion mentioned that were missing source code were all functions that were no longer being parsed and should've been deleted, and since have been.