diff --git a/CLAUDE.md b/CLAUDE.md index 298d7cb..b47c7fd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -99,8 +99,7 @@ no ACF Pro. Things to know before touching them: - `tests/bootstrap.php` **must** `define( 'ABSPATH' )` before including anything. All four PHP files open with `defined( 'ABSPATH' ) || exit;`, so an include without it silently exits and takes the test runner down with it. -- The bootstrap includes `plugin.php` exactly once (no `function_exists()` guards there), - which fires every `add_action`/`add_filter`/`add_shortcode` into a recording registry. +- The bootstrap includes `plugin.php` once, which fires every `add_action`/`add_filter`/`add_shortcode` into a recording registry. `ucsccomms_test_reset( true )` preserves that registry between tests while clearing everything else. - `have_rows()`/`the_row()` in `tests/wp-stubs.php` are a **stateful iterator pair** over @@ -127,5 +126,7 @@ None outstanding. All nine items from the original audit are fixed — see `ucsc-communications-functionality-settings` independently — one as the menu slug, one in a `strpos()` screen check — with no shared constant. They must stay in sync or the admin stylesheet silently stops loading. Pinned by `RegistrationTest`. -- `plugin.php` and `lib/functions/shortcodes.php` have **no `function_exists()` guards** - (unlike `general.php` and `settings.php`), so double-inclusion is fatal. +- `plugin.php` returns early if `UCSCCOMMS_PLUGIN_DIR` is already defined, so a second + copy of the plugin in another directory loads nothing and the first copy wins. Every + function in `plugin.php` and `lib/functions/` also has a `function_exists()` guard. + Keep both when you add code. Pinned by `DoubleInclusionTest`. diff --git a/ROADMAP.md b/ROADMAP.md index 894b7b2..bbbf99a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -291,6 +291,30 @@ class, together with that packaging work. --- +### ~~A second copy of the plugin was fatal~~ +**Status:** ✅ Fixed — [#33](https://github.com/ucsc/ucsc-communications-functionality/issues/33) +**Files:** `plugin.php`, `lib/functions/shortcodes.php` + +`plugin.php` and `lib/functions/shortcodes.php` had no `function_exists()` guards, +unlike `general.php` and `settings.php`. Inside one copy of the plugin this was safe, +because WordPress loads `plugin.php` once and `plugin.php` loads each lib file with +`require_once` / `include_once`. But a second copy in another directory (for example +after a second zip upload) has different paths, so `*_once` does not stop it. That copy +warned on the three `define()` calls and then fatalled on the first unguarded function. + +`function_exists()` guards alone do not fix this: the constants still warn, and the site +runs a mix of functions from two copies that can be different versions. + +**Fixed by:** an early `return` at the top of `plugin.php` when `UCSCCOMMS_PLUGIN_DIR` is +already defined, so the first copy that loads wins and the second copy does nothing. +The four unguarded functions also got `function_exists()` guards, to match the rest of +the codebase. `tests/DoubleInclusionTest.php` includes both files a second time. +The same change dropped a stray leading slash from the `settings.php` and `shortcodes.php` +include paths (`UCSCCOMMS_PLUGIN_DIR . '/lib/...'`), which made a double slash because +`plugin_dir_path()` already ends in one. + +--- + ## Deferred / not planned - **No PHPStan config.** Worth knowing what it would and would not buy here: diff --git a/lib/functions/shortcodes.php b/lib/functions/shortcodes.php index 095de42..4c72228 100644 --- a/lib/functions/shortcodes.php +++ b/lib/functions/shortcodes.php @@ -13,71 +13,75 @@ defined( 'ABSPATH' ) || exit; -/** - * Render the style definitions for the current post. - * - * Handles the [style-definition] shortcode, which outputs the - * `style_definitions` repeater for whichever post is in context. - * - * @return string HTML markup for the current post's style definitions. - */ -function ucsccomms_a_z_style_guide_single_loop() { - $finaldefs = ''; +if ( ! function_exists( 'ucsccomms_a_z_style_guide_single_loop' ) ) { + /** + * Render the style definitions for the current post. + * + * Handles the [style-definition] shortcode, which outputs the + * `style_definitions` repeater for whichever post is in context. + * + * @return string HTML markup for the current post's style definitions. + */ + function ucsccomms_a_z_style_guide_single_loop() { + $finaldefs = ''; - if ( have_rows( 'style_definitions' ) ) : - while ( have_rows( 'style_definitions' ) ) : - the_row(); - $az_item = get_sub_field( 'editorial_style_item' ); - $az_def = get_sub_field( 'editorial_style_definition' ); - // esc_html() for the plain-text item; wp_kses_post() for the WYSIWYG definition. - $finaldefs .= '

' . esc_html( $az_item ) . ':

