require get_template_directory() . 'path/to-my/file.php' BREAKS customize > themes functionality

Question

hope to get some help, please <3

i'm building a theme from scratch as an exercise to learn WP and PHP, using WP commercial themes (GeneratePress and WP default themes) as a guide.

when i use:

$theme_dir = get_template_directory();
require $theme_dir . '/inc/structure/header.php';

all the themes disappear when i click 'customize > change' to change themes and it displays 'showing "0" themes' in right upper corner. iow, the theme thumbnails aren't loading or otherwise visible. when i comment out the require stmt, it returns to normal.

this is exactly how other professional, commercial themes do it, and i've even copy/pasted the code but it still happens.

the file content from the required file is included but also shows on the admin as well as other pages and flashes before the rest of the page loads.

i've got basic theme support in functions.php and i'm hooking into wp_head for the viewport meta, pingbacks_url, and skip-to-content link as well as wp_enqueue_scripts for my styles.

i just started, so that's basically all i have in my theme so far.

i'm not advanced enough to make sense of this but here's my debug.php:

[16-Dec-2020 20:44:46 UTC] PHP Stack trace:
[16-Dec-2020 20:44:46 UTC] PHP   1. {main}() /app/public/wp-admin/admin-ajax.php:0
[16-Dec-2020 20:44:46 UTC] PHP   2. require_once() /app/public/wp-admin/admin-ajax.php:22
[16-Dec-2020 20:44:46 UTC] PHP   3. require_once() /app/public/wp-load.php:37
[16-Dec-2020 20:44:46 UTC] PHP   4. require_once() /app/public/wp-config.php:82
[16-Dec-2020 20:44:46 UTC] PHP   5. include() /app/public/wp-settings.php:525
[16-Dec-2020 20:44:47 UTC] PHP Stack trace:
[16-Dec-2020 20:44:47 UTC] PHP   1. {main}() /app/public/index.php:0
[16-Dec-2020 20:44:47 UTC] PHP   2. require() /app/public/index.php:17
[16-Dec-2020 20:44:47 UTC] PHP   3. require_once() /app/public/wp-blog-header.php:13
[16-Dec-2020 20:44:47 UTC] PHP   4. require_once() /app/public/wp-load.php:37
[16-Dec-2020 20:44:47 UTC] PHP   5. require_once() /app/public/wp-config.php:82
[16-Dec-2020 20:44:47 UTC] PHP   6. include() /app/public/wp-settings.php:525

i get these inspector console errors regardless of whether the require is there or not:

Unknown property ‘speak’.  Declaration dropped. dashicons.css:27:8
Unknown property ‘speak’.  Declaration dropped. admin-bar.css:231:8
Unknown property ‘speak’.  Declaration dropped. admin-bar.css:308:8
Unknown property ‘speak’.  Declaration dropped. admin-bar.css:508:8
Unknown property ‘speak’.  Declaration dropped. admin-bar.css:614:8
Unknown property ‘speak’.  Declaration dropped. admin-bar.css:844:9
Error in parsing value for ‘min-width’.  Declaration dropped. admin-bar.css:971:14
Error in parsing value for ‘min-width’.  Declaration dropped.

i'm baffled. thanks for any help!

Answer 1

thanks again @Rup for sparking the path to this answer!

rendering out directly from the required file was at least part of the problem.

i believe the other part was not rendering from inside a function as well as not hooking all of that functionality into an action in the target file.

the problem vanishes and the content renders properly when these steps are followed:

require the file in functions.php using built-in WordPress function to the current theme's template directory as indicated above.

create a simple action hook in the target file using do_action() function:

do_action( 'namespace_hook_name' );

create a (pluggable, if necessary) function in required file to render desired content (below is based on GeneratePress formatting). $priority and $accepted_args optional:

if ( ! function_exists( 'namespace_func_name' ) ) { add_action( 'namespace_hook_name', 'namespace_func_name', $priority, $args ); function namespace_func_name() { // code to render } }

sorry about the code formatting.. still new here <3

search commercial themes for how they use action hooks as well as WordPress's own default themes to learn more and practice.

https://developer.wordpress.org/reference/functions/do_action/

https://developer.wordpress.org/reference/functions/add_action/