Browse documentation

#Upgrade Guide

This document provides guidelines for upgrading between versions of Flow PHP. Please follow the instructions for your specific version to ensure a smooth upgrade process.

#Upgrading from 0.43.x to 0.44.x

#1) flow-php/etl-adapter-json - to_json()/to_json_lines() write list/map/structure/array entries as nested JSON

#2) flow-php/etl - Floe inferred schema keeps the first batch's nullability

Columns that may only become null in later batches, declare the schema explicitly: to_floe($path)->withSchema($schema).

#3) flow-php/types - detectType([]) returns list<null>

#4) flow-php/types - detectType() returns different types for arrays

#5) flow-php/types - cast() refuses values it used to coerce, fabricate or wrap

#6) flow-php/etl - FilesystemStreams replaced by FilesSink, and a failed run discards its sink

Build Config through Config::builder() / Config::default(). A Loader holding per-run state (an open stream, a writer, a counter) implements Discardable and drops that state in discard().

#7) flow-php/etl - RetryLoader no longer retries InvalidLogicException by default

To keep retrying every throwable:

write_with_retries($loader, retry_any_throwable(3));

#8) flow-php/etl - operations inside a Transformation answer for the whole stream

#9) flow-php/etl - to_branch()->withTransformation() drives its Transformation once over the whole stream

#10) flow-php/etl-adapter-doctrine, -postgresql - transactional loaders run closure() in a transaction

#11) flow-php/etl - Floe on-disk format v2, existing .floe files must be rewritten

Files written by 0.43.x cannot be read. Regenerate them from their source, or export them with 0.43.x to another format before upgrading.

#12) flow-php/etl - Floe rejects columns whose type is only known per value

Declare an element type, or declare the column with json_schema() when the shape is dynamic.

#13) flow-php/etl - Floe validates every value against its column type

#14) flow-php/etl - aggregate result type no longer depends on the value

#15) flow-php/etl - aggregates ignore a row missing the aggregated column

#16) flow-php/types - EnumType::isValid() requires an object

#17) flow-php/etl - filesystems are passed to sources and sinks, engine algorithms take a storage

#Filesystems

Two memory_filesystem() calls are two separate stores: pass the same instance to the writer and the reader.

#Filesystem telemetry

After:

$fs = traceable_filesystem(
    aws_s3_filesystem($bucket, $client),
    filesystem_telemetry_config($telemetry, $clock, filesystem_telemetry_options(trace_streams: true)),
);

data_frame()->read(from_csv(path('aws-s3://x.csv'), filesystem: $fs))->run();

#Engine algorithms

#Per-operation algorithm overrides

GroupedDataFrame::aggregate() stays variadic: $df->groupBy(['a'])->aggregate(sum(ref('b'))).

#Save mode, the CLI and the HTTP bridge

#18) flow-php/etl - equals() / notEquals() return null when either side is null

To keep the old result, switch to same() / notSame():

Before:

$df->filter(ref('a')->equals(ref('b')));
$df->filter(ref('a')->notEquals(lit(5)));

After:

$df->filter(ref('a')->same(ref('b')));
$df->filter(ref('a')->notSame(lit(5)));

same() compares with ===: over an integer column ref('i')->same(lit(1.0)) is false where equals() is true.

#19) flow-php/etl - execution modes are removed, a function given bad data throws

Before:

data_frame()->read($extractor)->withEntry('payload', ref('json')->jsonDecode())->run();

After:

data_frame()->read($extractor)->withEntry('payload', optional(ref('json')->jsonDecode()))->run();

#20) flow-php/etl - not(), all(), any() and isType() return null for a null operand

isNull(), isNotNull(), same(), notSame() and exists() still return true or false.

#21) flow-php/etl - expressions and steps are checked before the first row is read

Applies to frames read through from_data_frame() and to to_transformation() bodies: the inner error fails the outer run() / schema().

#22) flow-php/etl - functions return only values their column type can hold

#23) flow-php/etl - function arguments that decide the output type take plain values

#24) flow-php/etl - cast() accepts column types only

#25) flow-php/etl - EntryReference is renamed to UnresolvedReference and is immutable

#26) flow-php/etl - custom functions declare their output type and their children

Before:

final class Shout extends ScalarFunctionChain
{
    public function __construct(private readonly ScalarFunction $value) {}