' . wp_kses_post( $az_def ) . '
'; - endwhile; - endif; + if ( have_rows( 'style_definitions' ) ) : + while ( have_rows( 'style_definitions' ) ) : + the_row(); + $az_item = get_sub_field( 'editorial_style_item' ); + $az_def = get_sub_field( 'editorial_style_definition' ); + // esc_html() for the plain-text item; wp_kses_post() for the WYSIWYG definition. + $finaldefs .= '

' . esc_html( $az_item ) . ':

' . wp_kses_post( $az_def ) . '
'; + endwhile; + endif; - return $finaldefs; + return $finaldefs; + } } add_shortcode( 'style-definition', 'ucsccomms_a_z_style_guide_single_loop' ); -/** - * Render every Editorial Style Guide entry as an archive. - * - * Handles the [style-archive] shortcode. Retrieves all `a_z_style_guide` posts - * ordered by title ascending, and renders each title followed by its style - * definitions. - * - * @return string HTML markup for the full style guide archive. - */ -function ucsccomms_a_z_styles_archive_loop() { - $finalloop = ''; +if ( ! function_exists( 'ucsccomms_a_z_styles_archive_loop' ) ) { + /** + * Render every Editorial Style Guide entry as an archive. + * + * Handles the [style-archive] shortcode. Retrieves all `a_z_style_guide` posts + * ordered by title ascending, and renders each title followed by its style + * definitions. + * + * @return string HTML markup for the full style guide archive. + */ + function ucsccomms_a_z_styles_archive_loop() { + $finalloop = ''; - $args = array( - 'post_type' => 'a_z_style_guide', - 'orderby' => 'title', - 'order' => 'ASC', - 'posts_per_page' => -1, - ); + $args = array( + 'post_type' => 'a_z_style_guide', + 'orderby' => 'title', + 'order' => 'ASC', + 'posts_per_page' => -1, + ); - $az_dir = new \WP_Query( $args ); + $az_dir = new \WP_Query( $args ); - if ( $az_dir->have_posts() ) : - while ( $az_dir->have_posts() ) : - $az_dir->the_post(); - $az_title = get_the_title(); - $finalloop .= '

' . esc_html( $az_title ) . '

'; - if ( have_rows( 'style_definitions' ) ) : - while ( have_rows( 'style_definitions' ) ) : - the_row(); - $az_item = get_sub_field( 'editorial_style_item' ); - $az_def = get_sub_field( 'editorial_style_definition' ); - // esc_html() for the plain-text item; wp_kses_post() for the WYSIWYG definition. - $finalloop .= '

' . esc_html( $az_item ) . ':

' . wp_kses_post( $az_def ) . '
'; - endwhile; - endif; - endwhile; - // Restore the global $post clobbered by the_post() above. - wp_reset_postdata(); - endif; + if ( $az_dir->have_posts() ) : + while ( $az_dir->have_posts() ) : + $az_dir->the_post(); + $az_title = get_the_title(); + $finalloop .= '

' . esc_html( $az_title ) . '

'; + if ( have_rows( 'style_definitions' ) ) : + while ( have_rows( 'style_definitions' ) ) : + the_row(); + $az_item = get_sub_field( 'editorial_style_item' ); + $az_def = get_sub_field( 'editorial_style_definition' ); + // esc_html() for the plain-text item; wp_kses_post() for the WYSIWYG definition. + $finalloop .= '

' . esc_html( $az_item ) . ':

