From #2547833: Pager.inc -- add tests, clean it up, convert to a service, use it!:
Problem/Motivation
pager.inc uses global variables, which we are trying to get rid of, as they make it impossible to manage pagers in a OO manner. All the pager related API are procedural functions.
Proposed resolution
Make Drupal's default pager an OO service, using the capabilities introduced in Drupal 8. This will make it OO and will open it up to the possibility to replace it by alternative implementations.
Unfortunately proper cleanup would include removing the four globals in pager.inc. Since that's an API change, the best we can do in 8.x is deprecate them and include (deprecated) wrappers for the new service to maintain backwards comparability until 9.x.
In detail:
1) A 'pager' is a classed object that contains data and methods relative to a pager element. A 'pager manager' service creates 'pager' objects and keeps track of the objects created so that they can be traversed to produce the 'page' URL querystring for the pager links.
2) The global variables are retained at this stage, wrapped into the PagerInterface methods so that methods can alter them, but also, for BC, other code can alter them independently, and in this case the values stored in the global override any value stored in the PagerInterface object.
3) pager.inc procedural functions remain for BC as wrappers to PagerManagerInterface service or PagerInterface methods. There are no longer global variables declared in this file!
4) template_preprocess_pager() use the new service methods instead of directly accessing the globals.
Remaining tasks
- review
User interface changes
None.
API changes
All pager_* global variables and procedural function will be deprecated. New Drupal\Core\Pager\PagerInterface and Drupal\Core\Pager\PagerManagerInterface and their default implementations will be added. BC layer introduced to allow deprecated global variables and functions to stay with same functionality until Drupal 9.
Data model changes
None.