php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #32535 Are stream names URLs?
Submitted: 2005-04-01 17:01 UTC Modified: 2005-04-04 08:03 UTC
Votes:1
Avg. Score:1.0 ± 0.0
Reproduced:0 of 0 (0.0%)
From: a at b dot c dot de Assigned:
Status: Not a bug Package: Documentation problem
PHP Version: 5.0.3 OS: *
Private report: No CVE-ID: None
 [2005-04-01 17:01 UTC] a at b dot c dot de
Description:
------------
As indicated several times in the manual, the "filenames" that result from using stream wrappers are to be regarded as URLs, just as http, ftp and file schemes already are.

However, ALL such wrappers separate the scheme (what the manual refers to as the "protocol" from the rest of the URL with "://" - an example being the "var://myvar" in the example of the stream_wrapper_register() page.

This conflicts with RFC3986, the official specification for URIs (of which URLs are a subclass). The separator is just ":"; the double slash should only appear if what follows is a hierarchical structure in the sense given in section 3 of that document.

This is explicitly stated as improper in RFC2718, section 2.1.2 (which refers to the previous URI standard, RFC2396).

If these streams are supposed to be URLs, then the above example from the manual should read "var:myvar".


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2005-04-02 08:08 UTC] sniper@php.net
reclassified

 [2005-04-02 13:16 UTC] nlopess@php.net
I can't see any problem in the documentation. Everything about wrappers is well explained.
 [2005-04-02 13:23 UTC] betz@php.net
Nuno,

your statement does not anwser anything, sorry.
So you are saying that the current docs are in line with the mentioned RFC`s?
Yes or no?

Friedhelm
 [2005-04-02 22:41 UTC] jmcastagnetto@php.net
From RFC 3986:

'...
The term "Uniform Resource Locator" (URL) refers to the subset of URIs that, in addition to identifying a resource, provide a means of locating the resource by describing its primary access mechanism (e.g., its network "location").
...'

I do not see the conflict, the use of URL syntax is akin to the use of the valid location address of a file in a local filesystem, i.e. (as mentioned in the document quoted above):

'...
URIs that identify in relation to the end-user's local context should only be used when the context itself is a defining aspect of the resource, such as when an on-line help manual refers to a file on the end-user's file system 
(e.g., "file:///etc/hosts").
...'

A URN is also an URI (from which URLs are also a subset), and in that case, the syntax mentioned by the user is valid, although URNs are names, and usually used for resources without regard to their accessibility. For example, URNs are  used for LSIDs to refer to unique DNA sequences.
 
Furthermore, in 1.2.3, it is said:

'...
The generic syntax uses the slash ("/"), question mark ("?"), and number sign ("#") characters to delimit components that are significant to the generic parser's hierarchical interpretation of an identifier. In addition to aiding the readability of such identifiers through the consistent use of familiar syntax, this uniform representation of hierarchy across naming schemes allows scheme-independent references to be made relative to that hierarchy.
...'

In any case, to make it more consistent, we should use then:

stream://authority/path/to/remote/fileorresource

where authority, can be the name of a server.

accordingly, if addressing a local resource:

stream:///path/to/local/resource

All of these will require modification of the code for handling stream names.


 [2005-04-03 16:03 UTC] a at b dot c dot de
Well, to quote the cited section of RFC2718:

2.1.2 Improper use of "//" following "<scheme>:"
Contrary to some examples set in past years, the use of double slashes as the first component of the <scheme-specific-part> of a URL is not simply an artistic indicator that what follows is a URL: Double slashes are used ONLY when the syntax of the URL's <scheme-specific-part> contains a hierarchical structure as described in RFC 2396.  In URLs from such schemes, the use of double slashes indicates that what follows is the top hierarchical element for a naming authority.  (See section 3 of RFC 2396 for more details.)  URL schemes which do not contain a conformant hierarchical structure in their <scheme-specific-part> should not use double slashes following the "<scheme>:" string.

This has not changed with RFC3986. Note, too, the eight examples given in section 1.1.2 of 3986; three do not have the requisite hierarchical structure, and hence do not have //.
 [2005-04-04 08:03 UTC] a at b dot c dot de
Withdrawing the original report: it _is_ a documentation problem as reclassified. The examples shouldn't be using // indiscriminately (as in the "var://myvar" example), but only when appropriate. The distinction should be made, otherwise broken usages of parse_url() would become common (as in the given example, where the indicated variable name is in the "host" part of the URL, rather than the "path").

Nowhere is it actually stated how PHP decides which wrapper to use - the fact that it reads up to ':' (and not '://') is only _implicit_. No mention is made of the fact that the scheme name must not contain ':' (which one might be led to expect is possible if the scheme only ends with a "://"; especially since it would be succesfully registered. But that's a story for another bug (#32563).

Rewriting the documentation to use URL terminology ("scheme" rather than "protocol", for example) may also be a good idea.
 
PHP Copyright © 2001-2019 The PHP Group
All rights reserved.
Last updated: Mon Sep 16 06:01:27 2019 UTC