If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.
With a Subscription, click any sentence in the script to jump to that part of the video!
Login SubscribeLet's get wild. I want to add a totally custom, crazy new field to our DragonTreasure
API that does not correspond to any property in our class. Well, actually, we learned in part 1 of this series that adding custom fields is possible by creating a getter method and adding a serialization group above it. But, that solution only works if we can calculate the field's value solely from the data on the object. If, for example, we need to call a service to get the data, then we're out of luck.
Adding a new field whose data is calculated from a service is another trick up the custom normalizer's sleeve. And since we already have one set up, I thought we'd use it to see how this works.
Go to DragonTreasureResourceTest
and find testOwnerCanSeeIsPublishedField()
. Rename this to testOwnerCanSeeIsPublishedAndIsMineFields()
:
... lines 1 - 12 | |
class DragonTreasureResourceTest extends ApiTestCase | |
{ | |
... lines 15 - 158 | |
public function testOwnerCanSeeIsPublishedAndIsMineFields(): void | |
{ | |
... lines 161 - 178 | |
} | |
} |
This is a bit silly, but if we own a DragonTreasure
, we're going to add a new boolean property called $isMine
set to true
. So, down at the bottom, we'll say isMine
and expect it to be true
:
... lines 1 - 12 | |
class DragonTreasureResourceTest extends ApiTestCase | |
{ | |
... lines 15 - 158 | |
public function testOwnerCanSeeIsPublishedAndIsMineFields(): void | |
{ | |
... lines 161 - 166 | |
$this->browser() | |
... lines 168 - 175 | |
->assertJsonMatches('isPublished', false) | |
->assertJsonMatches('isMine', true) | |
; | |
} | |
} |
Copy that method name, then spin over and run this test:
symfony php bin/phpunit --filter=testOwnerCanSeeIsPublishedAndIsMineFields
Tada! It's null
because the field doesn't exist yet.
So how can we add this? Now that we've gone through the pain of getting the normalizer set up, it's easy! The normalizer system will do its thing, return the normalized data, then, between that and the return
statement, we can... just mess with it!
... lines 1 - 12 | |
class AddOwnerGroupsNormalizer implements NormalizerInterface, SerializerAwareInterface | |
{ | |
... lines 15 - 18 | |
public function normalize(mixed $object, string $format = null, array $context = []): array|string|int|float|bool|\ArrayObject|null | |
{ | |
if ($object instanceof DragonTreasure && $this->security->getUser() === $object->getOwner()) { | |
$context['groups'][] = 'owner:read'; | |
} | |
$normalized = $this->normalizer->normalize($object, $format, $context); | |
... lines 26 - 30 | |
return $normalized; | |
} | |
... lines 33 - 44 | |
} |
Copy the if statement from up here. I could be more clever and reuse code, but it's fine. If the object is a DragonTreasure
and we own this DragonTreasure
, we will say $normalized['isMine'] = true
:
... lines 1 - 12 | |
class AddOwnerGroupsNormalizer implements NormalizerInterface, SerializerAwareInterface | |
{ | |
... lines 15 - 18 | |
public function normalize(mixed $object, string $format = null, array $context = []): array|string|int|float|bool|\ArrayObject|null | |
{ | |
... lines 21 - 24 | |
$normalized = $this->normalizer->normalize($object, $format, $context); | |
if ($object instanceof DragonTreasure && $this->security->getUser() === $object->getOwner()) { | |
$normalized['isMine'] = true; | |
} | |
return $normalized; | |
} | |
... lines 33 - 44 | |
} |
That's it! When we run the test:
symfony php bin/phpunit --filter=testOwnerCanSeeIsPublishedAndIsMineFields
All green!
But there's a practical downside to these custom fields: they will not be documented in our API. Our API docs have no idea that this exists!
If you do need a super-duper custom field that requires service logic... and you do need it to be documented, you have two options. First, you could add a non-persisted isMe
property to your class then populate it with a state provider. We haven't talked about state providers yet, but they're how data is loaded. For example, our classes are already using a Doctrine state provider behind the scenes to query the database. We'll cover state providers in part 3 of this series.
The second solution would be to use the custom normalizer like we did, then try to add the field to the OpenAPI docs manually via the OpenAPI factory trick that we showed earlier.
Next: suppose a user is allowed to edit something... but there are certain changes to the data that they are not allowed to make - like they could set a field to foo
but they aren't allowed to change it to bar
because they don't have enough permissions. How should we handle that? It's security meets validation.
Hey back! :)
First, I'll admit that this isn't something I've had to deal much with directly. But, I can give you some guidance :).
API Platform does have some docs on this - https://api-platform.com/docs/core/file-upload/ - though I'm not sure how much I like the solution. VichUploaderBundle is magic, so both good and bad.
Another solution, if your file sizes aren't huge, is to base64_encode the field - https://symfonycasts.com/screencast/symfony-uploads/api-uploads#pure-api-endpoint-with-json-base64-decode - that allows you to send binary data on a normal "field" in your API. Then, you'd have a state processor which decodes this to get the binary, moves it to S3, then saves the final URL. This won't work for bigger files as base64 increases the upload size. Though, really, if you are handling big files, you might need to create a system where users are uploading directly to S3 - e.g. they are able to fetch a temporary signed URL, they upload directly to it, then send info to your API when completed.
Let me know if if this helps :)
Cheers!
Hello,
i'm eager to watch the part 3 of this series, when is it scheduled?
Especially State Provider :)
cheers
Hey @Joel-L!
I'm eager to record it! I'm in the planning/outline stage now - I'd say a few weeks. I'd like to get it out ASAP - but I'm also gone for a week at the end of July. But it's not far off.
Cheers!
// composer.json
{
"require": {
"php": ">=8.1",
"ext-ctype": "*",
"ext-iconv": "*",
"api-platform/core": "^3.0", // v3.1.2
"doctrine/annotations": "^2.0", // 2.0.1
"doctrine/doctrine-bundle": "^2.8", // 2.8.3
"doctrine/doctrine-migrations-bundle": "^3.2", // 3.2.2
"doctrine/orm": "^2.14", // 2.14.1
"nelmio/cors-bundle": "^2.2", // 2.2.0
"nesbot/carbon": "^2.64", // 2.66.0
"phpdocumentor/reflection-docblock": "^5.3", // 5.3.0
"phpstan/phpdoc-parser": "^1.15", // 1.16.1
"symfony/asset": "6.2.*", // v6.2.5
"symfony/console": "6.2.*", // v6.2.5
"symfony/dotenv": "6.2.*", // v6.2.5
"symfony/expression-language": "6.2.*", // v6.2.5
"symfony/flex": "^2", // v2.2.4
"symfony/framework-bundle": "6.2.*", // v6.2.5
"symfony/property-access": "6.2.*", // v6.2.5
"symfony/property-info": "6.2.*", // v6.2.5
"symfony/runtime": "6.2.*", // v6.2.5
"symfony/security-bundle": "6.2.*", // v6.2.6
"symfony/serializer": "6.2.*", // v6.2.5
"symfony/twig-bundle": "6.2.*", // v6.2.5
"symfony/ux-react": "^2.6", // v2.7.1
"symfony/ux-vue": "^2.7", // v2.7.1
"symfony/validator": "6.2.*", // v6.2.5
"symfony/webpack-encore-bundle": "^1.16", // v1.16.1
"symfony/yaml": "6.2.*" // v6.2.5
},
"require-dev": {
"doctrine/doctrine-fixtures-bundle": "^3.4", // 3.4.2
"mtdowling/jmespath.php": "^2.6", // 2.6.1
"phpunit/phpunit": "^9.5", // 9.6.3
"symfony/browser-kit": "6.2.*", // v6.2.5
"symfony/css-selector": "6.2.*", // v6.2.5
"symfony/debug-bundle": "6.2.*", // v6.2.5
"symfony/maker-bundle": "^1.48", // v1.48.0
"symfony/monolog-bundle": "^3.0", // v3.8.0
"symfony/phpunit-bridge": "^6.2", // v6.2.5
"symfony/stopwatch": "6.2.*", // v6.2.5
"symfony/web-profiler-bundle": "6.2.*", // v6.2.5
"zenstruck/browser": "^1.2", // v1.2.0
"zenstruck/foundry": "^1.26" // v1.28.0
}
}
Hi mate, I have a project created with symfony 6 and easy admin 4, currently I'm migrating from a "conventional" approach to an API to be used by a react frontend.
Well, my question is regarding input type files, I created a Service to upload the files into an S3 but I'm not sure about the best way to receive files in the API, can you help me to understand how can I receive this input file in the API??
The field associated with this input is a string where I stored the S3 url for the user badge.
Thanks in advance