Application and framework integration

This library is framework-agnostic, but using it in an application that relies on a framework is still possible.

For Symfony applications, check out the chapter below. For other frameworks, check out the custom integration chapter.

Symfony bundle

A bundle is available to automatically integrate this library into a Symfony application.

composer require cuyz/valinor-bundle

The documentation of this bundle can be found on the GitHub repository.

Custom integration

If the application does not have a dedicated framework integration, it is still possible to integrate this library manually.

Mapper and normalizer registration

The most important task of the integration is to correctly register the mapper(s) and normalizer(s) used in the application. Mapper instance(s) should be shared between services whenever possible; this is important because heavy operations are cached internally to improve performance during runtime.

If the framework uses a service container, it should be configured in a way where the mapper(s) and normalizer(s) are registered as shared services. In other cases, direct instantiation of these services should be avoided.

$mapperBuilder = new \CuyZ\Valinor\MapperBuilder();
$normalizerBuilder = new \CuyZ\Valinor\NormalizerBuilder();

// …customization of the mapper builder and normalization builder…

$mapper = $mapperBuilder->mapper();
$jsonNormalizer = $normalizerBuilder->normalizer(\CuyZ\Valinor\Normalizer\Format::json());

$container->addSharedService('mapper', $mapper);
$container->addSharedService('normalizer_json', $jsonNormalizer);

Registering a cache

As mentioned above, caching is important to allow the mapper to perform well. The application really should provide a cache implementation to the mapper builder.

As stated in the performance chapter, the library provides a cache implementation out of the box which can be used in any application.

$cache = new \CuyZ\Valinor\Cache\FileSystemCache('path/to/cache-directory');

// If the application can detect when it is in development environment, it is
// advised to wrap the cache with a `FileWatchingCache` instance, to avoid
// having to manually clear the cache when a file changes during development.
if ($isApplicationInDevelopmentEnvironment) {
    $cache = new \CuyZ\Valinor\Cache\FileWatchingCache($cache);
}

$mapperBuilder = $mapperBuilder->withCache($cache);
$normalizerBuilder = $normalizerBuilder->withCache($cache);

Warming up and clearing the cache

The cache can be warmed up to ease the application cold start. If the framework has a way to automatically detect which classes will be used by the mapper, they should be given to the warmupCacheFor method, as stated in the cache warmup chapter.

The cache can also be cleared when needed, this can be done by calling MapperBuilder::clearCache() or NormalizerBuilder::clearCache().

Other configurations

Concerning other configurations, such as flexible modes, configuring supported date formats or registering custom constructors, an integration should be provided to configure the mapper/normalizer builder in a convenient way — how it is done will mostly depend on the framework features and its main philosophy.