class-capabilities.php
5 months ago
class-plugin-settings.php
5 months ago
class-settings.php
5 months ago
class-capabilities.php
129 lines
| 1 | <?php |
| 2 | |
| 3 | namespace SearchRegex\Plugin; |
| 4 | |
| 5 | /** |
| 6 | * Search Regex capabilities |
| 7 | * |
| 8 | * Hook `searchregex_role` and return a capability for access to the plugin menu. For example `edit_pages` will allow an editor |
| 9 | * Hook `searchregex_capability` and return a different capability for each check that needs specific permissions. |
| 10 | * |
| 11 | * For example, if you want to give editors access to create redirects, but nothing else: |
| 12 | * |
| 13 | * ```php |
| 14 | * add_filter( 'searchregex_capability_check', function( $capability, $permission_name ) { |
| 15 | * if ( $permission_name === 'searchregex_cap_redirect_manage' || $permission_name === 'searchregex_cap_redirect_add' ) { |
| 16 | * return $capability; |
| 17 | * } |
| 18 | * |
| 19 | * return 'manage_options'; |
| 20 | * } ); |
| 21 | * ``` |
| 22 | * |
| 23 | * Always default to restrictive and then grant permissions. Don't default to permissive and remove permissions. This way if a new |
| 24 | * capability is added your users won't automatically be granted access. |
| 25 | * |
| 26 | * Capabilities can be filtered with: |
| 27 | * - `searchregex_capability_check( $capability, $permission_name )` - override `$capability` dependant on `$permission_name` |
| 28 | * - `searchregex_capability_pages( $pages )` - filters the list of available pages |
| 29 | * - `searchregex_role( $cap )` - return the role/capability used for overall access to the plugin |
| 30 | * |
| 31 | * Note some capabilities may give access to data from others. For example, when viewing a page of redirects via `searchregex_cap_redirect_manage` |
| 32 | * the client will need to access group data. |
| 33 | * |
| 34 | * @phpstan-type CapabilityName 'searchregex_cap_manage'|'searchregex_cap_options'|'searchregex_cap_support'|'searchregex_cap_preset' |
| 35 | * @phpstan-type PageName 'search'|'options'|'support'|'presets' |
| 36 | */ |
| 37 | class Capabilities { |
| 38 | const FILTER_ALL = 'searchregex_capability_all'; |
| 39 | const FILTER_PAGES = 'searchregex_capability_pages'; |
| 40 | const FILTER_CAPABILITY = 'searchregex_capability_check'; |
| 41 | |
| 42 | // The default WordPress capability used for all checks |
| 43 | const CAP_DEFAULT = 'manage_options'; |
| 44 | |
| 45 | // The main capability used to provide access to the plugin |
| 46 | const CAP_PLUGIN = 'searchregex_role'; |
| 47 | |
| 48 | // These capabilities are combined with `searchregex_cap_` to form `searchregex_cap_redirect_add` etc |
| 49 | const CAP_SEARCHREGEX_SEARCH = 'searchregex_cap_manage'; |
| 50 | const CAP_SEARCHREGEX_OPTIONS = 'searchregex_cap_options'; |
| 51 | const CAP_SEARCHREGEX_SUPPORT = 'searchregex_cap_support'; |
| 52 | const CAP_SEARCHREGEX_PRESETS = 'searchregex_cap_preset'; |
| 53 | |
| 54 | /** |
| 55 | * Determine if the current user has access to a named capability. |
| 56 | * |
| 57 | * @param CapabilityName $cap_name The capability to check for. See Capabilities for constants. |
| 58 | * @return bool |
| 59 | */ |
| 60 | public static function has_access( $cap_name ) { |
| 61 | // Get the capability using the default plugin access as the base. Old sites overriding `searchregex_role` will get access to everything |
| 62 | $cap_to_check = apply_filters( self::FILTER_CAPABILITY, self::get_plugin_access(), $cap_name ); |
| 63 | |
| 64 | // Check the capability |
| 65 | return current_user_can( $cap_to_check ); |
| 66 | } |
| 67 | |
| 68 | /** |
| 69 | * Return the role/capability used for displaying the plugin menu. This is also the base capability for all other checks. |
| 70 | * |
| 71 | * @return string Role/capability |
| 72 | */ |
| 73 | public static function get_plugin_access() { |
| 74 | return apply_filters( self::CAP_PLUGIN, self::CAP_DEFAULT ); |
| 75 | } |
| 76 | |
| 77 | /** |
| 78 | * Return all the pages the user has access to. |
| 79 | * |
| 80 | * @return list<PageName> Array of pages |
| 81 | */ |
| 82 | public static function get_available_pages() { |
| 83 | $pages = [ |
| 84 | self::CAP_SEARCHREGEX_SEARCH => 'search', |
| 85 | self::CAP_SEARCHREGEX_OPTIONS => 'options', |
| 86 | self::CAP_SEARCHREGEX_SUPPORT => 'support', |
| 87 | self::CAP_SEARCHREGEX_PRESETS => 'presets', |
| 88 | ]; |
| 89 | |
| 90 | $available = []; |
| 91 | foreach ( $pages as $key => $page ) { |
| 92 | if ( self::has_access( $key ) ) { |
| 93 | $available[] = $page; |
| 94 | } |
| 95 | } |
| 96 | |
| 97 | return array_values( apply_filters( self::FILTER_PAGES, $available ) ); |
| 98 | } |
| 99 | |
| 100 | /** |
| 101 | * Return all the capabilities the current user has |
| 102 | * |
| 103 | * @return list<CapabilityName> Array of capabilities |
| 104 | */ |
| 105 | public static function get_all_capabilities() { |
| 106 | $caps = self::get_every_capability(); |
| 107 | |
| 108 | $caps = array_filter( |
| 109 | $caps, fn( $cap ) => self::has_access( $cap ) |
| 110 | ); |
| 111 | |
| 112 | return array_values( apply_filters( self::FILTER_ALL, $caps ) ); |
| 113 | } |
| 114 | |
| 115 | /** |
| 116 | * Unfiltered list of all the supported capabilities, without influence from the current user |
| 117 | * |
| 118 | * @return list<CapabilityName> Array of capabilities |
| 119 | */ |
| 120 | public static function get_every_capability() { |
| 121 | return [ |
| 122 | self::CAP_SEARCHREGEX_SEARCH, |
| 123 | self::CAP_SEARCHREGEX_OPTIONS, |
| 124 | self::CAP_SEARCHREGEX_SUPPORT, |
| 125 | self::CAP_SEARCHREGEX_PRESETS, |
| 126 | ]; |
| 127 | } |
| 128 | } |
| 129 |