exsyst/normalizer-extra-bundle

An icing on top of the Symfony serializer cake

0.4.5 2024-06-10 22:09 UTC

Requires

• php: ^8.3.0
• doctrine/orm: ~2.6|dev-2.6-exsyst|dev-2.17-exsyst
• exsyst/dynamic-class-generation-bundle: 0.1.*
• exsyst/mini-enum: ~1.0
• symfony/dependency-injection: ~4.0|~5.0
• symfony/http-foundation: ~4.0|~5.0
• symfony/property-info: ~4.0|~5.0
• symfony/serializer: ~4.0|~5.0

MIT

• Exter-N

README

A mostly opinionated bundle which aims to ease creation of efficient API servers with the Symfony serializer, while trying to stay lightweight.

How to use?

1. Make sure you have a Symfony 3.* or 4.* project, with the Serializer component, and the Doctrine ORM ;
2. Run composer require exsyst/normalizer-extra-bundle in your project ;
3. Add a section to your project configuration to choose the features you want to use (see below) ;
4. Further customize and/or extend the bundle's behavior if you want (documentation will come later) ;
5. Start (de)serializing things!

Features and default configuration

The only features that are enabled by default are the ones that :

• Are inert on their own, or ;
• Define a reasonable, unopinionated behavior for cases that were completely unsupported.

exsyst_normalizer_extra:
  features:
    # Makes $request->request able to access the request body in the
    # Content-Type: application/json, application/xml, application/x-yaml,
    # text/csv cases and/or others depending on serializer support.
    # Enabled by default.
    request_decoder: true

    # Parses a JSON document in a header named "Response-Shape",
    # into a request attribute named "shape", used so that the client
    # can filter out unneeded fields.
    # Enabled by default.
    response_shape_header: true

    # Allows a controller to return an object or null and have it
    # automatically turned into a Response.
    # Disabled by default.
    serializer_view_listener: false

    # Allows a controller to throw a HttpException and have it
    # automatically turned into a Response.
    # Disabled by default.
    serializer_exception_listener: false

  normalizers:
    # A normalizer geared towards Doctrine collections, which also
    # supports most iterables (though in a limited way).
    # Disabled by default.
    collection: false

    # A normalizer for PHP 8.1+ enums. It will normalize backed enum
    # cases into their values, and unit enum cases into their names.
    # Disabled by default.
    enum: false

    # A meta-normalizer that can generate fast normalizers for most
    # classes, and delegate to them.
    # Disabled by default.
    specializing: false
  options:
    # Always use a breadth-first normalization algorithm, that can
    # optimize initialization operations by batching them.
    # Some normalizers may be incompatible.
    # Disabled by default.
    implicit_breadth_first: false

    # When using the breadth-first normalization algorithm (see above),
    # only normalize each object once in each normalized graph.
    # An object that appears at several places will have its extra
    # properties merged into the first normalized instance, and the
    # other instances will be replaced by stubs.
    # Disabled by default.
    implicit_merge_objects: false

    # Automatically provides metadata consumers with information
    # obtained by using Symfony's PropertyInfo component and serializer
    # metadata, Doctrine's mappings, and attributes.
    # Enabled by default.
    auto_metadata: true

    # Parameters to use in the (de)serialization context of the services
    # defined by enabling the above features.
    # Null by default, which is treated the same as an empty mapping.
    default_context: ~
  unsafe_features:
    # Optimizes Doctrine collection initializations by batching them.
    # Disabled by default.
    collection_batching: false

    # Optimizes Doctrine entity proxy initializations by batching them.
    # Disabled by default.
    entity_batching: false