knplabs/rad-resource-resolver

A routing resource resolver based on conventions

v2.1 2017-04-05 10:14 UTC

README

Build Status Scrutinizer Code Quality Latest Stable Version Total Downloads Latest Unstable Version License

Why using it?

Tired of doing the same things again and again in your controllers, like transforming a URL value in an object? Don't want to use ParamConverter Annotations?

This Resource Resolver is for you.

Installation

With composer :

$ composer require knplabs/rad-resource-resolver

If you are using symfony2 you can update your app/AppKernel.php file:

public function registerBundles()
{
    $bundles = array(
        // bundles here ...
        new Knp\Rad\ResourceResolver\Bundle\ResourceResolverBundle(),
    );
}

How to use it?

In a yaml routing file, it could look like this :

    users_show:
        path: /users/{id}
        defaults:
            _resources:
                user:
                    service: my.user.repository
                    method: find
                    arguments: [$id]
    # This will automatically resolve the resource to give you a $user object in your request attributes
    countries_cities_buildings_index:
        path: /countries/{countryId}/cities/{citySlug}/buildings
        defaults:
            _resources:
                buildings:
                    service: app.building.repository
                    method: findByCountryAndCityAndActivity
                    arguments: [$countryId, $citySlug, "School"]
    # You will have a $buildings variable in your request attributes

Every key under _resources will be return as a $key converted value in your request attributes.

However, you can use more concise ways to express your resources configuration :

    product_show:
        path: /product/{slug}
        defaults:
            _resources:
                product: [ "my.repository.product:findBySlug", [ $slug ] ]
                bestSellers: "my.repository.seller:findBestSellers"
                # Supports invokable
                bestOffers: "my.repository.bestOffers"
                comments: ["my.repository.randomComments"]
                # Invokable with arguments
                relatedProducts: ["my.repository.relatedProducts", [10]]

Optional Resources

By default, the Rad Resource Resolver throws a Symfony\Component\HttpKernel\Exception\NotFoundHttpException if the resource was not found. You can override this behavior by adding the required option to false:

    _resources:
        buildings:
            service: app.building.repository
            method: findByCountryAndCityAndActivity
            arguments: [$countryId, $citySlug, "School"]
            required: false

Available resource resolving arguments

  • URL variables: you have to use the $ prefix. For example, if your URL is /products/{products}/ you can access to product value by using $product.
  • Services: you can use the @ prefix (ex: @doctrine)
  • Previously resolved resources: you can use the & prefix (ex: &user will return the user resource)

How does it work?

A ResourcesListener listens to kernel.controller event and resolves automatically all resources in _resources. The component uses ParameterCaster objects to catch different argument types and Parser objects to resolve _resources locations syntax.

This means you can easily add your own ParameterCasters and Parsers to change the syntax used by the component.

To add your own ParameterCaster, just tag it with knp_rad_resource_resolver.parameter_caster. The tag to add a Parser is knp_rad_resource_resolver.parser.

#Events

All events are listed here.

##How can I hook resource resolution ?

There is two events :

- knp_rad_resource_resolver.before_resource_resolved:  dispatched before the resolution. You can set the resource before the resolution.
- knp_rad_resource_resolver.resource_resolved:         dispatched after the resolution.

##How can I get all resolved resources ?

There is a service alias named knp_rad_resource_resolver.resource_container where you can get all resolved resources. You can also listen to the event knp_rad_resource_resolver.resource.added and be notified when a resource is added to the container.

License

This project is published under MIT License. Feel free to contribute.