Upgrading a TYPO3 version / Move to composer

UPGRADE.md

TYPO3 Upgrade

Preparation

Project root == Document root

1. Create a folder (e.g. public)
2. Move folders and files into public
   1. fileadmin
   2. uploads
   3. typo3conf
   4. typo3temp
   5. index.php
   6. typo3 (and symlink typo3_src)
3. Leave sources outside of document root and link typo3_src to it

Template files are in fileadmin

1. Create a sitepackage extension
2. Move templates for pages and content elements into it
3. Move assets into it (alternatively in a separate folder inside doc root)
4. Move TypoScript from fileadmin and DB into it
5. Use the ext_typoscript_* files in extension root to load TypoScript every time as it's needed for a site

Move to composer

⚠️ Be careful when using version constraints. Some extensions do not use semantic versions

1. Go through every extension and separate them into
   • Third-Party extensions (loaded via TER)
   • Project extensions (only for this project)
2. Create a folder extensions on project root (not inside doc root)
3. Move project extensions into that folder
4. For every project extension do
   1. Add a basic composer.json with the fields name, type (typo3-cms-extension), require, extra and autoload to every project extension. Example:

      {
        "name": "vendor/extension-name",
        "type": "typo3-cms-extension",
        "require": {
          "typo3/cms": "^7.6 || ^8.7 || ^9.5 || ^10.4"
        },
        "autoload": {
          "psr-4": {
            "Vendor\\ExtensionName\\": "Classes"
          }
        },
        "extra": {
          "typo3/cms": {
            "extension-key": "extension_key"
          }
        }
      }

   2. The require section should handle all versions you need to deal with during the upgrade
   3. Adjust the ext_emconf.php file
   4. Remove upper border for TYPO3 dependencies and related extensions
   5. Remove files and folders created from ExtensionBuilder as they are not needed (Configuration/ExtensionBuilder.json, Documentation)
      • Documentation folder is only needed if it's touched and filled with important information
   6. Move ext_icon.(gif|png|svg) to Resources/Public/Icons/ExtensionIcon.$1
5. Create a composer.json file on project root
6. Add TYPO3 core via composer (<= v7 typo3/cms, > v7 typo3/cms-*), use composer helper: https://get.typo3.org/misc/composer/helper
7. Add every project extension with version @dev, e.g. composer require vendor/extension:@dev
8. For every third party extension do
   1. Look for extension key and version
   2. Look if composer package exists (https://extensions.typo3.org/extension/<extension_key>)
      • Remove extension folder
      • If yes, composer require <package-name>:<version-constraint> (for e.g. news in version 5.3.8 use version-constraint ^5.3
      • If not
        1. add composer.typo3.org as repository, see https://get.typo3.org/misc/composer/repository
        2. composer require typo3-ter/<extension-key-with-dashes-instead-underscore:<version-constraint>
   3. If there are hard coded changes inside the extension, use the composer-patches package: https://packagist.org/packages/cweagans/composer-patches
9. Install TYPO3 console extension (https://packagist.org/packages/helhum/typo3-console) to extend the CLI possibilities

Upgrading TYPO3

The TYPO3 core and extensions upgrade

From v7 to v8

1. Use the composer helper (https://get.typo3.org/misc/composer/helper) to create a command with all the system extensions you need
2. Look for all third party extension to get the version working with TYPO3 v8
3. composer remove typo3/cms
4. Add the command from step 1 and attach all third party extension's package name and version constraint
5. Run it and watch composer dependency warnings
6. Adjust the versions and packages

From v8 to later

1. Use the composer helper (https://get.typo3.org/misc/composer/helper) to create a command with all the system extensions you need
2. Look for all third party extension to get the version working with the target TYPO3 versions
3. Add the command from step 1 and attach all third party extension's package name and version constraint
4. Run it and watch composer dependency warnings
5. Adjust the versions and packages

After the composer update (using TYPO3 console)

☑️ These steps can be done after every composer changes and during deployment

1. Run database Compare vendor/bin/typo3cms database:updateschema
2. Run the upgrade wizards vendor/bin/typo3cms upgrade:all
3. Generate PackageStates.php file vendor/bin/typo3cms install:generatepackagestates
4. Check for DB updates or folder creations with vendor/bin/typo3cms install:extensionsetupifpossible

7. Add every project extension with version @dev, e.g. composer require vendor/extension:@dev

Don't forget to add the previously created extensions folder as a local repo, so that composer will know where to look for your unpublished project extensions:

...
"repositories": [
        {
            "type": "path",
            "url": "extensions/*",
            "options": {
                "symlink": true
            }
        }
    ]
...