mcstreetguy/fusion-debugger

A debugger plugin for Neos.Fusion.

MCStreetguy.FusionDebugger

A small plugin for the awesome Neos CMS, to improve debugging of Fusion DSL code.

---

• Overview
• Installation
  • Usage outside of Neos
  • Troubleshooting
    • Invalid controller class name "". Make sure your controller is in a folder named "Command" and it's name ends in "CommandController"
• Reference
  • Commands
    • fusion:debugprototype
    • fusion:showobjecttree
    • fusion:lint
    • fusion:listprototypes
  • Configuration
    • fusionFilePathPatterns
• Versioning
• Authors
• License

Overview

What is this plugin capable of?

• Debugging fully merged Fusion prototype definitions
• Visualizing (parts of) the combined Fusion object tree
• Linting Fusion files for syntax errors

Why do I need it?

Did you ever came across some really strange rending issue while you created a page in Neos? And did you ever told yourself: "Why the actual hell is this happening? It's supposed to do something different."
Well then you probably know about the reasons behind this plugin, it's improved debugging.

It's currently not possible in common Neos installations to have a closer look behind the scenes of Fusion rendering. It parses some code, does some magic and then hopefully your expected result will appear. But what happens actually in between?
To get rid of that uncertainty this Plugin allows you to visualize what you normally won't see: the merged Fusion prototype configuration and the combined object tree.

Installation

Install the plugin by requiring it through composer:

composer require --dev mcstreetguy/fusion-debugger

If composer refuses to install the plugin, try requiring a specific version of it. The major version of this project will always work with the corresponding Neos release. We support all Neos versions ranging from 3.0 upwards officially, although every version below 7.0 is considered legacy at this point and won't receive updates or new features anymore.

composer require --dev mcstreetguy/fusion-debugger:^8.0   # for Neos v8.x
composer require --dev mcstreetguy/fusion-debugger:^7.0   # for Neos v7.x
composer require --dev mcstreetguy/fusion-debugger:^5.0   # for Neos v5.x (legacy)
composer require --dev mcstreetguy/fusion-debugger:^4.0   # for Neos v4.x (legacy)
composer require --dev mcstreetguy/fusion-debugger:^3.0   # for Neos v3.x (legacy)

The plugin provides a seperate backport version, which omits typehinting to be compatible with older PHP and Neos 2.3:

composer require --dev mcstreetguy/fusion-debugger:dev-backport

Usage outside of Neos

As the plugin only relies on neos/flow and neos/fusion as dependencies, you can actually use it outside of Neos projects as long as both required components are available. Testing this is currently an ongoing process, but any feedback on compatibility outside Neos is greatly appreciated. If you come across any issues not covered in the troubleshooting section below, please report them.

Troubleshooting

Invalid controller class name "". Make sure your controller is in a folder named "Command" and it's name ends in "CommandController"

This error happens only straight after installing the plugin as this corrupts the internal code caches of Flow in some way.
We couldn't locate the origin of this problem yet but hope to resolve it asap! Until then we recommend force-clearing the application caches after requiring the plugin through composer, as the automatic graceful clear during the installation is what probably causes this problem to arise.

/path/to/flow flow:cache:flush --force

In some edge cases it might happen that the entire Flow CLI stops working upon installation. In that case you are required to manually empty the corresponding Data/Temporary directory, that will get Flow running again. If you are uncertain which directories to remove, you may also delete the entire directory at once, causing Flow to regenerate it fully.

Reference

Commands

The plugin provides several commands to the Flow CLI. These are listed below for reference. Please see the respective help pages for more detailled information.

fusion:debugprototype

mcstreetguy.fusiondebugger:fusion:debugprototype [--no-color] [--no-flatten] <prototype>

