| @@ -1,73 +1,106 @@ | ||
| 1 | 1 | <?php |
| 2 | +/** | |
| 3 | + * The [tableKit] shortcode | |
| 4 | + * | |
| 5 | + * @package TableKit | |
| 6 | + */ | |
| 2 | 7 | |
| 3 | 8 | namespace TableBuilder\Shortcode; |
| 4 | 9 | |
| 10 | +use TableBuilder\Hooks\AssetGenerator; | |
| 5 | 11 | use TableBuilder\Shortcode\ShortcodeUtils; |
| 6 | 12 | use TableBuilder\Render\BlockRenderer; |
| 7 | 13 | use TableBuilder\Traits\Singleton; |
| 8 | 14 | |
| 9 | -defined('ABSPATH') || exit; | |
| 15 | +defined( 'ABSPATH' ) || exit; | |
| 10 | 16 | |
| 11 | -// Handles registration and rendering of the [tableKit] shortcode. | |
| 12 | -class Shortcode | |
| 13 | -{ | |
| 17 | +/** | |
| 18 | + * Handles registration and rendering of the [tableKit] shortcode. | |
| 19 | + */ | |
| 20 | +class Shortcode { | |
| 14 | 21 | |
| 22 | + | |
| 15 | 23 | use Singleton; |
| 16 | 24 | |
| 17 | - // Whether frontend assets have been enqueued at least once | |
| 25 | + /** | |
| 26 | + * Whether frontend assets have been enqueued at least once. | |
| 27 | + * | |
| 28 | + * @var bool | |
| 29 | + */ | |
| 18 | 30 | private static bool $assets_enqueued = false; |
| 19 | 31 | |
| 20 | 32 | // Default shortcode attribute values. |
| 21 | - private const DEFAULT_ATTS = [ | |
| 33 | + private const DEFAULT_ATTS = array( | |
| 22 | 34 | 'id' => '', |
| 23 | 35 | 'post_id' => 0, |
| 24 | 36 | 'block_id' => '', |
| 25 | 37 | 'class' => '', |
| 26 | 38 | 'attrs_json' => '{}', |
| 27 | - ]; | |
| 39 | + ); | |
| 28 | 40 | |
| 29 | - // Default block attribute values | |
| 30 | - private const DEFAULT_BLOCK_ATTRS = [ | |
| 31 | - 'headers' => [], | |
| 32 | - 'footers' => [], | |
| 41 | + // Default block attribute values. | |
| 42 | + private const DEFAULT_BLOCK_ATTRS = array( | |
| 43 | + 'headers' => array(), | |
| 44 | + 'footers' => array(), | |
| 33 | 45 | 'hasHeader' => true, |
| 34 | 46 | 'hasFooter' => false, |
| 35 | 47 | 'columnCount' => 0, |
| 36 | - ]; | |
| 48 | + ); | |
| 37 | 49 | |
| 38 | - // Constructor — hooks into WordPress init. | |
| 39 | - protected function __construct() | |
| 40 | - { | |
| 41 | - add_action('init', [$this, 'register_shortcodes']); | |
| 50 | + /** | |
| 51 | + * Hooks shortcode registration into WordPress init. | |
| 52 | + */ | |
| 53 | + protected function __construct() { | |
| 54 | + add_action( 'init', array( $this, 'register_shortcodes' ) ); | |
| 42 | 55 | } |
| 43 | 56 | |
| 44 | - // Registers all shortcodes for this plugin. | |
| 45 | - public function register_shortcodes(): void | |
| 46 | - { | |
| 47 | - add_shortcode('tableKit', [$this, 'render']); | |
| 57 | + /** | |
| 58 | + * Registers all shortcodes for this plugin. | |
| 59 | + * | |
| 60 | + * @return void | |
| 61 | + */ | |
| 62 | + public function register_shortcodes(): void { | |
| 63 | + add_shortcode( 'tableKit', array( $this, 'render' ) ); | |
| 48 | 64 | } |
| 49 | 65 | |
| 50 | - // Shortcode Rendering | |
| 51 | - public function render($raw_atts, string $content = ''): string | |
| 52 | - { | |
| 53 | - $atts = $this->sanitize_atts(shortcode_atts(self::DEFAULT_ATTS, (array) $raw_atts, 'tableKit')); | |
| 54 | - $ids = $this->parse_ids($atts); | |
| 66 | + /** | |
| 67 | + * [tableKit] shortcode callback. Renders either every table block found in | |
| 68 | + * the resolved source post (when no specific block/id is given) or a single | |
| 69 | + * resolved block. | |
| 70 | + * | |
| 71 | + * @param array|string $raw_atts Raw shortcode attributes as passed by WordPress. | |
| 72 | + * @param string $content Optional. Shortcode enclosed content (currently unused | |
| 73 | + * beyond being passed through to the block renderer). | |
| 74 | + * @return string Rendered HTML. | |
| 75 | + */ | |
| 76 | + public function render( $raw_atts, string $content = '' ): string { | |
| 77 | + $atts = $this->sanitize_atts( shortcode_atts( self::DEFAULT_ATTS, (array) $raw_atts, 'tableKit' ) ); | |
| 78 | + $ids = $this->parse_ids( $atts ); | |
| 55 | 79 | |
| 80 | + // The shortcode prints its own table CSS, so the generic late-CSS | |
| 81 | + // printer (AssetGenerator) must not print it a second time. | |
| 82 | + $asset_generator = AssetGenerator::instance(); | |
| 83 | + $asset_generator->suspend_late_css(); | |
| 84 | + | |
| 56 | 85 | ob_start(); |
| 57 | 86 | |
| 58 | - if ( empty( $ids['block_id'] ) && empty( $ids['raw_id'] ) ) { | |
| 59 | - echo $this->render_all_blocks( $ids, $atts, $content ); | |
| 60 | - return (string) ob_get_clean(); | |
| 61 | - } | |
| 87 | + try { | |
| 88 | + if ( empty( $ids['block_id'] ) && empty( $ids['raw_id'] ) ) { | |
| 89 | + echo $this->render_all_blocks( $ids, $atts, $content ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- built from the_content filter output and esc_*()-escaped pieces, see render_all_blocks(). | |
| 90 | + return (string) ob_get_clean(); | |
| 91 | + } | |
| 62 | 92 | |
| 63 | - $block = $this->locate_block($ids['post_id'], $ids['block_id'], $ids['raw_id']); | |
| 93 | + $block = $this->locate_block( $ids['post_id'], $ids['block_id'], $ids['raw_id'] ); | |
| 64 | 94 | |
| 65 | - if (! empty($block)) { | |
| 66 | - echo $this->render_single_block($block, $atts, $ids, $content); | |
| 95 | + if ( ! empty( $block ) ) { | |
| 96 | + echo $this->render_single_block( $block, $atts, $ids, $content ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- delegates to BlockRenderer::render_table_builder(), which escapes/kses's its own output. | |
| 97 | + } | |
| 98 | + | |
| 99 | + return (string) ob_get_clean(); | |
| 100 | + } finally { | |
| 101 | + $asset_generator->resume_late_css(); | |
| 67 | 102 | } |
| 68 | - | |
| 69 | - return (string) ob_get_clean(); | |
| 70 | 103 | } |
| 71 | 104 | |
| 72 | 105 | // ------------------------------------------------------------------------- |
| 73 | 106 | // Multi-block rendering (no block_id given) |
| @@ -73,20 +106,24 @@ | ||
| 73 | 106 | // Multi-block rendering (no block_id given) |
| 74 | 107 | // ------------------------------------------------------------------------- |
| 75 | 108 | |
| 76 | 109 | /** |
| 77 | - * Render the source post/page content for post_id-only shortcodes. | |
| 110 | + * Renders the source post/page content for post_id-only shortcodes. | |
| 78 | 111 | * For standalone tablekit_table CPT entries, this preserves the original |
| 79 | 112 | * behavior of rendering the stored block content. |
| 113 | + * | |
| 114 | + * @param array $ids Resolved ID set from parse_ids() (post_id/block_id/raw_id). | |
| 115 | + * @param array $atts Sanitized shortcode attributes. | |
| 116 | + * @param string $content Shortcode enclosed content (unused here). | |
| 117 | + * @return string Rendered HTML, or an empty string if the post can't be found/viewed. | |
| 80 | 118 | */ |
| 81 | - private function render_all_blocks( array $ids, array $atts, string $content ): string | |
| 82 | - { | |
| 119 | + private function render_all_blocks( array $ids, array $atts, string $content ): string { | |
| 83 | 120 | if ( empty( $ids['post_id'] ) ) { |
| 84 | 121 | return ''; |
| 85 | 122 | } |
| 86 | 123 | |
| 87 | - $post_id = (int) $ids['post_id']; | |
| 88 | - static $cleared = []; | |
| 124 | + $post_id = (int) $ids['post_id']; | |
| 125 | + static $cleared = array(); | |
| 89 | 126 | if ( ShortcodeUtils::is_elementor_editor() && ! isset( $cleared[ $post_id ] ) ) { |
| 90 | 127 | clean_post_cache( $post_id ); |
| 91 | 128 | $cleared[ $post_id ] = true; |
| 92 | 129 | } |
| @@ -92,9 +129,9 @@ | ||
| 92 | 129 | } |
| 93 | 130 | |
| 94 | 131 | $post = get_post( $post_id ); |
| 95 | 132 | |
| 96 | - if ( ! $post || empty( $post->post_content ) ) { | |
| 133 | + if ( ! $post || empty( $post->post_content ) || ! $this->can_view_post( $post ) ) { | |
| 97 | 134 | return ''; |
| 98 | 135 | } |
| 99 | 136 | $this->block_enqueue_assets(); |
| 100 | 137 | $css = $this->collect_blocks_css_from_content( $post->post_content ); |
| @@ -100,12 +137,14 @@ | ||
| 100 | 137 | $css = $this->collect_blocks_css_from_content( $post->post_content ); |
| 101 | 138 | $style = $css ? '<style id="tbk-shortcode-' . absint( $post->ID ) . '">' . $css . '</style>' : ''; |
| 102 | 139 | |
| 103 | 140 | $previous_post = $GLOBALS['post'] ?? null; |
| 141 | + // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited -- required so the "the_content" filter (and any callback that reads $GLOBALS['post']/get_post()) sees the correct post context; restored immediately below via wp_reset_postdata()/the original value. | |
| 104 | 142 | $GLOBALS['post'] = $post; // Ensure filters use the shortcode post context. |
| 105 | 143 | setup_postdata( $post ); |
| 106 | - $content = (string) apply_filters( 'the_content', $post->post_content ); | |
| 144 | + $content = (string) apply_filters( 'the_content', $post->post_content ); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- "the_content" is a WordPress core filter, not a hook defined by this plugin. | |
| 107 | 145 | wp_reset_postdata(); |
| 146 | + // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited -- restoring the previous global post value, not overriding it. | |
| 108 | 147 | $GLOBALS['post'] = $previous_post; |
| 109 | 148 | |
| 110 | 149 | return $style . $content . ShortcodeUtils::get_elementor_init_script(); |
| 111 | 150 | } |
| @@ -114,26 +153,44 @@ | ||
| 114 | 153 | // Single-block rendering |
| 115 | 154 | // ------------------------------------------------------------------------- |
| 116 | 155 | |
| 117 | 156 | /** |
| 118 | - * Render a single resolved block. Used both by the multi-block path and the | |
| 157 | + * Renders a single resolved block. Used both by the multi-block path and the | |
| 119 | 158 | * specific block_id path. |
| 159 | + * | |
| 160 | + * @param array $block Parsed block array to render. | |
| 161 | + * @param array $atts Sanitized shortcode attributes. | |
| 162 | + * @param array $ids Resolved ID set from parse_ids(). | |
| 163 | + * @param string $content Shortcode enclosed content, passed through to the "tablekit/render_block" filter. | |
| 164 | + * @return string Rendered HTML. | |
| 120 | 165 | */ |
| 121 | - private function render_single_block( array $block, array $atts, array $ids, string $content ): string | |
| 122 | - { | |
| 166 | + private function render_single_block( array $block, array $atts, array $ids, string $content ): string { | |
| 123 | 167 | // Pro hooks handle their own block types. |
| 124 | - $output = apply_filters('tablekit/render_block', null, $block, $atts, $ids, $content); | |
| 125 | - if (null !== $output) { | |
| 168 | + /** | |
| 169 | + * Filters the rendered output for a single [tableKit] block, letting the | |
| 170 | + * Pro add-on (or third parties) render block types this plugin doesn't know about. | |
| 171 | + * | |
| 172 | + * @since Unknown | |
| 173 | + * | |
| 174 | + * @param string|null $output Rendered HTML to short-circuit with, or null to use the default renderer. | |
| 175 | + * @param array $block Parsed block array to render. | |
| 176 | + * @param array $atts Sanitized shortcode attributes. | |
| 177 | + * @param array $ids Resolved ID set from parse_ids(). | |
| 178 | + * @param string $content Shortcode enclosed content. | |
| 179 | + */ | |
| 180 | + // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores -- slash-namespaced hook name is this plugin's established public API (used by the Pro add-on); renaming would be a breaking change. | |
| 181 | + $output = apply_filters( 'tablekit/render_block', null, $block, $atts, $ids, $content ); | |
| 182 | + if ( null !== $output ) { | |
| 126 | 183 | return (string) $output; |
| 127 | 184 | } |
| 128 | 185 | |
| 129 | - $attrs = $this->prepare_attrs($block, $atts, $ids['block_id']); | |
| 130 | - $rows = $block['innerBlocks'] ?? []; | |
| 131 | - $css = ShortcodeUtils::collect_block_css($block); | |
| 186 | + $attrs = $this->prepare_attrs( $block, $atts, $ids['block_id'] ); | |
| 187 | + $rows = $block['innerBlocks'] ?? array(); | |
| 188 | + $css = ShortcodeUtils::collect_block_css( $block ); | |
| 132 | 189 | $this->block_enqueue_assets(); |
| 133 | - $style = $css ? '<style id="tb-' . esc_attr($attrs['blockID']) . '">' . $css . '</style>' : ''; | |
| 190 | + $style = $css ? '<style id="tb-' . esc_attr( $attrs['blockID'] ) . '">' . $css . '</style>' : ''; | |
| 134 | 191 | |
| 135 | - return $style . BlockRenderer::render_table_builder($attrs, $rows, $content); | |
| 192 | + return $style . BlockRenderer::render_table_builder( $attrs, $rows, $content ); | |
| 136 | 193 | } |
| 137 | 194 | |
| 138 | 195 | // ------------------------------------------------------------------------- |
| 139 | 196 | // Attribute Preparation |
| @@ -138,57 +195,82 @@ | ||
| 138 | 195 | // ------------------------------------------------------------------------- |
| 139 | 196 | // Attribute Preparation |
| 140 | 197 | // ------------------------------------------------------------------------- |
| 141 | 198 | |
| 142 | - private function prepare_attrs(array $block, array $atts, string $block_id): array | |
| 143 | - { | |
| 144 | - $attrs = $block['attrs'] ?? []; | |
| 145 | - $rows = $block['innerBlocks'] ?? []; | |
| 199 | + /** | |
| 200 | + * Resolves a block's final attribute set: applies any `attrs_json` shortcode | |
| 201 | + * override, assigns a stable block ID, appends an extra CSS class, and fills | |
| 202 | + * in default header/footer/column values. | |
| 203 | + * | |
| 204 | + * @param array $block Parsed block array (its stored `attrs` are the base). | |
| 205 | + * @param array $atts Sanitized shortcode attributes. | |
| 206 | + * @param string $block_id Resolved block ID (may be empty; falls back to the block's own ID or a generated UUID). | |
| 207 | + * @return array Final attribute array. | |
| 208 | + */ | |
| 209 | + private function prepare_attrs( array $block, array $atts, string $block_id ): array { | |
| 210 | + $attrs = $block['attrs'] ?? array(); | |
| 211 | + $rows = $block['innerBlocks'] ?? array(); | |
| 146 | 212 | |
| 147 | 213 | // Override stored attributes with any inline JSON overrides. |
| 148 | - $json_overrides = ShortcodeUtils::decode_json($atts['attrs_json']); | |
| 149 | - if ($json_overrides) { | |
| 150 | - $attrs = array_replace_recursive($attrs, $json_overrides); | |
| 214 | + $json_overrides = ShortcodeUtils::decode_json( $atts['attrs_json'] ); | |
| 215 | + if ( $json_overrides ) { | |
| 216 | + $attrs = array_replace_recursive( $attrs, $json_overrides ); | |
| 151 | 217 | } |
| 152 | 218 | |
| 153 | 219 | // Ensure a stable unique block ID. |
| 154 | - $attrs['blockID'] = $block_id ?: (! empty($attrs['blockID']) ? $attrs['blockID'] : 'tb-' . wp_generate_uuid4()); | |
| 220 | + if ( $block_id ) { | |
| 221 | + $attrs['blockID'] = $block_id; | |
| 222 | + } elseif ( empty( $attrs['blockID'] ) ) { | |
| 223 | + $attrs['blockID'] = 'tb-' . wp_generate_uuid4(); | |
| 224 | + } | |
| 155 | 225 | |
| 156 | 226 | // Append any extra CSS class passed via shortcode. |
| 157 | - if (! empty($atts['class'])) { | |
| 158 | - $extra_class = sanitize_html_class($atts['class']); | |
| 159 | - $attrs['blockClass'] = trim(($attrs['blockClass'] ?? '') . ' ' . $extra_class); | |
| 227 | + if ( ! empty( $atts['class'] ) ) { | |
| 228 | + $extra_class = sanitize_html_class( $atts['class'] ); | |
| 229 | + $attrs['blockClass'] = trim( ( $attrs['blockClass'] ?? '' ) . ' ' . $extra_class ); | |
| 160 | 230 | } |
| 161 | 231 | |
| 162 | - return $this->apply_block_defaults($attrs, $rows); | |
| 232 | + return $this->apply_block_defaults( $attrs, $rows ); | |
| 163 | 233 | } |
| 164 | 234 | |
| 165 | - private function apply_block_defaults(array $attrs, array $rows): array | |
| 166 | - { | |
| 167 | - $attrs = array_replace_recursive(self::DEFAULT_BLOCK_ATTRS, $attrs); | |
| 235 | + /** | |
| 236 | + * Merges in default block attribute values, and generates placeholder header/footer | |
| 237 | + * cells when a table has headers/footers enabled but no cell data yet. | |
| 238 | + * | |
| 239 | + * @param array $attrs Block attributes to fill in defaults for. | |
| 240 | + * @param array $rows The block's inner row blocks, used to detect column count when needed. | |
| 241 | + * @return array Attribute array with defaults applied. | |
| 242 | + */ | |
| 243 | + private function apply_block_defaults( array $attrs, array $rows ): array { | |
| 244 | + $attrs = array_replace_recursive( self::DEFAULT_BLOCK_ATTRS, $attrs ); | |
| 168 | 245 | |
| 169 | 246 | $col_count = (int) $attrs['columnCount']; |
| 170 | 247 | |
| 171 | - if (! $col_count && $rows) { | |
| 172 | - $col_count = $this->detect_column_count($rows); | |
| 248 | + if ( ! $col_count && $rows ) { | |
| 249 | + $col_count = $this->detect_column_count( $rows ); | |
| 173 | 250 | } |
| 174 | 251 | |
| 175 | - if ($attrs['hasHeader'] && empty($attrs['headers']) && $col_count) { | |
| 176 | - $attrs['headers'] = $this->generate_placeholder_cells($col_count, 'Header'); | |
| 252 | + if ( $attrs['hasHeader'] && empty( $attrs['headers'] ) && $col_count ) { | |
| 253 | + $attrs['headers'] = $this->generate_placeholder_cells( $col_count, 'Header' ); | |
| 177 | 254 | } |
| 178 | 255 | |
| 179 | - if ($attrs['hasFooter'] && empty($attrs['footers']) && $col_count) { | |
| 180 | - $attrs['footers'] = $this->generate_placeholder_cells($col_count, 'Footer'); | |
| 256 | + if ( $attrs['hasFooter'] && empty( $attrs['footers'] ) && $col_count ) { | |
| 257 | + $attrs['footers'] = $this->generate_placeholder_cells( $col_count, 'Footer' ); | |
| 181 | 258 | } |
| 182 | 259 | |
| 183 | 260 | return $attrs; |
| 184 | 261 | } |
| 185 | 262 | |
| 186 | - private function detect_column_count(array $rows): int | |
| 187 | - { | |
| 188 | - foreach ($rows as $row) { | |
| 189 | - if ('tablebuilder/table-builder-row' === ($row['blockName'] ?? '')) { | |
| 190 | - return count($row['innerBlocks'] ?? []); | |
| 263 | + /** | |
| 264 | + * Counts columns from the first "tablebuilder/table-builder-row" block's inner blocks. | |
| 265 | + * | |
| 266 | + * @param array $rows Row blocks (a table block's innerBlocks). | |
| 267 | + * @return int Detected column count, or 0 if no row block is found. | |
| 268 | + */ | |
| 269 | + private function detect_column_count( array $rows ): int { | |
| 270 | + foreach ( $rows as $row ) { | |
| 271 | + if ( 'tablebuilder/table-builder-row' === ( $row['blockName'] ?? '' ) ) { | |
| 272 | + return count( $row['innerBlocks'] ?? array() ); | |
| 191 | 273 | } |
| 192 | 274 | } |
| 193 | 275 | |
| 194 | 276 | return 0; |
| @@ -193,13 +275,19 @@ | ||
| 193 | 275 | |
| 194 | 276 | return 0; |
| 195 | 277 | } |
| 196 | 278 | |
| 197 | - private function generate_placeholder_cells(int $count, string $prefix): array | |
| 198 | - { | |
| 279 | + /** | |
| 280 | + * Builds a list of placeholder cell arrays, e.g. "Header 1", "Header 2", ... | |
| 281 | + * | |
| 282 | + * @param int $count Number of cells to generate. | |
| 283 | + * @param string $prefix Label prefix, e.g. "Header" or "Footer". | |
| 284 | + * @return array[] Array of ['title' => string] cell descriptors. | |
| 285 | + */ | |
| 286 | + private function generate_placeholder_cells( int $count, string $prefix ): array { | |
| 199 | 287 | return array_map( |
| 200 | - static fn(int $i) => ['title' => "{$prefix} " . ($i + 1)], | |
| 201 | - range(0, $count - 1) | |
| 288 | + static fn( int $i ) => array( 'title' => "{$prefix} " . ( $i + 1 ) ), | |
| 289 | + range( 0, $count - 1 ) | |
| 202 | 290 | ); |
| 203 | 291 | } |
| 204 | 292 | |
| 205 | 293 | // ------------------------------------------------------------------------- |
| @@ -205,23 +293,30 @@ | ||
| 205 | 293 | // ------------------------------------------------------------------------- |
| 206 | 294 | // ID Resolution |
| 207 | 295 | // ------------------------------------------------------------------------- |
| 208 | 296 | |
| 209 | - private function parse_ids(array $atts): array | |
| 210 | - { | |
| 211 | - $raw_id = trim((string) ($atts['id'] ?? '')); | |
| 212 | - $post_id = (int) ($atts['post_id'] ?? 0); | |
| 213 | - $block_id = (string) ($atts['block_id'] ?? ''); | |
| 297 | + /** | |
| 298 | + * Resolves the "id" attribute (which may be a numeric post ID or an alphanumeric | |
| 299 | + * block ID) alongside the explicit "post_id"/"block_id" attributes into a single | |
| 300 | + * unambiguous ID set. | |
| 301 | + * | |
| 302 | + * @param array $atts Sanitized shortcode attributes. | |
| 303 | + * @return array{raw_id:string,post_id:int,block_id:string} Resolved IDs. | |
| 304 | + */ | |
| 305 | + private function parse_ids( array $atts ): array { | |
| 306 | + $raw_id = trim( (string) ( $atts['id'] ?? '' ) ); | |
| 307 | + $post_id = (int) ( $atts['post_id'] ?? 0 ); | |
| 308 | + $block_id = (string) ( $atts['block_id'] ?? '' ); | |
| 214 | 309 | |
| 215 | - if (! $post_id && ctype_digit($raw_id)) { | |
| 310 | + if ( ! $post_id && ctype_digit( $raw_id ) ) { | |
| 216 | 311 | $post_id = (int) $raw_id; |
| 217 | 312 | } |
| 218 | 313 | |
| 219 | - if (! $block_id && $raw_id && ! ctype_digit($raw_id)) { | |
| 314 | + if ( ! $block_id && $raw_id && ! ctype_digit( $raw_id ) ) { | |
| 220 | 315 | $block_id = $raw_id; |
| 221 | 316 | } |
| 222 | 317 | |
| 223 | - return compact('raw_id', 'post_id', 'block_id'); | |
| 318 | + return compact( 'raw_id', 'post_id', 'block_id' ); | |
| 224 | 319 | } |
| 225 | 320 | |
| 226 | 321 | // ------------------------------------------------------------------------- |
| 227 | 322 | // Block Resolution (specific block_id path only) |
| @@ -226,87 +321,141 @@ | ||
| 226 | 321 | // ------------------------------------------------------------------------- |
| 227 | 322 | // Block Resolution (specific block_id path only) |
| 228 | 323 | // ------------------------------------------------------------------------- |
| 229 | 324 | |
| 230 | - private function locate_block(int $post_id, string $block_id, string $raw_id): array | |
| 231 | - { | |
| 232 | - if ($post_id) { | |
| 233 | - $block = $this->get_block_from_post($post_id, $block_id); | |
| 234 | - if ($block) { | |
| 325 | + /** | |
| 326 | + * Locates a target block, either within a specific post (when $post_id is given) | |
| 327 | + * or by searching the database for any post containing the block ID. | |
| 328 | + * | |
| 329 | + * @param int $post_id Post ID to look within first, or 0 to skip straight to a database search. | |
| 330 | + * @param string $block_id Explicit block ID to search for. | |
| 331 | + * @param string $raw_id Fallback ID (from the shortcode's "id" attribute) used when $block_id is empty. | |
| 332 | + * @return array The located block, or an empty array if not found. | |
| 333 | + */ | |
| 334 | + private function locate_block( int $post_id, string $block_id, string $raw_id ): array { | |
| 335 | + if ( $post_id ) { | |
| 336 | + $block = $this->get_block_from_post( $post_id, $block_id ); | |
| 337 | + if ( $block ) { | |
| 235 | 338 | return $block; |
| 236 | 339 | } |
| 237 | 340 | } |
| 238 | 341 | |
| 239 | - $lookup = $block_id ?: $raw_id; | |
| 342 | + $lookup = $block_id ? $block_id : $raw_id; | |
| 240 | 343 | |
| 241 | - return $lookup ? $this->search_block_by_id($lookup) : []; | |
| 344 | + return $lookup ? $this->search_block_by_id( $lookup ) : array(); | |
| 242 | 345 | } |
| 243 | 346 | |
| 244 | 347 | /** |
| 245 | 348 | * Parses a specific post's block content and finds the target block. |
| 349 | + * | |
| 350 | + * @param int $post_id Post ID to load and parse. | |
| 351 | + * @param string $block_id Block ID to search for. | |
| 352 | + * @return array The located block, or an empty array if not found/not viewable. | |
| 246 | 353 | */ |
| 247 | - private function get_block_from_post(int $post_id, string $block_id): array | |
| 248 | - { | |
| 249 | - $post = get_post($post_id); | |
| 354 | + private function get_block_from_post( int $post_id, string $block_id ): array { | |
| 355 | + $post = get_post( $post_id ); | |
| 250 | 356 | |
| 251 | - if (! $post || empty($post->post_content)) { | |
| 252 | - return []; | |
| 357 | + if ( ! $post || empty( $post->post_content ) || ! $this->can_view_post( $post ) ) { | |
| 358 | + return array(); | |
| 253 | 359 | } |
| 254 | 360 | |
| 255 | - return $this->find_table_block(parse_blocks($post->post_content), $block_id); | |
| 361 | + return $this->find_table_block( parse_blocks( $post->post_content ), $block_id ); | |
| 256 | 362 | } |
| 257 | 363 | |
| 258 | 364 | /** |
| 365 | + * Whether the current request is allowed to see a post's content. | |
| 366 | + * Prevents the [tableKit] shortcode from being used to pull table | |
| 367 | + * content out of private/draft/pending posts the viewer can't read. | |
| 368 | + * | |
| 369 | + * @param \WP_Post $post Post to check. | |
| 370 | + * @return bool True if the post is published, or the viewer has "read_post" capability on it. | |
| 371 | + */ | |
| 372 | + private function can_view_post( \WP_Post $post ): bool { | |
| 373 | + if ( 'publish' === $post->post_status ) { | |
| 374 | + return true; | |
| 375 | + } | |
| 376 | + | |
| 377 | + return current_user_can( 'read_post', $post->ID ); | |
| 378 | + } | |
| 379 | + | |
| 380 | + /** | |
| 259 | 381 | * Searches the database for posts containing the given block ID. |
| 382 | + * Candidate post IDs are cached for 5 minutes per block ID. | |
| 383 | + * | |
| 384 | + * @param string $block_id Block ID (or short ID) to search for in post content. | |
| 385 | + * @return array The located block, or an empty array if not found. | |
| 260 | 386 | */ |
| 261 | - private function search_block_by_id(string $block_id): array | |
| 262 | - { | |
| 387 | + private function search_block_by_id( string $block_id ): array { | |
| 263 | 388 | global $wpdb; |
| 264 | 389 | |
| 265 | - $candidate_ids = $wpdb->get_col( | |
| 266 | - $wpdb->prepare( | |
| 267 | - "SELECT ID | |
| 268 | - FROM {$wpdb->posts} | |
| 269 | - WHERE post_content LIKE %s | |
| 270 | - AND post_status NOT IN ('trash', 'auto-draft') | |
| 271 | - LIMIT 10", | |
| 272 | - '%' . $wpdb->esc_like($block_id) . '%' | |
| 273 | - ) | |
| 274 | - ); | |
| 390 | + $cache_key = 'tablekit_block_search_' . md5( $block_id ); | |
| 391 | + $candidate_ids = wp_cache_get( $cache_key, 'table-builder-block' ); | |
| 275 | 392 | |
| 276 | - foreach ($candidate_ids as $id) { | |
| 277 | - $block = $this->get_block_from_post((int) $id, $block_id); | |
| 278 | - if ($block) { | |
| 393 | + if ( false === $candidate_ids ) { | |
| 394 | + // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery -- no WP_Query equivalent for "find posts whose content contains this block ID"; result is cached just below. | |
| 395 | + $candidate_ids = $wpdb->get_col( | |
| 396 | + $wpdb->prepare( | |
| 397 | + "SELECT ID | |
| 398 | + FROM {$wpdb->posts} | |
| 399 | + WHERE post_content LIKE %s | |
| 400 | + AND post_status NOT IN ('trash', 'auto-draft') | |
| 401 | + LIMIT 10", | |
| 402 | + '%' . $wpdb->esc_like( $block_id ) . '%' | |
| 403 | + ) | |
| 404 | + ); | |
| 405 | + | |
| 406 | + wp_cache_set( $cache_key, $candidate_ids, 'table-builder-block', 5 * MINUTE_IN_SECONDS ); | |
| 407 | + } | |
| 408 | + | |
| 409 | + foreach ( $candidate_ids as $id ) { | |
| 410 | + $block = $this->get_block_from_post( (int) $id, $block_id ); | |
| 411 | + if ( $block ) { | |
| 279 | 412 | return $block; |
| 280 | 413 | } |
| 281 | 414 | } |
| 282 | 415 | |
| 283 | - return []; | |
| 416 | + return array(); | |
| 284 | 417 | } |
| 285 | 418 | |
| 286 | - private function find_table_block(array $blocks, string $block_id): array | |
| 287 | - { | |
| 288 | - $block_names = apply_filters('tablekit/block_names', ['tablebuilder/table-builder']); | |
| 419 | + /** | |
| 420 | + * Recursively searches a block tree for a table block matching the given ID | |
| 421 | + * (by blockID or shortId attribute), or the first table block if no ID is given. | |
| 422 | + * | |
| 423 | + * @param array $blocks Block tree to search (parsed blocks, possibly with innerBlocks). | |
| 424 | + * @param string $block_id Block ID to match; empty string matches the first table block found. | |
| 425 | + * @return array The matched block, or an empty array if not found. | |
| 426 | + */ | |
| 427 | + private function find_table_block( array $blocks, string $block_id ): array { | |
| 428 | + /** | |
| 429 | + * Filters the block names treated as "table blocks" by the [tableKit] shortcode, | |
| 430 | + * letting the Pro add-on (or third parties) register additional table block types. | |
| 431 | + * | |
| 432 | + * @since Unknown | |
| 433 | + * | |
| 434 | + * @param string[] $block_names Block names to match, e.g. "tablebuilder/table-builder". | |
| 435 | + */ | |
| 436 | + // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores -- slash-namespaced hook name is this plugin's established public API (used by the Pro add-on); renaming would be a breaking change. | |
| 437 | + $block_names = apply_filters( 'tablekit/block_names', array( 'tablebuilder/table-builder' ) ); | |
| 289 | 438 | |
| 290 | - foreach ($blocks as $block) { | |
| 291 | - if (in_array($block['blockName'] ?? '', $block_names, true)) { | |
| 292 | - $id = (string) ($block['attrs']['blockID'] ?? ''); | |
| 293 | - $short_id = (string) ($block['attrs']['shortId'] ?? ''); | |
| 439 | + foreach ( $blocks as $block ) { | |
| 440 | + if ( in_array( $block['blockName'] ?? '', $block_names, true ) ) { | |
| 441 | + $id = (string) ( $block['attrs']['blockID'] ?? '' ); | |
| 442 | + $short_id = (string) ( $block['attrs']['shortId'] ?? '' ); | |
| 294 | 443 | |
| 295 | - if (!$block_id || $id === $block_id || $short_id === $block_id) { | |
| 444 | + if ( ! $block_id || $id === $block_id || $short_id === $block_id ) { | |
| 296 | 445 | return $block; |
| 297 | 446 | } |
| 298 | 447 | } |
| 299 | 448 | |
| 300 | - if (!empty($block['innerBlocks'])) { | |
| 301 | - $found = $this->find_table_block($block['innerBlocks'], $block_id); | |
| 302 | - if ($found) { | |
| 449 | + if ( ! empty( $block['innerBlocks'] ) ) { | |
| 450 | + $found = $this->find_table_block( $block['innerBlocks'], $block_id ); | |
| 451 | + if ( $found ) { | |
| 303 | 452 | return $found; |
| 304 | 453 | } |
| 305 | 454 | } |
| 306 | 455 | } |
| 307 | 456 | |
| 308 | - return []; | |
| 457 | + return array(); | |
| 309 | 458 | } |
| 310 | 459 | |
| 311 | 460 | // ------------------------------------------------------------------------- |
| 312 | 461 | // CSS Collection |
| @@ -311,10 +460,15 @@ | ||
| 311 | 460 | // ------------------------------------------------------------------------- |
| 312 | 461 | // CSS Collection |
| 313 | 462 | // ------------------------------------------------------------------------- |
| 314 | 463 | |
| 315 | - public function collect_blocks_css_from_content( string $content ): string | |
| 316 | - { | |
| 464 | + /** | |
| 465 | + * Collects combined CSS for every table block found within a block of post content. | |
| 466 | + * | |
| 467 | + * @param string $content Serialized block content (e.g. a post's post_content). | |
| 468 | + * @return string Combined CSS, or an empty string if there's no content/no table blocks. | |
| 469 | + */ | |
| 470 | + public function collect_blocks_css_from_content( string $content ): string { | |
| 317 | 471 | if ( '' === trim( $content ) ) { |
| 318 | 472 | return ''; |
| 319 | 473 | } |
| 320 | 474 | |
| @@ -322,9 +476,11 @@ | ||
| 322 | 476 | if ( empty( $blocks ) ) { |
| 323 | 477 | return ''; |
| 324 | 478 | } |
| 325 | 479 | |
| 326 | - $block_names = apply_filters( 'tablekit/block_names', [ 'tablebuilder/table-builder' ] ); | |
| 480 | + /** This filter is documented in includes/Shortcode/Shortcode.php */ | |
| 481 | + // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores -- slash-namespaced hook name is this plugin's established public API (used by the Pro add-on); renaming would be a breaking change. | |
| 482 | + $block_names = apply_filters( 'tablekit/block_names', array( 'tablebuilder/table-builder' ) ); | |
| 327 | 483 | $css = ''; |
| 328 | 484 | |
| 329 | 485 | foreach ( $blocks as $block ) { |
| 330 | 486 | $css .= $this->collect_css_from_block_tree( $block, $block_names ); |
| @@ -332,10 +488,17 @@ | ||
| 332 | 488 | |
| 333 | 489 | return $css; |
| 334 | 490 | } |
| 335 | 491 | |
| 336 | - private function collect_css_from_block_tree( array $block, array $block_names ): string | |
| 337 | - { | |
| 492 | + /** | |
| 493 | + * Recursively collects CSS from a block and its inner blocks, for any block | |
| 494 | + * whose name is in the given allow-list. | |
| 495 | + * | |
| 496 | + * @param array $block Parsed block array. | |
| 497 | + * @param array $block_names Block names to collect CSS for (e.g. "tablebuilder/table-builder"). | |
| 498 | + * @return string Combined CSS from this block and its descendants. | |
| 499 | + */ | |
| 500 | + private function collect_css_from_block_tree( array $block, array $block_names ): string { | |
| 338 | 501 | $css = ''; |
| 339 | 502 | |
| 340 | 503 | if ( in_array( $block['blockName'] ?? '', $block_names, true ) ) { |
| 341 | 504 | $css .= ShortcodeUtils::collect_block_css( $block ); |
| @@ -351,17 +514,22 @@ | ||
| 351 | 514 | // ------------------------------------------------------------------------- |
| 352 | 515 | // Asset Management |
| 353 | 516 | // ------------------------------------------------------------------------- |
| 354 | 517 | |
| 355 | - private function block_enqueue_assets(): void | |
| 356 | - { | |
| 357 | - if (self::$assets_enqueued) { | |
| 518 | + /** | |
| 519 | + * Enqueues the plugin's shared styles + the base table-builder block's assets, | |
| 520 | + * once per request. | |
| 521 | + * | |
| 522 | + * @return void | |
| 523 | + */ | |
| 524 | + private function block_enqueue_assets(): void { | |
| 525 | + if ( self::$assets_enqueued ) { | |
| 358 | 526 | return; |
| 359 | 527 | } |
| 360 | 528 | |
| 361 | 529 | self::$assets_enqueued = true; |
| 362 | 530 | ShortcodeUtils::enqueue_shared_styles(); |
| 363 | - ShortcodeUtils::enqueue_block_assets('tablebuilder/table-builder'); | |
| 531 | + ShortcodeUtils::enqueue_block_assets( 'tablebuilder/table-builder' ); | |
| 364 | 532 | } |
| 365 | 533 | |
| 366 | 534 | // ------------------------------------------------------------------------- |
| 367 | 535 | // Public API |
| @@ -366,20 +534,29 @@ | ||
| 366 | 534 | // ------------------------------------------------------------------------- |
| 367 | 535 | // Public API |
| 368 | 536 | // ------------------------------------------------------------------------- |
| 369 | 537 | |
| 370 | - public static function is_assets_enqueued(): bool | |
| 371 | - { | |
| 538 | + /** | |
| 539 | + * Whether the shortcode's shared frontend assets have been enqueued yet this request. | |
| 540 | + * | |
| 541 | + * @return bool | |
| 542 | + */ | |
| 543 | + public static function is_assets_enqueued(): bool { | |
| 372 | 544 | return self::$assets_enqueued; |
| 373 | 545 | } |
| 374 | 546 | |
| 375 | - private function sanitize_atts(array $atts): array | |
| 376 | - { | |
| 377 | - $atts['id'] = sanitize_text_field((string) ($atts['id'] ?? '')); | |
| 378 | - $atts['post_id'] = absint($atts['post_id'] ?? 0); | |
| 379 | - $atts['block_id'] = sanitize_text_field((string) ($atts['block_id'] ?? '')); | |
| 380 | - $atts['class'] = sanitize_text_field((string) ($atts['class'] ?? '')); | |
| 381 | - $atts['attrs_json'] = (string) ($atts['attrs_json'] ?? ''); | |
| 547 | + /** | |
| 548 | + * Sanitizes raw shortcode attributes. | |
| 549 | + * | |
| 550 | + * @param array $atts Raw attributes (already merged with defaults via shortcode_atts()). | |
| 551 | + * @return array Sanitized attributes. | |
| 552 | + */ | |
| 553 | + private function sanitize_atts( array $atts ): array { | |
| 554 | + $atts['id'] = sanitize_text_field( (string) ( $atts['id'] ?? '' ) ); | |
| 555 | + $atts['post_id'] = absint( $atts['post_id'] ?? 0 ); | |
| 556 | + $atts['block_id'] = sanitize_text_field( (string) ( $atts['block_id'] ?? '' ) ); | |
| 557 | + $atts['class'] = sanitize_text_field( (string) ( $atts['class'] ?? '' ) ); | |
| 558 | + $atts['attrs_json'] = (string) ( $atts['attrs_json'] ?? '' ); | |
| 382 | 559 | |
| 383 | 560 | return $atts; |
| 384 | 561 | } |
| 385 | -} | |
| 562 | +} | |
