Pagination Links

The response is returning a paginated list, and it even has extra count and total
fields. Now we need to add those next, previous, first and last links. And
since the response is entirely created via this PaginatedCollection class, this
is simple: just add a new private $_links = array(); property:

To actually add links, create a new function called public function addLink()
that has two arguments: the $ref - that's the name of the link, like
first or last - and the $url. Add the link with $this->_links[$ref] = $url;.
Great - now head back to the controller:

Every link will point to the same route, but with a different page query parameter.
The route to this controller doesn't have a name yet, so give it one:
api_programmers_collection. Copy that name and set it to a $route variable:

Next, create $routeParams: this will hold any wildcards that need to be passed
to the route - meaning the curly brace parts in its path. This route doesn't have
any, so set leave it empty. We're already setting things up to be reusable for other
paginated responses.

Since we need to generate four links, create an anonymous function to help out
with this: $createLinkUrl = function(). Give it one argument $targetPage. Also,
add use for $route and $routeParams so we can access those inside. To generate
the URL, use the normal return $this->generateURL() passing it the $route and an
array_merge() of any routeParams with a new page key:

Since there's no {page} routing wildcard, the router will add a ?page= query
parameter to the end, exactly how we want it to.

Sweet! Add the first link with $paginatedCollection->addLink(). Call this link self
and use $page to point to the current page. It might seem silly to link to this
page, but it's a pretty standard thing to do:

The last two links are next and previous... but wait! We don't always have
a next or previous page: these should be conditional. Add: if($pagerfanta->hasNextPage()),
well, then, of course we want to generate a link to $pagerfanta->getNextPage()
that's called next:

The link keys - self, first, last, next and prev are actually called link
rels, or relations. They have a very important purpose: to explain the meaning
of the link. On the web, the link's text tells us what that link points to. In an
API, the "rel" does that job.

In other words, as long as our API client understands first means the first page
of results and next means the next page of results, you can communicate the significance
of what those links are.

And you know what else? I didn't just invent these link rels. They're super-official
IANA rels - an organization that tries to standardize some of this stuff. Why is
that cool? Because if everyone used these same links for pagination, understanding
API's would be easier and more consistent.

We are going to talk about links a lot more in a future episode - including all
those buzzwords like hypermedia and HATEOAS. So sit tight.

Why use that $createLinkUrl function instead of creating private function?

2016-07-05weaverryan

Wow, very clean. I really appreciate you posting your complete solutions inside here - it will definitely help others :)

Thanks!

2016-07-05Vlad

Hi Ryan,

I was also able to accomplish this by using a custom ORM adapter that implements AdapterInterface and the 2 interface methods. Its constructor has two parameters: a query to get the collection of items and a query to get the total number of items.

Here is the code:

use Doctrine\ORM\QueryBuilder;use Pagerfanta\Adapter\AdapterInterface;

So, output walkers are really advanced. An output walker - which is a less common thing to worry about, there are also tree walkers, which modify the AST - is responsible for turning the "DQL" (represented by an abstract syntax tree - AST) into the actual SQL. In essence, this the actual code that turns the AST into the actual query string. Here's the default walker: https://github.com/doctrine...

In the pagination library, they use a sub-class of this walker: https://github.com/doctrine... - which helps to "count" the query result, used for pagination. That's what you turned off. I'm honestly not sure what the result of that is - but if it works, do it :). Pagination is quite "magical" - since Doctrine needs to take your query and dynamically change it so that it can first get a COUNT of those potential results (without actually fetching all of them). The only thing I'd double-check is that the pagination library is not now querying for ALL the rows, just to get a count of them. Double-check that in the profiler.

Cheers!

2016-06-28Vlad

Hi Ryan,I just got it to work! Turns out I had to disable output walkers.

I changed the following line in PaginationFactory::createCollection()

new DoctrineORMAdapter($queryBuilder);

to

new DoctrineORMAdapter($queryBuilder, true, false);

thus setting the $useOutputWalkers parameter to false.

My query is a DTO query with the NEW operator, with 5 joins.

What are output walkers anyway, and in which cases are they needed?Thank you for your hints.

2016-06-28weaverryan

Hey Vlad!

Hmm, interesting! I don't have experience doing this, but in theory, I would be surprised if it's not supported. The error specifically is coming from Doctrine (not the paginator library itself), so changing libraries (probably) won't help.

Could you post your query? By looking at the code in Doctrine near where that error is thrown, it looks like it might be complaining that there is no "root alias" in the query, which means it may just be the query itself that's causing the problems. If you haven't tried it yet, try including the primary key (e.g. alias.id) in the results.

Hi,When I pass a query (e.g. $em->createQuery), instead of a query builder to this paginator, I get an error: ​"The Paginator does not support Queries which only yield ScalarResults.". Is there a paginator I can use with a query that returns scalar results?Thank you!

2016-06-08Chuck Norris

Hi,

thanks for the quick answer.I just saw that when I take a quick look to the rest of the course.

Any way, great job.

2016-06-08Victor Bocharsky

Hey Chuck!

Thank you!

Great question! HATEOS bundle is really cool! But we don't want to show this topic in basics and kept it for the next episode (Symfony REST 5) which was already released a few weeks ago. You can check it http://knpuniversity.com/sc... .

Cheers!

2016-06-07Chuck Norris

Hi,

Great tutorial,

But why not using HATEOS bundle to generate links like you do in silex rest tutorial ?