Virtual themes

In this blogpost I will address a specific problem, that I and many others have faced in Magento. This issue is about how layout changes in the custom theme, does not show up on the frontend. The Css and js changes seem to be loading just fine, but no matter what you try, the layout changes does not load.

This issue turns out to present itself because the custom theme somehow has been set to virtual in the database.

In the ‘theme’ table. Under the column ‘type’, a ‘1’ has been set for the theme. Changing this to ‘0’ sets the theme back to physical and layouts start loading once again.

Another way to figure out if the theme has been set to virtual, is from the backend. By following the path. Content->Design->Theme and click on ‘View’ for your theme.

If you are seeing something similar to what is shown on the image below, where it is possible to upload Css and Js, you can be certain that the theme has been set to virtual.

Figuring out theme types

Surprisingly when reviewing the devdocs on virtual themes, there is little to no information to be found. From the database column type comment, it can be seen that Magento has three theme types – Physical, Virtual and Staging.

From what I understand, physical themes have actual theme files, e.g., blank and luma themes. On the other hand, virtual themes extend physical themes, but do not have any actual files of their own. Not having any concrete information on staging themes and next to nothing on virtual themes, I looked through the code to understand these.

Following the path vendor/magento/module-theme/Model/Theme/Domain/Physical.php

The function createVirtualTheme is used to create a virtual theme, but the only place this is used is in vendor/magento/module-theme/Controller/Adminhtml/System/Design/Theme/Save.php 

which has been depreciated as of version 100.2.0.

Seemingly the only way to create a virtual theme is by directly making an entry in the ‘theme’ database table with ‘type’ set to ‘1’ i.e., virtual.

In the path vendor/magento/module-theme/Model/Theme/Domain/Virtual.php

Two interesting functions can be found, getStagingTheme() and _createStagingTheme()

From these functions it would seem that staging themes are created from a virtual theme when the getStagingTheme function is called. I was not able to find anywhere in Magento Opensource code where the getStagingTheme function is called. This leads me to think that this could be part of future plans for Magento enterprise, as they already have functionality for content staging, and could therefore possibly also have planned for future functionality to create virtual and staging themes. More on content staging can be found at https://docs.magento.com/user-guide/cms/content-staging.html.

On line 71 in getStagingTheme() we see a call to getStagingVersion(), but unlike its name, this actually returns a theme instance representing the latest changes to a theme. From this we can derive that a virtual theme can have multiple staging versions.

On line 72. If no staging theme were found for a virtual theme, then a new staging theme is created, and customisations are copied from the virtual theme to the staging theme.

In vendor/magento/module-theme/Model/Theme/Domain/Staging.php

The function updateFromStagingTheme() is used to copy database customisations, filesystem customisations and layout customisations from the staging theme to its parent theme, which is the virtual theme. This could explain why layouts don’t apply when a theme becomes virtual, perhaps it needs a staging theme for layout updates. Like the other functions, updateFromStagingTheme doesn’t seem to be used anywhere in Magento opensource code.

In the file vendor/magento/framework/View/Design/Theme/Customization.php

From the function getThemeFilesPath() we can see that for a physical theme, the path returned is the directory where the theme files are stored. For all other cases it returns an absolute path to where customisations are stored, which from code is in the media directory under theme_customization/{{theme_id}}.

From this we can derive that virtual themes and staging themes are used for customisations of the physical theme.

For reference, getCustomizationPath and getThemeFilesPath can be found in vendor/magento/framework/View/Design/Theme/Customization/Path.php

Conclusion

From what I understand virtual and staging themes could be part of future plans for Magento Enterprise to have the possibility to create a virtual layer on top of a physical theme, which could have customisations that can be staged and applied to the virtual theme when needed.

If this is the case, I can see two possibilities for where this functionality could be used:

1. Scheduling theme customisations for maybe festivals, public holidays, or other events.
2. Testing out theme changes before applying them.

Only time will tell whether these functionalities will become a reality, and if so, will they be made available for the opensource community as well.