rfc:socket_getaddrinfo

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rfc:socket_getaddrinfo [2016/08/10 02:47]
bp1222
rfc:socket_getaddrinfo [2017/09/22 13:28] (current)
Line 3: Line 3:
   * Date: 2016-08-08   * Date: 2016-08-08
   * Author: David Walker (dave@mudsite.com)   * Author: David Walker (dave@mudsite.com)
-  * Status: Draft+  * Status: Implemented (PHP 7.2)
   * First Published at: http://wiki.php.net/rfc/socket_getaddrinfo   * First Published at: http://wiki.php.net/rfc/socket_getaddrinfo
  
 ===== Introduction ===== ===== Introduction =====
-This RFC targets a reported feature request in [[https://bugs.php.net/bug.php?id=72733|#72733]].  The request is that PHP expose the C level function getaddrinfo().  This is a missing nice piece to the current socket library.  When dealing with IP variable networks it would be beneficial to allow libc to tell us what methods of connecting/listening would be most appropriate given a set of hints.+This RFC targets a reported feature request in [[https://bugs.php.net/bug.php?id=72733|#72733]].  The request is that PHP expose the C level function getaddrinfo().  This is a missing nice piece to the current socket library.  When dealing with variable networks it would be beneficial to allow libc to tell us what methods of connecting/listening would be most appropriate given a set of hints.
  
-===== Proposals ===== +===== Proposal ===== 
-I'm starting this RFC with 2 proposed solutions, which are very similar. +The implementation[[https://wiki.php.net/rfc/socket_getaddrinfo#references|[1]]] I'm proposing implements 4 new functions.  ''socket_addrinfo_lookup()'' will return an array of resources, with each resource corresponding to each returned addrinfo.  The next two implemented methods ''socket_addrinfo_bind()'', and ''socket_addrinfo_connect()'', would be used to bind, or connect, to a given resource rather than make the user go through the process of creating the socket and connect/binding themselves.  The last, ``socket_addrinfo_explain`` is to convert the resource to an array for examination.
-==== Proposal 1 ==== +
-The implementation[1] I'm proposing implements 4 new socket_* functions.  ''socket_getaddrinfo()'' will return an array of resources, with each resource corresponding to each returned addrinfo sockaddr.  The next two implemented methods ''socket_addrinfo_bind()'', and ''socket_addrinfo_connect()'', would be used to bind, or connect, to a given resource rather than make the user go through the process of creating the socket and connect/binding themselves.  The fourth function is a free'r if you'd want to free the resources before end of script.+
 <file php> <file php>
-array    socket_getaddrinfo(string node[, mixed service, array hints]) +socket_addrinfo_lookup(string node[, mixed service, array hints]) : array 
-resource socket_addrinfo_connect(sockaddrresource sockaddr) +socket_addrinfo_connect(resource $addrinforesource 
-resource socket_addrinfo_bind(sockaddrresource sockaddr+socket_addrinfo_bind(resource $addrinfo: resource 
-null     socket_addrinfo_close(sockaddrresource sockaddr)+socket_addrinfo_explain(resource $addrinfo: array
 </file> </file>
  
 +IPv4 Example
 <file php> <file php>
 <?php <?php
-$addrinfo = socket_getaddrinfo('127.0.0.1', 2000, array('ai_family' => AI_INET, 'ai_socktype' => SOCK_STREAM));+$addrinfo = socket_addrinfo_lookup('localhost', 2000, array('ai_family' => AF_INET, 'ai_socktype' => SOCK_STREAM));
 $sockaddr = reset($addrinfo); $sockaddr = reset($addrinfo);
 if (!$sockaddr) die ("No Valid Socket Types"); if (!$sockaddr) die ("No Valid Socket Types");
 $sock = socket_addrinfo_bind($sockaddr); $sock = socket_addrinfo_bind($sockaddr);
 // ^^ $sock is a socket resource that is bound to 127.0.0.1:2000 using TCP/IP ready for reading // ^^ $sock is a socket resource that is bound to 127.0.0.1:2000 using TCP/IP ready for reading
-foreach ($addrinfo as $sockaddr) { + 
-    socket_addrinfo_close($sockaddr);+var_dump(socket_addrinfo_explain($sockaddr)); 
 +/* Outputs: 
 +array(5) { 
 +  ["ai_flags"]=> 
 +  int(0) 
 +  ["ai_family"]=> 
 +  int(2) 
 +  ["ai_socktype"]=> 
 +  int(1) 
 +  ["ai_protocol"]=> 
 +  int(6) 
 +  ["ai_addr"]=> 
 +  array(2) { 
 +    ["sin_port"]=> 
 +    int(2000) 
 +    ["sin_addr"]=> 
 +    string(9) "127.0.0.1" 
 +  }
 } }
 +*/
 </file> </file>
  
-==== Proposal 2 ==== +IPv6 Example
-This attempt is identical to the first, EXCEPT, I change ''socket_create()'' and ''socket_bind()'' to accept one argument from two, IF, that argument is our addrinfo resource. If it is our addrinfo resourece the functions, rather than a boolean return will return the resource to the bound/connected socket resource. +
- +
-<file php> +
-array    socket_getaddrinfo(string node[, mixed service, array hints]) +
-mixed socket_connect(resource sockaddr[, string address, int port = 0]) +
-mixed socket_bind(resource sockaddr[, string address, int port = 0]) +
-null     socket_addrinfo_close(sockaddrresource sockaddr) +
-</file> +
 <file php> <file php>
 <?php <?php
-$addrinfo = socket_getaddrinfo('127.0.0.1', 2000, array('ai_family' => AI_INET, 'ai_socktype' => SOCK_STREAM));+$addrinfo = socket_addrinfo_lookup('localhost', 2000, array('ai_family' => AF_INET6, 'ai_socktype' => SOCK_STREAM));
 $sockaddr = reset($addrinfo); $sockaddr = reset($addrinfo);
 if (!$sockaddr) die ("No Valid Socket Types"); if (!$sockaddr) die ("No Valid Socket Types");
-$sock = socket_bind($sockaddr); +$sock = socket_addrinfo_bind($sockaddr); 
-// ^^ $sock is a socket resource that is bound to 127.0.0.1:2000 using TCP/IP ready for reading +// ^^ $sock is a socket resource that is bound to [::1]:2000 using TCP/IP ready for reading 
-foreach ($addrinfo as $sockaddr) { + 
-    socket_addrinfo_close($sockaddr);+var_dump(socket_addrinfo_explain($sockaddr)); 
 +/* Outputs: 
 +array(5) { 
 +  ["ai_flags"]=> 
 +  int(0) 
 +  ["ai_family"]=> 
 +  int(10) 
 +  ["ai_socktype"]=> 
 +  int(1) 
 +  ["ai_protocol"]=> 
 +  int(6) 
 +  ["ai_addr"]=> 
 +  array(2) { 
 +    ["sin6_port"]=> 
 +    int(2000) 
 +    ["sin6_addr"]=> 
 +    string(3) "::1" 
 +  }
 } }
 +*/
 </file> </file>
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-New functionality; no BC problems here.+New functionality; no BC issues.
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 73: Line 99:
 Exposing the AI_* family of constants. Exposing the AI_* family of constants.
  
-===== Open Issues ===== 
-The bug reporter provided desired code wherein getaddrinfo function would return an array-of-arrays that contain the ai_* info.  User would then be liable for issuing the scket_create & socket_(bind|connect).  I don't like adding more functions than necessary 
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
-Vote to implement the new functions, would require a 2/3 majority.+Vote to implement the new functionality, would require a 2/3 majority. 
 +<doodle title="Implement socket_getaddrinfo family" auth="bp1222" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 +Vote Start: 2016-08-24 15:23 UTC 
 + 
 +Vote End:   2016-08-31 23:59 UTC
  
 ===== Implementation ===== ===== Implementation =====
 +
 +  - merged into master (i.e. pre 7.2)
 +  - https://github.com/php/php-src/commit/d59af68f
 +  - https://github.com/php/php-src/commit/750f3d3f
 +  - a link to the PHP manual entry for the feature
  
 ===== References ===== ===== References =====
-  * [1] - [[https://github.com/php/php-src/compare/master...bp1222:fix-72733|Proposed #1 Implementation]] +  * [1] - [[https://github.com/php/php-src/pull/2078|Proposed Implementation]]
-  * [2] - [[https://github.com/php/php-src/compare/master...bp1222:fix2-72733|Proposed #2 Implementation]]+
rfc/socket_getaddrinfo.1470797266.txt.gz · Last modified: 2017/09/22 13:28 (external edit)