1.3.2: Common Workflows and Solutions
Common Workflows and Solutions
Before we finally roll up our sleeves and start writing code, there's one more topic that's worth some attention. With all the moving pieces in play in Magento, and the host of common commands we've reviewed, it's important to have a good idea of the necessary steps involved in refreshing your development environment in different scenarios.
As You Write Code
When first starting out in Magento, it's common to repeatedly face the frustration of writing your latest chunk of code, refreshing a page or re-running an operation, and just not seeing the new behavior you expect. You'll quickly develop the habit of refreshing your environment in the appropriate ways.
The most frequent operation you'll find yourself performing, of course, is clearing the cache.
bin/magento cache:flush
When you change layout XML, configuration XML, current Store Config values, or the contents of some templates, you'll need a refresh of the cache. If you have full page caching enabled in your environment, any change that affects the final output of a typical page will require this!
It's also commonly necessary to clear the contents of the generated
directory. More specifically, if you have added to
or modified the injected constructor arguments of a class, there's every possibility that a generated class file will
be affected. If you encounter elusive errors about classes receiving incorrect types in their constructors, this is a
sure sign that you should clear generated files:
rm -r generated/*
And finally, the nature of static asset materialization means it might be necessary to clear the contents of pub/static
when you are working with, for example, JS files. Give it a try if the latest version of a file doesn't seem to be getting
served to your browser:
rm -r pub/static/*
When you're modifying style rules in Less, you may need to clear the contents of var/view_preprocessed
as well:
rm -r var/view_preprocessed/*
The use of Grunt for automatically compiling new CSS, which we'll cover at a later point, will avoid these headaches when making frequent styling changes.
When Config Files Have Changed
Don't fret if you find yourself faced with a jarring error like this while developing:
The configuration file has changed. Run the "app:config:import" or the "setup:upgrade" command
to synchronize the configuration.
This simply means that information in app/etc/env.php
has changed, and Magento has detected that its
hash of this info is out of date. Do what the error message says and run app:config:import
or setup:upgrade
!
When Updating Your Codebase
You should be confident in the steps to take whenever you pull down the latest modifications in your project codebase.
If you've just run a git pull
and received a slew of updates, think through the possible ways in which your environment
might now be stale and the appropriate steps to take:
- The state of
composer.lock
might have been updated with new or upgraded packages. A fresh Composer installation is required to make sure your dependencies are still in line. - New code might have introduced schema changes or data patches that need to be applied to your database. A run of the upgrade command will do the trick.
- Any of the numerous generated PHP classes might be stale now, so it's time to clear the contents of the
generated
directory. - Your static assets may have become stale as well. But as we've seen,
setup:upgrade
will have already taken care of clearing out this directory. - Predictably, you'll want to clear out the cache.
A typical routine, then, after pulling new updates into your environment, would look like this:
composer install
rm -r generated/*
bin/magento setup:upgrade
bin/magento cache:flush
Less frequently, new updates might unexpectedly put your indexes out of sorts, for which you'll want to re-index as well (see below).
When Index-Related Data is Stale
From time to time, data changes rather than code changes will be the thing to perplex you when they fail to take effect. Remember that indexing, not only caching, comes into play here. Perhaps the most critical area of the site affected by indexes is the product listing displayed on category pages. Stale pricing or category association indexes are the most common culprit when products stubbornly refuse to show up in front-end listings.
If you encounter such an issue, and clearing the cache is of no help, then try a re-index.
bin/magento indexer:reindex
Of course, in such situations, it's key to ask why indexes have not updated as they should in response to data changes. If your indexes didn't update properly, we can't guarantee that you haven't uncovered a prickly problem to debug in your application code! But before you panic, check to make sure your indexes are in set to the proper update mode.
Indexes can be set to update immediately any time related data is saved ("Update on Save") or to queue incremental changes to be run on a scheduled basis ("Update on Schedule"). The latter is usually appropriate for production environments. But "Update on Save" is necessary in dev environments, assuming you have not configured the Magento cron.
You can check what mode your indexes are currently set to with the following:
bin/magento indexer:status
You can also easily check this info in the admin, at System > Tools > Index Management. It's easy to change index modes from this same admin interface, or you can do that from the command line as well:
bin/magento indexer:set-mode realtime catalog_product_category
When You've Imported a Database
It's not unlikely that your development workflow might eventually involve re-importing the entire Magento database from another environment from time to time.
If you do have occasion to wipe out your database and import from a fresh dump, keep in mind the potential needed updates.
You might have schema/data changes in your local code that were not reflected in the environment your new DB came from,
the stored hash of key config data likely doesn't match your local app/etc/env.php
, and when all is said and done a
re-index wouldn't go amiss! It goes without saying that a cache refresh would be a good idea in this situation too.
bin/magento setup:upgrade
bin/magento cache:flush
bin/magento indexer:reindex