Feature/scaffold plugin structure issue 24 #38

Ref34t · 2025-10-07T11:55:49Z

Scaffold Initial Plugin Structure

Implements #24 – Foundational plugin structure for the WordPress AI Experiments plugin.

Overview

This work delivers the core architecture for a modular, feature-based AI plugin. Features can be
registered, toggled, and tested in isolation, and the repository now follows the conventions we’ll
reuse as we add more experiments.

What’s Included

Core Architecture

Plugin bootstrap (ai.php) – WordPress headers, version guards (PHP 7.4+, WP 6.7+), and
initialization wiring.
Feature system – Registry refactored around a reusable Feature_Collection, maintaining enable/
disable logic and conditional feature support.
PSR-4 autoloading – Composer-managed namespaces for WordPress\AI core code and feature modules.
Interface-driven design – Feature and Conditional_Feature interfaces ensure every experiment
exposes the same surface.

Plugin Structure

ai/
├── ai.php
├── includes/
│ ├── Plugin.php
│ ├── Feature_Collection.php
│ ├── Feature_Registry.php
│ ├── Interfaces/
│ └── Abstracts/
├── features/
│ └── Example_Feature/
├── tests/
│ ├── bootstrap.php
│ ├── Integration/
│ │ ├── Features/
│ │ └── Includes/
│ └── Unit/
│ └── Includes/
├── docs/
│ ├── CONTRIBUTING.md
│ └── TESTING.md
├── phpcs.xml.dist
└── phpunit.xml.dist

Development Infrastructure

WordPress Coding Standards (PHPCS) plus PHPCompatibility checks.
Testing – PHPUnit configuration, bootstrap wiring, and refreshed integration/unit suites in PSR-
4 directories.
Static analysis – PHPStan bootstrap and composer stan script with lightweight WordPress stubs.
Composer scripts – composer lint, composer format, composer stan, composer test.

Documentation

docs/CONTRIBUTING.md – Expanded developer guide covering setup, feature creation, testing, and
contribution workflow.
docs/TESTING.md – Updated strategy with new test locations and commands.
README – Points to the new docs and outlines the development experience.

Key Features

Encapsulation

Every experiment lives under its own directory in features/, making reviews, toggles, and
migrations painless.

Extensibility

Third-party developers can add custom features by hooking into the registry:

  add_action( 'ai_register_features', function ( $registry ) {
      $registry->register_feature( new My_Custom_Feature() );
  } );

Feature Control

Features remain fully overridable:

  add_filter( 'ai_feature_enabled', function ( $enabled, $feature_id ) {
      return 'example-feature' === $feature_id ? false : $enabled;
  }, 10, 2 );

jeffpaul · 2025-10-07T20:03:43Z

@Ref34t thanks for picking up #24 and working on this PR! I see that the PR is still in draft, so is there more work you have pending or should this be considered ready for review?

Ref34t · 2025-10-08T11:09:03Z

@jeffpaul you're welcome. I'll assign it for review today after I finish my iteration on it.

github-actions · 2025-10-08T15:09:26Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @mohamed.khaled@9hdigital.com.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: mohamed.khaled@9hdigital.com.

Co-authored-by: Ref34t <mokhaled@git.wordpress.org>
Co-authored-by: felixarntz <flixos90@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: swissspidy <swissspidy@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: mindctrl <mindctrl@git.wordpress.org>
Co-authored-by: justlevine <justlevine@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Ref34t · 2025-10-08T15:09:32Z

@jeffpaul it's ready now

felixarntz

@Ref34t Thank you for kick-starting this! I think a lot of it goes in the right direction, but a few pieces seem overly complicated or catering for theoretical problems that we don't know are relevant.

I encourage you to simplify the PR according to my feedback and break out all the documentation into separate PRs to streamline the review process and decouple documentation and marketing language from source code.

ai.php

docs/CONTRIBUTING.md

includes/Abstracts/Abstract_Feature.php

includes/Feature_Collection.php

includes/Plugin.php

languages/readme.txt

phpstan.neon.dist

felixarntz · 2025-10-09T22:52:05Z

