snicco/http-routing-bundle

v2.0.0-beta.9 2024-09-07 14:27 UTC

README

codecov Psalm Type-Coverage Psalm level PhpMetrics - Static Analysis PHP-Versions

This WordPress bundle configures the standalone snicco/http-routing library for usage in applications based on snicco/kernel.

Installation

composer install snicco/http-routing-bundle

Configuration

This bundle has extensive configuration options:

If these files do not exist in your configuration directory the default configuration will be copied the first time the kernel is booted in dev mode.

Add the HttpRoutingBundle to your bundles.php configuration file.

<?php
// /path/to/configuration/bundles.php

use Snicco\Bundle\HttpRouting\HttpRoutingBundle;

return [
    
    'bundles' => [
        Snicco\Component\Kernel\ValueObject\Environment::ALL => [
            HttpRoutingBundle::class
        ]   
    ]   
];

Usage

This bundle provides to main services that should be used:

  • HttpKernelRunner: Sends the current request at the right time through your application. This class serves as an entrypoint to your HTTP request-response cycle.
  • WPAdminMenu: Uses the AdminMenu that is configured by your route definitions to integration them with the WordPress admin menu.

This is an example of how the bootstrap file of a plugin could look like:

<?php

use Snicco\Bundle\HttpRouting\HttpKernelRunner;
use Snicco\Bundle\HttpRouting\WPAdminMenu;
use Snicco\Component\Kernel\Kernel;

// Create kernel

/**
 * @var Kernel $kernel 
 */
$kernel->boot();

/**
 * @var HttpKernelRunner $runner
 */
$runner = $kernel->container()->make(HttpKernelRunner::class);

$is_admin = is_admin();

$runner->listen($is_admin);

if ($is_admin) {
    /**
     * @var WPAdminMenu $admin_menu
     */
    $admin_menu = $kernel->container()->make(WPAdminMenu::class);
    $admin_menu->setUp('my-plugin-text-domain');
}

Requests and Responses

This bundle takes care of running the middleware pipeline of the snicco/http-routing library at just the right moments inside the WordPress request lifecycle.

There are three types of requests that can be handled:

  • API requests, requests where the URI path starts with the API path prefix defined in your routing configuration.
  • Admin requests, request that go to the WordPress admin area.
  • Frontend requests, all other requests.

The HttpKernelRunner::listen() method sets appropriate hooks based on the current request type and will then pipe a request through your application.

All of your middlewares and controllers have three types of responses that can be returned:

  1. DelegatedResponse, with headers that should be sent
  2. DelegatedResponse, without headers
  3. Any other PSR-7 response

Depending on the current request type here is what will happen for each response type:

  • API-request / Frontend-request:
  • Admin-request:

Middleware

This bundle provides a couple PSR-15 middlewares that you can use in your application:

  • ErrorsToExceptions: Transforms all errors inside your middleware pipeline to proper exceptions. Strongly recommended.
  • SetUserId: Adds the user id of the current WordPress user to the request.
  • SimpleTemplating: Adds a simple middleware to render ViewResponses where the view name has to be an absolute path.

Error handling

This bundle automatically configures the snicco/psr7-error-handler library that is used by snicco/http-routing.

You can configure this behaviour with the http_error_handling configuration.

All exceptions inside YOUR middleware pipeline will be handled automatically. WordPress core code and plugins are not affected by this at all.

Contributing

This repository is a read-only split of the development repo of the Snicco project.

This is how you can contribute.

Reporting issues and sending pull requests

Please report issues in the Snicco monorepo.

Security

If you discover a security vulnerability within BetterWPCache, please follow our disclosure procedure.