namelesscoder / typo3-cms-fluid-debug
Requires
- typo3/cms-fluid: ^8|^9
Replaces
- fluid_debug: 1.1.1
- typo3-ter/fluid_debug: 1.1.1
README
此软件包包含对TYPO3 CMS标准Fluid调试工具的覆盖和补充。它使用改进版本替换了常规调试ViewHelper,解决了几个已知问题。除了输出变量外,它还允许您通过ViewHelper在Fluid模板中插入xdebug断点。
解决的问题
- 常规Fluid ViewHelper生成的输出要么在它被使用的地方,要么在文档顶部doctype声明之前。这两种方法都有很大的风险,可能会破坏CSS渲染,或者在剪辑或非常小的组件中使用时变得不可读。
- 当你在Fluid中调试对象的属性时,使用的是Extbase属性访问器。这意味着两件事:首先,你查看的数据不是实际数据,而是与之关联属性的可公开获取的数据。其次,它只会显示有属性的数据,即没有只有getters的虚拟属性。
- 调试Fluid模板意味着访问变量或ViewHelper表达式两次,因为内置的调试ViewHelper不会返回它调试的变量。
- 你不想在生产代码中留下调试语句,但有时你希望在模板中留下它们并对其调试输出进行断言——但你不能,因为调试ViewHelper会生成输出。
这些问题在Fluid调试中是众所周知的。而这个软件包解决了所有这些问题。
安装
使用Composer安装
composer require namelesscoder/typo3-cms-fluid-debug
如果需要,在扩展管理器中激活fluid_debug
扩展。
不需要配置,但该软件包仅在站点不在生产上下文时才有功能。请注意,如果你还在虚拟主机中定义了TYPO3_APPLICATION_CONTEXT
,仅切换TYPO3后端上下文是不够的——虚拟主机中定义的上下文具有优先级,因此请确保它设置为开发或测试。
策略
而不是输出内容,覆盖的调试ViewHelper将变量的输出委托给浏览器中的JS控制台,通过使用PageRenderer插入对console.log()
或其他方法的调用,该方法接收您丢弃的数据的JSON对象表示。在TYPO3后端,ViewHelper将输出到调试控制台(您可以禁用它),在CLI模式下触发常规的var_dump
(如果配置了使用xdebug断点)。
这意味着ViewHelper在任何地方都是安全的,因为它永远不会在DOM体内部生成调试输出。
另一种策略是允许调试ViewHelper返回它被要求调试的原始值。这意味着您可以使用它作为任何内联表达式的部分来调试该点的值。考虑以下示例
Long expression with debug in specific point: {myVariable -> f:debug() -> f:format.striptags() -> f:debug() -> f:format.nl2br()} Usage in argument value and arrays: <f:render partial="Render{myDynamicType -> f:debug()}" arguments="{foo: '{my:vh(bar: 1) -> f:debug()}'}" /> Debugging an array costructed in Fluid while also passing that array: <f:render partial="Foo" arguments="{f:debug(value: {foo: 'bar', baz: 1})}" />
由于ViewHelper只是传递值,因此可以将其留位而不引起渲染问题。这与原生调试ViewHelper有很大不同,后者不能以这种方式使用而不导致错误。
FE/BE/CLI敏感性还意味着您可以得到最不干扰的输出;除了CLI,在CLI中使用标准var_dump生成无标记的输出。
输出策略
与原生的TYPO3 CMS调试ViewHelper不同,重写版本的dump基于对象存在不需要参数的getter方法,而不是基于反射对象属性的。
为什么这样做?
答案是,尽管Extbase的dump(即原生调试ViewHelper所使用的)在处理域对象方面非常好,但当您想访问的getter方法没有相关属性时,它存在一些不足。最普遍的例子是dump一个File
资源,它没有揭示所有方法,包括一些在Fluid中非常有用的最重要的API方法(例如:元数据属性)。
因此,通过基于属性和getter方法的存在来dump,无论是使用get
、has
还是is
前缀,这个dump会揭示您可以在Fluid中使用的每一个属性,而不仅仅是那些在Extbase持久化上下文中合理使用的属性。
在生产环境中自动禁用
当TYPO3应用程序上下文设置为生产时,此包会自动禁用自己。
主要有两个原因
- 通过自动禁用,这意味着可以安全地部署包含调试语句的模板。
- 因为调试语句输出到
console.log()
或其他,如果您使用浏览器集成进行验收测试,您可以在验收测试中对通过Fluid传递的变量进行断言;这些变量在模板输出中看不到,但用于渲染模板。
因此,您不必像通常那样移除调试语句或使用f:comment
来抑制它们,只需将它们留在那里即可——它们不会在DOM主体中输出,它们会传递调试的值,在生产内容中,它们被替换为完全透明的版本。
使用说明
此包目前包含两个ViewHelper
- 对
f:debug
的重写,它是半兼容的(也使用标签内容来读取dump值) - 一个具有较少参数的专业别名
f:debug.break
,它不会输出到控制台,而是为xdebug创建一个动态断点,以便您可以在IDE中检查状态。
f:debug
的重写有以下参数
value
可以是参数值,也可以是从标签内容/子节点中获取title
是一个字符串,您可以使用它来识别调试输出——如果未指定,如果模板未编译,则显示当前模板源代码片段和行/字符号(刷新系统缓存以触发编译)。level
是一个字符串,包含log
、warn
等。它是要在console
对象上调用的方法名称。maxDepth
是一个整数,表示在遍历数组/对象时允许的最大级别(请注意,无限递归会自动防止)。silent
是一个布尔值,您可以将其设置为1
,如果您想完全抑制控制台输出。pass
是一个布尔值,您可以将其设置为0
,这样就不传递dump变量,这在例如您有另一个<f:debug pass="0">{object}</f:debug>
时很有用,否则它会导致字符串转换问题。break
是一个布尔值,您可以将其设置为1
来引起xdebug断点。只有当安装了xdebug时才会发生。compile
是一个布尔值,您可以将其设置为0
来禁用编译,这样您可以在不重复刷新缓存的情况下调试和中断模板在解析和编译期间的行为。
并且具有较少参数的别名f:debug.break
有以下参数
value
与上面完全相同pass
与上面完全相同silent
与上面相同,但默认设置为1
以抑制输出break
与上面相同,但默认设置为1
以始终中断compile
与上面完全相同
换句话说,f:debug
是主要实用工具,而 f:debug.break
是一个自定义别名,它使用不同的默认参数值,使其成为理想的“在此处插入断点”视图助手。
关于使用断点的说明
当你使用 f:debug.break
断点时,你不仅可以选择检查视图助手渲染时导出的变量,当启用断点时,它们会在以下事件上触发
- 当视图助手初始化时(当模板解析时,当视图助手节点在语法树中构建时)
- 当视图助手编译为PHP类时(当你可以导出例如编译器的状态时)
- 当视图助手渲染时(当你可以检查你想要导出的实际值,以及其他变量)
一些关键变量被提取出来,以便在你的IDE中更容易阅读。这些包括模板源代码块、行/字符编号、所有当前模板变量、模板是否已编译等。
注意,你还可以在 f:debug
上设置 break="1"
来使该视图助手的 xdebug 断点。
重要!并非所有对象都可以调试——当 f:debug
失败时,f:debug.break
和 xdebug 总是有效的!