From 41d1ebf6b64772aea485caeaa6146b0480766e88 Mon Sep 17 00:00:00 2001
From: matapatos <andre_gil22@hotmail.com>
Date: Wed, 20 Nov 2024 14:43:04 +0000
Subject: [PATCH] docs: Add page regarding plugins as dependencies

---
 README.md                                     |  1 +
 .../dependency-injection.md                   |  1 -
 .../plugins-as-dependencies.md                | 91 +++++++++++++++++++
 docs/docs/index.md                            |  1 +
 docs/mkdocs.yml                               |  1 +
 5 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/advanced-user-guide/plugins-as-dependencies.md

diff --git a/README.md b/README.md
index 530dce6..51a9bf3 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@
 - IDE auto completion support
 - No magic router. It uses WordPress [`register_rest_route`](https://developer.wordpress.org/reference/functions/register_rest_route/)
 - Support for newer JSON schema drafts thanks to [opis/json-schema](https://opis.io/json-schema/2.x/)
+- Able to treat plugins as dependencies via [WP-FastEndpoints Depends](https://github.com/matapatos/wp-fastendpoints-depends)
 
 ## Requirements
 
diff --git a/docs/docs/advanced-user-guide/dependency-injection.md b/docs/docs/advanced-user-guide/dependency-injection.md
index 05079ba..f476d60 100644
--- a/docs/docs/advanced-user-guide/dependency-injection.md
+++ b/docs/docs/advanced-user-guide/dependency-injection.md
@@ -34,4 +34,3 @@ With dependency injection our endpoints do look much cleaner ✨🧹
         return $allPosts ? $allPosts[array_rand($allPosts)] : new WpError(404, 'No posts found');
     });
     ```
-
diff --git a/docs/docs/advanced-user-guide/plugins-as-dependencies.md b/docs/docs/advanced-user-guide/plugins-as-dependencies.md
new file mode 100644
index 0000000..1033f08
--- /dev/null
+++ b/docs/docs/advanced-user-guide/plugins-as-dependencies.md
@@ -0,0 +1,91 @@
+One of the main strengths of WordPress is the wide range of plugins available
+which allow us to fully customise a website in a short time period. However, every time a plugin
+is added it can negatively impact the performance of our API endpoints, because even
+though those endpoints might not need some of the activated plugins to work properly, they will
+still be loaded.
+
+To address this issue [WP-FastEndpoints Depends](https://github.com/matapatos/wp-fastendpoints-depends)
+was created to enable us to treat plugins as REST endpoint dependencies.
+
+## Adding another plugin?? 😱
+
+Yes, this is a plugin! It could seem counterintuitive that adding another plugin could
+positively impact our API endpoints. However, given that in most cases our API
+endpoints don't need all the plugins that are active e.g. BuddyPress, Elementor
+it can actually improve your API endpoints.
+
+## How it works?
+
+Given this plugin needs to be setup as a MU-plugin it will always run before any regular plugin
+which allow us to decide which plugins are necessary for a given REST endpoint before loading them.
+
+## How to use it?
+
+Currently, we support both native WP endpoints and FastEndpoints 😊
+
+=== "With FastEndpoints"
+
+    ```php
+    $router->get('/example/all-plugins', function () {
+        return "Loads all active plugins";
+    });
+
+    $router->get('/example/buddypress', function () {
+        return "Only MyPlugin and BuddyPress plugins are loaded"; 
+    })->depends(['my-plugin', 'buddypress']);
+    ```
+
+=== "Native WP endpoints"
+
+    ```php
+    // Loads all active plugins
+    register_rest_route('native/v1', 'example/all-plugins', [
+        'methods' => 'GET',
+        (...)
+    ]);
+
+    // Only MyPlugin and BuddyPress plugins are loaded
+    register_rest_route('native/v1', 'example/buddypress', [
+        'methods' => 'GET',
+        'depends' => ['my-plugin', 'buddypress'],
+        (...)
+    ]);
+    ```
+
+???+ tip
+    By default, if no dependencies are specified in an endpoint it assumes that all active plugins needs
+    to be loaded. This behaviour could be overridden for a given set of WP-FastEndpoint's by setting
+    router dependencies e.g. `$router->depends(['my-plugin'])`
+
+### Router vs Endpoint dependencies
+
+With WP-FastEndpoint's we are able to either define _global_ endpoint dependencies via router dependencies
+or specific endpoint dependencies.
+
+One common scenario where router dependencies might be useful is when we want to change the default behaviour
+of loading all active plugins per endpoint.
+
+```php
+$router = new \Wp\FastEndpoints\Router('my-api', 'v1');
+$router->depends(['my-plugin']); // All endpoints and sub-routers would have this dependency
+```
+
+!!! danger
+    When adding dependencies to endpoints, make sure to at least include the given plugin that holds those endpoints.
+    For instance, if your endpoints reside inside a plugin with a slug `my-plugin` you have to set the dependencies
+    to `['my-plugin']` otherwise when a request is received for that endpoint `my-plugin` will not be loaded.
+
+### Endpoint dependencies up-to-date
+
+Under the hood, this plugin generates a config file with all the route dependencies (see [example](https://github.com/matapatos/wp-fastendpoints-depends/blob/main/tests/Data/config.php)).
+To have the most up-to-date endpoint dependencies, make sure to either:
+
+- run the `wp fastendpoints depends` command or 
+- activate any plugin on the website - this also triggers the re-generation of the route dependencies
+
+## Useful constants
+
+- **FASTENDPOINTS_DEPENDS_ENABLED** - If set to false, always loads all active plugins. **Useful for local development**  
+- **FASTENDPOINTS_DEPENDS_CONFIG_FILEPATH** - Overrides dependencies config file path
+- **FASTENDPOINTS_DEPENDS_REFRESH_ON_PLUGIN_ACTIVATION** - If set to false, disables re-generating endpoint dependencies
+when any plugin is activated
diff --git a/docs/docs/index.md b/docs/docs/index.md
index d8546d3..9ef265c 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -23,6 +23,7 @@ hide:
 - IDE auto completion support
 - No magic router. It uses WordPress [`register_rest_route`](https://developer.wordpress.org/reference/functions/register_rest_route/)
 - Support for newer JSON schema drafts thanks to [opis/json-schema](https://opis.io/json-schema/2.x/)
+- Able to treat plugins as dependencies via [WP-FastEndpoints Depends](https://github.com/matapatos/wp-fastendpoints-depends)
 
 ## Requirements
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index f90ccf8..82fdff7 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -62,6 +62,7 @@ nav:
       - Multiple Root Dirs: advanced-user-guide/json-schemas/multiple-root-dirs.md
       - Validator: advanced-user-guide/json-schemas/validator.md
       - References: advanced-user-guide/json-schemas/references.md
+    - Treat plugins as dependencies: advanced-user-guide/plugins-as-dependencies.md
   - Release Notes: release.md
 extra:
   social: