Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`.
24 changes: 24 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
118 changes: 61 additions & 57 deletions lib/functions/shortcodes.php
Original file line number Diff line number Diff line change
Expand Up @@ -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 .= '<p><b>' . esc_html( $az_item ) . ':</b></p>' . wp_kses_post( $az_def ) . '<hr>';
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 .= '<p><b>' . esc_html( $az_item ) . ':</b></p>' . wp_kses_post( $az_def ) . '<hr>';
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 .= '<h2>' . esc_html( $az_title ) . '</h2>';
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 .= '<p><b>' . esc_html( $az_item ) . ':</b></p>' . wp_kses_post( $az_def ) . '<hr>';
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 .= '<h2>' . esc_html( $az_title ) . '</h2>';
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 .= '<p><b>' . esc_html( $az_item ) . ':</b></p>' . wp_kses_post( $az_def ) . '<hr>';
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' );
62 changes: 36 additions & 26 deletions plugin.php
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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' );
73 changes: 73 additions & 0 deletions tests/DoubleInclusionTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
<?php
/**
* Double-inclusion tests.
*
* A second copy of the plugin in another directory loads plugin.php again
* under a different path, so require_once does not stop it. These tests
* include the files a second time and assert that nothing breaks.
*
* @package ucsc-communications-functionality
*/

namespace UCSC\UcscCommunicationsFunctionality\Tests;

/**
* plugin.php and shortcodes.php survive a second include.
*/
final class DoubleInclusionTest extends TestCase {

/**
* The hook registry as the bootstrap recorded it.
*
* @var array
*/
private $hooks;

/**
* Save the hook registry, because TestCase keeps it between tests and
* the add_action/add_filter doubles append rather than dedupe.
*
* @return void
*/
protected function setUp(): void {
parent::setUp();

$this->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'] );
}
}
4 changes: 2 additions & 2 deletions tests/bootstrap.php
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
Loading