    public function eval(Row $row, FlowContext $context): ?string
    {
        $value = (new Parameter($this->value))->asString($row, $context);

        return $value === null ? null : strtoupper($value);
    }
}

After:

final class Shout implements ScalarFunction
{
    use ScalarFunctionChain;
    use ResolvesFromChildren;

    public function __construct(private readonly ScalarFunction $value) {}

    public function eval(Row $row, FlowContext $context): ?string
    {
        $value = (new Parameter($this->value))->asString($row, $context);

        return $value === null ? null : strtoupper($value);
    }

    public function returns(): Type
    {
        return type_optional(type_string());
    }

    public function children(): array
    {
        return [$this->value];
    }

    public function withChildren(array $children): static
    {
        return new self($children[0]);
    }
}

#27) flow-php/etl - user callbacks removed, call() takes a ScalarFunction and a return type

Before:

$df->map(fn (Row $row): Row => $row->set(str_entry('name', $row->valueOf('name') ?? 'default')));

After:

$df->withEntry('name', coalesce(ref('name'), lit('default')));

Logic no scalar function expresses: implement Flow\ETL\Transformer and pass it to $df->with($transformer).

#28) flow-php/etl - Transformer requires bind()

Return new BoundStep($this, $output), where $output is the schema the step emits for $input.

#29) flow-php/etl - Extractor gains schema() and withSchema()

A source that cannot describe its output before reading throws Flow\ETL\Exception\SchemaNotDerivableException::extractor(self::class) from schema().

#30) flow-php/etl - Entry and the *_entry() functions are removed, a row is a name-keyed array under a Schema

Before:

$rows = rows(
    row(int_entry('id', 1), str_entry('name', 'Norbert')),
    row(int_entry('id', 2), str_entry('name', null)),
);

After:

$rows = rows(
    schema(int_schema('id'), str_schema('name', nullable: true)),
    row(['id' => 1, 'name' => 'Norbert']),
    row(['id' => 2, 'name' => null]),
);

#31) flow-php/etl - Rows holds only rows that match its schema

Before:

$adults = $rows->filter(fn (Row $row): bool => $row->valueOf('age') >= 18);

After:

$adults = new Rows($rows->schema(), ...array_filter($rows->all(), fn (Row $row): bool => $row->get('age') >= 18));

#32) flow-php/etl / flow-php/etl-adapter-excel - Entry parameters become the value and its Definition

#33) flow-php/etl - Config options move to the extractors or are removed

withMetadataColumns() is on from_csv(), from_json(), from_json_lines(), from_parquet(), from_text(), from_xml(), from_excel(), from_google_sheet(), from_google_sheet_columns() and from_floe().

#34) flow-php/etl - extractors yield batches

#35) flow-php/etl - LimitableExtractor replaced by LimitPushDown

#36) flow-php/etl - ErrorHandler answers per stage: extraction, transformation, loading

The error objects and the action enums are in Flow\ETL\ErrorHandler.

Before:

final class SkipInvalidBatches implements ErrorHandler
{
    public function throw(Throwable $error, Rows $rows): bool
    {
        return !$error instanceof InvalidArgumentException;
    }

    public function skipRows(Throwable $error, Rows $rows): bool
    {
        return true;
    }
}

After:

final class SkipInvalidBatches implements ErrorHandler
{
    public function onExtraction(ExtractionError $error): ExtractionAction
    {
        return ExtractionAction::propagate;
    }

    public function onTransformation(TransformationError $error): TransformationAction
    {
        return $error->cause instanceof InvalidArgumentException
            ? TransformationAction::skipBatch
            : TransformationAction::propagate;
    }

    public function onLoading(LoadingError $error): LoadingAction
    {
        return $error->cause instanceof InvalidArgumentException
            ? LoadingAction::skipLoader
            : LoadingAction::propagate;
    }
}

#37) flow-php/etl - Cache gains schema()

#38) flow-php/etl - data cached or serialized by 0.43.x cannot be read back

Clear persistent caches and regenerate stored serialize_to_string() payloads after upgrading.

#39) flow-php/etl - in-memory sources infer one nullable schema from the first 20,480 rows

InferredSchemaException is not a SchemaMismatchException; the mismatch is its getPrevious().

