Mark Fusion prototypes/properties deprecated

Creating Neos & Flow Documentation
1

This is mainly a follow-up to Documenting Fusion (but I didn’t want to revive this old post):

Today I stumbled upon the fact that we have Neos.Fusion:UriBuilder and Neos.Fusion:ActionUri and I was wondering about the differences between the two until I found out that the former was deprecated 4 years ago.
Inspite of that, it is still present in the Neos 9.2 code base.

That made me wonder: Did anyone experiment further or implement a way to mark Fusion prototypes and/or properties deprecated as discussed in the original post?

1 Like
2

Could a meta attribute in the prototype like @deprecated work?
With an optional flag to raise a warning or error?
Not sure how much that costs in the parser.

Could also be useful when cleaning up larger projects.

3

Ah seeing @deprecated reminded me of the ideas regarding fusion documentation :grinning_face_with_smiling_eyes: :

prototype(Vendor.Package:Thing) {
    @deprecated {
        reason = "things are no longer relevant"
        replacement = Vendor.Package:Bla
    }
}

How about a non-invasive implementation like:

prototype(Neos.Fusion:UriBuilder) {
    @context.deprecated = Neos.Fusion:DeprecationMarker
}

with a Fusion Object (Implementation) of:

prototype(Neos.Fusion:DeprecationMarker) {
    @class = "...\DeprecationMarkerImplementation"
    logLevel = "warn"
    reason = null
    replacement = null
}

class DeprecationMarkerImplementation extends AbstractFusionObject {
    public function evaluate() {
        $parentFusionObjectName = $this->getParentFusionObjectName();
        $parentFusionPath = $this->getParentFusionObjectPath();
        // $reason = $this->getReason();
        // $replacement = $this->getReplacement();

        $message = sprintf('The Fusion object "%s" is deprecated and should not be used anymore.\nUsed in: %s', $parentFusionObjectName, $parentFusionPath);

        $this->logger->log($message, $this->getLogLevel());

        return $message;
    }
}

Its not ideal but easy to implement and not that bad in my opinion.

And when we have a @deprecated we can use it to mark Neos.Fusion:DeprecationMarker itself as deprecated :grinning_face_with_smiling_eyes:

1 Like
4

thanks @sjsone for your nice ideas;) I like that we dont need to implement anything new - though just for the UriBuilder deprecation id prefer a simple deprecation log from within the PHP in \Neos\Fusion\FusionObjects\UriBuilderImplementation

And even better would obviously be an automated rector migration of all the usages at some point;)