核心 API

核心

Shieldon\Firewall\Kernel

• ban
• getCurrentUrl
• managedBy
• run
• setClosure
• exclude
• setExcludedUrls
• setLogger
• setProperty
• setProperties
• setStrict
• unban

ban($ip)

• 參數 string $ip - 單一 IP 位址。
• 回傳 void

封鎖一個 IP 位址。

範例：

$kernel->ban('33.125.12.87');

getCurrentUrl()

• 回傳 string

回傳目前的 URL。此方法等同於 $_SERVER['REQUEST_URI']。

範例：

echo $kernel->getCurrentUrl();

managedBy($type)

• 參數 string $type "" managed | config | demo
• 回傳 void

告訴 Shieldon Firewall 由哪種方式來管理它。 此設定僅影響防火牆面板。

範例：

$kernel->managedBy('demo');

run()

• 回傳 int

執行檢查過程。

回應碼：

常數	值	原因
RESPONSE_DENY	0	永久封鎖
RESPONSE_ALLOW	1	通過
RESPONSE_TEMPORARILY_DENY	2	暫時封鎖，需通過驗證碼解除封鎖
RESPONSE_LIMIT	3	因線上會話數量達到限制而停止

範例：

$result = $kernel->run();

setClosure($key, $closure)

• 參數 string $key - Closure 的識別名稱。
• 參數 Closure $closure - Closure 函式。
• 回傳 void

設定一個 Closure 函式。

範例：

$kernel->setClosure('www_authenticate', function() use ($authHandler, $authenticateList) {
    $authHandler->set($authenticateList);
    $authHandler->check();
});

exclude($uriPath)

• 參數 string $uriPath - URI 的路徑組件。
• 回傳 void

設定您希望從保護中排除的 URL。

範例：

$kernel->exclude('/firewall/panel');

setExcludedUrls($urls)

• 參數 array $urls - URL 的集合。
• 回傳 void

設定您希望從保護中排除的 URL。

範例：

$list = [
    '/example/1',
    '/wp-login.php',
];

$kernel->setExcludedUrls($list);

setLogger($logger)

• 參數 ActionLogger $logger - 紀錄使用者的操作日誌。
• 回傳 void

設定操作日誌記錄器。

範例：

$kernel->setLogger(
    new \Shieldon\Firewall\Log\ActionLogger(
        BOOTSTRAP_DIR . '/../tmp/shieldon'
    )
);

setProperty($key, $value)

• 參數 string $key - 屬性的鍵名。
• 參數 mixed $value - 鍵的值。
• 回傳 void

範例：

$kernel->setProperty('time_unit_quota', [
    's' => 4,
    'm' => 20, 
    'h' => 60, 
    'd' => 240,
]);

有關設定的解釋，您可以在這裡找到。

setProperties($settings)

• 參數 array $settings - 設定。
• 回傳 void

範例：

$kernel->setProperties($settings);

setStrict($bool)

• 參數 bool $bool - 設定為 true 以啟用嚴格模式，否則設定為 false。
• 回傳 void

範例：

$kernel->setStrict(true);

unban($ip)

• 參數 string $ip - 一個 IP 位址。
• 回傳 void

解封一個 IP 位址。

範例：

$kernel->unban('33.33.33.33');

---

驗證碼 Trait

Shieldon\Firewall\Kernel\CaptchaTrait

• setCaptcha
• captchaResponse
• disableCaptcha

setCaptcha($instance)

• 參數 CaptchaInterface $instance - 驗證碼實例。
• 回傳 void

設定驗證碼。詳細用法請參閱驗證碼章節。

$kernel->setCaptcha(
    new \Shieldon\Firewall\Captcha\Recaptcha([
        'key' => '6LfkOaUUAAAAAH-AlTz3hRQ25SK8kZKb2hDRSwz9',
        'secret' => '6LfkOaUUAAAAAJddZ6k-1j4hZC1rOqYZ9gLm0WQh',
        'version' => 'v2',
        'lang' => 'en',
    ])
);

captchaResponse()

• 回傳 bool

返回驗證碼結果。 true：驗證碼解決成功，false：否則。

範例：

$result = $this->captchaResponsse();

disableCaptcha()

• 回傳 void

禁用所有驗證碼模組。此方法僅用於單元測試目的。

---

組件 Trait

Shieldon\Firewall\Kernel\ComponentTrait

• setComponent
• getComponent
• disableComponents

setComponent($instance)

• 參數 ComponentProvider $instance - 組件實例。
• 回傳 void

設定一個組件。

範例：

$kernel->setComponent(
    new \Shieldon\Firewall\Component\UserAgent()
);

getComponent()

• 參數 string $name - 組件的類名。
• 回傳 void | ComponentProvider

從組件容器中獲取一個組件實例。

範例：

$useragent = $kernel->getComponent('UserAgent');

disableComponents()

• 回傳 void

禁用所有已設置的組件。

範例：

$kernel->disableComponents();

---

驅動器 Trait

Shieldon\Firewall\Kernel\DriverTrait

• setDriver
• setChannel
• disableDbBuilder

setDriver($driver)

• 參數 DriverProvider $driver - 從所選的驅動器查詢數據。
• 回傳 void

範例：

