post resource with associated file resource in a REST API - rest

Question

I have two entities, MediaObject and Book. MediaObject is a generic entity for managing files and includes fields like size, mimeType, and filePath. Book has fields like title, author, and also includes a link to an associated MediaObject for its cover image file.
How can I POST a Book entity with its associated MediaObject cover image with API-Platform? I'd like to do this as one atomic operation. I don't want books saved without a cover image and I don't want orphan cover images. So I don't want to POST a MediaObject cover image and then use the ID I get back when POSTing a new Book. (or vice-versa)
https://api-platform.com/docs/core/file-upload/
class MediaObject
{
...
public $filePath;
...
}
class Book
{
...
public $coverImage; // i.e. mediaObjectId; associated MediaObject to an image file
...
}

Answer 1

The documentation has the option "deserialize"= false. This means that deserialization will not occur for this operation. Therefore, you must write the entire deserialization process yourself to the handler controller. You must also write fields for the swagger documentation.
For example:
<?php
declare(strict_types=1);
namespace App\Entity;
// more use...
/**
* #ApiResource(
* iri="http://schema.org/MediaObject",
* normalizationContext={
* "groups" = {"media:read"}
* },
* collectionOperations={
* "post" = {
* "controller" = MediaHandler::class,
* "deserialize" = false,
* "access_control" = "is_granted('ROLE_USER')",
* "validation_groups" = {"Default", "media:collection:post"},
* "openapi_context" = {
* "requestBody" = {
* "content" = {
* "multipart/form-data" = {
* "schema" = {
* "type" = "object",
* "properties" = {
* "file" = {
* "type" = "string",
* "format" = "binary"
* },
* "name" = {
* "type" = "string"
* }
* }
* }
* }
* }
* }
* }
* },
* "get"
* },
* itemOperations={
* "get"
* }
* )
* #Vich\Uploadable
* #ORM\Entity(repositoryClass="App\Repository\MediaRepository")
*/
class Media
{
/**
* #ApiProperty(iri="http://schema.org/contentUrl")
* #Groups({"media:read"})
*/
public $contentUrl;
/**
* #Assert\NotNull(groups={"media:collection:post"})
* #Vich\UploadableField(mapping="media", fileNameProperty="filePath")
* #Assert\File(
* maxSize="2M",
* mimeTypes={
* "application/pdf",
* "application/x-pdf",
* "image/jpeg",
* "image/jpg",
* "image/png"
* },
* groups={"media:collection:post"}
* )
*/
public $file;
/**
* #ORM\Id
* #ORM\GeneratedValue
* #ORM\Column(type="integer")
*/
private $id;
/**
* #ORM\Column(type="string", length=512)
*/
private $filePath;
/**
* #ORM\Column(type="string", length=255)
*/
private $name;
//...
}
Controller handler example:
<?php
declare(strict_types=1);
namespace App\Controller\Api;
// use ...
class MediaHandler extends AbstractController
{
/**
* #var EntityManagerInterface
*/
private EntityManagerInterface $entityManager;
public function __construct(EntityManagerInterface $entityManager)
{
$this->entityManager = $entityManager;
}
public function __invoke(Request $request): Media
{
$uploadedFile = $request->files->get('file');
if (!$uploadedFile) {
throw new BadRequestHttpException('"file" is required');
}
$mediaObject = new Media();
$mediaObject->file = $uploadedFile;
$mediaObject->setName($request->request->get('name'));
return $mediaObject;
}
}
If the "Book" exists. And you want to add Book toMediaObject, you can set the iri string and parse it in the controller-handler:
//...
public function __construct(EntityManagerInterface $entityManager, IriConverterInterface $iriConverter)
{
$this->entityManager = $entityManager;
$this->iriConverter = $iriConverter;
}
public function __invoke(Request $request): Media
{
$uploadedFile = $request->files->get('file');
if (!$uploadedFile) {
throw new BadRequestHttpException('"file" is required');
}
$iriBook = $request->request->get('book');
$book = null;
if ($iriBook) {
/**
* #var Book $book
*/
$book = $this->iriConverter->getItemFromIri($iriBook);
}
$mediaObject = new Media();
$mediaObject->file = $uploadedFile;
$mediaObject->setBook($book);
return $mediaObject;
}
//..
If this is your case, then no further action (DataPersist) is required.
Next your need to go https://api-platform.com/docs/core/data-persisters/ and make DataPesist handler
Example:
<?php
declare(strict_types=1);
namespace App\DataPersister;
use ApiPlatform\Core\DataPersister\ContextAwareDataPersisterInterface;
use App\Entity\Media;
use App\ExtendTrait\ContextAwareDataTrait;
use Doctrine\ORM\EntityManagerInterface;
class MediaObjectDataPersister implements ContextAwareDataPersisterInterface
{
use ContextAwareDataTrait;
/**
* #var EntityManagerInterface
*/
private EntityManagerInterface $entityManager;
public function __construct(EntityManagerInterface $entityManager)
{
$this->entityManager = $entityManager;
}
/**
* {#inheritdoc}
*/
public function supports($data, array $context = []): bool
{
return $this->isCollection('post', $context) && $data instanceof Media;
}
/**
* {#inheritdoc}
*
* #param $data Media
*
* #throws \Exception
*/
public function persist($data, array $context = []): void
{
$book = new Book();
$book->setName($data->getName());
// begin transaction and persist and flush $book and $data
}
/**
* {#inheritdoc}
*/
public function remove($data, array $context = []): void
{
// todo remove book
}
}
P.S. I don't test this code. I writing idea ;)
P.S.S. $this->isCollection() it function from my trait, may be need you it:
<?php
declare(strict_types=1);
namespace App\ExtendTrait;
/**
* Trait ContextAwareDataTrait.
*
* Helps confirm the operation name
*/
trait ContextAwareDataTrait
{
public function isItem(string $operationName, array $context, string $resourceClass = null): bool
{
if ($resourceClass && ($context['resource_class'] ?? false) !== $resourceClass) {
return false;
}
return ($context['item_operation_name'] ?? null) === $operationName;
}
public function isCollection(string $operationName, array $context, string $resourceClass = null): bool
{
if ($resourceClass && ($context['resource_class'] ?? false) !== $resourceClass) {
return false;
}
return ($context['collection_operation_name'] ?? null) === $operationName;
}
}