README

ocolin/hyconext

A PHP client for monitoring and managing Hyconext network switches via SNMP and SSH. Provides structured access to interface data, system information, POE port statistics, and MAC address tables.

Built on top of ocolin/EasySNMP for SNMP and phpseclib for SSH.

Table of Contents

• Requirements
• Installation
• Configuration
  • SNMP Configuration
  • SSH Configuration
• Usage
  • SNMP Client
  • SSH Client
• Available Methods
  • HyconextSNMP
  • HyconextSSH
• Data Objects
  • Port
  • Poe
  • System
  • MacTable
• Notes
• Contributing & Roadmap

Requirements

• PHP 8.4 or higher
• ext-openssl
• ext-gmp

Installation

composer require ocolin/hyconext

Configuration

Configuration can be provided in three ways:

1. Environment variables with the default prefix — the simplest approach. Set HYCONEXT_* variables in your environment and instantiate with no arguments:

$snmp = new HyconextSNMP();
$ssh  = new HyconextSSH();

2. Environment variables with a custom prefix — useful when managing multiple devices with different credentials, or if you prefer a different naming convention:

$config = new Config( prefix: 'SWITCH_FLOOR2' );
$snmp   = new HyconextSNMP( $config );

With SWITCH_FLOOR2_SNMP_HOST, SWITCH_FLOOR2_SNMP_COMMUNITY etc. as your ENV vars.

3. Direct constructor arguments — pass values explicitly, bypassing ENV vars entirely:

$config = new Config( host: '192.168.1.1', community: 'public' );
$snmp   = new HyconextSNMP( $config );

Constructor arguments always take priority over environment variables. The tables below list all available parameters, their ENV suffix, and defaults. The full ENV var name is {PREFIX}{SUFFIX} where the prefix defaults to HYCONEXT — for example HYCONEXT_SNMP_HOST.

SNMP Configuration

SSH Configuration

Usage

SNMP Client

use Ocolin\Hyconext\HyconextSNMP;
use Ocolin\EasySNMP\Config;

// Using environment variables
$snmp = new HyconextSNMP();

// Using a config object directly
$config = new Config(
    host: '192.168.1.1',
    community: 'public',
    prefix: 'HYCONEXT'
);
$snmp = new HyconextSNMP( $config );

// Get system information
$system = $snmp->getSystem();
echo $system->sysName;      // 877Cedar.POESW
echo $system->sysUpTime;    // Raw TimeTicks value
echo $system->sysLocation;  // 877Cedar

// Get interfaces (default columns)
$interfaces = $snmp->getInterfaces();
foreach( $interfaces as $port ) {
    echo $port->name . ' - ' . $port->alias . ' - ' . $port->operStatus;
}

// Get interfaces (specific columns only)
$interfaces = $snmp->getInterfaces(['name', 'alias', 'operStatus', 'highSpeed']);

// Get POE data (all columns)
$poe = $snmp->getPoe();
foreach( $poe as $port ) {
    echo $port->label . ': ' . $port->currentPower . 'mW';
}

// Get POE data (specific columns only)
$poe = $snmp->getPoe(['adminEnable', 'detection', 'currentPower', 'label']);

SSH Client

The SSH client is used to retrieve the MAC address table, which is not available via SNMP on Hyconext switches.

use Ocolin\Hyconext\HyconextSSH;
use Ocolin\Hyconext\SshConfig;

// Using environment variables
$ssh = new HyconextSSH();

// Using a config object directly
$config = new SshConfig(
    host: '192.168.1.1',
    password: 'yourpassword'
);
$ssh = new HyconextSSH( $config );

// Get MAC address table
$macTable = $ssh->getMacTable();

echo $macTable->macStats->total;    // Total MAC addresses
echo $macTable->macStats->dynamic;  // Dynamic entries
echo $macTable->macStats->static;   // Static entries