#40) flow-php/etl - Hydrator, array_to_row() and array_to_rows() require a Schema

#41) flow-php/etl / flow-php/types - autoCast() removed

Before:

df()->read(from_csv($path))->autoCast()->fetch();
df()->read(from_array([['id' => '1', 'total' => '10.5']]))->autoCast()->fetch();

After:

df()->read(from_csv($path))->fetch();
df()->read(from_array([['id' => '1', 'total' => '10.5']], schema(int_schema('id'), float_schema('total'))))->fetch();

from_array() types by PHP value: numeric strings stay ?string unless the schema is declared.

#42) flow-php/etl - a value a declared column refuses throws SchemaMismatchException

Replace catch (CastingException $e) around a read with catch (SchemaMismatchException $e).

#43) flow-php/etl - DataFrame::schema() describes the plan without running it

#44) flow-php/etl - printSchema() prints the plan's schema and takes no limit

#45) flow-php/etl - display() and printRows() render one table

#46) flow-php/etl - select() and groupBy() refuse an undeclared column

#47) flow-php/etl - renaming onto an existing column throws

#48) flow-php/etl - float values compare exactly

#49) flow-php/etl - Window and window functions are immutable

#50) flow-php/etl - group and join key extraction reads the schema

#51) flow-php/etl - a join producing a duplicate column throws SchemaDefinitionNotUniqueException

#52) flow-php/etl - Joiner takes JoinSide and no EntryFactory, Expression drop helpers removed

#53) flow-php/etl - a join against an empty side keeps that side's columns

#54) flow-php/etl - a global aggregate() over zero rows returns one row

#55) flow-php/etl - pivot() takes its values

Before:

$df->groupBy('date')->pivot(ref('product'))->aggregate(sum(ref('amount')));

After:

$df->groupBy(['date'])->pivot(ref('product'), pivot_values('A', 'B'))->aggregate(sum(ref('amount')));
// or
$df->groupBy(['date'])->pivot(ref('product'), discover_pivot_values())->aggregate(sum(ref('amount')));

A custom extractor read by discover_pivot_values() must implement Flow\ETL\Extractor\RewindableExtractor.

#56) flow-php/etl - unpack() / array_unpack() take the Schema of the columns they produce

Before:

$df->withEntry('row', ref('row')->unpack(['internal_id']));

After:

$df->withEntry('row', ref('row')->unpack(schema(int_schema('id'), str_schema('name'))));

A custom Flow\ETL\Function\ScalarFunction\UnpackResults function must return a StructureType of its columns from returns().

#57) flow-php/etl - on_each() requires an operand that declares its element type

#58) flow-php/etl - isIn() compares numbers loosely and refuses incomparable types

#59) flow-php/etl - Calculator::divide() always returns float

#60) flow-php/etl - DataFrame::partitionBy() removed, loaders partition, Rows carry no partitions

#61) flow-php/etl - filterPartitions() compares the raw string partition value

#62) flow-php/etl / flow-php/types - missing-column and type-mismatch messages changed

#63) flow-php/etl - pipeline and generator extractors and Schema::fromPipeline() removed

#64) flow-php/etl - until() stops at the first row failing its predicate

#65) flow-php/etl - UnserializeTransformer requires the payload schema

#66) flow-php/etl - Floe reader drops RowPadding, conform: and lenient:

#67) flow-php/etl / flow-php/etl-adapter-parquet - a Floe or Parquet glob checks every file against the first

#68) flow-php/etl and every package with DSL functions - documentation attributes leave the packages

No installable package ships Flow\Documentation\Attribute\*: ReflectionAttribute::newInstance() on them throws Attribute class "..." not found. Read them with getName() / getArguments().

#69) flow-php/etl / flow-php/types - TypeMerge moved to flow-php/types as TypeWidener

#70) flow-php/types - structure optional fields are declared inline with structure_element()

Regenerate any stored schema_to_json() output that contains a structure.

#71) flow-php/types - time, date, string and Json accept and refuse different values

#72) flow-php/types - StringTypeNarrower types compact digit dates as integer and month-only dates as string

#73) flow-php/filesystem - Partition takes a value and its type, encodes reserved characters and allows null

#74) flow-php/filesystem - SourceStream::readLines() strips the separator and yields nothing for 0 bytes

