From 64347f8984115e9a61ccdd87b68fbbf0d03440b3 Mon Sep 17 00:00:00 2001
From: Domizio Demichelis <dd.nexus@gmail.com>
Date: Thu, 22 Apr 2021 16:46:56 +0700
Subject: [PATCH] changed the argument order from pagy_url_for(page, pagy) >
 pagy_url_for(pagy, page) for consistency with all the other helpers;
 deprecation warning and support for pagy < 5

---
 lib/pagy.rb                                  |  3 ++-
 lib/pagy/deprecation.rb                      | 20 ++++++++++++++++
 lib/pagy/extras/bootstrap.rb                 |  4 ++--
 lib/pagy/extras/bulma.rb                     |  4 ++--
 lib/pagy/extras/foundation.rb                |  4 ++--
 lib/pagy/extras/headers.rb                   |  2 +-
 lib/pagy/extras/items.rb                     |  5 ++--
 lib/pagy/extras/materialize.rb               |  4 ++--
 lib/pagy/extras/metadata.rb                  |  2 +-
 lib/pagy/extras/navs.rb                      |  4 ++--
 lib/pagy/extras/semantic.rb                  |  4 ++--
 lib/pagy/extras/support.rb                   | 20 ++++++++--------
 lib/pagy/extras/uikit.rb                     |  4 ++--
 lib/pagy/frontend.rb                         | 14 ++++--------
 pagy.manifest                                |  1 +
 test/pagy/derecation_test.rb                 | 20 ++++++++++++++++
 test/pagy/extras/items_countless_test.rb     | 10 ++++----
 test/pagy/extras/items_elasticsearch_test.rb | 10 ++++----
 test/pagy/frontend_test.rb                   | 24 ++++++++------------
 19 files changed, 95 insertions(+), 64 deletions(-)
 create mode 100644 lib/pagy/deprecation.rb
 create mode 100644 test/pagy/derecation_test.rb

diff --git a/lib/pagy.rb b/lib/pagy.rb
index d9928b448..f64db7218 100644
--- a/lib/pagy.rb
+++ b/lib/pagy.rb
@@ -66,9 +66,10 @@ def series(size=@vars[:size])
     series[series.index(@page)] = @page.to_s
     series
   end
-
+  
 end
 
+require 'pagy/deprecation'
 require 'pagy/backend'
 require 'pagy/frontend'
 require 'pagy/exceptions'