foreach( $macTable->macTable as $entry ) {
    echo $entry->mac . ' on ' . $entry->interface . ' (VLAN ' . $entry->vlan . ')';
}

Available Methods

HyconextSNMP

getInterfaces() Columns

Default columns: name, alias, description, speed, operStatus, adminStatus

getPoe() Columns

Default: All columns

HyconextSSH

Data Objects

Port

Returned by getPorts().

$port->interface;   // Name of the interface port.
$port->adminStatus; // Administrative status.
$port->operStatus;  // Operational status.
$port->mode;        // Interface mode.
$port->description; // Description of port

Poe

Returned by getPoe(). All properties except index are nullable depending on requested columns.

$poe->index;          // int     - Interface index (matches Port index)
$poe->adminEnable;    // ?int    - 1=enabled, 2=disabled
$poe->detection;      // ?int    - 1=disabled, 2=searching, 3=deliveringPower, 4=fault
$poe->currentPower;   // ?int    - Current consumption in milliwatts
$poe->peakPower;      // ?int    - Peak consumption in milliwatts
$poe->maxPower;       // ?int    - Configured power limit in milliwatts
$poe->voltage;        // ?int    - Port voltage in volts
$poe->currentMa;      // ?int    - Current draw in milliamps
$poe->label;          // ?string - POE port label

System

Returned by getSystem().

$system->sysName;        // ?string - Device hostname
$system->sysDescr;       // ?string - Hardware/firmware description
$system->sysLocation;    // ?string - Physical location
$system->sysContact;     // ?string - Contact information
$system->sysUpTime;      // ?int    - Uptime in TimeTicks (hundredths of a second)

MacTable

Returned by getMacTable().

$macTable->macStats->total;    // int - Total MAC entries
$macTable->macStats->dynamic;  // int - Dynamic entries
$macTable->macStats->static;   // int - Static entries
$macTable->macStats->valid;    // int - Valid entries

foreach( $macTable->macTable as $entry ) {
    $entry->mac;        // string  - MAC address (xx:xx:xx:xx:xx:xx)
    $entry->interface;  // string  - Interface name
    $entry->vlan;       // ?int    - VLAN ID
    $entry->operType;   // string  - Operation type (forward, discard, etc.)
    $entry->type;       // string  - Entry type (dynamic, static, etc.)
    $entry->vsi;        // ?string - Virtual Switch Instance (null if not used)
    $entry->bd;         // ?string - Bridge Domain (null if not used)
}

Notes

• MAC table via SNMP: Hyconext switches do not expose the MAC address table via SNMP despite having a documented OID for it. The SSH client is provided as a workaround.
• POE data: The POE trait uses Hyconext's proprietary SNMP MIB (1.3.6.1.4.1.60609.1.1622). Some columns were determined empirically due to incomplete MIB documentation. These are noted in the source code.
• SSH compatibility: The SSH client has been tested against dropbear_USP_SSH as used by Hyconext switches. Standard phpseclib password authentication is used.
• Column 43 timeout: SNMP column .43 of the proprietary POE table causes the device to timeout and is intentionally skipped.
• Interface name format: SNMP returns full interface names (2.5GigaEthernet1/0/1) while SSH returns abbreviated names (2.5ge1/0/1). Keep this in mind when correlating data between the two clients.
• Raw values: All SNMP integer values are returned as-is without string conversion. This keeps the library lightweight and lets consumers format values as needed for their use case.t**: SNMP returns full interface names (2.5GigaEthernet1/0/1) while SSH returns abbreviated names (2.5ge1/0/1). Keep this in mind when correlating data between the two clients.

Contributing & Roadmap

This package is under active development. The current release covers the most commonly needed functionality — interfaces, system information, POE, and MAC address tables — but Hyconext switches support much more than what is documented here.

Planned additions include more SNMP traits for things like routing tables, ARP tables, and VLAN information. If there is a specific feature you need that isn't yet implemented, feel free to open an issue on GitHub and it will be considered for a future release. Pull requests are also welcome.