Доклад Алексея Кривцова, Sumy PHP User Group #1, 14.05.2016

1. Service approach for
development Rest API in
Symfony2
Aleksey Kryvtsov @ Web-developer at CPCS
alkryvtsov@gmail.com

2. Development Rest API in Symfony2
2

3. ● Interface as contracts.
● Thin Controller, Fat Service.
● The Content Negotiation in the HTTP and REST.
● Form as API interface.
Rules
3

4. ● FOSRestBundle
● JMSSerializerBundle
● NelmioApiDocBundle
List of bundles
// app/AppKernel.php
$bundles = [
//...
new FOSRestBundleFOSRestBundle(),
new JMSSerializerBundleJMSSerializerBundle(),
new
NelmioApiDocBundleNelmioApiDocBundle(),
4

5. /api/v1/{_lang}/pages/{id}.{_format}
/api/v1/en/pages/{id}.json
Will return a json file
/api/v1/en/pages/{id}.xml
Will return a xml file
/api/v1/en/pages/{id} and /api/v1/en/pages/{id}.html
Will return the web page file
Format of routing
5

6. # /app/config/routing.yml
acme_api_blog:
type: rest
prefix: /api/v1/{_lang}
resource:
"@AcmeBlogBundle/Resources/config/routes.yml"
Adding the routes
6

7. # /src/Acme/BlogBundle/Resources/config/routes.yml
acme_api_blog_page:
resource:
"AcmeBlogBundleControllerPageController"
name_prefix: api_v1_ # naming collision
Create a route file into the bundle
# php app/console route:debug | grep api_v1_
7

8. # /src/Acme/BlogBundle/Controller/PageController.php
namespace AcmeBlogBundleController;
use FOSRestBundleControllerFOSRestController as Rest;
class PageController extends Rest {
// another methods POST, PUT, DELETE and etc...
/* @annotations */
public function getPageAction ($id) {
return $this->get('acme_blog.blog_post.handler')->get($id);
}
}
Controller: PageController::getPageAction ()
8

9. # /src/Acme/BlogBundle/Controller/PageController.php
use FOSRestBundleControllerAnnotations as FOSRest;
/**
* Get single Page
* @FOSRestGet("/pages/{id}", requirements={"id" = "d+"}, name="get_page")
* @FOSRestView(serializerGroups={"page"})
*
* @ApiDoc(/* documentation */)
*
* @param int $id The page id
*
* @return array
* @throws NotFoundHttpException when page not exist or not found
*/
public function getPageAction ($id) {}
Controller: PageController::getPageAction ()
9

10. # /src/Acme/BlogBundle/Entity/Page.php
namespace AcmeBlogBundleEntity;
class Page implements PageInterface {
// fields, getters and setters
}
Interface as contract
# /src/Acme/BlogBundle/Model/PageInterface.php
namespace AcmeBlogBundleModel;
interface PageInterface {
}
10

11. Handler configuration. Part I
# /src/Acme/BlogBundle/Resources/config/handlers.yml
services:
1 acme_blog.page.entity:
class: AcmeBlogBundleEntityPage
2 acme_blog.blog_post.handler:
class: AcmeBlogBundleHandlerPageHandler
arguments:
3 - @doctrine.orm.entity_manager
4 - @acme_blog.page.entity
11

12. HandlerInterface: PageHandlerInterface::get()
# /src/Acme/BlogBundle/Handler/PageHandlerInterface.php
namespace AcmeBlogBundleHandler;
use AcmeBlogBundleModelPageInterface;
interface PageHandlerInterface {
// another methods POST, PUT, DELETE and etc...
/**
* Gets a page by id
*
* @api
* @param integer $id
*
* @return PageInterface
*/
public function get ($id);
}
12

