README

This package can be installed in a Laravel application to mark API endpoints as deprecated according to the Deprecation HTTP Header Field draft.

Installation

You can install the package via composer:

composer require wizofgoz/deprecation-laravel

Usage

Apply the middleware everywhere you want to be able to send deprecation headers, most likely the global middleware stack in the HTTP kernel.

protected $middleware = [
    \Wizofgoz\DeprecationLaravel\Http\Middleware\DeprecationAwareMiddleware::class,
];

During the course of the request life cycle, the resource that is being served can be marked as deprecated by using the facade, and the middleware will attach the appropriate headers to the response.

use \Wizofgoz\DeprecationLaravel\Deprecated;
use \Wizofgoz\DeprecationLaravel\Facades\Deprecation;
use \Wizofgoz\DeprecationLaravel\Links\AlternateLink;
use \Wizofgoz\DeprecationLaravel\Links\LatestLink;
use \Wizofgoz\DeprecationLaravel\Links\SuccessorLink;

// The resource is simply deprecated
$deprecated = Deprecated::new();

// The resource will be deprecated at a certain date
$deprecated = Deprecated::new()->setDate(new Carbon());

// Add a link to an alternate resource that could be used
$deprecated->addLink(new AlternateLink('https://example.com/resource'));

// Add a link to the resource that is the successor of this one
$deprecated->addLink(new SuccessorLink('https://example.com/resource'));

// Add a link to the resource that is the latest version of this one
$deprecated->addLink(new LatestLink('https://example.com/resource'));

// Apply the deprecation setting to the container so the middleware can pick it up
Deprecation::deprecate($deprecated);

// Unset a deprecation that has been set already
Deprecation::deprecate(null);

To convey that a resource will stop receiving requests in the future, they can be marked as sunsetted.

use \Wizofgoz\DeprecationLaravel\Sunset;
use \Wizofgoz\DeprecationLaravel\Facades\Deprecation;

$sunset = Sunset::new(new Carbon());

Deprecation::sunset($sunset);

// Unset a sunset that has been set already
Deprecation::sunset(null);

Events

Events are emitted when the middleware applies the Deprecation and Sunset headers. Simply, register listeners for either the DeprecatedResourceCalled or SunsettedResourceCalled events.

Event::listen(function (DeprecatedResourceCalled $event) {
    Log::warning('Call to deprecated resource: ' . $event->request->getUri());
});

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

wizofgoz / deprecation-laravel

Maintainers

Details