Download the PHP package pooshgan/pasarguard-php without Composer

PasarGuard PHP SDK

Language / زبان: فارسی

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Quick Start
• Architecture
• Endpoints
  • Users
  • Admins
  • Admin Roles
  • Nodes
  • Cores
  • Hosts
  • Groups
  • HWIDs
  • Subscriptions
  • User Templates
  • Client Templates
  • Settings
  • System
  • Setup
  • Home
• Real-World Examples
• Error Handling
• Advanced Usage
• API Reference
• Credits
• License

Overview

PasarGuard PHP SDK is a fully-typed, ergonomic client library for interacting with the PasarGuard Panel API. It is built on top of GuzzleHTTP and follows modern PHP 8.1+ conventions including strict typing, PSR-4 autoloading, and predictable method signatures.

The SDK covers 100% of the PasarGuard API surface, exposing every endpoint (Users, Nodes, Cores, Admins, Hosts, Groups, Subscriptions, Templates, Settings, System stats, HWID management, and more) through a clean, chainable object-oriented interface. Every method maps 1:1 to an API route, with parameters strongly typed and request payloads normalized to PHP arrays.

Whether you are building a custom dashboard, automating user provisioning, integrating billing, or running a Telegram Mini App backed by PasarGuard, this SDK gives you a stable foundation without the boilerplate of raw HTTP calls.

Features

• Strongly Typed — Every endpoint method has explicit parameter types and returns a typed array. No magic, no surprises.
• Guzzle Powered — Built on Guzzle 7, the de-facto standard for production HTTP in PHP. Supports middlewares, async calls, custom handlers, and connection pooling out of the box.
• 100% API Coverage — Implements every endpoint exposed by the PasarGuard Panel REST API, including bulk operations, by-username / by-id variants, and admin user-management flows.
• Flexible Auth — Out-of-the-box Bearer token auth, plus full support for injecting custom headers per-request (e.g., Telegram Mini App auth).
• Configurable Subscription Path — If your panel uses a non-default subscription path (e.g., /sub vs. /custom-sub), pass it once to the Client constructor and every related endpoint is rewritten automatically.
• Consistent Error Handling — All non-2xx responses raise a single PasarGuardException carrying the HTTP status code and the raw error payload, so you can centralize retries, logging, and user-facing messages.
• PSR-4 Autoloading — composer install and you are ready. No manual includes, no require_once chains.
• No Hidden State — The SDK is stateless per call; safe to share a single PasarGuard instance across a long-running process (queue workers, daemons, Swoole handlers).
• Bulk Operations — First-class support for bulk delete / reset / disable / enable / set-owner / modify-expire / modify-data-limit / modify-proxy-settings / wireguard-reallocate operations on users, admins, hosts, groups, and templates.

Requirements

The SDK is framework-agnostic: it works equally well inside Laravel, Symfony, Yii, CodeIgniter, CakePHP, plain PHP scripts, or long-running workers (RoadRunner, Swoole, FrankenPHP).

Installation

Install via Composer:

If you don't have Composer yet:

After installation, include the Composer autoloader in your entry-point file:

Quick Start

Architecture

The SDK is intentionally small and follows a layered design:

Key design choices

1. Single facade. You always work through PasarGuard. No need to instantiate endpoints manually.
2. Guzzle under the hood. All advanced Guzzle options (proxy, SSL, timeouts, middlewares) are exposed via the optional $guzzleOptions constructor argument.
3. Predictable signatures. Every mutating method follows (string $identifier, array $data = [], array $query = [], array $headers = []). Every reading method follows (array $query = [], array $headers = []). This means you can guess the signature of any method you have never used.
4. By-username / by-id variants. Most user- and admin-targeted endpoints ship in three flavours: by username, byUsername(), and byId(). Pick whichever identifier you have on hand.

Endpoints

All endpoint groups are accessible as properties on the PasarGuard facade:

Users

