Upgrading from Magento <=2.2.x to 2.3.x

At some point you’re going to want to upgrade your Magento project from 2.0/2.1/2.2 to the latest 2.3.x release to take advantage of new functionality and many improvements. There are a few manual changes that get in the way of the standard composer update that you’re used to. Thankfully, to accommodate this obstacle a tool was included in the codebase to automate these changes for you.


# Create a fresh Magento 2.3 project via composer (or clone the repo and switch to a 2.3 tag/branch, or grab the script by itself..)
composer create-project --repository=https://repo.magento.com/ magento/project-community-edition=2.3 m23base

# Change working directories to the upgrade tools directory in your new project
cd m23base/dev/tools/UpgradeScripts


# Run the 2.3 upgrade assistant against the root of the Magento project you’re intending to upgrade
php -f pre_composer_update.php — –root=/path/to/magento-installation –repo=https://repo.magento.com/


– Updated composer.json
– Updated update/composer.lock
– Updated update/dev/tests

Change working directories to the root of the Magento project you’ve begun updating and complete the remaining steps.

cd /path/to/magento-installation

# Update Magento and all dependencies
composer update

# Clear the cache
rm -rf /var/cache/*
rm -rf /var/page_cache/*

# Remove any generated code
rm -rf /var/generation
rm -rf /generated/code/*

# Run Magento upgrade scripts
php bin/magento setup:upgrade

# Reindex after upgrade
php bin/magento i:rei

# Flush cache after reindex
php bin/magento c:f


– https://devdocs.magento.com/guides/v2.3/comp-mgr/cli/cli-upgrade.html#upgrade-cli-script

M2: Composer Bash Alias

At times you may need to quickly spin up a new, clean Magento 2 install. To simplify this process I added an alias for creating a new Magento 2 environment with composer. If you’re using Oh-My-Zsh as well then its as simple as nano ~/.zshrc and adding the following to the bottom of your configuration.

alias newm2="composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition ."

newm2 bash composer alias

Once you’re all set up you can run newm2 in any folder and this will automatically grab whatever the latest version is from Magento’s repo and create a new composer based env for you to continue testing/debugging/etc.

If you use any other shell this will still work but you’ll need to locate the proper configuration file for registering your alias (eg ~/.bashrc).

M2: OPCache GUI

Now you can easily view the statistics for PHP OPcache in your Magento admin panel. TCMP OPcache GUI displays current memory usage / hit rate / configuration values. You can optionally enable the display of all cached scripts, including details about them, and a quick reset link for the menu (Stores > Configuration > TCMP Studio > OPcache).


composer require tcmp/opcache
php bin/magento module:enable TCMP_OpCache
php bin/magento setup:updgrade
php bin/magento setup:static-content:deploy


TCMP OPcache GUI Example

More Information:

Supports: Magento 2.x (System Requirements) / PHP 7.x (OPCache Documentation)
The source: https://github.com/theycallmepepper/m2-opcache-gui
Packagist listing: https://packagist.org/packages/tcmp/opcache

Charts built with Chart.js
Version for Magento 1 (and inspiration for this version): https://github.com/SchumacherFM/Magento-OpCache/

M2: UI Component Form Field Validation

When building custom forms you’ll need to validate a few different types of data. Thankfully there are a number of validation rules already at your disposal in Magento’s core.

<!-- ... abbreviated usage example - vendor/module/view/adminhtml/ui_component/example_form.xml -->
<field name="title">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="dataType" xsi:type="string">text</item>
                    <item name="label" xsi:type="string" translate="true">Title</item>
                    <item name="formElement" xsi:type="string">input</item>
                    <item name="sortOrder" xsi:type="number">20</item>
                    <item name="dataScope" xsi:type="string">title</item>
                    <item name="validation" xsi:type="array">
                        <item name="required-entry" xsi:type="boolean">true</item>
                        <!-- ... additional rules go here -->
<!-- ... abbreviated usage example -->

A list of available rules from vendor/magento/module-ui/view/base/web/js/lib/validation/rules.js:

  • min_text_length
  • max_text_length
  • max-words
  • min-words
  • range-words
  • letters-with-basic-punc
  • alphanumeric
  • letters-only
  • no-whitespace
  • zip-range
  • vinUS //US VIN Numbers
  • dateITA
  • dateNL
  • time
  • time12h
  • phoneUS
  • phoneUK
  • mobileUK
  • stripped-min-length
  • email2
  • url2
  • credit-card-types
  • ipv4
  • ipv6
  • pattern //REGEX
  • validate-no-html-tags
  • validate-select
  • validate-no-empty
  • validate-alphanum-with-spaces
  • validate-data
  • validate-street
  • validate-phoneStrict
  • validate-phoneLax
  • validate-fax
  • validate-email
  • validate-emailSender
  • validate-password
  • validate-admin-password
  • validate-customer-password
  • validate-url
  • validate-clean-url
  • validate-xml-identifier
  • validate-ssn
  • validate-zip-us
  • validate-date-au
  • validate-currency-dollar
  • validate-not-negative-number
  • validate-zero-or-greater
  • validate-greater-than-zero
  • validate-css-length
  • validate-number
  • validate-integer
  • validate-number-range
  • validate-digits
  • validate-digits-range
  • validate-range
  • validate-alpha
  • validate-code
  • validate-alphanum
  • validate-date
  • validate-identifier
  • validate-zip-international
  • validate-state
  • less-than-equals-to
  • greater-than-equals-to
  • validate-emails
  • validate-cc-number
  • validate-cc-ukss
  • required-entry
  • checked
  • not-negative-amount
  • validate-per-page-value-list
  • validate-new-password
  • validate-item-quantity
  • equalTo
  • validate-file-type
  • validate-max-size
  • validate-if-tag-script-exist
  • date_range_min
  • date_range_max

M2: Enabling REST API access to your module

If your module is correctly implementing interfaces and preferences for them in its di.xml then enabling web API access to your object’s repository should look something like the example shown below. You have the option of setting an ACL resource on any particular endpoint or making it publicly accessible for unauthenticated usage (maybe on the frontend of your site via AJAX?).

File Location: app/code/Vendor/Module/etc/webapi.xml
Reference: http://devdocs.magento.com/guides/v2.2/extension-dev-guide/service-contracts/service-to-web-service.html

        <?xml version="1.0"?>
        <routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            <!-- Example Service -->
            <route url="/V1/example" method="POST">
                <service class="TCMP\ExampleModule\Api\ExampleRepositoryInterface" method="save"/>
                    <resource ref="TCMP_ExampleModule::save"/>
            <route url="/V1/example/:id" method="PUT">
                <service class="TCMP\ExampleModule\Api\ExampleRepositoryInterfacee" method="save"/>
                    <resource ref="TCMP_ExampleModule::save"/>
            <route url="/V1/example/:id" method="DELETE">
                <service class="TCMP\ExampleModule\Api\ExampleRepositoryInterface" method="delete"/>
                    <resource ref="TCMP_ExampleModule::delete"/>
            <route url="/V1/example" method="GET">
                <service class="TCMP\ExampleModule\Api\ExampleRepositoryInterface" method="getList"/>
                    <!-- allow public access to your api! -->
                    <resource ref="anonymous"/>
            <route url="/V1/example/:id" method="GET">
                <service class="TCMP\ExampleModule\Api\ExampleRepositoryInterface" method="getById"/>
                    <!-- allow public access to your api! -->
                    <resource ref="anonymous"/>

No syntax highlighting on this one. Not sure which part of this liked me trying to post XML the least…but that’s added to the backlog now! Thankfully < XMP > hasn’t been removed yet!

Reference: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/xmp

M2: Invalidating Caches

When saving objects in your custom module it may be beneficial to indicate that a cache type should be cleared. ┬áThis can be achieved using the TypeListInterface from the Framework’s Cache Module. Furthermore with this interface you can also retrieve the cache type labels, a list of other caches that have been invalidated, or clean a cache type by code.


namespace Vendor\Module\Folder;

use Magento\Framework\App\Cache\TypeListInterface;

 * Class Example
 * @package Vendor\Module\Folder
class Example {

   * @var TypeListInterface
   protected $_cacheTypesList;

    * Example constructor.
    * @param TypeListInterface $_cacheTypesList
   public function __construct( TypeListInterface $_cacheTypesList )
      $this->_cacheTypesList = $_cacheTypesList;

    * Mark specific cache type(s) as invalidated
    * @param $type
   public function invalidateCache( $type )
      $this->_cacheTypesList->invalidate( $type );

    * Get information about all declared cache types
    * @return array
   public function getCacheTypes()
      /* Example structure for cache type array
       $_types = [
         'CACHE TYPE CODE' =>
          (object)[ //Magento\Framework\DataObject
                    'id' =>(int)'',
                    'cache_type'=>(string) '',
      return $this->_cacheTypesList->getTypes();


M2: Loading model collections the Magento 2.x way

It is now be the responsibility of the repository to load and persist models from the database rather than using the model to load and save directly. This can be confirmed by the load and save methods being marked as @deprecated in \Magento\Framework\Model\AbstractModel.

use Magento\Framework\Api\FilterBuilder;
use Magento\Framework\Api\SearchCriteriaBuilder;
use Magento\Framework\Api\Search\FilterGroupBuilder;
//your model repo, etc...

$_searchCriteria = $this->_searchCriteriaBuilder->create();

$filterA = $this->_filterBuilder->setField( $fieldName ) //Filter by model field name
->setValue( $tagValue ) //Filter value
->setConditionType( 'eq' ) //Comparison operator

$filterGroupA = $this->_filterGroupBuilder->setFilters( [ $filterA ] )->create();

//Filters in the same groups work like OR
//Multiple filter groups work like AND
//Which is why the filter and the group are noted with as [$a]

$_searchCriteria->setFilterGroups( [ $filterGroupA ] );

/** @var Model[] $_results */
$_results = $this->_modelRepository->getList( $_searchCriteria )->getItems();

return $_results;

M2: Add a CMS block to your layout

Add a CMS block to your layout XML:

<referenceContainer name="containerName">
    <block class="Magento\Cms\Block\Block" name="block_name_in_layout" as="block.name.in.layout">
            <argument name="block_id" xsi:type="string">block_identifier</argument>