' . wp_kses_post( $az_def ) . '
'; + endwhile; + endif; + endwhile; + // Restore the global $post clobbered by the_post() above. + wp_reset_postdata(); + endif; - return $finalloop; + return $finalloop; + } } add_shortcode( 'style-archive', 'ucsccomms_a_z_styles_archive_loop' ); diff --git a/plugin.php b/plugin.php index 341485e..db0814b 100644 --- a/plugin.php +++ b/plugin.php @@ -19,6 +19,12 @@ defined( 'ABSPATH' ) || exit; +// Load once. A second copy of this plugin in another directory, or a second +// include of this file, returns here before it defines or registers anything. +if ( defined( 'UCSCCOMMS_PLUGIN_DIR' ) ) { + return; +} + // Set plugin directory, URL and base name. define( 'UCSCCOMMS_PLUGIN_DIR', plugin_dir_path( __FILE__ ) ); // Path to plugin directory. define( 'UCSCCOMMS_PLUGIN_URL', plugin_dir_url( __FILE__ ) ); // URL of plugin directory, for enqueuing assets. @@ -29,40 +35,44 @@ require_once UCSCCOMMS_PLUGIN_DIR . 'lib/functions/general.php'; } // Include settings. -if ( file_exists( UCSCCOMMS_PLUGIN_DIR . '/lib/functions/settings.php' ) ) { - include_once UCSCCOMMS_PLUGIN_DIR . '/lib/functions/settings.php'; +if ( file_exists( UCSCCOMMS_PLUGIN_DIR . 'lib/functions/settings.php' ) ) { + include_once UCSCCOMMS_PLUGIN_DIR . 'lib/functions/settings.php'; } // Include shortcodes. -if ( file_exists( UCSCCOMMS_PLUGIN_DIR . '/lib/functions/shortcodes.php' ) ) { - include_once UCSCCOMMS_PLUGIN_DIR . '/lib/functions/shortcodes.php'; +if ( file_exists( UCSCCOMMS_PLUGIN_DIR . 'lib/functions/shortcodes.php' ) ) { + include_once UCSCCOMMS_PLUGIN_DIR . 'lib/functions/shortcodes.php'; } -/** - * Point ACF at this plugin's acf-json directory when saving field groups. - * - * @param string $path Default save path supplied by ACF. - * @return string Path to this plugin's acf-json directory. - */ -function ucsccomms_acf_json_save_point( $path ) { - $path = UCSCCOMMS_PLUGIN_DIR . 'acf-json'; - return $path; +if ( ! function_exists( 'ucsccomms_acf_json_save_point' ) ) { + /** + * Point ACF at this plugin's acf-json directory when saving field groups. + * + * @param string $path Default save path supplied by ACF. + * @return string Path to this plugin's acf-json directory. + */ + function ucsccomms_acf_json_save_point( $path ) { + $path = UCSCCOMMS_PLUGIN_DIR . 'acf-json'; + return $path; + } } // Set plugin directory for saving ACF JSON files. add_filter( 'acf/settings/save_json', 'ucsccomms_acf_json_save_point' ); -/** - * Point ACF at this plugin's acf-json directory when loading field groups. - * - * Drops ACF's default load path so field groups come from this plugin rather - * than the active theme. - * - * @param array $paths Default load paths supplied by ACF. - * @return array Load paths with this plugin's acf-json directory appended. - */ -function ucsccomms_acf_json_load_point( $paths ) { - unset( $paths[0] ); - $paths[] = UCSCCOMMS_PLUGIN_DIR . 'acf-json'; - return $paths; +if ( ! function_exists( 'ucsccomms_acf_json_load_point' ) ) { + /** + * Point ACF at this plugin's acf-json directory when loading field groups. + * + * Drops ACF's default load path so field groups come from this plugin rather + * than the active theme. + * + * @param array $paths Default load paths supplied by ACF. + * @return array Load paths with this plugin's acf-json directory appended. + */ + function ucsccomms_acf_json_load_point( $paths ) { + unset( $paths[0] ); + $paths[] = UCSCCOMMS_PLUGIN_DIR . 'acf-json'; + return $paths; + } } // Set plugin directory for loading ACF JSON files. add_filter( 'acf/settings/load_json', 'ucsccomms_acf_json_load_point' ); diff --git a/tests/DoubleInclusionTest.php b/tests/DoubleInclusionTest.php new file mode 100644 index 0000000..11f6a50 --- /dev/null +++ b/tests/DoubleInclusionTest.php @@ -0,0 +1,73 @@ +hooks = $GLOBALS['ucsccomms_test']['hooks']; + } + + /** + * Restore the hook registry for the tests that run after this one. + * + * @return void + */ + protected function tearDown(): void { + $GLOBALS['ucsccomms_test']['hooks'] = $this->hooks; + + parent::tearDown(); + } + + /** + * A second include of plugin.php returns before it registers anything. + * + * @return void + */ + public function test_second_include_of_plugin_php_is_a_no_op(): void { + include dirname( __DIR__ ) . '/plugin.php'; + + $this->assertSame( $this->hooks, $GLOBALS['ucsccomms_test']['hooks'] ); + } + + /** + * A second include of shortcodes.php does not redeclare its functions. + * + * @return void + */ + public function test_second_include_of_shortcodes_php_is_safe(): void { + include dirname( __DIR__ ) . '/lib/functions/shortcodes.php'; + + $shortcodes = $GLOBALS['ucsccomms_test']['hooks']['shortcode']; + + $this->assertSame( 'ucsccomms_a_z_style_guide_single_loop', $shortcodes['style-definition'] ); + $this->assertSame( 'ucsccomms_a_z_styles_archive_loop', $shortcodes['style-archive'] ); + } +} diff --git a/tests/bootstrap.php b/tests/bootstrap.php index 963192a..9fb5264 100644 --- a/tests/bootstrap.php +++ b/tests/bootstrap.php @@ -14,8 +14,8 @@ ucsccomms_test_reset(); -// Include the real plugin bootstrap exactly once. plugin.php and shortcodes.php -// have no function_exists() guards, so a second include is fatal. This defines +// Include the real plugin bootstrap. A second include is a no-op, because plugin.php +// returns early once UCSCCOMMS_PLUGIN_DIR is defined (see DoubleInclusionTest). This defines // the UCSCCOMMS_* constants, pulls in the three lib files, and fires every // add_action/add_filter/add_shortcode into the recording registry. require_once dirname( __DIR__ ) . '/plugin.php';