{"id":19247931,"url":"https://github.com/litespeedtech/lscache-laravel","last_synced_at":"2025-04-04T13:11:51.251Z","repository":{"id":52117107,"uuid":"181526408","full_name":"litespeedtech/lscache-laravel","owner":"litespeedtech","description":"LSCache for Laravel framework","archived":false,"fork":false,"pushed_at":"2025-02-23T09:58:46.000Z","size":51,"stargazers_count":55,"open_issues_count":2,"forks_count":15,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-28T12:08:48.055Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/litespeedtech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-15T16:34:22.000Z","updated_at":"2025-02-23T09:58:04.000Z","dependencies_parsed_at":"2024-06-21T02:36:06.291Z","dependency_job_id":"11498b79-6175-440a-a3b0-93a653f1d7f7","html_url":"https://github.com/litespeedtech/lscache-laravel","commit_stats":{"total_commits":36,"total_committers":5,"mean_commits":7.2,"dds":"0.16666666666666663","last_synced_commit":"c9b6057bd8495c951ea3a8e7562445825e677613"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flscache-laravel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flscache-laravel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flscache-laravel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flscache-laravel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/litespeedtech","download_url":"https://codeload.github.com/litespeedtech/lscache-laravel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247182401,"owners_count":20897381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T18:05:42.450Z","updated_at":"2025-04-04T13:11:51.226Z","avatar_url":"https://github.com/litespeedtech.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Laravel LSCache\n\nThis package allows you to use lscache together with Laravel.\n\nIt provides two middlewares and one facade:\n\n- LSCache Middleware to control the cache-control header for LiteSpeed LSCache\n- LSTags Middleware to control the tag header for LiteSpeed LSCache\n- LSCache facade to handle purging\n\n## Installation\n\nRequire this package using composer.\n\n```\ncomposer require litespeed/lscache-laravel\n```\n\nLaravel uses Auto-Discovery, so you won't have to make any changes to your application, the two middlewares and facade will be available right from the beginning.\n\n#### Steps for Laravel \u003e=5.1 and \u003c=5.4\n\nThe package can be used for Laravel 5.1 to 5.4 as well, however due to lack of Auto-Discovery, a few additional steps have to be performed.\n\nIn `config/app.php` you have to add the following code in your `aliases`:\n\n```\n'aliases' =\u003e [\n    ...\n    'LSCache'   =\u003e Litespeed\\LSCache\\LSCache::class,\n],\n```\n\nIn `app/Http/Kernel.php` you have to add the two middlewares under `middleware` and `routeMiddleware`:\n\n```\nprotected $middleware = [\n    ...\n    \\Litespeed\\LSCache\\LSCacheMiddleware::class,\n    \\Litespeed\\LSCache\\LSTagsMiddleware::class,\n];\n\nprotected $routeMiddleware = [\n    ...\n    'lscache' =\u003e \\Litespeed\\LSCache\\LSCacheMiddleware::class,\n    'lstags' =\u003e \\Litespeed\\LSCache\\LSTagsMiddleware::class,\n];\n```\n\nCopy `lscache.php` to `config/`:\n\nCopy the package `config/lscache.php` file to your `config/` directory.\n\n**important**: Do not add the ServiceProvider under `providers` in `config/app.php`.\n\n#### Steps for Laravel 5.5 and above\n\nYou should publish the package configuration, which allows you to set the defaults for the `X-LiteSpeed-Cache-Control` header:\n\n```\nphp artisan vendor:publish --provider=\"Litespeed\\LSCache\\LSCacheServiceProvider\"\n```\n\n### Enable CacheLookup for LiteSpeed Cache\n\nTo enable CacheLookup for LiteSpeed Cache, you have to include the following code, either on server, vhost or .htaccess level:\n\n```apacheconf\n\u003cIfModule LiteSpeed\u003e\n   CacheLookup on\n\u003c/IfModule\u003e\n```\n\n## Usage\n\nThe package comes with 3 functionalities: Setting the cache control headers for lscache, settings specific tags and purging.\n\n### cache-control\n\nYou'll be able to configure defaults in the `config/lscache.php` file, here you can set the max-age (`default_ttl`), the cacheability (`default_cacheability`) such as public, private or no-cache or enable esi (`esi`) in the `X-LiteSpeed-Cache-Control` response header.\n\nIf the `default_ttl` is set to `0`, then we won't return the `X-LiteSpeed-Cache-Control` response header.\n\nYou can control the config settings in your `.env` file as such:\n\n- `LSCACHE_ESI_ENABLED` - accepts `true` or `false` to whether you want ESI enabled or not globally; Default `false`\n- `LSCACHE_DEFAULT_TTL` - accepts an integer, this value is in seconds; Default: `0`\n- `LSCACHE_DEFAULT_CACHEABILITY` - accepts a string, you can use values such as `private`, `no-cache`, `public` or `no-vary`; Default: `no-cache`\n- `LSCACHE_GUEST_ONLY` - accepts `true` or `false` to decide if the cache should be enabled for guests only; Defaults to `false`\n\nYou set the cache-control header for lscache using a middleware, so we can in our routes do something like this:\n\n```php\nRoute::get('/', function() {\n    return view('frontpage');\n});\n\nRoute::get('/about-us', function() {\n    return view('about-us');\n})-\u003emiddleware('lscache:max-age=300;public');\n\nRoute::get('/contact', function() {\n    return view('contact');\n})-\u003emiddleware('lscache:max-age=10;private;esi=on');\n\nRoute::get('/admin', function() {\n    return view('admin');\n})-\u003emiddleware('lscache:no-cache');\n```\n\nBelow is 4 examples:\n- the `/` route will use the default X-LiteSpeed-Cache-Control header that you've configured in `config/lscache.php`.\n- the `/about-us` route sets a max-age of 300 seconds as well as setting the cacheability to `public`, keep in mind you'll use semi-colon (`;`) to separate these values.\n- the `/contact` route uses a max-age of 10 seconds, uses private cacheability and turns ESI on. Turning ESI on, allows you to use `\u003cesi:include\u003e` within your blade templates and these will be parsed by the ESI engine in LiteSpeed Web Server.\n- the `/admin` route will never be cached by setting a `X-LiteSpeed-Cache-Control: no-cache` -header.\n\nNow, you'll also be able to apply the same middleware to route groups in Laravel, let's take an example:\n\n```php\nRoute::group(['prefix' =\u003e 'admin', 'middleware' =\u003e ['lscache:private;esi=on;max-age=120']], function() {\n    Route::get('/dashboard', function() {\n        return view('dashboard');\n    });\n\n    Route::get('/stats', function() {\n        return view('stats');\n    })-\u003emiddleware('lscache:no-cache');\n});\n```\n\nIn the above case, we've set the whole `admin` group to be private with esi enabled and a max-age of 120 seconds, however in the `/admin/stats` route, we override the `X-LiteSpeed-Cache-Control` header to `no-cache`.\n\n### tags\n\nYou're also able to set tags for LSCache using the `lstags` middleware. If we use the previous example of our `admin` route group:\n\n```php\nRoute::group(['prefix' =\u003e 'admin', 'middleware' =\u003e ['lscache:private;esi=on;max-age=900', 'lstags:admin']], function() {\n    Route::get('/dashboard', function() {\n        return view('dashboard');\n    });\n\n    Route::get('/users', function() {\n        return view('users');\n    });\n});\n```\n\nHere we've added the `lstags:admin` middleware, this means that the cache will get tagged with an `admin` tag, so when we later want to purge the cache, we can target all admin pages using the tag `admin`.\n\nYou can also do more complex tags as such:\n\n```php\nRoute::get('/view', function() {\n    return view('view');\n})-\u003emiddleware(['lscache:private', 'lstags:public:pubtag1;public:pubtag2;public:pubtag3;privtag1;privtag2']);\n```\n\n### purge\n\nIf we have an admin interface that controls for example a blog, when you publish a new article, you might want to purge the frontpage of the blog so the article appears in the overview.\n\nYou'd do this in your controller by doing\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse LSCache;\n\nclass BlogController extends BaseController\n{\n    // Your article logic here\n\n    LSCache::purge('/');\n}\n```\n\nIn the above example, we're simply telling it to add an additional header called `X-LiteSpeed-Purge` with the value `stale,/`, this will invalidate the frontpage of the site.\n\nYou can also purge everything by doing:\n\n```php\nLSCache::purge('*');\n// or\nLSCache::purgeAll();\n```\n\nOne or multiple URIs can be purged by using a comma-separated list:\n\n```php\nLSCache::purge('/blog,/about-us,/');\n// or\nLSCache::purgeItems(['/blog', '/about-us', '/']);\n```\n\nYou can purge individual or multiple tags:\n\n```php\nLSCache::purge('tag=archive, tag=categories');\n// or\nLSCache::purgeTags(['archive', 'categories']);\n```\n\nOr if you want to purge private cache by tag:\n\n```php\nLSCache::purge('private, tag=users');\n```\n\nYou even have the possibility to purge a set of public tags and and purge all the private tags:\n\n```php\nLSCache::purge('pubtag1, pubtag2, pubtag3; private, *');\n```\n\nLiteSpeed Cache for Laravel 1.1.0 comes with a stale option turned on by default for the `LSCache::purge` function, this can be turned off by using `false` as the second parameter in the `purge` function:\n\n```php\nLSCache::purge('*', false);\n// or\nLSCache::purge('*', $stale=false);\n// or\nLSCache::purgeAll(false);\n```\n\n#### Why stale purge matters\n\nBy default the way Lscache works in LiteSpeed is by purging an element in the cache, and next request will generate the cached version.\n\nThis works great if you're running a fairly low traffic site, however if your application takes let's say 2 seconds to process a given request, all traffic received to this endpoint within those 2 seconds will end up hitting the backend, and all visitors will hit PHP.\n\nBy using the `stale,` keyword in front the \"key\" you're purging, you're telling Lscache to purge the item, but if multiple visitors hit the same endpoint right after each other, only the first visitor will be the one generating the cache item, all remaining vistors will get served the stale cached page until the new cached page is available.\n\nSince a page generation should be rather fast, we're only serving this stale content for maybe a couple of seconds, thus also the reason it's being enabled by default.\n\nIf your application cannot work with stale content at all, then you can use `false` or `$stale=false` as the second parameter in the `LSCache::purge()` function to disable this functionality.\n\nYou can also purge specific public tags by adding `~s` after the tag, such as:\n\n```php\nLSCache::purge('pubtag1, pubtag2~s, pubtag3; private, privtag1, privtag2', $stale=false);\n```\nOnly `pubtag2` will be served stale.\n\n### Laravel Authentication\n\nIf you use authentication in Laravel for handling guests and logged-in users, you'll likely want to also separate the cache for people based on this.\n\nThis can be done in the `.htaccess` file simply by using the cache-vary on the Authorization cookie:\n\n```apache\nRewriteEngine On\nRewriteRule .* - [E=Cache-Vary:Authorization]\n```\n\n**Note: In the above example we use `Authorization`, this may have a different name depending on your setup, so it has to be changed accordingly.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitespeedtech%2Flscache-laravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flitespeedtech%2Flscache-laravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitespeedtech%2Flscache-laravel/lists"}