Download the PHP package fiber-interop/ext-scope without Composer
On this page you can find all versions of the php package fiber-interop/ext-scope. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download fiber-interop/ext-scope
More information about fiber-interop/ext-scope
Files in fiber-interop/ext-scope
Package ext-scope
Short Description The Scope class from the PHP RFC "Scope", as a PHP extension (PHP 8.2+).
License MIT
Homepage https://wiki.php.net/rfc/scope
Informations about the package ext-scope
fiber-interop/ext-scope
The Scope class from the PHP RFC: Scope, as an extension for
PHP 8.2 and later. A userland polyfill with the same class is fiber-interop/scope.
A Scope identifies the logical operation running code belongs to, such as an HTTP request, a
queued job or a transaction, and keeps that identity across fibers and generators. Service
containers can key request-scoped services by it, and libraries can keep per-operation state
without depending on a particular event loop.
The root scope is one object for the whole request (process, on the CLI). It is current in
{main} outside any run(), and in fibers and generators created there, so getCurrent() and
getScope() never return null. "Am I inside an operation" is
Scope::getCurrent() !== Scope::getRootScope(). To start something that belongs to no request
from inside one: Scope::getRootScope()->run(fn() => /* start the service */).
Release 0.4.0
0.4.0 implements the Scope RFC 0.9:
- A new scope starts empty (vote A):
$_GET,$_POST,$_COOKIE,$_FILES,$_REQUESTand$_SERVERare empty arrays in a newScope, instead of copy-on-write copies of its creator's. The root scope keeps the SAPI's arrays; fibers and generators still join the scope they are created in. - The session follows the scope (vote A, ini
scope.session): see "Session" below. - Locale and timezone start from ini (vote B): a new scope starts with the
date.timezoneini (or its fallback) and theintl.default_localeini, not with its creator's values. Scope::bind(Closure $closure): Closure: see "bind()" below.
Code that relied on a new scope inheriting its creator's superglobals, timezone or locale must now seed the scope.
Release 0.3.1
0.3.1 removes the per-call cost of loading the extension: generators now switch scope through calls compiled into generator bodies only, instead of an fcall observer that put every function call on PHP's observed path (#3). Same spec level as 0.3.0.
Release 0.3.0
0.3.0 is the "Scope spec level": the RFC draft plus both secondary votes. It contains the Scope class (getRootScope(), getCurrent(), run()), Fiber::getScope() and Generator::getScope(), per-scope request superglobals (vote A, ini scope.superglobals), per-scope default timezone and locale (vote B, ini scope.locale_timezone), and PIE metadata (composer.json, config.m4). The polyfill fiber-interop/scope 0.3.0 implements the same level.
Install
- PIE:
pie install fiber-interop/scope - PECL:
pecl install scopeA project that declares its own globalScopeclass cannot install this package.
Rules
$scope->run($callback)makes$scopecurrent while$callbackruns, and restores the previous scope afterwards, also on exceptions and fatal errors.- A fiber belongs to the scope current when it is constructed; a generator to the scope current when the generator function is called. Wherever either is resumed from, it runs in its own scope.
- Functions and closures run in their caller's scope.
- The scope never changes within an executing function, except through
run()calls it makes: across ayieldor aFiber::suspend(),Scope::getCurrent()returns what it returned before. - A scope carries no data. Keep per-scope state in a
WeakMapkeyed by the scope; entries go away once the scope is unreachable.
The RFC has the full motivation, the rules and prior art in other languages.
Request superglobals (secondary vote A)
$_GET, $_POST, $_COOKIE, $_FILES, $_REQUEST and $_SERVER follow the scope:
- In the root scope they are the SAPI's arrays, so code that never creates a scope sees today's behaviour.
- A new scope starts with six empty arrays, wherever it is created; whoever creates it seeds them, as a server does for each request. The creator's arrays are not copied.
- An assignment or write inside a scope changes only that scope's array. Reads see the current scope's array;
every fiber and generator of the scope shares it.
$_REQUESTis an array like the others, not a live merge. $_SERVERcarries both the request (REQUEST_URI,HTTP_*, ...) and the environment (PATH,DOCUMENT_ROOT, ...); both follow the scope the same way, so a new scope's$_SERVERstarts empty, environment entries included (read what you need from the root's$_SERVERbefore seeding).$_ENVdescribes the process and is not in scope.$_SESSIONfollows the scope's session (below).
When the current scope changes (run() entering or leaving, a fiber switch, a generator resuming or yielding) the
six arrays are moved between the scope's storage and the live EG(symbol_table) entries, which is where compiled
$_GET accesses read and write, and PG(http_globals)[TRACK_VARS_*] is re-pointed at the same array for C code
such as filter_input(). The cost of a switch is six symbol-table lookups and pointer moves; no array is copied.
The first scope creation makes the engine create the six lazily-created auto-globals (auto_globals_jit).
scope.superglobals (default 1, PHP_INI_SYSTEM) turns this off, so the vote can be shown independently
of the base proposal: with 0, all scopes share the SAPI's arrays (and the session, see below).
Session
When ext/session is loaded (it is an optional dependency), its request state follows the scope too:
- Swapped at each scope change:
$_SESSION(kept in step with ext/session'shttp_session_vars), the session id, status, the save handler module and its data (mod,mod_data), user save handlers (session_set_save_handler(): the handler callables, class name, open/implemented flags), the serialized original data (session_vars),send_cookie,define_sid,in_save_handler,set_handlerand the "started at" file and line. These are thePS()globals ext/session's RINIT and RSHUTDOWN reset; phasync'ssapi()swaps the same set. - Also swapped, as ini values re-applied through the entries' own handlers when two scopes differ:
session.name,session.save_path,session.cache_limiter,session.cache_expireand thesession.cookie_*entries (lifetime, path, domain, secure, httponly, samesite, partitioned), that is whatsession_name(),session_save_path(),session_set_cookie_params()andsession_cache_limiter()/session_cache_expire()change. - A new scope has no session (
PHP_SESSION_NONE), the ini values of those entries, and the save handler of thesession.save_handlerini (not a handler the creator set withsession_set_save_handler()). session_start()inside a scope starts that scope's session; all its fibers and generators share it.- A scope destroyed with its session active writes and closes it, as request end does; scopes still alive at request end are written and closed before ext/session's own shutdown handles the root's.
- Not swapped: other session ini entries (
session.save_handler,session.serialize_handler,use_*, gc settings) stay request-wide. While no scope has session data,$_SESSIONis an ordinary global.
scope.session (default 1, PHP_INI_SYSTEM) turns only this off; it is also off when scope.superglobals=0.
The session is not swapped on ZTS builds.
Default locale and timezone (secondary vote B)
date_default_timezone_get()/set() (ext/date) and Locale::getDefault()/setDefault() (ext/intl, only when intl is
loaded) follow the scope with the same rules as the superglobals: the root scope's values are today's (from ini and
the SAPI), a new scope starts with the ini values (date.timezone, or its fallback when unset; intl.default_locale,
or ICU's default at request start when unset), not with its creator's, a change
inside a scope affects only that scope, and code outside any scope sees no change. Fibers and generators of a scope
share its values.
How it is done, and what a switch costs:
- Timezone: the string
date_default_timezone_set()writes (ext/date'stimezoneglobal,NULLmeaning "use thedate.timezoneini") is swapped as a pointer. ext/date does not export its globals, butphp_date.hhas the struct and the module entry carries its address, found withzend_hash_str_find_ptr(&module_registry, "date")at startup. Each scope owns a private copy, becausedate_default_timezone_set()frees the old string. A switch is one pointer swap; no allocation. - Locale: ext/intl keeps no state of its own:
Locale::setDefault()writes theintl.default_localeini entry andLocale::getDefault()reads it. The extension holds a reference to the outgoing scope's value and, when the incoming scope's value differs, writes the entry exactly asLocale::setDefault()does (zend_alter_ini_entry). intl's globals (and headers) are not reachable from another extension, and going through the ini entry also keeps the engine's ini restore at request end correct. When two scopes have the same locale a switch is a string comparison; when they differ it allocates the new ini string (the one cost above two words). ini_set('date.timezone')is a request-wide ini, not scope state. A scope that has set its own timezone is not affected by it; a scope that never set one uses the ini value, which is the same for all of them.
scope.locale_timezone (default 1, PHP_INI_SYSTEM) turns this off independently of scope.superglobals:
with 0, all scopes share one timezone and one locale.
bind()
$scope->bind($closure) returns a new closure that runs $closure with $scope current, exactly as run() would,
whoever calls it and from whichever scope: the previous scope is restored when it returns or throws, and calls nest.
Generators and fibers created inside such a call belong to $scope. $closure itself is unchanged and still runs in
its caller's scope. Binding a closure that bind() returned replaces its scope rather than nesting:
$a->bind($b->bind($fn)) runs $fn in $a.
The returned closure is a native wrapper that uses $closure's own parameter info, so it keeps its signature
(by-reference parameters, defaults, variadics, return type, named arguments) and its $this and class scope; it is not
a variadic fn(...$a) => $scope->run($closure, ...$a), which would lose by-reference parameters. Reflection reports
it as an internal function with $closure's parameters; default values of its parameters are not visible to
Reflection, and it does not return by reference.
Per-scope state (prototype)
A follow-up to the RFC plans an internal API with two layers, so that extensions can give implicit state one copy per scope without changing anything for code outside scopes. This extension implements both, each with one user that is off by default.
Slots are for new code: an extension allocates a slot at startup, and scope_slot() returns
the current scope's copy of its state, created on first use. Outside any scope it returns the copy
of the root scope, so extension code never handles a missing scope; Scope::getRootScope() is
that root scope's object, and getRootScope()->run() makes the root's state current. A change of scope updates a
pointer. The demonstration user is a per-scope counter:
Swapped globals are a bridge for state that stays in an extension's globals: the globals always
hold the current scope's copy, and are swapped when execution moves between scopes, so code that
reads them directly keeps working. The demonstration user is json_last_error():
With it, json_last_error() and json_last_error_msg() are per scope: a new scope starts with no
error, the fibers of one scope share it, and requests no longer see each other's last error. Code
outside any scope sees the global, as without the extension. Swapping costs roughly 25–55 ns per
switch between fibers of different scopes; switches within one scope cost a pointer comparison.
Build
Cost
An extension can't add fields to the engine's fiber and generator objects, so this one keeps each
fiber's and generator's scope in a WeakMap. It follows fiber switches with the engine's fiber
observer. For generators it compiles scope switches into generator bodies only (a zend_extension
op_array handler, registered by the extension itself): the body switches to the generator's scope
when it starts, after each yield and at each catch and finally, and back to the resumer's scope
before each yield, yield from and return. An exception escaping the body is handled where the
generator is resumed (the Generator methods, its iterator for foreach, its destructor). Every other
function compiles exactly as without the extension, and there is no function call observer, so ordinary
calls cost nothing extra and the JIT stays on. Measured on PHP 8.5 (x86-64, php -n):
| Without | With | |
|---|---|---|
| Function call | ~25 ns | ~25 ns |
Generator step (valid(), current(), next()) |
~67 ns | ~98 ns |
Generator step (foreach) |
~37 ns | ~70 ns |
| Fiber resume and suspend | ~108 ns | ~163 ns |
An implementation in the engine stores the scope in the fiber or generator itself, which makes switching it a pointer assignment.
On PHP 8.2, a cycle that runs through a scope's WeakMap state back to a fiber of that scope isn't
collected: the cycle collector learned to see through WeakMap entries in PHP 8.3.
License
MIT