- Installation - how to register a plugin
- Configuration - how to configure
- Negotiation - content negotiation
- Playground - real examples
This plugin requires Apitte/Core library.
At first you have to register the main extension.
extensions: api: Apitte\Core\DI\ApiExtension
Secondly, add the
api: plugins: Apitte\Negotiation\DI\NegotiationPlugin:
You can configure a few options.
api: plugins: Apitte\Negotiation\DI\NegotiationPlugin: unification: false catchException: false
unification- Change default
JsonUnifyTransform. You will see in next capter.
catchException- Great for front-end developers, convert (catch) Tracy-exception to JSON.
This plugin adds new features. They are called decorators, negotiators and transformers.
Basically, decorator listen on specic event and can modify incomming request or outgoing response directly or via negotiator. The negotiator has the handling logic, if request has an appropriate extension or header and call the transformer. All modifications (trasforming data from A to B) is done in transformer, e.q. transform array to json.
There are 2 predefined decorators:
ResponseEntityDecorator- It listens on 2 events, after dispatching and after exception. It means this decorator is trigged when the response is returned from controller or if some exception is throwed.
ThrowExceptionDecorator- This decorator is appliable only in debug mode. It just diplays the exception for you.
The main goal of the negotiator is determine if given request/response apply all conditions and call the transformer.
There are 3 predefined transformers:
SuffixNegotiator- It's called if the URI ends with the given suffix, e.q
DefaultNegotiator- It's called when the route is matched and annotation
@Negotiation(default = true)has provided default attribute.
FallbackNegotiator- The last one transformer. It's called when no other negotiator is matched.
These classes transform data formats from A to B.
JsonTransform- The most used transformer,
JsonUnifyTransform- Applied when the
unificationis enabled. Transformer,
json(with formatted response).
csv, but the entity must have an appropriate data.
RendererTransformer- This is special transformer. If annotation
@Negotiation(renderer = App\Some\Classhas provided renderer attribute, this transformer recieve that renderer,
I've made a repository with full applications for education.
Take a look: https://github.com/apitte/playground