Fixing PHP streams

gistfile1.md

1. Interfaces for streams wrappers (clean up apis) - primarily userland, small to no BC
2. Resources -> objects (engine storage and attachment) - primarily core, some BC issues
3. finish implementations for callbacks - primarily feature addition
4. async IO features (see: jpauli) - feature addition with core implications and some BC issues
5. curl:// stream wrapper - feature addition (functionality of --with-curl-wrappers but with curl:// as prefix)
6. filtering api - buckets hard to use, user_filter class is api possessed - userland and BC
7. factory registration for wrapper creation - feature addition
8. ability to plug into transports from php land instead of requiring C extensions

Streams Interfaces:

Rough draft of initial interfaces for stream and stream features

https://github.com/auroraeosrose/streams-exercises/blob/usage-examples/interfaces.php

I'm not attached to names - but current implementation drops on top of current PHP streams wrapper implementation

Why is stream open not the constructor? Several reasons

1. streams are creating via factory - you'd want a NEW object for each file opened or http connection made - that's how OOP works
2. you need control over opening/closing a stream - you may want to do so several times with the same stream
3. for RAII the destructor should detect if the stream is open and close it

For those that don't quite understand how wrappers and wrapper registration is designed to work conceptually when you register a wrapper you're registering a DEFINITION of a stream - you're registering a CLASS when you use the stream somewhere in PHP (say, for example, file_get_contents) PHP uses the definition (class) to create a new stream resource (object instance) - it injects any parameters (context) that you've given into the stream class- the context is available in all methods in teh stream class

Allowing for registration of a factory callable along with your stream would simplify global injection of parameters without requiring setting of default context + merging of default + specific context in userland code

As discussed on Twitter, based on our experience in Drupal the ideal stream extension API would let us do something kinda-sorta like this:

file1.php:

file2.php:
class ModuleStreamWrapper extends ExtensionWrapper implements StreamWrapperInterface {}
class StreamStreamWrapper extends ExtensionWrapper implements StreamWrapperInterface {}
?>

file 3:

(That particular example is directly taken from Drupal, where we're trying to do exactly that in order to get to paths within modules that could live in a half-dozen places.)

That would also greatly help with PSR-7, which some are trying to have reimplement stream filters entirely rather than rely on PHP's native implementation. Michael Dowling is definitely someone to bring into this conversation.

Addendum: Based on the gist updates made as I was writing this, I think we're on the same page; the only difference is that step 4 is "the new object is created and used, duh". Looks like I learned something about stream implementations today. 😄

Awesome - so yes bring him in if you want, new ideas welcome... I guess I need to do a blog post or something about how streams wrappers conceptually map to objects - just with a REALLY ick pre-nice php objects way

@auroraeosrose Are you using snake-case named methods with redundant names to make BC easier? Because Stream::stream_open() seems strange otherwise where Stream::open() would suffice.

Yeah - the current implementation is designed to keep BC - would be acceptable for shoving into 5.6 or 5.7 - for PHP 7 names that actually follow PHP naming conventions would be better :)

Yea, makes sense to me. 👍