A custom SourceStream::readLines() must strip the separator, yield nothing for a 0-byte stream and yield an empty line as ''.

#75) flow-php/parquet - FLOAT32 values read without ext-arrow are no longer rounded to 7 decimals

#76) flow-php/parquet - FlatColumn::decimal() sizes FIXED_LEN_BYTE_ARRAY by the Parquet spec

#77) flow-php/postgresql - Client gains describe(), and execute() accepts ConvertedParameters

A custom Client::execute() binds ConvertedParameters::$values as they are, without a converter.

#78) flow-php/postgresql - arrays parsed, oid as integer, timetz without offset, duplicates cast by name

Applies to rows returned by Client::fetch*() and Client::cursor().

#79) flow-php/doctrine-dbal-bulk - Dialect requires maxBindParameters()

#80) flow-php/etl-adapter-csv, -json, -excel, -google-sheet - a read without a schema infers one schema

On from_google_sheet(), ->inferSchema(infer_schema()) without ->sampleSize() samples 20,480 rows, not 100.

#81) flow-php/etl-adapter-csv - cells are typed, not strings

Keep every column a string: from_csv($path)->inferSchema(infer_schema()->allStrings()).

#82) flow-php/etl-adapter-doctrine - from_dbal_*() type columns from the query

Applies to from_dbal_query(), from_dbal_queries(), from_dbal_limit_offset(), from_dbal_limit_offset_qb() and from_dbal_key_set_qb() without ->withSchema(). A missing table or column throws what the read throws (TableNotFoundException, InvalidFieldNameException, on SQLite DriverException); any other query the driver refuses to describe throws SchemaNotDerivableException with the DBAL exception as getPrevious(). Declare ->withSchema(...) to pick the types.

#83) flow-php/etl-adapter-doctrine, -postgresql - withPageSize() / withFetchSize() become withBatchSize()

#84) flow-php/etl-adapter-excel - text cells narrow to uuid, json and timezone, to_excel() writes date cells

Before:

to_excel($path)->withDateFormat('Y-m-d')->withDateTimeFormat('Y-m-d H:i:s');

After:

to_excel($path)->withDateFormat('yyyy-mm-dd')->withDateTimeFormat('yyyy-mm-dd hh:mm:ss');

#85) flow-php/etl-adapter-excel - requires openspout/openspout ~5.3.0

#86) flow-php/etl-adapter-google-sheet - FORMATTED_VALUE cells are typed, and '' reads as null

#87) flow-php/etl-adapter-http - response_body and request_body hold the raw body text

Decode in the pipeline: ->withEntry('response_body', ref('response_body')->jsonDecode()).

#88) flow-php/etl-adapter-json - schema_from_json_schema() rejects a property with more than one non-null type

Give the property a single type in the JSON Schema, or declare the column by hand: str_schema('v'), json_schema('v').

#89) flow-php/etl-adapter-json - keys outside the sample are dropped, missing keys are null

Applies to from_json() and from_json_lines() unless the row names one.

#90) flow-php/etl-adapter-json - from_json_lines() skips blank lines

#91) flow-php/etl-adapter-parquet - to_parquet() does not validate values against the Parquet schema

#92) flow-php/etl-adapter-postgresql - from_pgsql_*() type columns from the query instead of reading strings

Applies to from_pgsql_cursor(), from_pgsql_limit_offset() and from_pgsql_key_set() without ->withSchema(). A missing table, column, function, type or privilege throws PostgreSQL's QueryException, as the read does; a query that writes (a data-modifying WITH, SELECT ... INTO) throws InvalidArgumentException before any query runs. Declare ->withSchema(...) to pick the types.

#93) flow-php/etl-adapter-postgresql - pgsql_table_to_flow_schema() maps arrays, text-like types, oid, timetz

Applies to pgsql_table_to_flow_schema() and EntryTypesMap::toFlowType().

#94) flow-php/etl-adapter-postgresql - InsertQueryBuilder::build() takes the client's converters

#95) flow-php/etl-adapter-xml - from_xml() keeps each element as the source wrote it

#96) flow-php/cli - --schema-auto-cast removed, flow schema ignores the row window

#97) flow-php/cli - command classes name themselves with #[AsCommand]

