Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/symfony-orchestra/view-bundle
The `view-bundle` is a simple and highly efficient Symfony bundle designed to replace Symfony Responses when working with the JSON API.
https://github.com/symfony-orchestra/view-bundle
api api-rest json symfony symfony-bundle
Last synced: 1 day ago
JSON representation
The `view-bundle` is a simple and highly efficient Symfony bundle designed to replace Symfony Responses when working with the JSON API.
- Host: GitHub
- URL: https://github.com/symfony-orchestra/view-bundle
- Owner: symfony-orchestra
- License: apache-2.0
- Created: 2024-03-05T09:38:29.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2024-04-01T08:21:09.000Z (6 months ago)
- Last Synced: 2024-09-20T06:18:22.384Z (5 days ago)
- Topics: api, api-rest, json, symfony, symfony-bundle
- Language: PHP
- Homepage:
- Size: 39.1 KB
- Stars: 251
- Watchers: 5
- Forks: 26
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# view-bundle
The `view-bundle` is a simple and highly efficient Symfony bundle designed to replace Symfony Responses when working with the JSON API.
The goal of the bundle is to separate the response views from the app's business logic, making them typed, configurable, and reusable across the app.
As a result, you will have a set of simple `View` classes with an internal hierarchy that is easily understandable by everybody in a team.
# Requirements
- PHP 8.3
- Symfony 7.0.*
- Doctrine common ^3.4
```json
{
"php": "^8.3",
"symfony/http-kernel": "7.0.*",
"symfony/serializer": "7.0.*",
"symfony/property-access": "7.0.*",
"symfony/dependency-injection": "7.0.*",
"symfony/config": "7.0.*",
"doctrine/common": "^3.4.3"
}
```
# Example
Let's consider the code below as an example.
We have an entity `User` with some fields and with the joined collection of `Image` images.
```php
notBoundField = $user->getCreatedDatetime();
}
}
```
```php
getUser());
}
}
```
Will produce the following 200 response
```json
{
"data": {
"id": "92c7c4d4-2ce0-4353-a9e2-6a3794c60d8f",
"firstName": "Andrew",
"images": [
{
"id": "eb9fa57e-3d8f-44c5-80d4-7f33220f1a48",
"path": "/grand-piano.png"
},
{
"id": "16d01967-9066-4dc9-9d82-028419ba0ed5",
"path": "/violin.png"
}
],
"notBoundField": "1685-03-31"
}
}
```
The response is fully controllable, you can still add different headers to the response using the stack of provided internal View classes (`ResponseView`).
The main payload is placed under the `data` key in the JSON array.
As you can see, the last name is omitted because `null` values were removed from the response to match with `undefined` properties while working with a `Typescript`.
# Installation
```
composer install symfony-orchestra/view-bundle:7.0.*
```
Add the bundle to `config/bundles.php`
```php
['all' => true],
];
```
To make it work your controller should return an object of instance of `SymfonyOrchestra\ViewBundle\View\ViewInterface` instead of `Symfony\Component\HttpFoundation\Response`.
# Cache
The most usable `SymfonyOrchestra\ViewBundle\View\BindView` which maps the properties of the class with the properties of the view comes with the cache support.
See `SymfonyOrchestra\ViewBundle\EventSubscriber\SetVersionSubscriber` for more details.
It uses `Symfony\Component\PropertyAccess\PropertyAccessor::createCache` when the env parameter `APP_DEBUG` is set to `false`.
# Internal views
The bundle comes with the several internal core views.
### \SymfonyOrchestra\ViewBundle\View\ResponseView
The main view that can be considered as a response. Contains headers and http status that can be overridden.
See `SymfonyOrchestra\EventSubscriber\ViewSubscriber`.
### \SymfonyOrchestra\ViewBundle\View\DataView
The inherited view of the `ResponseView`, that wraps all the data into `data` JSON key.
See `SymfonyOrchestra\EventSubscriber\ViewSubscriber`.
### \SymfonyOrchestra\ViewBundle\View\BindView
The helper View that maps the properties of the underlined object to the view as one to one. The most powerful one.
It uses `SymfonyOrchestra\ViewBundle\Utils\BindUtils` internally to map the properties.
```php
class User {
private int $int;
private string $string;
private iterable $collection
}
class UserView extends \SymfonyOrchestra\ViewBundle\View\BindView {
/** will take all the properties from the User class */
private int $int;
private string $string;
private array $collection
}
```
### \SymfonyOrchestra\ViewBundle\View\IterableView
The view for the iterable objects.
```php
class GetOptions extends GetAction
{
public function __invoke(Request $request): ViewInterface
{
$option1 = new Option();
$option2 = new Option();
return new \SymfonyOrchestra\ViewBundle\View\IterableView(
[$option1, $option2],
OptionView::class,
);
}
}
```
It can be used together with the `\SymfonyOrchestra\ViewBundle\Attribute\Type` and `\SymfonyOrchestra\ViewBundle\View\BindView`
attribute to simplify the workflow. In this case the underlined iterable objects will be automatically constructed based on the configured
type.
**Enjoy the orchestra! 🎻**