Power-Based Class Overriding & Source Injection

[Llewellynvdm]

One of the most powerful additions is the ability to use Powers to override or inject PHP classes directly into the generated src/ folders of Components, Modules, and Plugins.

This is not guesswork, magic, or a loose convention — it is fully deterministic, namespace-driven, and designed to be portable across projects.

This section explains exactly how it works, with concrete examples.

---

Core Concept: Namespace = Destination

JCB determines where a Power class is placed (and whether it overrides an existing generated class) purely from its namespace.

There are two key ideas:

1. The namespace determines the extension type and location
2. Dot notation determines folder structure and class name

If a Power resolves to the same namespace + class name as a generated class, it overrides it.
If it resolves to a new namespace + class name, it adds a new file.

---

Dynamic Placeholders (Critical for Reusability)

JCB supports dynamic placeholders inside Power namespaces so that the same Power can be reused across multiple projects without modification.

Available placeholders

• [[[NamespacePrefix]]]
  → Dynamically replaced with the project’s namespace prefix

• [[[ComponentNamespace]]]
  → Dynamically replaced with the project’s component namespace

• [[[Componment]]]
  → Dynamically replaced with the project’s component name

These placeholders allow a Power to adapt itself automatically when used in different components, modules, or projects.

---

Component Examples

Override an existing generated Component class

To override the generated file:

src/Extension/ComponentbuilderComponent.php

Use this Power namespace:

[[[NamespacePrefix]]]\Component\[[[ComponentNamespace]]]\Administrator\Extension.[[[Componment]]]Component

What happens:

• JCB resolves the placeholders
• The namespace exactly matches the generated class
• The Power replaces the generated ComponentbuilderComponent.php file
• Your version is used instead of the generated one

This is a true override, not a hook or decoration.

---

Add a new file to the Component Administrator src area

[[[NamespacePrefix]]]\Component\[[[ComponentNamespace]]]\Administrator\MyFolder.MyOwnClass

Resulting file path:

src/MyFolder/MyOwnClass.php

No generated class is replaced — this file is added to the component admin src/ tree.

---

Add a new file to the Component Site src area

[[[NamespacePrefix]]]\Component\[[[ComponentNamespace]]]\Site\MyFolder.MyOwnClass

Resulting file path:

site/src/MyFolder/MyOwnClass.php

Again, this is a clean addition, not an override.

---

Module Examples

Override a Module Dispatcher

To override the generated module file:

src/Dispatcher/Dispatcher.php

Use this Power namespace:

[[[NamespacePrefix]]]\Module\CPanelRedirect\Administrator\Dispatcher.Dispatcher

Where:

• CPanelRedirect must be your module name

Effect:

• The generated dispatcher is replaced
• Your Power class becomes the active dispatcher

---

Add a file to the Module Administrator src area

[[[NamespacePrefix]]]\Module\CPanelRedirect\Administrator\MyFolder.MyOwnClass

Result:

src/MyFolder/MyOwnClass.php

---

Add a file to the Module Site src area

[[[NamespacePrefix]]]\Module\CPanelRedirect\Site\MyFolder.MyOwnClass

Result:

site/src/MyFolder/MyOwnClass.php

---

Plugin Examples

Override an existing Plugin class

To override the generated plugin file:

src/Extension/ComponentbuilderPowersAutoloaderCompiler.php

Use this Power namespace:

[[[NamespacePrefix]]]\Plugin\Extension\ComponentbuilderPowersAutoloaderCompiler\Extension.ComponentbuilderPowersAutoloaderCompiler

Where:

• ComponentbuilderPowersAutoloaderCompiler is the plugin name

Outcome:

• The generated plugin extension class is overridden
• Your Power class replaces it completely

---

Add a new file to the Plugin src area

[[[NamespacePrefix]]]\Plugin\Extension\ComponentbuilderPowersAutoloaderCompiler\MyFolder.MyOwnClass

Result:

src/MyFolder/MyOwnClass.php

---

Dot Notation Explained (Why It Works)

JCB uses dot notation inside the namespace to determine:

• The class name → everything after the last dot
• The folder structure → everything before the last dot

Example:

MyFolder.SubFolder.MyClass

Becomes:

MyFolder/SubFolder/MyClass.php

This applies consistently across Components, Modules, and Plugins.

---

Using the Class in Your Code (JPK Integration)

Once the Power is placed into the correct src/ location, you can:

• Reference it using the JPK key
• Use it inside custom code areas
• Treat it like any native class in your extension

JCB automatically ensures the class is available and loaded.

---

Important Trade-Offs (By Design)

This feature intentionally gives you full control, which means:

• If you override a generated class, you own it

• JCB will not regenerate that class unless you remove the Power

• This is ideal for:

  • Advanced customization
  • Manual architecture control
  • Long-term maintenance strategies

It is optional, explicit, and never forced.

---

Why This Matters

This turns Powers into:

• A source-level extension mechanism
• A safe override system
• A portable, reusable class injection tool

You can now:

• Maintain critical classes manually
• Share advanced logic across projects
• Extend or replace generated code cleanly
• Do all of this without hacks or post-build scripts