DBIx::C...t::Pager(3)

💅 DBIx::C...t::Pager(3) — the group-chat remix

okay so real talk, this is a page from the User Contributed Perl Documentation fam, and bestie, it's about paging through result sets without having a math meltdown. pull up a chair 🎀

---

✨ NAME ✨

DBIx::Class::ResultSet::Pager — literally here to help you when you're paging through sets of results 💖

---

🦋 SYNOPSIS 🦋

use DBIx::Class::ResultSet::Pager;

my $page = DBIx::Class::ResultSet::Pager->new();
$page->total_entries($total_entries);
$page->entries_per_page($entries_per_page);
$page->current_page($current_page);

print "         First page: ", $page->first_page, "\n";
print "          Last page: ", $page->last_page, "\n";
print "First entry on page: ", $page->first, "\n";
print " Last entry on page: ", $page->last, "\n";

---

🌸 DESCRIPTION 🌸

so this module is a near-verbatim copy of Data::Page 2.02 — https://metacpan.org/pod/release/LBROCARD/Data-Page-2.02/lib/Data/Page.pm — which stayed completely unchanged on CPAN from late 2009 all the way through late 2019. iconic longevity honestly 👑

The only diffs? It drops a bunch of accessor generators in lieu of direct method implementations, and it folds in the lazily evaluated total_entries, which was the only bit originally provided by DBIx::Class::ResultSet::Pager. And this module passes the entire contemporary test suite of Data::Page unmodified. no cap, not one test touched 🔥

💀 WHAT FOLLOWS IS A VERBATIM COPY OF Data::Page's 2.02 DOCUMENTATION 💀

When you're searching through large amounts of data, it's often the case that the result set coming back is bigger than what you actually wanna display on one page. so now you're paging. and the maths behind that? unfortunately fiddly. hence this module, bestie 🫶

The main concept: you pass in the number of total entries, the number of entries per page, and the current page number. then you call methods to find out how many pages of info there are, and what number the first and last entries on the current page really are.

For example, say we wished to page through the integers from 1 to 100 with 20 entries per page. The first page would consist of 1-20, the second page from 21-40, the third page from 41-60, the fourth page from 61-80 and the fifth page from 81-100. This module would help you work this out. math? handled. 💅

---

⭐ METHODS ⭐

🎀 new

This is the constructor, and it takes no arguments.

my $page = DBIx::Class::ResultSet::Pager->new();

There is also an old, deprecated constructor — currently takes two mandatory arguments, the total number of entries and the number of entries per page. It also optionally takes the current page number:

my $page = DBIx::Class::ResultSet::Pager->new($total_entries, $entries_per_page, $current_page);

yo, heads up: that second one is deprecated. it still works, but it's giving legacy energy 🙈

🎀 total_entries

This method gets or sets the total number of entries:

print "Entries:", $page->total_entries, "\n";

🎀 entries_per_page

This method gets or sets the total number of entries per page — and it defaults to 10:

print "Per page:", $page->entries_per_page, "\n";

🎀 current_page

This method gets or sets the current page number — and it defaults to 1:

print "Page: ", $page->current_page, "\n";

🎀 entries_on_this_page

This method returns the number of entries on the current page:

print "There are ", $page->entries_on_this_page, " entries displayed\n";

🎀 first_page

This method returns the first page. It's here purely for symmetry with last_page, because it always returns 1:

print "Pages range from: ", $page->first_page, "\n";

🎀 last_page

This method returns the total number of pages of information:

print "Pages range to: ", $page->last_page, "\n";

🎀 first

This method returns the number of the first entry on the current page:

print "Showing entries from: ", $page->first, "\n";

🎀 last

This method returns the number of the last entry on the current page:

print "Showing entries to: ", $page->last, "\n";

🎀 previous_page

This method returns the previous page number, if one exists. Otherwise it returns undefined:

if ($page->previous_page) {
  print "Previous page number: ", $page->previous_page, "\n";
}

🎀 next_page

This method returns the next page number, if one exists. Otherwise it returns undefined:

if ($page->next_page) {
  print "Next page number: ", $page->next_page, "\n";
}

🎀 splice

This method takes in a listref, and returns only the values which are on the current page:

@visible_holidays = $page->splice(\@holidays);

🎀 skipped

This method is lowkey the MVP for paging through data in a database using SQL LIMIT clauses. It is simply $page->first - 1:

$sth = $dbh->prepare(
  q{SELECT * FROM table ORDER BY rec_date LIMIT ?, ?}
);
$sth->execute($page->skipped, $page->entries_per_page);

🎀 change_entries_per_page

This method changes the number of entries per page and the current page number, so that the first item on the current page will still be present on the new page. it keeps your place, bestie 🧚

$page->total_entries(50);
$page->entries_per_page(20);
$page->current_page(3);
print $page->first; # 41
$page->change_entries_per_page(30);
print $page->current_page; # 2 - the page that item 41 will show in

---

🌈 NOTES 🌈

It has been said before that this code is "too simple" for CPAN, but I must disagree. I have seen people write this kind of code over and over again and they always get it wrong. Perhaps now they will spend more time getting the rest of their code right... 💀 honestly? read.

Based on code originally by Leo Lapworth, with many changes added by by Leon Brocard <acme@astray.com>, and few enhancements by James Laver (ELPENGUIN).

---

🫶 FURTHER QUESTIONS? 🫶

Check the list of additional DBIC resources.

---

👑 COPYRIGHT AND LICENSE 👑

This module is free software copyright by the DBIx::Class (DBIC) authors. You can redistribute it and/or modify it under the same terms as the DBIx::Class library.

---

and that's the whole page, periodt ✨ this was perl v5.42.0, dated 2025-01-22, filed under DBIx::C...t::Pager(3) — go forth and paginate responsibly, bestie 💜