{"id":19114871,"url":"https://github.com/namelesscoder/typo3-cms-fluid-debug","last_synced_at":"2025-04-30T22:51:09.627Z","repository":{"id":57023496,"uuid":"120004415","full_name":"NamelessCoder/typo3-cms-fluid-debug","owner":"NamelessCoder","description":"TYPO3 CMS improved Fluid debugging assistants","archived":false,"fork":false,"pushed_at":"2019-03-19T12:38:59.000Z","size":15,"stargazers_count":27,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-26T03:14:48.350Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NamelessCoder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-02T16:27:44.000Z","updated_at":"2020-05-09T18:42:14.000Z","dependencies_parsed_at":"2022-08-23T13:50:23.385Z","dependency_job_id":null,"html_url":"https://github.com/NamelessCoder/typo3-cms-fluid-debug","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NamelessCoder%2Ftypo3-cms-fluid-debug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NamelessCoder%2Ftypo3-cms-fluid-debug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NamelessCoder%2Ftypo3-cms-fluid-debug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NamelessCoder%2Ftypo3-cms-fluid-debug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NamelessCoder","download_url":"https://codeload.github.com/NamelessCoder/typo3-cms-fluid-debug/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251795387,"owners_count":21645019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T04:44:45.627Z","updated_at":"2025-04-30T22:51:09.605Z","avatar_url":"https://github.com/NamelessCoder.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"TYPO3 CMS Fluid Debugging Assistant\n===================================\n\nThis package contains overrides and additions to the standard Fluid debugging utility in TYPO3 CMS. It replaces the\nnormal debugging ViewHelper with an improved version that solves several known problems. In addition to dumping\nvariables it also allows you to insert xdebug break points in Fluid templates via a ViewHelper.\n\n\nThe problems it solves\n----------------------\n\n1. The normal Fluid ViewHelper generates output either where it is used, or at the very top of the document before the\n   doctype declaration. Either method has tremendous risk to destroy CSS rendering or be unreadable if used in a clipped\n   or very tiny component.\n2. When you debug properties of an object in Fluid, the Extbase property accessor is used. This means two things: first,\n   the data you look at is *not* the actual data, it is the public gettable data which has properties associated with\n   it. And two, it will only show you data that has a property, i.e. no virtual properties which only have getters.\n3. Debugging a Fluid template means accessing a variable or ViewHelper expression twice, because the built-in debug\n   ViewHelper _will not return the variable it debugs_.\n4. You do not want debug statements in your production code, but sometimes you would like to leave them in templates and\n   make assertions on the output they debug - but you can't, because the debug ViewHelper produces output.\n\nThese problems are well known when debugging in Fluid. And this package solves all of them.\n\n\nInstallation\n------------\n\nInstall with Composer:\n\n```sh\ncomposer require namelesscoder/typo3-cms-fluid-debug\n```\n\nAnd if necessary, activate the `fluid_debug` extension in Extension Manager.\n\nNo configuration is needed, but the package only has functionality when the site is not in Production context. Note that\nit is not enough to switch the context in the TYPO3 backend if you also defined `TYPO3_APPLICATION_CONTEXT` in your\nvirtual host - the one defined in your virtual host takes priority, so make sure it is set to Development or Testing.\n\n\nThe strategy\n------------\n\nInstead of outputting content, the overridden debug ViewHelper instead delegates the output of variables to the JS\nconsole in your browser, by using PageRenderer to insert a call to a `console.log()` or other method, which receives a\nJSON object representation of the data you dump. In TYPO3 backend the ViewHelper dumps to the debugging console (which\nyou can disable) and in CLI mode a regular `var_dump` is triggered (and xdebug break point if so configured in use).\n\nThis means the ViewHelper is safe to use anywhere as it will never produce debug output inside the DOM body.\n\nAn additional strategy is to allow the debugging ViewHelper to return the raw value it was asked to debug. This means\nyou can use it as part of any inline expression to debug the value at that exact point. Consider the following example:\n\n```xml\nLong expression with debug in specific point:\n{myVariable -\u003e f:debug() -\u003e f:format.striptags() -\u003e f:debug() -\u003e f:format.nl2br()}\n\nUsage in argument value and arrays:\n\u003cf:render partial=\"Render{myDynamicType -\u003e f:debug()}\" arguments=\"{foo: '{my:vh(bar: 1) -\u003e f:debug()}'}\" /\u003e\n\nDebugging an array costructed in Fluid while also passing that array:\n\u003cf:render partial=\"Foo\" arguments=\"{f:debug(value: {foo: 'bar', baz: 1})}\" /\u003e\n```\n\nBecause the ViewHelper simply passes the value through, it can be left in place without causing rendering problems. This\nis a major difference compared to the native debugging ViewHelper which cannot be used this way without causing errors.\n\nThe FE/BE/CLI sensitivity also means you get the least intrusive output possible; except on CLI where the standard\nvar_dump is used to produce markup-free dumps.\n\n\nDumping strategy\n----------------\n\nContrary to the native TYPO3 CMS debug ViewHelper, the override dumps objects based primarily on the presence of getter\nmethods which require no arguments - as opposed to basing it on the properties of a reflected object.\n\nWhy this?\n\nThe answer is that while Extbase dumping (which is what the native debug ViewHelper uses) is exceptionally good at\ndumping domain objects, it has shortcomings when the getter method you want to access doesn't have an associated\nproperty. Most prevalent example would be dumping a `File` resource which does not reveal all methods, including some of\nthe most important API methods that are very useful in Fluid (example: metadata properties).\n\nSo by dumping based not just on properties but by the presence of getter methods, with either the `get` or `has` or `is`\nprefixes, this dump reveals every property *that you can use in Fluid*, rather than just those that makes sense in an\nExtbase persistence context.\n\n\nAuto-suppressed in Production\n-----------------------------\n\nThe package silences itself when the TYPO3 application context is set to Production.\n\nThere are two main reasons for this:\n\n1. By auto-suppressing, it means it is safe to deploy templates which contain debug statements.\n2. Because debug statements output to `console.log()` or other, if you use acceptance testing with browser integration\n   you can make assertions on variables passing through Fluid as part of your acceptance testing; variables which you\n   don't see in the template output but are used to render it.\n\nSo rather than as you normally would, remove debug statements or suppress them with `f:comment`, you can simply leave\nthem in there - they cause no output in DOM body, they pass the debugged value through, and in Production content they\nare replaced with completely transparent versions of themselves.\n\n\nUsage details\n-------------\n\nThe package currently contains two ViewHelpers:\n\n* An override for `f:debug` which is semi-compatible (also uses tag content to read dump value)\n* A specialised alias with reduced arguments, `f:debug.break`, which instead of outputting to console will create a\n  dynamic breakpoint for xdebug so you can inspect the state in your IDE.\n\nThe `f:debug` override has the following arguments:\n\n* `value` which can be specified as argument value or is otherwise taken from tag content / child node\n* `title` which is a string you can use to identify the debug output - if not specified, the current template source\n  code chunk and line/character number is shown if the template is not compiled (flush system cache to cause compiling).\n* `level` which is a string containing `log`, `warn` etc. - method name on the `console` object to be called.\n* `maxDepth` which is in integer, maximum number of levels to allow when traversing arrays/objects (note that infinite\n  recursion is automatically prevented).\n* `silent` which is a boolean you can set to `1` if you want to suppress the output in console altogether.\n* `pass` which is a boolean you can set to `0` to not pass the dumped variable, useful if you for example have a\n  separate `\u003cf:debug pass=\"0\"\u003e{object}\u003c/f:debug\u003e` that would otherwise cause string conversion problems.\n* `break` which is a boolean you can set to `1` to cause an xdebug break point. Only happens if xdebug is installed.\n* `compile` which is a boolean you can set to `0` to disable compiling, letting you debug and break on the behavior\n  the template has during parsing and compiling without having to flush caches repeatedly.\n\nAnd the reduced alias `f:debug.break` has the following arguments:\n\n* `value` exactly like above\n* `pass` exactly like above\n* `silent` like above, but with default set to `1` to suppress output\n* `break` like above, but with default set to `1` to always break\n* `compile` exactly like above\n\nIn other words, `f:debug` is the main utility and `f:debug.break` is a customised alias which uses different default\nargument values, making it an ideal \"insert breakpoint here\" ViewHelper.\n\n\nNote about using breakpoints\n----------------------------\n\nWhen you use break points with `f:debug.break` you don't just get the option of inspecting the variable you dump when\nthe ViewHelper gets rendered - when break points are enabled, they trigger on the following events:\n\n* When the ViewHelper is initialized (when template is parsed, when ViewHelperNode is built in syntax tree)\n* When the ViewHelper is compiled to a PHP class (when you can dump for example the compiler's state)\n* When the ViewHelper is rendered (when you can inspect the actual value you want to dump, as well as other variables)\n\nA handful of key variables are extracted for easier reading in your IDE. These include the template source chunk, the\nline/character number, all current template variables, whether template is compiled, and so on.\n\nNote that you can also set `break=\"1\"` on `f:debug` to cause an xdebug break point from that ViewHelper as well.\n\n**Important! Not all objects are possible to debug - when `f:debug` fails, `f:debug.break` and xdebug always works!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamelesscoder%2Ftypo3-cms-fluid-debug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamelesscoder%2Ftypo3-cms-fluid-debug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamelesscoder%2Ftypo3-cms-fluid-debug/lists"}