readme.txt

@@ -0,0 +1,89 @@
+=== AI Experiments ===


See above, adding the readme.txt should be its own PR, also as it requires a completely different expertise to review.

Note that I added the readme.txt file as some changes were made to README.md that are more properly formatted for the WPORG txt version. Happy to strip that out and roll into a separate PR if helpful.

…ss#24)

felixarntz

@Ref34t Getting close!

My last remaining concern is to make the feature abstraction a bit easier and also more error-proof to use.

includes/Features/Example_Feature/Example_Feature.php

includes/Abstracts/Abstract_Feature.php

tests/Integration/Includes/Feature_LoaderTest.php

- Add Invalid_Feature_Exception and Invalid_Feature_Metadata_Exception classes - Implement validate_feature method in Abstract_Feature with metadata checks - Refactor Feature_Loader to use new exceptions and validation - Update bootstrap to handle exceptions with user-friendly notices - Add comprehensive test coverage for validation scenarios

Ref34t · 2025-10-16T11:17:13Z

@felixarntz I've pushed a new commit covering the points you mentioned yesterday with some improvements over them. Here is what this last iteration does:

Introducing a comprehensive validation system for the plugin's feature architecture, ensuring all features have valid metadata before they can be loaded. The changes centralize metadata management in the Abstract_Feature base class and add proper exception handling throughout the feature loading pipeline.

Summary of Changes

New Exception Classes

Invalid_Feature_Exception - for invalid feature instances
Invalid_Feature_Metadata_Exception - for missing/invalid metadata

Abstract_Feature

Added final __construct() that validates and assigns metadata (id, label, description)
Added abstract load_feature_metadata() method that child classes must implement
Changed $enabled from protected to private
Made is_enabled() final

Feature_Loader

Wrapped feature loading in try-catch to handle validation exceptions
Returns WP_Error when features fail validation

Example_Feature

Implemented load_feature_metadata() returning feature metadata array
Removed direct property assignments (now handled by parent constructor)

bootstrap.php

Added exception handling that displays admin notices when Features fail to load

dkotter

Thanks for all the work here @Ref34t! Overall this looks good to me, noting I'd expect there to be some changes as we actually start building things out but I feel this is a good base to start with

jeffpaul · 2025-10-17T23:46:26Z

@dkotter I'll defer to you on merge order here between this and #46 to minimize conflicts

includes/Abstracts/Abstract_Feature.php

Move the master enable/disable hook to the `Feature_Loader` to act as a global "master switch" and simplify the `Abstract_Feature` class. This improves separation of concerns and clarifies the roles of the classes.

dkotter · 2025-10-21T14:29:56Z

@dkotter I'll defer to you on merge order here between this and #46 to minimize conflicts

I would merge this one in first as it contains all the scaffold work. And then I can rebase #46 to fix conflicts

felixarntz

@Ref34t Thank you for the iterations, LGTM!

Just one minor thing that we can fix inline.

includes/Abstracts/Abstract_Feature.php

felixarntz · 2025-10-21T15:00:06Z

@jeffpaul @dkotter @Ref34t Happy for this to be merged! I agree it should probably be merged before #46.

mindctrl · 2025-10-22T01:30:47Z

I'm seeing a PHP notice due to translations being loaded too early.

PHP Notice: Function _load_textdomain_just_in_time was called incorrectly. Translation loading for the ai domain was triggered too early. This is usually an indicator for some code in the plugin or theme running too early. Translations should be loaded at the init action or later. Please see Debugging in WordPress for more information. (This message was added in version 6.7.0.)

This happens when WordPress\AI\load(), which runs on plugins_loaded, registers the Example Feature and ends up running __() in Example_Feature::load_feature_metadata().

Maybe the feature initialization could be deferred to the init hook?

includes/Feature_Loader.php

felixarntz · 2025-10-22T01:45:24Z

includes/bootstrap.php