The users group is the largest endpoint. It manages subscribers, their data limits, expirations, ownership, subscriptions, and bulk operations. Every method that targets a single user ships in three variants — by default username slug, getByUsername(), and getById() — so you can use whichever identifier your application holds.

List and search users

Get a single user

Create, update, delete

Enable / Disable

Reset usage & revoke subscription

Ownership & next-plan activation

Usage & metrics

Expired users

Bulk operations

All bulk methods accept an array of identifiers (usernames or ids, depending on the variant) and additional payload data.

Template-based user creation

You can pre-define user templates in the panel and instantiate users from them — great for SaaS-style provisioning.

Admins

The admins group manages resellers and administrators. In addition to the CRUD operations familiar from the users group, admins expose a getToken() flow (for reseller login) and a getMiniAppToken() flow (for Telegram Mini App auth), as well as operations that act on the users owned by an admin.

Authentication

CRUD

List and inspect

Acting on an admin's users

Bulk admin operations

Admin Roles

Role-based access control for admins.

Nodes

Nodes represent the actual proxy servers running your cores. The nodes group covers CRUD, software / core / geofiles updates, reconnection, sync, logs, and stats.

Cores

A "core" is the underlying proxy binary (e.g., Xray, Marzban-node, Sing-box) that a node runs.

Hosts

Hosts are the public-facing addresses / SNI entries users connect to.

Groups

Groups let you bundle users for collective operations.

HWIDs

Hardware-ID locks for client apps that enforce device binding.

Subscriptions

Subscription endpoints are served from /sub by default (configurable via the Client constructor). These are the URLs that end-users put into their client apps.

If your panel exposes subscriptions under a different path (e.g., /custom-sub), pass it to the client once:

Every /sub-prefixed request from Subscription will then automatically use /custom-sub.

User Templates

Reusable recipes for creating users with a pre-configured set of proxies, data limits, expirations, and notes.

Client Templates

Templates that customize what each subscription client (v2rayNG, Streisand, V2RayN, ...) sees — useful for branding, custom configs, or pushing in-app ads.

Settings

Panel-wide settings (subscription path, Telegram bot, captcha, branding, etc.).

System

Server-level stats, inbound info, and worker health — handy for dashboards and uptime monitors.

Setup

One-time setup endpoints for creating / upgrading / deleting the panel owner.

Home

Health-check endpoint — useful for uptime probes and load-balancer checks.

Real-World Examples

1. Provision 100 users from a template

2. Daily cron: disable expired users and email a summary

3. Telegram Mini App: authenticate an admin

4. Custom HTTP layer (proxy + extended timeout)

5. Per-request custom header (e.g., Telegram Mini App auth on a single call)

Error Handling

Every non-2xx response throws a single, predictable exception:

Retry helper example

Advanced Usage

Sharing a single SDK instance across long-running workers

The SDK is stateless per request. You can build one PasarGuard instance at worker bootstrap and reuse it for thousands of jobs:

Injecting custom Guzzle middlewares

Because the SDK never hides Guzzle, you can attach any middleware by passing a pre-built GuzzleClient instance to a custom subclass of Client, or by manipulating the handler stack through guzzleOptions. For most use-cases, the constructor options are enough:

Using multiple panels at once

Non-default subscription path

Sending form params instead of JSON

Most mutating methods send JSON. For the few routes that expect form-encoded bodies (e.g., admin login), the SDK already uses form_params. For custom cases, you can pass a raw Guzzle multipart or form_params option through the headers / query slots — or, more cleanly, extend the endpoint:

API Reference

Client

Client::request()

Performs an HTTP request and returns the decoded JSON payload as an array. Throws PasarGuardException on any non-2xx response.

PasarGuard

A facade holding 15 endpoint instances. Construct it with a Client:

Endpoint method signature conventions

Every endpoint method follows one of three canonical shapes:

PasarGuardException

Credits

• Original Panel: PasarGuard
• SDK Author: Kazem Pooshgan
• HTTP Foundation: GuzzleHTTP

License

This project is licensed under the MIT License.

Copyright (c) 2026 Kazem Pooshgan