From 2e8c1e572615604064eb156042160bbd9797cd90 Mon Sep 17 00:00:00 2001
From: matapatos <andre_gil22@hotmail.com>
Date: Wed, 20 Nov 2024 15:24:03 +0000
Subject: [PATCH] Deployed 7278be3 with MkDocs version: 1.6.0

---
 .../plugins-as-dependencies/index.html        | 36 +++++++++----------
 search/search_index.json                      |  2 +-
 2 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/advanced-user-guide/plugins-as-dependencies/index.html b/advanced-user-guide/plugins-as-dependencies/index.html
index d67b98d..1f01f07 100644
--- a/advanced-user-guide/plugins-as-dependencies/index.html
+++ b/advanced-user-guide/plugins-as-dependencies/index.html
@@ -929,26 +929,26 @@
 </li>
         
           <li class="md-nav__item">
-  <a href="#endpoint-dependencies-config" class="md-nav__link">
+  <a href="#endpoint-dependencies-up-to-date" class="md-nav__link">
     <span class="md-ellipsis">
-      Endpoint dependencies config
+      Endpoint dependencies up-to-date
     </span>
   </a>
   
 </li>
         
-          <li class="md-nav__item">
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
   <a href="#useful-constants" class="md-nav__link">
     <span class="md-ellipsis">
       Useful constants
     </span>
   </a>
   
-</li>
-        
-      </ul>
-    </nav>
-  
 </li>
       
     </ul>
@@ -1049,26 +1049,26 @@
 </li>
         
           <li class="md-nav__item">
-  <a href="#endpoint-dependencies-config" class="md-nav__link">
+  <a href="#endpoint-dependencies-up-to-date" class="md-nav__link">
     <span class="md-ellipsis">
-      Endpoint dependencies config
+      Endpoint dependencies up-to-date
     </span>
   </a>
   
 </li>
         
-          <li class="md-nav__item">
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
   <a href="#useful-constants" class="md-nav__link">
     <span class="md-ellipsis">
       Useful constants
     </span>
   </a>
   
-</li>
-        
-      </ul>
-    </nav>
-  
 </li>
       
     </ul>
@@ -1154,14 +1154,14 @@ <h3 id="router-vs-endpoint-dependencies">Router vs Endpoint dependencies</h3>
 For instance, if your endpoints reside inside a plugin with a slug <code>my-plugin</code> you have to set the dependencies
 to <code>['my-plugin']</code> otherwise when a request is received for that endpoint <code>my-plugin</code> will not be loaded.</p>
 </div>
-<h3 id="endpoint-dependencies-config">Endpoint dependencies config</h3>
+<h3 id="endpoint-dependencies-up-to-date">Endpoint dependencies up-to-date</h3>
 <p>Under the hood, this plugin generates a config file with all the route dependencies (see <a href="https://github.com/matapatos/wp-fastendpoints-depends/blob/main/tests/Data/config.php">example</a>).
 To have the most up-to-date endpoint dependencies, make sure to either:</p>
 <ul>
 <li>run the <code>wp fastendpoints depends</code> command or </li>
 <li>activate any plugin on the website - this also triggers the re-generation of the route dependencies</li>
 </ul>
-<h3 id="useful-constants">Useful constants</h3>
+<h2 id="useful-constants">Useful constants</h2>
 <ul>
 <li><strong>FASTENDPOINTS_DEPENDS_ENABLED</strong> - If set to false always loads all active plugins. <strong>Useful for local development</strong>  </li>
 <li><strong>FASTENDPOINTS_DEPENDS_CONFIG_FILEPATH</strong> - Overrides dependencies config file path</li>
