README

This package provides an easy-to-use PHP wrapper for the TCPShield API, with enhanced support for Laravel applications.

Installation

You can install the package via composer:

composer require punterdigital/tcpshield

Laravel Integration

Service Provider

The package includes a service provider that will automatically register the TCPShield client:

// config/app.php

'providers' => [
    // ...
    PunterDigital\TCPShield\TCPShieldServiceProvider::class,
];

If you're using Laravel 5.5 or higher, the service provider will be automatically registered.

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="PunterDigital\TCPShield\TCPShieldServiceProvider" --tag="config"

This will create a config/tcpshield.php file. You can set your API key in your .env file:

TCPSHIELD_API_KEY=your-api-key

Facade

The package includes a facade for more convenient usage:

// config/app.php

'aliases' => [
    // ...
    'TCPShield' => PunterDigital\TCPShield\TCPShieldFacade::class,
];

Basic Usage

Direct Client Usage

use PunterDigital\TCPShield\TCPShield;

// Instantiate the client
$client = new TCPShield('your-api-key');

// Get all networks
$networks = $client->getNetworks();

// Create a new network
$newNetwork = $client->createNetwork('My Network');

// Get details for a specific network
$network = $client->getNetwork(123);

// Add domain to network
$client->createDomain(123, 'example.com', 456, false);

Using the Facade in Laravel

use TCPShield;

// Get all networks
$networks = TCPShield::getNetworks();

// Create a new network
$newNetwork = TCPShield::createNetwork('My Network');

Using the Models (Laravel)

The package includes Eloquent-like models for working with TCPShield resources:

use PunterDigital\TCPShield\Models\Network;
use PunterDigital\TCPShield\Models\Domain;
use PunterDigital\TCPShield\Models\BackendSet;

// Get all networks
$networks = Network::all();

// Find a specific network
$network = Network::find(123);

// Create a new network
$network = Network::create('My Network');

// Update a network
$network->update([
    'name' => 'Updated Network Name',
    'mitigation_message' => 'You have been blocked'
]);

// Get domains for a network
$domains = $network->domains();

// Get backend sets for a network
$backendSets = $network->backendSets();

// Create a new domain
$domain = Domain::create(123, 'example.com', 456, false);

// Create a new backend set
$backendSet = BackendSet::create(
    123,             // Network ID
    'My Backends',   // Name
    [                // Backends
        '127.0.0.1:25565',
        '10.0.0.1:25565'
    ],
    true,            // Proxy Protocol
    false,           // Vulcan AC Enabled
    0                // Load Balancing Mode
);

Available Methods

This package provides comprehensive coverage of the TCPShield API endpoints, including:

Networks management
Domains management
Backend sets management
Firewall rules (IP, ASN, Country)
Bedrock tunnels
Sentry tunnels
Analytics
User management

See the TCPShield API documentation for detailed information on each endpoint and its parameters.

Error Handling

The package throws exceptions when API requests fail. You can catch these exceptions to handle errors gracefully:

use PunterDigital\TCPShield\Exceptions\TCPShieldException;

try {
    $networks = TCPShield::getNetworks();
} catch (TCPShieldException $e) {
    // Handle exception
    echo 'Error: ' . $e->getMessage();
}

License

The MIT License (MIT). Please see License File for more information.

punterdigital / tcpshield

Maintainers

Details