From 89aaec14b459a0af005750841915741a456fc520 Mon Sep 17 00:00:00 2001 From: SirDomin Date: Wed, 29 Apr 2020 13:03:23 +0200 Subject: [PATCH] fixed code standards --- docs/configuration.md | 70 +++++----- docs/create_resource.md | 230 +++++++++++++++++-------------- docs/delete_resource.md | 114 +++++++++------- docs/forms.md | 60 ++++----- docs/index_resources.md | 142 ++++++++++--------- docs/installation.md | 18 +-- docs/reference.md | 70 +++++----- docs/routing.md | 292 ++++++++++++++++++++-------------------- docs/show_resource.md | 118 ++++++++-------- docs/update_resource.md | 196 +++++++++++++++------------ 10 files changed, 695 insertions(+), 615 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index d5203c537..eb4ce5f98 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -13,20 +13,20 @@ You can see a full exemplary configuration of a typical resource ## Implement the ResourceInterface in your model class. ```php - namespace App\Entity; +namespace App\Entity; - use Sylius\Component\Resource\Model\ResourceInterface; +use Sylius\Component\Resource\Model\ResourceInterface; - class Book implements ResourceInterface - { - // Most of the time you have the code below already in your class. - protected $id; +class Book implements ResourceInterface +{ + // Most of the time you have the code below already in your class. + protected $id; - public function getId() - { - return $this->id; - } + public function getId() + { + return $this->id; } +} ``` ## Configure the class as a resource. @@ -34,11 +34,11 @@ You can see a full exemplary configuration of a typical resource In your ``config/packages/sylius_resource.yaml`` add: ```yaml - sylius_resource: - resources: - app.book: - classes: - model: App\Entity\Book +sylius_resource: + resources: + app.book: + classes: + model: App\Entity\Book ``` That's it! Your Book entity is now registered as Sylius Resource. @@ -47,18 +47,18 @@ That's it! Your Book entity is now registered as Sylius Resource. Remember that the ``doctrine/orm`` driver is used by default. ```yaml - sylius_resource: - drivers: - - doctrine/orm - - doctrine/phpcr-odm - resources: - app.book: - classes: - model: App\Entity\Book - app.article: - driver: doctrine/phpcr-odm - classes: - model: App\Document\ArticleDocument +sylius_resource: + drivers: + - doctrine/orm + - doctrine/phpcr-odm + resources: + app.book: + classes: + model: App\Entity\Book + app.article: + driver: doctrine/phpcr-odm + classes: + model: App\Document\ArticleDocument ``` ## Generate API routing. @@ -68,10 +68,10 @@ Learn more about using Sylius REST API in these articles: Add the following lines to ``config/routes.yaml``: ```yaml - app_book: - resource: | - alias: app.book - type: sylius.resource_api +app_book: + resource: | + alias: app.book + type: sylius.resource_api ``` After that a full JSON/XML CRUD API is ready to use. Sounds crazy? Spin up the built-in server and give it a try: @@ -99,10 +99,10 @@ As you can guess, other CRUD actions are available through this API. What if you want to render HTML pages? That's easy! Update the routing configuration: ```yaml - app_book: - resource: | - alias: app.book - type: sylius.resource +app_book: + resource: | + alias: app.book + type: sylius.resource ``` This will generate routing for HTML views. diff --git a/docs/create_resource.md b/docs/create_resource.md index aad460b6e..1a50ca588 100644 --- a/docs/create_resource.md +++ b/docs/create_resource.md @@ -4,11 +4,13 @@ To display a form, handle its submission or to create a new resource via API, you should use the **createAction** of your **app.controller.book** service. ```yaml - app_book_create: - path: /books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction +# config/routes.yaml + +app_book_create: + path: /books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction ``` Done! Now when you go to ``/books/new``, the ResourceController will use the factory (``app.factory.book``) to create a new book instance. Then it will try to create an ``app_book`` form, and set the newly created book as its data. @@ -30,13 +32,15 @@ When validation fails, it will render the form just like previously with the err Just like for the **show** and **index** actions, you can customize the template per route. ```yaml - app_book_create: - path: /books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - template: Book/create.html.twig +# config/routes.yaml + +app_book_create: + path: /books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + template: Book/create.html.twig ``` ## Using Custom Form @@ -45,13 +49,15 @@ You can also use custom form type on per route basis. Following Symfony3 convent Below you can see the usage for specifying a custom form. ```yaml - app_book_create: - path: /books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - form: App\Form\BookType +# config/routes.yaml + +app_book_create: + path: /books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + form: App\Form\BookType ``` ## Passing Custom Options to Form @@ -61,16 +67,18 @@ Well, there's a configuration for that! Below you can see the usage for specifying custom options, in this case, ``validation_groups``, but you can pass any option accepted by the form. ```yaml - app_book_create: - path: /books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - form: - type: App\Form\BookType - options: - validation_groups: [sylius, my_custom_group] +# config/routes.yaml + +app_book_create: + path: /books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + form: + type: App\Form\BookType + options: + validation_groups: [sylius, my_custom_group] ``` ## Using Custom Factory Method @@ -78,26 +86,30 @@ By default, ``ResourceController`` will use the ``createNew`` method with no arg To use a different method of your factory, you can simply configure the ``factory`` option. ```yaml - app_book_create: - path: /books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - factory: createNewWithAuthor +# config/routes.yaml + +app_book_create: + path: /books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + factory: createNewWithAuthor ``` Additionally, if you want to provide your custom method with arguments from the request, you can do so by adding more parameters. ```yaml - app_book_create: - path: /books/{author}/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - factory: - method: createNewWithAuthor - arguments: [$author] +# config/routes.yaml + +app_book_create: + path: /books/{author}/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + factory: + method: createNewWithAuthor + arguments: [$author] ``` With this configuration, ``$factory->createNewWithAuthor($request->get('author'))`` will be called to create new resource within the ``createAction``. @@ -106,15 +118,17 @@ With this configuration, ``$factory->createNewWithAuthor($request->get('author') If you would like to use your own service to create the resource, then try the following configuration: ```yaml - app_book_create: - path: /{authorId}/books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - factory: - method: ["expr:service('app.factory.custom_book_factory')", "createNewByAuthorId"] - arguments: $authorId +# config/routes.yaml + +app_book_create: + path: /{authorId}/books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + factory: + method: ["expr:service('app.factory.custom_book_factory')", "createNewByAuthorId"] + arguments: $authorId ``` With this configuration, service with id "app.factory.custom_book_factory" will be called to create new resource within the ``createNewByAuthorId`` method and the author id from the url as argument. @@ -125,39 +139,45 @@ You can easily change that behaviour. For example, to redirect to the index list after successfully creating a new resource - you can use the following configuration. ```yaml - app_book_create: - path: /books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - redirect: app_book_index +# config/routes.yaml + +app_book_create: + path: /books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + redirect: app_book_index ``` You can also perform more complex redirects, with parameters. For example: ```yaml - app_book_create: - path: /genre/{genreId}/books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - redirect: - route: app_genre_show - parameters: { id: $genreId } +# config/routes.yaml + +app_book_create: + path: /genre/{genreId}/books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + redirect: + route: app_genre_show + parameters: { id: $genreId } ``` In addition to the request parameters, you can access some of the newly created objects properties, using the ``resource.`` prefix. ```yaml - app_book_create: - path: /books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - redirect: - route: app_book_show - parameters: { title: resource.title } +# config/routes.yaml + +app_book_create: + path: /books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + redirect: + route: app_book_show + parameters: { title: resource.title } ``` With this configuration, the ``title`` parameter for route ``app_book_show`` will be obtained from your newly created book. @@ -168,13 +188,15 @@ The pattern is always the same - ``{applicationName}.{resourceName}.pre/post_cre own action name. ```yaml - app_book_customer_create: - path: /customer/books/new - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - event: customer_create +# config/routes.yaml + +app_book_customer_create: + path: /customer/books/new + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + event: customer_create ``` This way, you can listen to ``app.book.pre_customer_create`` and ``app.book.post_customer_create`` events. It's especially useful, when you use ``ResourceController:createAction`` in more than one route. @@ -182,23 +204,25 @@ This way, you can listen to ``app.book.pre_customer_create`` and ``app.book.post ## Configuration Reference ```yaml - app_genre_book_add: - path: /{genreName}/books/add - methods: [GET, POST] - defaults: - _controller: app.controller.book:createAction - _sylius: - template: Book/addToGenre.html.twig - form: App\Form\BookType - event: book_create - factory: - method: createForGenre - arguments: [$genreName] - criteria: - group.name: $genreName - redirect: - route: app_book_show - parameters: { title: resource.title } +# config/routes.yaml + +app_genre_book_add: + path: /{genreName}/books/add + methods: [GET, POST] + defaults: + _controller: app.controller.book:createAction + _sylius: + template: Book/addToGenre.html.twig + form: App\Form\BookType + event: book_create + factory: + method: createForGenre + arguments: [$genreName] + criteria: + group.name: $genreName + redirect: + route: app_book_show + parameters: { title: resource.title } ``` **[Go back to the documentation's index](index.md)** diff --git a/docs/delete_resource.md b/docs/delete_resource.md index 1551585dd..0ced69425 100644 --- a/docs/delete_resource.md +++ b/docs/delete_resource.md @@ -3,11 +3,13 @@ Deleting a resource is simple. ```yaml - app_book_delete: - path: /books/{id} - methods: [DELETE] - defaults: - _controller: app.controller.book:deleteAction +# config/routes.yaml + +app_book_delete: + path: /books/{id} + methods: [DELETE] + defaults: + _controller: app.controller.book:deleteAction ``` ## Calling an Action with DELETE method @@ -15,12 +17,12 @@ Currently browsers do not support the "DELETE" http method. Fortunately, Symfony You can make a POST call with parameter override, which will force the framework to treat the request as the specified method. ```html -
- - -
+
+ + +
``` On submit, the delete action with the method DELETE, will remove and flush the resource. Then, by default it redirects to ``app_book_index`` to display the books index, but just like for the other actions - it's customizable. @@ -31,15 +33,17 @@ By default, the **deleteAction** will look for the resource by id. However, you For example, if you want to delete a book that belongs to a particular genre, not only by its id. ```yaml - app_book_delete: - path: /genre/{genreId}/books/{id} - methods: [DELETE] - defaults: - _controller: app.controller.book:deleteAction - _sylius: - criteria: - id: $id - genre: $genreId +# config/routes.yaml + +app_book_delete: + path: /genre/{genreId}/books/{id} + methods: [DELETE] + defaults: + _controller: app.controller.book:deleteAction + _sylius: + criteria: + id: $id + genre: $genreId ``` There are no magic hacks behind that, it simply takes parameters from request and builds the criteria array for the ``findOneBy`` repository method. @@ -48,15 +52,17 @@ There are no magic hacks behind that, it simply takes parameters from request an By default the controller will redirect to the "index" route after successful action. To change that, use the following configuration. ```yaml - app_book_delete: - path: /genre/{genreId}/books/{id} - methods: [DELETE] - defaults: - _controller: app.controller.book:deleteAction - _sylius: - redirect: - route: app_genre_show - parameters: { id: $genreId } +# config/routes.yaml + +app_book_delete: + path: /genre/{genreId}/books/{id} + methods: [DELETE] + defaults: + _controller: app.controller.book:deleteAction + _sylius: + redirect: + route: app_genre_show + parameters: { id: $genreId } ``` ## Custom Event Name @@ -66,13 +72,15 @@ The pattern is always the same - ``{applicationName}.{resourceName}.pre/post_del However, you can customize the last part of the event, to provide your own action name. ```yaml - app_book_customer_delete: - path: /customer/book-delete/{id} - methods: [DELETE] - defaults: - _controller: app.controller.book:deleteAction - _sylius: - event: customer_delete +# config/routes.yaml + +app_book_customer_delete: + path: /customer/book-delete/{id} + methods: [DELETE] + defaults: + _controller: app.controller.book:deleteAction + _sylius: + event: customer_delete ``` This way, you can listen to ``app.book.pre_customer_delete`` and ``app.book.post_customer_delete`` events. It's especially useful, when you use ``ResourceController:deleteAction`` in more than one route. @@ -82,21 +90,23 @@ This way, you can listen to ``app.book.pre_customer_delete`` and ``app.book.post ```yaml - app_genre_book_remove: - path: /{genreName}/books/{id}/remove - methods: [DELETE] - defaults: - _controller: app.controller.book:deleteAction - _sylius: - event: book_delete - repository: - method: findByGenreNameAndId - arguments: [$genreName, $id] - criteria: - genre.name: $genreName - id: $id - redirect: - route: app_genre_show - parameters: { genreName: $genreName } +# config/routes.yaml + +app_genre_book_remove: + path: /{genreName}/books/{id}/remove + methods: [DELETE] + defaults: + _controller: app.controller.book:deleteAction + _sylius: + event: book_delete + repository: + method: findByGenreNameAndId + arguments: [$genreName, $id] + criteria: + genre.name: $genreName + id: $id + redirect: + route: app_genre_show + parameters: { genreName: $genreName } ``` **[Go back to the documentation's index](index.md)** diff --git a/docs/forms.md b/docs/forms.md index 572286f3a..58446658e 100644 --- a/docs/forms.md +++ b/docs/forms.md @@ -7,30 +7,30 @@ Have you noticed how Sylius generates forms for you? Of course, for many use-cas ### Create a FormType class for your resource ```php - namespace App\Form\Type; +namespace App\Form\Type; - use Sylius\Bundle\ResourceBundle\Form\Type\AbstractResourceType; - use Symfony\Component\Form\FormBuilderInterface; +use Sylius\Bundle\ResourceBundle\Form\Type\AbstractResourceType; +use Symfony\Component\Form\FormBuilderInterface; - class BookType extends AbstractResourceType +class BookType extends AbstractResourceType +{ + /** + * {@inheritdoc} + */ + public function buildForm(FormBuilderInterface $builder, array $options) { - /** - * {@inheritdoc} - */ - public function buildForm(FormBuilderInterface $builder, array $options) - { - // Build your custom form, with all fields that you need - $builder->add('title', TextType::class); - } + // Build your custom form, with all fields that you need + $builder->add('title', TextType::class); + } - /** - * {@inheritdoc} - */ - public function getBlockPrefix() - { - return 'app_book'; - } + /** + * {@inheritdoc} + */ + public function getBlockPrefix() + { + return 'app_book'; } +} ``` ### **Note** The getBlockPrefix method returns the prefix of the template block name for this type. @@ -44,21 +44,21 @@ the registration of a form type is only needed when the form is extending the `` or when it has some custom constructor dependencies. ```yaml - app.book.form.type: - class: App\Form\Type\BookType - tags: - - { name: form.type } - arguments: ['%app.model.book.class%', '%app.book.form.type.validation_groups%'] +app.book.form.type: + class: App\Form\Type\BookType + tags: + - { name: form.type } + arguments: ['%app.model.book.class%', '%app.book.form.type.validation_groups%'] ``` ## Configure the form for your resource ```yaml - sylius_resource: - resources: - app.book: - classes: - model: App\Entity\Book - form: App\Form\Type\BookType +sylius_resource: + resources: + app.book: + classes: + model: App\Entity\Book + form: App\Form\Type\BookType ``` That's it. Your new class will be used for all forms! diff --git a/docs/index_resources.md b/docs/index_resources.md index 57ce05dac..53974a95d 100644 --- a/docs/index_resources.md +++ b/docs/index_resources.md @@ -4,11 +4,13 @@ To get a paginated list of Books, we will use **indexAction** of our controller. In the default scenario, it will return an instance of paginator, with a list of Books. ```yaml - app_book_index: - path: /books - methods: [GET] - defaults: - _controller: app.controller.book:indexAction +# config/routes.yaml + +app_book_index: + path: /books + methods: [GET] + defaults: + _controller: app.controller.book:indexAction ``` When you go to ``/books``, the ResourceController will use the repository (``app.repository.book``) to create a paginator. The default template will be rendered - ``App:Book:index.html.twig`` with the paginator as the ``books`` variable. @@ -21,16 +23,18 @@ which is a [Library](https://github.com/whiteoctober/Pagerfanta) used to manage Just like for the **showAction**, you can override the default template and criteria. ```yaml - app_book_index_inactive: - path: /books/disabled - methods: [GET] - defaults: - _controller: app.controller.book:indexAction - _sylius: - filterable: true - criteria: - enabled: false - template: Book/disabled.html.twig +# config/routes.yaml + +app_book_index_inactive: + path: /books/disabled + methods: [GET] + defaults: + _controller: app.controller.book:indexAction + _sylius: + filterable: true + criteria: + enabled: false + template: Book/disabled.html.twig ``` This action will render a custom template with a paginator only for disabled Books. @@ -39,16 +43,18 @@ This action will render a custom template with a paginator only for disabled Boo Except filtering, you can also sort Books. ```yaml - app_book_index_top: - path: /books/top - methods: [GET] - defaults: - _controller: app.controller.book:indexAction - _sylius: - sortable: true - sorting: - score: desc - template: Book/top.html.twig +# config/routes.yaml + +app_book_index_top: + path: /books/top + methods: [GET] + defaults: + _controller: app.controller.book:indexAction + _sylius: + sortable: true + sorting: + score: desc + template: Book/top.html.twig ``` Under that route, you can paginate over the Books by their score. @@ -66,17 +72,19 @@ It will transform your doctrine query builder into ``Pagerfanta\Pagerfanta`` obj You can also control the "max per page" for paginator, using ``paginate`` parameter. ```yaml - app_book_index_top: - path: /books/top - methods: [GET] - defaults: - _controller: app.controller.book:indexAction - _sylius: - paginate: 5 - sortable: true - sorting: - score: desc - template: Book/top.html.twig +# config/routes.yaml + +app_book_index_top: + path: /books/top + methods: [GET] + defaults: + _controller: app.controller.book:indexAction + _sylius: + paginate: 5 + sortable: true + sorting: + score: desc + template: Book/top.html.twig ``` This will paginate 5 books per page, where 10 is the default. @@ -85,18 +93,20 @@ This will paginate 5 books per page, where 10 is the default. Pagination is handy, but you do not always want to do it, you can disable pagination and simply request a collection of resources. ```yaml - app_book_index_top3: - path: /books/top - methods: [GET] - defaults: - _controller: app.controller.book:indexAction - _sylius: - paginate: false - limit: 3 - sortable: true - sorting: - score: desc - template: Book/top3.html.twig +# config/routes.yaml + +app_book_index_top3: + path: /books/top + methods: [GET] + defaults: + _controller: app.controller.book:indexAction + _sylius: + paginate: false + limit: 3 + sortable: true + sorting: + score: desc + template: Book/top3.html.twig ``` That action will return the top 3 books by score, as the ``books`` variable. @@ -104,22 +114,24 @@ That action will return the top 3 books by score, as the ``books`` variable. ```yaml - app_book_index: - path: /{author}/books - methods: [GET] - defaults: - _controller: app.controller.book:indexAction - _sylius: - template: Author/books.html.twig - repository: - method: createPaginatorByAuthor - arguments: [$author] - criteria: - enabled: true - author.name: $author - paginate: false # Or: 50 - limit: 100 # Or: false - serialization_groups: [Custom, Details] - serialization_version: 1.0.2 +# config/routes.yaml + +app_book_index: + path: /{author}/books + methods: [GET] + defaults: + _controller: app.controller.book:indexAction + _sylius: + template: Author/books.html.twig + repository: + method: createPaginatorByAuthor + arguments: [$author] + criteria: + enabled: true + author.name: $author + paginate: false # Or: 50 + limit: 100 # Or: false + serialization_groups: [Custom, Details] + serialization_version: 1.0.2 ``` **[Go back to the documentation's index](index.md)** diff --git a/docs/installation.md b/docs/installation.md index 235c7b6b0..3c510896e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -19,14 +19,16 @@ Otherwise you have to download .phar file. You need to enable the bundle and its dependencies in the kernel: ```php - return [ - new FOS\RestBundle\FOSRestBundle(), - new JMS\SerializerBundle\JMSSerializerBundle($this), - new Sylius\Bundle\ResourceBundle\SyliusResourceBundle(), - new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(), - new Bazinga\Bundle\HateoasBundle\BazingaHateoasBundle(), - new winzou\Bundle\StateMachineBundle\winzouStateMachineBundle(), - ]; +# config/bundles.php + +return [ + new FOS\RestBundle\FOSRestBundle(), + new JMS\SerializerBundle\JMSSerializerBundle($this), + new Sylius\Bundle\ResourceBundle\SyliusResourceBundle(), + new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(), + new Bazinga\Bundle\HateoasBundle\BazingaHateoasBundle(), + new winzou\Bundle\StateMachineBundle\winzouStateMachineBundle(), +]; ``` That's it! Now you can configure your first resource. diff --git a/docs/reference.md b/docs/reference.md index 4dd98d6b5..c0ecbf43d 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,53 +1,53 @@ ## Configuration Reference ```yaml - sylius_resource: - resources: - app.book: - driver: doctrine/orm +sylius_resource: + resources: + app.book: + driver: doctrine/orm + classes: + model: # Required! + interface: ~ + controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController + repository: ~ + factory: Sylius\Component\Resource\Factory\Factory + form: Sylius\Bundle\ResourceBundle\Form\Type\DefaultResourceType + validation_groups: [sylius] + options: + object_manager: default + templates: + form: Book/_form.html.twig + translation: classes: - model: # Required! + model: ~ interface: ~ controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController repository: ~ factory: Sylius\Component\Resource\Factory\Factory form: Sylius\Bundle\ResourceBundle\Form\Type\DefaultResourceType validation_groups: [sylius] - options: - object_manager: default templates: - form: Book/_form.html.twig - translation: - classes: - model: ~ - interface: ~ - controller: Sylius\Bundle\ResourceBundle\Controller\ResourceController - repository: ~ - factory: Sylius\Component\Resource\Factory\Factory - form: Sylius\Bundle\ResourceBundle\Form\Type\DefaultResourceType - validation_groups: [sylius] - templates: - form: Book/Translation/_form.html.twig - options: ~ + form: Book/Translation/_form.html.twig + options: ~ ``` ## Routing Generator Configuration Reference ```yaml - app_book: - resource: | - alias: app.book - path: library - identifier: code - criteria: - code: $code - section: admin - templates: :Book - form: App/Form/Type/SimpleBookType - redirect: create - except: ['show'] - only: ['create', 'index'] - serialization_version: 1 - type: sylius.resource +app_book: + resource: | + alias: app.book + path: library + identifier: code + criteria: + code: $code + section: admin + templates: :Book + form: App/Form/Type/SimpleBookType + redirect: create + except: ['show'] + only: ['create', 'index'] + serialization_version: 1 + type: sylius.resource ``` **[Go back to the documentation's index](index.md)** diff --git a/docs/routing.md b/docs/routing.md index 6b80c4aa2..85fb55268 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -7,160 +7,160 @@ SyliusResourceBundle ships with a custom route loader that can save you some tim To generate a full CRUD routing, simply configure it in your ``config/routes.yaml``: ```yaml - app_book: - resource: | - alias: app.book - type: sylius.resource +app_book: + resource: | + alias: app.book + type: sylius.resource ``` Results in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ ------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ ------------------------- - app_book_show GET ANY ANY /books/{id} - app_book_index GET ANY ANY /books/ - app_book_create GET|POST ANY ANY /books/new - app_book_update GET|PUT|PATCH ANY ANY /books/{id}/edit - app_book_delete DELETE ANY ANY /books/{id} +------------------------ --------------- -------- ------ ------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ ------------------------- +app_book_show GET ANY ANY /books/{id} +app_book_index GET ANY ANY /books/ +app_book_create GET|POST ANY ANY /books/new +app_book_update GET|PUT|PATCH ANY ANY /books/{id}/edit +app_book_delete DELETE ANY ANY /books/{id} ``` ## Using a Custom Path By default, Sylius will use a plural form of the resource name, but you can easily customize the path: ```yaml - app_book: - resource: | - alias: app.book - path: library - type: sylius.resource +app_book: + resource: | + alias: app.book + path: library + type: sylius.resource ``` Results in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ ------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ ------------------------- - app_book_show GET ANY ANY /library/{id} - app_book_index GET ANY ANY /library/ - app_book_create GET|POST ANY ANY /library/new - app_book_update GET|PUT|PATCH ANY ANY /library/{id}/edit - app_book_delete DELETE ANY ANY /library/{id} +------------------------ --------------- -------- ------ ------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ ------------------------- +app_book_show GET ANY ANY /library/{id} +app_book_index GET ANY ANY /library/ +app_book_create GET|POST ANY ANY /library/new +app_book_update GET|PUT|PATCH ANY ANY /library/{id}/edit +app_book_delete DELETE ANY ANY /library/{id} ``` ## Generating API CRUD Routing To generate a full API-friendly CRUD routing, add these YAML lines to your ``config/routes.yaml``: ```yaml - app_book: - resource: | - alias: app.book - type: sylius.resource_api +app_book: + resource: | + alias: app.book + type: sylius.resource_api ``` Results in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ ------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ ------------------------- - app_book_show GET ANY ANY /books/{id} - app_book_index GET ANY ANY /books/ - app_book_create POST ANY ANY /books/ - app_book_update PUT|PATCH ANY ANY /books/{id} - app_book_delete DELETE ANY ANY /books/{id} +------------------------ --------------- -------- ------ ------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ ------------------------- +app_book_show GET ANY ANY /books/{id} +app_book_index GET ANY ANY /books/ +app_book_create POST ANY ANY /books/ +app_book_update PUT|PATCH ANY ANY /books/{id} +app_book_delete DELETE ANY ANY /books/{id} ``` ## Excluding Routes If you want to skip some routes, simply use ``except`` configuration: ```yaml - app_book: - resource: | - alias: app.book - except: ['delete', 'update'] - type: sylius.resource +app_book: + resource: | + alias: app.book + except: ['delete', 'update'] + type: sylius.resource ``` Results in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ ------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ ------------------------- - app_book_show GET ANY ANY /books/{id} - app_book_index GET ANY ANY /books/ - app_book_create GET|POST ANY ANY /books/new +------------------------ --------------- -------- ------ ------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ ------------------------- +app_book_show GET ANY ANY /books/{id} +app_book_index GET ANY ANY /books/ +app_book_create GET|POST ANY ANY /books/new ``` ## Generating Only Specific Routes If you want to generate only some specific routes, simply use the ``only`` configuration: ```yaml - app_book: - resource: | - alias: app.book - only: ['show', 'index'] - type: sylius.resource +app_book: + resource: | + alias: app.book + only: ['show', 'index'] + type: sylius.resource ``` Results in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ ------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ ------------------------- - app_book_show GET ANY ANY /books/{id} - app_book_index GET ANY ANY /books/ +------------------------ --------------- -------- ------ ------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ ------------------------- +app_book_show GET ANY ANY /books/{id} +app_book_index GET ANY ANY /books/ ``` ## Generating Routing for a Section Sometimes you want to generate routing for different "sections" of an application: ```yaml - app_admin_book: - resource: | - alias: app.book - section: admin - type: sylius.resource - prefix: /admin - - app_library_book: - resource: | - alias: app.book - section: library - only: ['show', 'index'] - type: sylius.resource - prefix: /library +app_admin_book: + resource: | + alias: app.book + section: admin + type: sylius.resource + prefix: /admin + +app_library_book: + resource: | + alias: app.book + section: library + only: ['show', 'index'] + type: sylius.resource + prefix: /library ``` The generation results in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ ------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ ------------------------- - app_admin_book_show GET ANY ANY /admin/books/{id} - app_admin_book_index GET ANY ANY /admin/books/ - app_admin_book_create GET|POST ANY ANY /admin/books/new - app_admin_book_update GET|PUT|PATCH ANY ANY /admin/books/{id}/edit - app_admin_book_delete DELETE ANY ANY /admin/books/{id} - app_library_book_show GET ANY ANY /library/books/{id} - app_library_book_index GET ANY ANY /library/books/ +------------------------ --------------- -------- ------ ------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ ------------------------- +app_admin_book_show GET ANY ANY /admin/books/{id} +app_admin_book_index GET ANY ANY /admin/books/ +app_admin_book_create GET|POST ANY ANY /admin/books/new +app_admin_book_update GET|PUT|PATCH ANY ANY /admin/books/{id}/edit +app_admin_book_delete DELETE ANY ANY /admin/books/{id} +app_library_book_show GET ANY ANY /library/books/{id} +app_library_book_index GET ANY ANY /library/books/ ``` ## Using Custom Templates @@ -168,13 +168,13 @@ By default, ``ResourceController`` will use the templates namespace you have con You can easily change that per route, but it is also easy when you generate the routing: ```yaml - app_admin_book: - resource: | - alias: app.book - section: admin - templates: Admin/Book - type: sylius.resource - prefix: /admin +app_admin_book: + resource: | + alias: app.book + section: admin + templates: Admin/Book + type: sylius.resource + prefix: /admin ``` Following templates will be used for actions: @@ -188,11 +188,11 @@ Following templates will be used for actions: If you want to use a custom form: ```yaml - app_book: - resource: | - alias: app.book - form: App/Form/Type/AdminBookType - type: sylius.resource +app_book: + resource: | + alias: app.book + form: App/Form/Type/AdminBookType + type: sylius.resource ``` ``create`` and ``update`` actions will use ``App/Form/Type/AdminBookType`` form type. @@ -205,11 +205,11 @@ By default, after successful resource creation or update, Sylius will redirect t If you want to change that behavior, use the following configuration: ```yaml - app_book: - resource: | - alias: app.book - redirect: update - type: sylius.resource +app_book: + resource: | + alias: app.book + redirect: update + type: sylius.resource ``` ## API Versioning @@ -217,20 +217,20 @@ One of the ResourceBundle dependencies is JMSSerializer, which provides a useful If you would like to return only the second version of your object serializations, use the following snippet: ```yaml - app_book: - resource: | - alias: app.book - serialization_version: 2 - type: sylius.resource_api +app_book: + resource: | + alias: app.book + serialization_version: 2 + type: sylius.resource_api ``` What is more, you can use a path variable to dynamically change your request. You can achieve this by setting a path prefix when importing file or specify it in the path option. ```yaml - app_book: - resource: | - alias: app.book - serialization_version: $version - type: sylius.resource_api +app_book: + resource: | + alias: app.book + serialization_version: $version + type: sylius.resource_api ``` ### **Note** Remember that a dynamically resolved `books` prefix is no longer available when you specify ``path``, and it has to be defined manually. @@ -241,27 +241,27 @@ Sometimes it is convenient to add some additional constraint when resolving reso Assuming that the path prefix is `/libraries/{libraryId}`, if you would like to list all books from this library, you could use the following snippet: ```yaml - app_book: - resource: | - alias: app.book - criteria: - library: $libraryId - type: sylius.resource +app_book: + resource: | + alias: app.book + criteria: + library: $libraryId + type: sylius.resource ``` Which will result in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ --------------------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ --------------------------------------- - app_book_show GET ANY ANY /libraries/{libraryId}/books/{id} - app_book_index GET ANY ANY /libraries/{libraryId}/books/ - app_book_create GET|POST ANY ANY /libraries/{libraryId}/books/new - app_book_update GET|PUT|PATCH ANY ANY /libraries/{libraryId}/books/{id}/edit - app_book_delete DELETE ANY ANY /libraries/{libraryId}/books/{id} +------------------------ --------------- -------- ------ --------------------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ --------------------------------------- +app_book_show GET ANY ANY /libraries/{libraryId}/books/{id} +app_book_index GET ANY ANY /libraries/{libraryId}/books/ +app_book_create GET|POST ANY ANY /libraries/{libraryId}/books/new +app_book_update GET|PUT|PATCH ANY ANY /libraries/{libraryId}/books/{id}/edit +app_book_delete DELETE ANY ANY /libraries/{libraryId}/books/{id} ``` ## Using a Custom Identifier @@ -270,28 +270,28 @@ As you could notice the generated routing resolves resources by the ``id`` field If you want to look for books by ``isbn``, use the following configuration: ```yaml - app_book: - resource: | - identifier: isbn - alias: app.book - criteria: - isbn: $isbn - type: sylius.resource +app_book: + resource: | + identifier: isbn + alias: app.book + criteria: + isbn: $isbn + type: sylius.resource ``` Which will result in the following routes: ```bash - php bin/console debug:router +php bin/console debug:router ``` ``` - ------------------------ --------------- -------- ------ ------------------------- - Name Method Scheme Host Path - ------------------------ --------------- -------- ------ ------------------------- - app_book_show GET ANY ANY /books/{isbn} - app_book_index GET ANY ANY /books/ - app_book_create GET|POST ANY ANY /books/new - app_book_update GET|PUT|PATCH ANY ANY /books/{isbn}/edit - app_book_delete DELETE ANY ANY /books/{isbn} +------------------------ --------------- -------- ------ ------------------------- +Name Method Scheme Host Path +------------------------ --------------- -------- ------ ------------------------- +app_book_show GET ANY ANY /books/{isbn} +app_book_index GET ANY ANY /books/ +app_book_create GET|POST ANY ANY /books/new +app_book_update GET|PUT|PATCH ANY ANY /books/{isbn}/edit +app_book_delete DELETE ANY ANY /books/{isbn} ``` **[Go back to the documentation's index](index.md)** diff --git a/docs/show_resource.md b/docs/show_resource.md index 76fa1565e..fd892e577 100644 --- a/docs/show_resource.md +++ b/docs/show_resource.md @@ -7,11 +7,13 @@ The simplest action is **showAction**. It is used to display a single resource. Let's assume that you have a ``app.book`` resource registered. To display a single Book, define the following routing: ```yaml - app_book_show: - path: /books/{id} - methods: [GET] - defaults: - _controller: app.controller.book:showAction +# config/routes.yaml + +app_book_show: + path: /books/{id} + methods: [GET] + defaults: + _controller: app.controller.book:showAction ``` Done! Now when you go to ``/books/3``, ResourceController will use the repository (``app.repository.book``) to find a Book with the given id (``3``). If the requested book resource does not exist, it will throw a ``404 Not Found`` exception. @@ -24,13 +26,15 @@ with the Book result as the ``book`` variable. That's the most basic usage of th Okay, but what if you want to display the same Book resource, but with a different representation in a view? ```yaml - app_admin_book_show: - path: /admin/books/{id} - methods: [GET] - defaults: - _controller: app.controller.book:showAction - _sylius: - template: Admin/Book/show.html.twig +# config/routes.yaml + +app_admin_book_show: + path: /admin/books/{id} + methods: [GET] + defaults: + _controller: app.controller.book:showAction + _sylius: + template: Admin/Book/show.html.twig ``` Nothing more to do here, when you go to ``/admin/books/3``, the controller will try to find the Book and render it using the custom template you specified under the route configuration. Simple, isn't it? @@ -40,15 +44,17 @@ it using the custom template you specified under the route configuration. Simple Displaying books by id can be boring... and let's say we do not want to allow viewing disabled books. There is a solution for that! ```yaml - app_book_show: - path: /books/{title} - methods: [GET] - defaults: - _controller: app.controller.book:showAction - _sylius: - criteria: - title: $title - enabled: true +# config/routes.yaml + +app_book_show: + path: /books/{title} + methods: [GET] + defaults: + _controller: app.controller.book:showAction + _sylius: + criteria: + title: $title + enabled: true ``` With this configuration, the controller will look for a book with the given title and exclude disabled books. Internally, it simply uses the ``$repository->findOneBy(array $criteria)`` method to look for the resource. @@ -59,15 +65,17 @@ By default, resource repository uses **findOneBy(array $criteria)**, but in some Creating yet another action to change the method called could be a solution but there is a better way. The configuration below will use a custom repository method to get the resource. ```yaml - app_book_show: - path: /books/{author} - methods: [GET] - defaults: - _controller: app.controller.book:showAction - _sylius: - repository: - method: findOneNewestByAuthor - arguments: [$author] +# config/routes.yaml + +app_book_show: + path: /books/{author} + methods: [GET] + defaults: + _controller: app.controller.book:showAction + _sylius: + repository: + method: findOneNewestByAuthor + arguments: [$author] ``` Internally, it simply uses the ``$repository->findOneNewestByAuthor($author)`` method, where ``author`` is taken from the current request. @@ -76,15 +84,17 @@ Internally, it simply uses the ``$repository->findOneNewestByAuthor($author)`` m If you would like to use your own service to get the resource, then try the following configuration: ```yaml - app_book_show: - path: /books/{author} - methods: [GET] - defaults: - _controller: app.controller.book:showAction - _sylius: - repository: - method: ["expr:service('app.repository.custom_book_repository')", "findOneNewestByAuthor"] - arguments: [$author] +# config/routes.yaml + +app_book_show: + path: /books/{author} + methods: [GET] + defaults: + _controller: app.controller.book:showAction + _sylius: + repository: + method: ["expr:service('app.repository.custom_book_repository')", "findOneNewestByAuthor"] + arguments: [$author] ``` With this configuration, method ``findOneNewestByAuthor`` from service with ID ``app.repository.custom_book_repository`` will be called to get the resource. @@ -92,20 +102,22 @@ With this configuration, method ``findOneNewestByAuthor`` from service with ID ` ## Configuration Reference ```yaml - app_book_show: - path: /books/{author} - methods: [GET] - defaults: - _controller: app.controller.book:showAction - _sylius: - template: Book/show.html.twig - repository: - method: findOneNewestByAuthor - arguments: [$author] - criteria: - enabled: true - serialization_groups: [Custom, Details] - serialization_version: 1.0.2 +# config/routes.yaml + +app_book_show: + path: /books/{author} + methods: [GET] + defaults: + _controller: app.controller.book:showAction + _sylius: + template: Book/show.html.twig + repository: + method: findOneNewestByAuthor + arguments: [$author] + criteria: + enabled: true + serialization_groups: [Custom, Details] + serialization_version: 1.0.2 ``` **[Go back to the documentation's index](index.md)** diff --git a/docs/update_resource.md b/docs/update_resource.md index 0178b46f4..a3a1136f5 100644 --- a/docs/update_resource.md +++ b/docs/update_resource.md @@ -3,11 +3,13 @@ To display an edit form of a particular resource, change it or update it via API, you should use the **updateAction** action of your **app.controller.book** service. ```yaml - app_book_update: - path: /books/{id}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction +# config/routes.yaml + +app_book_update: + path: /books/{id}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction ``` Done! Now when you go to ``/books/5/edit``, ResourceController will use the repository (``app.repository.book``) to find the book with id == **5**. If found it will create the ``app_book`` form, and set the existing book as data. @@ -17,8 +19,8 @@ If found it will create the ``app_book`` form, and set the existing book as data You can use exactly the same route to handle the submit of the form and updating the book. ```html -
- + + ``` On submit, the update action with method PUT, will bind the request on the form, and if it is valid it will use the right manager to persist the resource. Then, by default it redirects to ``app_book_show`` to display the updated book, but like for creation of the resource - it's customizable. @@ -30,13 +32,15 @@ When validation fails, it will simply render the form again, but with error mess Just like for other actions, you can customize the template. ```yaml - app_book_update: - path: /books/{id}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - template: Admin/Book/update.html.twig +# config/routes.yaml + +app_book_update: + path: /books/{id}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + template: Admin/Book/update.html.twig ``` ## Using Custom Form @@ -44,13 +48,15 @@ Just like for other actions, you can customize the template. Same way like for **createAction** you can override the default form. ```yaml - app_book_update: - path: /books/{id}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - form: App\Form\BookType +# config/routes.yaml + +app_book_update: + path: /books/{id}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + form: App\Form\BookType ``` ## Passing Custom Options to Form @@ -59,16 +65,18 @@ Same way like for **createAction** you can pass options to the form. Below you can see how to specify custom options, in this case, ``validation_groups``, but you can pass any option accepted by the form. ```yaml - app_book_update: - path: /books/{id}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - form: - type: app_book_custom - options: - validation_groups: [sylius, my_custom_group] +# config/routes.yaml + +app_book_update: + path: /books/{id}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + form: + type: app_book_custom + options: + validation_groups: [sylius, my_custom_group] ``` ## Overriding the Criteria @@ -76,13 +84,15 @@ Below you can see how to specify custom options, in this case, ``validation_grou By default, the **updateAction** will look for the resource by id. You can easily change that criteria. ```yaml - app_book_update: - path: /books/{title}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - criteria: { title: $title } +# config/routes.yaml + +app_book_update: + path: /books/{title}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + criteria: { title: $title } ``` ## Custom Redirect After Success @@ -90,26 +100,30 @@ By default, the **updateAction** will look for the resource by id. You can easil By default the controller will try to get the id of resource and redirect to the "show" route. To change that, use the following configuration. ```yaml - app_book_update: - path: /books/{id}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - redirect: app_book_index +# config/routes.yaml + +app_book_update: + path: /books/{id}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + redirect: app_book_index ``` You can also perform more complex redirects, with parameters. For example: ```yaml - app_book_update: - path: /genre/{genreId}/books/{id}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - redirect: - route: app_genre_show - parameters: { id: $genreId } +# config/routes.yaml + +app_book_update: + path: /genre/{genreId}/books/{id}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + redirect: + route: app_genre_show + parameters: { id: $genreId } ``` ## Custom Event Name @@ -119,13 +133,15 @@ The pattern is always the same - ``{applicationName}.{resourceName}.pre/post_upd own action name. ```yaml - app_book_customer_update: - path: /customer/book-update/{id} - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - event: customer_update +# config/routes.yaml + +app_book_customer_update: + path: /customer/book-update/{id} + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + event: customer_update ``` This way, you can listen to ``app.book.pre_customer_update`` and ``app.book.post_customer_update`` events. It's especially useful, when you use ``ResourceController:updateAction`` in more than one route. @@ -137,14 +153,16 @@ Depending on your app approach it can be useful to return a changed object or on Sylius, by default is returning the ``204 HTTP Code``, which indicates an empty response. If you would like to receive a whole object as a response you should set a ``return_content`` option to true. ```yaml - app_book_update: - path: /books/{title}/edit - methods: [GET, PUT] - defaults: - _controller: app.controller.book:updateAction - _sylius: - criteria: { title: $title } - return_content: true +# config/routes.yaml + +app_book_update: + path: /books/{title}/edit + methods: [GET, PUT] + defaults: + _controller: app.controller.book:updateAction + _sylius: + criteria: { title: $title } + return_content: true ``` ### **Warning** @@ -154,25 +172,27 @@ It is worth noticing, that the ``applyStateMachineTransitionAction`` returns a d ## Configuration Reference ```yaml - app_book_update: - path: /genre/{genreId}/books/{title}/edit - methods: [GET, PUT, PATCH] - defaults: - _controller: app.controller.book:updateAction - _sylius: - template: Book/editInGenre.html.twig - form: app_book_custom - event: book_update - repository: - method: findBookByTitle - arguments: [$title, expr:service('app.context.book')] - criteria: - enabled: true - genreId: $genreId - redirect: - route: app_book_show - parameters: { title: resource.title } - return_content: true +# config/routes.yaml + +app_book_update: + path: /genre/{genreId}/books/{title}/edit + methods: [GET, PUT, PATCH] + defaults: + _controller: app.controller.book:updateAction + _sylius: + template: Book/editInGenre.html.twig + form: app_book_custom + event: book_update + repository: + method: findBookByTitle + arguments: [$title, expr:service('app.context.book')] + criteria: + enabled: true + genreId: $genreId + redirect: + route: app_book_show + parameters: { title: resource.title } + return_content: true ``` **[Go back to the documentation's index](index.md)**