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:

1. 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.
2. 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.
3. Any of the numerous generated PHP classes might be stale now, so it's time to clear the contents of the generated directory.
4. 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.
5. 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