Reads the definition of the requested prototype from the __prototypes key in the parsed object tree and resolves the contained prototype chain very carefully so that the result contains all properties, either inherited or explictely defined. For better readability, this command also includes something similar to syntax highlighting as several parts of the built tree are colored (such as eel expressions, further prototype names or just plain strings). Furthermore it flattens the resulting data by removing empty properties and combining the internal properties for e.g. plain values (as these are stored with three properties but could be displayed directly without an array structure). These additional behaviour can be suppressed by specifying the options --no-color or --no-flatten if it corrupts the resulting data or your terminal does not support ANSI colors.

fusion:showobjecttree

mcstreetguy.fusiondebugger:fusion:showobjecttree [--path <path>]

Builds the object tree from all Fusion files and displays it in an ASCII tree structure (excluding the __prototypes key as we got the above command for that). You can optionally provide a dot-separated path that will be loaded instead of the whole tree. (e.g. ./flow fusion:showobjecttree --path root.page)

fusion:lint

mcstreetguy.fusiondebugger:fusion:lint [--package-key <packageKey>] [--verbose] [--quiet]

Checks all Fusion files individually for syntax errors and lists the incorrect files with their associated package and file path. This command was intended to programmatically check the correctness of the Fusion source code and is in fact still an experiment but listed for the sake of completeness.

fusion:listprototypes

mcstreetguy.fusiondebugger:fusion:listprototypes [--no-format]

Lists all known Fusion prototype names.
If the --no-format option is specified, the list will lack any bullets and return unsorted.

Configuration

The plugin comes with minimal configuration options available. These are listed below for reference.

fusionFilePathPatterns

An array of file path patterns used to search for Fusion files that will be loaded.
The default path resource://@package/Private/Fusion/ is already present for ease of use. If your setup involves Fusion files at other locations as the default one provide these here.

The following placeholders can be used inside the pattern and will be exchanged with real values upon evaluation:

Placeholder	Description
@package	The current package key from where the fusion gets loaded.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Maximilian Schmidt - Owner - MCStreetguy

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details

fusion-debugger's Issues

Add support for `__stopInheritanceChain` property

Currently, when unsetting a path in Fusion through my.path > the engine sets a meta-key for that path, named __stopInheritanceChain, to identify such "emptied" values. That key is currently not flattened by the plugin. Would be better if it could be parsed too.

Verified with neos/fusion v5.3.0

[BUG] '0' interpreted as '<emtpy>' in flattened prototype debug-view

Describe the bug
In some cases the library interprets the number 0 as the null constant, resulting in the overview showing <empty> for the property, even if it should actually be a numeric value.

To Reproduce
Steps to reproduce the behavior:

1. Create a prototype and assign one of it's properties the static value 0
2. Run the debugger on that freshly created prototype
3. Have a close look on the 0-property in the tree view, it will say <empty>

Expected behavior
This exceptional case should be considered in the processing of the prototype definitions so that 0 is recognized as this value and not as a missing value.

Screenshots
The elementIndex property is initialized with the value 0, but see the output below:

(sensitive information has been censored in the image.)

Environment (please complete the following information):

• OS: Ubuntu 16.04
• Terminal: bash
• PHP: 7.0.33-0ubuntu0.16.04.5
• Flow: v4.3.19
• Neos: v3.3.24

[BUG] Linter multiplies error messages

Describe the bug
Currently, if a syntax error is present in one of the Fusion files and you make the plugin lint them, it reports multiple errors in several files if the corresponding errorneous file is included somewhere (e.g. in Root.fusion)

To Reproduce
Steps to reproduce the behavior:

1. Create a syntax error in one of your fusion files that is included in another
2. Execute the fusion:lint command
3. Have a closer look at it's output

Expected behavior
The linter should only report the error in the actual source file, not in a file that actually includes the problematic code and does not actually contain it. This can be very confusing if you want to fix a syntax error that's simply not present.

Screenshots

