This tutorial has a new version, check it out!
> APIs > Symfony RESTful API: Hypermedia, Links & Bonuses (Course 5)
Buy Access to Course
06.

Form Voodoo: property_path

Share this awesome video!

|

Keep on Learning!

Start your All-Access Pass

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

Login Subscribe

Remember, we want to design our API to work well with whomever is using it: whether that's a third-party API client, a JavaScript front end, or another PHP app that's talking to us. That's why we just changed how our Battle output looks.

But you might also want to control how the input looks: what the client needs to send to your API. For example, right now, to create a new battle, you send a project field and a programmer field: each set to their ID:

45 lines | tests/AppBundle/Controller/Api/BattleControllerTest.php
// ... lines 1 - 6
class BattleControllerTest extends ApiTestCase
{
// ... lines 9 - 15
public function testPOSTCreateBattle()
{
// ... lines 18 - 22
$data = array(
'project' => $project->getId(),
'programmer' => $programmer->getId()
);
// ... lines 27 - 42
}
}

But what if we wanted to call these fields projectId and programmerId?

45 lines | tests/AppBundle/Controller/Api/BattleControllerTest.php
// ... lines 1 - 6
class BattleControllerTest extends ApiTestCase
{
// ... lines 9 - 15
public function testPOSTCreateBattle()
{
// ... lines 18 - 22
$data = array(
'projectId' => $project->getId(),
'programmerId' => $programmer->getId()
);
// ... lines 27 - 42
}
}

After all, those are IDs that are being sent. If we change this in the test, everything will explode. Prove it by running things:

./vendor/bin/phpunit --filter testPOSTCreateBattle

Yep, a big validation error: the form should not contain extra fields: these two new fields are not in the form we built.

The easiest fix is to simply rename these fields in the form to projectId and programmerId:

35 lines | src/AppBundle/Form/BattleType.php
// ... lines 1 - 9
class BattleType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
->add('programmerId', EntityType::class, [
// ... lines 17 - 18
])
->add('projectId', EntityType::class, [
// ... lines 21 - 22
])
;
}
// ... lines 26 - 33
}

But then, we would also need to change the property names in BattleModel to match these:

33 lines | src/AppBundle/Form/Model/BattleModel.php
// ... lines 1 - 7
class BattleModel
{
private $project;
private $programmer;
// ... lines 13 - 32
}

And that sucks: because these properties do not hold ID's: they hold objects. I'd rather not need to make my class ugly and confusing to help out the API.

Using property_path

Here is the very simple, elegant, amazing solution. In the form, you do need to update your fields to projectId and programmerId so they match what the client is sending. But then, add a property_path option to projectId set to project:

35 lines | src/AppBundle/Form/BattleType.php
// ... lines 1 - 10
class BattleType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
->add('programmerId', EntityType::class, [
'class' => 'AppBundle\Entity\Programmer',
'property_path' => 'programmer'
])
// ... lines 20 - 23
;
}
// ... lines 26 - 33
}

Do the same thing to the programmerId field: 'property_path' => 'programmer':

35 lines | src/AppBundle/Form/BattleType.php
// ... lines 1 - 10
class BattleType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
// ... lines 16 - 19
->add('projectId', EntityType::class, [
'class' => 'AppBundle\Entity\Project',
'property_path' => 'project'
])
;
}
// ... lines 26 - 33
}

That's the key! The form now expects the client to send projectId and programmerId. But when it sets the final data on BattleModel, it will call setProject() and setProgrammer().

This is a little known way to have a field name that's different than the property name on your class. Bring on the test!

./vendor/bin/phpunit --filter testPOSTCreateBattle

Awesome! Another useful option I want you to know about is called mapped. You can use this to allow an extra field in your input, without needing to add a corresponding property to your class.