webpatser / fledge-fiber
Non-blocking async drivers for the Fledge framework — PHP 8.5 only
Requires
- php: ^8.5
- daverandom/libdns: ^2.1
- guzzlehttp/guzzle: ^7.8 || ^8.0
- guzzlehttp/promises: ^2.5 || ^3.0
- guzzlehttp/psr7: ^2.4 || ^3.0
- illuminate/database: ^13.0
- illuminate/http: ^13.0
- illuminate/redis: ^13.0
- illuminate/support: ^13.0
- kelunik/certificate: ^1.1
- league/uri: ^7.0
- league/uri-interfaces: ^7.0
- revolt/event-loop: ^1.0
Requires (Dev)
- aws/aws-sdk-php: ^3.300
- illuminate/broadcasting: ^13.0
- illuminate/mail: ^13.0
- league/flysystem-aws-s3-v3: ^3.0
- livewire/livewire: ^4.4.8
- mockery/mockery: ^1.6
- pdphilip/elasticsearch: ^5.0
- pestphp/pest: ^4.0
- phpoption/phpoption: ^1.9
- phpunit/phpunit: ^11.0 || ^12.0 || ^13.0
- pusher/pusher-php-server: ^7.2
- symfony/http-client: ^7.4 || ^8.0
- symfony/postmark-mailer: ^7.4 || ^8.0
- vlucas/phpdotenv: ^5.6
Suggests
- ext-resp3: Install the resp3 PECL extension 0.2.0 or newer via PIE (`pie install webpatser/php-resp3:^0.2`) for faster RESP parsing on cache-heavy workloads; SocketRedisConnection picks it up automatically when loaded and falls back to the PHP parser for older versions.
- ext-sockets: Lets the pgsql Postgres driver close a connection mid-statement (a pool wait timeout, a server that stopped answering) without waiting for the server
- livewire/livewire: Required for concurrent Livewire component updates (^4.4.8)
- symfony/http-client: Required for FledgeSymfonyHttpClient, which runs Symfony HTTP consumers such as the mailer's API transports on the Fledge loop (^7.4 || ^8.0)
Provides
None
Conflicts
None
Replaces
None
- v13.43.0.2
- v13.43.0.1
- v13.42.0.3
- v13.42.0.2
- v13.42.0.1
- v13.40.0.4
- v13.40.0.3
- v13.40.0.2
- v13.40.0.1
- v13.39.0.1
- v13.38.0.4
- v13.38.0.3
- v13.38.0.2
- v13.38.0.1
- v13.38.0.0
- v13.36.0.4
- v13.36.0.3
- v13.36.0.2
- v13.36.0.1
- v13.35.0.5
- v13.35.0.4
- v13.35.0.3
- v13.35.0.2
- v13.35.0.1
- v13.35.0.0
- v13.34.0.1
- v13.34.0.0
- v13.33.0.0
- v13.32.0.0
- v13.31.0.0
- v13.30.1.1
- v13.30.1.0
- v13.29.0.3
- v13.29.0.2
- v13.29.0.1
- v13.29.0.0
- v13.26.1.2
- v13.26.1.1
- v13.26.1.0
- v13.25.0.2
- v13.25.0.1
- v13.25.0.0
- v13.24.0.0
- v13.23.0.1
- v13.23.0.0
- v13.22.1.0
- v13.22.0.0
- v13.21.1.0
- v13.20.0.2
- v13.20.0.1
- v13.20.0.0
- v13.19.0.3
- v13.19.0.2
- v13.19.0.1
- v13.18.0.0
- v13.17.0.0
- v13.16.1.0
- v13.15.0.0
- v13.14.0.0
- v13.13.0.0
- v13.12.0.0
- v13.11.2.0
- v13.11.1.1
- v13.11.1.0
- v13.9.0.1
- v13.9.0.0
- v13.8.0.1
- v13.8.0.0
- dev-main / 13.7.x-dev
- v13.7.0.2
- v13.7.0.1
- v13.7.0.0
- v13.6.0.0
- v13.5.0.0
- v13.4.0.2
- v13.4.0.1
- dev-release/13.19
- dev-feat/redis-cluster-support
This package is auto-updated.
Last update: 2026-11-19 16:12:06 UTC
README
Non-blocking async drivers for the Fledge framework. PHP 8.5 only.
Provides fiber-based database (MySQL, MariaDB, PostgreSQL), Redis, HTTP, WebSocket, filesystem, and parallel processing drivers that integrate seamlessly with Laravel's service container.
Requirements
- PHP 8.5+
- revolt/event-loop ^1.0
- fledge-framework v13.42.0.1 and later require fledge-fiber 13.42.0.1 or later (earlier v13 frameworks work with any fiber v13 release)
Installation
composer require webpatser/fledge-fiber
The FiberServiceProvider is auto-discovered. No manual registration needed.
Configuration
Set drivers in your .env:
DB_CONNECTION=fledge-mysql REDIS_CLIENT=fledge
Available database drivers:
| Driver | Database | Implementation |
|---|---|---|
fledge-mysql, fledge-mariadb |
MySQL, MariaDB | MySQL wire protocol in PHP |
fledge-pgsql |
PostgreSQL | PostgreSQL driver in PHP |
fledge-mysql-native, fledge-mariadb-native |
MySQL, MariaDB | pdo_mysql made fiber-aware by php-fiberio (see below) |
Driver option support
The drivers aim for config parity with Laravel's stock drivers. Everything below reflects what actually reaches the wire; options that cannot be supported fail loudly or are documented here rather than silently ignored.
Database
Honored beyond the basics: Postgres sslcert/sslkey/sslrootcert and keepalives* (libpq connection string), Postgres session settings (isolation_level, timezone, search_path/schema, synchronous_commit, charset) via libpq startup -c options so DISCARD ALL on pool checkout restores instead of wipes them, MySQL/MariaDB TLS via Pdo\Mysql::ATTR_SSL_CA/ATTR_SSL_CAPATH/ATTR_SSL_CERT/ATTR_SSL_KEY/ATTR_SSL_CIPHER in options (any of these present in options requests TLS, whatever its value; ATTR_SSL_VERIFY_SERVER_CERT alone never requests TLS and only modifies verification; TLS is skipped for unix sockets), ATTR_INIT_COMMAND (runs on every new pooled connection), and per-connection isolation_level/timezone on MySQL through SessionInitializingConnector.
Explicitly unsupported PDO attributes: ATTR_CASE (server column names always), ATTR_ERRMODE (the shim always throws, Laravel's default), ATTR_ORACLE_NULLS, ATTR_STRINGIFY_FETCHES (native types from the wire), ATTR_EMULATE_PREPARES (statements are always server-prepared), ATTR_PERSISTENT (pooling replaces it).
MySQL 5.7: there is no live server-version probe, so set 'version' => '5.7' in the connection config to get the NO_AUTO_CREATE_USER strict mode string.
Transactions on fledge-mysql, fledge-mariadb and fledge-pgsql are pinned per Laravel connection, not per fiber. While one fiber (or the main context) has a transaction open, a query, prepared-statement execute, begin, commit or rollback from any other fiber on that connection throws a LogicException instead of silently running inside it. Give concurrent fibers separate connections, or use the native drivers below, which keep transactions per fiber.
Native MySQL/MariaDB drivers (fledge-mysql-native, fledge-mariadb-native)
A pool of real pdo_mysql connections running on php-fiberio, one lease per fiber. Fiberio makes the stock PDO socket I/O yield to the Revolt event loop, so you get Laravel's own connectors, TLS, session settings and error shapes without the userland wire protocol. A fiber takes a connection for the duration of a query (or a whole transaction, or a cursor() until its generator ends) and gives it back afterwards. A fiber that finds the pool empty waits for a free lease, and fails with a RuntimeException after pool_wait_timeout.
When to use which driver
fledge-mariadb / fledge-mysql |
fledge-mariadb-native / fledge-mysql-native |
|
|---|---|---|
| Wire protocol | Implemented in PHP | Stock pdo_mysql (C) |
| Extra requirements | None | php-fiberio 0.3.0+, NTS PHP only |
| Transactions | Pinned per connection; other fibers get a LogicException |
Per fiber, each on its own lease |
| CPU per row, bulk read (10,000 rows) | 11.11 us | 0.63 us |
| CPU per row, bulk read (20,000 rows) | 6.55 us | 0.19 us |
Wall time, 32 fibers x SELECT SLEEP(0.05) |
0.057 s | 0.058 s |
Both overlap concurrent I/O equally well; the native drivers cost far less CPU per row on large reads. Numbers are from bench/database/results/local-mariadb11-2026-10-08.md (MariaDB 11.8, PHP 8.5.11, local TCP, scale 0.2, 5 runs). On single-row point lookups the native driver spent 60.76 us of CPU per row against 161.26 us for fledge-mariadb, but more than blocking stock pdo_mysql through Laravel (25.60 us), as it adds pool and lease handling.
Install fiberio
pie install webpatser/php-fiberio
- NTS builds of PHP only; the extension is v0.x (0.3.0 is the latest; the C extension is unchanged since 0.2.x). Source and releases: https://github.com/webpatser/php-fiberio.
- php-fiberio 0.3.0 or later is required.
- Without the extension the connector throws a
RuntimeExceptionnaming the install command. Set'fiberio' => 'optional'to fall back to blocking PDO with one logged warning instead.
Configuration
// config/database.php 'connections' => [ 'mariadb-native' => [ 'driver' => 'fledge-mariadb-native', // or 'fledge-mysql-native' 'host' => env('DB_HOST', '127.0.0.1'), 'port' => env('DB_PORT', '3306'), 'database' => env('DB_DATABASE', 'laravel'), 'username' => env('DB_USERNAME', 'root'), 'password' => env('DB_PASSWORD', ''), 'charset' => 'utf8mb4', 'collation' => 'utf8mb4_unicode_ci', 'pool_size' => 32, // max real connections (default 32) 'pool_idle_timeout' => 60, // seconds before an idle connection is closed (default 60) 'pool_wait_timeout' => 30, // seconds a fiber waits for a free lease (default 30) 'fiberio' => 'optional', // omit to require the extension ], ],
PDO::ATTR_PERSISTENT is rejected with an InvalidArgumentException: fiberio routes persistent streams to the blocking transport, and the pool replaces them.
Switching an existing app
- Install fiberio on every worker host (see above).
- Change
driverfromfledge-mariadbtofledge-mariadb-native(orfledge-mysqltofledge-mysql-native). Host, credentials and charset stay as they are. - Review the caveats below, especially TLS and test setup.
To roll back, change driver back. fledge-mysql and fledge-mariadb keep their wire-protocol implementation and stay available.
fiberio hooks (FLEDGE_FIBERIO_HOOKS)
With php-fiberio 0.3.0 or later the extension can also make sleep() and friends, DNS lookups and ssl:///tls:// client streams fiber-aware. The native connector enables them for the whole process through config fledge-http.fiberio_hooks, fed by the env var FLEDGE_FIBERIO_HOOKS:
FLEDGE_FIBERIO_HOOKS=sleep,dns,ssl # default: all
- Values: a comma list (or array) of
sleep,dns,ssl, orall.none,off,no,false,0and the empty string turn every optional hook off (plaintcp://andunix://stay hooked, which is what the driver needs). - Unknown names are ignored with one logged warning per process. If no valid name is left, the result is no hooks, never all.
- Precedence: the connection's own
fiberio_hookskey, thenfledge-http.fiberio_hooks(envFLEDGE_FIBERIO_HOOKS), thenall. - fiberio state is process-global and
enable()runs once, so the first native connection to connect decides the hooks for the whole process. Set it app-wide through the env var rather than per connection. - Needs php-fiberio 0.3.0.
- The setting is read through config, so it survives
php artisan config:cache. Runconfig:cacheagain after changing the env var.
Caveats and migration notes
Requirements
- TLS needs one of the TLS options. The native drivers use stock
pdo_mysql, which requests TLS when any ofATTR_SSL_CA,ATTR_SSL_CAPATH,ATTR_SSL_CERT,ATTR_SSL_KEYorATTR_SSL_CIPHERis present inoptions, whatever its value.ATTR_SSL_VERIFY_SERVER_CERT => falseon its own connects in plain text.fledge-mariadbuses the same trigger asfledge-mysql(its connector extends the MySQL one), so both behave alike. - Use a socket or IP address, or enable the DNS hook. Without the
dnshook (FLEDGE_FIBERIO_HOOKSwithoutdns), resolving a hostname blocks the whole process while connecting. With thednshook, the lookup runs on a helper thread and only the calling fiber waits. - No benefit under FPM without an event loop: requests run one at a time, so the pool just adds overhead.
Behaviour
- Fiberio is process-wide. Once enabled, every PHP stream client is affected, not only PDO. A stream shared by two fibers (Predis, SMTP transports, the Guzzle stream handler) now throws "stream is in use by another fiber" instead of blocking. Give each fiber its own client, or serialize access.
- Child fibers and transactions. A child fiber started inside a transaction runs on a separate lease, outside that transaction, so it cannot see the uncommitted rows (and with a small pool it waits until
pool_wait_timeout). A child fiber does not share the parent's session either:SETvalues or foreign key checks turned off in the parent do not apply to it. afterCommitcallbacks are routed per fiber. A fiber that is not inside its own transaction runs them immediately, even while the main context has a native transaction open (its writes already autocommitted on another connection). A pgsql orfledge-mariadbtransaction nested inside a fiber's native transaction gets its callbacks deferred to the native commit, and they are not dropped if only the inner transaction rolls back (stock Laravel attaches them to the innermost transaction). Rare, cross-connection only.- Custom transactions manager. Fledge wraps the
db.transactionsbinding only when it is Laravel's ownDatabaseTransactionsManager. An app's own subclass stays bound as is: native connections still keep their transactions andDB::afterCommit()callbacks per fiber, but callbacks registered on the container from a fiber (after-commit queued jobs, broadcasts) go to that subclass unwrapped. - Shared connection state.
pretend()andrecordsModifiedlive on the Laravel connection object and are shared by all fibers. - Bare
DB::getPdo()keeps its lease until the fiber's outermost scope ends, or until the callback ends (main context:DB::disconnect()) if its session changed, even if it is never used. Prefer the query builder. - Unbuffered queries: fetches are not ownership-checked, so only the fiber that ran the query may fetch from it.
Testing
- RefreshDatabase wraps only the main context. Other fibers use other leases and do not see the test transaction. A child fiber that waits on rows locked by the test transaction can hit error 1205 (lock wait timeout). Queue and event after-commit hooks bypass per-fiber routing under RefreshDatabase.
Operations
-
Exhausted pool. A fiber waiting on a full pool (for example
pool_size => 1with a second fiber) fails with aRuntimeExceptionafterpool_wait_timeout; the message names leaked leases. A fiber whose connection is pinned and that awaits child fibers needing the same pool can exhaust it (for examplepool_size => 1afterdisableForeignKeyConstraints()): the children fail afterpool_wait_timeout. -
Pool size is per pool.
pool_sizeapplies to each pool (write, read and direct), so a read/write split can open 2 to 3 times that many connections. -
Octane. The
DisconnectFromDatabaseslistener closes the pool, which fails open transactions of other in-flight requests when running a fiber server. -
Crashes. A fiberio crash is a C-level crash and takes the worker down. Keep it to workers you can restart (Octane, queue workers) and treat the v0.x version as such.
-
quote()doubles single quotes.pdo_mysqlwrites\'for a single quote, Fledge writes'', because the statement may run on another pooled connection than the onequote()looked at. To honourNO_BACKSLASH_ESCAPESit may open a pooled connection to read the server's SQL mode. The result is safe on any connection unless every known connection reportsNO_BACKSLASH_ESCAPESand the statement then runs on a connection without it, which only happens when the application changessql_modeitself. -
secure_key_retrievalexists only in Fledge and is off by default. Likepdo_mysql,fledge-mysqlandfledge-mariadbfetch the server's RSA key forcaching_sha2_passwordfull authentication andsha256_passwordover a connection without TLS, where a host on the path could substitute its own key. TLS, a pinned key (Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY, a PEM file path) or this option avoids that; with the option on, such a connect fails instead of fetching the key:'options' => [Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY => '/path/to/server-public.pem'], // or 'secure_key_retrieval' => true,
-
LOCAL INFILE follows mysqlnd.
Pdo\Mysql::ATTR_LOCAL_INFILEallows it;ATTR_LOCAL_INFILE_DIRECTORYalone allows only files whose real path lies inside that directory (a strictrealpathcheck; withATTR_LOCAL_INFILEon the directory is ignored but must still be openable). A refused request fails the query with error 2068 and leaves the connection usable.
Redis
Supported: scheme (tcp/tls/rediss/unix), host, port, path (unix socket, predis and phpredis styles), username/password (two-arg AUTH), database, timeout, read_timeout (values at or below 0 wait forever), context ssl options (peer_name, verify_peer, verify_peer_name, cafile, capath, verify_depth, ciphers, local_cert/local_pk/passphrase, security_level, peer_fingerprint), prefix (phpredis OPT_PREFIX semantics, including pub/sub channels), name (CLIENT SETNAME), tcp_keepalive (best effort, needs ext-sockets), command_retries, max_retries, retry_interval, backoff_algorithm/backoff_base/backoff_cap. Cluster seeds inherit TLS, auth, timeouts, and retry policy.
Tolerated without effect: scan (SCAN MATCH patterns are not auto-prefixed, matching phpredis defaults), persistent/persistent_id (connections are long-lived per worker), compression_level without compression.
Rejected loudly with UnsupportedRedisOptionException: serializer and compression (data would be unreadable across clients), pack_ignore_numbers, replication => sentinel (use a direct connection or predis), cluster failover => distribute/distribute_slaves (reads always go to a master), options.cluster other than redis.
HTTP client handler
FledgeHandler is a Guzzle handler backed by the async HTTP client, registered globally by FiberHttpServiceProvider (disabled under PHPUnit); opt out at runtime with Factory::globalHandler(null).
Supported request options: timeout, connect_timeout, version (1.0/1.1/2 with ALPN and 1.1 fallback), verify (true/false/CA file or dir), cert, ssl_key, crypto_method, proxy (string or array form including no; http:// via CONNECT and socks5://), decode_content, sink (path, resource, PSR-7 stream), stream, on_headers, on_stats (curl-shaped handler stats), delay, allow_redirects (all Guzzle sub-options, handled by RedirectMiddleware), plus everything Guzzle middleware implements above the handler. Transport failures reject as Guzzle exception types, so Illuminate\Http\Client\ConnectionException and the ConnectionFailed event work.
Known limitations: no ntlm auth, progress, debug, force_ip_resolve, Expect 100-continue handling, or raw curl options; no https://-scheme proxies; plain-HTTP proxying always tunnels via CONNECT; namelookup_time is always 0 in handler stats.
FledgeGuzzle: one stack for every Guzzle consumer
Fledge\Fiber\Http\FledgeGuzzle hands out Guzzle pieces that run on the Fledge handler instead of curl:
use Fledge\Fiber\Http\FledgeGuzzle; $stack = FledgeGuzzle::stack(); // HandlerStack: redirects, cookies, http_errors, prepare-body on FledgeHandler $client = FledgeGuzzle::client(['base_uri' => 'https://api.example.com']); $limited = FledgeGuzzle::client([], 8); // at most 8 open connections per host $factory = FledgeGuzzle::factory(8); // the shared AsyncClientFactory for that limit FledgeGuzzle::flush(); // drop the shared pools (tests)
stack(?int $perHost = null)returns a freshHandlerStackeach call (stacks are mutable);client(array $options = [], ?int $perHost = null)is aGuzzleHttp\Clienton it, and ahandlerin$optionswins.- Connection pools live in one
AsyncClientFactoryper per-host limit, shared by every stack and client, so keep-alive connections are reused across integrations.
Third-party integrations (on by default)
FiberHttpServiceProvider also puts the HTTP clients of these integrations on the Fledge handler, so their requests suspend only the calling fiber:
| Integration | What changes | Env flag |
|---|---|---|
The mail manager is replaced by FiberMailManager. HTTP transports (Postmark, Mailgun, Resend, ...) use a Symfony HttpClientInterface on the Fledge client. SES and SES v2 get an AWS SDK http_handler on the Fledge stack. |
FLEDGE_HTTP_MAIL |
|
| Broadcasting | The pusher and reverb drivers get client_options.handler on the Fledge stack. |
FLEDGE_HTTP_BROADCASTING |
| S3 | The s3 filesystem driver gets an http_handler through the AWS SDK's Guzzle bridge. No-op without aws/aws-sdk-php. |
FLEDGE_HTTP_S3 |
| Elasticsearch | PDPhilip's elasticsearch database driver is replaced by FledgeElasticConnection, built by ElasticClientFactory. No-op without pdphilip/elasticsearch. |
FLEDGE_HTTP_ELASTICSEARCH |
Behaviour change: all four are ON by default after upgrading. Mail, Pusher/Reverb, S3 and Elasticsearch traffic that used to go through curl, Symfony's client or the AWS default handler now goes through Fledge. Set the flag to false to return one integration to its previous client:
FLEDGE_HTTP_MAIL=false FLEDGE_HTTP_BROADCASTING=false FLEDGE_HTTP_S3=false FLEDGE_HTTP_ELASTICSEARCH=false
- All integrations are inactive while PHPUnit runs, so application test suites keep the stock managers and HTTP fakes.
- Config lives in
config/fledge-http.php, merged by the provider (there is novendor:publishtag). To change a value, set the env var or add your ownconfig/fledge-http.phpwith the keys you want to override. It holds scalars only, so it isconfig:cachesafe; runphp artisan config:cacheagain after changing an env var. - Per-host connection limits,
fledge-http.pool_per_host.*(nullmeans unlimited):mailnull,broadcasting8,s3null,elasticsearch8. A mailer's ownclient.max_host_connectionswins overpool_per_host.mail. - Per-mailer opt-out:
'client' => ['fledge' => false]in the mailer config keeps that mailer (and its SES handler) on the stock client. Other keys of a mailer'sclientarray are passed on as Symfony request options;max_pending_pushesis dropped. Withoutsymfony/http-clientthe stock client is used. - An
http_handlerset on an SES mailer, inservices.ses, or on an S3 disk, and aclient_options.handleron a Pusher/Reverb connection, are left alone. - Extend-order caveat: Pusher/Reverb and S3 are registered right after the broadcast and filesystem managers resolve. An app's own
Broadcast::extend('pusher')orStorage::extend('s3')in a providerboot()replaces the Fledge one (last extend wins). - Elasticsearch moved here from scrpr's
app/Support/Search. The handler is now passed throughsetHttpClientOptions(['handler' => ...])as well, becauseClientBuilderrebuilds its Guzzle client when SSL verification is off or a CA bundle is set, and used to lose the handler (and fall back to curl). - Elasticsearch hosts go through
ResurrectingNodePool: a host that hit a network error is skipped for 5 seconds and then tried again. When every host is dead and none is past its window the request fails fast withNoNodeAvailableException(no HTTP attempt, so pdphilip's default 3 retries cannot stack up timeouts on a single host); after the window the host is tried again. Per connection (top level or underoptions):resurrect_afterin seconds, ornode_poolas aNodePoolInterfaceinstance or class name (falsefor elastic-transport'sSimpleNodePoolwithNoResurrect). A pool set withsetNodePool()on the builder wins.
Symfony HttpClient adapter
Fledge\Fiber\Http\Symfony\FledgeSymfonyHttpClient implements Symfony's HttpClientInterface on the async client (requires symfony/http-client). Requests start when request() returns and responses created back to back overlap on the wire. Supported options: timeout, max_duration, max_connect_duration, verify_peer, verify_host, cafile, capath, local_cert, local_pk, passphrase, crypto_method, proxy, no_proxy, max_redirects, http_version (1.0, 1.1, 2), plus the body and header options Symfony normalizes itself.
- Unsupported options throw
InvalidArgumentExceptioninstead of being ignored:bindto,resolve,peer_fingerprint,ciphers,capture_peer_cert_chain,on_progress. verify_host => falseon its own throws, because the transport cannot skip only the host name check and would silently turn off chain verification. Useverify_peer => falseto turn verification off.cafiletogether withcapaththrows too; pass one.- Redirects are followed by the adapter. On a cross-origin hop only
Accept,Accept-Language,Accept-Encoding,User-Agentand (when the body is kept)Content-Typeare forwarded, so no credential header reaches the new host. NoRefereris added. - Proxy settings the transport cannot use (for example an
https://proxy) surface lazily as aTransportExceptionwhen the response is read, as with Symfony's own clients. The proxy is decided again for each redirect hop. - The body is always buffered in memory.
Cross-origin Referer
With allow_redirects.referer enabled, Guzzle 7 sends the full previous URL (path and query) to the new origin; only Guzzle 8 trims it. FledgeHandler now reduces the Referer on every redirect hop itself: origin only across origins, no userinfo or fragment. A Referer you set on the first request is left alone.
Rolling back the integrations
- Set the
FLEDGE_HTTP_*flag of the affected integration tofalse(or'client' => ['fledge' => false]for one mailer), runphp artisan config:cache, and restart workers (Octane, queue, Torque) so long-lived processes pick it up. - To drop the global Guzzle handler as well, call
Factory::globalHandler(null). - Native database driver: change
driverback tofledge-mariadb/fledge-mysql, or switch single fiberio hooks off withFLEDGE_FIBERIO_HOOKS(for exampleFLEDGE_FIBERIO_HOOKS=none), thenconfig:cacheand restart workers.
Differences from stock Laravel
Where the Fledge drivers deliberately or unavoidably behave differently from Laravel's stock drivers, as implemented.
Database
- MySQL/MariaDB TLS is requested when a TLS option is present.
fledge-mysqlandfledge-mariadbrequest TLS when at least one ofPdo\Mysql::ATTR_SSL_CA,ATTR_SSL_CAPATH,ATTR_SSL_CERT,ATTR_SSL_KEYorATTR_SSL_CIPHERis present inoptions, whatever its value (nulland''included), likepdo_mysql, which then refuses a server without TLS. - No TLS offered means no connection. When TLS is requested and the server greeting does not advertise SSL support, the connection fails with
SqlConnectionExceptionbefore any credentials are sent; it never falls back to plaintext. ATTR_SSL_VERIFY_SERVER_CERTalone does not enable TLS. It only modifies verification (falseskips peer verification) once one of the options above has requested TLS.- One pooled connection per fiber scope on
fledge-mysqlandfledge-mariadb.pdo_mysqlis one connection per PDO, soSET, user variables, temporary tables,GET_LOCKandLAST_INSERT_ID()carry over from one statement to the next. Fledge gives each fiber (and the main context) one pooled connection on its first statement, and its transactions run on it. The differences frompdo_mysql:- Under pool contention a pin whose session is provably unchanged goes back to the pool when another caller waits and the owner is between statements, so its connection can change between statements. A session-reading function in a later statement (
FOUND_ROWS(),ROW_COUNT(),CONNECTION_ID(),SHOW WARNINGS) may then read another session. UsePDO::lastInsertId(), which follows the fiber and not the connection. The statement straight after anINSERT,UPDATE,DELETEorREPLACEkeeps the connection, as do open transactions, unread rows and a prepared statement that has not run yet. - A statement is judged from its text. Session changes made by triggers or stored functions (also through a view) are not seen: the connection is not marked changed and is not reset, so such a change can go to the next fiber with the connection. A query that calls a stored function or any name that is not built-in on both MySQL 8 and MariaDB 11 (for example
point(),ANY_VALUE,MEMBER OF,uuid_to_bin,regexp_like,json_query), uses a user variable,SELECT ... INTO, a lock function,SQL_CALC_FOUND_ROWS, a temporary table, a backslash anywhere in the text, a/*!executable comment,--followed by a control character or a second statement counts as changing the session;MATCH (columns) AGAINST (...)(whatwhereFullTextemits;against(anywhere else is dirty), plain comments, optimizer hints, sized casts, math, date, JSON reader and read-only spatial functions and CTE column lists do not. A regex engine failure while judging counts as changing it too. - A fiber that changed its session holds a pool slot until its scope ends. Waiting for a slot ends after
pool_wait_timeout(default 30 seconds, see below), and a fiber with a changed session that awaits a child fiber needing a connection on a full pool waits until then; withpool_wait_timeout => 0it waits forever. - A changed session costs a reset on release:
COM_RESET_CONNECTION, then one query that re-applies the session settings andUSEof the configured database, two round trips. A clean pin goes back without a reset. A server withoutCOM_RESET_CONNECTION(MySQL before 5.7.3, MariaDB before 10.2.4, some proxies) gets its connection closed instead, so the next fiber opens a new one; one line is logged per process. - Transactions run at the session's isolation level, as with
pdo_mysql(the server default or the connection'sisolation_level). Earlier versions ran every transaction at READ COMMITTED. - Results are buffered when executed, as
pdo_mysqldoes by default. WithPdo\Mysql::ATTR_USE_BUFFERED_QUERY => falserows stream, and a second statement while rows are unread fails with error 2014, as inpdo_mysql.
- Under pool contention a pin whose session is provably unchanged goes back to the pool when another caller waits and the owner is between statements, so its connection can change between statements. A session-reading function in a later statement (
pool_wait_timeoutdefaults to 30 seconds on all three pools. Onfledge-mysql,fledge-mariadbandfledge-pgsqlit is the seconds a caller may wait for a connection (the wait on a full pool and the connect included, on Postgres also theDISCARD ALLreset); unset means 30, and 0, '0' or '' means no limit. A timeout throwsSqlExceptionwith code 2002, which Laravel reports as aQueryException; it is deliberately not treated as a lost connection, so Laravel does not reconnect into a second pool. A pool class built directly through the async API keeps no limit unlesswaitTimeoutis passed. Onfledge-mysql-nativeandfledge-mariadb-nativeit is the seconds a fiber waits for a free lease (default 30; a value of 0 or below throws anInvalidArgumentExceptionwhen the pool is built; the timeout throws aRuntimeException).- MySQL and Redis connects fail at once. A refused connect makes one attempt and throws, as
pdo_mysqland phpredis do; there is no socket-level retry (it used to add about 6 s). The connectors no longer use a globally setStream\socketConnector(); the async API accepts a connector (for examplenew SocketMysqlConnector(new RetrySocketConnector(new DnsSocketConnector()))) if you want retries. - The native PDO pool pins a lease whose session may have changed, then discards it.
pdo_mysqlhas no reset command (noCOM_RESET_CONNECTION), so onfledge-mysql-nativeandfledge-mariadb-nativea lease whose session may have changed stays pinned to its fiber for the rest of the fiber's scope (the whole request or job callback): its following statements run on the same connection and see their own session state, as with one stock PDO. When the scope ends the connection is discarded instead of returned and the pool opens a fresh one for a later lessee; session state never reaches another fiber. Dirty is decided per statement inNativePdo::prepare(),exec()andquery()with the MySQL classifier above (plus clean read-backs ofCONNECTION_ID(),DATABASE(),FOUND_ROWS(),ROW_COUNT()and savepoint statements), andsetAttribute()is dirty.quote(),getAttribute(),lastInsertId()andinTransaction()are clean, so Telescope or Debugbar do not cause reconnects.setAttribute()andgetAttribute(ATTR_SERVER_INFO)through a reference that no longer owns the lease throwLeaseOwnershipException. The differences from stockpdo_mysql:- Session state (
SET @x,Schema::disableForeignKeyConstraints(), temporary tables,GET_LOCK) lasts for the fiber's scope, not for the worker process: With a fiber per request or job (Fledge HTTP server, Torque) the next one starts with a fresh session. In the main context (artisan commands,queue:work, Horizon, Octane on Swoole, RoadRunner or FrankenPHP, PHPUnit) session state carries from job to job untilDB::disconnect(),purge()orDB::reconnect(), as with stock Laravel's single PDO; a lost-connection retry drops only the slot that failed. Write, read and direct slots pin on their own, so with a read/write split aSETon the write connection is not seen by a read, as with stock's two PDOs. - A pinned connection counts against
pool_sizeuntil the fiber's scope ends. The pinning fiber's own statements reuse its connection; other fibers wait for a slot up topool_wait_timeout. A fiber that changes its session costs one extra connection for its whole scope, not one per statement; a clean lease goes back without a round trip. - Read-back values of a clean lessee (
LAST_INSERT_ID(),ROW_COUNT(),FOUND_ROWS(),SHOW WARNINGS) stay readable by the next lessee. - A raw
DB::getPdo()that is never used holds its connection until the fiber's outermost scope ends, or until the callback ends (main context:DB::disconnect()) if its session changed, and a raw PDO held after a discard stays open outside the pool count. - Triggers, views and stored code are invisible to the text check, so a change they make can still reach the next lessee.
- Residual risks:
- When another context replaces the pool mid-request (for example the Octane
DisconnectFromDatabaseslistener under a fiber server), a fiber with a pinned connection continues on a fresh session without an error. Do not rely on session-level guards such asSET SESSION TRANSACTION READ ONLY,SET ROLE,sql_safe_updatesor a tenant variable surviving that. - A statement classified as session-changing holds its connection for the rest of the request or job, including slow external awaits, so size
pool_sizefor the number of fibers that change their session at once. - Long-lived main-context workers keep one pinned connection, and any held
GET_LOCK, until disconnect.
- When another context replaces the pool mid-request (for example the Octane
- Session state (
- An abandoned transaction is rolled back by the server. When a callback ends with a transaction open on the native pool, its lease is discarded (the connection is dropped, so the server rolls the transaction back) and the transaction's after-commit callbacks are dropped. On the amphp MySQL driver a pin with an open transaction is closed when its scope ends. Stock PDO would keep the transaction open until the request ends.
- MySQL text-protocol results return BIT as raw bytes. Unprepared statements (the text protocol) give a BIT column as the raw byte string; prepared statements give an integer. An unsigned BIGINT of 2^63 and above is a decimal string in prepared results (as mysqlnd returns it).
- Postgres resets a pooled connection only when its session may have changed. The pool runs
DISCARD ALLon checkout of a new connection or one that ran a statement the classifier cannot prove clean (SET,LISTEN,PREPARE, temporary tables, advisory locks, user functions, an abandoned or failed transaction); a clean connection is reused as it is.INSERT,UPDATE,DELETEandMERGEcount as dirty because of triggers, so a transaction with DML costs aDISCARD ALLon the next checkout. A failednotify()leaves its connection to be reset (a lost connection is closed). Function names with non-ASCII characters are never treated as built-ins. A function or rule behind a view or a trigger is invisible to the text check. - A fiber with a pinned native session fails once when its pool is replaced. When another fiber or context disconnects or reconnects the connection while a fiber holds a pin with changed session state (variables, locks, temporary tables), that fiber's next statement throws
LostConnectionExceptiononce and then runs on a fresh session. Stock Laravel reconnects silently and drops the session state. Clean leases move to the new pool without a word. A dirty pin whose pool was closed by another context keeps its connection open until the pinned fiber's (or the main context's) next statement,disconnect(), or the end of the fiber. - In-process browser tests on the native driver. Request fibers get their own connection and cannot see the test's uncommitted transaction, so
RefreshDatabaseandDatabaseTransactionsdo not work with the Pest browser plugin onfledge-mysql-nativeandfledge-mariadb-native. UseDatabaseTruncation, or run browser tests on the stock driver. - Postgres decodes user-defined types created later as strings. The type table is read once per process for each host, port, user and database and then reused by every connection to that database. A type created after it was read (a new enum, composite or domain) is decoded with the default text type, so it comes back as a string until the worker restarts. Enum and composite values are strings, as with
pdo_pgsql, and the cache is per database. On thepgsqlpath an array column whose type is in the type table is parsed into a PHP array, where thepqpath returns the'{a,b}'literal.
Redis
These reply shapes match phpredis; the differences listed after them do not:
- Inside
MULTI, a queued command returns the connection (also throughsetnx,hsetnxand the scan wrappers), somulti()->set()->incr()->exec()chains. exec()returns one reply per queued command. Failed commands, nil replies and nested nils arefalse.- A WATCH-aborted
EXECreturnsfalse. - A command Redis rejects while queueing (wrong arity, unknown command) returns
false, and the followingEXECABORTmakesexec()returnfalse. - In a pipeline, a failed command, a nil reply and nested nils (
MGETelements) arefalse, and aBLPOPorBRPOPtimeout is[]. - Inside an open transaction
evalis sent asEVAL(anEVALSHAwould only be queued, so itsNOSCRIPTfallback could not run). A nil result and nils inside result tables arefalse. - Commands through
__call(for examplefcall) map errors nested in an array reply tofalse. - Connection errors still throw.
Remaining differences:
executeRawkeeps a nil reply and nested nils asnull, and insideMULTIit still throws when Redis rejects the command while queueing.- Direct
command()calls outside a pipeline and a transaction keep nested nils asnull, as Laravel's ownmgetwrapper returns them. - A
BLPOPorBRPOPtimeout insideEXECisfalse, not[]. - Timeouts of other blocking commands in a pipeline (
BZPOPMIN,BZPOPMAX) arefalse, where phpredis returns[]. - A top-level error reply outside a transaction throws
QueryException; phpredis returnsfalse(for exampleincron a non-integer, anevalthat returns an error,rawCommandwith an unknown command). - Status replies are
'OK'in Fledge andtruein phpredis (set,setex,hmset, also inexec()and pipeline slots).multi()->set()->get(missing)->exec()gives[true, false]in phpredis and['OK', false]in Fledge. - A top-level nil from a command without a Laravel wrapper (
hget,lpop,zscoreand others through__call) isnullin Fledge andfalsein phpredis. hmgetreturnsnullfor missing fields in Fledge andfalseon stock Laravel.bzpopminoutside a pipeline: a timeout isnullin Fledge and[]in phpredis.- A pipeline run inside an open
MULTIreturns the connection in each slot (phpredis raises a fatal error there). - In a pipeline
HMGETreturns a list, where phpredis returns an array keyed by field. - Blocking commands run on their own connections.
BLPOP,BRPOP,BRPOPLPUSH,BLMOVE,BLMPOP,BZPOPMIN,BZPOPMAX,BZMPOPandXREAD/XREADGROUPwithBLOCKget a dedicated connection, so other fibers are not blocked behind them (phpredis blocks only its own process). Up toFledgeRedisConnection::BLOCKING_IDLE_LIMIT(2) idle dedicated connections are kept; only idle ones are capped, so N concurrent blocking calls open N sockets. A pipeline that holds a blocking command runs in order. InsideMULTIthe command stays on the transaction connection.disconnect()fails blocking calls in flight with the lost-connection exception and they are not retried (not on cluster links). xread()andxreadgroup()follow phpredis, including[]on aBLOCKtimeout.SELECTsurvives a reconnect. The link selects the database again after a reconnect, also for aSELECTqueued inMULTI(applied only when its ownEXECentry succeeded) and forexecuteRaw(['SELECT', n]). A link reconnects lazily on the next command afterQUIT, a server-side close or a closed connection.- The subscriber reconnects by itself. When the pub/sub connection drops, phpredis throws to the
subscribe()caller; Fledge's subscriber reconnects and resubscribes every channel and pattern on its own, after a short backoff (the default strategy: 0.1 s doubling to 1 s, back to the start once a subscription is confirmed or a message arrives; the connection'sbackoff_*options are not passed to the subscriber). A refused reconnect after an established connection dropped (a Redis restart) is retried for up to about 6 seconds before the subscriptions fail; a refused first connect fails at once. Messages published while it is disconnected are lost, because plain pub/sub has no replay. - A rejected channel raises Fledge's
QueryException, not\RedisException. A server error toSUBSCRIBEorPSUBSCRIBE(for example-NOPERM) fails thesubscribe()/psubscribe()call withFledge\Async\Redis\Protocol\QueryExceptioninstead of reconnecting into the same rejection. Only the subscriptions of that channel fail.
HTTP
- A request body of 1,000,000 bytes or more, or one with a
Transfer-Encodingheader and no known size, is streamed in 64 KiB reads instead of buffered; smaller bodies stay buffered. A streamed body cannot be replayed, so a user-supplied async client wrapped inRetryRequestsfails its retry. - On HTTP/1 a request whose write fails is never reused: the connection is closed. An early response, such as a 413 sent before the body was written, is still delivered in full before the close.
read_timeoutmaps to the client's inactivity timeout (the wait between reads).max_body_sizecaps the response body; without it there is no cap, as with Guzzle.connect_timeoutis capped attimeoutwhen both are positive, as curl does. Without aconnect_timeout(absent or 0) the connect and TLS handshake limit is 300 s, curl's own default, which a positivetimeoutstill caps.- A positive
timeoutbounds the whole request, as curl's total timeout does: the handler cancels the request attimeoutseconds, counted from the start, so the wait for a free slot in a connection-limited pool, the connect, the TLS handshake and the transfer all count. Without atimeout(absent or 0) nothing bounds the total; connect and TLS handshake still getconnect_timeouteach (or the 300 s default). stream => truewithoutread_timeoutusestimeoutas the idle bound. The transfer timeout stays armed while the body is read (the HTTP/1 body reader and the HTTP/2 per-stream watcher use it), sotimeoutalso caps the total time including body reads.- A coalesced DNS lookup cannot be cancelled by its callers. Callers asking for the same name and type share one query. It runs without any caller's cancellation and ends at the resolver's configured timeout (per attempt, over the configured attempts); a caller that is cancelled stops waiting, but the query keeps running for the others.
- The HTTP/2 client limits queued control frames. A server that floods PING, SETTINGS or pushed streams without reading the replies gets the connection closed (
ENHANCE_YOUR_CALM) at 1000 queued control frames. The limit cannot be set from client configuration. - Redirects in the async HTTP client's own follower (
FollowRedirects; not used on Laravel's HTTP client path, where Guzzle follows redirects): the request body is dropped on every redirect, a non-GET request is not followed on 307 and 308, and a HEAD request becomes a GET. - The streaming form parser returns raw key names (not on the Laravel request path). PHP rewrites spaces and dots in names and builds arrays from brackets; this parser only URL-decodes the key. Multipart parsing requires the body to start with the boundary (no preamble) and CRLF line endings (no bare LF).
- Multipart part headers are capped at 16384 bytes by default (
StreamingFormParser::DEFAULT_PART_HEADER_SIZE_LIMIT); a larger header block is answered with 400. PasspartHeaderSizeLimitto theStreamingFormParserconstructor to change it.
WebSocket
- The server caps what queues up behind a slow client. Each client may have 16 MiB and 65,536 messages waiting by default; past either, the client is closed with 1008 and its pending sends fail with
WebsocketClosedException. The caps are per client, there is no global cap. PassnullformaxQueuedBytesormaxQueuedMessagestoWebsocketClientGatewayto disable one. A single message larger than the byte cap is still delivered to a client with an empty queue.
Livewire
- Concurrent component updates are off by default (
fledge-livewire.concurrentisfalse). Blade and Livewire rendering rely on global state (view data stacks, component and slot stacks, shared sections) that interleaving fibers can corrupt. - To opt in, publish the config (
php artisan vendor:publish --tag=fledge-livewire-config) and setconcurrenttotrue, only when every component updated in one request is known to be safe to render interleaved.max_concurrent(default 10) limits how many components update at once.
What's included
| Module | Namespace | Description |
|---|---|---|
| Core | Fledge\Async |
Future, async/await, cancellation, pipelines |
| Stream | Fledge\Async\Stream |
Non-blocking byte streams, sockets, TLS |
| Database | Fledge\Async\Database |
MySQL, MariaDB, PostgreSQL wire protocols |
| Redis | Fledge\Async\Redis |
RESP protocol, pub/sub, TLS |
| HTTP | Fledge\Async\Http |
HTTP/1.1 + HTTP/2 client and server |
| WebSocket | Fledge\Async\WebSocket |
WebSocket client and server |
| File | Fledge\Async\File |
Non-blocking filesystem I/O |
| Parallel | Fledge\Async\Parallel |
Multi-process worker pools |
| DNS | Fledge\Async\Dns |
Async DNS resolution |
| Cache | Fledge\Async\Cache |
Cache interfaces + local implementations |
| Sync | Fledge\Async\Sync |
Mutexes, semaphores, barriers |
| Process | Fledge\Async\Process |
OS process management |
The Laravel integration layer lives under Fledge\Fiber\ and bridges async drivers to Laravel's database, Redis, HTTP, and Livewire systems.
PHP 8.5 Features
This library requires PHP 8.5 and uses:
#[\NoDiscard]on Future-returning methodsclone()with property overrides for immutable configsreadonly classfor value objects (76 classes)- Typed class constants
- First-class callable syntax throughout
Versioning
Follows Fledge versioning: v13.x.y.z where the first three digits match the Laravel version and the fourth is the fledge-fiber patch level.
License
Apache-2.0. Portions are derived from amphp (MIT); see LICENSE for the original notice.