diff --git a/lib/pagy/deprecation.rb b/lib/pagy/deprecation.rb
new file mode 100644
index 000000000..27f99fb04
--- /dev/null
+++ b/lib/pagy/deprecation.rb
@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+class Pagy
+  class << self
+
+    # deprecated pagy_url_for rgument order
+    def deprecated_order(pagy, page)
+      Warning.warn '[PAGY WARNING] inverted use of pagy/page in pagy_url_for will not be supported in 5.0! Use pagy_url_for(pagy, page) instead.'
+      [page, pagy]
+    end
+
+
+    # deprecated arguments to remove in 5.0
+    def deprecated_arg(arg, val, new_key, new_val)
+      value = new_val || val  # we use the new_val if present
+      Warning.warn %([PAGY WARNING] deprecated use of positional `#{arg}` arg will not be supported in 5.0! Use only the keyword arg `#{new_key}: #{value.inspect}` instead.)
+      value
+    end
+
+  end
+end
diff --git a/lib/pagy/extras/bootstrap.rb b/lib/pagy/extras/bootstrap.rb
index 12b20c897..3237ee6d0 100644
--- a/lib/pagy/extras/bootstrap.rb
+++ b/lib/pagy/extras/bootstrap.rb
@@ -26,7 +26,7 @@ def pagy_bootstrap_nav(pagy, pagy_id: nil, link_extra: '')
 
     # Javascript pagination for bootstrap: it returns a nav and a JSON tag used by the Pagy.nav javascript
     def pagy_bootstrap_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: nil)
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, %(class="page-link" #{link_extra}))
       tags = { 'before' => %(<ul class="pagination">#{pagy_bootstrap_prev_html pagy, link}),
@@ -41,7 +41,7 @@ def pagy_bootstrap_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '',
 
     # Javascript combo pagination for bootstrap: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript
     def pagy_bootstrap_combo_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '')
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id    = %( id="#{pagy_id}") if pagy_id
       link    = pagy_link_proc(pagy, link_extra)
       p_page  = pagy.page
diff --git a/lib/pagy/extras/bulma.rb b/lib/pagy/extras/bulma.rb
index c7adbc36a..a99d80948 100644
--- a/lib/pagy/extras/bulma.rb
+++ b/lib/pagy/extras/bulma.rb
@@ -25,7 +25,7 @@ def pagy_bulma_nav(pagy, pagy_id: nil, link_extra: '')
     end
 
     def pagy_bulma_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: nil)
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra)
       tags = { 'before' => %(#{pagy_bulma_prev_next_html(pagy, link)}<ul class="pagination-list">),
@@ -40,7 +40,7 @@ def pagy_bulma_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', ste
 
     # Javascript combo pagination for Bulma: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript
     def pagy_bulma_combo_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '')
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id    = %( id="#{pagy_id}") if pagy_id
       link    = pagy_link_proc(pagy, link_extra)
       p_page  = pagy.page
diff --git a/lib/pagy/extras/foundation.rb b/lib/pagy/extras/foundation.rb
index 65db4d37d..49cd5dcf2 100644
--- a/lib/pagy/extras/foundation.rb
+++ b/lib/pagy/extras/foundation.rb
@@ -26,7 +26,7 @@ def pagy_foundation_nav(pagy, pagy_id: nil, link_extra: '')
 
     # Javascript pagination for foundation: it returns a nav and a JSON tag used by the Pagy.nav javascript
     def pagy_foundation_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: nil)
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra)
       tags = { 'before' => %(<ul class="pagination">#{pagy_foundation_prev_html pagy, link}),
@@ -41,7 +41,7 @@ def pagy_foundation_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: ''
 
     # Javascript combo pagination for Foundation: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript
     def pagy_foundation_combo_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '')
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id    = %( id="#{pagy_id}") if pagy_id
       link    = pagy_link_proc(pagy, link_extra)
       p_page  = pagy.page
diff --git a/lib/pagy/extras/headers.rb b/lib/pagy/extras/headers.rb
index 6ec8c6297..a5bb260a2 100644
--- a/lib/pagy/extras/headers.rb
+++ b/lib/pagy/extras/headers.rb
@@ -24,7 +24,7 @@ def pagy_headers_hash(pagy)
       countless = defined?(Pagy::Countless) && pagy.is_a?(Pagy::Countless)
       rels = { 'first' => 1, 'prev' => pagy.prev, 'next' => pagy.next }
       rels['last'] = pagy.last unless countless
-      url_str = pagy_url_for(PAGE_PLACEHOLDER, pagy, :url)
+      url_str = pagy_url_for(pagy, PAGE_PLACEHOLDER, :url)
       hash    = { 'Link' => rels.filter_map do |rel, num|
                               next unless num
                               [ rel, url_str.sub(PAGE_PLACEHOLDER, num.to_s) ]
diff --git a/lib/pagy/extras/items.rb b/lib/pagy/extras/items.rb
index c80141fed..faa6e15b7 100644
--- a/lib/pagy/extras/items.rb
+++ b/lib/pagy/extras/items.rb
@@ -37,7 +37,8 @@ module Frontend
 
     module UseItemsExtra
 
-      def pagy_url_for(page, pagy, url=nil)
+      def pagy_url_for(pagy, page, url=nil)
+        pagy, page = Pagy.deprecated_order(pagy, page) if page.is_a?(Pagy)
         p_vars = pagy.vars
         params = request.GET.merge(p_vars[:params])
         params[p_vars[:page_param].to_s]  = page
@@ -50,7 +51,7 @@ def pagy_url_for(page, pagy, url=nil)
 
     # Return the items selector HTML. For example "Show [20] items per page"
     def pagy_items_selector_js(pagy, deprecated_id=nil, pagy_id: nil, item_name: nil, i18n_key: nil)
-      pagy_id        = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id        = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id           = %( id="#{pagy_id}") if pagy_id
       p_vars         = pagy.vars
       p_items        = p_vars[:items]
diff --git a/lib/pagy/extras/materialize.rb b/lib/pagy/extras/materialize.rb
index 8dde1bc45..300483a36 100644
--- a/lib/pagy/extras/materialize.rb
+++ b/lib/pagy/extras/materialize.rb
@@ -26,7 +26,7 @@ def pagy_materialize_nav(pagy, pagy_id: nil, link_extra: '')
 
     # Javascript pagination for materialize: it returns a nav and a JSON tag used by the Pagy.nav javascript
     def pagy_materialize_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: nil)
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra)
 
