README

Cisco IOS communications and configuration-parsing library for PHP. Provides:

• Detain\CiscoParser\CiscoParser — converts a Cisco IOS running/startup configuration text dump into a nested associative-array tree based on indentation depth.
• Detain\CiscoParser\CiscoLoader — SSH transport (via PECL ssh2) that drives an interactive shell against a real device and parses the output of common show commands (show int status, show int <int>, show log, show arp, show mac address-table, show ipv6 neighbors, show ipv6 routers, DHCP snooping bindings, trunk ports, VLANs, err-disabled, …).

Build Status and Code Analysis

Site	Status

Requirements

• PHP 7.4 or newer
• ext-mbstring
• ext-ssh2 — only required if you use CiscoLoader to talk to a real device. The pure-text CiscoParser works without it.

Installation

Install with Composer:

composer require detain/cisco_parser

Usage

Parsing a configuration

CiscoParser::parse_cisco_children() takes an array of lines (typically from explode("\n", file_get_contents(...)) after stripping \r) and produces a nested tree where each node has:

• command — the first whitespace-delimited token on the line
• arguments — (optional) anything after the first token
• children — (optional) the sub-block of more deeply-indented lines

use Detain\CiscoParser\CiscoParser;

$config = <<<CFG
hostname Switch1
interface FastEthernet0/1
 switchport access vlan 10
 spanning-tree portfast
interface FastEthernet0/2
 description Uplink
CFG;

$lines  = explode("\n", str_replace("\r", '', $config));
$parser = new CiscoParser();
$tree   = $parser->parse_cisco_children($lines);

print_r($tree);

Output:

Array
(
    [0] => Array
        (
            [command] => hostname
            [arguments] => Switch1
        )
    [1] => Array
        (
            [command] => interface
            [arguments] => FastEthernet0/1
            [children] => Array
                (
                    [0] => Array
                        (
                            [command] => switchport
                            [arguments] => access vlan 10
                        )
                    [1] => Array
                        (
                            [command] => spanning-tree
                            [arguments] => portfast
                        )
                )
        )
    [2] => Array
        (
            [command] => interface
            [arguments] => FastEthernet0/2
            [children] => Array
                (
                    [0] => Array
                        (
                            [command] => description
                            [arguments] => Uplink
                        )
                )
        )
)

Parsing from the command line

A small wrapper script is shipped at bin/cisco_parser.php:

php bin/cisco_parser.php /path/to/show-running-config.txt

If installed via Composer, the same script is exposed at vendor/bin/cisco_parser.php.

The wrapper recognises an optional Building configuration... / Current configuration : N bytes header (as emitted by show running-config) and pulls the byte count out into the result. Files without that header are parsed in full.

Talking to a real device

CiscoLoader opens an SSH session and exposes typed helpers around the most common show commands. It requires the ssh2 PECL extension.

use Detain\CiscoParser\CiscoLoader;

$device = new CiscoLoader('switch1.example.net', 'admin', 's3cret');

// Implicit connect on first exec() because $autoconnect is true by default.
$status = $device->show_int_status();
foreach ($status as $port) {
    echo "{$port['interface']}\t{$port['status']}\t{$port['vlan']}\n";
}

// Other helpers
$device->show_log();              // requires enable mode (#)
$device->show_int('Gi1/0/1');
$device->trunk_ports();
$device->vlans();
$device->errdisabled();
$device->dhcpsnoop_bindings();
$device->mac_address_table();
$device->arp_table();
$device->ipv6_neighbor_table();
$device->ipv6_routers();

// Push configuration. Requires enable mode (#).
$device->configure("interface Gi1/0/2\n description new label\n");
$device->write_config();          // saves running-config to startup-config

$device->disconnect();

CiscoLoader::exec($cmd) is available for any other command not covered by a helper; it returns the device's raw response with the trailing prompt stripped.

Testing

composer install
composer test

For coverage output:

composer test-coverage
# → tests/ + coverage.xml (clover format)

License

The Cisco Parser library is licensed under the LGPL-2.1-only license.