wp-widget-control: base feature (#1)

* Sidebar storage

* Widget storage

* Require support

* Wrapping up widget instance

* WIP

* WIP

* WIP

* Abstract widget instances to dto

* Remove prepend from instances

* Use generic

* Wrapping up bulk

* Adding the base features

* Finishing up

* Doc update

* Formatting

* README feedback

* CR Feedback

* Dont call save

* PHPStan improve

* CR feedback

* Remove the storage namespace

* Fixing phpstan

Author: srtfisher

CHANGELOG.md

@@ -1,7 +1,7 @@
 # Changelog
 
-All notable changes to `Create PHP Package` will be documented in this file.
+All notable changes to `WP Widget Control` will be documented in this file.
 
-## 0.1.0 - 202X-XX-XX
+## 0.1.0
 
 - Initial release

README.md

@@ -14,13 +14,175 @@ composer require alleyinteractive/wp-widget-control
 
 ## Usage
 
-Use this package like so:
+WP Widget Control lets you programmatically manage WordPress sidebars and
+widgets. This can be useful for setting up default widget configurations,
+managing widget curation with code for end to end testing, or simply
+maintaining widget state in a more structured way.
+
+When you have to manage widgets with code, WordPress doesn't provide a great way
+to do that. WP Widget Control fills this gap by providing a simple API for
+managing widgets programmatically.
+
+Here are some common usage patterns:
+
+### Retrieve a Sidebar
+
+```php
+use Alley\WP\Widget_Control\Sidebar;
+
+$sidebar = Sidebar::from( 'sidebar-1' );
+```
+
+### Append a Widget to a Sidebar
+
+```php
+use Alley\WP\Widget_Control\Sidebar;
+use Alley\WP\Widget_Control\Widget;
+
+$sidebar = Sidebar::from( 'sidebar-1' );
+
+// Append a widget by its ID:
+$sidebar->append( 'example_widget-4' );
+
+// You can create a new widget instance from the base ID and append it to the sidebar:
+$sidebar->append(
+  Widget::from( 'example_widget' )->append( [ 'content' => 'Hello, World!' ] ),
+);
+
+// Or by referencing the widget's class:
+$sidebar->append(
+  Widget::from( \My\Custom\ExampleWidget::class )->append( [ 'content' => 'Hello, World!' ] ),
+);
+
+// Save the sidebar to persist changes.
+$sidebar->save();
+```
+
+### Insert Widgets Before or After Another Widget
+
+```php
+use Alley\WP\Widget_Control\Sidebar;
+use Alley\WP\Widget_Control\Widget;
+
+$sidebar = Sidebar::from( 'sidebar-1' );
+
+// Insert a widget "block-99" before "block-2":
+$sidebar->insert_before( widget: 'block-99', before_widget_id: 'block-2' );
+
+// Insert a widget "example_widget-6" after "example_widget-2":
+$sidebar->insert_after( widget: 'example_widget-6', after_widget_id: 'example_widget-2' );
+
+// Also supports inserting a widget instance directly.
+// Inside a new widget instance before "example_widget-2":
+$sidebar->insert_before(
+	widget: Widget::from( 'example_widget' )->append( [ 'content' => 'Hello, World!' ] ),
+	before_widget_id: 'example_widget-2',
+);
+
+// Save the sidebar to persist changes.
+$sidebar->save();
+```
+
+### Remove a Widget by ID or Index
+
+```php
+use Alley\WP\Widget_Control\Sidebar;
+use Alley\WP\Widget_Control\Widget_Instance;
+
+$sidebar = Sidebar::from( 'sidebar-1' );
+
+// Remove a widget by its ID:
+$sidebar->remove( 'block-2' );
+
+// Remove a widget by its index:
+$sidebar->remove_index( 2 );
+
+// Save the sidebar to persist changes.
+$sidebar->save();
+```
+
+### Set All Widgets in a Sidebar
+
+```php
+use Alley\WP\Widget_Control\Sidebar;
+use Alley\WP\Widget_Control\Widget;
+
+$sidebar = Sidebar::from( 'sidebar-1' );
+
+$sidebar->set( [
+	// Use existing widget instances (they follow a widget_base-ID pattern).
+	'nav_menu-1',
+	'block-2',
+	'example_widget-2',
+
+	// You can also create a new widget instance and append it to the sidebar.
+	Widget::from( 'example_widget' )->append( [ 'content' => 'Hello, World!' ] ),
+	Widget::from( \My\Custom\ExampleWidget::class )->append( [ 'content' => 'Hello, World!' ] ),
+] );
+
+// Save the sidebar to persist changes.
+$sidebar->save();
+```
+
+### Filter Widgets in a Sidebar
+
+Remove a specific widget from a sidebar while keeping others:
 
 ```php
-$package = Create_PHP_Package\WP_Widget_Control\WP_Widget_Control();
-$package->perform_magic();
+use Alley\WP\Widget_Control\Sidebar;
+use Alley\WP\Widget_Control\Widget;
+use Alley\WP\Widget_Control\Widget_Instance;
+
+$sidebar = Sidebar::from( 'sidebar-1' );
+
+// Remove all widgets whose ID contains 'example_widget'.
+$sidebar->filter_by_id( function( string $widget_id ) {
+	return ! str_contains( $widget_id, 'example_widget' );
+} );
+
+// Keep only widgets of a certain type (using Widget_Instance).
+$sidebar->filter( function( Widget_Instance $widget ) {
+	return $widget->id_base === 'example_widget';
+} );
+
+// Save the sidebar to persist changes.
+$sidebar->save();
 ```
 
+### Clear All Widgets from a Sidebar
+
+```php
+use Alley\WP\Widget_Control\Sidebar;
+
+$sidebar = Sidebar::from( 'sidebar-1' );
+
+$sidebar->clear();
+
+// Save the sidebar to persist changes.
+$sidebar->save();
+```
+
+### Full Sidebar Curation Example
+
+In this example, we will set the sidebar to contain an instance of
+`ExampleWidget` and another instance of the `block` widget:
+
+```php
+use Alley\WP\Widget_Control\Sidebar;
+use Alley\WP\Widget_Control\Widget;
+use Alley\WP\Widget_Control\Tests\ExampleWidget;
+
+$sidebar->set( [
+	Widget::from( ExampleWidget::class )->append( [ 'content' => 'Hello, World! 1' ] ),
+	Widget::from( 'block' )->append( [ 'content' => 'Hello, World! 2' ] ),
+] );
+
+// Save the sidebar to persist changes.
+$sidebar->save();
+```
+
+These will be the only two widgets in the sidebar.
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
@@ -31,9 +193,9 @@ This project is actively maintained by [Alley
 Interactive](https://github.com/alleyinteractive). Like what you see? [Come work
 with us](https://alley.co/careers/).
 
-- [Sean Fisher](https://github.com/Sean Fisher)
+- [Sean Fisher](https://github.com/srtfisher)
 - [All Contributors](../../contributors)
 
 ## License
 
-The GNU General Public License (GPL) license. Please see [License File](LICENSE) for more information.
+The GNU General Public License (GPL) license. Please see [License File](LICENSE) for more information.

composer.json

@@ -16,7 +16,8 @@
     ],
     "require": {
         "php": "^8.2",
-        "alleyinteractive/composer-wordpress-autoloader": "^1.0"
+        "alleyinteractive/composer-wordpress-autoloader": "^1.0",
+        "mantle-framework/support": "^1.5"
     },
     "require-dev": {
         "alleyinteractive/alley-coding-standards": "^2.0",
@@ -31,15 +32,20 @@
         },
         "sort-packages": true
     },
+    "autoload": {
+      "files": [
+        "src/autoload.php"
+      ]
+    },
     "autoload-dev": {
         "psr-4": {
-            "Alley\\WP\\WP_Widget_Control\\Tests\\": "tests"
+            "Alley\\WP\\Widget_Control\\Tests\\": "tests"
         }
     },
     "extra": {
         "wordpress-autoloader": {
             "autoload": {
-                "Alley\\WP\\WP_Widget_Control\\": "src"
+                "Alley\\WP\\Widget_Control\\": "src"
             }
         }
     },

src/autoload.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * Helper functions for WP Widget Control.
+ *
+ * @package wp-widget-control
+ */
+
+namespace Alley\WP\Widget_Control;
+
+/**
+ * Reload the widgets available to WordPress.
+ *
+ * This is a workaround to be able to set the widgets and then use them right
+ * away in tests. This should not be used outside of tests.
+ */
+function reload_widgets(): void {
+	if ( ! defined( 'MANTLE_IS_TESTING' ) || ! MANTLE_IS_TESTING ) {
+		_doing_it_wrong(
+			__FUNCTION__,
+			'This function should only be used in tests.',
+			'1.0.0',
+		);
+	}
+
+	$GLOBALS['wp_widget_factory'] = new \WP_Widget_Factory(); // phpcs:ignore WordPress.WP.GlobalVariablesOverride
+
+	$GLOBALS['wp_registered_widgets'] = []; // phpcs:ignore WordPress.WP.GlobalVariablesOverride
+
+	wp_widgets_init();
+}