Download the PHP package webiny/hrc without Composer

On this page you can find all versions of the php package webiny/hrc. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package hrc

HRC - Http Request Cache

This is a cache management system that provides control mechanisms around your cache. Caches are tied to the incoming HTTP request. In practice that means that you can create caches based on a combination of a request path, cookies, sent headers, query strings and some custom callbacks.

... but I use memcache (or redis)

Sure, but that's not a cache management system, that's just a storage ... managing cache requires a lot of knowledge and it's not an easy thing to do (especially with memcache).

A much smarter person than me, once stated:

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

You can still use memcache, redis or any other cache storage system you want, just create a driver for it and hook it into Hrc. (see the guide down below)

Installation

Requires PHP 7.0 or later.

How it works

1. Define a set of cache rules

Cache rules define how and if something can be cached. For example, a simple cache rule looks something like this:

Ttl (Time-to-live) defines for how long that entry should be kept in cache.

Tags are used to tag the content, so you can invalidate it easier.

Match is a set of match criterias that the rule needs to satisfy in order for you to be able to store content. They also define what is used to create a cache key.

Match criteria

There are several things you can use in your match criteria:

Match options:

Here are some match examples:

The Callback section is used to invoke a custom callback which is basically just an extension to the match rules. The callback method should return a value, that value will be used to build the cache key. If the callback returns boolean false, the rule will not match the request.

A callback method takes two parameters, Webiny\Hrc\Request and Webiny\Hrc\CacheRules\CacheRule\CacheRule:

Although not recommended, instead of strictly specifying match options for Cookie, Header and Query, you can put a *, to simply take all received parameters (eg. all query parameters), and build a cache key for any variation in a request.

2. Cache storage

Hrc is built in a way that you can store cache using any storage you want, from memcache to mongodb. By default we provide a filesystem storage and MongoDb. If you write a driver for any other storage mechanism, send over a pull request, and we will gladly merge it.

Creating a storage drive is rather simple, just create a class and implement Webiny\Hrc\CacheStorage\CacheStorageInterface. You have 3 simple methods to implement, and you're done.

3. Index storage

Index storage is used to store additional cache information, you can look at it as a combination of cache metadata and taxonomy. The index is mainly used to achieve more possibilities around cache invalidation and faster cache invalidation times.

By default we provide a filesystem cache index and a MongoDb cache index, to create a custom-one, just implement Webiny\Hrc\IndexStorage\IndexStorageInterface.

Mongo storage and index

If you plan to use the Mongo cache storage and cache index, make sure you run the installCollections method prior to using the driver, otherwise the required indexes won't be created and the performance will be slow.

You need to run this only once. Alternative approach is to create the two collections and indexes manually:

4. Matching a cache rule

When you call the read or save method, if you don't provide the name of the cache rule, the class will run through all of defined cache rules, and will select the first rule that matched the request. However if you provide the cache rule name, the cache rule match patterns still must match, but the check will only be done on that particular rule. By providing a cache rule name, you can match multiple cache rules inside the same HTTP request.

5. Callbacks

There are two main callback events supported:

To register a callback for those events create a class that implements \Webiny\Hrc\EventCallbackInterface. You will have to implement all the callback methods. Both save methods receive 1 parameter, which is SavePayload instance. This instance contains all the relevant data about the current cache entry that is about to be created, or has been created. Similar is for the read methods, they receive the ReadPayload instance, which gives you access to the current cache entry as well as the option to set the purge flag, so that the content is actually purged and not retrieved from the database.

The callback methods don't need to return anything, but since the SavePayload instance is an object, on beforeSave you can use it to manipulate your cache entry, by changing the cache content, adding or removing tags and similar. On afterSave callback you will get back the same object, but this is just a confirmation that the object was successfully saved.

Cache purge

There are couple of ways you can purge cache:

Purge by cache key

When you save a cache entry, the save method will return a cache key, using that key, you can purge that particular entry:

Purge by tag

Every cache rule has one or more tags associated. Using the same tags, you can purge multiple cache entries. Note: when providing multiple tags, only entries that match ALL tags will be purged, or to put it in different words, we use logical AND condition between the tags.

Purge by request

There is a flag that you can set, so that every matched cache entry, inside the current request, will automatically be purged.

Another way of doing this is by sending a special request header inside your request. That header is X-HRC-Purge and it just needs to be defined, there is no need to set any value for it. Sending that header has the same effect as setting the purge flag to true, but this way you don't need to set the flag, and it's actually only valid for that particular request.

Security

Based on the previous section, you might think that there is a big risk in having that header, because everybody can purge the cache and hit your database/backend on every request...and that's true, but there's a built-in mechanism to prevent that. You can set a control key, so only requests that have a valid key can actually purge via the header.

Once the control header is set, you now need to send a X-HRC-Control-Key request header, containing the same value. Only if both values match, the purge request will be executed.

Bugs and improvements

Just report them under issues, or even better, send a pull request :)

License

MIT

Resources

To run unit tests, you need to use the following command:


All versions of hrc with dependencies

PHP Build Version
Package Version
Requires php Version >=7
webiny/mongo Version ~1.6 || dev-master
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package webiny/hrc contains the following files

Loading the files please wait ....