Skip to content
Snippets Groups Projects
Verified Commit b33d5e9f authored by Bartek Jaskulski's avatar Bartek Jaskulski
Browse files

docs: document current configuration and prefixing process

parent 97dfd42e
Branches
Tags
2 merge requests!3improve into wp-hook and some additional unfinished things,!21.x
...@@ -39,20 +39,24 @@ Init::setup('config.php')->boot(); ...@@ -39,20 +39,24 @@ Init::setup('config.php')->boot();
### Plugin configuration ### 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
<?php <?php
// TODO: docs about possible configuration keys
return [ return [
'hook_resources_path' => 'config/hook_providers',
'services' => 'config/services.inc.php', 'services' => 'config/services.inc.php',
'hook_resources_path' => [],
'cache_path' => 'generated', 'cache_path' => 'generated',
'requirements' => [], 'requirements' => [
'plugins' => [
'name' => 'woocommerce/woocommerce.php',
'nice_name' => 'WooCommerce',
]
],
'plugin_class_name' => 'Example\Plugin', 'plugin_class_name' => 'Example\Plugin',
]; ];
...@@ -71,49 +75,11 @@ string, ready for handling by DI container: ...@@ -71,49 +75,11 @@ string, ready for handling by DI container:
+ $this->add_hookable( \WPDesk\Init\Provider\I18n::class ); + $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 ## Credits
This package is heavily inspired by Cedaro's [`wp-plugin`](https://github.com/cedaro/wp-plugin/) 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). 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 ## License
Copyright (c) 2024 WPDesk Copyright (c) 2024 WPDesk
......
# 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.
# 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.
# 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'
],
];
```
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment