Namespaces & Autoload

warning

Do not run Composer installs directly on production unless you have a controlled build/deploy pipeline. Prefer building artifacts elsewhere, then deploying.

Namespaces & Autoload Explained

Concept	Meaning	Why it helps
Prefixing	gp_child_* names	Avoid collisions
Namespace	GPChild\\...	Organize code by domain
Autoload	Load classes automatically	No manual require chains
PSR-4	Mapping namespace -> folder	Predictable structure

Why It Matters

• Larger child themes become hard to maintain with only functions and requires.
• Namespaces reduce collisions with plugins.
• Autoloading creates a real "codebase" structure.

How It Works

Composer generates vendor/autoload.php based on your composer.json. Your theme includes that file, and classes are loaded automatically when referenced.

flowchart LR
  COMPOSER[composer.json] --> V[vendor/autoload.php]
  V --> CLASS[Class load]
  CLASS --> HOOKS[Hooks/filters]

Practical Walkthrough

Step 1: Create a composer.json (Child Theme Root)

wp-content/themes/generatepress-child/composer.json

{
  "name": "example/generatepress-child",
  "type": "wordpress-theme",
  "autoload": {
    "psr-4": {
      "GPChild\\": "src/"
    }
  },
  "require": {}
}

Step 2: Create a Namespaced Class

wp-content/themes/generatepress-child/src/Hooks/Notices.php

<?php

namespace GPChild\Hooks;

final class Notices {
    public static function register(): void {
        add_action( 'generate_before_header', array( __CLASS__, 'banner' ) );
    }

    public static function banner(): void {
        echo '<div class="gp-ns-banner">Namespaced banner</div>';
    }
}

Step 3: Include Autoload and Register Hooks

wp-content/themes/generatepress-child/functions.php

<?php

if ( file_exists( __DIR__ . '/vendor/autoload.php' ) ) {
    require_once __DIR__ . '/vendor/autoload.php';
}

if ( class_exists( '\\GPChild\\Hooks\\Notices' ) ) {
    \GPChild\Hooks\Notices::register();
}

Practical Examples

Example 1: Keep Code in src/ and Keep WP Files Clean

Structure:

generatepress-child/
  functions.php
  composer.json
  src/
    Hooks/
    Filters/

Example 2: Autoload in a Deployment Workflow

Options:

Option	Pros	Cons
Commit vendor/	Simple deploy	Larger repo
Build artifact includes vendor/	Clean repo	Needs build pipeline

Best Practices

Practice	Why
Use namespaces for anything non-trivial	Avoid collisions
Keep autoload optional (guard file_exists)	Prevents fatal errors
Keep classes small and focused	Easier debugging
Do not autoload secrets	Security

Troubleshooting

Symptom	Cause	Fix
Class not found	Autoloader missing	Ensure vendor/autoload.php exists in deploy
Fatal error on production	Composer not installed	Deploy built artifacts instead of running composer
Hooks not firing	register() not called	Confirm class exists and is invoked

Hands-On

1. Create a src/ folder and one namespaced class.
2. Wire it into functions.php with a guarded autoloader include.
3. Confirm the hook output appears and can be disabled quickly.

Quick Reference

Task	File
Namespace mapping	composer.json
Autoload include	vendor/autoload.php
Class location	src/...

What's Next

• Next: Asset Pipeline (SCSS/ESBuild/RTL)
• Related: Asset Loading