BUG: Neos.Neos:MenuItem state is accessed differently than documented.

[jonaphil]

Is there an existing issue for this?

• I have searched the existing issues

There already was a bugreport on this topic, but it was closed by the opener shortly after without a reply from the core-team: #5712

I still consider this a bug, because it is a mismatch between Documentation and current implementation.

Current Behavior

To access the state as a string of a MenuItem I have to access it via item.state.value

                items = Neos.Neos:MenuItems
                
                renderer = afx `
                    <Neos.Fusion:Loop items={props.items} @children='itemRenderer'>
                         <Customer.Base:Components.Organisms.MainNavigation.ItemList.Item
                             label={item.label}
                             state={item.state.value}
                             link={item.uri}
                             subItems={item.subItems} />

The Documentation states that item.state returns a string: https://neos.readthedocs.io/en/9.2/References/NeosFusionReference.html#menuitems-item-properties

Expected Behavior

I can assess the state as string via item.state, like stated in the Documentation.

                items = Neos.Neos:MenuItems
                
                renderer = afx `
                    <Neos.Fusion:Loop items={props.items} @children='itemRenderer'>
                         <Customer.Base:Components.Organisms.MainNavigation.ItemList.Item
                             label={item.label}
                             state={item.state}
                             link={item.uri}
                             subItems={item.subItems} />

Steps To Reproduce

Use the Fusion Objects as above.

Environment

- Flow: 9.1.0
- Neos: 9.1.1
- PHP: 8.3

Anything else?

The Documentation states that the state of a MenuItem is of type string: https://neos.readthedocs.io/en/9.0/References/NeosFusionReference.html#menuitems-item-properties
This is also the behavior I would expect from the property.

On the contrary the current implementation returns a backed enum as state: https://neos.github.io/neos/9.0/Neos/Neos/Fusion/MenuItem.html#method_getState .

If I understand it correctly (please correct me if I'm wrong), the MenuItem-Object has getters for all values which can be accessed in fusion. (Which confused me in the first place, because in the code documentation there are a lot of links to methods, which don't exist directly in the code. listed Methods here: https://neos.github.io/neos/9.0/Neos/Neos/Fusion/MenuItem.html, aren't present here: https://github.com/neos/neos/blob/9.0/Classes/Fusion/MenuItem.php)

I would expect something like the following to solve the problem. So in Fusion the state can be accessed as a string, but in PHP, it is still possible to access the $state as backed enum MenuItemState.

Neos.Neos/Classes/Fusion/MenuItem.php
<?php
//... skip lines 2 - 43
    public function getUri(): ?string
    {
        return $this->uri;
    }

    public function getState(): ?string
    {
        if (isset($this->state)) {
            return $this->state->value;
        }
        return null;
    }
}

[dlubitz]

Thanks @jonaphil for this issue. This is correct, we changed the state internally using a enum. So we either need to change the docs or make the enum "stringable".

@mficzel was it intended to be used as enum in fusion with ->value?

Edit: AFAIS this class already had a __toString method before. Shall we bring this back?
300f84f#diff-69a95c75a1a1884e9608e502950908d543b1b325438165666a43c4dae7f1872cL68-L71

[mficzel]

Not much opinion from my side. Would be fine with _toString. I think we removed that when we made it an Enum without special intention.

[dlubitz]

Ok, now I got it. 🙈 Enums don't allow magic method __toString to be implemented. So we need to change the documentation here.
Adding a getter for state which returns the string value would make the enum useless.

[dlubitz]

I've decided to add the getter now! As the MenuItem is in Neos/Neos/Fusion namespace, we can assume the main purpose of this class is to provide Fusion functionality, which does not take any advantage of type safety. Please check the PR.

Another advantage: It's compatible with Neos 8 Fusion.

[dlubitz]

Sorry. But after creating the PR I noticed the drawback of this solution. With the new getter, the access over the enum is not possible anymore. Which would break all implementations of the enum-way. So I updated the docs now accordingly.