Flag of Ukraine
SymfonyCasts stands united with the people of Ukraine
TRACK

APIs >

COURSE

Symfony RESTful API: Hypermedia, Links & Bonuses (Course 5)

Buy Access to Course
This tutorial has a new version, check it out!

Rock-Solid, Consistent Collection Endpoints

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00
Previous Chapter

Next Chapter
Edit on GitHub

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

Go back to the test we're working on right now. First, every collection should have an items key for consistency. Assert that with $this->asserter()->assertResponsePropertyExists() for items:

318 lines tests/AppBundle/Controller/Api/ProgrammerControllerTest.php
... lines 1 - 7
class ProgrammerControllerTest extends ApiTestCase
{
... lines 10 - 64
public function testFollowProgrammerBattlesLink()
{
... lines 67 - 86
$this->asserter()->assertResponsePropertyExists($response, 'items');
$this->debugResponse($response);
}
... lines 90 - 316
}

Pagination in the Past

Next, open ProgrammerController. The whole reason the other endpoint had an items key was because - in listAction() - we went through our fancy pagination system. Click into the pagination_factory. The key part is that this method eventually creates a PaginatedCollection object:

58 lines src/AppBundle/Pagination/PaginationFactory.php
... lines 1 - 10
class PaginationFactory
{
... lines 13 - 19
public function createCollection(QueryBuilder $qb, Request $request, $route, array $routeParams = array())
{
... lines 22 - 33
$paginatedCollection = new PaginatedCollection($programmers, $pagerfanta->getNbResults());
... lines 35 - 55
return $paginatedCollection;
}
}

This is what we feed to the serializer.

The PaginatedCollection object is something we created. And hey! It has an $items property! So this isn't rocket science. It also has a few other properties: total, count and the pagination links:

27 lines src/AppBundle/Pagination/PaginatedCollection.php
... lines 1 - 4
class PaginatedCollection
{
private $items;
private $total;
private $count;
private $_links = array();
... lines 14 - 25
}

So if we want every collection endpoint to be identical, every endpoint should return a PaginatedCollection.

Creating a PaginatedCollection

We could do this the simple way: $collection = new PaginatedCollection() and pass it $battles and the total items - which right now is count($battles):

165 lines src/AppBundle/Controller/Api/ProgrammerController.php
... lines 1 - 23
class ProgrammerController extends BaseController
{
... lines 26 - 154
public function battlesListAction(Programmer $programmer)
{
$battles = $this->getDoctrine()->getRepository('AppBundle:Battle')
->findBy(['programmer' => $programmer]);
$collection = new PaginatedCollection($battles, count($battles));
... lines 161 - 162
}
}

There's not actually any pagination going on.

At the bottom, pass that $collection to createApiResponse():

165 lines src/AppBundle/Controller/Api/ProgrammerController.php
... lines 1 - 23
class ProgrammerController extends BaseController
{
... lines 26 - 154
public function battlesListAction(Programmer $programmer)
{
$battles = $this->getDoctrine()->getRepository('AppBundle:Battle')
->findBy(['programmer' => $programmer]);
$collection = new PaginatedCollection($battles, count($battles));
return $this->createApiResponse($collection);
}
}

Done! Run that test:

./vendor/bin/phpunit --filter testFollowProgrammerBattlesLink

Yes! Now we have an items key, and total, count and _links... which is empty.

Adding Real Pagination

And really: if we're going to all of this trouble to use the PaginatedCollection, shouldn't we go one extra half-step and actually add pagination? After all, it'll make this endpoint even more consistent by having those pagination links.

Change the $collection = line to $this->get('pagination_factory')->createCollection():

170 lines src/AppBundle/Controller/Api/ProgrammerController.php
... lines 1 - 23
class ProgrammerController extends BaseController
{
... lines 26 - 154
public function battlesListAction(Programmer $programmer, Request $request)
{
... lines 157 - 159
$collection = $this->get('pagination_factory')->createCollection(
... lines 161 - 164
);
... lines 166 - 167
}
}

This needs a few arguments. The first is a query builder. So instead of making this full query for battles, we need to just return the query builder. Rename this to a new method called - createQueryBuilderForProgrammer() and pass it the $programmer object:

170 lines src/AppBundle/Controller/Api/ProgrammerController.php
... lines 1 - 23
class ProgrammerController extends BaseController
{
... lines 26 - 154
public function battlesListAction(Programmer $programmer, Request $request)
{
$battlesQb = $this->getDoctrine()->getRepository('AppBundle:Battle')
->createQueryBuilderForProgrammer($programmer);
... lines 159 - 167
}
}

I'll hold command and I'll click Battle to jump into BattleRepository. Add that method: public function createQueryBuilderForProgrammer() with a Programmer $programmer argument:

17 lines src/AppBundle/Repository/BattleRepository.php
... lines 1 - 4
use AppBundle\Entity\Programmer;
... lines 6 - 7
class BattleRepository extends EntityRepository
{
public function createQueryBuilderForProgrammer(Programmer $programmer)
{
... lines 12 - 14
}
}