@@ -42,7 +42,7 @@ def pagy_materialize_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '
 
     # Javascript combo pagination for materialize: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript
     def pagy_materialize_combo_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '')
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id    = %( id="#{pagy_id}") if pagy_id
       link    = pagy_link_proc(pagy, link_extra)
       p_page  = pagy.page
diff --git a/lib/pagy/extras/metadata.rb b/lib/pagy/extras/metadata.rb
index fa189d86a..752a6d05a 100644
--- a/lib/pagy/extras/metadata.rb
+++ b/lib/pagy/extras/metadata.rb
@@ -22,7 +22,7 @@ def pagy_metadata(pagy, url=nil)
       raise VariableError.new(pagy), "unknown metadata #{unknown.inspect}" \
             unless unknown.empty?
 
-      scaffold_url = pagy_url_for(PAGE_PLACEHOLDER, pagy, url)
+      scaffold_url = pagy_url_for(pagy, PAGE_PLACEHOLDER, url)
       {}.tap do |metadata|
         names.each do |key|
           metadata[key] = case key
diff --git a/lib/pagy/extras/navs.rb b/lib/pagy/extras/navs.rb
index c0d3e8c94..d1e68f318 100644
--- a/lib/pagy/extras/navs.rb
+++ b/lib/pagy/extras/navs.rb
@@ -8,7 +8,7 @@ module Frontend
 
     # Javascript pagination: it returns a nav and a JSON tag used by the Pagy.nav javascript
     def pagy_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: nil)
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra)
       tags = { 'before' => pagy_nav_prev_html(pagy, link),
@@ -23,7 +23,7 @@ def pagy_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: ni
 
     # Javascript combo pagination: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript
     def pagy_combo_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '')
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id    = %( id="#{pagy_id}") if pagy_id
       link    = pagy_link_proc(pagy, link_extra)
       p_page  = pagy.page