Registering the commands in your own console application: drop the setName() / setAliases() calls.

#98) flow-php/flow-php-ext - the flow_php extension must be reinstalled

Reinstall it with the new release: pie install flow-php/flow-php-ext.

#99) flow-php/etl-adapter-csv - withSeparator(), withEnclosure() and withEscape() take a single byte

#100) flow-php/etl - array_expand() nested in an expression gives rows, and is refused outside withEntry()

#101) flow-php/array-dot - \ escapes every path grammar character, array_dot_steps() deprecated

#102) flow-php/array-dot - array_dot_set() and array_dot_rename() change only the addressed key

#103) flow-php/etl - array_get_collection() reads its keys as literal keys

#104) flow-php/etl - array_expand() over a null list gives no rows

#105) flow-php/array-dot, flow-php/etl - a nullsafe multimatch over an empty array reads null

#106) flow-php/filesystem - every filesystem matches glob patterns the same way

Files: data/flat.parquet, data/.hidden.parquet, data/.dir/x.parquet, data/date=2026-09-01/one.parquet, data/id=1/date=2026-09-01/two.parquet

Recurse with data/**/*.parquet, not data/**.parquet. webmozart/glob is no longer installed with flow-php/filesystem or flow-php/etl.

#107) flow-php/parquet - ParquetEngine::openForWrite() returns a ParquetFileWriter

#108) flow-php/etl-adapter-parquet - path-only partition columns leave the file body

#109) flow-php/etl-adapter-postgresql - a failed from_pgsql_cursor() read throws its own error and rolls back

#110) flow-php/etl-adapter-postgresql - from_pgsql_*() read exactly one read-only SELECT or VALUES statement

#111) flow-php/postgresql - declare_cursor() over SQL takes exactly one SELECT or VALUES

#112) flow-php/postgresql - SelectStatement::hasIntoClause() sees SELECT ... INTO in a UNION / INTERSECT / EXCEPT

#113) flow-php/postgresql - sql_to_*_query() and the pagination modifiers take exactly one read-only SELECT or VALUES

Applies to PaginationModifier, CountModifier and KeysetPaginationModifier passed to ParsedQuery::traverse().

#114) flow-php/etl-adapter-postgresql - from_pgsql_limit_offset() requires the query's own ORDER BY

#Upgrading from 0.42.x to 0.43.x

#1) flow-php/etl - to_transformation() expands a Transformation once per loader, not once per batch

Unchanged: any pipeline using ->collect(), drop(), select(), mask_columns(), batch_size(), batch_by().

#2) flow-php/telemetry - Tracer::span() no longer activates the span

Call sites relying on implicit nesting still compile and silently produce siblings. Rewrite each one that needs children:

Before:

$span = $tracer->span('parent');

try {
    // ...
} finally {
    $tracer->complete($span);
}

After:

$span = $tracer->span('parent');
$scope = $tracer->activate($span);

try {
    // ...
} finally {
    $scope->detach();
    $tracer->complete($span);
}

#3) flow-php/etl - window aggregates use the SQL default frame

On d = 2024-01-01, 2024-01-02, 2024-01-03, 2024-01-04 and s = 100, 200, 300, 400:

Restore the previous result:

sum(ref('s'))->over(window()->orderBy(ref('d'))->rowsBetween(unbounded_preceding(), unbounded_following()));

#4) flow-php/etl - count() over a window is SQL COUNT

On s = 100, 100, 300 ordered by a distinct column:

#5) flow-php/etl - partitionBy() no longer sets orderBy()

Add the ordering explicitly:

rank()->over(window()->partitionBy(ref('dept'))->orderBy(ref('salary')->desc()));

#6) flow-php/etl - WindowFunction::apply() receives a WindowContext

Implementations must no longer sort; $window->partition() and $window->frame() are already ordered.

#7) flow-php/postgresql - query recording moved to flow-php/symfony-postgresql-bundle

Applies to flow-php/postgresql users only through the bundle; Client\Telemetry is unchanged.

#8) flow-php/symfony-telemetry-bundle - cache pools and PSR-18 clients that were silently skipped are now traced

To keep the previous set of traced pools, exclude the framework's own:

flow_telemetry:
  instrumentation:
    cache:
      exclude_pools:
        - 'cache.system'
        - 'cache.validator'
        - 'cache.serializer'
        - 'cache.property_info'
        - '/^cache\.doctrine\..*/'
        - 'cache.http_client.pool'