Fortunately, the query is easy: return $this->createQueryBuilder('battle'), then ->andWhere('battle.programmer = :programmer') with setParameter('programmer', $programmer):

17 lines src/AppBundle/Repository/BattleRepository.php
... lines 1 - 7
class BattleRepository extends EntityRepository
{
public function createQueryBuilderForProgrammer(Programmer $programmer)
{
return $this->createQueryBuilder('battle')
->andWhere('battle.programmer = :programmer')
->setParameter('programmer', $programmer);
}
}

Perfect! Back in ProgrammerController, rename the variable to $battlesQb and pass it to createCollection():

170 lines src/AppBundle/Controller/Api/ProgrammerController.php
... lines 1 - 23
class ProgrammerController extends BaseController
{
... lines 26 - 154
public function battlesListAction(Programmer $programmer, Request $request)
{
$battlesQb = $this->getDoctrine()->getRepository('AppBundle:Battle')
->createQueryBuilderForProgrammer($programmer);
$collection = $this->get('pagination_factory')->createCollection(
$battlesQb,
... lines 162 - 164
);
... lines 166 - 167
}
}

The second argument is the request object. You guys know what to do: type-hint a new argument with Request and pass that in:

170 lines src/AppBundle/Controller/Api/ProgrammerController.php
... lines 1 - 16
use Symfony\Component\HttpFoundation\Request;
... lines 18 - 23
class ProgrammerController extends BaseController
{
... lines 26 - 154
public function battlesListAction(Programmer $programmer, Request $request)
{
$battlesQb = $this->getDoctrine()->getRepository('AppBundle:Battle')
->createQueryBuilderForProgrammer($programmer);
$collection = $this->get('pagination_factory')->createCollection(
$battlesQb,
$request,
... lines 163 - 164
);
... lines 166 - 167
}
}

The third argument is the name of the route the pagination links should point to. That's this route: api_programmers_battles_list. Finally, the last argument is any route parameters that need to be passed to the route. This route has a nickname, so pass nickname => $programmer->getNickname():

170 lines src/AppBundle/Controller/Api/ProgrammerController.php
... lines 1 - 23
class ProgrammerController extends BaseController
{
... lines 26 - 154
public function battlesListAction(Programmer $programmer, Request $request)
{
... lines 157 - 159
$collection = $this->get('pagination_factory')->createCollection(
$battlesQb,
$request,
'api_programmers_battles_list',
['nickname' => $programmer->getNickname()]
);
... lines 166 - 167
}
}

Done. We basically changed one line to create a real paginated collection. And now, we celebrate. Run the test:

./vendor/bin/phpunit --filter testFollowProgrammerBattlesLink

That is real pagination pretty much out of the box. Yea, this only has three results and only one page: but if this programmer keeps having battles, we're covered.

We've really perfected a lot of traditional REST endpoints. Now, let's talk about what happens when endpoints get weird...

Leave a comment!

Most Useful Newest Oldest
0
Login or Register to join the conversation
Cat in space

"Houston: no signs of life"
Start the conversation!

This tutorial uses an older version of Symfony. The concepts of Hypermedia & HATEOAS are still valid. But I recommend using API Platform in modern Symfony apps.
Symfony 3

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=5.5.9",
        "symfony/symfony": "3.0.*", // v3.0.3
        "doctrine/orm": "^2.5", // v2.5.4
        "doctrine/doctrine-bundle": "^1.6", // 1.6.2
        "doctrine/doctrine-cache-bundle": "^1.2", // 1.3.0
        "symfony/swiftmailer-bundle": "^2.3", // v2.3.11
        "symfony/monolog-bundle": "^2.8", // v2.10.0
        "sensio/distribution-bundle": "^5.0", // v5.0.4
        "sensio/framework-extra-bundle": "^3.0.2", // v3.0.14
        "incenteev/composer-parameter-handler": "~2.0", // v2.1.2
        "jms/serializer-bundle": "^1.1.0", // 1.1.0
        "white-october/pagerfanta-bundle": "^1.0", // v1.0.5
        "lexik/jwt-authentication-bundle": "^1.4", // v1.4.3
        "willdurand/hateoas-bundle": "^1.1" // 1.1.1
    },
    "require-dev": {
        "sensio/generator-bundle": "^3.0", // v3.0.6
        "symfony/phpunit-bridge": "^3.0", // v3.0.3
        "behat/behat": "~3.1@dev", // dev-master
        "behat/mink-extension": "~2.2.0", // v2.2
        "behat/mink-goutte-driver": "~1.2.0", // v1.2.1
        "behat/mink-selenium2-driver": "~1.3.0", // v1.3.1
        "phpunit/phpunit": "~4.6.0", // 4.6.10
        "doctrine/doctrine-fixtures-bundle": "^2.3" // 2.3.0
    }
}
Edit on GitHub
Previous Chapter
Next Chapter
userVoice