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
Next revision Both sides next revision
rfc:socket_getaddrinfo [2016/08/11 14:28]
bp1222
rfc:socket_getaddrinfo [2016/09/02 18:43]
cmb this RFC has been implemented
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 3 proposed solutions, which are very similar, but I'm not sure which is preferable for implementation. +The implementation[[https://wiki.php.net/rfc/socket_getaddrinfo#references|[1]]] I'm proposing implements 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[[https://wiki.php.net/rfc/socket_getaddrinfo#references|[1]]] I'm proposing implements new socket_* functions.  ''socket_getaddrinfo()'' 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 fourth function is a free'r if you'd want to free the resources before end of script.  And the last to pull info from the addrinfo resource.+
 <file php> <file php>
-socket_getaddrinfo(string node[, mixed service, array hints]) : array+socket_addrinfo_lookup(string node[, mixed service, array hints]) : array
 socket_addrinfo_connect(resource $addrinfo) : resource socket_addrinfo_connect(resource $addrinfo) : resource
 socket_addrinfo_bind(resource $addrinfo) : resource socket_addrinfo_bind(resource $addrinfo) : resource
-socket_addrinfo(resource $addrinfo) : array +socket_addrinfo_explain(resource $addrinfo) : array
-socket_addrinfo_close(sockaddrresource sockaddr) : null+
 </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 [[https://wiki.php.net/rfc/socket_getaddrinfo#references|[2]]] is very similar 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 resource the functions, rather than a boolean return will return the resource to the bound/connected socket resource. +
- +
-<file php> +
-socket_getaddrinfo(string $node[, mixed $service, array $hints]) : array +
-socket_connect(resource $sock_or_addr[, string $address, int $port = 0]) : mixed +
-socket_bind(resource $sock_or_addr[, string address, int port = 0]) : mixed +
-socket_addrinfo(resource $addrinfo) : array +
-socket_addrinfo_close(resourece $addrinfo) : null +
-</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); +
-+
-</file>+
  
-==== Proposal 3 ==== +var_dump(socket_addrinfo_explain($sockaddr)); 
-This attempt [[https://wiki.php.net/rfc/socket_getaddrinfo#references|[3]]] is very similar to the others, and tries to be a hybrid approach.  It still alters the default signature of socket_(connect|bindto change the second argument to mixed.  This method is the most C-like of the 3.  After playing with all three, this is my preferred, but changing default signatures is not always the best idea. +/* Outputs: 
- +array(5
-<file php> +  ["ai_flags"]=> 
-socket_getaddrinfo(string $node[, mixed $service, array $hints]) : array +  int(0) 
-socket_connect(resource $sock, mixed $address_or_addrinfo[, int $port = 0]: bool +  ["ai_family"]=> 
-socket_bind(resource $sock, string $address_or_addrinfo[, int port 0]) : bool +  int(10
-socket_addrinfo_close(resourece $addrinfo: null +  ["ai_socktype"]=
-</file+  int(1
- +  ["ai_protocol"]=> 
-<file php> +  int(6
-<?php +  ["ai_addr"]=
-$addrinfo = socket_getaddrinfo('127.0.0.1', 2000, array('ai_family' => AI_INET, 'ai_socktype' => SOCK_STREAM)); +  array(2) { 
-$sockaddr = reset($addrinfo); +    ["sin6_port"]=> 
-if (!$sockaddr) die ("No Valid Socket Types"); +    int(2000
-$sock socket_create($sockaddr['ai_family'], $sockaddr['ai_socktype'], $sockaddr['ai_protocol']); +    ["sin6_addr"]=> 
-$sock = socket_bind($sock, $sockaddr); +    string(3"::1" 
-// ^^ $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);+
 } }
 +*/
 </file> </file>
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-New functionality; BC problems in changing default socket function signatures for Proposal 2&3.+New functionality; no BC issues.
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 97: Line 98:
 ==== New Constants ==== ==== New Constants ====
 Exposing the AI_* family of constants. Exposing the AI_* family of constants.
- 
-===== Open Issues ===== 
  
 ===== 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
 +  - 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]] +
-  * [3] - [[https://github.com/php/php-src/compare/master...bp1222:fix3-72733|Proposed #3 Implementation]]+
rfc/socket_getaddrinfo.txt · Last modified: 2017/09/22 13:28 (external edit)