#9) flow-php/types - a Type implementation's generic parameter is the value it represents

Update ListType, MapType, StructureType and ClassStringType parameters in your own docblocks.

#Upgrading from 0.41.x to 0.42.x

#1) flow-php/symfony-telemetry-bundle - messenger tracing simplified

The worker-cycle span and the trace: worker/both modes are gone; a consumed message is a process span and a produced one a send span. The messenger:consume worker loop is suppressed via instrumentation.console.exclude_commands - which now fully suppresses matching commands (previously it only skipped the console span) and defaults to ['messenger:consume'] - so transport-poll/idle-tick work does not surface and the long-lived messenger:consume console span is dropped. Per-message handler traces are still recorded. Set console.exclude_commands: [] to trace the worker loop.

#2) flow-php/symfony-telemetry-bundle - cache span names unified to dotted lowercase

Cache spans now match the DBAL/messenger convention (dotted lowercase, low cardinality). The {key} and {pool} that were baked into the span name move out of it - they were already available as the cache.key and cache.pool attributes. Rename these series in dashboards and alerts, and update any filters on the camelCase cache.operation values.

#3) flow-php/telemetry - Sampler::shouldSample() receives the parent Context

Custom Sampler implementations (including a sampler: { type: service } service in flow-php/symfony-telemetry-bundle) must update the signature and forward $parentContext to any delegated sampler.

#4) flow-php/telemetry - ResettableContextStorage removed; MemoryContextStorage::reset() removed

The context storage is no longer tagged kernel.reset in flow-php/symfony-telemetry-bundle; scope balance is maintained by attach/detach alone. A custom context_storage service no longer needs a reset() method.

#5) flow-php/symfony-telemetry-bundle - messenger tracing middleware auto-injected into all buses

The tracing middleware is now injected into every message bus automatically. If you previously added flow.telemetry.messenger.middleware to a bus's framework.messenger.buses.*.middleware list by hand, remove it to avoid duplicate spans.

#6) flow-php/symfony-telemetry-bundle - http_kernel.exclude_paths now suppresses the whole request

An excluded path now attaches the OpenTelemetry suppression key for the request's duration (through kernel.terminate), so lower-level auto-instrumentation and terminate-phase database writes no longer emit orphan root spans (e.g. the /_wdt toolbar fetch writing an audit row after its response). If you relied on those child spans being recorded for an excluded path, remove the path from exclude_paths.

#7) flow-php/postgresql, flow-php/symfony-postgresql-bundle - traceTransactions bool replaced by

transactionSpans mode

TransactionSpanMode::PER_OPERATION emits a short span per BEGIN/COMMIT/ROLLBACK; GROUPED (default) keeps the single long-lived transaction span.

The db.client.operation.duration metric now uses only low-cardinality dimensions: queries are tagged with db.system.name, db.namespace, db.operation.name, db.collection.name; transactions with db.system.name, db.namespace, db.operation.name (begin/commit/rollback), db.transaction.nesting_level. db.query.text, db.query.parameter.*, server.address and db.transaction.savepoint are no longer metric dimensions.

#8) flow-php/symfony-telemetry-bundle - DBAL spans, metrics and config aligned with the PostgreSQL client

Query spans now carry db.system.name, db.namespace, server.address, server.port, db.operation.name, db.collection.name, db.response.returned_rows and (on error) db.response.status_code, and the instrumentation emits db.client.operation.duration and db.client.response.returned_rows metrics. If you matched DBAL spans by their doctrine.dbal.* names, switch to the semantic names above.

#9) flow-php/symfony-telemetry-bundle - custom attribute keys moved out of reserved OTel namespaces

#10) flow-php/symfony-telemetry-bundle - HTTP spans aligned with the stable HTTP semconv

Applies to the HttpKernel server span and to the http_client/psr18_client client spans.

#11) flow-php/symfony-telemetry-bundle - messenger destination is the transport; metrics_duration_unit removed

#12) flow-php/phpunit-telemetry-bridge - test.* keys aligned with the OTel test registry; durations in seconds

