Neos Caching 101

Overview.md

Caching is hard but worth the hassle

Motivation

• no clear cache button
• 100 % transparent for editors
• good caching makes sites fast

We are forced to configure caching right as otherwise editors will complain

https://docs.neos.io/cms/manual/rendering/caching

What is cached

• Fusion has a static syntax tree and each branch can evaluated seperately for a specific context
• Same path and context should result in the same value.
• The results of each branch/leave can be cached (for a given set of identifiers)
• When evaluating any branch fusion checks first wether there is a cache entry alredy
• Cached entries
  • Value for the fusion path
  • Can have a due date (may be 0)
  • Can have tags to mark when they are be thrown away before the due date
• !!! Fusion cache entries are always strings !!!

Cache Modes: https://docs.neos.io/cms/manual/rendering/caching#the-basics

• embed ... into parent cache entry
• cached ... control maximumLifetime, entryIdentifier (find entry again), entryTags (when to delete)
• uncached ... control context as only those values will be available for partial reevaluation
• dynamic ... control entryDiscriminator false >> like uncached, "strings" >> multiple cached fragments

Cache Tags: https://docs.neos.io/cms/manual/rendering/caching#cache-entry-tags

• ${Neos.Caching.nodeTypeTag('[My.Package:NodeTypeName]', node)} : Flushes cache entries if any node with the given node type changes.
• ${Neos.Caching.nodeTag(node)} : Flushes cache entries if the node changes
• ${Neos.Caching.descendantOfTag(node)} : Flushes cache entries if a child node of the node changes.
• "anyStringCanBeUsedAsTag" : You have to ensure calling flushByTag for this cache-tag yourself via signal, aspect etc.

Default.fusion

root {
  
	#  
	# render the fusion prototype that is named like the document type
	#

	@cache {
		mode = 'cached'

		entryIdentifier {
			node = ${node}
		}
		entryTags {
			# Whenever the node changes the matched condition could change
			1 = ${Neos.Caching.nodeTag(documentNode)}
			# Whenever one of the parent nodes changes the layout could change
			2 = ${Neos.Caching.nodeTag(q(documentNode).parents())}
		}
	}
}

Quelle: https://github.com/neos/neos-development-collection/blob/master/Neos.Neos/Resources/Private/Fusion/DefaultFusion.fusion#L72-L83

Neos.Neos:ContentCollection

prototype(Neos.Neos:ContentCollection) < prototype(Neos.Fusion:Tag) {
	
	# 
	# rendering of content collection
	#

	@cache {
		mode = 'cached'

		entryIdentifier {
			collection = ${node}
		}

		entryTags {
			1 = ${Neos.Caching.descendantOfTag(node)}
			2 = ${Neos.Caching.nodeTag(node)}
		}

		maximumLifetime = ${q(node).context({'invisibleContentShown': true}).children().cacheLifetime()}
	}

	@exceptionHandler = 'Neos\\Neos\\Fusion\\ExceptionHandlers\\NodeWrappingHandler'
}

#
# no caching for nested collections 
#
prototype(Neos.Neos:ContentCollection) {
	prototype(Neos.Neos:ContentCollection) {
		@cache {
			mode = 'embed'
		}
	}
}

Quelle: Neos.Neos:ContentCollection

Neos.Fusion:GlobalCacheIdentifiers

prototype(Neos.Fusion:GlobalCacheIdentifiers) {
	workspaceChain = ${documentNode.context.workspace.name + ',' + Array.join(Array.keys(documentNode.context.workspace.baseWorkspaces), ',')}
	editPreviewMode = ${documentNode.context.currentRenderingMode.name}
}

Quelle: https://github.com/neos/neos-development-collection/blob/master/Neos.Neos/Resources/Private/Fusion/DefaultFusion.fusion#L121-L124

Helpers and Tips

• Avoid unneded cache fragmentation
• Cache things across pages when possible
• Try editing
• t3n/neos-debug https://github.com/t3n/neos-debug