Enhancements for page numbers links API

[sirzooro]

Currently WordPress provides few functions to create links with page numbers embedded. Unfortunately they have some limitations:

• get_pagenum_link() - works on $_SERVER['REQUEST_URI'] only;
  
• get_comments_pagenum_link() - works on current post only;
  
• _wp_link_page() - works on current post only, returns HTML code and is private.

Because of these limitations in the past I have reimplemented these functions in my SEO plugin. Now I decided that it will be better if WP core will provide needed functionality.

Attached path introduces following changes for functions:

• get_pagenum_link() - added new $url param, which can be used to pass any URL to function;
  
• get_comments_pagenum_link() - added two new params: $post and $add_anchor. The former one allows to pass any post object to function, the latter one tells function if it should append #comments at the end of URL;
• get_post_page_link() - new function. I moved code from _wp_link_page() here and modified it so it can work on any post. Additionally it calls new filter get_post_page_link before returning value.
  

Additionally these functions passes new argument(s) to filter at the end, so it will be easier for plugins to generate different pagination URLs.

I also modified _wp_link_page() function (now it calls get_post_page_link()) and removed @access private from wp_link_pages() (as I checked, it is called from themes code only).

[sirzooro]

I have performed some additional tests and found that get_comments_pagenum_link() and get_post_page_link() do not generate correct links when both page on front and index-based permalinks are used - generated permalinks does not include the `/index.php/' part. New patch fixes this bug.

[sirzooro]

Path with fix for incorrect index-based permalinks for front page

[sirzooro]

Related: #21274

[joostdevalk]

Closing for lack of activity. If you have a refreshed patch, feel free to re-open it!