How should the ORM interact with state and withState() in particular?

[GuySartorelli]

In silverstripe/developer-docs#175 an upgrade guide for Fluent v4 => v5 => v6 was written. It included an assumption that behaviour had changed with how ORM operations interact with state and with withState() in particular (I'll include the exact markdown in a comment below).

In silverstripe/developer-docs#175 (comment) there was discussion about this - and it looks as though this behaviour is not working in the way we expected it to work.

We should write some unit tests to identify the current behaviour, and then the maintainers should decide what the correct behaviour is, and (if changes are required) when those changes should be made (based on if they're breaking changes, etc).
The answers to those questions may-or-may-not result in changes being needed in the upgrade guide.

TO DO

• Identify the current behaviour
• Decide what the correct behaviour is
• If changes are required, decide when to make them
• Upgrade documentation as required

[GuySartorelli]

Original upgrade guide content:

Fluent state

Fluent state is the mechanism responsible for maintaining the global current locale state. Any time you swap between locales, the fluent state handles this change.

In fluent 5 the way this state affects ORM actions changed.

	Fluent 4	Fluent 5	Fluent 6
Fluent state	Local	Global	Global

• Local - The current locale is set to the ORM query upon creation and
  persists even if the global state change later in the code execution
• Global - ORM query uses current locale from the global state at
  the time of execution

This affects any ORM calls inside a withState() callback which return a DataList. You should do a search in your codebase for calls to withState() and convert these to return the result of the ORM operation instead of the DataList. For example:

• return $list->column() or $list->getIDList()
• return an aggregated result such as $list->min() or $list->max()
• return $list->getIterator()
• return a specific record e.g. via $list->find() or $list->first()
• return an ArrayList (e.g. ArrayList::create($list->toArray()))

[warning]
You should also check you don't have any situations where you set the state without calling withState(), and then set it back again. These should be converted to use withState() instead.
[/warning]

Code examples {#fluent-state-examples}

Fluent v4 {#fluent-state-example-v4}

$list = FluentState::singleton()->withState(function (FluentState $state): DataList {
    $state->setLocale('my_locale_code');

    return MyModel::get();
});
// The $list DataList will give results for the 'my_locale_code' locale, not whatever locale is in the global scope.
$titles = $list->column('Title');

Fluent v5 and v6 {#fluent-state-example-v5-v6}

$titles = FluentState::singleton()->withState(function (FluentState $state): array {
    $state->setLocale('my_locale_code');

    // This returns results for the 'my_locale_code' locale.
    return MyModel::get()->column('Title');
});
// If you returned the DataList above, here it would give results for the locale in the global scope, not for 'my_locale_code'.

[tractorcow]

Fluent 4 5 and 6 are all local, as is my understanding. Only fluent 7 uses global state, since the dataquery params state API (or at least the part fluent uses) seems to have been removed in silverstripe 5.

[tractorcow]

See my answer at silverstripe/developer-docs#175 (comment)