php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Bug #79251 net_get_interfaces function is not documented
Submitted: 2020-02-10 11:56 UTC Modified: 2020-02-11 11:25 UTC
Votes:2
Avg. Score:4.0 ± 1.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: michael dot vorisek at email dot cz Assigned:
Status: Verified Package: Documentation problem
PHP Version: 7.4.2 OS:
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: michael dot vorisek at email dot cz
New email:
PHP Version: OS:

 

 [2020-02-10 11:56 UTC] michael dot vorisek at email dot cz
Description:
------------
net_get_interfaces function is not documented


Patches

Add a Patch

Pull Requests

Pull requests:

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2020-02-11 11:25 UTC] cmb@php.net
-Status: Open +Status: Verified
 [2020-02-11 11:25 UTC] cmb@php.net
net_get_interfaces is available as of PHP 7.3.0[1].

[1] <https://github.com/php/php-src/pull/2935>
 [2021-04-01 14:20 UTC] CjrRbt at yahoo dot com
When will this function be documented? It's been a long of time since it was released.
 [2021-05-27 16:34 UTC] webamster_20210527 at cubiclesoft dot com
The correct way to call this function is net_get_interfaces().  It takes zero parameters and returns an array on success or a boolean of false on failure.

But what a missed opportunity!

There's currently no way in PHP userland to easily get the local system's DNS server list and other key network configuration information in a cross-platform fashion (especially Windows).  That's a significant oversight and something that this function or one like it could easily solve.  It's unfortunate that the original implementer didn't realize the larger need.

On Windows, this function calls the GetAdaptersAddresses() Win32 API but then fails to fully utilize the massive structure that is returned.  (IP_ADAPTER_ADDRESSES is a stupidly huge structure because...Microsoft.)  PHP only returns Unicast adapter information to userland while flat out ignoring the DNS server, Anycast, Multicast, and DHCP entries.  The information is right there but not utilized anywhere.

While GetAdaptersAddresses() returns a bunch of useful information in a single API call, *NIXes can obtain the same information as well through a variety of means.  For example, calling res_ninit() for the DNS server list.  Linux is also notably missing the adapter MAC address in this function despite it supposedly being available via getifaddrs().  I believe that is a bug in this userland function since the AF_PACKET/AF_LINK type contain the MAC rather than an IP address.  As a result, the first "unicast" item in the returned array for each interface on Linux is actually the MAC but doesn't show it since PHP attempts to interpret the data as an IP address.  As a result, just 'flags' and 'family' (17) show up in the output.  This means that net_get_interfaces() is buggy and inconsistent as well across all platforms.

The interface metrics are also notably missing across all platforms despite that information also being readily available (at least on Windows).  Interface metrics dictate some routing information for packets.

As I said, this is a missed opportunity.  The lack of documentation is a comparatively minor issue to what could and should actually exist.
 [2021-09-21 11:50 UTC] cmb@php.net
The following pull request has been associated:

Patch Name: Documentation for net_get_interfaces()
On GitHub:  https://github.com/php/doc-en/pull/847
Patch:      https://github.com/php/doc-en/pull/847.patch
 
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Sun Sep 26 10:03:36 2021 UTC