#13) flow-php/filesystem, flow-php/etl, flow-php/postgresql - flow-custom keys under flow.*; UCUM units

#14) flow-php/telemetry, flow-php/psr18-telemetry-bridge - shared semconv constants; UCUM time units

#15) flow-php/symfony-telemetry-bundle - runtime_mode removed; terminate flushes, process end shuts down

Drop the runtime_mode key from flow_telemetry config and remove any WorkerModeDetector service overrides.

#16) flow-php/telemetry - Telemetry::registerShutdownFunction() holds a weak reference

Keep the registered Telemetry instance referenced for as long as it should be shut down at process end.

#17) flow-php/etl - SchemaValidator::isValid() replaced by validate(): ValidationContext

Custom SchemaValidator implementations must return a Flow\ETL\Schema\Validator\ValidationContext built from the missing, mismatched (MismatchedDefinition), and unexpected definitions they reject.

#18) flow-php/filesystem - Partition name and value forbid { and }

{name} in a path is now a partition placeholder resolved from partitionBy() columns; strip braces from partition values before partitioning.

#19) flow-php/etl - Cache stores only Rows; cache indexes are stored as Rows

Custom Cache implementations must adopt the Rows-only signatures.

#20) flow-php/etl - cache and serialization use the Floe (.floe) binary format; datetime subclasses rejected

Delete cache directories written by 0.41 - the old serialized payloads are unreadable. Convert DateTime/DateTimeImmutable subclasses to DateTime/DateTimeImmutable before caching or serializing.

A Floe file carries exactly one schema, and sort / join / group-by spill batches through it - a pipeline with a drifting or schemaless source must declare column types at the source so nullable columns carry a concrete type (DataFrame::match($schema) validates but does not retype values):

->read(from_array($data, schema(str_schema('email'), float_schema('discount', nullable: true))))

#21) flow-php/symfony-telemetry-bundle - HttpKernelSpanSubscriber takes a

RouteNamePathMap instead of the router

Applies only to direct construction; services wired by the bundle need no change.

#22) flow-php/etl - sort algorithm is an explicit choice; external sort is the default

To sort in memory, opt in explicitly:

data_frame(config_builder()->sort(memory_sort()))->read(...)->sortBy(ref('id'))->run();

#23) flow-php/etl - joins emit every matching right row and follow SQL semantics

Rows::joinRight() emits matched rows in left-probe order and unmatched right rows last.

#24) flow-php/etl - join buckets storage is configurable, spills to disk by default

To keep the right side in memory and preserve left row order:

data_frame(config_builder()->join(hash_join()->storage(new MemoryBuckets())))
    ->read(...)
    ->join(...)
    ->run();

#25) flow-php/etl - Serializer works on Rows and filesystem streams

#26) flow-php/etl - EntryFactory API reshaped

#27) flow-php/etl - Encoder/Hydrator contracts; hydrator configured on the context

cast() coerces untrusted values through the schema (null schema infers types); hydrate() instantiates trusted, already-typed values and requires a schema. A custom extractor reading raw values (CSV, JSON, XML, Excel, Text, Google Sheet, PostgreSQL, Doctrine) calls $context->hydrator()->cast(...); a self-describing source (Parquet, Floe) calls $context->hydrator()->hydrate(...).

Under a schema, entries emit in schema-definition order (was data-key order with missing columns appended); a schema column missing from the source hydrates as a typed null (was a StringEntry null); a column absent from the schema is dropped. When the flow_php extension is loaded, AdaptiveRowHydrator runs hydration natively - pin the pure-PHP engine with config_builder()->hydrator(new PhpRowHydrator()).

#28) flow-php/etl-adapter-csv, -json, -parquet, -xml, -excel, -doctrine, -postgresql, -seal, -text,

-google-sheet - per-format Encoders replace normalizers

Behavioural changes: CSV/JSON/XML/Excel/Seal date columns render with dateFormat (Y-m-d, was dateTimeFormat); XML date/time columns render (was InvalidArgumentException); Seal time columns render as microseconds (was null); Google Sheet _spread_sheet_id/_sheet_name are appended to the schema under putInputIntoRows() (were dropped when a schema was set); Excel now appends _input_file_uri under putInputIntoRows().

#29) flow-php/etl - null is a first-class NullEntry/NullDefinition; from_null metadata removed