Relations & Iris

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

When we tried to create a DragonTreasure with this owner, we set the field to the owner's database id. And we found out that API Platform did not like that. It said: "expected IRI". But what is an IRI?

We mentioned this term once earlier in the tutorial. Go back down to the GET /api/users collection endpoint. We know that every resource has an @id field set to the URL where you can fetch that resource. This is the IRI or "International Resource Identifier". It's meant to be a unique identifier across your entire API - like across all resources.

Think about it: the number "1" is not a unique identifier - we might have a DragonTreasure with that id and a User. But the IRI is unique. And, a URL is also just a heck of a lot more handy than an integer anyways.

So when we want to set a relation property, we need to also use the IRI, like /api/users/1.

When we hit Execute, it works! A 201 status code. In the returned JSON, no surprise, the owner field also comes back as an IRI.

The takeaway from all of this is delightfully simple. Relations are just normal fields... but we get and set them via their IRI string. This is such a beautiful and clean way to handle this.

Adding a Collection dragonTreasures Relation Field

Ok, let's talk about the other side of this relationship. Refresh the whole page and go to the GET one user endpoint. Try this with a real user id - like 1 for me. And... there's the data.

So the question I have now is: could we add a dragonTreasures field that shows all the treasures that this user owns?

Well, let's think about it. We know that the serializer works by grabbing all accessible properties on an object that are in the normalization group. And... we do have a dragonTreasures property on User.

            
            171 lines
            
            src/Entity/User.php
        
                                                    ... lines 1 - 22
                            
            class User implements UserInterface, PasswordAuthenticatedUserInterface
        
            {
        
                                                    ... lines 25 - 50
                            
                #[ORM\OneToMany(mappedBy: 'owner', targetEntity: DragonTreasure::class)]
        
                private Collection $dragonTreasures;
        
                                                    ... lines 53 - 169
                            
            }

So... it should just work! To expose the field to the API, add it to the serialization group user:read. Later, we'll talk about how we can write to a collection field... but for now, just make it readable.

            
            172 lines
            
            src/Entity/User.php
        
                                                    ... lines 1 - 22
                            
            class User implements UserInterface, PasswordAuthenticatedUserInterface
        
            {
        
                                                    ... lines 25 - 50
                            
                #[ORM\OneToMany(mappedBy: 'owner', targetEntity: DragonTreasure::class)]
        
                #[Groups(['user:read'])]
        
                private Collection $dragonTreasures;
        
                                                    ... lines 54 - 170
                            
            }

Ok! Refresh... and look at the same GET endpoint. Down here, cool! It shows a new dragonTreasures field in the example response. Let's try it: use the same id, hit "Execute" and... oh, gorgeous: it returns an array of IRI strings! I love that! And, of course, if we need more information about these, we can make a request to any of these URLs to get all the shiny details.

And to get really fancy, you could use Vulcain so that users can "preload" those relations... meaning the server will push the data directly to the client.

But as cool as this is, it does lead me to a question: what if needing the DragonTreasure data for a user is so common that, to avoid extra requests, we want to embed the data right here - like JSON objects instead of IRI strings?

Can we do that? Absolutely. Let's find out how next.

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "api-platform/core": "^3.0", // v3.0.8
        "doctrine/annotations": "^1.0", // 1.14.2
        "doctrine/doctrine-bundle": "^2.8", // 2.8.0
        "doctrine/doctrine-migrations-bundle": "^3.2", // 3.2.2
        "doctrine/orm": "^2.14", // 2.14.0
        "nelmio/cors-bundle": "^2.2", // 2.2.0
        "nesbot/carbon": "^2.64", // 2.64.1
        "phpdocumentor/reflection-docblock": "^5.3", // 5.3.0
        "phpstan/phpdoc-parser": "^1.15", // 1.15.3
        "symfony/asset": "6.2.*", // v6.2.0
        "symfony/console": "6.2.*", // v6.2.3
        "symfony/dotenv": "6.2.*", // v6.2.0
        "symfony/expression-language": "6.2.*", // v6.2.2
        "symfony/flex": "^2", // v2.2.4
        "symfony/framework-bundle": "6.2.*", // v6.2.3
        "symfony/property-access": "6.2.*", // v6.2.3
        "symfony/property-info": "6.2.*", // v6.2.3
        "symfony/runtime": "6.2.*", // v6.2.0
        "symfony/security-bundle": "6.2.*", // v6.2.3
        "symfony/serializer": "6.2.*", // v6.2.3
        "symfony/twig-bundle": "6.2.*", // v6.2.3
        "symfony/ux-react": "^2.6", // v2.6.1
        "symfony/validator": "6.2.*", // v6.2.3
        "symfony/webpack-encore-bundle": "^1.16", // v1.16.0
        "symfony/yaml": "6.2.*" // v6.2.2
    },
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.4", // 3.4.2
        "symfony/debug-bundle": "6.2.*", // v6.2.1
        "symfony/maker-bundle": "^1.48", // v1.48.0
        "symfony/monolog-bundle": "^3.0", // v3.8.0
        "symfony/stopwatch": "6.2.*", // v6.2.0
        "symfony/web-profiler-bundle": "6.2.*", // v6.2.4
        "zenstruck/foundry": "^1.26" // v1.26.0
    }
}

Edit on GitHub

TRACK

APIs >

COURSE

API Platform 3 Part 1: Mythically Good RESTful APIs

Relations & Iris

Keep on Learning!

Adding a Collection dragonTreasures Relation Field

Leave a comment!

What PHP libraries does this tutorial use?

	... lines 1 - 22
	class User implements UserInterface, PasswordAuthenticatedUserInterface
	{
	... lines 25 - 50
	#[ORM\OneToMany(mappedBy: 'owner', targetEntity: DragonTreasure::class)]
	private Collection $dragonTreasures;
	... lines 53 - 169
	}