13. Handler: PageHandler::__construct()
# /src/Acme/BlogBundle/Handler/PageHandler.php
namespace AcmeBlogBundleHandler;
use DoctrineORMEntityManager;
use AcmeBlogBundleModelPageInterface;
class PageHandler implements PageHandlerInterface {
// another methods
/**
* @return void
*/
public function __construct(
EntityManager $entityManager,
PageInterface $pageEntity
) // continue...
13

14. Handler: PageHandler::__construct()
# /src/Acme/BlogBundle/Handler/PageHandler.php
namespace AcmeBlogBundleHandler;
class PageHandler implements PageHandlerInterface {
// another methods
/* public function __construct (...) */ {
1 $this->entityManager = $entityManager;
2 $this->pageEntity = $pageEntity;
3 $this->repository = $entityManager->getRepository(get_class($pageEntity));
}
}
14

15. Handler: PageHandler (UML)
15

16. Handler: PageHandler::get()
# /src/Acme/BlogBundle/Handler/PageHandler.php
namespace AcmeBlogBundleHandler;
class PageHandler implements PageHandlerInterface {
// another methods POST, PUT, DELETE and etc...
/**
* {@inheritdoc}
*/
public function get ($id) {
return $this->repository->find($id);
}
}
16

17. Controller: PageController::getAllPagesAction()
17
URL: ~/pages

18. 18
Diagram: getAction, getAllAction

19. # /src/Acme/BlogBundle/Controller/PageController.php
use SymfonyComponentHttpFoundationRequest;
class PageController extends Rest {
// another methods
/* @annotations -> URL: ~/pages */
public function postPageAction(Request $request) {
return $this->get('acme_blog.blog_post.handler')
->post($request->request->all());
}
}
Controller: PageController::postPageAction ()
19

20. HandlerInterface: PageHandlerInterface::post()
# /src/Acme/BlogBundle/Handler/PageHandlerInterface.php
use AcmeBlogBundleModelPageInterface;
interface PageHandlerInterface {
/**
* Creates a new page
*
* @api
* @param array $parameters
* @param array $options
*
* @return PageInterface
*/
public function post(array $parameters = [], array $options = []);
}
20

21. Handler: PageHandler::post()
# /src/Acme/BlogBundle/Handler/PageHandler.php
/* {@inheritdoc} */
public function post (
array $parameters = [],
array $options = []
) {
return $this->processForm(
$this->pageClass,
$parameters,
$options,
“POST”
);
}
21

22. Handler configuration. Part II
# /src/Acme/BlogBundle/Resources/config/handlers.yml
services:
// ...
acme_blog.page.form_type:
class: AcmeBlogBundleFormTypePageFormType
acme_blog.blog_post.handler:
class: AcmeBlogBundleHandlerPageHandler
arguments:
- @doctrine.orm.entity_manager
- @acme_blog.page.entity
- @form.factory
- @acme_blog.page.form_type
22

23. Handler: PageHandler::__construct()
# /src/Acme/BlogBundle/Handler/PageHandler.php
use SymfonyComponentFormFormFactoryInterface;
use use SymfonyComponentFormFormTypeInterface;
class PageHandler implements PageHandlerInterface {
/**
* @return void
*/
public function __construct (
//...
FormFactoryInterface $formFactory,
FormTypeInterface $formType
) {
// ...
$this->formFactory = $formFactory;
$this->formType = $formType;
} 23

24. HandlerInterface: PageHandlerInterface::processForm()
# /src/Acme/BlogBundle/Handler/PageHandlerInterface.php
use AcmeBlogBundleModelPageInterface;
interface PageHandlerInterface {
/**
* Processes the form
*
* @api
* @param PageInterface $page
* @param array $parameters
* @param array $options
* @param string $method
*
* @return PageInterface
*/
private function processForm(PageInterface $page, array $parameters = [], array $options = [],
$method
)
} 24

25. Handler: PageHandler::processForm()
# /src/Acme/BlogBundle/Handler/PageHandler.php
protected function processForm (/*...*/) {
1 $form = $this->formFactory->create($this->formType, $page, $options);
2 $form->submit($parameters, 'PATCH' !== $method);
3 if ($form->isValid()) {
4 $this->entityManager->persist($page);
5 $this->entityManager->flush($page);
6 return $page;
}
7 // throw new InvalidFormException(/*...*/)
}
25

26. Controller: PageController::[patch|put]PageAction()
26
URL: ~/pages/{id}

27. Handler: PageHandler::patch()
# /src/Acme/BlogBundle/Handler/PageHandler.php
// another methods
public function patch(array $parameters = [], array $options = []) {
1 $page = $this->get($parameters[‘id’]);
2 return $this->processForm(
$page,
$parameters,
$options,
“PATCH”
);
}
27

28. Handler: PageHandler::put()
# /src/Acme/BlogBundle/Handler/PageHandler.php
// another methods
public function put(array $parameters = [], array $options = []) {
1 $page = $this->get($parameters[‘id’]);
2 return $this->processForm(
$page,
$parameters,
$options,
“PUT”
);
}
28

29. 29
Diagram: postAction, putAction, patchAction

30. # /src/Acme/BlogBundle/Controller/PageController.php
class PageController extends Rest {
// another methods
/* @annotations -> URL: ~/pages/{id} */
public function deletePageAction($id) {
return $this->get('acme_blog.blog_post.handler')->delete($id);
}
}
Controller: PageController::deletePageAction()
30

31. HandlerInterface: PageHandlerInterface::delete()
# /src/Acme/BlogBundle/Handler/PageHandlerInterface.php
use AcmeBlogBundleModelPageInterface;
interface PageHandlerInterface {
/**
* Returns the result of removal
*
* @api
* @param integer $id
*
* @return string
*/
public function delete($id);
}
31

32. Handler: PageHandler::delete()
# /src/Acme/BlogBundle/Handler/PageHandler.php
namespace AcmeBlogBundleHandler;
class PageHandler implements PageHandlerInterface {
/**
* {@inheritdoc}
*/
public function delete ($id) {
1 $page = $this->get($id);
2 $this->entityManager->remove($page);
3 $this->entityManager->flush();
}
}
32

33. Diagram
33

34. 34
UML

35. 1. # app/config/routing.yml
NelmioApiDocBundle:
resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
prefix: /api/doc
Documentation: ApiDoc
35
2. # /src/Acme/BlogBundle/Controller/PageController.php
/**
* @ApiDoc(
* description = "Creates a new page from the submitted data.",
* input = "AcmeBlogBundleFormPageType",
* output = "AcmeBlogBundleEntityPage",
* statusCodes = {
* 200 = "Returned when successful",
* 400 = "Returned when the form has errors"
* }
* )
*/

36. 36

37. JMSSerializer
37
# /src/Acme/BlogBundle/Entity/Page.php
use DoctrineORMMapping as ORM;
use JMSSerializerAnnotation as JMS;
/**
* @ORMEntity
* @JMSExclusionPolicy("all")
*/
class Page {
/**
* @JMSExpose
* @JMSType("AnotherClass")
* @JMSGroups({"page", "details"})
* @ORMManyToOne(targetEntity="AnotherClass")
* @ORMJoinColumn(name="column", referencedColumnName="id")
*/
protected $field;
{
"id": 1,
"field": AnotherClass,
"another": "anotherType"
}

38. JMSSerializer: Annotations
38
● @ExclusionPolicy
● @Exclude
● @Expose
● @SerializedName
● @Since
● @Until
● @Groups
● @MaxDepth
● @AccessType
● @Accessor
● @ReadOnly
● @PreSerialize
● @PostSerialize
● @PostDeserialize
● @HandlerCallback
● @Discriminator
● @Type
● @XmlRoot
● @XmlAttribute
● @XmlValue

39. References
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
Best Practices for Designing a Pragmatic RESTful API
http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way
REST APIs with Symfony2: The Right Way
https://www.youtube.com/watch?v=Kkby5fG89K0
Lukas Kahwe Smith (Symfony Camp)
http://welcometothebundle.com/symfony2-rest-api-the-best-2013-way
Symfony2 REST API: the best way
https://github.com/liuggio/symfony2-rest-api-the-best-2013-way
The github repository
39

40. Thank you
Questions ?
Aleksey Kryvtsov alkryvtsov@gmail.com
40