README

Warning

v3.0.0 is a complete rewrite and is not compatible with v1.x or v2.x. Requires PHP 8.4+ and FreeDSx SNMP.

ocolin/easysnmp

A PHP SNMP client that provides formatted, DTO-backed access to standard MIB-II data without requiring SNMP knowledge. Pass in your authentication credentials, call a method, get structured data back.

Built on top of FreeDSx SNMP.

Requirements

• PHP 8.4+
• FreeDSx SNMP ^0.5.1
• ocolin/global-type ^2.0

Installation

composer require ocolin/easysnmp

Configuration

Configuration is handled by the Config class. Credentials can be passed explicitly or read automatically from environment variables.

Explicit configuration

use Ocolin\EasySNMP\Config;
use Ocolin\EasySNMP\EasySNMP;

$config = new Config(
    host:      '10.0.0.1',
    community: 'public'
);

$snmp = new EasySNMP( config: $config );

Environment variables

If no explicit values are passed, Config falls back to environment variables using the EASY_SNMP_ prefix by default:

// Reads from EASY_SNMP_* environment variables
$snmp = new EasySNMP( config: new Config() );
// Or alternatively
$snmp = new EasySNMP();

Multiple devices with prefixes

When monitoring multiple devices, use the $prefix parameter to namespace your environment variables:

JUNIPER_SNMP_HOST=10.0.0.1
JUNIPER_SNMP_COMMUNITY=public

MIKROTIK_SNMP_HOST=10.0.0.2
MIKROTIK_SNMP_COMMUNITY=private

$juniper  = new EasySNMP( config: new Config( prefix: 'JUNIPER' ) );
$mikrotik = new EasySNMP( config: new Config( prefix: 'MIKROTIK' ) );

Prefix values are case-insensitive — 'juniper' and 'JUNIPER' both resolve to JUNIPER_SNMP_*.

Configuration reference

The EASY prefix in all ENV variable names is replaced by your custom prefix when using the $prefix parameter. For example, with prefix: 'JUNIPER' the variable EASY_SNMP_HOST becomes JUNIPER_SNMP_HOST.

Usage

System information

$system = $snmp->getSystem();

echo $system->name;      // Router-01
echo $system->descr;     // Linux Router 5.15.0
echo $system->location;  // Server Room A
echo $system->contact;   // admin@example.com
echo $system->upTime;    // TimeTicks integer
echo $system->objectId;  // 1.3.6.1.4.1.14988.1

// Formatted version:
$system = Format::System( $snmp->getSystem());

Interface table (ifTable)

$interfaces = $snmp->getIfTable();

foreach( $interfaces as $interface ) {
    echo $interface->index;        // Interface index
    echo $interface->description;  // Interface description
    echo $interface->speed;        // Speed in bps
    echo $interface->adminStatus;  // Raw integer (1=up, 2=down, 3=testing)
    echo $interface->operStatus;   // Raw integer (1=up, 2=down, etc.)
    echo $interface->macAddress;   // Raw MAC address
}


// Formatted version:
$interfaces = Format::IfTables( $snmp->getIfTable());

Fetch only specific columns to reduce SNMP calls:

$interfaces = $snmp->getIfTable( columns: ['description', 'operStatus'] );

Extended interface table (ifXTable)

$interfaces = $snmp->getIfXTable();

foreach( $interfaces as $interface ) {
    echo $interface->name;        // Interface name
    echo $interface->alias;       // Administrator-set alias
    echo $interface->highSpeed;   // Speed in Mbps
    echo $interface->inHcOctets;  // 64-bit input byte counter
    echo $interface->outHcOctets; // 64-bit output byte counter
}

// Formatted version:
$interfaces = Format::IfXTables( $snmp->getIfXTable());

ARP table

$arp = $snmp->getArpTable();

foreach( $arp as $entry ) {
    echo $entry->interface;  // Interface index
    echo $entry->ipAddress;  // IP address
    echo $entry->mac;        // Raw MAC address
    echo $entry->type;       // Raw integer (1=other, 2=invalid, 3=dynamic, 4=static)
}

// Formatted version:
$arp = Format::ArpTables( $snmp->getArpTable());

LLDP remote table

$lldp_rem = $snmp->getLldpRemTable();
foreach( $arp as $entry ) {
    echo $entry->localPort;     // Local port index
    echo $entry->chassisIdType; // Chassis ID subtype
    echo $entry->chassisId;     // Chassis identifier
    echo $entry->portIdType;    // Port ID subtype
    echo $entry->portId;        // Remote port identifier
    echo $entry->portDesc;      // Remote port description
    echo $entry->sysName;       // Remote system name
    echo $entry->sysDesc;       // Remote system description
    echo $entry->capSupported;  // Supported capabilities
    echo $entry->capEnabled;    // Enabled capabilities
}

// Formatted values:
$lldp_rem = Format::LldpRemTable( $snmp->getLldpRemTable());

IP address table

$addresses = $snmp->getIpAddrTable();

foreach( $addresses as $entry ) {
    echo $entry->address;    // 10.0.0.1
    echo $entry->interface;  // Interface index — matches ifTable
    echo $entry->netmask;    // 255.255.255.0
    echo $entry->bcast;      // Broadcast address bit
    echo $entry->reasmMaxSize; // Max datagram size for reassembly
}

