piotrpolak/conditional-routing-bundle

Provides a way to selectively load Symfony bundle routes based on a set of user defined conditions.

1.0.0 2018-10-25 16:00 UTC

Requires

• php: >=5.3.0
• symfony/config: ~2.3|~3.4
• symfony/dependency-injection: ~2.3|~3.4
• symfony/framework-bundle: ~2.3|~3.4
• symfony/http-kernel: ~2.3|~3.4
• symfony/routing: ~2.3|~3.4
• symfony/yaml: ~2.3|~3.4

Requires (Dev)

• codeclimate/php-test-reporter: ^0.3.2
• phpmd/phpmd: ^2.6
• phpunit/phpunit: ^4.8
• symfony/expression-language: ~2.3|~3.4

MIT

• Piotr Polak

README

Provides a way to load selected Symfony bundle routes based on a set of user defined conditions.

Solves the problem of redirecting (overwriting) Symfony application routes from a base bundle to another bundle.

Example usages

• Overwrite Symfony application routes for selected users and/or roles;
• Overwrite Symfony application routes based on the current time (e.g. switching monthly campaigns);
• Overwrite Symfony application routes based on session variable values;
• Overwrite Symfony application routes based on user role and HTTP domain.

Installation

Install composer package

composer require piotrpolak/conditional-routing-bundle

Enable PiotrPolakConditionalRoutingBundle in the application kernel

// in AppKernel::registerBundles()
$bundles = array(
    // ...
    new PiotrPolak\ConditionalRoutingBundle\PiotrPolakConditionalRoutingBundle(),
    // ...
);

Include bundle routing

Including routing.yml will enable the ConditionalRouterLoader.

# in app/config/routing.yml, without those lines ConditionalRouterLoader will not be enabled
conditional_routing:
    resource: "@PiotrPolakConditionalRoutingBundle/Resources/config/routing.yml"
    type:     yaml

Symfony will only load the resource loader if you use it for at least one route. You can alternatively paste the contents of the above resource file directly in your app/config/routing.yml.

Implement your own route resolver

Route resolvers are the components that implement RouteResolverInterface and decide which bundles' routing is to be included at the request time.

A typical route resolver component is registered in the container configuration under the conditional_loader.route_resolver tag - you can register any number of route resolver components and all of them will be taken in account when selecting the combination of bundles to be included.

Since you can pass any other component to the route resolver constructor (like @session, @security.token_storage...) bundles can be picked using any user defined scenarios.

Example - date condition

The following example loads MyCampaign2016Bundle routing based on the year condition. Note: MyCampaign2016Bundle must first be enabled in AppKernel.php.

Please note that AbstractYamlRouteResolver is just a helper that makes use of RouteResolverInterface easier.

<?php

namespace MyApp\Router;

use PiotrPolak\ConditionalRoutingBundle\Model\AbstractYamlRouteResolver;

class TimeCampaignRouteResolver extends AbstractYamlRouteResolver
{
    /**
     * {@inheritdoc}
     */
    public function resolveBundleNames()
    {
        // Loads @BaseCampaignBundle/Resources/config/routing.yml
        // In most cases it makes no sense to define bundle names that are ALWAYS loaded here as it can be done in the
        // app/config/routing.yml
        $bundleNames = ['BaseCampaignBundle'];
        if ((int)date('Y') >= 2016) {
            // Loads @MyCampaign2016Bundle/Resources/config/routing.yml
            // Can overwrite routes defined in BaseCampaignBundle or any other bundle
            $bundleNames[] = 'MyCampaign2016Bundle';
        }
        return $bundleNames;
    }
}

# in services.yml
services:
    # ...
    my_app.campaign_route_resolver:
        class: MyApp\CampaignRouteResolver
        tags:
            - { name: conditional_loader.route_resolver }

Example - database value input

Reading the current bundle name from the database.

<?php

namespace MyApp\Router;

use Doctrine\ORM\EntityManagerInterface;
use PiotrPolak\ConditionalRoutingBundle\Model\AbstractYamlRouteResolver;

class DatabaseCampaignRouteResolver extends AbstractYamlRouteResolver
{
    /** @var EntityManagerInterface */
    private $em;

    /**
     * CampaignRouteResolver constructor.
     * @param EntityManagerInterface $em
     */
    public function __construct(EntityManagerInterface $em)
    {
        $this->em = $em;
    }

