開始使用

這份詳盡指南提供了使用 Shieldon 防火牆保護您的網頁應用程式的詳細概述。讓我們逐步了解。

伺服器需求

在使用 Shieldon 防火牆之前，請確保您的伺服器符合以下需求：

PHP >= 7.1.0
Ctype PHP 擴充套件
JSON PHP 擴充套件
GD PHP 擴充套件 (產生 Captcha 驗證碼圖片時輸要)
PDO PHP 擴充套件（僅在使用 MySQL、SQLite 驅動程式時需要）
Redis PHP 擴充套件（僅在使用 Redis 驅動程式時需要）

安裝

Shieldon 可以透過 PHP Composer 進行安裝：

composer require shieldon/shieldon

實作

在應用程式中實作 Shieldon 有三種主要方法：

將 Shieldon 實作為 PSR-15 中介軟體。
在應用程式的啟動階段實作 Shieldon。
將 Shieldon 實作在一個父控制器中，其他控制器繼承該父控制器。

每種實作方法都附有使用流行框架（如 Slim 4、Laravel 6 和 CodeIgniter 3）的實際範例。

PSR-15 中介軟體

範例：Slim 4 框架

Shieldon 可以作為 PSR-15 中介軟體使用，以下是使用 Slim 4 框架的範例。

(1) 建立防火牆中介軟體。

class FirewallMiddleware
{
    /**
     * 範例中介軟體可呼叫的類別
     *
     * @param ServerRequest  $request PSR-7 要求
     * @param RequestHandler $handler PSR-15 要求處理器
     *
     * @return Response
     */
    public function __invoke(Request $request, RequestHandler $handler): Response
    {
        $response = $handler->handle($request);

        $firewall = new \Shieldon\Firewall\Firewall($request, $response);

        // Shieldon 防火牆將放置其檔案的目錄。
        $firewall->configure(__DIR__ . '/../cache/shieldon_firewall');
        $response = $firewall->run();

        if ($response->getStatusCode() !== 200) {
            $httpResolver = new \Shieldon\Firewall\HttpResolver();
            $httpResolver($response);
        }

        return $response;
    }
}

(2) 將防火牆中介軟體加入應用程式。

例如，如果您使用 Slim 4 框架，程式碼應如下所示：

$app->add(new FirewallMiddleware());

(3) 建立控制台路由。

例如，如果您使用 Slim 4 框架，程式碼應如下所示。然後，您可以透過 URL https://yourwebsite.com/firewall/panel 登入控制台。

$app->any('/firewall/panel[/{params:.*}]', function (Request $request, Response $response, $args) {
    $firewall = new \Shieldon\Firewall\Firewall($request, $response);

    // Shieldon 防火牆將放置其檔案的目錄。
    // 必須與 FirewallMiddleware 相同。
    $firewall->configure(__DIR__ . '/../cache/shieldon_firewall');

    $panel = new \Shieldon\Firewall\Panel();

    // 控制台的基本 URL。
    $panel->entry('/firewall/panel/');
});

注意：

您的網站應該同時應用 POST 和 GET 這兩個 HTTP 方法。
使用者在被暫時封鎖後需要使用 POST 方法來解決 CAPTCHA。

啟動階段

範例：Laravel 6 框架

您可以在應用程式的啟動階段初始化 Shieldon，以下是使用 Laravel 6 框架的範例。

(1) 在初始化 $app 之前

在 bootstrap/app.php 中，<?php 之後，加入以下程式碼。

/*
|--------------------------------------------------------------------------
| 執行 Shieldon 防火牆
|--------------------------------------------------------------------------
|
| Shieldon 防火牆會監控傳入您網站的所有 HTTP 要求。
| 在初始化 Laravel 之前執行 Shieldon 防火牆可以避免與 Laravel 內建函式庫之間的可能衝突。
*/
if (isset($_SERVER['REQUEST_URI'])) {

    // 此目錄必須具有寫入權限。
    // 我們將其放在 `storage/shieldon_firewall` 目錄中。
    $storage =  __DIR__ . '/../storage/shieldon_firewall';

    $firewall = new \Shieldon\Firewall\Firewall();
    $firewall->configure($storage);
    $response = $firewall->run();

    if ($response->getStatusCode() !== 200) {
        $httpResolver = new \Shieldon\Firewall\HttpResolver();
        $httpResolver($response);
    }
}

(2) 定義控制台路由。

Route::any('/firewall/panel/{path?}', function() {

    $panel = new \Shieldon\Firewall\Panel();
    $panel->csrf(['_token' => csrf_token()]);

    // 進入點必須與定義的路由相同。
    $panel->entry('/firewall/panel/');

})->where('path', '(.*)');

父控制器

範例：CodeIgniter 3 框架

Shieldon 也可以在一個父控制器中實作，其他控制器繼承該父控制器，以下是使用 CodeIgniter 3 框架的範例。

建立一個父控制器。

在 application/core/ 目錄下建立一個新檔案 MY_Controller.php，這將成為您的父控制器。

以下是 MY_Controller 的基本結構：

class MY_Controller extends CI_Controller
{
    public function __construct()
    {
        parent::__construct();
    }
}

初始化防火牆實例

接下來，在 MY_Controller 的建構子中初始化 Shieldon 防火牆。這將確保每個繼承 MY_Controller 的控制器都會初始化 Shieldon 防火牆。

class MY_Controller extends CI_Controller
{
    public function __construct()
    {
        parent::__construct();

        // Composer 自動載入
        require_once APPPATH . '../vendor/autoload.php';

        // 此目錄必須具有寫入權限。
        $storage = APPPATH . 'cache/shieldon_firewall';

        $firewall = new \Shieldon\Firewall\Firewall();
        $firewall->configure($storage);
        $response = $firewall->run();

        if ($response->getStatusCode() !== 200) {
            $httpResolver = new \Shieldon\Firewall\HttpResolver();
            $httpResolver($response);
        }
    }

    /**
     * Shieldon 防火牆保護。
     */
    public function firewall()
    {
        $firewall = \Shieldon\Container::get('firewall');
        $firewall->run();
    }
}

定義控制器用於控制台。

接下來，您需要為 Shieldon 防火牆控制台定義一個控制器。在這個範例中，您將建立一個名為 Firewall 的控制器。

在 application/controllers/ 目錄中建立一個新檔案 Firewall.php，並添加以下程式碼：

class Firewall extends MY_Controller
{
    public function __construct()
    {
        parent::__construct();
    }

    /**
     * 這是我們的防火牆控制台入口。
     */
    public function panel()
    {
        $panel = new \Shieldon\Firewall\Panel();
        $panel->entry('/firewall/panel/');
    }
}

現在，Shieldon 防火牆已在您的 MY_Controller 中初始化，並且每個繼承 MY_Controller 並執行 firewall 方法的控制器都可以使用它。此外，您已經定義了一個名為 Firewall 的控制器，其中的 panel 方法是您進入 Shieldon 防火牆控制台的入口點。