how to use guard?

[mytskine]

Hello. I've tried to migrate a deptrac config into a config for mago's guard, and I failed miserably. I couldn't find anything about that subject in the discussions or issues. If someone has been using Mago guards on real projects, please share your config.

Here are my questions and comments about guards in Mago, after reading the documentation and experimenting.

Config "guard.perimeter"

• [guard.perimeter] has a layering field which is "an array of namespaces". Are they PHP namespaces? At first I couldn't believe it because it would mean that the layers must be an exact match with the PHP namespaces, which will very rarely be true.
• The implicit layering in undocumented. It seems that the default is that the guard only allows use from the same namespace and sub-namespaces.
• The documentation does not state clearly that a layer can access itself and the previously declared layers.
• layering being a flat array, and a unique field, there is no way to write layers like: (kernelOld, kernelNew) | (domainA, domainB) | Controller
• Supposing the layers are PHP namespaces, are they recursive? i.e. a layering of ["a\\x", "a\\x\\y"] means that a\x\y\z\Foo can use a\x\Bar?
• The documentation is unclear about the interaction of the layers defined in guard.perimeter.layering with the other fields under guard. My guess is that they are independent, even from those named guard.perimeter.layers.

Config "guard.perimeter.rules"

• If namespace = "ns\\" means "any code that is directly in \ns but not in its sub-namespaces, it should be explicit in the documentation.
• If namespace = "ns" is allowed and means "any code that is in \ns or any of its sub-namespaces like ns\sub1\sub2, it should be explicit in the documentation. See my comment below, about the syntax-error message.
• The syntax for the caller ("namespace") is rigid, while the syntax for each callee ("permit" item) is lax. Why?

Command "guard"

• The syntax-error messages are not helpful. E.g. "ERROR Failed to build the configuration: Invalid namespace: must be '@global' or a valid namespace ending with '\'. for key guard".
  • No indication of the field that failed.
  • No indication of the line where the error occurs.
  • There is a dot in the middle of the sentence.
  • The error message seems wrong, because namespaces not "ending with '\'" are accepted. BTW, this syntax without a final backslash is undocumented for guard.perimeter.rules.namespace, and, guessing from the doc of permit, it has a different meaning.
• The "guard" command fails to identify global functions. E.g. I got errors like "error[disallowed-function-call]: Illegal dependency on ...\sudoc\array_filter". It seems that Mago is not aware that PHP fallbacks on the global namespace for function calls.

Overall

Overall, I found the structure unsuited to the code I had. Unless I misunderstood the Mago model, there are 2 parts:

• One where I define a stack of recursive PHP namespaces.
• One where I define, for a non-recursive PHP namespace, which parts of the code it has access to.

The deptrac model was easy to understand: you define "layers", and each has "collectors" that will gather code into it; then you define the "ruleset" where each layer lists the other layers it has access to. I wish Mago coud use a similar model.