包简介

The Pi-hole API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts and returns reliable UTF-8 [JavaScript Object Notation (JSON)-encoded](http://www.json.org/) data for all API responses, and uses standard

README 文档

README

The Pi-hole API is organized around REST. Our API has predictable resource-oriented URLs, accepts and returns reliable UTF-8 JavaScript Object Notation (JSON)-encoded data for all API responses, and uses standard HTTP response codes and verbs. Most (but not all) endpoints require authentication. API endpoints requiring authentication will fail with code 401 Unauthorized when used outside a valid session.

For more information, please visit https://discourse.pi-hole.net.

Installation & Usage

Requirements

PHP 8.1 and later.

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/aseemann/pihole-api-client.git"
    }
  ],
  "require": {
    "aseemann/pihole-api-client": "*@dev"
  }
}

Then run composer install

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/aseemann/pihole-api-client/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');



// Configure API key authorization: x_header_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('X-FTL-SID', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-FTL-SID', 'Bearer');

// Configure API key authorization: query_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('sid', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('sid', 'Bearer');

// Configure API key authorization: cookie_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('sid', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('sid', 'Bearer');

// Configure API key authorization: header_sid
$config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKey('sid', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aseemann\PiholeApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('sid', 'Bearer');


$apiInstance = new Aseemann\PiholeApi\Api\ActionsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

try {
    $result = $apiInstance->actionFlusharp();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ActionsApi->actionFlusharp: ', $e->getMessage(), PHP_EOL;
}

API Endpoints

All URIs are relative to https://pi.hole:443/api

Class	Method	HTTP request	Description
ActionsApi	actionFlusharp	POST /action/flush/arp	Flush the network table
ActionsApi	actionFlushlogs	POST /action/flush/logs	Flush the DNS logs
ActionsApi	actionGravity	POST /action/gravity	Run gravity
ActionsApi	actionRestartdns	POST /action/restartdns	Restart pihole-FTL
AuthenticationApi	addApp	GET /auth/app	Create new application password
AuthenticationApi	addAuth	POST /auth	Submit password for login
AuthenticationApi	deleteAuthSession	DELETE /auth/session/{id}	Delete session by ID
AuthenticationApi	deleteGroups	DELETE /auth	Delete session
AuthenticationApi	getAuth	GET /auth	Check if authentication is required
AuthenticationApi	getAuthSessions	GET /auth/sessions	List of all current sessions
AuthenticationApi	getAuthTotp	GET /auth/totp	Suggest new TOTP credentials
ClientManagementApi	addClient	POST /clients	Add new client
ClientManagementApi	batchDeleteClients	POST /clients:batchDelete	Delete multiple clients
ClientManagementApi	deleteClient	DELETE /clients/{client}	Delete client
ClientManagementApi	getClientSuggestions	GET /clients/_suggestions	Get client suggestions
ClientManagementApi	getClients	GET /clients/{client}	Get clients
ClientManagementApi	replaceClient	PUT /clients/{client}	Replace client
DHCPApi	deleteDhcp	DELETE /dhcp/leases/{ip}	Remove DHCP lease
DHCPApi	getDhcp	GET /dhcp/leases	Get currently active DHCP leases
DNSControlApi	getBlocking	GET /dns/blocking	Get current blocking status
DNSControlApi	setBlocking	POST /dns/blocking	Change current blocking status
DocumentationApi	getDocs	GET /docs	Get the embedded API documentation rendered as HTML
DomainManagementApi	addDomain	POST /domains/{type}/{kind}	Add new domain
DomainManagementApi	batchDeleteDomains	POST /domains:batchDelete	Delete multiple domains
DomainManagementApi	deleteDomain	DELETE /domains/{type}/{kind}/{domain}	Delete domain
DomainManagementApi	getDomains	GET /domains/{type}/{kind}/{domain}	Get domain
DomainManagementApi	replaceDomain	PUT /domains/{type}/{kind}/{domain}	Replace domain
FTLInformationApi	deleteMessage	DELETE /info/messages/{message_id}	Delete Pi-hole diagnosis message
FTLInformationApi	getClient	GET /info/client	Get information about requesting client
FTLInformationApi	getDbinfo	GET /info/database	Get info about long-term database
FTLInformationApi	getDnsLog	GET /logs/dnsmasq	Get DNS log content
FTLInformationApi	getEndpoints	GET /endpoints	Get list of available API endpoints
FTLInformationApi	getFtlLog	GET /logs/ftl	Get DNS log content
FTLInformationApi	getFtlinfo	GET /info/ftl	Get info about various ftl parameters
FTLInformationApi	getHostinfo	GET /info/host	Get info about various host parameters
FTLInformationApi	getLogininfo	GET /info/login	Login page related information
FTLInformationApi	getMessages	GET /info/messages	Get Pi-hole diagnosis messages
FTLInformationApi	getMessagesCount	GET /info/messages/count	Get count of Pi-hole diagnosis messages
FTLInformationApi	getMetricsinfo	GET /info/metrics	Get metrics info
FTLInformationApi	getSensors	GET /info/sensors	Get info about various sensors
FTLInformationApi	getSysteminfo	GET /info/system	Get info about various system parameters
FTLInformationApi	getVersion	GET /info/version	Get Pi-hole version
FTLInformationApi	getWebserverLog	GET /logs/webserver	Get DNS log content
GroupManagementApi	addGroup	POST /groups	Add new group
GroupManagementApi	batchDeleteGroups	POST /groups:batchDelete	Delete multiple groups
GroupManagementApi	deleteGroup	DELETE /groups/{name}	Delete group
GroupManagementApi	getGroups	GET /groups/{name}	Get groups
GroupManagementApi	replaceGroup	PUT /groups/{name}	Replace group
ListManagementApi	addList	POST /lists	Add new list
ListManagementApi	batchDeleteLists	POST /lists:batchDelete	Delete lists
ListManagementApi	deleteLists	DELETE /lists/{list}	Delete list
ListManagementApi	getLists	GET /lists/{list}	Get lists
ListManagementApi	getSearch	GET /search/{domain}	Search domains in Pi-hole's lists
ListManagementApi	replaceLists	PUT /lists/{list}	Replace list
MetricsApi	getActivityMetrics	GET /history	Get activity graph data
MetricsApi	getActivityMetricsDatabase	GET /history/database	Get activity graph data (long-term data)
MetricsApi	getClientMetrics	GET /history/clients	Get per-client activity graph data
MetricsApi	getClientMetricsDatabase	GET /history/database/clients	Get per-client activity graph data (long-term data)
MetricsApi	getMetricsDatabaseQueryTypes	GET /stats/database/query_types	Get query types (long-term database)
MetricsApi	getMetricsDatabaseSummary	GET /stats/database/summary	Get database content details
MetricsApi	getMetricsDatabaseTopClients	GET /stats/database/top_clients	Get top clients (long-term database)
MetricsApi	getMetricsDatabaseTopDomains	GET /stats/database/top_domains	Get top domains (long-term database)
MetricsApi	getMetricsQueryTypes	GET /stats/query_types	Get query types
MetricsApi	getMetricsRecentBlocked	GET /stats/recent_blocked	Get most recently blocked domain
MetricsApi	getMetricsSummary	GET /stats/summary	Get overview of Pi-hole activity
MetricsApi	getMetricsTopClients	GET /stats/top_clients	Get top clients
MetricsApi	getMetricsTopDomains	GET /stats/top_domains	Get top domains
MetricsApi	getMetricsUpstreams	GET /stats/upstreams	Get metrics about Pi-hole's upstream destinations
MetricsApi	getMetricsUpstreamsDatabase	GET /stats/database/upstreams	Get metrics about Pi-hole's upstream destinations (long-term database)
MetricsApi	getQueries	GET /queries	Get queries
MetricsApi	getSuggestions	GET /queries/suggestions	Get query filter suggestions
NetworkInformationApi	deleteDevice	DELETE /network/devices/{device_id}	Delete a device from the network table
NetworkInformationApi	getGateway	GET /network/gateway	Get info about the gateway of your Pi-hole
NetworkInformationApi	getInterfaces	GET /network/interfaces	Get info about the interfaces of your Pi-hole
NetworkInformationApi	getNetwork	GET /network/devices	Get info about the devices in your local network as seen by your Pi-hole
NetworkInformationApi	getRoutes	GET /network/routes	Get info about the routes of your Pi-hole
PADDApi	getPadd	GET /padd	Get summarized data for PADD
PiHoleConfigurationApi	addArrayItem	PUT /config/{element}/{value}	Add config array item
PiHoleConfigurationApi	deleteArrayItem	DELETE /config/{element}/{value}	Delete config array item
PiHoleConfigurationApi	getConfigElem	GET /config/{element}	Get specific part of current configuration of your Pi-hole
PiHoleConfigurationApi	getPiholeConfig	GET /config	Get current configuration of your Pi-hole
PiHoleConfigurationApi	getTeleporter	GET /teleporter	Export Pi-hole settings
PiHoleConfigurationApi	patchConfig	PATCH /config	Change configuration of your Pi-hole
PiHoleConfigurationApi	postTeleporter	POST /teleporter	Import Pi-hole settings

Models

Authorization

Authentication schemes defined for the API:

query_sid

Type: API key
API key parameter name: sid
Location: URL query string

cookie_sid

Type: API key
API key parameter name: sid
Location:

header_sid

Type: API key
API key parameter name: sid
Location: HTTP header

x_header_sid

Type: API key
API key parameter name: X-FTL-SID
Location: HTTP header

query_password

Type: API key
API key parameter name: password
Location: URL query string

Tests

To run the tests, use:

composer install
vendor/bin/phpunit

Author

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

API version: 6.0
- Generator version: 7.13.0-SNAPSHOT
Build package: org.openapitools.codegen.languages.PhpClientCodegen

aseemann/pihole-api-client 适用场景与选型建议

aseemann/pihole-api-client 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 24 次下载、GitHub Stars 达 0，最近一次更新时间为 2025 年 04 月 01 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「php」「rest」「api」「sdk」「openapi」「openapitools」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 aseemann/pihole-api-client 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 aseemann/pihole-api-client 我们能提供哪些服务？

定制开发 / 二次开发

基于 aseemann/pihole-api-client 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 aseemann/pihole-api-client 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

theodorejb/phaster 6

A PSR-7 compatible library for making CRUD API endpoints

braune-digital/api-base-bundle 0

Api bundle

foxtes/alfabank-rest 1

Alfabank REST API integration

intahwebz/flickrguzzle 4

A Flickr wrapper to allow you to call the Flickr api with Guzzle as the backend.Goal is to have 100% Flickr api coverage rather than just upload/display photos (currently at 23%).

gego-soft/php-client 0

BlockCypher's PHP SDK for REST API

wellrested/cookies 0

Helper classes for creating cookie headers

aseemann/pihole-api-client

包简介

关键字：