Visibility
Handles access control for the Document Library.
Tags
Table of Contents
- CATEGORY_COOKIE_PREFIX = 'dlp_category_unlocks_'
- DOCUMENT_COOKIE_PREFIX = 'dlp_document_unlocks_'
- GLOBAL_COOKIE_PREFIX = 'dlp_global_unlocks_'
- clear_protection_cache() : void
- Clear the protection check cache.
- get_all_unlocks() : array<string|int, mixed>
- Get all unlocks across all cookie types
- get_category_passwords() : array<string|int, mixed>
- Get the list of passwords for the specified term.
- get_category_visibilities() : mixed
- Get's all category visibilities.
- get_category_visibility() : bool|Category_Visibility
- Retrieve the Category_Visibility instance for the specified term.
- get_category_visibility_cache() : array<string|int, mixed>
- Retrieves the term visibility cache.
- get_category_visibility_level() : string
- Get the visibility for the specified term.
- get_document_categories() : array<string|int, mixed>
- Retrieve an array of all document category IDs.
- get_document_visibilities() : array<string|int, Document_Visibility>
- Get's all document visibilities.
- get_document_visibility() : Document_Visibility
- Retrieve the Document_Visibility instance for the specified document.
- get_document_visibility_level() : string
- Get the visibility for the specified document.
- get_global_visibility() : Global_Visibility|null
- Returns the Global_Visibility instance
- get_hidden_check_document_visibilities() : array<string|int, Document_Visibility>
- Get document visibilities for checking exclusions in document loops.
- get_protectable_taxonomies() : array<string|int, mixed>
- Retrieve a list of all protectable taxonomies from the list of currently registered taxonomies.
- get_the_category_visibility() : array<string|int, mixed>
- Retrive a list of Category_Visibility objects for the specified post.
- get_unlock_check_document_visibilities() : array<string|int, Document_Visibility>
- Get document visibilities for checking unlocks in document loops.
- get_unlocked_document() : bool|array<string|int, mixed>
- Returns the currently unlocked document (if any) as an array in the following format:
- get_unlocked_global() : array<string|int, mixed>|false
- Get global unlock status
- get_unlocked_term() : bool|array<string|int, mixed>
- Returns the currently unlocked category or term (if any) as an array in the following format:
- has_any_protection() : bool
- Check if ANY protection is active across the entire site.
- has_valid_protection() : bool
- Determine if the protection data is valid
- is_category_protected() : false|array<string|int, mixed>
- Determines whether the supplied category or categories are protected.
- is_document_protected() : array<string|int, mixed>|false
- Determine if the supplied document is protected anywhere on the hierarchy.
- is_document_unlocked_by_cookie() : bool
- Check if specific document is unlocked
- is_global_protected() : array<string|int, mixed>|false
- Determines whether the global setting is protected.
- is_global_unlocked() : bool
- Check if global unlock is active
- is_protectable_category() : bool
- Are we viewing a category/taxonomy archive page (for any post type) which can be protected by the plugin?
- is_term_unlocked() : bool
- Check if specific term is unlocked
- protected_category_has_unlocked_documents() : bool|null
- Check if a protected category has any unlocked documents.
- protected_category_unlocked_documents_count() : int|null
- Get the number of unlocked documents in a protected category.
- protected_site_has_unlocked_documents() : bool|null
- Check if a protected site has any unlocked content.
- tax_query_has_protected_terms() : array<string|int, mixed>|null
- Check query vars for excluded category
- tax_query_remove_protected_terms() : array<string|int, mixed>
- Remove protected terms from tax query
- to_category_visibilities() : array<string|int, mixed>
- Converts an array of WP_Term objects to an array of Category_Visibility objects.
- update_category_visibility_cache() : mixed
- Updates the term visibility cache.
- build_category_protection_for_level() : mixed
- Build the protection array for a given category and level.
- check_any_protection() : bool
- Perform the actual check for any protection.
- get_document_level_visibility_ids() : array<string|int, int>
- Retrieve an array of all document IDs with document level protection not inherited.
- get_document_visibility_cache() : array<string|int, mixed>
- Get the document visiblity cache.
- get_excluded_document_owner_document_ids() : array<string|int, int>
- Retrieve an array of all document IDs for checking exclusion in document loops.
- get_unlocked_document_owner_document_ids() : array<string|int, int>
- Retrieve an array of all document IDs for checking unlocks in document loops.
- parse_cookie_safely() : object|false
- Safe JSON parsing with error handling
- update_document_visibility_cache() : mixed
- Updates the document visiblity cache.
Constants
CATEGORY_COOKIE_PREFIX
public
mixed
CATEGORY_COOKIE_PREFIX
= 'dlp_category_unlocks_'
Tags
DOCUMENT_COOKIE_PREFIX
public
mixed
DOCUMENT_COOKIE_PREFIX
= 'dlp_document_unlocks_'
Tags
GLOBAL_COOKIE_PREFIX
public
mixed
GLOBAL_COOKIE_PREFIX
= 'dlp_global_unlocks_'
Tags
Methods
clear_protection_cache()
Clear the protection check cache.
public
static clear_protection_cache() : void
Tags
Return values
void —get_all_unlocks()
Get all unlocks across all cookie types
public
static get_all_unlocks() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —get_category_passwords()
Get the list of passwords for the specified term.
public
static get_category_passwords(int $term_id[, bool $single = false ]) : array<string|int, mixed>
Parameters
- $term_id : int
-
The term ID for the term.
- $single : bool = false
-
Whether to return a single value.
Tags
Return values
array<string|int, mixed> —The passwords array. Will be an empty array if there are no passwords.
get_category_visibilities()
Get's all category visibilities.
public
static get_category_visibilities() : mixed
Tags
Return values
mixed —get_category_visibility()
Retrieve the Category_Visibility instance for the specified term.
public
static get_category_visibility(string|int $term_id) : bool|Category_Visibility
Parameters
- $term_id : string|int
Tags
Return values
bool|Category_Visibility —get_category_visibility_cache()
Retrieves the term visibility cache.
public
static get_category_visibility_cache() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —The term visibility cache
get_category_visibility_level()
Get the visibility for the specified term.
public
static get_category_visibility_level(int $term_id) : string
Parameters
- $term_id : int
-
The term ID for the term.
Tags
Return values
string —The visibility - one of 'public' or 'protected'.
get_document_categories()
Retrieve an array of all document category IDs.
public
static get_document_categories() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —get_document_visibilities()
Get's all document visibilities.
public
static get_document_visibilities([array<string|int, mixed>|null $document_ids = null ]) : array<string|int, Document_Visibility>
Parameters
- $document_ids : array<string|int, mixed>|null = null
-
The document IDs to get visibilities for.
Tags
Return values
array<string|int, Document_Visibility> —get_document_visibility()
Retrieve the Document_Visibility instance for the specified document.
public
static get_document_visibility(Document|int $document) : Document_Visibility
Parameters
- $document : Document|int
Tags
Return values
Document_Visibility —get_document_visibility_level()
Get the visibility for the specified document.
public
static get_document_visibility_level(int $document_id) : string
Parameters
- $document_id : int
-
The document ID for the document.
Tags
Return values
string —The visibility - one of 'public' or 'protected'.
get_global_visibility()
Returns the Global_Visibility instance
public
static get_global_visibility() : Global_Visibility|null
Tags
Return values
Global_Visibility|null —get_hidden_check_document_visibilities()
Get document visibilities for checking exclusions in document loops.
public
static get_hidden_check_document_visibilities() : array<string|int, Document_Visibility>
This adds all relevant inheritable document owner documents to the document visibility cache so we can check for exclusions.
Tags
Return values
array<string|int, Document_Visibility> —get_protectable_taxonomies()
Retrieve a list of all protectable taxonomies from the list of currently registered taxonomies.
public
static get_protectable_taxonomies() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —A list of taxonomy names which can be protected by the plugin
get_the_category_visibility()
Retrive a list of Category_Visibility objects for the specified post.
public
static get_the_category_visibility([int|WP_Post $post = null ]) : array<string|int, mixed>
If no post is specified, the current post object is used.
Parameters
- $post : int|WP_Post = null
-
The post ID or post object
Tags
Return values
array<string|int, mixed> —An array of Category_Visibility objects
get_unlock_check_document_visibilities()
Get document visibilities for checking unlocks in document loops.
public
static get_unlock_check_document_visibilities() : array<string|int, Document_Visibility>
This adds all relevant inheritable document owner documents to the document visibility cache so we can check for unlocks.
Tags
Return values
array<string|int, Document_Visibility> —get_unlocked_document()
Returns the currently unlocked document (if any) as an array in the following format:
public
static get_unlocked_document() : bool|array<string|int, mixed>
[ 'document_id' => 12, 'password' => 'password' ]
Tags
Return values
bool|array<string|int, mixed> —The document array or false if no document is currently unlocked.
get_unlocked_global()
Get global unlock status
public
static get_unlocked_global() : array<string|int, mixed>|false
Tags
Return values
array<string|int, mixed>|false —get_unlocked_term()
Returns the currently unlocked category or term (if any) as an array in the following format:
public
static get_unlocked_term() : bool|array<string|int, mixed>
[ 'term_id' => 12, 'taxonomy' => 'category', 'password' => 'password' ]
Tags
Return values
bool|array<string|int, mixed> —The taxonomy array or false if no terms are currently unlocked.
has_any_protection()
Check if ANY protection is active across the entire site.
public
static has_any_protection() : bool
This checks:
- Global protection
- Any category with protection
- Any document with protection
Tags
Return values
bool —True if any protection exists, false if everything is public/inherited
has_valid_protection()
Determine if the protection data is valid
public
static has_valid_protection(array<string|int, mixed> $protection_data) : bool
Parameters
- $protection_data : array<string|int, mixed>
-
The protection data
Tags
Return values
bool —is_category_protected()
Determines whether the supplied category or categories are protected.
public
static is_category_protected(int|array<string|int, mixed> $category_ids[, Document_Visibility $document_visibility = null ]) : false|array<string|int, mixed>
The function will always return false (i.e. unlocked) if at least one category is unlocked, regardless of the other categories supplied, even if the other categories are protected.
Parameters
- $category_ids : int|array<string|int, mixed>
-
The category IDs to check.
- $document_visibility : Document_Visibility = null
-
The document visibility object to check if relevant (used for document owner checks)
Tags
Return values
false|array<string|int, mixed> —is_document_protected()
Determine if the supplied document is protected anywhere on the hierarchy.
public
static is_document_protected(int $document_id) : array<string|int, mixed>|false
Parameters
- $document_id : int
Tags
Return values
array<string|int, mixed>|false —is_document_unlocked_by_cookie()
Check if specific document is unlocked
public
static is_document_unlocked_by_cookie(int $document_id, array<string|int, mixed> $passwords) : bool
Parameters
- $document_id : int
- $passwords : array<string|int, mixed>
Tags
Return values
bool —is_global_protected()
Determines whether the global setting is protected.
public
static is_global_protected([Document_Visibility $document_visibility = null ]) : array<string|int, mixed>|false
Don't use this to determine if the entire site is protected.
Parameters
- $document_visibility : Document_Visibility = null
-
The document visibility object to check if relevant (used for document owner checks)
Tags
Return values
array<string|int, mixed>|false —'password', 'user', 'role', or 'document_owner'
is_global_unlocked()
Check if global unlock is active
public
static is_global_unlocked(array<string|int, mixed> $passwords) : bool
Parameters
- $passwords : array<string|int, mixed>
Tags
Return values
bool —is_protectable_category()
Are we viewing a category/taxonomy archive page (for any post type) which can be protected by the plugin?
public
static is_protectable_category() : bool
Tags
Return values
bool —is_term_unlocked()
Check if specific term is unlocked
public
static is_term_unlocked(int $term_id, string $taxonomy, array<string|int, mixed> $passwords) : bool
Parameters
- $term_id : int
- $taxonomy : string
- $passwords : array<string|int, mixed>
Tags
Return values
bool —protected_category_has_unlocked_documents()
Check if a protected category has any unlocked documents.
public
static protected_category_has_unlocked_documents(int $term_id) : bool|null
Only documents with explicit public/unlocked visibility can override category protection.
Parameters
- $term_id : int
-
Category term ID
Tags
Return values
bool|null —True if has unlocked documents, false if all locked, null if not protected
protected_category_unlocked_documents_count()
Get the number of unlocked documents in a protected category.
public
static protected_category_unlocked_documents_count(int $term_id) : int|null
Parameters
- $term_id : int
Tags
Return values
int|null —protected_site_has_unlocked_documents()
Check if a protected site has any unlocked content.
public
static protected_site_has_unlocked_documents() : bool|null
Only categories/documents with explicit public/unlocked visibility can override global protection. Empty categories (categories without any published documents) are ignored.
Tags
Return values
bool|null —True if has unlocked content, false if fully locked, null if not protected
tax_query_has_protected_terms()
Check query vars for excluded category
public
static tax_query_has_protected_terms(array<string|int, mixed> $tax_query) : array<string|int, mixed>|null
Parameters
- $tax_query : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>|null —tax_query_remove_protected_terms()
Remove protected terms from tax query
public
static tax_query_remove_protected_terms(mixed $tax_query) : array<string|int, mixed>
Parameters
- $tax_query : mixed
Tags
Return values
array<string|int, mixed> —$tax_query
to_category_visibilities()
Converts an array of WP_Term objects to an array of Category_Visibility objects.
public
static to_category_visibilities(array<string|int, mixed> $terms) : array<string|int, mixed>
Parameters
- $terms : array<string|int, mixed>
-
An array of WP_Term objects
Tags
Return values
array<string|int, mixed> —An array of Category_Visibility objects
update_category_visibility_cache()
Updates the term visibility cache.
public
static update_category_visibility_cache(array<string|int, mixed> $term_visibilities) : mixed
Parameters
- $term_visibilities : array<string|int, mixed>
-
The term visibilities to cache
Tags
Return values
mixed —build_category_protection_for_level()
Build the protection array for a given category and level.
private
static build_category_protection_for_level(array<string|int, mixed> &$protection, Category_Visibility $category, int $level[, array<string|int, mixed> &$protection_source = [] ]) : mixed
Parameters
- $protection : array<string|int, mixed>
-
The protection array to build
- $category : Category_Visibility
-
The category to build protection for
- $level : int
-
The level of the category
- $protection_source : array<string|int, mixed> = []
-
Array to track which category provides protection at each level
Tags
Return values
mixed —check_any_protection()
Perform the actual check for any protection.
private
static check_any_protection() : bool
Tags
Return values
bool —get_document_level_visibility_ids()
Retrieve an array of all document IDs with document level protection not inherited.
private
static get_document_level_visibility_ids() : array<string|int, int>
Tags
Return values
array<string|int, int> —get_document_visibility_cache()
Get the document visiblity cache.
private
static get_document_visibility_cache() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed> —get_excluded_document_owner_document_ids()
Retrieve an array of all document IDs for checking exclusion in document loops.
private
static get_excluded_document_owner_document_ids() : array<string|int, int>
Since document owner can only be verified at the document level via post_author, we need to check for documents which inherit document owner protection from the category or global level.
Tags
Return values
array<string|int, int> —get_unlocked_document_owner_document_ids()
Retrieve an array of all document IDs for checking unlocks in document loops.
private
static get_unlocked_document_owner_document_ids() : array<string|int, int>
Since document owner can only be verified at the document level via post_author, we need to check for documents which inherit document owner protection from the category or global level.
Tags
Return values
array<string|int, int> —parse_cookie_safely()
Safe JSON parsing with error handling
private
static parse_cookie_safely(string $cookie_value) : object|false
Parameters
- $cookie_value : string
Tags
Return values
object|false —update_document_visibility_cache()
Updates the document visiblity cache.
private
static update_document_visibility_cache(array<string|int, Document_Visibility> $document_visibilities) : mixed
Parameters
- $document_visibilities : array<string|int, Document_Visibility>