// Fetch only specific columns
$addresses = $snmp->getIpAddrTable( columns: ['address', 'interface', 'netmask'] );

IpAddrTable properties

MAC address table

$macs = $snmp->getMacTable();

foreach( $macs as $entry ) {
    echo $entry->mac;        // Raw MAC address
    echo $entry->bridge;     // Bridge port number
    echo $entry->interface;  // Interface index — matches ifTable index
    echo $entry->status;     // Raw integer (3=learned, 4=self etc.)
}

// Formatted version
$macs = Format::macTables( $snmp->getMacTable() );

MacTable properties

IP forwarding table

$routes = $snmp->getIpForwardTable();

foreach( $routes as $route ) {
    echo $route->destination;  // Destination network
    echo $route->mask;         // Subnet mask
    echo $route->nextHop;      // Next hop IP address
    echo $route->interface;    // Interface index — matches ifTable
    echo $route->type;         // Raw integer. Use SnmpHelper::formatIpForwardType()
    echo $route->protocol;     // Raw integer. Use SnmpHelper::formatIpForwardProto()
    echo $route->status;       // Raw integer. Use SnmpHelper::formatRowStatus()
}

// Fetch additional columns
$routes = $snmp->getIpForwardTable( columns: [
    'interface', 'type', 'protocol', 'metric1', 'status',
    'age', 'nextHopAs', 'metric2', 'metric3', 'metric4', 'metric5'
]);

// Formatted version
$routes = Format::ipForwardTables( $snmp->getIpForwardTable() );

IpForwardTable properties

STP port table

$ports = $snmp->getStpPorts();

foreach( $ports as $port ) {
    echo $port->bridge;    // Bridge port number — matches MacEntry bridge
    echo $port->priority;  // Port priority (0-255)
    echo $port->state;     // Raw integer. Use SnmpHelper::formatStpPortState()
    echo $port->enable;    // Raw integer. Use SnmpHelper::formatStpPortEnable()
    echo $port->pathCost;  // STP path cost
    echo $port->desRoot;   // Designated root bridge ID (8 bytes binary)
    echo $port->desCost;   // Designated path cost to root
    echo $port->desBridge; // Designated bridge ID (8 bytes binary)
    echo $port->desPort;   // Designated port ID (2 bytes binary)
}

// Formatted version
$ports = Format::stpPortEntries( $snmp->getStpPorts() );

StpPortEntry properties

Formatting helpers

Raw integer values can be converted to human-readable labels using SnmpHelper:

use Ocolin\EasySNMP\SnmpHelper;

// Interface status
SnmpHelper::formatOperStatus( $interface->operStatus );
// "up", "down", "testing", "unknown", "dormant", "notPresent", "lowerLayerDown"

SnmpHelper::formatAdminStatus( $interface->adminStatus );
// "up", "down", "testing"

// Interface type
SnmpHelper::formatIfType( $interface->type );
// "ethernet", "softwareLoopback", "tunnel", "ieee8023adLag", etc.

// MAC address formatting
SnmpHelper::formatMacAddress( $interface->macAddress );
// "00:11:22:33:44:55"

SnmpHelper::formatMacAddress( $entry->mac );
// "00:11:22:33:44:55"

// ARP entry type
SnmpHelper::formatArpType( $entry->type );
// "other", "invalid", "dynamic", "static"

All helper methods accept null and return null, so they are safe to call directly on nullable DTO properties.

Extending for vendor-specific devices

EasySNMP is designed to be extended. Vendor-specific functionality can be added by extending the base class and adding traits for proprietary OID trees:

namespace Ocolin\Hyconext;

use Ocolin\EasySNMP\EasySNMP;
use Ocolin\Hyconext\Traits\PoeTrait;

class HyconextSNMP extends EasySNMP
{
    use PoeTrait;
}

The extending class inherits all standard MIB-II methods and gains access to bulkWalk(), getColumn(), and getCompositeColumn() for building vendor-specific trait methods.

PHP 8.4 compatibility

FreeDSx SNMP was written for PHP 7.4 and contains a nullable type deprecation that triggers on PHP 8.4. This is handled internally within EasySNMP and does not affect consuming code. A fix has been submitted upstream via pull request.

Property Lists

IfTable properties

IfXTable properties

System properties

ArpTable properties

Direct SNMP access

For custom queries beyond the built-in methods, pass-through access to the underlying FreeDSx client is available:

// Fetch specific OIDs
$result = $snmp->get( '1.3.6.1.2.1.1.1.0', '1.3.6.1.2.1.1.5.0' );

// Fetch next OID
$result = $snmp->getNext( '1.3.6.1.2.1.1.1.0' );

// Walk an OID subtree
$walk = $snmp->walk( startAt: '1.3.6.1.2.1.1' );

// Bulk walk an OID subtree — returns paginated Oid[] array
$oids = $snmp->bulkWalk( oid: '1.3.6.1.2.1.2.2.1' );

These methods return raw FreeDSx objects. See the FreeDSx documentation for details on working with the returned values.

License

MIT