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';