halloverden/symfony-route-deprecation-bundle

The Route Deprecation Bundle provides tools to deprecate routes in your Symfony application. It implements the IETF draft of The Deprecation HTTP Header Field.

2.0.1 2022-09-12 18:17 UTC

README

The Route Deprecation Bundle provides tools to deprecate routes in your Symfony application. It implements the IETF draft of The Deprecation HTTP Header Field.

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

$ composer require halloverden/symfony-route-deprecation-bundle

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require halloverden/symfony-route-deprecation-bundle

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:

// config/bundles.php

return [
    // ...
    HalloVerden\RouteDeprecationBundle\HalloVerdenRouteDeprecationBundle::class => ['all' => true],
];

Usage

You can deprecate a route in any route definition (annotation, yaml, xml, php, what have you) by passing three values to the defaults option:

  • _deprecated_since is a string ("yyyy-mm-dd") that defines the moment in which a route becomes deprecated. The header Deprecation will be set on the response, like so: Deprecation: date="Wed, 01 Jan 2020 00:00:00 GMT".

  • _sunset_at is a string ("yyyy-mm-dd") that defines the moment in which a route becomes expired. The header Sunset will be set on the response, like so: Sunset: date="Mon, 01 Jun 2020 00:00:00 GMT".

  • _enforce_sunset is a boolean that makes the route inaccessible after the _sunset_at date. If you try to access a route where this option is set to true and the current date is greater than the _deprecated_until date, a GoneHttpException is thrown.

You can deprecate a method / endpoint in a controller, or the controller itself (to deprecate all methods / endpoints in the controller).

Example using annotations:

namespace App\Controller;

use Symfony\Component\Routing\Annotation\Route;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

/**
 * @Route("/", defaults={"_deprecated_since"="2020-01-01", "_sunset_at"="2020-06-01", "_enforce_sunset"=false)
 */
class TestController extends AbstractController {
  /**
   * @Route("/test", methods={"GET"}, name="test", defaults={"_deprecated_since"="2020-01-01", "_sunset_at"="2020-06-01", "_enforce_sunset"=true)
   */
  public function test() {
    // Controller method stuff
  }
}

@DeprecatedRoute annotation

The bundle also ships with a handy new annotation, called @DeprecatedRoute, and is used like so:

namespace App\Controller;

use HalloVerden\RouteDeprecationBundle\Annotation\DeprecatedRoute;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

/**
 * @DeprecatedRoute("/", since="2020-01-01", until="2020-06-01", enforce=false)
 */
class TestController extends AbstractController {
  /**
   * @DeprecatedRoute("/test", methods={"GET"}, name="test", since="2020-01-01", until="2020-06-01", enforce=true)
   */
  public function test() {
    // Controller method stuff
  }
}

It's just a convenience annotation that behind the curtains makes use of Symfony\Component\Routing\Annotation\Route, but it reads nice. It can be mixed with the @Route annotation.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT