Study guide · Installation, Composer and Upgrades
Installing TYPO3, maintaining it with Composer and upgrading safely
Before the website of the Lindenau music school gets any content, it needs a clean installation. This page follows the integrator Mara from the first Composer command to the upgrade to the next major version. Afterwards you know the directories of a Composer project and the difference between install and update. You also know the composer.json of an extension, how a major upgrade works and the main tools for system maintainers.
Installing with Composer and DDEV
Mara is building the website of the Lindenau music school. Her site package has the extension key lindenau_site, and its Composer package name is lindenau/site. She manages the whole project with Composer.
Composer is the package manager for PHP. The file composer.json lists the packages a project needs. Composer downloads these packages together with their dependencies into the folder vendor/. Other package managers have other jobs: npm is for JavaScript, pip for Python and apt-get for the system packages of a Linux server. The recommended way to install TYPO3 is Composer.
On her own computer, Mara works with DDEV. DDEV starts containers with a web server, PHP and a database that suit TYPO3. The TYPO3 documentation recommends it for local development. An FTP program like FileZilla or an API tool like Postman is no replacement. TYPO3 14 needs PHP 8.2 or higher and Composer 2.1 or higher.
The new project is created from the package Base Distribution. It brings a suitable composer.json and the most important system extensions. Then the setup command configures the installation. It asks for the database credentials, the first admin account and the settings of the first site, and writes the configuration.
composer create-project "typo3/cms-base-distribution:^14.3" lindenau
vendor/bin/typo3 setupNext, Mara logs in to the backend, creates the first pages and enters the site settings. If a change to TypoScript, templates or site settings does not show up in the frontend, the cache is usually the reason. Then she flushes the caches, in the backend with the lightning bolt icon or on the command line with the command cache:flush.
The directories of a Composer project
A Composer project strictly separates what may be public from what must stay private. This is a matter of security.
- The folder
config/holds the configuration. The subfolderconfig/system/containssettings.php, which TYPO3 writes from the backend, andadditional.php, which you maintain by hand. The subfolderconfig/sites/has one folder per site with the site configuration. - The folder
public/contains everything that should be publicly reachable. The document root of the web server must point here. It holds the centralindex.php,fileadmin/and_assets/. - The folder
var/contains private, temporary files. These includevar/cache/for caches,var/log/for logs andvar/labels/for downloaded translations. - The folder
vendor/belongs to Composer. Composer installs all packages there, for example the Core invendor/typo3/cms-coreand the news extension invendor/georgringer/news. - The folder
packages/is meant for your own extensions and the site package. The Base Distribution registers it incomposer.jsonas a repository of type path.
What does not belong there: You never put your own files into vendor/ by hand. The next Composer run or the next deployment overwrites them. That is why Mara keeps her site package in packages/ and installs it with composer require. Composer then links it into vendor/.
fileadmin belongs to the editors. It holds images, PDFs and videos that editors upload. It is only the default storage. Through the File Abstraction Layer, FAL for short, further storages can be added. Logos, CSS and templates do not belong in fileadmin/, for example in a folder called layout. Editors could change or delete them, and they would not be under version control. Mara ships these files in the site package, in the folder Resources/Public.
Never delete var completely. If you remove the whole var/ folder, you risk errors at runtime or during deployment. Only clear individual subfolders. A system maintainer finds missing folders and wrong permissions in the backend under System, Environment, Directory Status. Missing folders can also be created there.
Since TYPO3 14, public/typo3 is gone. The files index.php and install.php in the folder public/typo3/ no longer exist. Backend and Install Tool run through the central index.php in the web root. You reach the Install Tool at the path typo3, slash, install. TYPO3 still answers the old address with install.php as a route. A monitoring check that still calls the old file index.php in the folder typo3 gets an error after the upgrade.
Public files of extensions
Extensions bring CSS, JavaScript, fonts and images. In Composer mode they sit in vendor/, outside the web root. So that the browser can still load them, TYPO3 publishes only the folder Resources/Public of each extension under public/_assets/. Usually this happens with a symlink, that is, a reference. Templates and PHP files of the extension stay private. You never edit the _assets/ folder by hand.
Since TYPO3 14.2, the command asset:publish publishes the public resources. It runs automatically during composer install, and also with the command extension:setup. The environment variable TYPO3_SKIP_ASSET_PUBLISH only skips this step during composer install.
Copying instead of linking: Some servers do not allow symlinks or have a read-only file system. For this, since 14.2 there is the option filesystemPublishingType in the section SYS/SystemResources of the system configuration. It knows three values:
- The default, link, creates references.
- The value mirror copies the files into
_assets/. - The value auto copies in the Production context and links in the Development context.
Never copy from live to local. In development, _assets/ must contain references. If Mara copies the folder back from the live server, the files will not point to the new JavaScript and CSS files after the next Composer update. Then old code runs in the browser with new code on the server, and backend and frontend show errors. Synchronization goes one way only: from development to live.
Composer in everyday work
Two files matter. In composer.json, the require section lists the packages with their version constraints. The composer.lock records exactly which version of each package is installed. Composer writes it itself. You never edit it by hand.
For TYPO3, Mara enters the constraint ^14.3. The caret allows all versions from 14.3.0 up to, but not including, 15.0.0. According to Semantic Versioning, these are compatible updates. To move to TYPO3 15 she has to change the constraint herself.
The most important commands:
- The command
composer create-projectcreates a new project from a package. - The command
composer requireadds a package, for example the extensiongeorgringer/news. It adds it tocomposer.json, installs it and updatescomposer.lock. - The command
composer removeremoves a package fromcomposer.jsonand fromvendor/, and updatescomposer.lock. - The command
composer installinstalls exactly the versions fromcomposer.lock. - The command
composer updateresolves the constraints ofcomposer.jsonagain, installs matching newer versions and rewritescomposer.lock.
Composer has no commands called add, get, fetch, uninstall, delete or drop. If composer.lock is missing, composer install behaves like an update: it resolves the constraints itself and writes a new lock file.
Mara commits composer.lock to version control. That way, composer install installs the same versions locally, on staging and live. The file contains no credentials.
Watch out with caches: the command composer clear-cache only clears Composer's download cache. It does not touch the TYPO3 caches.
The site package as a Composer package
Every extension needs its own composer.json. Mara writes this one for the site package:
{
"name": "lindenau/site",
"type": "typo3-cms-extension",
"description": "Lindenau Site - Site package of the Lindenau music school",
"require": {
"typo3/cms-core": "^14.3"
},
"autoload": {
"psr-4": { "Lindenau\\Site\\": "Classes/" }
},
"extra": {
"typo3/cms": { "extension-key": "lindenau_site" }
}
}- The field type has the value
typo3-cms-extension. This is how the TYPO3 Composer installer recognizes the package as an extension. The type library is for normal PHP libraries, project for a whole project. - Under extra, key
typo3/cms, you find the extension key. - Under require you find the dependency on the Core.
- Database credentials never belong in a
composer.json.
Since TYPO3 14, the title comes from the description. This way TYPO3 no longer has to read the old ext_emconf.php for it in Composer mode. If the description contains the sequence space, dash, space, everything before it becomes the title and the rest becomes the description. Only the first occurrence counts. If the sequence is missing, the whole description is shown as the title.
Since TYPO3 14, Classic mode also needs a composer.json. An older extension that only has an ext_emconf.php is no longer recognized. Its composer.json needs a type that starts with typo3-cms, and the extension key under extra.
Autoloading in Classic mode: Without Composer, TYPO3 creates the autoload information itself. When an extension gets new classes, the card Rebuild PHP Autoload Information in the Maintenance module resets this information. The command composer dump-autoload, on the other hand, requires a Composer installation.
Composer or Classic? The advantage of Composer: dependencies are resolved, and versions are locked and reproducible. The drawback: you need Composer, the know-how and usually access to the command line. Loading extensions directly from the TYPO3 Extension Repository, TER for short, in the Extension Manager only works in Classic mode. Both variants receive security updates.
Preparing a major upgrade
A major upgrade is the move to a new major version, for example from TYPO3 13 to 14. It has three phases: preparation, the Core update itself and the follow-up tasks.
Beforehand, Mara takes care of four things:
- She creates a full backup of the database and all files. The motto is: No backup, no sympathy.
- She reviews the deprecation log and fixes all deprecations of the current version.
- She checks every extension for a version that supports the target version, in the TER and on packagist.org.
- She runs all upgrade wizards of the current version.
The TYPO3 changelogs describe what has changed in the Core. In the Upgrade module, the card View Upgrade Documentation shows them. For extensions, the Upgrade module in the System area helps with four checks.
- The card Scan Extension Files searches the PHP code of extensions for calls that the changelog marks as deprecated or removed.
- The card Check for Broken Extensions checks whether the active extensions can run.
- The card Check TCA Migrations finds outdated settings in the TCA of extensions.
- The card Check TCA in ext_tables.php finds extensions that change the TCA in that file.
The Core update itself runs through Composer in Composer mode. Mara raises the constraints of the Core packages in composer.json, for example to ^14.3, and runs composer update. The card Update TYPO3 Core in the Upgrade module only works in Classic mode. There it updates within a major version at the click of a button, for bug fixes and security updates. Replacing the file settings.php or reinstalling the Core in the Extension Manager is not a way to upgrade.
Mara first rehearses the upgrade on a copy of the live site. Only when everything works there is it the real website's turn.
After the Core update
Right after the Core update, the follow-up tasks come in a fixed order. The tools for them are in the modules Maintenance and Upgrade.
- In the Maintenance module, flush all caches with Flush TYPO3 and PHP Cache.
- Create missing tables and columns with Analyze Database Structure, the Database Analyzer.
- Run all upgrade wizards.
- Change or remove outdated columns and tables in the Database Analyzer.
- Flush the caches again.
- Optionally reset the backend user preferences.
- Update the language packs.
- Check the web server configuration, for example compare the htaccess file with the new template.
Why remove only after the wizards? Many wizards copy data from old fields into new ones. If Mara deletes the old columns first, that data is lost. That is why “change” and “remove” in the Database Analyzer come after the wizards. Page tree and extensions stay untouched throughout.
Your own code is part of the follow-up work too. Mara adapts places in the site package that use removed or changed APIs, and updates extensions to matching versions.
Upgrade wizards
Upgrade wizards check after a Core or extension update whether data or configuration needs to be adapted. If so, they run this migration. They do not create backups, download new versions or redesign anything in the frontend.
Prerequisite: Wizards work with the new database structure. If tables or columns are missing, Mara first creates them in the Database Analyzer. So the wizards do not replace the Database Analyzer.
Where: In the backend they are in the Upgrade module, card Upgrade Wizard. Only system maintainers see this module. Like the modules Maintenance, Settings and Environment, it comes from the package typo3/cms-install. Since TYPO3 14, this package is no longer included by default in minimal Composer installations. If the Upgrade module is missing even though Mara is a system maintainer, this package is usually missing.
On the command line, the wizards also work without this package, because since TYPO3 14 the commands are part of the Core:
vendor/bin/typo3 upgrade:list
vendor/bin/typo3 upgrade:run
vendor/bin/typo3 upgrade:run <identifier>
vendor/bin/typo3 upgrade:mark:undone <identifier>In the backend, you reset a completed wizard in the list of completed wizards.
More rules:
- Some wizards are optional, for example one that installs an extension. They can be skipped.
- Extensions can ship their own wizards too.
- Wizards are not only for major upgrades. Check for pending wizards after every major or minor Core update, so also after the step from 14.2 to 14.3. The same applies after updates of extensions that ship their own wizards.
- Wizards never run automatically in the frontend.
- Before moving to the next major version, all wizards of the current version must be completed.
The area for system maintainers
Under System in the backend you find the modules Maintenance, Settings, Upgrade and Environment. Only backend users who are both admin and system maintainer can access them. If the backend does not work, the Install Tool can be reached directly by URL after you create the file ENABLE_INSTALL_TOOL on the server. That is how you lock and unlock the Install Tool.
The Maintenance module has these important cards.
- The card Flush TYPO3 and PHP Cache clears all registered TYPO3 caches and also the PHP opcode cache and the dependency injection cache. You need this after major upgrades, for example. It does not reach visitors' browser caches, an upstream CDN or Composer's download cache.
- The card Analyze Database Structure compares the database with the definitions of the active extensions and creates missing tables and fields.
- The card Clear Persistent Database Tables empties persistent tables that have nothing to do with caching. These include the session tables be_sessions and fe_sessions, the log sys_log, the CSP reports in sys_http_report and, with workspaces, the preview links in sys_preview. Clearing the sessions logs out all users. Pages and content are kept.
- The card Create Administrative User creates new admins, optionally as system maintainers right away.
- The card Manage Language Packs downloads and updates language packs.
- The card Rebuild PHP Autoload Information only works in Classic mode. In Composer mode it is greyed out and points to Composer.
The Environment module checks the environment. The card Directory Status checks the folder structure and file permissions. The card Test Mail Setup sends a test email.
Much of this also works on the command line. TYPO3 14 has these commands for it:
- The command
cache:flushclears all caches. With the option group and the value system or pages, it only clears one group. - The command
backend:user:createcreates backend users, admins included. - The command
language:updateupdates the language packs. - The command
upgrade:runruns upgrade wizards. - The command
install:password:setsets the Install Tool password. - The command
extension:setupsets up extensions and also creates their tables.
There is no Core command called database:compare or ter:download. Made-up variants like cache:delete, flush:all or backend:user:add do not exist either.
Rotating log files
In Composer mode, TYPO3 writes its logs to var/log/, outside the web root. That way they cannot be fetched in a browser. You find the general log there, whose file name starts with typo3 and a short code, the deprecation log and logs from extensions. Without care, these files grow without limit.
On big servers, a tool like logrotate takes care of this. The music school, however, has shared hosting without root access. For this case TYPO3 ships the RotatingFileWriter. It extends the normal FileWriter. At the configured interval it copies the current file away, adds a timestamp to the name and empties the current file.
Two options control it:
- The option interval sets the rhythm: daily, weekly, monthly or yearly. The default is daily.
- The option maxFiles sets how many old files are kept. The default is 5. The value 0 means: never delete.
You adapt the name of the log file with the options of the FileWriter. Use logFile for your own path or logFileInfix for a part of the name.
$GLOBALS['TYPO3_CONF_VARS']['LOG']['writerConfiguration'] = [
\Psr\Log\LogLevel::ERROR => [
\TYPO3\CMS\Core\Log\Writer\RotatingFileWriter::class => [
'logFileInfix' => 'lindenau',
'interval' => 'weekly',
'maxFiles' => 4,
],
],
];With these values, TYPO3 rotates once a week, and at most four old files remain. Files are not split when they reach a certain size, and several files are not written in parallel.
Key points
- You install TYPO3 with Composer from the Base Distribution and set it up with the setup command. Locally, DDEV helps.
- The document root points to
public/. The folders config, var, vendor and packages sit outside it. fileadmin/belongs to the editors, layout files belong in the site package._assets/only contains theResources/Publicfolders of extensions. If one is missing,asset:publishhelps. Never synchronize from live to local.composer installinstalls the versions fromcomposer.lock.composer updateresolves again and does not belong on the live server.- An extension needs the type
typo3-cms-extensionand the extension key under extra in itscomposer.json. Since TYPO3 14 this also applies in Classic mode. - Before a major upgrade: backup, fix deprecations, check extensions, run the wizards of the current version.
- Afterwards: flush caches, create tables, run wizards, and only then remove old items.
- Check for upgrade wizards after every major and minor update and after extension updates.
- The RotatingFileWriter rotates logs without logrotate, controlled by interval and maxFiles.
Terms
- Base Distribution
- The Composer package typo3 cms-base-distribution from which a new TYPO3 project is created.
- Caret
- Version constraint with a caret sign that allows updates up to the next major version.
- Classic mode
- Installation without Composer, in which TYPO3 manages packages and autoloading itself.
- composer.lock
- File with the exact installed versions of all packages.
- Database Analyzer
- Tool in the Maintenance module that compares and adapts the database structure.
- Document root
- The folder the web server points to, public in Composer mode.
- Major upgrade
- Move to a new major version of TYPO3.
- RotatingFileWriter
- Log writer that rotates log files itself and cleans up old files.
- System maintainer
- Admin who may use the modules Maintenance, Settings, Upgrade and Environment.
- Upgrade wizard
- Migration that adapts data and configuration after an update.