From b33d5e9f470100f79752be4d160a6a2fa2228cbb Mon Sep 17 00:00:00 2001
From: Bart Jaskulski <bjaskulski@protonmail.com>
Date: Sat, 9 Mar 2024 03:36:40 +0100
Subject: [PATCH] docs: document current configuration and prefixing process
Signed-off-by: Bart Jaskulski <bjaskulski@protonmail.com>
---
README.md | 52 ++++++----------------------------
docs/configuration.md | 66 +++++++++++++++++++++++++++++++++++++++++++
docs/legacy.md | 7 +++++
docs/prefixing.md | 36 +++++++++++++++++++++++
4 files changed, 118 insertions(+), 43 deletions(-)
create mode 100644 docs/configuration.md
create mode 100644 docs/legacy.md
create mode 100644 docs/prefixing.md
diff --git a/README.md b/README.md
index 7a7eca4..2ab2a72 100644
--- a/README.md
+++ b/README.md
@@ -39,20 +39,24 @@ Init::setup('config.php')->boot();
### Plugin configuration
-For plugin configuration, you may focus on declarative configuration.
+For plugin configuration, you may focus on succinct, declarative configuration.
-Supported configuration:
+[Supported configuration](docs/configuration.md):
```php
<?php
-// TODO: docs about possible configuration keys
return [
+ 'hook_resources_path' => 'config/hook_providers',
'services' => 'config/services.inc.php',
- 'hook_resources_path' => [],
'cache_path' => 'generated',
- 'requirements' => [],
+ 'requirements' => [
+ 'plugins' => [
+ 'name' => 'woocommerce/woocommerce.php',
+ 'nice_name' => 'WooCommerce',
+ ]
+ ],
'plugin_class_name' => 'Example\Plugin',
];
@@ -71,49 +75,11 @@ string, ready for handling by DI container:
+ $this->add_hookable( \WPDesk\Init\Provider\I18n::class );
```
-#### Target environment requirements
-
-`wp-init` also integrates with `wpdesk/wp-basic-requirements` to validate target environment and
-detect, whether your plugin can actually instantiate. With this addition, if your plugin fails
-to positively validate environment, your hooks are not triggered, and the website admin is
-provided with actionable message.
-
-```shell
-composer require wpdesk/wp-basic-requirements
-```
-
-```php
-<?php
-/**
- * Plugin Name: Example Plugin
- */
-
-use WPDesk\Init\PluginInit;
-
-require __DIR__ . '/vendor/autoload.php';
-
-Init::setup(
- [
- 'requirements' => [
- 'wp' => '6.0',
- 'php' => '7.2'
- ]
- ]
-)->boot();
-```
-
## Credits
This package is heavily inspired by Cedaro's [`wp-plugin`](https://github.com/cedaro/wp-plugin/)
and Alain Schlesser's [`basic-scaffold`](https://github.com/mwpd/basic-scaffold).
-## Roadmap
-
-~1. Add support for path based hook providers discovery similar to Symfony's [controllers resolving](https://github.com/symfony/demo/blob/3787b9f71f6bee24f1ed0718b9a808d824008776/config/routes.yaml#L15-L17)~
-1. Improve `wpdesk/wp-basic-requirements` library. This is not related directly to this project, but internals could be rewritten.
-~1. Scrap plugin data from plugin comments.~
-1. Support *bundles* of hook providers. This should be easy to extend plugin capabilities with shared functions, preserving minimal init system
-
## License
Copyright (c) 2024 WPDesk
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..145f2ee
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,66 @@
+# Configuration
+
+`wp-init` relies on declarative configuration, which encapsulates process of attaching hooks to
+WordPress life cycle and provides some additional features, like filling DI container with your
+services definitions.
+
+## `hook_resources_path`
+
+Pass a path to the file/directory with your hook actions. Configuration accepts any valid path
+string, relative or absolute, either `hook_providers` or `__DIR__ . '/hook_providers/plugins_loaded.php'`
+
+Files are mapped to hooks by name, so `woocommerce_init.php` is registered inside `woocommerce_init`
+action. The exception is `index.php` file which is flushed immediately.
+
+Example of a hook resource content:
+
+```php
+<?php
+// plugins_loaded.php
+
+return [
+ MyCoolTitleChanger::class,
+ AnotherHookAction::class,
+ function ( Dependency $dep ) {
+ // You can even use a closure, to execute simple actions.
+ // Arguments are injected by DI container.
+ $dep->one_off_action();
+ },
+ function ( Migarator $migrator ) {
+ $migrator->migrate();
+ }
+];
+```
+
+## `services`
+
+As you add more services with increasing complexity, you will need to provide some kind of
+definitions for a DI container to create objects. Pass a path to a file, which will hold such
+definitions. Refer to [php-di documentation](https://php-di.org/doc/definitions.html) for more
+information on such file content.
+
+> Warning
+> If you are using _shortcut_ functions from `php-di/php-di` (e.g. `DI\autowire`, `DI\create`), you
+> must load them first. Add `require __DIR__ . '/vendor_prefixed/php-di/php-di/src/functions.php';`
+> to your plugin file.
+
+## `cache_path`
+
+Plugin header data and compiled DI container is cached in a directory specified by this
+setting. Defaults to `generated`.
+
+## `requirements`
+
+**This setting only works when `wpdesk/wp-basic-requirements` is installed.**
+
+Enables your plugin to check an environment requirement before instantiation, e.g. PHP version or
+active plugins. Refer to [wp-basic-requirements documentation](https: //gitlab.wpdesk.dev/wpdesk/wp-basic-requirements)
+for more information on setting structure.
+
+## `plugin_class_name`
+
+**This setting only works when `wpdesk/wp-builder` is installed.**
+
+When a plugin is used in [legacy mode](legacy.md), `plugin_class_name` is used to create an instance
+of main plugin class. This setting is required to enable legacy mode. Despite that,
+`WPDesk\Init\Plugin\Plugin` is still accessible to your services.
diff --git a/docs/legacy.md b/docs/legacy.md
new file mode 100644
index 0000000..bab5e4a
--- /dev/null
+++ b/docs/legacy.md
@@ -0,0 +1,7 @@
+# Migration from `wpdesk/wp-builder`
+
+Projects using `wpdesk/wp-builder` (or `wpdesk/wp-plugin-flow`) may easily migrate to `wp-init`
+in a few steps:
+
+1. Install `wpdesk/wp-init`.
+1.
diff --git a/docs/prefixing.md b/docs/prefixing.md
new file mode 100644
index 0000000..acceec0
--- /dev/null
+++ b/docs/prefixing.md
@@ -0,0 +1,36 @@
+# Prefixing `wp-init` with `php-scoper`
+
+When developing plugins, it's worth to prefix all dependencies to avoid version collision between
+different plugins loaded during runtime. For this library to enable prefixing you will need to
+introduce following configuration to your `scoper.inc.php` file.
+
+- Whitelist `vendor/php-di/php-di/src/Compiler/Template.php`
+- Include `php-di` and it's dependencies in finders
+
+> Note
+> Pay attention to actual installed `php-di/php-di` version, as it's dependencies may change,
+> requiring to update `scoper.inc.php` accordingly.
+
+## Example configuration
+
+**`php-di/php-di` up to 6.3.5**
+
+```php
+return [
+ 'finder' => Finder::create()->in(['vendor/wpdesk/wp-init', 'vendor/php-di', 'vendor/opis/closure']),
+ 'files-whitelist' => [
+ 'vendor/php-di/php-di/src/Compiler/Template.php'
+ ],
+];
+```
+
+**`php-di/php-di` since 6.4.0**
+
+```php
+return [
+ 'finder' => Finder::create()->in(['vendor/wpdesk/wp-init', 'vendor/php-di', 'vendor/laravel/serializable-closure']),
+ 'files-whitelist' => [
+ 'vendor/php-di/php-di/src/Compiler/Template.php'
+ ],
+];
+```
--
GitLab