diff --git a/search/search_index.json b/search/search_index.json
index 0f419ba..a5a8695 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"WP-FastEndpoints","text":"<p>FastEndpoints is an elegant way of writing custom WordPress REST endpoints with a focus on readability and IDE auto completion support.</p>"},{"location":"#features","title":"Features","text":"<ul> <li>Decouples request validation from main logic</li> <li>Removes unwanted fields from responses</li> <li>Middlewares support</li> <li>IDE auto completion support</li> <li>No magic router. It uses WordPress <code>register_rest_route</code></li> <li>Support for newer JSON schema drafts thanks to opis/json-schema</li> <li>Able to treat plugins as dependencies via WP-FastEndpoints Depends</li> </ul>"},{"location":"#requirements","title":"Requirements","text":"<ul> <li>PHP 8.1+</li> <li>WordPress 6.x</li> <li>opis/json-schema</li> <li>php-di/invoker</li> </ul> <p>We aim to support versions that haven't reached their end-of-life.</p>"},{"location":"#installation","title":"Installation","text":"<pre><code>composer require wp-fastendpoints</code></pre>"},{"location":"#sponsors","title":"Sponsors","text":""},{"location":"release/","title":"Release Notes","text":""},{"location":"release/#v200","title":"v2.0.0","text":"<p>Support for treating plugins as dependencies.</p> <ul> <li><code>depends(['buddypress''])</code> - Only loads the BuddyPress plugin for this given endpoint</li> </ul> <pre><code>$router-&gt;get('/users/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return get_user_by('id', $ID);\n})\n-&gt;returns('Users/Get')\n-&gt;depends(['buddypress']);  // Only BuddyPress plugin will be loaded for this REST endpoint</code></pre> <p>Warn</p> <p>Make sure to run the following WP-CLI command after a successfull deployment: <code>wp</code></p>"},{"location":"release/#v122","title":"v1.2.2","text":"<p>Three new filters that allows us to customise our JSON schema validator's.</p> <ul> <li><code>fastendpoints_validator</code> - Triggered by both middlewares</li> <li><code>fastendpoints_schema_validator</code> - Only triggered for Schema middlewares validators</li> <li><code>fastendpoints_response_validator</code> - Only triggered for Response middlewares validators</li> </ul> <pre><code>use Opis\\JsonSchema\\Validator;\n\nadd_filter('fastendpoints_validator', function (Validator $validator): Validator {\n    $formatsResolver = $validator-&gt;parser()-&gt;getFormatResolver();\n    $formatsResolver-&gt;registerCallable('integer', 'even', function (int $value): bool {\n        return $value % 2 === 0;\n    });\n\n    return $validator;\n});</code></pre> <p>Info</p> <p>For more customisations check the following links: 1. Custom formats, 2. Custom filters, 3. Custom media types and, 4. Custom content encoding</p>"},{"location":"release/#v121","title":"v1.2.1","text":"<p>Using JSON/opis schema loader and resolver which allows us to reference schemas inside other schemas.</p> <pre><code>// Now we also need to set a prefix while appending a directory. This prefix\n// will be used to reference schemas from inside another schema.\n$router-&gt;appendSchemaDir('/my-dir', 'http://www.example.com');</code></pre>"},{"location":"release/#v120","title":"v1.2.0","text":"<p>Dependency injection support in main handler, middlewares and permission handlers.</p> <pre><code>// In the past, the $request parameter was mandatory:\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function (WP_REST_Request $request) {\n    return $request-&gt;get_param('ID');\n});\n\n// Now you only type what you need\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return $ID;\n});\n// Middleware changes\nclass MyCustomMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware {\n    public function onRequest(/* Type what you need e.g. $request */) {\n        // Called before handling the request\n    }\n    public function onResponse(/* Type what you need e.g. $response, $request */) {\n        // Called after the request being handled\n    }\n}</code></pre>"},{"location":"release/#v110","title":"v1.1.0","text":"<ul> <li>100% test coverage</li> <li>Integration tests</li> <li>Middleware support</li> <li>Upgraded PHP version to 8.1</li> <li>Full support for WordPress 6.x versions</li> <li>Updated both Response and Schema to a middleware</li> </ul> <pre><code>// Middleware example\nclass MyCustomMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware {\n    public function onRequest(\\WP_REST_Request $request): ?\\WP_Error {\n        // Called before handling the request\n        return null;\n    }\n    public function onResponse(\\WP_REST_Request $request, mixed $response): mixed {\n        // Called after the request being handled\n        return $response;\n    }\n}</code></pre>"},{"location":"release/#v100","title":"v1.0.0","text":"<p>Initial release - don't use it!</p>"},{"location":"advanced-user-guide/","title":"Advanced User Guide","text":"<p>The Quick Start should be able to get you a feel of the main features of WP-FastEndpoints.</p> <p>However, it's possible that the solution for your use case might not be in the Quick Start tutorial. In the next sections we will take a look at further functionalities that WP-FastEndpoints provides.</p>"},{"location":"advanced-user-guide/dependency-injection/","title":"Dependency Injection","text":"<p>Each REST endpoint has its unique logic. Same goes with the data that it needs to work.</p> <p>For that reason, WP-FastEndpoints provides dependency injection support for all handlers e.g. permission handlers, main endpoint handler and middlewares.</p> <p>With dependency injection our endpoints do look much cleaner \u2728\ud83e\uddf9</p> With dependency injectionNo dependency injection <pre><code>// We only need the ID. So we type $ID\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return get_post($ID);\n});\n\n// We don't need anything. So no arguments are defined :D\n$router-&gt;get('/posts/random', function () {\n    $allPosts = get_posts();\n    return $allPosts ? $allPosts[array_rand($allPosts)] : new WpError(404, 'No posts found');\n});</code></pre> <pre><code>// Unable to fetch a dynamic parameter. Have to work with the $request argument\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($request) {\n    return get_post($request-&gt;get('ID'));\n});\n\n// Forced to accept $request even if not used :(\n$router-&gt;get('/posts/random', function ($request) {\n    $allPosts = get_posts();\n    return $allPosts ? $allPosts[array_rand($allPosts)] : new WpError(404, 'No posts found');\n});</code></pre>"},{"location":"advanced-user-guide/middlewares/","title":"Middlewares","text":"<p>Another cool feature of WP-FastEndpoints is the support for middlewares.</p> <p>Middlewares are pieces of code that can either run before and/or after a request is handled.</p> <p>At this stage, you might be already familiar with both the <code>schema(...)</code> and <code>returns(...)</code> middlewares. However, you can also create your own.</p> <pre><code>use Wp\\FastEndpoints\\Contracts\\Middleware;\n\nclass MyCustomMiddleware extends Middleware\n{\n    /**\n    * Create this function if you want that your middleware is\n    * triggered when it receives a request and after checking\n    * the user permissions.\n     */\n    public function onRequest(/* Type what you need */)\n    {\n        return;\n    }\n\n    /**\n    * Create this function when you want your middleware to be\n    * triggered before sending a response to the client \n     */\n    public function onResponse(/* Type what you need */) {\n        return;\n    }\n}\n\n// Attach middleware to endpoint\n$router-&gt;get('/test', function () {\n    return true;\n})\n-&gt;middleware(new MyCustomMiddleware());</code></pre> Tip <p>You can create both methods in a middleware: <code>onRequest</code> and <code>onResponse</code>. However, to save some CPU cycles only create the one you need [CPU emoji]</p>"},{"location":"advanced-user-guide/middlewares/#responses","title":"Responses","text":"<p>If you need you can also take advantage of either WP_Error and WP_REST_Response to send a direct response to the client. See Responses page for more info</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/","title":"Treat plugins as dependencies","text":"<p>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.</p> <p>To address this issue WP-FastEndpoints Depends was created to enable us to treat plugins as REST endpoint dependencies.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#adding-another-plugin","title":"Adding another plugin?? \ud83d\ude31","text":"<p>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.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#how-it-works","title":"How it works?","text":"<p>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.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#how-to-use-it","title":"How to use it?","text":"<p>Currently, we support both native WP endpoints and FastEndpoints \ud83d\ude0a</p> With FastEndpointsNative WP endpoints <pre><code>$router-&gt;get('/example/all-plugins', function () {\n    return \"Loads all active plugins\";\n});\n\n$router-&gt;get('/example/buddypress', function () {\n    return \"Only MyPlugin and BuddyPress plugins are loaded\"; \n})-&gt;depends(['my-plugin', 'buddypress']);</code></pre> <pre><code>// Loads all active plugins\nregister_rest_route('native/v1', 'example/all-plugins', [\n    'methods' =&gt; 'GET',\n    (...)\n]);\n\n// Only MyPlugin and BuddyPress plugins are loaded\nregister_rest_route('native/v1', 'example/buddypress', [\n    'methods' =&gt; 'GET',\n    'depends' =&gt; ['my-plugin', 'buddypress'],\n    (...)\n]);</code></pre> Tip <p>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. <code>$router-&gt;depends(['my-plugin'])</code></p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#router-vs-endpoint-dependencies","title":"Router vs Endpoint dependencies","text":"<p>With WP-FastEndpoint's we are able to either define global endpoint dependencies via router dependencies or specific endpoint dependencies.</p> <p>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.</p> <pre><code>$router = new \\Wp\\FastEndpoints\\Router('my-api', 'v1');\n$router-&gt;depends(['my-plugin']); // All endpoints and sub-routers would have this dependency</code></pre> <p>Danger</p> <p>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 <code>my-plugin</code> you have to set the dependencies to <code>['my-plugin']</code> otherwise when a request is received for that endpoint <code>my-plugin</code> will not be loaded.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#endpoint-dependencies-config","title":"Endpoint dependencies config","text":"<p>Under the hood, this plugin generates a config file with all the route dependencies (see example). To have the most up-to-date endpoint dependencies, make sure to either:</p> <ul> <li>run the <code>wp fastendpoints depends</code> command or </li> <li>activate any plugin on the website - this also triggers the re-generation of the route dependencies</li> </ul>"},{"location":"advanced-user-guide/plugins-as-dependencies/#useful-constants","title":"Useful constants","text":"<ul> <li>FASTENDPOINTS_DEPENDS_ENABLED - If set to false always loads all active plugins. Useful for local development </li> <li>FASTENDPOINTS_DEPENDS_CONFIG_FILEPATH - Overrides dependencies config file path</li> <li>FASTENDPOINTS_DEPENDS_REFRESH_ON_PLUGIN_ACTIVATION - If set to false, disables re-generating endpoint dependencies when any plugin is activated</li> </ul>"},{"location":"advanced-user-guide/request-life-cycle/","title":"Request Life Cycle","text":"<p>In WP-FastEndpoints an endpoint can have multiple optional handlers attached to:</p> <ol> <li>Permission handlers via <code>hasCap(...)</code> or <code>permission(...)</code> - Used to check for user permissions</li> <li>Middlewares<ol> <li>Request Payload Schema Middleware via <code>schema(...)</code> - Validates the request payload</li> <li>Response Schema Middleware via <code>returns(...)</code> - Makes sure that the proper response is sent to the client</li> <li>Custom middlewares via <code>middleware(...)</code> - Any other custom logic that you might want to run</li> </ol> </li> </ol>"},{"location":"advanced-user-guide/request-life-cycle/#permission-handlers","title":"Permission handlers","text":"<p>When a request is received the first handlers to run are the permissions handlers. Permission handlers are called by WordPress via <code>permission_callback</code>.</p> <p>In contrast to WordPress, you can have one or multiple permission handlers attached to the same endpoint.</p> Note <p>In the background all permission handlers are wrapped into one callable which is later on used as <code>permission_callback</code> by the endpoint</p> <p>These handlers will then be called in the same order as they were attached. For instance:</p> <pre><code>$router-&gt;get('/test', function () {return true;})\n-&gt;hasCap('read')                # Called first\n-&gt;hasCap('edit_posts')          # Called second if the first one was successful\n-&gt;permission('__return_true')   # Called last if both the first and second were successful</code></pre>"},{"location":"advanced-user-guide/request-life-cycle/#middlewares","title":"Middlewares","text":"<p>If all the permission handlers are successful the next set of handlers that run are the middlewares which implement the <code>onRequest</code> function.</p> <p>Remember that a middleware can implement <code>onRequest</code> and/or <code>onResponse</code> functions. The first one, runs before the main endpoint handler and the later one should run after the main endpoint handler.</p> <p>Warning</p> <p>Please bear in mind that if either a WP_Error or a WP_REST_Response is returned by the main endpoint handler following middlewares will not run. See Responses page for more info.</p>"},{"location":"advanced-user-guide/request-life-cycle/#onrequest","title":"onRequest","text":"<p>Same as with the permission handlers, middlewares are called with the same order that they were attached.</p> <pre><code>class OnRequestMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware\n{\n    public function onRequest(/* Type what you need */){\n        return;\n    }\n}\n\n$router-&gt;post('/test', function () {return true;})\n-&gt;middleware(OnRequestMiddleware()) # Called first\n-&gt;schema('Basics/Bool');            # Called second</code></pre>"},{"location":"advanced-user-guide/request-life-cycle/#onresponse","title":"onResponse","text":"<p>Likewise, middlewares implementing onResponse functions will be triggered in the same order as they were attached.</p> <pre><code>class OnResponseMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware\n{\n    public function onResponse(/* Type what you need */){\n        return;\n    }\n}\n\n$router-&gt;post('/test', function () {return true;})\n-&gt;returns('Basics/Bool')                # Called first\n-&gt;middleware(OnResponseMiddleware());   # Called second</code></pre>"},{"location":"advanced-user-guide/responses/","title":"Responses","text":"<p>When building an API sometimes we want to return a response directly to the client. For example:</p> <pre><code>$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return get_post($ID);\n})\n-&gt;returns('Posts/Get');  // It will raise a 422 HTTP error when we are unable to find a post</code></pre> <p>The code above, will raise a 422 HTTP status code error when ever we are unable to find a given post. This is where returning a message directly to the client can be useful.</p>"},{"location":"advanced-user-guide/responses/#early-return","title":"Early return","text":"<p>To trigger those scenarios we can either return a WP_Error or a WP_REST_Response.</p> WP_REST_ResponseWP_Error <pre><code>$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n    return $post ?: new WP_REST_Response(\"No posts found\", 404);\n})\n-&gt;returns('Posts/Get');  // This will not be triggered if no posts are found</code></pre> <pre><code>$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n    return $post ?: new WpError(404, \"No posts found\");\n})\n-&gt;returns('Posts/Get');  // This will not be triggered if no posts are found</code></pre>"},{"location":"advanced-user-guide/responses/#difference-between-returning-wp_rest_response-or-wp_error","title":"Difference between returning WP_REST_Response or WP_Error","text":"<p>The main difference between returning a WP_Error or a WP_REST_Response is regarding the JSON returned in the body.</p> WP_REST_ResponseWP_Error <pre><code>\"No posts found\"</code></pre> <pre><code>{\n    \"error\": 404,\n    \"message\": \"No posts found\",\n    \"data\": {\n        \"status\": 404\n    }\n}</code></pre>"},{"location":"advanced-user-guide/json-schemas/multiple-root-dirs/","title":"Multiple Root Dirs","text":"<p>For most projects, all JSON schemas might be kept inside a single root directory, like:</p> <pre><code>my-plugin\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Api\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500Schemas  // Root dir\n\u2502   \u2502       \u2502\n\u2502   \u2502       \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502       \u2502   \u2502   (...)\n\u2502   \u2502       \u2502\n\u2502   \u2502       \u2514\u2500\u2500\u2500Users\n\u2502   \u2502           \u2502   (...)</code></pre> <p>However, when your API starts to grow you might end up having the need for multiple root directories.</p>"},{"location":"advanced-user-guide/json-schemas/multiple-root-dirs/#example","title":"Example","text":"<p>Let's imagine that your API consists on two different versions: v1 and v2, like the following:</p> <pre><code>my-plugin\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Api\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500v1\n\u2502   \u2502   \u2502   \u2514\u2500\u2500\u2500Schemas  // V1 JSON schemas root dir\n\u2502   \u2502   \u2502       \u2502\n\u2502   \u2502   \u2502       \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502   \u2502           \u2502   (...)\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500v2\n\u2502   \u2502       \u2514\u2500\u2500\u2500Schemas  // V2 JSON schemas root dir\n\u2502   \u2502           \u2502\n\u2502   \u2502           \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502               \u2502   (...)</code></pre> <p>In this case scenario your code would look something like this:</p> <pre><code>$router-&gt;appendSchemaDir(MY_PLUGIN_DIR.'Api/v1/Schemas', 'https://www.wp-fastendpoints.com/v1');\n$router-&gt;appendSchemaDir(MY_PLUGIN_DIR.'Api/v2/Schemas', 'https://www.wp-fastendpoints.com/v2');</code></pre> <p>Then in all your endpoints you will have to specify the full schema prefix. It's important that you specify the full prefix because we can't guarantee the order or even if the same schema directory is returned all the time.</p> Using v1 schemasUsing v2 schemas <pre><code>$router-&gt;get('/test', function(){return true;})\n-&gt;returns('https://www.wp-fastendpoints.com/v1/Posts/Get.json');</code></pre> <pre><code>$router-&gt;get('/test', function(){return true;})\n-&gt;returns('https://www.wp-fastendpoints.com/v2/Posts/Get.json');</code></pre>"},{"location":"advanced-user-guide/json-schemas/references/","title":"References","text":"<p>References is another great feature from opis/json-schema.</p> <p>With references, you are able to point to another JSON schema inside of schema. This can be useful to reuse the same schema multiple times.</p> <p>Tip</p> <p>Bear in mind that when referencing a schema the full prefix must be used e.g. https://www.wp-fastendpoints.com/Posts/Get.json</p> <p>Take a look at their References Docs \u00bb for more information</p>"},{"location":"advanced-user-guide/json-schemas/validator/","title":"Validator","text":"<p>WP-FastEndpoints uses opis/json-schema for JSON schema validation.</p> <p>The reason we don't use the default WordPress JSON schema validation functionality is because it's quite outdated: it only partially supports JSON schema draft 4. opis/json-schema on the other side, does support the latest JSON schema drafts.</p>"},{"location":"advanced-user-guide/json-schemas/validator/#customising-validator","title":"Customising validator","text":"<p>One of the coolest features of opis/json-schema is that is super flexible, and supports:</p> <ul> <li>Custom formats</li> <li>Custom filters</li> <li>Custom media types and</li> <li>Custom content encoding</li> </ul> <p>These, can be super useful when ever you need some custom functionality in your JSON schemas.</p>"},{"location":"advanced-user-guide/json-schemas/validator/#available-hooks","title":"Available hooks","text":"<p>There are three WordPress filter hooks that you can use to customise the JSON schema validators used in WP-FastEndpoints:</p> <ol> <li><code>fastendpoints_validator</code> - Triggered by both middlewares</li> <li><code>fastendpoints_schema_validator</code> - Only triggered for Schema middlewares validators</li> <li><code>fastendpoints_response_validator</code> - Only triggered for Response middlewares validators</li> </ol>"},{"location":"advanced-user-guide/json-schemas/validator/#example","title":"Example","text":"<p>Imagine we only want to accept even numbers. To solve this issue, we might want to create a new custom format for integers, called <code>even</code>, which checks if a given number is even, like:</p> <pre><code>use Opis\\JsonSchema\\Validator;\n\n/**\n * Adds custom format resolvers to all JSON validators: request payload schema and response.\n *\n * @see fastendpoints_schema_validator - To update only the request payload schema validator, or\n * @see fastendpoints_response_validator - To update only the response validator\n */\nadd_filter('fastendpoints_validator', function (Validator $validator): Validator {\n    $formatsResolver = $validator-&gt;parser()-&gt;getFormatResolver();\n    $formatsResolver-&gt;registerCallable('integer', 'even', function (int $value): bool {\n        return $value % 2 === 0;\n    });\n\n    return $validator;\n});</code></pre> <p>Here is an example of a JSON schema using our custom <code>even</code> format:</p> <pre><code>{\n  \"type\": \"integer\",\n  \"format\": \"even\"\n}</code></pre> <p>More examples can be found in Custom Formats docs \u00bb</p>"},{"location":"quick-start/","title":"Quick Start","text":"<p>To better exemplify the benefits of using FastEndpoints we are going to build an API for manipulating blog posts.</p> <p>This API will be able to:</p> <ul> <li>Create</li> <li>Retrieve</li> <li>Update and</li> <li>Delete a blog post</li> </ul> <p>Full source code can be found at matapatos/wp-fastendpoints-my-plugin \u00bb</p>"},{"location":"quick-start/#plugin-code-structure","title":"Plugin code structure \ud83d\udd28","text":"<p>To hold this API we are going to create a plugin called MyPLugin - don't forget that logic shouldn't be contained in a theme - with the following structure:</p> <pre><code>my-plugin\n\u2502   my-plugin.php  # Registers the plugin provider\n\u2502   composer.json\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502   \u2502   constants.php\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Api\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500Routers\n\u2502   \u2502   \u2502   \u2502   Posts.php  # Holds our custom endpoints\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500Schemas\n\u2502   \u2502       \u2502\n\u2502   \u2502       \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502           \u2502   CreateOrUpdate.json  # Validates request payload\n\u2502   \u2502           \u2502   Get.json             # Validates responses and discards unwanted fields\n\u2502   \u2502\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Providers\n\u2502       \u2502   ApiServiceProvider.php       # Registers all routers\n\u2502       \u2502   MyPluginProvider.php         # Bootstraps our plugin\n\u2502       \u2502   ProviderContract.php\n\u2502\n\u2514\u2500\u2500\u2500tests</code></pre>"},{"location":"quick-start/json-schemas/","title":"JSON Schemas","text":"<p>For this scenario, we are going to create two JSON schemas: 1) for validating the request payload and another 2) to discard unwanted fields from responses (e.g. sensitive information).</p>"},{"location":"quick-start/json-schemas/#request-payload-createupdate","title":"Request payload (create/update)","text":"<p>For the payload we decided to accept the following fields: 1) post_title, 2) post_status, 3) post_type and 4) optionally post_content</p> <pre><code>{\n  \"type\": \"object\",\n  \"properties\": {\n    \"post_title\": {\n      \"type\": \"string\"\n    },\n    \"post_status\": {\n      \"enum\": [\"publish\", \"draft\", \"private\"],\n      \"default\": \"publish\"\n    },\n    \"post_type\": {\n      \"const\": \"post\"\n    },\n    \"post_content\": {\n      \"type\": \"string\",\n      \"contentMediaType\": \"text/html\"\n    }\n  },\n  \"required\": [\"post_title\", \"post_status\", \"post_type\"]\n}</code></pre>"},{"location":"quick-start/json-schemas/#response-retrieve","title":"Response (retrieve)","text":"<p>For the response we decided to only return the following fields: 1) post_title and 2) optionally post_excerpt</p> <pre><code>{\n  \"type\": \"object\",\n  \"properties\": {\n    \"post_title\": {\n      \"type\": \"string\"\n    },\n    \"post_excerpt\": {\n      \"type\": \"string\",\n      \"contentMediaType\": \"text/html\"\n    }\n  },\n  \"required\": [\"post_title\"]\n}</code></pre>"},{"location":"quick-start/router/","title":"Router","text":"<p>The first thing we need to do is to create a Router.</p> <pre><code>use Wp\\FastEndpoints\\Router;\n\n// Dependency injection to enable us to mock router in tests\n$router = $router ?? new Router('posts');</code></pre> <p>A router is a class which allow us to attach and register endpoints.</p> <p>An application can have one or multiple routers. One main benefit of using multiple routers is to group endpoints by same namespace and (optionally) same version. For instance, in this tutorial we are going to create a main router with a base namespace <code>my-plugin</code> and a version of <code>v1</code> which will add <code>/my-plugin/v1/</code> to the beginning of each attached endpoint from all sub-routers.</p>"},{"location":"quick-start/router/#create-a-post","title":"Create a post","text":"<p>With the posts router in place we can now start attaching our endpoints. We start adding the one responsible to create a new blog post.</p> <pre><code>$router-&gt;post('/', function (\\WP_REST_Request $request, \\WP_REST_Response $response): int|\\WP_Error {\n    $response-&gt;set_status(201);\n    $payload = $request-&gt;get_params();\n\n    return wp_insert_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('publish_posts');</code></pre> <p>When a request is received by this endpoint the following happens:</p> <ol> <li>Firstly, the user permissions are checked - Makes sure that the user has publish_posts capability</li> <li>Then, if successful, it validates the request payload by using the Posts/CreateOrUpdate schema.     We still didn't explain where the endpoints should look for the schemas, but will get into that     in Service Provider page</li> <li>Lastly, if the validation process also passes the handler is called.</li> </ol> <p>Info</p> <p>In this scenario we are not using a JSON schema to discard fields because the wp_insert_post either returns the ID of the post or a WP_Error which is already what we want \ud83d\ude0a</p>"},{"location":"quick-start/router/#retrieve-a-post","title":"Retrieve a post","text":"<p>Some endpoints however do need to return more complex objects. And in those cases JSON schemas can be of a great help.</p> <p>JSON schemas can help us to make sure that we are returning all the required fields as well as to avoid retrieving sensitive information. The last one is configurable.</p> <pre><code>use Wp\\FastEndpoints\\Helpers\\WpError;\n\n$router-&gt;get('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n\n    return $post ?: new WpError(404, 'Post not found');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('read');</code></pre> <p>In this case, we didn't set a JSON schema on purpose because we only need the post_id which is already parsed by the regex rule - we could have made that rule to match only positive integers though \ud83e\udd14</p> <p>Going back to the endpoint, this is what happens if a request comes in:</p> <ol> <li>Firstly, it checks the user has read    capability - one of the lowest WordPress users capabilities</li> <li>If so, it then calls the handler which either retrieves the post data (e.g. array or object)    or a WpError    in case that is not found. If a WpError or WP_Error is returned it stops further code execution    and returns that error message to the client - avoiding triggering response schema validation for example.</li> <li>Lastly, if the post data is returned by the handler the response schema will be triggered    and will check the response according to the given schema (e.g. Posts/Get)</li> </ol> <p>Note</p> <p>The WpError is just a subclass of WP_Error which automatically set's the HTTP status code of the response</p>"},{"location":"quick-start/router/#update-a-post","title":"Update a post","text":"<p>Checking for user capabilities such as <code>publish_posts</code> and <code>read</code> is cool. However, in the real world we sometimes also need to check for a particular resource.</p> <pre><code>$router-&gt;put('(?P&lt;ID&gt;[\\d]+)', function (\\WP_REST_Request $request): int|\\WP_Error {\n    $payload = $request-&gt;get_params();\n\n    return wp_update_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('edit_post', '&lt;ID&gt;');</code></pre> <p>The code above is not that different from the one for creating a post. However, in the last line <code>hasCap('edit_post', '&lt;ID&gt;')</code> the second parameter is a special one for FastEndpoints which will try to replace it by the ID parameter.</p> <p>Warning</p> <p>FastEndpoints will only replace the {PARAM_NAME} if that parameter exists in the request payload. Otherwise, will not touch it. Also, bear in mind that the first stage in an endpoint is checking the user capabilities. As such, at that time the request params have not been already validated by the request payload schema.</p>"},{"location":"quick-start/router/#delete-a-post","title":"Delete a post","text":"<pre><code>use Wp\\FastEndpoints\\Helpers\\WpError;\n\n$router-&gt;delete('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = wp_delete_post($postId);\n\n    return $post ?: new WpError(500, 'Unable to delete post');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('delete_post', '&lt;ID&gt;');</code></pre>"},{"location":"quick-start/router/#everything-together","title":"Everything together","text":"<pre><code>\"\"\"\nApi/Endpoints/Posts.php\n\"\"\"\ndeclare(strict_types=1);\n\nnamespace MyPlugin\\Api\\Routers;\n\nuse Wp\\FastEndpoints\\Helpers\\WpError;\nuse Wp\\FastEndpoints\\Router;\n\n// Dependency injection to enable us to mock router in the tests\n$router = $router ?? new Router('posts');\n\n// Creates a post\n$router-&gt;post('/', function (\\WP_REST_Request $request): int|\\WP_Error {\n    $payload = $request-&gt;get_params();\n\n    return wp_insert_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('publish_posts');\n\n// Fetches a single post\n$router-&gt;get('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n\n    return $post ?: new WpError(404, 'Post not found');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('read');\n\n// Updates a post\n$router-&gt;put('(?P&lt;ID&gt;[\\d]+)', function (\\WP_REST_Request $request): int|\\WP_Error {\n    $payload = $request-&gt;get_params();\n\n    return wp_update_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('edit_post', '&lt;ID&gt;');\n\n// Deletes a post\n$router-&gt;delete('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = wp_delete_post($postId);\n\n    return $post ?: new WpError(500, 'Unable to delete post');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('delete_post', '&lt;ID&gt;');\n\n// IMPORTANT: If no service provider is used make sure to set a version to the $router and call\n//            the following function here:\n// $router-&gt;register();\n\n// Used later on by the ApiProvider\nreturn $router;</code></pre>"},{"location":"quick-start/service-provider/","title":"Service Provider","text":"<p>Now that we have our posts router built the last main three bits missing are the following:</p> <ol> <li>Create a main router to hold all sub-routers (e.g. posts router)</li> <li>Specifying where to look for the JSON schemas (one or multiple directories) and</li> <li>Lastly, register the router. This is what adds the <code>rest_api_init</code> hook for registering all    the endpoints.</li> </ol> <pre><code>\"\"\"\nsrc/Providers/ApiProvider.php\n\"\"\"\ndeclare(strict_types=1);\n\nnamespace MyPlugin\\Providers;\n\nuse Wp\\FastEndpoints\\Router;\n\nclass ApiProvider implements ProviderContract\n{\n    protected Router $appRouter;\n\n    public function register(): void\n    {\n        $this-&gt;appRouter = new Router('my-plugin', 'v1');\n        $this-&gt;appRouter-&gt;appendSchemaDir(\\SCHEMAS_DIR, 'http://www.my-plugin.com');\n        foreach (glob(\\ROUTERS_DIR.'/*.php') as $filename) {\n            $router = require $filename;\n            $this-&gt;appRouter-&gt;includeRouter($router);\n        }\n        $this-&gt;appRouter-&gt;register();\n    }\n}</code></pre> <p>Tip</p> <p>Adding the schema directory to the main router will share it across   all sub-routers.</p>"},{"location":"quick-start/service-provider/#its-running","title":"It's running","text":"<p>\ud83c\udf89 Congrats you just created your first set of REST FastEndpoints</p> <p>Now let's see how to test it out! \ud83d\ude04</p> <p>Full source code can be found at matapatos/wp-fastendpoints-my-plugin \u00bb</p>"},{"location":"quick-start/tests/","title":"Testing","text":"<p>For testing our WP-FastEndpoints router we are going to use pest/php.</p> <p>Pest is a testing framework that makes it super easy to test functionality in PHP, that's why we are going to use it here. However, if you have a preference for some other testing framework, the some principles should apply \ud83d\ude0a</p> <p>Full source code can be found at matapatos/wp-fastendpoints-my-plugin \u00bb</p>"},{"location":"quick-start/tests/#testing-dependencies","title":"Testing dependencies","text":"<p>First, let's add all the necessary testing dependencies:</p> <pre><code>composer require mockery/mockery --dev  # For mocking classes/functions\ncomposer require dingo-d/wp-pest --dev  # Adds Pest support for integration tests</code></pre>"},{"location":"quick-start/tests/#testing-structure","title":"Testing structure","text":"<p>For testing our plugin, we are going to assume the following structure:</p> <pre><code>my-plugin\n\u2502   my-plugin.php\n\u2502   composer.json\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502       (...)\n\u2502\n\u2514\u2500\u2500\u2500tests\n    \u2502   bootstrap.php   # Loads WordPress for integration tests\n    \u2502   Helpers.php     # (optional) Helper functions\n    \u2502   Pest.php        # Pest configuration file\n    \u2502\n    \u2514\u2500\u2500\u2500Integration\n    \u2502       PostsApiTest.php\n    \u2502\n    \u2514\u2500\u2500\u2500Unit\n            PostsApiTest.php</code></pre>"},{"location":"quick-start/tests/integration/","title":"Integration Tests","text":"<p>Integration tests, are a bit tricky to set up.</p> <p>The following needs to happen in order to successfully run them:</p> <ol> <li>Load WordPress</li> <li>Replace the default TestCase class with another with enhanced WordPress functionalities    (e.g. to easily create users or posts)</li> <li>Create the REST server and boot it using the <code>rest_api_init</code>    hook</li> </ol>"},{"location":"quick-start/tests/integration/#wp-pest-to-the-rescue","title":"wp-pest to the rescue \ud83e\uddb8","text":"<p>However, thanks to wp-pest most of this trouble is no longer an issue. By simply running the command bellow, it will automatically pull the WordPress version you want and also set up the tests directory for you.</p> <pre><code>./vendor/bin/wp-pest setup plugin --plugin-slug my-plugin --wp-version 6.4.4</code></pre> <p>Tip</p> <p>If you use matapatos/wp-fastendpoints-my-plugin you can use the already configured <code>composer setup:wp:6.x</code> commands</p>"},{"location":"quick-start/tests/integration/#optional-changes","title":"Optional changes","text":"<p>If you take a closer look at the resultant tests structure you might notice that is slightly different from matapatos/wp-fastendpoints-my-plugin. These changes are not mandatory and so, feel free to skip this section \u23e9</p> <p>The main reason of these differences is to allow us to run tests without the need to always specify a group of tests. Those changes include:</p> <pre><code>/**\n* tests/Helpers.php\n */ \nnamespace MyPlugin\\Tests;\n\nclass Helpers\n{\n    /**\n     * Checks if weather we want to run integration tests or not\n     */\n    public static function isIntegrationTest(): bool\n    {\n        return isset($GLOBALS['argv']) &amp;&amp; in_array('--group=integration', $GLOBALS['argv'], true);\n    }\n}</code></pre> <pre><code>/**\n* tests/Integration/*Test.php\n */ \nnamespace MyPlugin\\Tests\\Integration;\n\nuse MyPlugin\\Tests\\Helpers;\n\n// Needs to add this check to every Integration test file\nif (! Helpers::isIntegrationTest()) {\n    return;\n}</code></pre>"},{"location":"quick-start/tests/integration/#our-integration-test","title":"Our integration test \ud83d\ude43","text":"<p>Now that everything is configured we can start creating integration tests:</p> <pre><code>test('Create a new post', function () {\n    // Create user with correct permissions\n    $userId = $this::factory()-&gt;user-&gt;create();\n    $user = get_user_by('id', $userId);\n    $user-&gt;add_cap('publish_posts');\n    // Make request as that user\n    wp_set_current_user($userId);\n    $request = new \\WP_REST_Request('POST', '/my-plugin/v1/posts');\n    $request-&gt;set_body_params([\n        'post_title' =&gt; 'My testing message',\n        'post_status' =&gt; 'publish',\n        'post_type' =&gt; 'post',\n        'post_content' =&gt; '&lt;p&gt;Message body&lt;/p&gt;',\n    ]);\n    $response = $this-&gt;server-&gt;dispatch($request);\n    expect($response-&gt;get_status())-&gt;toBe(201);\n    $postId = $response-&gt;get_data();\n    // Check that the post details are correct\n    expect(get_post($postId))\n        -&gt;toBeInstanceOf(\\WP_Post::class)\n        -&gt;toHaveProperty('post_title', 'My testing message')\n        -&gt;toHaveProperty('post_status', 'publish')\n        -&gt;toHaveProperty('post_type', 'post')\n        -&gt;toHaveProperty('post_content', '&lt;p&gt;Message body&lt;/p&gt;');\n})-&gt;group('api', 'posts');</code></pre> <p>Here, we take advantage of the existent testing factories to create a single user with the necessary capability to publish posts. Then, we make mimic a REST request from that given user, and lastly, we check if that blog post was created.</p>"},{"location":"quick-start/tests/unit/","title":"Unit Tests","text":"<p>As an example of a unit test, we are going add a test to check the 1) request payload schema used and 2) the necessary user permissions on the endpoint that allows a user to create a new blog post.</p> <p>We could have separated each assertion in its own unit test but for the sake of simplicity we are going to make both of them in the same test.</p> <pre><code>test('Creating post endpoint has correct permissions and schema', function () {\n    // Create endpoint mock\n    $endpoint = Mockery::mock(Endpoint::class);\n    // Assert that the request payload schema passed is correct\n    $endpoint\n        -&gt;shouldReceive('schema')\n        -&gt;once()\n        -&gt;with('Posts/CreateOrUpdate')\n        -&gt;andReturnSelf();\n    // Assert that user permissions are correct\n    $endpoint\n        -&gt;shouldReceive('hasCap')\n        -&gt;once()\n        -&gt;with('publish_posts');\n    // To ignore all the other endpoints\n    $ignoreEndpoint = Mockery::mock(Endpoint::class)\n        -&gt;shouldIgnoreMissing(Mockery::self());\n    // Create router. Make sure that var name matches your router variable\n    $router = Mockery::mock(Router::class)\n        -&gt;shouldIgnoreMissing($ignoreEndpoint);\n    // Assert that router endpoint is called\n    $router\n        -&gt;shouldReceive('post')\n        -&gt;once()\n        -&gt;with('/', Mockery::type('callable'))\n        -&gt;andReturn($endpoint);\n    // Needed to attach endpoints\n    require \\ROUTERS_DIR.'/Posts.php';\n})-&gt;group('api', 'posts');</code></pre> <p>The reason we are able to make the assertions above is due to this line. Specially, regarding this part <code>$router ??</code>. This allows us to replace our original router with our mocked version.</p> <p>Nothing magical happening here, just pure PHP code! \ud83e\ude84</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"WP-FastEndpoints","text":"<p>FastEndpoints is an elegant way of writing custom WordPress REST endpoints with a focus on readability and IDE auto completion support.</p>"},{"location":"#features","title":"Features","text":"<ul> <li>Decouples request validation from main logic</li> <li>Removes unwanted fields from responses</li> <li>Middlewares support</li> <li>IDE auto completion support</li> <li>No magic router. It uses WordPress <code>register_rest_route</code></li> <li>Support for newer JSON schema drafts thanks to opis/json-schema</li> <li>Able to treat plugins as dependencies via WP-FastEndpoints Depends</li> </ul>"},{"location":"#requirements","title":"Requirements","text":"<ul> <li>PHP 8.1+</li> <li>WordPress 6.x</li> <li>opis/json-schema</li> <li>php-di/invoker</li> </ul> <p>We aim to support versions that haven't reached their end-of-life.</p>"},{"location":"#installation","title":"Installation","text":"<pre><code>composer require wp-fastendpoints</code></pre>"},{"location":"#sponsors","title":"Sponsors","text":""},{"location":"release/","title":"Release Notes","text":""},{"location":"release/#v200","title":"v2.0.0","text":"<p>Support for treating plugins as dependencies.</p> <ul> <li><code>depends(['buddypress''])</code> - Only loads the BuddyPress plugin for this given endpoint</li> </ul> <pre><code>$router-&gt;get('/users/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return get_user_by('id', $ID);\n})\n-&gt;returns('Users/Get')\n-&gt;depends(['buddypress']);  // Only BuddyPress plugin will be loaded for this REST endpoint</code></pre> <p>Warn</p> <p>Make sure to run the following WP-CLI command after a successfull deployment: <code>wp</code></p>"},{"location":"release/#v122","title":"v1.2.2","text":"<p>Three new filters that allows us to customise our JSON schema validator's.</p> <ul> <li><code>fastendpoints_validator</code> - Triggered by both middlewares</li> <li><code>fastendpoints_schema_validator</code> - Only triggered for Schema middlewares validators</li> <li><code>fastendpoints_response_validator</code> - Only triggered for Response middlewares validators</li> </ul> <pre><code>use Opis\\JsonSchema\\Validator;\n\nadd_filter('fastendpoints_validator', function (Validator $validator): Validator {\n    $formatsResolver = $validator-&gt;parser()-&gt;getFormatResolver();\n    $formatsResolver-&gt;registerCallable('integer', 'even', function (int $value): bool {\n        return $value % 2 === 0;\n    });\n\n    return $validator;\n});</code></pre> <p>Info</p> <p>For more customisations check the following links: 1. Custom formats, 2. Custom filters, 3. Custom media types and, 4. Custom content encoding</p>"},{"location":"release/#v121","title":"v1.2.1","text":"<p>Using JSON/opis schema loader and resolver which allows us to reference schemas inside other schemas.</p> <pre><code>// Now we also need to set a prefix while appending a directory. This prefix\n// will be used to reference schemas from inside another schema.\n$router-&gt;appendSchemaDir('/my-dir', 'http://www.example.com');</code></pre>"},{"location":"release/#v120","title":"v1.2.0","text":"<p>Dependency injection support in main handler, middlewares and permission handlers.</p> <pre><code>// In the past, the $request parameter was mandatory:\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function (WP_REST_Request $request) {\n    return $request-&gt;get_param('ID');\n});\n\n// Now you only type what you need\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return $ID;\n});\n// Middleware changes\nclass MyCustomMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware {\n    public function onRequest(/* Type what you need e.g. $request */) {\n        // Called before handling the request\n    }\n    public function onResponse(/* Type what you need e.g. $response, $request */) {\n        // Called after the request being handled\n    }\n}</code></pre>"},{"location":"release/#v110","title":"v1.1.0","text":"<ul> <li>100% test coverage</li> <li>Integration tests</li> <li>Middleware support</li> <li>Upgraded PHP version to 8.1</li> <li>Full support for WordPress 6.x versions</li> <li>Updated both Response and Schema to a middleware</li> </ul> <pre><code>// Middleware example\nclass MyCustomMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware {\n    public function onRequest(\\WP_REST_Request $request): ?\\WP_Error {\n        // Called before handling the request\n        return null;\n    }\n    public function onResponse(\\WP_REST_Request $request, mixed $response): mixed {\n        // Called after the request being handled\n        return $response;\n    }\n}</code></pre>"},{"location":"release/#v100","title":"v1.0.0","text":"<p>Initial release - don't use it!</p>"},{"location":"advanced-user-guide/","title":"Advanced User Guide","text":"<p>The Quick Start should be able to get you a feel of the main features of WP-FastEndpoints.</p> <p>However, it's possible that the solution for your use case might not be in the Quick Start tutorial. In the next sections we will take a look at further functionalities that WP-FastEndpoints provides.</p>"},{"location":"advanced-user-guide/dependency-injection/","title":"Dependency Injection","text":"<p>Each REST endpoint has its unique logic. Same goes with the data that it needs to work.</p> <p>For that reason, WP-FastEndpoints provides dependency injection support for all handlers e.g. permission handlers, main endpoint handler and middlewares.</p> <p>With dependency injection our endpoints do look much cleaner \u2728\ud83e\uddf9</p> With dependency injectionNo dependency injection <pre><code>// We only need the ID. So we type $ID\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return get_post($ID);\n});\n\n// We don't need anything. So no arguments are defined :D\n$router-&gt;get('/posts/random', function () {\n    $allPosts = get_posts();\n    return $allPosts ? $allPosts[array_rand($allPosts)] : new WpError(404, 'No posts found');\n});</code></pre> <pre><code>// Unable to fetch a dynamic parameter. Have to work with the $request argument\n$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($request) {\n    return get_post($request-&gt;get('ID'));\n});\n\n// Forced to accept $request even if not used :(\n$router-&gt;get('/posts/random', function ($request) {\n    $allPosts = get_posts();\n    return $allPosts ? $allPosts[array_rand($allPosts)] : new WpError(404, 'No posts found');\n});</code></pre>"},{"location":"advanced-user-guide/middlewares/","title":"Middlewares","text":"<p>Another cool feature of WP-FastEndpoints is the support for middlewares.</p> <p>Middlewares are pieces of code that can either run before and/or after a request is handled.</p> <p>At this stage, you might be already familiar with both the <code>schema(...)</code> and <code>returns(...)</code> middlewares. However, you can also create your own.</p> <pre><code>use Wp\\FastEndpoints\\Contracts\\Middleware;\n\nclass MyCustomMiddleware extends Middleware\n{\n    /**\n    * Create this function if you want that your middleware is\n    * triggered when it receives a request and after checking\n    * the user permissions.\n     */\n    public function onRequest(/* Type what you need */)\n    {\n        return;\n    }\n\n    /**\n    * Create this function when you want your middleware to be\n    * triggered before sending a response to the client \n     */\n    public function onResponse(/* Type what you need */) {\n        return;\n    }\n}\n\n// Attach middleware to endpoint\n$router-&gt;get('/test', function () {\n    return true;\n})\n-&gt;middleware(new MyCustomMiddleware());</code></pre> Tip <p>You can create both methods in a middleware: <code>onRequest</code> and <code>onResponse</code>. However, to save some CPU cycles only create the one you need [CPU emoji]</p>"},{"location":"advanced-user-guide/middlewares/#responses","title":"Responses","text":"<p>If you need you can also take advantage of either WP_Error and WP_REST_Response to send a direct response to the client. See Responses page for more info</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/","title":"Treat plugins as dependencies","text":"<p>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.</p> <p>To address this issue WP-FastEndpoints Depends was created to enable us to treat plugins as REST endpoint dependencies.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#adding-another-plugin","title":"Adding another plugin?? \ud83d\ude31","text":"<p>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.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#how-it-works","title":"How it works?","text":"<p>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.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#how-to-use-it","title":"How to use it?","text":"<p>Currently, we support both native WP endpoints and FastEndpoints \ud83d\ude0a</p> With FastEndpointsNative WP endpoints <pre><code>$router-&gt;get('/example/all-plugins', function () {\n    return \"Loads all active plugins\";\n});\n\n$router-&gt;get('/example/buddypress', function () {\n    return \"Only MyPlugin and BuddyPress plugins are loaded\"; \n})-&gt;depends(['my-plugin', 'buddypress']);</code></pre> <pre><code>// Loads all active plugins\nregister_rest_route('native/v1', 'example/all-plugins', [\n    'methods' =&gt; 'GET',\n    (...)\n]);\n\n// Only MyPlugin and BuddyPress plugins are loaded\nregister_rest_route('native/v1', 'example/buddypress', [\n    'methods' =&gt; 'GET',\n    'depends' =&gt; ['my-plugin', 'buddypress'],\n    (...)\n]);</code></pre> Tip <p>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. <code>$router-&gt;depends(['my-plugin'])</code></p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#router-vs-endpoint-dependencies","title":"Router vs Endpoint dependencies","text":"<p>With WP-FastEndpoint's we are able to either define global endpoint dependencies via router dependencies or specific endpoint dependencies.</p> <p>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.</p> <pre><code>$router = new \\Wp\\FastEndpoints\\Router('my-api', 'v1');\n$router-&gt;depends(['my-plugin']); // All endpoints and sub-routers would have this dependency</code></pre> <p>Danger</p> <p>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 <code>my-plugin</code> you have to set the dependencies to <code>['my-plugin']</code> otherwise when a request is received for that endpoint <code>my-plugin</code> will not be loaded.</p>"},{"location":"advanced-user-guide/plugins-as-dependencies/#endpoint-dependencies-up-to-date","title":"Endpoint dependencies up-to-date","text":"<p>Under the hood, this plugin generates a config file with all the route dependencies (see example). To have the most up-to-date endpoint dependencies, make sure to either:</p> <ul> <li>run the <code>wp fastendpoints depends</code> command or </li> <li>activate any plugin on the website - this also triggers the re-generation of the route dependencies</li> </ul>"},{"location":"advanced-user-guide/plugins-as-dependencies/#useful-constants","title":"Useful constants","text":"<ul> <li>FASTENDPOINTS_DEPENDS_ENABLED - If set to false always loads all active plugins. Useful for local development </li> <li>FASTENDPOINTS_DEPENDS_CONFIG_FILEPATH - Overrides dependencies config file path</li> <li>FASTENDPOINTS_DEPENDS_REFRESH_ON_PLUGIN_ACTIVATION - If set to false, disables re-generating endpoint dependencies when any plugin is activated</li> </ul>"},{"location":"advanced-user-guide/request-life-cycle/","title":"Request Life Cycle","text":"<p>In WP-FastEndpoints an endpoint can have multiple optional handlers attached to:</p> <ol> <li>Permission handlers via <code>hasCap(...)</code> or <code>permission(...)</code> - Used to check for user permissions</li> <li>Middlewares<ol> <li>Request Payload Schema Middleware via <code>schema(...)</code> - Validates the request payload</li> <li>Response Schema Middleware via <code>returns(...)</code> - Makes sure that the proper response is sent to the client</li> <li>Custom middlewares via <code>middleware(...)</code> - Any other custom logic that you might want to run</li> </ol> </li> </ol>"},{"location":"advanced-user-guide/request-life-cycle/#permission-handlers","title":"Permission handlers","text":"<p>When a request is received the first handlers to run are the permissions handlers. Permission handlers are called by WordPress via <code>permission_callback</code>.</p> <p>In contrast to WordPress, you can have one or multiple permission handlers attached to the same endpoint.</p> Note <p>In the background all permission handlers are wrapped into one callable which is later on used as <code>permission_callback</code> by the endpoint</p> <p>These handlers will then be called in the same order as they were attached. For instance:</p> <pre><code>$router-&gt;get('/test', function () {return true;})\n-&gt;hasCap('read')                # Called first\n-&gt;hasCap('edit_posts')          # Called second if the first one was successful\n-&gt;permission('__return_true')   # Called last if both the first and second were successful</code></pre>"},{"location":"advanced-user-guide/request-life-cycle/#middlewares","title":"Middlewares","text":"<p>If all the permission handlers are successful the next set of handlers that run are the middlewares which implement the <code>onRequest</code> function.</p> <p>Remember that a middleware can implement <code>onRequest</code> and/or <code>onResponse</code> functions. The first one, runs before the main endpoint handler and the later one should run after the main endpoint handler.</p> <p>Warning</p> <p>Please bear in mind that if either a WP_Error or a WP_REST_Response is returned by the main endpoint handler following middlewares will not run. See Responses page for more info.</p>"},{"location":"advanced-user-guide/request-life-cycle/#onrequest","title":"onRequest","text":"<p>Same as with the permission handlers, middlewares are called with the same order that they were attached.</p> <pre><code>class OnRequestMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware\n{\n    public function onRequest(/* Type what you need */){\n        return;\n    }\n}\n\n$router-&gt;post('/test', function () {return true;})\n-&gt;middleware(OnRequestMiddleware()) # Called first\n-&gt;schema('Basics/Bool');            # Called second</code></pre>"},{"location":"advanced-user-guide/request-life-cycle/#onresponse","title":"onResponse","text":"<p>Likewise, middlewares implementing onResponse functions will be triggered in the same order as they were attached.</p> <pre><code>class OnResponseMiddleware extends \\Wp\\FastEndpoints\\Contracts\\Middleware\n{\n    public function onResponse(/* Type what you need */){\n        return;\n    }\n}\n\n$router-&gt;post('/test', function () {return true;})\n-&gt;returns('Basics/Bool')                # Called first\n-&gt;middleware(OnResponseMiddleware());   # Called second</code></pre>"},{"location":"advanced-user-guide/responses/","title":"Responses","text":"<p>When building an API sometimes we want to return a response directly to the client. For example:</p> <pre><code>$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    return get_post($ID);\n})\n-&gt;returns('Posts/Get');  // It will raise a 422 HTTP error when we are unable to find a post</code></pre> <p>The code above, will raise a 422 HTTP status code error when ever we are unable to find a given post. This is where returning a message directly to the client can be useful.</p>"},{"location":"advanced-user-guide/responses/#early-return","title":"Early return","text":"<p>To trigger those scenarios we can either return a WP_Error or a WP_REST_Response.</p> WP_REST_ResponseWP_Error <pre><code>$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n    return $post ?: new WP_REST_Response(\"No posts found\", 404);\n})\n-&gt;returns('Posts/Get');  // This will not be triggered if no posts are found</code></pre> <pre><code>$router-&gt;get('/posts/(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n    return $post ?: new WpError(404, \"No posts found\");\n})\n-&gt;returns('Posts/Get');  // This will not be triggered if no posts are found</code></pre>"},{"location":"advanced-user-guide/responses/#difference-between-returning-wp_rest_response-or-wp_error","title":"Difference between returning WP_REST_Response or WP_Error","text":"<p>The main difference between returning a WP_Error or a WP_REST_Response is regarding the JSON returned in the body.</p> WP_REST_ResponseWP_Error <pre><code>\"No posts found\"</code></pre> <pre><code>{\n    \"error\": 404,\n    \"message\": \"No posts found\",\n    \"data\": {\n        \"status\": 404\n    }\n}</code></pre>"},{"location":"advanced-user-guide/json-schemas/multiple-root-dirs/","title":"Multiple Root Dirs","text":"<p>For most projects, all JSON schemas might be kept inside a single root directory, like:</p> <pre><code>my-plugin\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Api\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500Schemas  // Root dir\n\u2502   \u2502       \u2502\n\u2502   \u2502       \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502       \u2502   \u2502   (...)\n\u2502   \u2502       \u2502\n\u2502   \u2502       \u2514\u2500\u2500\u2500Users\n\u2502   \u2502           \u2502   (...)</code></pre> <p>However, when your API starts to grow you might end up having the need for multiple root directories.</p>"},{"location":"advanced-user-guide/json-schemas/multiple-root-dirs/#example","title":"Example","text":"<p>Let's imagine that your API consists on two different versions: v1 and v2, like the following:</p> <pre><code>my-plugin\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Api\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500v1\n\u2502   \u2502   \u2502   \u2514\u2500\u2500\u2500Schemas  // V1 JSON schemas root dir\n\u2502   \u2502   \u2502       \u2502\n\u2502   \u2502   \u2502       \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502   \u2502           \u2502   (...)\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500v2\n\u2502   \u2502       \u2514\u2500\u2500\u2500Schemas  // V2 JSON schemas root dir\n\u2502   \u2502           \u2502\n\u2502   \u2502           \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502               \u2502   (...)</code></pre> <p>In this case scenario your code would look something like this:</p> <pre><code>$router-&gt;appendSchemaDir(MY_PLUGIN_DIR.'Api/v1/Schemas', 'https://www.wp-fastendpoints.com/v1');\n$router-&gt;appendSchemaDir(MY_PLUGIN_DIR.'Api/v2/Schemas', 'https://www.wp-fastendpoints.com/v2');</code></pre> <p>Then in all your endpoints you will have to specify the full schema prefix. It's important that you specify the full prefix because we can't guarantee the order or even if the same schema directory is returned all the time.</p> Using v1 schemasUsing v2 schemas <pre><code>$router-&gt;get('/test', function(){return true;})\n-&gt;returns('https://www.wp-fastendpoints.com/v1/Posts/Get.json');</code></pre> <pre><code>$router-&gt;get('/test', function(){return true;})\n-&gt;returns('https://www.wp-fastendpoints.com/v2/Posts/Get.json');</code></pre>"},{"location":"advanced-user-guide/json-schemas/references/","title":"References","text":"<p>References is another great feature from opis/json-schema.</p> <p>With references, you are able to point to another JSON schema inside of schema. This can be useful to reuse the same schema multiple times.</p> <p>Tip</p> <p>Bear in mind that when referencing a schema the full prefix must be used e.g. https://www.wp-fastendpoints.com/Posts/Get.json</p> <p>Take a look at their References Docs \u00bb for more information</p>"},{"location":"advanced-user-guide/json-schemas/validator/","title":"Validator","text":"<p>WP-FastEndpoints uses opis/json-schema for JSON schema validation.</p> <p>The reason we don't use the default WordPress JSON schema validation functionality is because it's quite outdated: it only partially supports JSON schema draft 4. opis/json-schema on the other side, does support the latest JSON schema drafts.</p>"},{"location":"advanced-user-guide/json-schemas/validator/#customising-validator","title":"Customising validator","text":"<p>One of the coolest features of opis/json-schema is that is super flexible, and supports:</p> <ul> <li>Custom formats</li> <li>Custom filters</li> <li>Custom media types and</li> <li>Custom content encoding</li> </ul> <p>These, can be super useful when ever you need some custom functionality in your JSON schemas.</p>"},{"location":"advanced-user-guide/json-schemas/validator/#available-hooks","title":"Available hooks","text":"<p>There are three WordPress filter hooks that you can use to customise the JSON schema validators used in WP-FastEndpoints:</p> <ol> <li><code>fastendpoints_validator</code> - Triggered by both middlewares</li> <li><code>fastendpoints_schema_validator</code> - Only triggered for Schema middlewares validators</li> <li><code>fastendpoints_response_validator</code> - Only triggered for Response middlewares validators</li> </ol>"},{"location":"advanced-user-guide/json-schemas/validator/#example","title":"Example","text":"<p>Imagine we only want to accept even numbers. To solve this issue, we might want to create a new custom format for integers, called <code>even</code>, which checks if a given number is even, like:</p> <pre><code>use Opis\\JsonSchema\\Validator;\n\n/**\n * Adds custom format resolvers to all JSON validators: request payload schema and response.\n *\n * @see fastendpoints_schema_validator - To update only the request payload schema validator, or\n * @see fastendpoints_response_validator - To update only the response validator\n */\nadd_filter('fastendpoints_validator', function (Validator $validator): Validator {\n    $formatsResolver = $validator-&gt;parser()-&gt;getFormatResolver();\n    $formatsResolver-&gt;registerCallable('integer', 'even', function (int $value): bool {\n        return $value % 2 === 0;\n    });\n\n    return $validator;\n});</code></pre> <p>Here is an example of a JSON schema using our custom <code>even</code> format:</p> <pre><code>{\n  \"type\": \"integer\",\n  \"format\": \"even\"\n}</code></pre> <p>More examples can be found in Custom Formats docs \u00bb</p>"},{"location":"quick-start/","title":"Quick Start","text":"<p>To better exemplify the benefits of using FastEndpoints we are going to build an API for manipulating blog posts.</p> <p>This API will be able to:</p> <ul> <li>Create</li> <li>Retrieve</li> <li>Update and</li> <li>Delete a blog post</li> </ul> <p>Full source code can be found at matapatos/wp-fastendpoints-my-plugin \u00bb</p>"},{"location":"quick-start/#plugin-code-structure","title":"Plugin code structure \ud83d\udd28","text":"<p>To hold this API we are going to create a plugin called MyPLugin - don't forget that logic shouldn't be contained in a theme - with the following structure:</p> <pre><code>my-plugin\n\u2502   my-plugin.php  # Registers the plugin provider\n\u2502   composer.json\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502   \u2502   constants.php\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Api\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500Routers\n\u2502   \u2502   \u2502   \u2502   Posts.php  # Holds our custom endpoints\n\u2502   \u2502   \u2502\n\u2502   \u2502   \u2514\u2500\u2500\u2500Schemas\n\u2502   \u2502       \u2502\n\u2502   \u2502       \u2514\u2500\u2500\u2500Posts\n\u2502   \u2502           \u2502   CreateOrUpdate.json  # Validates request payload\n\u2502   \u2502           \u2502   Get.json             # Validates responses and discards unwanted fields\n\u2502   \u2502\n\u2502   \u2502\n\u2502   \u2514\u2500\u2500\u2500Providers\n\u2502       \u2502   ApiServiceProvider.php       # Registers all routers\n\u2502       \u2502   MyPluginProvider.php         # Bootstraps our plugin\n\u2502       \u2502   ProviderContract.php\n\u2502\n\u2514\u2500\u2500\u2500tests</code></pre>"},{"location":"quick-start/json-schemas/","title":"JSON Schemas","text":"<p>For this scenario, we are going to create two JSON schemas: 1) for validating the request payload and another 2) to discard unwanted fields from responses (e.g. sensitive information).</p>"},{"location":"quick-start/json-schemas/#request-payload-createupdate","title":"Request payload (create/update)","text":"<p>For the payload we decided to accept the following fields: 1) post_title, 2) post_status, 3) post_type and 4) optionally post_content</p> <pre><code>{\n  \"type\": \"object\",\n  \"properties\": {\n    \"post_title\": {\n      \"type\": \"string\"\n    },\n    \"post_status\": {\n      \"enum\": [\"publish\", \"draft\", \"private\"],\n      \"default\": \"publish\"\n    },\n    \"post_type\": {\n      \"const\": \"post\"\n    },\n    \"post_content\": {\n      \"type\": \"string\",\n      \"contentMediaType\": \"text/html\"\n    }\n  },\n  \"required\": [\"post_title\", \"post_status\", \"post_type\"]\n}</code></pre>"},{"location":"quick-start/json-schemas/#response-retrieve","title":"Response (retrieve)","text":"<p>For the response we decided to only return the following fields: 1) post_title and 2) optionally post_excerpt</p> <pre><code>{\n  \"type\": \"object\",\n  \"properties\": {\n    \"post_title\": {\n      \"type\": \"string\"\n    },\n    \"post_excerpt\": {\n      \"type\": \"string\",\n      \"contentMediaType\": \"text/html\"\n    }\n  },\n  \"required\": [\"post_title\"]\n}</code></pre>"},{"location":"quick-start/router/","title":"Router","text":"<p>The first thing we need to do is to create a Router.</p> <pre><code>use Wp\\FastEndpoints\\Router;\n\n// Dependency injection to enable us to mock router in tests\n$router = $router ?? new Router('posts');</code></pre> <p>A router is a class which allow us to attach and register endpoints.</p> <p>An application can have one or multiple routers. One main benefit of using multiple routers is to group endpoints by same namespace and (optionally) same version. For instance, in this tutorial we are going to create a main router with a base namespace <code>my-plugin</code> and a version of <code>v1</code> which will add <code>/my-plugin/v1/</code> to the beginning of each attached endpoint from all sub-routers.</p>"},{"location":"quick-start/router/#create-a-post","title":"Create a post","text":"<p>With the posts router in place we can now start attaching our endpoints. We start adding the one responsible to create a new blog post.</p> <pre><code>$router-&gt;post('/', function (\\WP_REST_Request $request, \\WP_REST_Response $response): int|\\WP_Error {\n    $response-&gt;set_status(201);\n    $payload = $request-&gt;get_params();\n\n    return wp_insert_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('publish_posts');</code></pre> <p>When a request is received by this endpoint the following happens:</p> <ol> <li>Firstly, the user permissions are checked - Makes sure that the user has publish_posts capability</li> <li>Then, if successful, it validates the request payload by using the Posts/CreateOrUpdate schema.     We still didn't explain where the endpoints should look for the schemas, but will get into that     in Service Provider page</li> <li>Lastly, if the validation process also passes the handler is called.</li> </ol> <p>Info</p> <p>In this scenario we are not using a JSON schema to discard fields because the wp_insert_post either returns the ID of the post or a WP_Error which is already what we want \ud83d\ude0a</p>"},{"location":"quick-start/router/#retrieve-a-post","title":"Retrieve a post","text":"<p>Some endpoints however do need to return more complex objects. And in those cases JSON schemas can be of a great help.</p> <p>JSON schemas can help us to make sure that we are returning all the required fields as well as to avoid retrieving sensitive information. The last one is configurable.</p> <pre><code>use Wp\\FastEndpoints\\Helpers\\WpError;\n\n$router-&gt;get('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n\n    return $post ?: new WpError(404, 'Post not found');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('read');</code></pre> <p>In this case, we didn't set a JSON schema on purpose because we only need the post_id which is already parsed by the regex rule - we could have made that rule to match only positive integers though \ud83e\udd14</p> <p>Going back to the endpoint, this is what happens if a request comes in:</p> <ol> <li>Firstly, it checks the user has read    capability - one of the lowest WordPress users capabilities</li> <li>If so, it then calls the handler which either retrieves the post data (e.g. array or object)    or a WpError    in case that is not found. If a WpError or WP_Error is returned it stops further code execution    and returns that error message to the client - avoiding triggering response schema validation for example.</li> <li>Lastly, if the post data is returned by the handler the response schema will be triggered    and will check the response according to the given schema (e.g. Posts/Get)</li> </ol> <p>Note</p> <p>The WpError is just a subclass of WP_Error which automatically set's the HTTP status code of the response</p>"},{"location":"quick-start/router/#update-a-post","title":"Update a post","text":"<p>Checking for user capabilities such as <code>publish_posts</code> and <code>read</code> is cool. However, in the real world we sometimes also need to check for a particular resource.</p> <pre><code>$router-&gt;put('(?P&lt;ID&gt;[\\d]+)', function (\\WP_REST_Request $request): int|\\WP_Error {\n    $payload = $request-&gt;get_params();\n\n    return wp_update_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('edit_post', '&lt;ID&gt;');</code></pre> <p>The code above is not that different from the one for creating a post. However, in the last line <code>hasCap('edit_post', '&lt;ID&gt;')</code> the second parameter is a special one for FastEndpoints which will try to replace it by the ID parameter.</p> <p>Warning</p> <p>FastEndpoints will only replace the {PARAM_NAME} if that parameter exists in the request payload. Otherwise, will not touch it. Also, bear in mind that the first stage in an endpoint is checking the user capabilities. As such, at that time the request params have not been already validated by the request payload schema.</p>"},{"location":"quick-start/router/#delete-a-post","title":"Delete a post","text":"<pre><code>use Wp\\FastEndpoints\\Helpers\\WpError;\n\n$router-&gt;delete('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = wp_delete_post($postId);\n\n    return $post ?: new WpError(500, 'Unable to delete post');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('delete_post', '&lt;ID&gt;');</code></pre>"},{"location":"quick-start/router/#everything-together","title":"Everything together","text":"<pre><code>\"\"\"\nApi/Endpoints/Posts.php\n\"\"\"\ndeclare(strict_types=1);\n\nnamespace MyPlugin\\Api\\Routers;\n\nuse Wp\\FastEndpoints\\Helpers\\WpError;\nuse Wp\\FastEndpoints\\Router;\n\n// Dependency injection to enable us to mock router in the tests\n$router = $router ?? new Router('posts');\n\n// Creates a post\n$router-&gt;post('/', function (\\WP_REST_Request $request): int|\\WP_Error {\n    $payload = $request-&gt;get_params();\n\n    return wp_insert_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('publish_posts');\n\n// Fetches a single post\n$router-&gt;get('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = get_post($ID);\n\n    return $post ?: new WpError(404, 'Post not found');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('read');\n\n// Updates a post\n$router-&gt;put('(?P&lt;ID&gt;[\\d]+)', function (\\WP_REST_Request $request): int|\\WP_Error {\n    $payload = $request-&gt;get_params();\n\n    return wp_update_post($payload, true);\n})\n    -&gt;schema('Posts/CreateOrUpdate')\n    -&gt;hasCap('edit_post', '&lt;ID&gt;');\n\n// Deletes a post\n$router-&gt;delete('(?P&lt;ID&gt;[\\d]+)', function ($ID) {\n    $post = wp_delete_post($postId);\n\n    return $post ?: new WpError(500, 'Unable to delete post');\n})\n    -&gt;returns('Posts/Get')\n    -&gt;hasCap('delete_post', '&lt;ID&gt;');\n\n// IMPORTANT: If no service provider is used make sure to set a version to the $router and call\n//            the following function here:\n// $router-&gt;register();\n\n// Used later on by the ApiProvider\nreturn $router;</code></pre>"},{"location":"quick-start/service-provider/","title":"Service Provider","text":"<p>Now that we have our posts router built the last main three bits missing are the following:</p> <ol> <li>Create a main router to hold all sub-routers (e.g. posts router)</li> <li>Specifying where to look for the JSON schemas (one or multiple directories) and</li> <li>Lastly, register the router. This is what adds the <code>rest_api_init</code> hook for registering all    the endpoints.</li> </ol> <pre><code>\"\"\"\nsrc/Providers/ApiProvider.php\n\"\"\"\ndeclare(strict_types=1);\n\nnamespace MyPlugin\\Providers;\n\nuse Wp\\FastEndpoints\\Router;\n\nclass ApiProvider implements ProviderContract\n{\n    protected Router $appRouter;\n\n    public function register(): void\n    {\n        $this-&gt;appRouter = new Router('my-plugin', 'v1');\n        $this-&gt;appRouter-&gt;appendSchemaDir(\\SCHEMAS_DIR, 'http://www.my-plugin.com');\n        foreach (glob(\\ROUTERS_DIR.'/*.php') as $filename) {\n            $router = require $filename;\n            $this-&gt;appRouter-&gt;includeRouter($router);\n        }\n        $this-&gt;appRouter-&gt;register();\n    }\n}</code></pre> <p>Tip</p> <p>Adding the schema directory to the main router will share it across   all sub-routers.</p>"},{"location":"quick-start/service-provider/#its-running","title":"It's running","text":"<p>\ud83c\udf89 Congrats you just created your first set of REST FastEndpoints</p> <p>Now let's see how to test it out! \ud83d\ude04</p> <p>Full source code can be found at matapatos/wp-fastendpoints-my-plugin \u00bb</p>"},{"location":"quick-start/tests/","title":"Testing","text":"<p>For testing our WP-FastEndpoints router we are going to use pest/php.</p> <p>Pest is a testing framework that makes it super easy to test functionality in PHP, that's why we are going to use it here. However, if you have a preference for some other testing framework, the some principles should apply \ud83d\ude0a</p> <p>Full source code can be found at matapatos/wp-fastendpoints-my-plugin \u00bb</p>"},{"location":"quick-start/tests/#testing-dependencies","title":"Testing dependencies","text":"<p>First, let's add all the necessary testing dependencies:</p> <pre><code>composer require mockery/mockery --dev  # For mocking classes/functions\ncomposer require dingo-d/wp-pest --dev  # Adds Pest support for integration tests</code></pre>"},{"location":"quick-start/tests/#testing-structure","title":"Testing structure","text":"<p>For testing our plugin, we are going to assume the following structure:</p> <pre><code>my-plugin\n\u2502   my-plugin.php\n\u2502   composer.json\n\u2502\n\u2514\u2500\u2500\u2500src\n\u2502       (...)\n\u2502\n\u2514\u2500\u2500\u2500tests\n    \u2502   bootstrap.php   # Loads WordPress for integration tests\n    \u2502   Helpers.php     # (optional) Helper functions\n    \u2502   Pest.php        # Pest configuration file\n    \u2502\n    \u2514\u2500\u2500\u2500Integration\n    \u2502       PostsApiTest.php\n    \u2502\n    \u2514\u2500\u2500\u2500Unit\n            PostsApiTest.php</code></pre>"},{"location":"quick-start/tests/integration/","title":"Integration Tests","text":"<p>Integration tests, are a bit tricky to set up.</p> <p>The following needs to happen in order to successfully run them:</p> <ol> <li>Load WordPress</li> <li>Replace the default TestCase class with another with enhanced WordPress functionalities    (e.g. to easily create users or posts)</li> <li>Create the REST server and boot it using the <code>rest_api_init</code>    hook</li> </ol>"},{"location":"quick-start/tests/integration/#wp-pest-to-the-rescue","title":"wp-pest to the rescue \ud83e\uddb8","text":"<p>However, thanks to wp-pest most of this trouble is no longer an issue. By simply running the command bellow, it will automatically pull the WordPress version you want and also set up the tests directory for you.</p> <pre><code>./vendor/bin/wp-pest setup plugin --plugin-slug my-plugin --wp-version 6.4.4</code></pre> <p>Tip</p> <p>If you use matapatos/wp-fastendpoints-my-plugin you can use the already configured <code>composer setup:wp:6.x</code> commands</p>"},{"location":"quick-start/tests/integration/#optional-changes","title":"Optional changes","text":"<p>If you take a closer look at the resultant tests structure you might notice that is slightly different from matapatos/wp-fastendpoints-my-plugin. These changes are not mandatory and so, feel free to skip this section \u23e9</p> <p>The main reason of these differences is to allow us to run tests without the need to always specify a group of tests. Those changes include:</p> <pre><code>/**\n* tests/Helpers.php\n */ \nnamespace MyPlugin\\Tests;\n\nclass Helpers\n{\n    /**\n     * Checks if weather we want to run integration tests or not\n     */\n    public static function isIntegrationTest(): bool\n    {\n        return isset($GLOBALS['argv']) &amp;&amp; in_array('--group=integration', $GLOBALS['argv'], true);\n    }\n}</code></pre> <pre><code>/**\n* tests/Integration/*Test.php\n */ \nnamespace MyPlugin\\Tests\\Integration;\n\nuse MyPlugin\\Tests\\Helpers;\n\n// Needs to add this check to every Integration test file\nif (! Helpers::isIntegrationTest()) {\n    return;\n}</code></pre>"},{"location":"quick-start/tests/integration/#our-integration-test","title":"Our integration test \ud83d\ude43","text":"<p>Now that everything is configured we can start creating integration tests:</p> <pre><code>test('Create a new post', function () {\n    // Create user with correct permissions\n    $userId = $this::factory()-&gt;user-&gt;create();\n    $user = get_user_by('id', $userId);\n    $user-&gt;add_cap('publish_posts');\n    // Make request as that user\n    wp_set_current_user($userId);\n    $request = new \\WP_REST_Request('POST', '/my-plugin/v1/posts');\n    $request-&gt;set_body_params([\n        'post_title' =&gt; 'My testing message',\n        'post_status' =&gt; 'publish',\n        'post_type' =&gt; 'post',\n        'post_content' =&gt; '&lt;p&gt;Message body&lt;/p&gt;',\n    ]);\n    $response = $this-&gt;server-&gt;dispatch($request);\n    expect($response-&gt;get_status())-&gt;toBe(201);\n    $postId = $response-&gt;get_data();\n    // Check that the post details are correct\n    expect(get_post($postId))\n        -&gt;toBeInstanceOf(\\WP_Post::class)\n        -&gt;toHaveProperty('post_title', 'My testing message')\n        -&gt;toHaveProperty('post_status', 'publish')\n        -&gt;toHaveProperty('post_type', 'post')\n        -&gt;toHaveProperty('post_content', '&lt;p&gt;Message body&lt;/p&gt;');\n})-&gt;group('api', 'posts');</code></pre> <p>Here, we take advantage of the existent testing factories to create a single user with the necessary capability to publish posts. Then, we make mimic a REST request from that given user, and lastly, we check if that blog post was created.</p>"},{"location":"quick-start/tests/unit/","title":"Unit Tests","text":"<p>As an example of a unit test, we are going add a test to check the 1) request payload schema used and 2) the necessary user permissions on the endpoint that allows a user to create a new blog post.</p> <p>We could have separated each assertion in its own unit test but for the sake of simplicity we are going to make both of them in the same test.</p> <pre><code>test('Creating post endpoint has correct permissions and schema', function () {\n    // Create endpoint mock\n    $endpoint = Mockery::mock(Endpoint::class);\n    // Assert that the request payload schema passed is correct\n    $endpoint\n        -&gt;shouldReceive('schema')\n        -&gt;once()\n        -&gt;with('Posts/CreateOrUpdate')\n        -&gt;andReturnSelf();\n    // Assert that user permissions are correct\n    $endpoint\n        -&gt;shouldReceive('hasCap')\n        -&gt;once()\n        -&gt;with('publish_posts');\n    // To ignore all the other endpoints\n    $ignoreEndpoint = Mockery::mock(Endpoint::class)\n        -&gt;shouldIgnoreMissing(Mockery::self());\n    // Create router. Make sure that var name matches your router variable\n    $router = Mockery::mock(Router::class)\n        -&gt;shouldIgnoreMissing($ignoreEndpoint);\n    // Assert that router endpoint is called\n    $router\n        -&gt;shouldReceive('post')\n        -&gt;once()\n        -&gt;with('/', Mockery::type('callable'))\n        -&gt;andReturn($endpoint);\n    // Needed to attach endpoints\n    require \\ROUTERS_DIR.'/Posts.php';\n})-&gt;group('api', 'posts');</code></pre> <p>The reason we are able to make the assertions above is due to this line. Specially, regarding this part <code>$router ??</code>. This allows us to replace our original router with our mocked version.</p> <p>Nothing magical happening here, just pure PHP code! \ud83e\ude84</p>"}]}
\ No newline at end of file