{"id":19107762,"url":"https://github.com/alleyinteractive/wp-page-cache-control","last_synced_at":"2025-09-13T05:31:52.045Z","repository":{"id":177352371,"uuid":"660267685","full_name":"alleyinteractive/wp-page-cache-control","owner":"alleyinteractive","description":"Control and modify the page cache for multiple hosting providers.","archived":false,"fork":false,"pushed_at":"2024-10-12T13:48:08.000Z","size":6504,"stargazers_count":2,"open_issues_count":4,"forks_count":1,"subscribers_count":20,"default_branch":"develop","last_synced_at":"2024-10-20T09:17:12.620Z","etag":null,"topics":["wordpress","wordpress-plugin"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alleyinteractive.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":"2023-06-29T16:02:43.000Z","updated_at":"2024-10-12T13:48:13.000Z","dependencies_parsed_at":"2023-11-11T15:29:51.115Z","dependency_job_id":"bd21b7a6-5dcb-4b4b-979c-6c50c74165df","html_url":"https://github.com/alleyinteractive/wp-page-cache-control","commit_stats":null,"previous_names":["alleyinteractive/page-cache-control","alleyinteractive/wp-page-cache-control"],"tags_count":6,"template":false,"template_full_name":"alleyinteractive/create-wordpress-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-page-cache-control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-page-cache-control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-page-cache-control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-page-cache-control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alleyinteractive","download_url":"https://codeload.github.com/alleyinteractive/wp-page-cache-control/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223783042,"owners_count":17201915,"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":["wordpress","wordpress-plugin"],"created_at":"2024-11-09T04:13:52.628Z","updated_at":"2024-11-09T04:13:53.209Z","avatar_url":"https://github.com/alleyinteractive.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WP Page Cache Control\n\n[![Coding Standards](https://github.com/alleyinteractive/wp-page-cache-control/actions/workflows/coding-standards.yml/badge.svg)](https://github.com/alleyinteractive/wp-page-cache-control/actions/workflows/coding-standards.yml)\n[![Testing Suite](https://github.com/alleyinteractive/wp-page-cache-control/actions/workflows/unit-test.yml/badge.svg)](https://github.com/alleyinteractive/wp-page-cache-control/actions/workflows/unit-test.yml)\n\nControl and modify the page cache for multiple hosting providers.\n\n## Installation\n\nYou can install the package via Composer:\n\n```bash\ncomposer require alleyinteractive/wp-page-cache-control\n```\n\nThe plugin supports the following hosting providers and their respective page\ncaching systems:\n\n- [Pantheon](https://pantheon.io/) via [their `Pantheon Advanced Cache`\n  plugin](https://github.com/pantheon-systems/pantheon-advanced-page-cache):\n  (`Alley\\WP\\WP_Page_Cache_Control\\Providers\\Pantheon_Provider`)\n- [WordPress VIP](https://vip.wordpress.com/) via [their `mu-plugins` repository](https://github.com/automattic/vip-go-mu-plugins/): (`Alley\\WP\\WP_Page_Cache_Control\\Providers\\VIP_Provider`)\n\nThe plugin will attempt to detect the caching system in use and will load the\nappropriate provider class. It can also be controlled by the\n`wp_page_cache_control_provider` hook which should return a provider class\nstring.\n\nThe main goal of the plugin is to solve common page cache control needs across\nmultiple hosting providers. It is not meant to be a complete solution for all\npage cache control needs. If you have a need that is not met by the plugin,\nplease open an issue or pull request.\n\n## Usage\n\nThe plugin supports back-end page cache control including TTL, bypassing the\npage cache, user segmentation, and purging from the page cache. It also\nsupports front-end segmentation.\n\n## Usage: Back-end\n\nActivate the plugin in WordPress and use the following methods as needed:\n\n### Controlling the Time-to-live (TTL) of the Current Request\n\n```php\nwp_page_cache_control()-\u003ettl( 3600 );\n```\n\n### Disabling the Page Cache for the Current Request\n\n```php\nwp_page_cache_control()-\u003edisable_cache();\n```\n### Disabling the Page Cache for the Current User\n\nDisabling the page cache for the current user will cause the user to bypass the\npage cache for the current and subsequent requests. This is useful for testing\nor for logged-in users.\n\n```php\nwp_page_cache_control()-\u003edisable_cache_for_user();\n\n// enabling it again via:\nwp_page_cache_control()-\u003eenable_cache_for_user();\n```\n\n### Segmenting the Page Cache\n\nSee [Page Cache Segmentation](#page-cache-segmentation) for more information.\n\n```php\nwp_page_cache_control()-\u003eregister_group( 'special-user-group' );\n\n// Add the current user to the group (only needs to be done once).\nwp_page_cache_control()-\u003eset_group_for_user( 'special-user-group', 'segment' );\n```\n\n### Purging a Specific URL\n\n```php\nwp_page_cache_control()-\u003epurge( home_url( '/example/' );\n```\n\n### Purging for a Post or Term\n\n```php\nwp_page_cache_control()-\u003epurge_post( $post_id );\n\nwp_page_cache_control()-\u003epurge_term( $term_id );\n```\n\n### Purging the Entire Page Cache\n\n**Warning:** This will purge the entire page cache. This is a dangerous operation and should be used with caution.\n\n```php\nwp_page_cache_control()-\u003eflush();\n```\n\n## Page Cache Segmentation\n\nPage Cache Segmentation is used when you want to vary or differ the page\nresponse to different users. For example, you may want to show a different\nversion of a page to logged-in users than to logged-out users. Or you may want\nto hide ads for users from a specific country. Segmenting the page cache allows\nyou to do this in a performant way.\n\n### Registering a Group\n\nTo register a group, use the `register_group()` method:\n\n```php\nwp_page_cache_control()-\u003eregister_group( 'special-user-group' );\n```\n\nGroup names must be unique and must contain alphanumeric characters, dashes, and\nunderscores only.\n\n### Adding a User to a Group\n\nTo add a user to a group, use the `set_group_for_user()` method:\n\n```php\nwp_page_cache_control()-\u003eset_group_for_user( 'special-user-group', 'segment' );\n```\n\nThe second parameter allows you to specify a segment within a group. For\nexample, the group could be \"logged-in\" and the segment could be \"digital\nsubscriber\". You could also have a different user in the \"logged-in\" group with\nthe segment \"print subscriber\" to show a different version of the page to print\nsubscribers.\n\n**Note:** A user cannot be removed from a group once added at this time. If you need\nto remove a user from a group, you can add them to a different segment of the\nsame group.\n\n### Checking if a User is in a Group or Segment\n\nTo check if a user is in a group or segment, use the `is_user_in_group()` method:\n\n```php\nwp_page_cache_control()-\u003eis_user_in_group( 'special-user-group' );\n\nwp_page_cache_control()-\u003eis_user_in_group( 'special-user-group', 'segment' );\n```\n\n### Testing Headers\n\nThe plugin supports faking the sending of headers sent through the plugin for testing purposes. To enable this, call the following code:\n\n```php\nuse Alley\\WP\\WP_Page_Cache_Control\\Header;\n\nHeader::fake();\n```\n\nOnce enabled, you can use the following methods to test headers being sent with\nthe `Alley\\WP\\WP_Page_Cache_Control\\Concerns\\Tests_Headers` trait:\n\n```php\nnamespace Alley\\WP\\My_Plugin\\Tests;\n\nuse Alley\\WP\\WP_Page_Cache_Control\\Concerns\\Tests_Headers;\nuse Alley\\WP\\WP_Page_Cache_Control\\Header;\nuse Mantle\\Testkit\\Test_Case;\n\nclass Example_Test extends Test_Case {\n\tuse Tests_Headers;\n\n\tprotected function setUp(): void {\n\t\tparent::setUp();\n\n\t\tHeader::fake();\n\t}\n\n\tpublic function test_example() {\n\t\t// Perform some action that should send a header.\n\n\t\tstatic::assertHeaderSent( 'X-My-Header', 'optional value' );\n\t\tstatic::assertHeaderNotSent( 'X-My-Other-Header', 'optional value' );\n\n\t\t// static::assertAnyHeadersSent() and static::assertNoHeadersSent()\n\t\t// are also available to assert that any headers were sent or not sent.\n\t}\n}\n```\n\n## Usage: Front-end\n\nThe package has a front-end integration to allow for segmenting the page cache\nin-browser. This is enabled by default but can be disabled by using the\n`wp_page_cache_control_enqueue_script` filter.\n\nCache segmentation groups must be registered on the back end before they can be\nused on the front end. See [Registering a Group](#registering-a-group) for more\ninformation.\n\n```js\nwpPageCacheControl.setGroupForUser('logged-in-group', 'segment-name');\n\n// To remove a user from a group, you have to set them to a different segment.\nwpPageCacheControl.setGroupForUser('logged-in-group', 'different-name');\n\n// To check if a user is in a group or segment, use the following:\nwpPageCacheControl.isUserInGroup('logged-in-group');\nwpPageCacheControl.isUserInGroupSegment('logged-in-group', 'segment-name');\n\n// You can read the groups and segments from the page cache control object:\\\n//\n//   wpPageCacheControl.groups;\n```\n\nTypes are available for TypeScript users:\n\n\tnpm install --save-dev @alleyinteractive/wp-page-cache-control\n\n## Testing\n\nRun `npm run test` to run Jest tests against JavaScript files. Run\n`npm run test:watch` to keep the test runner open and watching for changes.\n\nRun `npm run lint` to run ESLint against all JavaScript files. Linting will also\nhappen when running development or production builds.\n\nRun `composer test` to run tests against PHPUnit and the PHP code in the plugin.\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Credits\n\nThis project is actively maintained by [Alley\nInteractive](https://github.com/alleyinteractive). Like what you see? [Come work\nwith us](https://alley.com/careers/).\n\n- [Sean Fisher](https://github.com/srtfisher)\n- [All Contributors](../../contributors)\n\n## License\n\nThe GNU General Public License (GPL) license. Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-page-cache-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falleyinteractive%2Fwp-page-cache-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-page-cache-control/lists"}