$dbLocation = APPPATH . 'cache/shieldon.sqlite3';
$pdoInstance = new \PDO('sqlite:' . $dbLocation);

$kernel->setDriver(
    new \Shieldon\Firewall\Driver\SqliteDriver($pdoInstance)
);

setChannel($channel)

• 參數 string $channel - 指定一個通道。
• 回傳 void

範例：

$kernel->setChannel('web_project');

disableDbBuilder()

• 回傳 void

禁用自動建立資料庫。

範例：

$kernel->disableDbBuilder();

過濾器 Trait

Shieldon\Firewall\Kernel\FilterTrait

• setFilters
• setFilter
• disableFilters

setFilters($settings)

• 參數 array $settings - 過濾器設定。
• 回傳 void

$kernel->setFilters([
    'session' => true,
    'cookie' => true,
    'referer' => true,
    'frequency' => true,
]);

setFilter($filterName, $value)

• 參數 string $filterName - 過濾器的名稱。
• 參數 bool $value - 啟用過濾器為 true，否則為 false。
• 回傳 void

範例：

$kernel->setFilter('session', false);
$kernel->setFilter('cookie', false);
$kernel->setFilter('referer', true);
$kernel->setFilter('frequency', false); 

預設設定：

鍵	類型	值	說明
session	bool	true	檢查 Shieldon 會話驅動建立的會話。
cookie	bool	false	檢查 JavaScript 生成的 cookie。
referer	bool	true	檢查 HTTP_REFERER
frequency	bool	true	檢查 time_unit_quota 設定。

Cookie 過濾器預設為 false，因為您必須在網頁中輸出 JavaScript 片段。由 getJavascript() 生成的片段將使用 JavaScript 生成 cookie。

請查看 getJavascript() 的用法。

disableFilters()

• 回傳 void

禁用所有已設置的過濾器。

$kernel->disableFilters();

---

IP Trait

Shieldon\Firewall\IpTrait

• setIp
• getIp
• setRdns
• getRdns

setIp($ip)

• 參數 string $ip - 一個 IP 位址。
• 回傳 void

設定一個 IP 位址。

範例：

// 這裡是一個例子，從 CloudFlare 捕獲真實訪問者的 IP。
$realIp = $_SERVER['HTTP_CF_CONNECTING_IP'];

// 如果您在網站上使用了 CDN 服務，
// 請確保捕獲到真實的訪問者 IP，否則用戶將被封鎖。
$kernel->setIp($realIp);

getIp()

• 回傳 string

獲取當前設定的 IP。

範例：

$ip = $kernel->getIp();

setRdns($rdns)

• 參數 string $rdns - IP 位址的反向 DNS 記錄。
• 回傳 void

設定一個反向 DNS 記錄供檢查使用。

範例：

$kernel->setRdns('localhost');

getRdns()

• 回傳 string

獲取 IP 解析的主機名稱。

$rdns = $kernel->getRdns();

---

Messenger Trait

Shieldon\Firewall\Kernel\MessengerTrait

• setMessenger

setMessenger($instance)

• 參數 MessengerInterface $instance - 信使實例。
• 回傳 void

範例：

$apiKey = '981441296:AAGCcgv_NETMdWQCBTaMOk_yoMfax5EV7YQ';
$channel = '@your_channel';

$telegramMessenger = new \Messenger\Telegram($apiKey, $channel);

$kernel->setMessenger($telegramMessenger);

---

Template Trait

Shieldon\Firewall\Kernel\TemplateTrait

• setDialog
• respond
• setTemplateDirectory
• getJavascript

setDialog($settings)

• 參數 array $settings - 對話框 UI 設置。
• 回傳 void

自定義對話框 UI。

範例：

$settings = [
    'lang'             => 'en',
    'background_image' => '',
    'bg_color'         => '#ffffff',
    'header_bg_color'  => '#212531',
    'header_color'     => '#ffffff',
    'shadow_opacity'   => '0.2',
];

$kernel->setDialog($settings);

respond()

• 回傳 ResponseInterface

回應結果。

範例：

$response = $kernel->respond();

setTemplateDirectory($directory)

• 參數 array $directory - 存放模板檔案的目錄。
• 回傳 void

設定前端模板目錄。您可以將這些檔案複製到一個目錄中，並對其進行修改以自定義對話框的外觀。

範例：

$kernel->setTemplateDirectory(YOUR_DIRECTORY_PATH);

getJavascript()

• 回傳 string

在您的網頁中輸出 JavaScript 片段。

此片段在客戶端的瀏覽器上生成 cookie，然後我們檢查 cookie 來識別客戶端是否為機器人。

// 在您的頁面模板中輸出此變數。
$jsCode = $kernel->getJavascript();

會話

Shieldon\Firewall\Kernel\SessionTrait

• limitSession
• getSessionCount

limitSession($count, $period, $unique)

• 參數 int $count 1000 在線使用者的數量。如果達到，使用者將排隊。
• 參數 int $period 300 允許使用者瀏覽的時間段。 (單位：秒)
• 參數 bool $unique false 允許每個 IP 位址只有一個會話。
• 回傳 void

限制在線會話。

範例：

$kernel->limitSession(100, 300);

getSessionCount()

• 回傳 int

獲取在線人數。如果啟用 limitSession。

範例：

$count = $kernel->getSessionCount();