rfc:uuid

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
rfc:uuid [2017/05/26 22:07] – fleshgrinderrfc:uuid [2017/09/02 07:01] – Started Voting fleshgrinder
Line 3: Line 3:
   * Date: 2017-05-25   * Date: 2017-05-25
   * Author: Richard Fussenegger, php@fleshgrinder.com   * Author: Richard Fussenegger, php@fleshgrinder.com
-  * Status: Under Discussion+  * Status: Voting
   * First Published at: http://wiki.php.net/rfc/uuid   * First Published at: http://wiki.php.net/rfc/uuid
  
Line 41: Line 41:
 ==== Why C? ==== ==== Why C? ====
 There is no reason why this should be implemented in C. One could argue that it is faster, which it probably is, but this is a weak argument. This RFC would propose the inclusion of UUIDs implemented in PHP if shipping of PHP code as part of the standard module of PHP would be possible. However, there is a C API included that allows other PHP modules to utilize UUIDs. There is no reason why this should be implemented in C. One could argue that it is faster, which it probably is, but this is a weak argument. This RFC would propose the inclusion of UUIDs implemented in PHP if shipping of PHP code as part of the standard module of PHP would be possible. However, there is a C API included that allows other PHP modules to utilize UUIDs.
- 
-<blockquote>Fully documented C API can be found [[https://github.com/Fleshgrinder/php-src/blob/rfc/uuid/ext/standard/php_uuid.h|at GitHub]].</blockquote> 
- 
-<code c> 
-PHPAPI extern zend_class_entry *php_ce_UUID; 
-PHPAPI extern zend_class_entry *php_ce_UUIDParseException; 
- 
-PHPAPI typedef uint8_t php_uuid[16]; 
-PHPAPI typedef char php_uuid_hex[33]; 
-PHPAPI typedef char php_uuid_string[37]; 
- 
-PHPAPI const uint8_t PHP_UUID_LEN = 16; 
-PHPAPI const uint8_t PHP_UUID_HEX_LEN = 32; 
-PHPAPI const uint8_t PHP_UUID_STRING_LEN = 36; 
- 
-PHPAPI extern const php_uuid PHP_UUID_NAMESPACE_DNS; 
-PHPAPI extern const php_uuid PHP_UUID_NAMESPACE_OID; 
-PHPAPI extern const php_uuid PHP_UUID_NAMESPACE_URL; 
-PHPAPI extern const php_uuid PHP_UUID_NAMESPACE_X500; 
-PHPAPI extern const php_uuid PHP_UUID_NIL; 
- 
-PHPAPI typedef enum php_uuid_variant { 
-  PHP_UUID_VARIANT_NCS             = 0, /* 0b0xx */ 
-  PHP_UUID_VARIANT_RFC4122         = 1, /* 0b10x */ 
-  PHP_UUID_VARIANT_MICROSOFT       = 2, /* 0b110 */ 
-  PHP_UUID_VARIANT_FUTURE_RESERVED = 3, /* 0b111 */ 
-} php_uuid_variant; 
- 
-PHPAPI const uint8_t PHP_UUID_VERSION_1_TIME_BASED      = 1; 
-PHPAPI const uint8_t PHP_UUID_VERSION_2_DCE_SECURITY    = 2; 
-PHPAPI const uint8_t PHP_UUID_VERSION_3_NAME_BASED_MD5  = 3; 
-PHPAPI const uint8_t PHP_UUID_VERSION_4_RANDOM          = 4; 
-PHPAPI const uint8_t PHP_UUID_VERSION_5_NAME_BASED_SHA1 = 5; 
- 
-PHPAPI int php_uuid_parse(php_uuid *uuid, const char *input, const size_t input_len, const zend_bool throw); 
-#define php_uuid_parse_silent(uuid, input, input_len) php_uuid_parse(uuid, input, input_len, 0) 
-#define php_uuid_parse_throw(uuid, input, input_len) php_uuid_parse(uuid, input, input_len, 1) 
- 
-PHPAPI void php_uuid_create_v3(php_uuid *uuid, const php_uuid *namespace, const char *name, const size_t name_len); 
- 
-PHPAPI int php_uuid_create_v4(php_uuid *uuid, const zend_bool throw); 
-#define php_uuid_create_v4_silent(uuid) php_uuid_create_v4(uuid, 0) 
-#define php_uuid_create_v4_throw(uuid) php_uuid_create_v4(uuid, 1) 
- 
-PHPAPI void php_uuid_create_v5(php_uuid *uuid, const php_uuid *namespace, const char *name, const size_t name_len); 
- 
-PHPAPI zend_always_inline const php_uuid_variant php_uuid_get_variant(const php_uuid uuid); 
- 
-PHPAPI zend_always_inline const uint8_t php_uuid_get_version(const php_uuid uuid); 
- 
-PHPAPI zend_always_inline const int php_uuid_is_nil(const php_uuid uuid); 
- 
-PHPAPI zend_always_inline void php_uuid_to_hex(php_uuid_hex *buffer, const php_uuid uuid); 
- 
-PHPAPI zend_always_inline void php_uuid_to_string(php_uuid_string *buffer, const php_uuid uuid); 
- 
-</code> 
  
 === Why not PECL UUID? === === Why not PECL UUID? ===
Line 108: Line 51:
 The implementation consists of two new final classes in the global namespace. Supported generation algorithms are version 3, 4, and 5. Version 3 is provided for backwards compatibility with existing UUID implementations, RFC 4122 recommends version 5 over version 3 because of MD5’s higher collision probability compared to SHA1; even if truncated, as is the case for version 5 UUIDs. Versions 1 and 2 are not supported due to privacy/security concerns. Please refer to the RFC and Wikipedia article for further details on all these technical details. The implementation consists of two new final classes in the global namespace. Supported generation algorithms are version 3, 4, and 5. Version 3 is provided for backwards compatibility with existing UUID implementations, RFC 4122 recommends version 5 over version 3 because of MD5’s higher collision probability compared to SHA1; even if truncated, as is the case for version 5 UUIDs. Versions 1 and 2 are not supported due to privacy/security concerns. Please refer to the RFC and Wikipedia article for further details on all these technical details.
  
-<blockquote>Fully documented ''UUID'' class can be found [[https://github.com/Fleshgrinder/php-src/blob/rfc/uuid/ext/standard/stubs/UUID.php|at GitHub]].</blockquote>+<blockquote>Fully documented ''UUID'' class can be found [[https://github.com/Fleshgrinder/php-uuid/blob/php-7.1/src/UUID.php|at GitHub]].</blockquote>
  
 <code php> <code php>
Line 166: Line 109:
 </code> </code>
  
-<blockquote>Fully documented ''UUIDParseException'' class can be found [[https://github.com/Fleshgrinder/php-src/blob/rfc/uuid/ext/standard/stubs/UUIDParseException.php|at GitHub]].</blockquote>+<blockquote>Fully documented ''UUIDParseException'' class can be found [[https://github.com/Fleshgrinder/php-uuid/blob/php-7.1/src/UUIDParseException.php|at GitHub]].</blockquote>
  
 <code php> <code php>
Line 226: Line 169:
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-Both ''UUID'' and ''UUIDParsException'' are now globally defined classes, which might collide with user defined classes of the same name in the global namespace. However, the risk of the introduction of them is considered to be very low, since the global namespace should not be used by PHP users.+Both ''UUID'' and ''UUIDParseException'' are now globally defined classes, which might collide with user defined classes of the same name in the global namespace. However, the risk of the introduction of them is considered to be very low, since the global namespace should not be used by PHP users.
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
-Next PHP 7.x+7.3
  
 ===== RFC Impact ===== ===== RFC Impact =====
Line 248: Line 191:
  
 ===== Open Issues ===== ===== Open Issues =====
-==== Namespace ==== +None
-The discussion about namespace in PHP core is on ongoing dispute. This highly self-contained component could easily be provided from an internal namespace and thus lay the grounds for other things to come. This would require additional discussion, but possible namespaces in alphabetical order are (''UUID'' is the class): +
- +
-  * ''PHP\UUID'' +
-  * ''PHP\Core\UUID'' +
-  * ''PHP\Lang\UUID'' +
-  * ''PHP\Standard\UUID'' +
-  * ''PHP\STD\UUID'' +
-  * ''PHP\UUIDs\UUID'' +
- +
-Other variations, based on the premise that the reserved ''PHP'' namespace should be used only for things that are directly tied to the language itself (e.g. AST): +
- +
-  * ''Core\UUID'' +
-  * ''Lang\UUID'' +
-  * ''Standard\UUID'' +
-  * ''STD\UUID'' +
-  * ''UUIDs\UUID'' +
- +
-==== Doxygen Documentation ==== +
-The provided implementation uses [[http://www.doxygen.org/|Doxygen]] documentation for the C APIs. There were concerns about this, because PHP is currently undocumented and no standard way of providing documentation is in use so far. [[http://news.php.net/php.internals/99140|A discussion on php-internals]] was started to address this issue separately.+
  
 ===== Unaffected PHP Functionality ===== ===== Unaffected PHP Functionality =====
Line 274: Line 198:
 ===== Future Scope ===== ===== Future Scope =====
   * [[https://wiki.php.net/rfc/deprecate-uniqid|Deprecate and then remove uniqid and recommend the usage of UUIDs instead.]]   * [[https://wiki.php.net/rfc/deprecate-uniqid|Deprecate and then remove uniqid and recommend the usage of UUIDs instead.]]
-  * Addition of a ''toURI'' method, if we have a proper URL value object.+  * Addition of a ''toURN'' method, if we have a proper URL value object.
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
 Simple 50%+1 majority vote. Simple 50%+1 majority vote.
 +
 +<doodle title="Add UUID value object to PHP standard module?" auth="fleshgrinder" voteType="single" closed="false">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
Line 290: Line 219:
  
 ===== References ===== ===== References =====
-  * [[http://news.php.net/php.internals/99136|php-internals discussion]] 
-  * [[https://www.reddit.com/r/PHP/comments/6cyqtd/rfc_uuid/|Reddit discussion]] 
   * [[https://tools.ietf.org/html/rfc4122|RFC 4122]]   * [[https://tools.ietf.org/html/rfc4122|RFC 4122]]
   * [[https://en.wikipedia.org/wiki/Universally_unique_identifier|Wikipedia]]   * [[https://en.wikipedia.org/wiki/Universally_unique_identifier|Wikipedia]]
 +  * [[http://news.php.net/php.internals/99136|php-internals discussion]]
 +  * [[https://www.reddit.com/r/PHP/comments/6cyqtd/rfc_uuid/|Reddit discussion]]
 +  * [[https://twitter.com/AmbassadorAwsum/status/868097123627171842|Twitter discussion]]
 +  * [[https://wiki.php.net/rfc/class-naming|Class Naming RFC]]
  
 ===== Rejected Features ===== ===== Rejected Features =====
-None so far.+  * Doxygen Documentation ([[https://wiki.php.net/rfc/doxygen|corresponding declined RFC]]) 
 +  * Namespaces ([[https://wiki.php.net/rfc/namespaces-in-core|corresponding withdrawn RFC]])
rfc/uuid.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1

Page Tools