(as you can see, it's the same error and message in both files.)

Environment (please complete the following information):

• OS: Ubuntu 16.04
• Terminal: bash
• PHP: v7.1
• Flow: v4.3.21
• Neos: v3.3.25

Automatically recognized namespaces

Is your feature request related to a problem? Please describe.
Currently you need to define the namespace mappings for the plugin manually in the Settings.yaml. This is kind of obsolete as the plugin could also read all namespace declarations from the fusion code it need's to parse either way.

Describe the solution you'd like
The plugin could collect namespace definitions during runtime directly from the loaded fusion code instead of loading these mapping from the config.

Provide a customizable color scheming

Is your feature request related to a problem? Please describe.
Currently, the colored output of the fusion:debugprototype command appears badly readable in several terminals, depending on their individual color scheme.

Describe the solution you'd like
It would be great, if some could configure the used colors to fit their personal environment.
Such that in e.g. the Settings.yaml one could change some color codes to be more readable.

Describe alternatives you've considered
Alternatively we could provide a "color scheme" setting with several predefined schemes the user can choose from. This could be even an addition to the override-approach, where the user can first select a theme but still override single colors if needed.

Additional context
See this screenshot as an example:

• The dark blue property names are nearly invisible
• The yellow prototype names are way too eye-catching
• The red meta-properties have a far too high contrast to "normal" properties.

The example in my case may be particularly extreme and possibly not representative, but I find that a single counter-example is sufficient to justify this function meaningfully. Debugging should work well in any environment, regardless of the shell, terminal program, or color scheme. Of course you can also switch off coloring completely with the `--no-color' option, but I think this is no real alternative because the results are so much harder to read.

Improve nested prototype definitions

Describe the bug
Currently, if the debugger encounters a nested prototype definition it cannot handle it properly. Instead, the meta key containing these definitions remains in the otherwise flattened debug-view. This is no real issue as the overview is still correct, but as the information is unstyled it looks really messy...

We have not found a clear remedy to this problem currently. See our thoughts on this below:

• One option would be to include modified properties if the corresponding prototype is used somewhere below the current level. This could be problematic as nested definitions also apply to furtherly nested prototypes and we would need to pass them around between recursions, which will most likely result in unexpected behaviour in some way.
• Another possibility would be to append the modifications to the internal prototype definitions but this would introduce a whole new world of complexity, as we would need to differ between nesting-levels within protoype definitions and this would either be very time- or resource-expensive!
• The third solution would be to simply keep the information where it is, but to style it in some way (colorization, etc.) to make it at least prettier if we cannot integrate it reasonably.

To Reproduce
Steps to reproduce the behavior:

1. Create some prototype definition
2. Create a nested prototype definition inside of the freshly created prototype
3. Have a look at the debug-view of the topmost new prototype

Expected behavior
Nested definitions should not be ignored totally.

Environment (please complete the following information):

• OS: Ubuntu 16.04
• Terminal: Bash
• PHP: 7.0.33-0ubuntu0.16.04.5
• Flow: v4.3.19
• Neos: v3.3.24

Add an option to resolve all prototypes recursively in the debug view

Is your feature request related to a problem? Please describe.
Currently, the output of the debugger lists all nested prototypes used, but their contents are not visible. This means I have to execute the command several times and put the results together myself to be able to reconstruct my prototype in detail. It would be much more practical for this case if the debugger could already merge this information itself.

Describe the solution you'd like
There should be an option added to fusion:debugprototype, that forces the Debugger to recursively resolve all used prototypes, instead of only merging the root inheritance chain. I propose to name it --resolve-all in coherence with it's functionality.

Discussion: use Neos\Neos\Domain\Service\FusionService->getMergedFusionObjectTree($node)?

Maybe with this api one would need less to rewrite. I just saw that youre not using it...
https://github.com/neos/neos-development-collection/blob/master/Neos.Neos/Classes/Domain/Service/FusionService.php#L136

But then one couldn't use this package outside of neos...

Add a prototype debug-view as backend module

Is your feature request related to a problem? Please describe.
This improvement only targets convenience.

Describe the solution you'd like
It would be a huge improvement to the debugger if one could see the prototype information directly from within the backend, just like the "Configuration" backend module but for Fusion definitions respectively.