diff --git a/lib/pagy/extras/semantic.rb b/lib/pagy/extras/semantic.rb
index 04cc7b487..6cd707c62 100644
--- a/lib/pagy/extras/semantic.rb
+++ b/lib/pagy/extras/semantic.rb
@@ -26,7 +26,7 @@ def pagy_semantic_nav(pagy, pagy_id: nil, link_extra: '')
 
     # Javascript pagination for semantic: it returns a nav and a JSON tag used by the Pagy.nav javascript
     def pagy_semantic_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: nil)
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, %(class="item" #{link_extra}))
       tags = { 'before' => pagy_semantic_prev_html(pagy, link),
@@ -41,7 +41,7 @@ def pagy_semantic_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '',
 
     # Combo pagination for semantic: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript
     def pagy_semantic_combo_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '')
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id    = %( id="#{pagy_id}") if pagy_id
       link    = pagy_link_proc(pagy, %(class="item" #{link_extra}))
       p_page  = pagy.page
diff --git a/lib/pagy/extras/support.rb b/lib/pagy/extras/support.rb
index cfc0febf7..9edeadcc6 100644
--- a/lib/pagy/extras/support.rb
+++ b/lib/pagy/extras/support.rb
@@ -6,39 +6,39 @@ class Pagy
   module Frontend
 
     def pagy_prev_url(pagy)
-      pagy_url_for(pagy.prev, pagy) if pagy.prev
+      pagy_url_for(pagy, pagy.prev) if pagy.prev
     end
 
     def pagy_next_url(pagy)
-      pagy_url_for(pagy.next, pagy) if pagy.next
+      pagy_url_for(pagy, pagy.next) if pagy.next
     end
 
     def pagy_prev_link(pagy, deprecated_text=nil, deprecated_link_extra=nil, text: pagy_t('pagy.nav.prev'), link_extra: '')
-      text       = pagy_deprecated_arg(:text, deprecated_text, :text, text) if deprecated_text
-      link_extra = pagy_deprecated_arg(:link_extra, deprecated_link_extra, :link_extra, link_extra) if deprecated_link_extra
+      text       = Pagy.deprecated_arg(:text, deprecated_text, :text, text) if deprecated_text
+      link_extra = Pagy.deprecated_arg(:link_extra, deprecated_link_extra, :link_extra, link_extra) if deprecated_link_extra
       if pagy.prev
-        %(<span class="page prev"><a href="#{pagy_url_for(pagy.prev, pagy)}" rel="prev" aria-label="previous" #{pagy.vars[:link_extra]} #{link_extra}>#{text}</a></span>)
+        %(<span class="page prev"><a href="#{pagy_url_for(pagy, pagy.prev)}" rel="prev" aria-label="previous" #{pagy.vars[:link_extra]} #{link_extra}>#{text}</a></span>)
       else
         %(<span class="page prev disabled">#{text}</span>)
       end
     end
 
     def pagy_next_link(pagy, deprecated_text=nil, deprecated_link_extra=nil, text: pagy_t('pagy.nav.next'), link_extra: '')
-      text       = pagy_deprecated_arg(:text, deprecated_text, :text, text) if deprecated_text
-      link_extra = pagy_deprecated_arg(:link_extra, deprecated_link_extra, :link_extra, link_extra) if deprecated_link_extra
+      text       = Pagy.deprecated_arg(:text, deprecated_text, :text, text) if deprecated_text
+      link_extra = Pagy.deprecated_arg(:link_extra, deprecated_link_extra, :link_extra, link_extra) if deprecated_link_extra
       if pagy.next
-        %(<span class="page next"><a href="#{pagy_url_for(pagy.next, pagy)}" rel="next" aria-label="next" #{pagy.vars[:link_extra]} #{link_extra}>#{text}</a></span>)
+        %(<span class="page next"><a href="#{pagy_url_for(pagy, pagy.next)}" rel="next" aria-label="next" #{pagy.vars[:link_extra]} #{link_extra}>#{text}</a></span>)
       else
         %(<span class="page next disabled">#{text}</span>)
       end
     end
 
     def pagy_prev_link_tag(pagy)
-      %(<link href="#{pagy_url_for(pagy.prev, pagy)}" rel="prev"/>) if pagy.prev
+      %(<link href="#{pagy_url_for(pagy, pagy.prev)}" rel="prev"/>) if pagy.prev
     end
 
     def pagy_next_link_tag(pagy)
-      %(<link href="#{pagy_url_for(pagy.next, pagy)}" rel="next"/>) if pagy.next
+      %(<link href="#{pagy_url_for(pagy, pagy.next)}" rel="next"/>) if pagy.next
     end
 
   end
diff --git a/lib/pagy/extras/uikit.rb b/lib/pagy/extras/uikit.rb
index 5a7d1209b..392f790b3 100644
--- a/lib/pagy/extras/uikit.rb
+++ b/lib/pagy/extras/uikit.rb
@@ -25,7 +25,7 @@ def pagy_uikit_nav(pagy, pagy_id: nil, link_extra: '')
 
     # Javascript pagination for uikit: it returns a nav and a JSON tag used by the Pagy.nav javascript
     def pagy_uikit_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', steps: nil)
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id = %( id="#{pagy_id}") if pagy_id
       link = pagy_link_proc(pagy, link_extra)
       tags = { 'before' => pagy_uikit_prev_html(pagy, link),
@@ -40,7 +40,7 @@ def pagy_uikit_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '', ste
 
     # Javascript combo pagination for uikit: it returns a nav and a JSON tag used by the Pagy.combo_nav javascript
     def pagy_uikit_combo_nav_js(pagy, deprecated_id=nil, pagy_id: nil, link_extra: '')
-      pagy_id = pagy_deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
+      pagy_id = Pagy.deprecated_arg(:id, deprecated_id, :pagy_id, pagy_id) if deprecated_id
       p_id    = %( id="#{pagy_id}") if pagy_id
       link    = pagy_link_proc(pagy, link_extra)
       p_page  = pagy.page
diff --git a/lib/pagy/frontend.rb b/lib/pagy/frontend.rb
index 085880449..425c9e035 100644
--- a/lib/pagy/frontend.rb
+++ b/lib/pagy/frontend.rb
@@ -13,7 +13,8 @@ class Pagy
 
   module Helpers
     # This works with all Rack-based frameworks (Sinatra, Padrino, Rails, ...)
-    def pagy_url_for(page, pagy, url=nil)
+    def pagy_url_for(pagy, page, url=nil)
+      pagy, page = Pagy.deprecated_order(pagy, page) if page.is_a?(Pagy)
       p_vars = pagy.vars
       params = request.GET.merge(p_vars[:params])
       params[p_vars[:page_param].to_s] = page
@@ -60,7 +61,7 @@ def pagy_nav(pagy, pagy_id: nil, link_extra: '')
 
     # Return examples: "Displaying items 41-60 of 324 in total" of "Displaying Products 41-60 of 324 in total"
     def pagy_info(pagy, deprecated_item_name=nil, item_name: nil, i18n_key: nil)
-      item_name = pagy_deprecated_arg(:item_name, deprecated_item_name, :item_name, item_name) if deprecated_item_name
+      item_name = Pagy.deprecated_arg(:item_name, deprecated_item_name, :item_name, item_name) if deprecated_item_name
       p_count = pagy.count
       key     = if    p_count.zero?   then 'pagy.info.no_items'
                 elsif pagy.pages == 1 then 'pagy.info.single_page'
@@ -75,7 +76,7 @@ def pagy_info(pagy, deprecated_item_name=nil, item_name: nil, i18n_key: nil)
     def pagy_link_proc(pagy, link_extra='')
       p_prev = pagy.prev
       p_next = pagy.next
-      left, right = %(<a href="#{pagy_url_for PAGE_PLACEHOLDER, pagy}" #{pagy.vars[:link_extra]} #{link_extra}).split(PAGE_PLACEHOLDER, 2)
+      left, right = %(<a href="#{pagy_url_for pagy, PAGE_PLACEHOLDER}" #{pagy.vars[:link_extra]} #{link_extra}).split(PAGE_PLACEHOLDER, 2)
       lambda do |num, text=num, extra_attrs=''|
         %(#{left}#{num}#{right}#{ case num
                                   when p_prev then ' rel="prev"'
@@ -91,12 +92,5 @@ def pagy_t(key, **opts)
       Pagy::I18n.t @pagy_locale||=nil, key, **opts
     end
 
-    # deprecated arguments to remove in 5.0
-    def pagy_deprecated_arg(arg, val, new_key, new_val)
-      value = new_val || val  # we use the new_val if present
-      Warning.warn %([PAGY WARNING] deprecated positional `#{arg}` arg, it will be removed in 5.0! Use only the keyword arg `#{new_key}: #{value.inspect}` instead.\n)
-      value
-    end
-
   end
 end
diff --git a/pagy.manifest b/pagy.manifest
index 938c8f816..cc10fc6be 100644
--- a/pagy.manifest
+++ b/pagy.manifest
@@ -35,6 +35,7 @@ lib/locales/zh-TW.yml
 lib/pagy.rb
 lib/pagy/backend.rb
 lib/pagy/countless.rb
+lib/pagy/deprecation.rb
 lib/pagy/exceptions.rb
 lib/pagy/extras/arel.rb
 lib/pagy/extras/array.rb
diff --git a/test/pagy/derecation_test.rb b/test/pagy/derecation_test.rb
new file mode 100644
index 000000000..0fb6d8ca5
--- /dev/null
+++ b/test/pagy/derecation_test.rb
@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../test_helper'
+
+describe 'pagy/deprecation' do
+  
+  describe 'Pagy.deprecated_arg' do
+    it 'deprecate arg and returns right value' do
+      _ { _(Pagy.deprecated_arg(:arg, 'deprecated-val', :new_key, 'new-value')).must_equal 'new-value' }.must_output nil, \
+          "[PAGY WARNING] deprecated use of positional `arg` arg will not be supported in 5.0! Use only the keyword arg `new_key: \"new-value\"` instead."
+    end
+  end
+
+  describe 'Pagy.deprecated_order' do
+    it 'deprecate arg order and returns them inverted' do
+      _ { _(Pagy.deprecated_order('page', 'pagy')).must_equal %w[pagy page] }.must_output nil, \
+          "[PAGY WARNING] inverted use of pagy/page in pagy_url_for will not be supported in 5.0! Use pagy_url_for(pagy, page) instead."
+    end    
+  end
+end
diff --git a/test/pagy/extras/items_countless_test.rb b/test/pagy/extras/items_countless_test.rb
index 4b047f3de..ba76fd63d 100644
--- a/test/pagy/extras/items_countless_test.rb
+++ b/test/pagy/extras/items_countless_test.rb
@@ -131,23 +131,23 @@
     describe '#pagy_url_for' do
       it 'renders basic url' do
         pagy = Pagy.new count: 1000, page: 3
-        _(view.pagy_url_for(5, pagy)).must_equal '/foo?page=5&items=20'
+        _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5&items=20'
       end
       it 'renders basic url and items var' do
         pagy = Pagy.new count: 1000, page: 3, items: 50
-        _(view.pagy_url_for(5, pagy)).must_equal '/foo?page=5&items=50'
+        _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5&items=50'
       end
       it 'renders url with items_params' do
         pagy = Pagy.new count: 1000, page: 3, items_param: :custom
-        _(view.pagy_url_for(5, pagy)).must_equal '/foo?page=5&custom=20'
+        _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5&custom=20'
       end
       it 'renders url with anchor' do
         pagy = Pagy.new count: 1000, page: 3, anchor: '#anchor'
-        _(view.pagy_url_for(6, pagy)).must_equal '/foo?page=6&items=20#anchor'
+        _(view.pagy_url_for(pagy, 6)).must_equal '/foo?page=6&items=20#anchor'
       end
       it 'renders url with params and anchor' do
         pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, anchor: '#anchor', items: 40
-        _(view.pagy_url_for(5, pagy)).must_equal "/foo?page=5&a=3&b=4&items=40#anchor"
+        _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4&items=40#anchor"
       end
     end
     it 'renders items selector with countless' do
diff --git a/test/pagy/extras/items_elasticsearch_test.rb b/test/pagy/extras/items_elasticsearch_test.rb
index c18b80b98..5224bd14b 100644
--- a/test/pagy/extras/items_elasticsearch_test.rb
+++ b/test/pagy/extras/items_elasticsearch_test.rb
@@ -132,23 +132,23 @@
     describe '#pagy_url_for' do
       it 'renders basic url' do
         pagy = Pagy.new count: 1000, page: 3
-        _(view.pagy_url_for(5, pagy)).must_equal '/foo?page=5&items=20'
+        _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5&items=20'
       end
       it 'renders basic url and items var' do
         pagy = Pagy.new count: 1000, page: 3, items: 50
-        _(view.pagy_url_for(5, pagy)).must_equal '/foo?page=5&items=50'
+        _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5&items=50'
       end
       it 'renders url with items_params' do
         pagy = Pagy.new count: 1000, page: 3, items_param: :custom
-        _(view.pagy_url_for(5, pagy)).must_equal '/foo?page=5&custom=20'
+        _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5&custom=20'
       end
       it 'renders url with anchor' do
         pagy = Pagy.new count: 1000, page: 3, anchor: '#anchor'
-        _(view.pagy_url_for(6, pagy)).must_equal '/foo?page=6&items=20#anchor'
+        _(view.pagy_url_for(pagy, 6)).must_equal '/foo?page=6&items=20#anchor'
       end
       it 'renders url with params and anchor' do
         pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, anchor: '#anchor', items: 40
-        _(view.pagy_url_for(5, pagy)).must_equal "/foo?page=5&a=3&b=4&items=40#anchor"
+        _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4&items=40#anchor"
       end
     end
     it 'renders items selector with elasticsearch' do
diff --git a/test/pagy/frontend_test.rb b/test/pagy/frontend_test.rb
index 15d9080b2..a71c04959 100644
--- a/test/pagy/frontend_test.rb
+++ b/test/pagy/frontend_test.rb
@@ -131,23 +131,23 @@
   describe '#pagy_url_for' do
     it 'renders basic url' do
       pagy = Pagy.new count: 1000, page: 3
-      _(view.pagy_url_for(5, pagy)).must_equal '/foo?page=5'
-      _(view.pagy_url_for(5, pagy, :url)).must_equal 'http://example.com:3000/foo?page=5'
+      _(view.pagy_url_for(pagy, 5)).must_equal '/foo?page=5'
+      _(view.pagy_url_for(pagy, 5, :url)).must_equal 'http://example.com:3000/foo?page=5'
     end
     it 'renders url with params' do
       pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}
-      _(view.pagy_url_for(5, pagy)).must_equal "/foo?page=5&a=3&b=4"
-      _(view.pagy_url_for(5, pagy, :url)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4"
+      _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4"
+      _(view.pagy_url_for(pagy, 5, :url)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4"
     end
     it 'renders url with anchor' do
       pagy = Pagy.new count: 1000, page: 3, anchor: '#anchor'
-      _(view.pagy_url_for(6, pagy)).must_equal '/foo?page=6#anchor'
-      _(view.pagy_url_for(6, pagy, :url)).must_equal 'http://example.com:3000/foo?page=6#anchor'
+      _(view.pagy_url_for(pagy, 6)).must_equal '/foo?page=6#anchor'
+      _(view.pagy_url_for(pagy, 6, :url)).must_equal 'http://example.com:3000/foo?page=6#anchor'
     end
     it 'renders url with params and anchor' do
       pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, anchor: '#anchor'
-      _(view.pagy_url_for(5, pagy)).must_equal "/foo?page=5&a=3&b=4#anchor"
-      _(view.pagy_url_for(5, pagy, :url)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4#anchor"
+      _(view.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&a=3&b=4#anchor"
+      _(view.pagy_url_for(pagy, 5, :url)).must_equal "http://example.com:3000/foo?page=5&a=3&b=4#anchor"
     end
   end
 
@@ -155,14 +155,8 @@
     it 'overrides params' do
       overridden = MockView::Overridden.new
       pagy = Pagy.new count: 1000, page: 3, params: {a: 3, b: 4}, anchor: '#anchor'
-      _(overridden.pagy_url_for(5, pagy)).must_equal "/foo?page=5&b=4&k=k#anchor"
+      _(overridden.pagy_url_for(pagy, 5)).must_equal "/foo?page=5&b=4&k=k#anchor"
     end
   end
 
-  describe '#pagy_deprecated_arg' do
-    it 'deprecate arg and returns right value' do
-      _ { _(view.pagy_deprecated_arg(:arg, 'deprecated-val', :new_key, 'new-value')).must_equal 'new-value' }.must_output nil, \
-        "[PAGY WARNING] deprecated positional `arg` arg, it will be removed in 5.0! Use only the keyword arg `new_key: \"new-value\"` instead.\n"
-    end
-  end
 end