Download the PHP package sofascore/purgatory without Composer

Purgatory

Purgatory is an extension which makes it possible for Symfony applications to handle enormous load using minimal infrastructure. Infrastructure meant to be used with this bundle along with Symfony application is a HTTP caching reverse proxy.

This bundle implements an easy and maintainable way to invalidate cache on endpoints based on changes in Doctrine entities.

Installation

Prerequisite - doctrine/orm

composer require sofascore/purgatory-bundle

Setup - Symfony reverse proxy

Enable Symfony Http Cache component in config/packages/framework.yaml

Wrap the default kernel into HttpCache caching kernel public/index.php

Define implementation of PurgerInterface and host to purge in config/packages/purgatory

Usage

Suppose you have a simple entity and controller.

When a request is sent to an endpoint for first time, reverse proxy saves the response and serves the same response until it expires (1 hour in this example). If the state of an entity changes in the meantime, content on the website stays the same until cache expires.

Purgatory has an annotation which defines rules for cache invalidation when a state of an object changes.

PurgeOn annotation

Parameters:

• Required FQCN of an entity whose changes are being tracked for cache purging.
• parameters
  • defines an associative array where keys are route parameters and values are property names.
• properties
  • list of properties which are required to change in order to purge the endpoint.
  • if omitted, change of any property purges the cache.
• if
  • an expression which has to be true in order to purge the endpoint with specified parameters.

Workflow

When property of Post entity is changed and flushed to a database, Purgatory goes through PurgeOn annotations where changed property is in list of properties, checks the if expression, injects the parameters and purges the route.

Custom Purger

If you have a more complex setup or use varnish (recommended) you should implement your own purger that will be aware of your infrastructure.

Example purger:

You must also register that Purger with the configuration:

Add purge capability to varnish

That's it!

Examples

Endpoint which fetches all properties of a single post.

Use PurgeOn with FQCN and map route parameters with property of an entity. On change of any property of a Post, endpoint with entity id injected as route parameter postId gets invalidated.

Endpoint which fetches all featured Posts.

Use PurgeOn and specify a single property - cache invalidation happens every time property featured changes on any of the Posts.

Endpoint which fetches a list of all popular posts with more than 3000 upvotes.

Use PurgeOn with a condition - cache invalidation happens every time property upvotes on a Post with more than 3000 upvotes changes.

Debugging

Purgatory debug command groups all defined purging rules and dumps it on the screen. Its argument is an entity name or entity and property.

Command with defined entity and property dumps all routes which get refreshed by change of that property.

Observe that change of upvotes causes a cache invalidation on popular posts route as well as on post details route.