+	try {
+		$registry = new Feature_Registry();
+		$loader   = new Feature_Loader( $registry );
+		$loader->register_default_features();
+		$loader->initialize_features();
+	} catch ( \Exception $e ) {
+		_doing_it_wrong(
+			__NAMESPACE__ . '\load',
+			sprintf(
+				/* translators: %s: Error message. */
+				esc_html__( 'AI Plugin initialization failed: %s', 'ai' ),
+				esc_html( $e->getMessage() )
+			),
+			'0.1.0'
+		);
+	}


+1 in regards to @mindctrl's comment, this should probably only happen on init:

Only before init the user gets initialized by default, and that influences translation strings. It's a best practice to not run any translation functions before the user is normally initialized.

It's common in WordPress for things to be registered on init, so this would tie in nicely with that practice.

It would enforce that no feature can break these patterns either. init is sufficiently early in the WordPress bootstrap process for probably any kind of interaction a specific feature may need to support.

@felixarntz I went with John's approach, is this satisfying for you? 65139be

better readibility Co-authored-by: Felix Arntz <flixos90@gmail.com>

includes/bootstrap.php

mindctrl · 2025-10-22T18:08:33Z

includes/bootstrap.php

+ * @return bool True if PHP version is sufficient, false otherwise.
+ */
+function check_php_version(): bool {
+	if ( version_compare( phpversion(), AI_MIN_PHP_VERSION, '<' ) ) {


A small thing but when testing this PR against WP 6.9-beta1, using this constant set to 6.9 causes the plugin to show an admin notice and stops the bootstrap process.

AI plugin requires WordPress version 6.9 or higher. You are running WordPress version 6.9-beta1-61040-src.

I had to edit the value to make the plugin work during beta testing. Of course it's only a temporary inconvenience, but it made me wonder if we should use a different way, like checking if the wp_register_ability() function exists. Thoughts?

@mindctrl I went with using a lower version for now until the release of 6.9, we can pump it up then

includes/Features/Example_Feature/Example_Feature.php

Move feature initialization from plugins_loaded to init hook by extracting the try/catch block into initialize_features() function. This allows the plugin to bootstrap dependencies on plugins_loaded for early access by integrations, while features initialize at the appropriate init timing.

Remove the $features parameter from register_default_features() method. This method should only register built-in default features. Custom features should use the ai_register_features action hook instead.

Change AI_MIN_WP_VERSION from 6.9 to 6.8 to allow the plugin to work with WordPress 6.9-beta1. Version comparison treats 6.9-beta1 as less than 6.9, preventing the plugin from loading during testing.

Add isset() check before accessing title['site'] to prevent PHP warning on front page where WordPress doesn't set the site key when is_front_page() returns true.

jeffpaul added this to the 0.1.0 milestone Oct 7, 2025

jeffpaul self-requested a review October 7, 2025 20:02

jeffpaul assigned Ref34t Oct 7, 2025

jeffpaul linked an issue Oct 7, 2025 that may be closed by this pull request

Scaffold the initial plugin structure #24

Closed

7 tasks

Ref34t marked this pull request as ready for review October 8, 2025 15:09

jeffpaul requested review from Jameswlepage, felixarntz and swissspidy October 9, 2025 19:53

felixarntz requested changes Oct 9, 2025

View reviewed changes

Mohamed Khaled added 12 commits October 12, 2025 13:55

Build foundational plugin structure for AI experiments (issue WordPre…

2b02ee8

…ss#24)

Fix WordPress.org plugin check compliance issues

11cbb0f

improve example feature

4adfdb6

improve example feature

07ed443

Tests: Remove test_load_textdomain()

9f3ad4f

Refactor: relocate example feature

41109a1

clean documentation

f629a25

Refactor: Organize test directory and fix autoloader issues

a811108

Refactor feature registry around a shared collection

babd739

Reorganize test suites and refresh contributor docs

83e9417

Add PHPStan static analysis tooling

b850515

Remove unnecessary activation and deactivation hooks

99fe2cb

Ref34t force-pushed the feature/scaffold-plugin-structure-issue-24 branch from eee2a66 to 99fe2cb Compare October 12, 2025 11:04

Mohamed Khaled added 4 commits October 12, 2025 14:06

Remove documentation files from feature branch

7926793

Add dynamic feature-specific enabled filter

29959e4

Remove unnecessary hook wrapper methods

3c920d1

Rename test file to match class naming convention

298e4b0

jeffpaul requested a review from dkotter October 15, 2025 17:35

felixarntz reviewed Oct 15, 2025

View reviewed changes

Ref34t requested a review from felixarntz October 16, 2025 11:17

dkotter mentioned this pull request Oct 16, 2025

Add new GitHub Action workflows to support WordPress Playground previews #46

Merged

dkotter approved these changes Oct 16, 2025

View reviewed changes

mindctrl reviewed Oct 18, 2025

View reviewed changes

includes/Abstracts/Abstract_Feature.php Outdated Show resolved Hide resolved

Refactor: Centralize feature enabling logic

bb89550

Move the master enable/disable hook to the `Feature_Loader` to act as a global "master switch" and simplify the `Abstract_Feature` class. This improves separation of concerns and clarifies the roles of the classes.

felixarntz approved these changes Oct 21, 2025

View reviewed changes

includes/Abstracts/Abstract_Feature.php Outdated Show resolved Hide resolved

Sanitize filter results.

e8d3ae0

felixarntz reviewed Oct 22, 2025

View reviewed changes

Update includes/Feature_Loader.php

0f4b86d

better readibility Co-authored-by: Felix Arntz <flixos90@gmail.com>

mindctrl reviewed Oct 22, 2025

View reviewed changes

includes/bootstrap.php Outdated Show resolved Hide resolved

mindctrl reviewed Oct 22, 2025

View reviewed changes

justlevine self-requested a review October 22, 2025 21:06

mindctrl reviewed Oct 23, 2025

View reviewed changes

includes/Features/Example_Feature/Example_Feature.php Show resolved Hide resolved

Mohamed Khaled added 4 commits October 23, 2025 08:39

Remove unnecessary parameter from register_default_features

90579ca

Remove the $features parameter from register_default_features() method. This method should only register built-in default features. Custom features should use the ai_register_features action hook instead.

Lower minimum WordPress version to 6.8

aad56c5

Change AI_MIN_WP_VERSION from 6.9 to 6.8 to allow the plugin to work with WordPress 6.9-beta1. Version comparison treats 6.9-beta1 as less than 6.9, preventing the plugin from loading during testing.

Fix undefined array key warning in Example_Feature

721d8a1

Add isset() check before accessing title['site'] to prevent PHP warning on front page where WordPress doesn't set the site key when is_front_page() returns true.

Ref34t requested review from dkotter, felixarntz and mindctrl October 23, 2025 05:52

dkotter approved these changes Oct 23, 2025

View reviewed changes

jeffpaul merged commit 188281c into WordPress:trunk Oct 23, 2025
4 checks passed

Feature/scaffold plugin structure issue 24 #38

Feature/scaffold plugin structure issue 24 #38

Uh oh!

Conversation

Ref34t commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Scaffold Initial Plugin Structure

Overview

What’s Included

Core Architecture

Plugin Structure

Development Infrastructure

Documentation

Key Features

Encapsulation

Extensibility

Feature Control

Uh oh!

jeffpaul commented Oct 7, 2025

Uh oh!

Ref34t commented Oct 8, 2025

Uh oh!

github-actions bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

Ref34t commented Oct 8, 2025

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixarntz Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

jeffpaul Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ref34t commented Oct 16, 2025

Summary of Changes

New Exception Classes

Abstract_Feature

Feature_Loader

Example_Feature

bootstrap.php

Uh oh!

dkotter left a comment

Choose a reason for hiding this comment

Uh oh!

jeffpaul commented Oct 17, 2025

Uh oh!

Uh oh!

dkotter commented Oct 21, 2025

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixarntz commented Oct 21, 2025

Uh oh!

mindctrl commented Oct 22, 2025

Uh oh!

Uh oh!

Uh oh!

felixarntz Oct 22, 2025

Ref34t commented Oct 7, 2025 •

edited

Loading

github-actions bot commented Oct 8, 2025 •

edited

Loading

Ref34t Oct 23, 2025 •

edited

Loading