From 3271b6ed2c0b1a573f95d1ae15f0ff120738fd75 Mon Sep 17 00:00:00 2001 From: Jason Date: Sat, 7 Nov 2026 09:06:25 -0800 Subject: [PATCH 1/2] fix: make a second copy of the plugin load safely A second copy of the plugin in another directory loads plugin.php under a different path, so require_once does not stop it. That copy warned on the three define() calls and then fatalled on the first unguarded function in shortcodes.php or plugin.php. plugin.php now returns early when UCSCCOMMS_PLUGIN_DIR is already defined, so the first copy wins and the second copy loads nothing. The four unguarded functions also get function_exists() guards, to match general.php and settings.php. DoubleInclusionTest includes both files a second time. CLAUDE.md, ROADMAP.md and the bootstrap comment describe the new behavior. Closes #33 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 9 +-- ROADMAP.md | 21 ++++++ lib/functions/shortcodes.php | 118 ++++++++++++++++++---------------- plugin.php | 54 +++++++++------- tests/DoubleInclusionTest.php | 73 +++++++++++++++++++++ tests/bootstrap.php | 4 +- 6 files changed, 194 insertions(+), 85 deletions(-) create mode 100644 tests/DoubleInclusionTest.php 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..b092517 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -291,6 +291,27 @@ 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. + +--- + ## 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..e8d19d3 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. @@ -37,32 +43,36 @@ 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'; From 2b7b955724b26c4ec16ef7ea402d424532874732 Mon Sep 17 00:00:00 2001 From: Jason Date: Sat, 7 Nov 2026 09:09:08 -0800 Subject: [PATCH 2/2] fix: drop the stray leading slash from two include paths plugin_dir_path() already ends in a slash, so UCSCCOMMS_PLUGIN_DIR . '/lib/...' made a double slash in the settings.php and shortcodes.php include paths. The general.php path already used the correct form. Refs #33 Co-Authored-By: Claude Opus 5.5 --- ROADMAP.md | 3 +++ plugin.php | 8 ++++---- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index b092517..bbbf99a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -309,6 +309,9 @@ runs a mix of functions from two copies that can be different versions. 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. --- diff --git a/plugin.php b/plugin.php index e8d19d3..db0814b 100644 --- a/plugin.php +++ b/plugin.php @@ -35,12 +35,12 @@ 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'; } if ( ! function_exists( 'ucsccomms_acf_json_save_point' ) ) {