    /**
     * {@inheritdoc}
     */
    public function resolveBundleNames()
    {
        // Loads @<CURRENT_BUNDLE_NAME>/Resources/config/routing.yml
        // Can overwrite any previously defined routes
        $bundleNames = [$this->getCurrentBundleName()];
        return $bundleNames;
    }

    /**
     * @return string
     */
    protected function getCurrentBundleName()
    {
        // Suppose you have a an entity having two fields: key and value
        // You might want to add some kind of cache to avoid reading from DB at every request
        return $this->em->getRepository('MyApp:Parameter')
                ->findOneBy(['key' => 'currentBundle'])
                ->getValue();
    }
}

# in services.yml
services:
    # ...
    my_app.database_campaign_route_resolver:
        class: MyApp\DatabaseCampaignRouteResolver
        arguments: ['@doctrine.orm.entity_manager']
        tags:
            - { name: conditional_loader.route_resolver }

Example - loading routing of various types

Route resolver from the following example implements directly the RouteResolverInterface and loads routing of both YAML and XML types.

<?php

namespace MyApp\Router;

use PiotrPolak\ConditionalRoutingBundle\Model\RouteResolverInterface;
use PiotrPolak\ConditionalRoutingBundle\Model\RoutingDefinition\XmlBundleRoutingDefinition;
use PiotrPolak\ConditionalRoutingBundle\Model\RoutingDefinition\YamlBundleRoutingDefinition;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\HttpFoundation\Session\SessionInterface;

class VariousTypesCampaignRouteResolver implements RouteResolverInterface
{
    /** @var EntityManagerInterface */
    private $em;
    /** @var SessionInterface */
    private $session;

    /**
     * VariousTypesCampaignRouteResolver constructor.
     * @param EntityManagerInterface $em
     * @param SessionInterface $session
     */
    public function __construct(EntityManagerInterface $em, SessionInterface $session)
    {
        $this->em = $em;
        $this->session = $session;
    }

    /**
     * {@inheritdoc}
     */
    public function resolveConditionalRoutingDefinitions()
    {
        $definitions = [];

        // Overwrites homepage for the first visit
        $numberOfHits = $this->session->get('my_app.number_of_visits', 0);
        $this->session->set('my_app.number_of_visits', $numberOfHits + 1);
        if (0 === $numberOfHits) {
            $definitions[] = new YamlBundleRoutingDefinition('MyAppFirstVisitBundle');
        }

        // Disables some of the business critical routes based on the database value
        if ($this->em->getRepository('MyApp:Parameters')->findIsMaintenanceModeOn()) {
            $definitions[] = new XmlBundleRoutingDefinition('MyAppMaintenanceModeBundle');
        }

        return $definitions;
    }
}

# in services.yml
services:
    # ...
    my_app.various_types_campaign_route_resolver:
        class: MyApp\VariousTypesCampaignRouteResolver
        arguments:
            - '@doctrine.orm.entity_manager'
            - '@session'
        tags:
            - { name: conditional_loader.route_resolver }

Compatibility

• PHP 5.4+
• Symfony 2.3-3.4

Precautions

If you are trying to generate a link to a route that is not currently active, Symfony will throw an error. To avoid situations like that please make sure all routes have their default behavior defined in one of you base bundles.

Development

Code should be checked using phpmd before being commited:

./vendor/phpmd/phpmd/src/bin/phpmd src/ text codesize,controversial,design,unusedcode,naming,cleancode

Testing

composer install --prefer-dist && ./vendor/bin/phpunit -v

To test in an arbitrary version combination, please use (sudo might be required to connect to the Docker daemon):

SYMFONY_VERSION=3.4 PHP_VERSION=7.4 bin/test_in_docker.sh

Known issues

Warming up the Symfony cache will nor remove the custom router matchers and generators as we are not able to predict the final combination of the router-enabled bundles (they are only known at the runtime).

A workaround to clean up the cache would be to add the following commands to your deploy scripts:

• Symfony 2

  rm -f ./app/cache/*/*UrlGenerator__*.php* && rm -f ./app/cache/*/*UrlMatcher__*.php*

• Symfony 3

  rm -f ./var/*/cache/*UrlGenerator__*.php* && rm -f ./var/*/cache/*UrlMatcher__*.php*