Composer cheat sheet

Composer is a powerful tool for managing dependencies in PHP projects, including TYPO3. Here you will find an overview of the four most important commands with a simple explanation of what they do.

composer require vendor/extension-name

composer remove vendor/extension-name

composer install

composer update

Backend modules

The backend contains modules that are grouped by task. Which modules a user sees depends on the access rights that have been given to them.

The Web group contains a set of modules for the creation and management of pages and content. This group contains important backend modules such as Pages, where the page content can be edited, List where database records can be viewed and edited and Info where you can find information provided by different system and third party extension. Many page modules provided by third party extensions can also be found in this area.

Site Management is for the setup of a site. Here it is possible to specify the site name, assign domains and select languages.

Filelist is for viewing and managing files including documents, images and videos.

Admin Tools are administrative modules for maintenance and performing upgrades. One module is the Extension manager for enabling/disabling third-party extensions.

System is where administrators control access to the backend, view error logs and provide information specific to the installation.

Working with the page tree

We will now look at some components of the page tree a little more closely:

Root page

The page with the globe icon represents the root of your web site. Multiple websites can exist within a single installation of TYPO3. The top node with the TYPO3 logo is a special container which is used to store shared resources such as file mounts and backend user records.

Modules:

Some modules make use of the page tree, but not all. The presence of the page tree implies that the module depends upon the selection of a specific pages in the page tree.

Content area:

Clicking on a pages title opens that page in the content area to the right. Hovering over the icon of a page will display its internal id.

Context menu:

1. A click on the page icon will open the context menu. 2. Or, you can right click the whole page title.

The context menu

The context menu of a page is used to access the most common page related functions. Here is what these options do:

• Show: Opens the page you clicked in the browser (frontend)
• Edit: Lets you edit the page properties
• New: Create a new page

parent
 |
 ---> current page
 |
 ---> new page

parent
 |
 --> current page
      |
      ---> new page

• Info: Displays information about the page
• Copy: Copies the page
• Cut: Cuts the page

• More options:

  • More options ... > 'Create New' wizard: Same as "New", but you can select where the new page is to be created.
  • ...
  • More options ... > Export: Opens the export tool and preselects the selected page
  • More options ... > Import: Opens the import tool and preselects the selected page
• Disable: Disables the page (so it isn't accessible from the frontend anymore)
• Delete: Deletes the page
• History/Undo: Shows the change history of the page (who did which changes when)

Create new pages with drag and drop

You can also create new pages using drag and drop.

1. Clicking on the "Create new pages" icon (top left of the page tree)

2. Drag and drop a "Standard" page to its desired location in the page tree.

   

   

3. A new page has now been created at the desired location.

   By default it will be called "[Default Title]" which can be changed right away by entering a new title.

   

The view module

It is also possible to view a page without having to leave the backend. By selecting the View module, backend users are able to preview individual pages and test them against various screen sizes, by accessing the drop-down menu at the top.

Collapsing the page tree

The page tree can be collapsed to gain screen space, by clicking on the second icon on the left in the top bar.

Editing pages

Modifying an existing page or adding a new one is covered in the Editors Tutorial.

Next we will look at how content is placed on pages.

Page layout / backend layout

Within the Page module there can be one or more areas (also called columns) in which content can be added. The columns to be displayed in the backend are defined via page TSconfig in a so-called backend layout, sometimes also called page layout. The site package tutorial describes how page layouts can be configured and used: Page layouts with page TSconfig.

The topic is also covered in-depth in the TSconfig Reference, chapter Backend layouts.

The "New Page Content" wizard

When an editor adds a new content element to the page the "New Page Content" wizard is displayed. Available content elements and plugins are ordered into groups.

You can use the page TSconfig setting mod.wizard.newContentElement.wizardItems to hide or edit content elements displayed here. For example you can hide the "HTML" content element supplied by typo3/cms-fluid-styled-content :

mod.wizards.newContentElement.wizardItems {
    special.removeItems := addToList(html)
}

Content elements

You can use the community extension friendsoftypo3/content-blocks to define additional content elements. Many third party extensions like bk2k/bootstrap-package offer pre-defined content elements or, like georgringer/news plugins.

New content elements can also be created without relying on third party extensions. You need basic knowledge on TCA (Table Configuration Array), A minimal page created by pure TypoScript, and templating with Fluid. You have to use PHP for some basic configurations but need no in-depth knowledge of programming.

See create a custom content element type.

Plugins

A plugin is a special kind of content element. It typically provides dynamic or interactive functionality. Many third party extensions offer ready to use plugins for a wide range of functionality. For example plugins to display news: georgringer/news , plugins to perform searches: apache-solr-for-typo3/solr , to display Open Street maps: wsr/myleaflet , event management with registration: derhansen/sf-event-mgt-contentelements and many more.

The chapter How to find extensions covers searching for suitable extensions.

Usually a PHP class called a "controller" manages the functionality and display of the plugin. To create a custom plugin you need some experience in PHP programming and dealing with databases etc.

How to preview a page

The preview function in TYPO3 allows you to check pages before publishing them.

1. Preview from the Page Module

   • You can preview a page by clicking the page icon of the desired page in the page tree. Click the ´show´ icon in the appearing context menu. The page will open in a new tab.

   

2. Preview button in the top bar

   • You can preview the page via clicking the button in the top bar.

   

Display of database records in the List module

How a database record type is displayed in the list module is determined by TCA (Table Configuration Array) and can be further configured by TSconfig. While TCA is always loaded globally Tsconfig can be included on a per-site or per-page level.

Here are some examples of what you might want to change in the list module:

mod.web_list {
    hideTables := addToList(tx_my_table,tx_my_table2)
}

TCEMAIN.table.tx_my_table {
   disablePrependAtCopy = 1
   disableHideAtCopy = 1
}

# Do not hide newly created pages by default
TCAdefaults.pages.hidden = 0

# Set the author of a news to "Anonymous"
TCAdefaults.tx_news_domain_model_news.author = Anonymous

Fileadmin - the default file storage

By default all media managed via the Filelist module is stored in the folder public/fileadmin.

This folder is publicly accessible and it is possible for attackers to access any file herein when they have or guess the correct path.

Third party extensions like leuchtfeuer/secure-downloads can help you if downloads should only be available to logged-in frontend users.

File storages

It is possible to configure additional file storages, including private and read only ones. This topic is beyond the scope of this guide. It is explained in TYPO3 Explained, chapter File storages.

File abstraction layer (FAL)

All media and download files managed in the Filelist module are managed via an abstraction layer. You can find the documentation of this layer in TYPO3 Explained, chapter File abstraction layer (FAL).

On uploading, each file gets a unique identifier assigned to it. This identifier is used to link to files and also to attach meta data to them.

This allows your editors to rename and move files without breaking the frontend. It also allows to test whether a file is still being used on deletion and to automatically delete unused media if desired.

However you can only use the full power of the FAL if you do not link directly to files but only use the API to access them:

In Fluid link files using the Image ViewHelper <f:image> with property image for images and the Link.file ViewHelper <f:link.file> for download links.

In TypoScript the typolink function with the file property can be used to link downloads.

For usage in PHP there is an API: Working with files, folders and file references

File meta data

A number of meta data fields for media uploaded in the Filelist module is available out-of-the-box. Additional meta data fields are available if the system extension typo3/cms-filemetadata is installed.

For accessibility reasons images should always have an alt text defined. Editors can input an alt text either in the file metadata in the Filelist module or override it in the file relation when they use an image in a content element.

By using the Image ViewHelper <f:image> the alt text is automatically output unless you override it with property 'alt'.

Pages containing page TSconfig

Until TYPO3 version 13 page TSconfig was either added globally via a file called EXT:my_extension/Configuration/page.tsconfig or inserted or included in the record of a page in the page properties. Doing so is still possible for backward compatibility reasons.

If you included the Page TSconfig via a site set or globally it not displayed in the overview submodule.

This does not mean it is not being loaded.

Active page TSconfig

This module works much like Active TypoScript.

Included page TSconfig

This module works much like Included TypoScript, however the sources from which TSconfig is being loaded are different.

In this Guide we assume that you load page TSconfig via the the site set of your site package. The TSconfig Reference gives you an overview of all possible strategies to set page TSconfig: Setting page TSconfig.

And to make confusion perfect there is also user TSconfig, which is loaded on a per user basis: Setting user TSconfig and can override page TSconfig: Overriding page TSconfig in user TSconfig

These topics are beyond the scope of this Guide however.

TypoScript Overview

Global overview of all pages with active TypoScript definitions (TypoScript records and site sets). Useful if you have more then one site or more then one TypoScript record in one site.

Constant Editor

Before site settings were introduced with TYPO3 13, TypoScript constants where used to define values once and reuse them across TypoScript definitions.

Constants can still be used for backward compatibility reasons but the Constant Editor is not available if you are using site sets. Other then site settings, TypoScript constants are only available within TypoScript.

It is therefore recommended to always use site settings.

Edit TypoScript record

Only available if TypoScript records are being used. Can be used to edit those records. As we manage TypoScript within the site in this Guide it is out of scope of this Guide. Its usage is described in the TypoScript reference, chapter Submodule "Edit TypoScript Record".

Active TypoScript

This module can be used to debug the active TypoScript. During loading and pre compiling TypoScript configuration can override or unset definitions made in another file.

How exactly this happens depends on things like dependencies between the used site sets.

For example if a site set in your site package configures:

page.20 = TEXT
page.20.value = Apple

And the set of another extensions configures:

page.20 = TEXT
page.20.value = Banana

It depends on how these sets are loaded weather the page.20.value ends up being set to "Banana" or "Apple".

If the site set of our site package depends on the Banana set, the SitePackage set overrides the Banana set and the Active TypoScript submodule will show you the value "Apple" while it never mentions Banana.

This module therefore shows you the compiled version of the TypoScript.

The module can also be used to simulate what happens if certain TypoScript Conditions are being met or how site settings / TypoScript constants are replaced.

Chapter Debug the TypoScript in the backend module "Active TypoScript" demonstrates the usage of this module in a concrete example.

Included TypoScript

This submodule is helpful in debugging in which order TypoScript files were included and @import statements were resolved.

If the "Banana" from the example in Active TypoScript was overridden, you can use this module to find out where it might have been overridden.

This module is also described in the TypoScript reference, chapter Submodule "Included TypoScript".

Accessing the Admin Tools

The Admin Tools can only be accessed from the backend if:

• typo3/cms-install is installed. This system extension became optional with TYPO3 13.
• The currently logged in backend user has admin privileges and is a system maintainer.
• On systems in the application context "Production" the user has to reconfirm their login.

If the TYPO3 backend is not accessible you can access the "Install Tool", which features the Admin Tool modules provided by typo3/cms-install :

Accessing the Install Tools without TYPO3 Backend access

On any TYPO3 installation with typo3/cms-install you can access the Install Tools by calling the following URL: https://example.org/typo3/index.php.

To prove that you have writing access to the file system where TYPO3 is installed you have to create a file in path var/transient/ENABLE_INSTALL_TOOL or config/ENABLE_INSTALL_TOOL. The file can be empty, TYPO3 has to have write access to the file. You can create it like this on:

touch config/ENABLE_INSTALL_TOOL

See also TYPO3 Explained, ENABLE_INSTALL_TOOL.

You must now enter the Install Tool password. If you do not know the install tool password you can generate a new one by entering the desired password.

Copy the calculated hash:

Open file config/system/settings.php and adjust the Install tool password like so:

 <?php
 return [
     'BE' => [
-        'installToolPassword' => '$argon2i$v=19$m=65536,t=16,p=1$Z1BRbnZDdGx4T3pJVmpLVw$Bjhz+rSW1Bps5hIdXUBXrtlZ52E4Qx4lw4NU0MiEUyg',
+        'installToolPassword' => '$argon2i$v=19$m=65536,t=16,p=1$Z0tiZjVVdzN5VUEuLzhmYw$xTalKXJVMCALCO+0OklDt24Y/7NkffNc1bOeg2jo00I',
         'passwordHashing' => [
             'className' => 'TYPO3\\CMS\\Core\\Crypto\\PasswordHashing\\Argon2iPasswordHash',
             'options' => [],
         ],
     ],
 ];

Flush TYPO3 and PHP Cache

By clicking the button Flush cache you can flush all caches. This is necessary during development if you changed files like Fluid templates, TypoScript files, or PHP files.

It is also necessary to flush caches after installing or updating extensions.

You can achieve the same effect by calling

ddev typo3 cache: flush

Analyze Database Structure

Aside its name this tool does not only analyze the database structure but also offers to fix it for you.

Database changes can be necessary when TCA files where changed or extensions installed / updated.

Create Administrative User

This tool can be used to create a new administrative backend user with or without maintainer privileges.

You can also create a new backend user from the console:

ddev typo3 backend:user:create

and from the module System > Backend Users. The latter cannot grant system maintainer rights but is available to all admins.

Permissions

In TYPO3, you can grant permissions to backend users. At first, a newly created backend user without any administrative privileges has no access to neither the page module nor the pages in the backend. The module System > Permissions can be used to view or edit these backend user permissions for pages in the backend.

See also TYPO3 Explained, Permissions management.

Backend Users

The module System > Backend Users is used to create, edit and delete backend users.

See also TYPO3 Explained, Backend user management.

Reactions (optional)

This module is only available if the system extension typo3/cms-reactions is installed. This extension handles incoming webhooks to TYPO3. It also provides a corresponding backend module to manage reaction records.

It has its own manual: TYPO3 Reactions.

Webhooks (optional)

This module is only available if the system extension typo3/cms-webhooks is installed. This extension handles outgoing webhooks to TYPO3. It also provides a corresponding backend module to manage webhook records in TYPO3.

Unfortunately this extension is not documented at the time of writing.

Scheduler (optional)

This module is only available if the system extension typo3/cms-scheduler is installed.

The Scheduler supports one-time or periodic execution of tasks that can be delivered by any extension. It has its own manual: TYPO3 Scheduler.

crontab -e

DB check (optional)

This module is only available if the system extension typo3/cms-lowlevel is installed.

The Database (DB) check module offers functions related to the database and its content.

Record Statistics

Shows a count of the various records in the database, broken down by type for pages and content elements.

Relations

Checks if certain relations are empty or broken, typically used to check if files are being referenced.

Search

A tool to search through the whole database. It offers an advanced mode which is similar to a visual query builder.

Check and update global reference index

TYPO3 CMS keeps a record of relations between all records. This may get out of sync when certain operations are performed without the strict context of the backend. It is therefore useful to update this index regularly.

Some third party extensions offer similar but extended functionality around the database, for example fixpunkt/backendtools can be used during development to find all pages that contain a certain plugin or that use a certain backend layout etc.

Configuration

The Configuration module can be used to view the various configuration arrays used by the CMS. It is not the goal of this tutorial to describe the role of each of these arrays, you can discover their function as you dig deeper into TYPO3 CMS. Let's just mention that the $GLOBALS['TYPO3_CONF_VARS'] contains global configuration values.

Reports (optional)

This module is only available if the system extension typo3/cms-reports is installed.

The System > Reports module contains information and diagnostic data about your TYPO3 installation. It is recommended that you regularly check the "Status Report" as it will inform you about configuration errors, security issues, etc.

This module has its own dedicated manual: TYPO3 Reports. It can be extended by third-party extensions. For example apache-solr-for-typo3/solr offers its own section in the report module.

Log

The TYPO3 CMS backend logs a number of actions performed by backend users: login, cache clearing, database entries (creation, update, deletion), settings changes, file actions and errors. A number of filters are available to help filter this data.

Files and directories on project level

The composer.json contains the requirements for the TYPO3 installation and the composer.lock contains information about the concrete installed versions of each package. For further information see here.

Extensions as Composer packages

If you have worked with other PHP based projects you have probably run across Composer packages.

Each TYPO3 extension is a Composer package of type typo3-cms-extension. Extensions provided by the TYPO3 Core have type typo3-cms-framework.

The minimum needed to define a TYPO3 extension is:

A directory containing a file called composer.json with at least the following data:

{
    "name": "myvendor/my-extension",
    "type": "typo3-cms-extension",
    "require": {
        "typo3/cms-core": "^13.4",
    },
    "extra": {
        "typo3/cms": {
            "extension-key": "my_extension"
        }
    }
}

In order to be used the Extension should be installed via Composer.

There is a legacy way to install extensions without Composer but it is not recommended anymore and not covered in this Guide. For this legacy way of installation as well as for functional tests or to publish your extension your need a file called ext_emconf.php. This topic is also not covered here.

Extension vs plugin

A TYPO3 extension is a similar concept to what is called a "Plugin" in WordPress.

In TYPO3 a plugin is a content element that can be inserted into one or all pages, typically providing dynamic or interactive functionality.

The data to be displayed is usually supplied by a special PHP class called a "controller".

One TYPO3 extension can provide several plugins - or none at all.

See also: Plugins in TYPO3 (TYPO3 explained).

Therefore in TYPO3 extensions and plugins are different concepts.

Types of extensions

Internally the TYPO3 Core consists of mandatory and optional system extensions each of them is a Composer package. All mandatory system extensions and a few recommended ones will be automatically installed during the Installation. Optional system extensions can be installed via Composer or the Extension Manager in classic mode

Third party extensions offer additional functionality. Find commonly used extensions in the list of Recommended Extensions. There are extensions available for many different use cases, see also chapter How to find extensions.

A site package is an extension that you install locally and only in your project. It contains the templates and assets as well as configuration for your theme. It can also contain specialized plugins or other pieces of software used only in this one project.

What is caching in TYPO3?

Caching is a process TYPO3 uses to temporarily store content and data to help your website load faster and perform efficiently. Instead of regenerating every page or content piece each time a visitor loads it, TYPO3 saves a "cached" version. This way, the system can quickly serve this saved content, reducing the load on the server and speeding up the response time for users.

How to clear caches in TYPO3?

When you update content or make configuration changes, TYPO3 sometimes needs a cache refresh to reflect these updates on the live site. Here are the main ways to clear caches in TYPO3 13:

• Clearing Cache in the backend:

  • In the Backend, look for the Clear cache icon, which resembles a lightning bolt. You can find this in the top bar.

    

  • For deeper cache management, you can use the Install Tool: In Admin Tools > Maintenance you can find the option to clear all caches. This will refresh everything, including caches that aren't typically cleared through the backend top bar.

• Clearing caches via Command Line

  For advanced users or developers, caches can also be cleared from the command line:

  ddev typo3 cache:flush

  Copied!

When should you clear caches?

• If new content, images or text doesn't show up right away.
• When adjusting templates, extensions or system settings.
• While working on custom code, plugins or during site updates.

"Hello world" example in TypoScript

Put the following TypoScript in a file called setup.typoscript within your Site set. The site set is the folder containing your site configuration.

# Create the frontend output of the page
page = PAGE
page {
    # Show a text with value "Hello world."
    10 = TEXT
    10.value = Hello, world.
}

1. Is a comment. See the Syntax of comments in TypoScript: Comments.
2. Assigns a top level object of type PAGE to a variable called page.
3. The page gets more options in this block. See the Blocks in the TypoScript syntax.
4. Another comment.
5. Assigns a content object (also called "cObject") of type TEXT to index number 10 of page. It has the path page.10 if you want to change it later.
6. Assigns the value Hello, world. to the value property of the TEXT cObject stored in path page.10.

Clear all caches via the following console command or the button in the backend:

ddev typo3 cache:flush

You can now preview the result.

Resulting web page

Here is the resulting web page HTML source for both the TypoScript-only and the Fluid-based implementations. Notice how TYPO3 has added default markup around the single line of content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <!--
       This website is powered by TYPO3 - inspiring people to share!
       TYPO3 is a free open source Content Management Framework initially
       created by Kasper Skaarhoj and licensed under GNU/GPL.
       TYPO3 is copyright 1998-2018 of Kasper Skaarhoj. Extensions are
       copyright of their respective owners.
       Information and contribution at https://typo3.org/
    -->
    <title>Example site - Start page</title>
    <meta name="generator" content="TYPO3 CMS">
</head>
<body>
Hello, world.
</body>
</html>

Debug the TypoScript in the backend module "Active TypoScript"

Open the backend module Site Management > TypoScript > Active TypoScript.

You can find the variable page that you just defined. The other variables have been created by TypoScript loaded globally by the TYPO3 Core and system extensions. They are some of the Reserved top-level objects.

Play around with TypoScript

You can now try out a couple of TypoScript commands to familiarize yourself with TypoScript.

Here are some examples:

page = PAGE
page {
    10 = TEXT
    10 {
        value = Hello, world.
        stdWrap.wrap = <p>|</p>
    }
}

page = PAGE
page {
    10 = TEXT
    10 {
        value = Hello, world.
        wrap = <p>|</p>
    }
}

page = PAGE
page {
    5 = TEXT
    5 {
        stdWrap.field = title
        stdWrap.wrap = <h1>|</h1>
    }
    10 = TEXT
    10 {
        value = Hello, world.
        stdWrap.wrap = <p>|</p>
    }
}

page = PAGE
page {
    10 = TEXT
    10 {
        value = Hello, world.
        stdWrap.wrap = <p>|</p>
    }
    5 = TEXT
    5 {
        stdWrap.field = title
        stdWrap.wrap = <h1>|</h1>
    }
}

User TSconfig

User TSconfig is a set of configuration values that affect backend users. Best practice is to set them globally (in a site package TSconfig file) but they can also be set at the backend user or group level (then affecting all users in that group). Things that can be configured are generally related to permissions for basic functionality, for example, whether a user can clear the cache.

There are also configuration values for the TYPO3 Admin Panel (which is shown in the frontend and not the backend).

Page TSconfig

Page TSconfig is a set of configuration values that affect pages. It is often set globally at the site level (in a site package TSconfig file) but can also be set at the page level and then affects that page and all the pages below it in the tree. The things that can be configured mainly affect the look and feel of the backend, such as which fields are available when editing a content element. In general, page TSconfig dictates what a user sees when they click on modules under Web in the left-hand module bar that open a pagetree, e.g. Page, View, List.

Where to find more information

To learn more about TSconfig and how to use it in your TYPO3 projects, refer to the official TYPO3 documentation:

• Using and setting TSconfig

Quick Introduction to Fluid

TYPO3 uses a template engine to generate the necessary HTML markup for a website. The template engine provides data from the backend, such as content or menu structures, which can then be formatted with HTML.

TYPO3's template engine of choice is called Fluid. Fluid's syntax is inspired by the syntax of HTML or XML documents, so it should already be familiar for users that already know HTML.

While Fluid is extendable by PHP developers, knowing any PHP is not necessary to write templates for TYPO3. However, Fluid comes with its own syntax rules, which need to be obeyed when writing templates.

Fluid Basics

<h1>{myHeadline}</h1>

<p>{myVariable.mySubItem}</p>

{myNumber + 5}

<f:format.case mode="upper">{myText}</f:format.case>

<f:if condition="{myVariable} == 'hello'">
    The variable is "hello".
</f:if>

<ul>
    <f:for each="{myList}" as="myItem">
        <li>This item is {myItem}.</li>
    </f:for>
</ul>

Directory structure

Nowadays, Fluid templates in TYPO3 are always part of an extension. As they are neither PHP code nor configuration files and don't need to be accessed by end users, they are placed in the Resources/Private/ subfolder.

The displayed folder structure is the convention for the location of template files in a sitepackage extension. However, be aware that these paths might vary slightly between projects or extensions as they can be configured individually.

Fluid in depth

What is TCA used for?

TCA is used to:

• TCA lets you define the fields of a database table, specifying data types, labels, default values, and constraints. You can configure various input types like text fields, checkboxes, and dropdowns.
• TCA controls how forms are rendered in the TYPO3 backend. It defines the fields that are shown, their layout, and whether they are required or optional.
• TCA allows developers to enforce validation rules on fields to ensure data integrity. For example, you can set a field to only accept numeric values or enforce a specific character limit.
• TCA supports defining relationships between tables, such as one-to-one, one-to-many, and many-to-many relations. It manages how records from related tables are linked and displayed in the backend.
• TCA handles which fields and records are editable, based on user roles and permissions.
• TCA extends existing tables and creates new ones with custom field definitions

For example, when you create a new content element or extend an existing one, you define the fields using TCA in the Configuration/TCA directory of your extension. TYPO3 then uses this configuration to build the backend interface for editors.

Where to find more information

To learn more about TCA and how to use it in your TYPO3 projects, you can refer to the official TYPO3 documentation:

• TYPO3 TCA Reference
• Database records
• Relations between Extbase models

Media and downloads

Media and downloads must be stored in fileadmin. In standard Composer-based installations, as we assume you have here, they are stored in public/fileadmin/.

Read more about this folder: TYPO3 Explained, folder "public/fileadmin/".

Files in the fileadmin directory are managed by the File abstraction layer (FAL).

They can be uploaded, moved and deleted in the backend module File > Filelist by administrators and depending on permissions, by editors.

Assets in extensions and site packages

Assets usually include CSS files, JavaScript and images / icons used for design purposes.

Within an extension, including a site package, they can only be placed in the Resources/Public folder and subfolders of this folder.

During Composer installation the Resources/Public directories of all installed extensions are symlinked into the public/_assets webroot folder. For security reasons the folders in public/_assets have hashed names.

Read more about this folder: TYPO3 Explained, folder "public/_assets/".

Advanced installation topics

Install Docker

Docker is required to run DDEV containers.

• Visit docker.com and download the latest version for your operating system.
• Follow the installation instructions for your platform (Windows, macOS, or Linux).

Install DDEV

Once Docker is running, install DDEV by following the official installation instructions:

Installing DDEV

This page covers installation for macOS, Linux, Windows, and WSL, and is kept up-to-date.

Check your DDEV installation

After installing, verify that Docker and DDEV are available:

docker --version
ddev version

If both commands return version information, installation was successful.

When DDEV is up and running, you can continue with Installing TYPO3 with DDEV.

Update DDEV

DDEV releases frequent updates with new features, bug fixes, and improvements. It is recommended to keep DDEV up to date.

For instructions on how to update DDEV on your operating system, see the official DDEV Upgrade Guide.

After updating, verify the installed version:

ddev version

Managing the database

Running ddev start automatically creates a database for you. DDEV also creates the file config/system/additional.php, containing the database credentials.

You can access your database using any local database client.

On Windows, you can quickly open the database in HeidiSQL:

ddev heidisql

Other popular database clients include TablePlus, Sequel Ace, and DBeaver.

For more details, see the DDEV documentation on Database GUIs.

Sending emails

DDEV captures outgoing mails and stores them for review. You can view sent emails with:

ddev launch -m

Stopping a DDEV instance

If you want to stop all running DDEV projects, run:

ddev poweroff

The projects will remain configured and databases will be persisted.

Deleting a DDEV instance

If you want to delete the project you created, run the following command inside your project root folder:

ddev delete --omit-snapshot

This removes all containers for the project and deletes the database.

Afterwards you can safely delete the project root folder manually if needed.

DDEV documentation

You can find detailed documentation at DDEV Documentation. There is also a TYPO3 Quick Start that parallels this guide.

Quick Start: TYPO3 Installation with DDEV

The following commands will create a new TYPO3 project, initialize DDEV, install TYPO3 via Composer, and run the setup. Copy and paste them into your terminal.

# Create project directory
mkdir my_project && cd my_project

# Initialize DDEV project
ddev config --php-version 8.4 --docroot public --project-type typo3

# Start DDEV
ddev start

# Install TYPO3 via Composer
ddev composer create "typo3/cms-base-distribution:^13"

# Run TYPO3 CLI setup (database credentials are pre-filled)
ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db

# Open the Backend login in a browser
ddev launch /typo3/

Next steps: TYPO3 setup on first installation

Step-by-step: TYPO3 Installation with DDEV

mkdir my_project
cd my_project

ddev config --php-version 8.4 --docroot public --project-type typo3

ddev start

ddev composer create "typo3/cms-base-distribution:^13"

~/projects/typo3/sites/my_project$ ls -a
composer.json  composer.lock  config  .ddev  .gitignore  LICENSE  packages  public  README.md  vendor

Set up TYPO3 using the console

To perform an interactive guided setup, run:

# Run TYPO3 CLI setup (database credentials are pre-filled)
ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db

When prompted, provide the following answers to match the default DDEV configuration:

Admin username (user will be "system maintainer") ? j.doe
Admin user and installer password ?
Admin user email ? j.doe@example.org
Give your project a name [default: New TYPO3 Project] ? My Project
Create a basic site? Please enter a URL [default: no] https://my-project.ddev.site
✓ Congratulations - TYPO3 Setup is done.

Set up TYPO3 using the web installer (1-2-3 install tool)

Alternatively, you can use the web-based Install Tool to set up TYPO3.

1. Create a file named FIRST_INSTALL in your webroot:

   ddev exec touch public/FIRST_INSTALL

   Copied!

2. Open the TYPO3 installer in your browser:

   ddev launch /typo3/install.php

   Copied!

3. After completing the setup, access the TYPO3 backend:

   ddev launch /typo3

   Copied!

Log in using the credentials you just created during the setup process.

Set the application context for local development

After completing the setup, TYPO3 will run in the "Production" application context by default.

For local development, it is recommended to switch to the "Development/DDEV" context for better error reporting, debugging features, and developer-friendly features.

Edit your .ddev/config.yaml and add:

environment:
  - TYPO3_CONTEXT=Development/DDEV

Restart DDEV to apply the changes:

ddev restart

When and why should we perform TYPO3 updates?

With the newest version of TYPO3 you receive free bugfixes and free security patches for at least three years from the time of the first LTS minor (for example v13.1) release.

In TYPO3 however, we follow a specific cycle which usually takes 1.5 years long. Every 1 and a half year a new TYPO3 version occurs.

We explain the different parts in the roadmap now. When you follow the roadmap you see dark red strokes. They represent the sprint releases. Sprint release is a version that starts for example with v13.0 and then the next sprint release follows with v13.1. After the last sprint release (v13.3) the Long Term Support release (LTS release) v13.4 follows. The aim of the sprint releases is to test the new code with the new features extensively, until the LTS-release is reached. Therefore, the reason for sprint releases is to make the new code with the new features as agile and stable as possible. The order is: sprint release (0), sprint release (1), sprint release (2), sprint release (3), LTS release (4). Sometimes more sprint releases are possible.

The green area represents the regular maintenance state. The orange area is the time where the focus lays on fixing bugs - so it is the bug fixing phase. The light orange area corresponds to the extended support. This means, when you want to get further bugfixes you have to book an extended support which usually costs money.

Before we look a bit deeper into the types of updates we summarize how a TYPO3 user should act with respect to TYPO3 updates:

• When a new major LTS version is released, users should focus on updating to this version as soon as possible.
• When a new minor version is released, users must update to the new minor version, since the previous minor version is not supported any more.
• When a new patch level version is released, users should always update to the new version, because it contains important bugfixes and security fixes (if announced). Here you find the security advisories.

Additionally, users should take care of updated extensions on a regular schedule in order to use the most recent versions.

When you feel safe with the concepts of TYPO3 updates you can in general use this Upgrade Guide.

Now we explain the types of updates.

Major, minor and patch level updates

In TYPO3 you can update your TYPO3 version. There exist three different types of updates:

1. Major updates: for example, from 12.4.23 to 13.0.0
2. Minor updates: for example, from 13.0 to 13.1
3. Patch and bugfix level updates (often security updates): for example, from 13.4.0 to 13.4.1

Extension updates

In a TYPO3 instance you have usually third party extensions installed. When you update your TYPO3 version, you have to update the third-party extensions too. In the `TYPO3 Extension Repository (TER) <https://extensions.typo3.org/>`__ you can enter the name of that extension and get information about supported TYPO3 versions. Some extension authors prefer to only publish their extensions on packagist. When the extension does not exist for the current TYPO3 version you can create an issue or search for an alternative extension offering the same functionality. For example, the gridelements extension was replaced by the container extension, both having equal functionalities.

Useful commands to simplify the updates of extensions can be found in the Upgrade extensions guide.

Deprecations

In TYPO3, deprecations indicate that a specific functionality will be removed in the next TYPO3 version. For further information we refer to the article about deprecation. For example the deprecation: #105171 - INCLUDE_TYPOSCRIPT TypoScript syntax - a deprecation notice telling you that in TYPO3 v14 you can't use the TypoScript syntax INCLUDE_TYPOSCRIPT to include TypoScript files anymore.

Little Helpers: Rector and Fractor

In general you can use extensions like Rector or Fractor to find and replace deprecations. To reach this, you have to fill out a configuration file (in Rector rector.php, in Fractor fractor.php) that defines the scope in which you want to perform deprecation replacements. For both extensions, only the rules that exist can find the respective deprecation. For instance, check the overview of existing rules for Rector or search for your desired Rector rule if it already exists. When a rule is missing, you can't find the deprecation using the extension. If you feel able to create your own Rector or Fractor rule and want to share it with the TYPO3 community, everyone using these tools would be happy to benefit from your efforts.

Language updates

After a TYPO3 update, you have to update your translations. We refer to the article Update backend translations. You have to update the language packs that you are using after each TYPO3 update.

Using Git and Composer on the webserver

• Check if Composer is available on the production server. If it is not available consider to use the latest composer.phar.
• Keep all development related files in a Git repository.
• Clone this repository on your production server.
• Copy the database to the production server.

• Install TYPO3 without dev dependencies on the production server:

  composer install --no-dev

  Copied!
• Compare the database
• Fix file permissions
• Clear caches

If you do a composer install directly on the production server you might experience some problems. For this reason some developers and administrators decide not to do it:

• There can be several minutes of downtime even if the installation goes smoothly.
• The installation might fail if some packages are not available.
• You might accidentally call composer update as is often done during development and do unintended, untested updates.
• You might omit the --no-dev option and accidentally install packages that are not save to be used during production.

Some of these problems can be fixed by using a symlink strategy where one directory is running on production and another one is being updated.

Build locally and copy all files and symlinks to the server

• Build the local environment (installing everything necessary for the website)
• Run composer install --no-dev to install without development dependencies
• Copy files to the production server
• Copy the database to the production server
• Compare the database
• Fix file permissions
• Clear caches

There can be several problems with this strategy:

• Copying files or unzipping files can be slow, there can be several minutes of downtime.
• A TYPO3 installation depends on symlinks. Make sure these symlinks are preserved during copying and or compressing files.

Automatic deployment

There are multiple tools that can be used to automate deployment. Read more about it: TYPO3 Explained, automatic deployment.

Setting the application context

If the application context is not set it is Production by default so that you don't have to do anything on the production server.

In DDEV you should set the application context to Development/Local to enable debugging and different site configurations for DDEV and your live server.

Create a file called docker-compose.context.yaml in your .ddev path with the following content:

services:
  web:
    environment:
      - TYPO3_CONTEXT=Development/Local

Restart DDEV using

ddev restart

Local development

When you installed TYPO3 with DDEV, DDEV automatically created a file called config/system/additional.php for you. This file includes server settings needed only during development, including:

• A connection to the local database in DDEV
• Configuration of Mailpit to enable debugging of emails
• Image magic configuration so that images can be scaled and edited
• Enabling enhanced error reporting

You should not deploy this file to your production server but create one just for the production server. See section Production environment

Production environment

It is not recommended to put credentials into a file that is kept under version control. However, many other settings should be kept under version control.

We recommend putting all configuration containing credentials into a special file that is not kept under version control and include it in your config/system/additional.php.

Create a file called config/system/credentials.php:

<?php

defined('TYPO3') or die();
$customChanges = [
    'BE' => [
        'installToolPassword' => 'some encrypted string',
    ],
    'DB' => [
        'Connections' => [
            'Default' => [
                'dbname' => 'my_db',
                'host' => 'localhost',
                'password' => '<secure password>',
                'user' => 'my_db_user',
            ],
        ],
    ],
    'SYS' => [
        'encryptionKey' => 'replace with generated encryption key',
    ],
];

You can now include this file in your config/system/additional.php:

<?php

defined('TYPO3') or die();

$customChanges = [
];

$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
$file = realpath(__DIR__) . '/credentials.php';
if (is_file($file)) {
    include_once($file);
    $GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
}

The following steps are needed for a secure production context:

• Generate a unique encryption key and put it in $customChanges['SYS']['encryptionKey'] in your config/system/credentials.php.
• Choose a new install tool password and put its hash into $customChanges['BE']['installToolPassword'].
• Replace the database credentials in the $customChanges['DB']['Connections']['Default'] section with database credentials for your server.

Further settings important for security can be made directly in the config/system/additional.php:

<?php

defined('TYPO3') or die();

$customChanges = [
    'BE' => [
        'debug' => '0',
    ],
    'FE' => [
        'debug' => '0',
    ],
    'SYS' => [
        'trustedHostsPattern' => 'SERVER_NAME', // keep this if it is working on your server
        'devIPmask' => '127.0.0.1,::1', // localhost oly
        'displayErrors' => 0, // Turn off error reporting
    ],
];

$GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
$file = realpath(__DIR__) . '/credentials.php';
if (is_file($file)) {
    include_once($file);
    $GLOBALS['TYPO3_CONF_VARS'] = array_replace_recursive($GLOBALS['TYPO3_CONF_VARS'], (array)$customChanges);
}

Please refer to the security guide in getting started to check which settings are currently recommended for a secure production environment:

Global TYPO3 configuration options

Suggested configurations might change in future security bulletins.

You can put any of the suggested changes into the $customChanges array of your config/system/additional.php.

Create a new page on root level

Once you log into the TYPO3 backend, locate the Web > Page module on the left-hand side of the screen. Click on the Page module to open the page tree.

• In the page tree, right-click on the "root level" or the top node of the page tree (if no pages exist yet, this will likely be labeled as "site" or similar). A context menu will appear.
• From the context menu, select "New". This will open a form for creating a new page.

Configure the newly created page

Now, you need to configure the new page:

• In the form that appears, give your new page a name. This will be the label of your root page in the page tree.
• Under the Behavior tab, look for the checkbox called "Use as Root Page". Ensure this is checked.

Save the page

Once you have filled in the necessary information and selected the "Use as Root Page" option, click the "Save" button at the top of the form. Your new root page will now appear in the page tree on the left. The page is only visible in the Backend at this point

Configure the site

All sites must have a site configuration. If you have created a new page in the root of the page tree, the site configuration has been created automatically and you can edit it:

Create a site package for the theme

The site needs a theme, also known as a "site package" in the TYPO3 world. Learn more about creating a site package.

Trouble shooting

TYPO3 does not come with a default theme. You will have to install or create a site package. If your site does not have a theme configured, you will see a message like the the one below when trying to display the page in the frontend:

• How to create a site package
• Troubleshooting "No TypoScript found!"
• The Introduction Package includes a ready-to-use theme and example content.

Enable the page when you are ready

Enable the page as newly created pages are hidden by default.

Create a new site configuration

Before creating a site configuration, you should have created the root page of your site in the page tree.

The site configuration is stored in a file called config/sites/my_site/config.yaml. For your convenience, you can edit this file using the backend module: Site Management > Sites.

Available root pages should be listed in this module. Click the button Add new site configuration next to the relevant page to create a site configuration for it.

Edit the site configuration

You can now enter some basic information about the site.

The site identifier can be arbitrary, so we use "example_site" here. The entry point should be a URL pointing to the web root. In this example, it is a local URL generated by DDEV.

From the list of available sets, choose the set for your site package if you have one. You can learn how to create a site package in the TYPO3 Sitepackage Tutorial.

Since our set already depends on the set of fluid_styled_content, it is not necessary to choose that set here.

In the next two tabs, you can define error handling, such as a custom 404 page, and static routes, for example, to a robots.txt file.

You can read more about Site Handling in the reference "TYPO3 Explained".

After saving, a new file should be created in your project:

base: 'https://example-typo3131.ddev.site'
dependencies:
  - t3docs/site-package
languages:
  -
    title: English
    enabled: true
    locale: en_US
    hreflang: ''
    base: /en/
    websiteTitle: ''
    navigationTitle: English
    flag: en-us-gb
    languageId: 0
rootPageId: 7
websiteTitle: 'My example page'

Site management: Trouble shooting

Set of Site Package not available

If the set of your site package is not available make sure, that the site package extension is Installed.

If the site package is installed but the site package set is still not available the set or one of its dependencies might be corrupted.

New in version 13.4.5

The site sets are cached. If you change the site set configuration and see no difference, clear the caches.

This site depends on invalid site sets

If a set or one of its dependencies becomes corrupted after it has already been added to a site configuration, an error box appears in the table of configurations.

This can happen for example when you uninstall an extension on which your site package depends. In this case install the extension again or remove the dependency from your site package.

The site sets are cached. If you change the site set configuration and see no difference, clear the caches.

On saving TYPO3 keeps creating empty language configurations

On saving the site settings TYPO3 keeps creating empty language configurations.

This can happen if you deleted the language configuration with uid 0. If you only need to use one language this one language has to have the uid 0.

Edit the auto created language to fit your language needs.

Sometimes it is easier to just edit the site configuration file:

 base: 'https://site-introduction.ddev.site/'
 languages:
   -
     title: English
     enabled: true
     locale: en-US
     hreflang: ''
     base: /
     websiteTitle: ''
     navigationTitle: ''
     flag: global
-    languageId: 1
+    languageId: 0
 rootPageId: 1
 websiteTitle: ''

Copied!

Change the language id of the only language from 1 to 0.

Malformed inline YAML string at line 17

If you manually edited the site configuration and it contains a syntax error, the whole backend module might stop working:

Fix or delete the affected site configuration by editing the file, for example config/sites/my-site/config.yaml.

No pages found

If you see the following you cannot add any site configuration until you fix the problem in the page tree:

If you have not created any pages yet, create a root page first.

If you have created pages but still see the message, set the flag "Use as Root Page" in the page properties, tab "Behavior" for the page that should be the startpage of your site. A root page is displayed with a globe icon in the page tree.

Global settings

Global settings can be made in the modules under the Admin Tools section, which updates the config/system/settings.php file. Alternatively, settings can be overridden manually in the config/system/additional.php file. Avoid making manual changes to the first file mentioned, as it is auto-managed.

Global extension settings

Global settings for installed extensions, including some that are part of a default installation, can be made in the Admin Tools > Settings > Extension Configuration submodule.

After opening the submodule, you can make your changes and hit "Save":

Note

The config/system/settings.php file has to be writable. If you keep it under version control, make sure to commit and push your changes.

Site handling

One TYPO3 installation can contain more then one site. Even if you only have one site in your installation, important settings can be made in the Site Configuration. Read more about this in the chapter: Create a new site configuration.

Site configurations are stored in a file called config/sites/my-site/config.yaml and can be edited from the Site Management > Sites module. Each site must have a unique key, called the "Site Identifier". For demonstration purposes, we use "my-site" here. The Site Identifier is also used as the path for saving the configuration file.

Find detailed information in TYPO3 Explained, Site handling.

Site settings

New in version 13.3

Starting with TYPO3 v13.3, site settings can also be edited in the site settings editor.

You can edit site settings in the Site Management > Settings module. Changes are written to the config/sites/my-site/settings.yaml file. If you keep this file under version control, you must commit and push the changes made to this file.

You can find more information about this editor in TYPO3 Explained, Site settings editor.

If site settings are available, refer to the documentation of the extension offering them.

The following optional Core extensions offer site settings:

• typo3/cms-fluid-styled-content : Site set "Fluid Styled Content". Commonly used in projects that do not depend on bk2k/bootstrap-package .
• typo3/cms-felogin : Settings for the "Frontend Login" site set. Used to offer a login for frontend users.
• typo3/cms-indexed-search : Settings of the site set "Indexed Search". Used to display a search box and offer basic indexing of a page without the need for a Solr core, as would be required by apache-solr-for-typo3/solr .
• typo3/cms-seo : Site sets settings of EXT:seo. Used to improve meta tags and page titles, and provides an XML sitemap.

You can define custom site settings in your site package: TYPO3 Sitepackage Tutorial.

For detailed information on this topic, see also TYPO3 Explained, Site settings.

Page wide frontend definitions: TypoScript

TypoScript is a configuration language used to configure both the frontend output and the backend of a TYPO3 web site. TypoScript can be managed in a TypoScript record, which can be found in the Site Management > TypoScript module.

TypoScript affects the page on which it is defined, and any subpages. In most cases, TypoScript is only defined on the root page of a site. In this case. the settings made here affect the entire page.

You can also navigate between the different submodules by using the submodule menu:

See also the complete TypoScript Reference.

Page wide backend settings: Page TSconfig

Read more about this topic in Setting page TSconfig.

How to create a site package

To create a site package, you have two main options:

• Manual creation: For full control over your project's setup, you can follow the detailed instructions in the TYPO3 site package tutorial.

• Using the Site Package Builder: If you are looking for a faster start, TYPO3's official Site Package Builder is a handy tool. You can choose whether your site package should be based on the Bootstrap Package or fluid_styled_content.

  Fill in the fields in the form, download the site package and save it in the packages directory. Then require the site package using Composer:

  composer require vendor\sitepackagename

  Copied!

  and include the sets in your site configuration.

  

Pros and cons of using the Site Package Builder

Pros:

• The Site Package Builder is particularly useful for beginners or projects that need a quick start.

Cons:

• A large number of unnecessary, mostly empty files are generated.
• Depending on your prior knowledge, you may use code that you do not fully understand.

Installing the Introduction Package

To install the Introduction Package run the following command:

composer require typo3/cms-introduction

composer require typo3/cms-introduction

ddev composer require typo3/cms-introduction

Then run:

vendor/bin/typo3 extension:setup

vendor/bin/typo3 extension:setup

ddev typo3 extension:setup

This will set up the extension ready for immediate use.

First steps with the Introduction Package

The "Introduction Package" creates a number of pre-built pages within the page tree. The top level page is named "Congratulations".

1. Click on "Congratulations" in the page tree.

2. View the page in the frontend:

   Click on the "View webpage" icon (with an eye) to view the page in the frontend.

Create from template

Go to page GitLab - New from template or to path /new#create_from_template on your self-hosted GitLab. And chose TYPO3 Distribution from the list:

Fill in project details

Clone the project

Clone the project to your local machine. You can download the SSH link from the Code dropdown:

Then clone the repository:

git clone git@gitlab.com:linawolf/getting-started-with-the-gitlab-template.git

Start DDEV and setup TYPO3

You can start and setup the project locally in DDEV using the built-in command:

ddev typo3-init

See also file Readme.md in the root of your project.

This step automatically creates several files that should be added to git:

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        composer.lock
        config/sites/
        package-lock.json

nothing added to commit but untracked files present (use "git add" to track)

$ git add .

:file:`composer.lock`
    This file contains the information which exact versions of PHP packages
    are installed.
:file:`package-lock.json`
    This file contains the information which exact versions of npm packages
    are installed.
:file:`config/sites/`
    Contains configuration and settings of the site that was created during
    setup.

Log into the TYPO3 backend

If allowed by your system the TYPO3 backend login will be automatically opened in a browser. Otherwise you can open a browser of your choice with the link displayed in the console.

A default user has been created. Username and password are displayed in your console.

Once logged in, you can preview a page and see it rendered with a basic theme.

Directory structure of the project

Creating a TYPO3 backend administrator

There are 3 ways to create a new TYPO3 backend administrator:

ddev typo3 backend:user:create

vendor/bin/typo3 backend:user:create

Using the backend module "Backend Users" to create admins

The first administrator got created for you during Installation.

When you log into the backend (See Backend login) you can go to module Backend Users and create a new administrator there.

When creating the user check the "Admin" option:

You can Grant System Maintainer rights in the Admin Tools later on.

Using the Install Tool to create an administrator

Access the Install Tool at https://my-site.ddev.site/typo3/install.php using the Install Tool password defined during the installation process.

If they should be a System Maintainer check the box.

Granting System Maintainer rights

Using the module Admin Tools > Settings and card "Manage System Maintainers Access" you can manage which administrator accounts should be granted "System Maintainer" rights.

On saving the changes are written to file config/system/settings.php therefore this file needs to be writable.

If your installation also has a file called config/system/additional.php the settings can be overridden here. In this case changes you make in the Admin Tools do not take effect.

A setting overriding the System Maintainer list could look like this:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['systemMaintainers'] => [
    1,
    3,
    42
];

This setting is also documented in systemMaintainers.

Login page reloads without error

• Try deleting all browser cookies and caches or use a different browser / device. There might be an outdated cookie that prevents log-in.
• Clear all TYPO3 caches via console command or install tool.
• Delete folder var/cache to remove possible corrupted cache data.
• Check the cookies configuration in TYPO3: Ensure that cookie-related settings (sessionTimeout, cookieDomain) are correct and not causing session issues.

"Invalid Credentials" error

• Check if the username and password are correct.
• Try to Create a new backend administrator and use that one.

White screen before or after login

Many older TYPO3 files contain a line like the following that needs to be replaced:

-defined('TYPO3_MODE') or die();
+defined('TYPO3') or die();

The PHP constant TYPO3_MODE was removed with TYPO3 v12 but it is still widespread in older code examples and extensions. This can also happen if you installed a TYPO3 extension that is not compatible with newer TYPO3 versions.

If you have this line in your own code, replace it. If you find it in the above code in a third party extension, check if a newer version is available. If you do not find one you can try to reach out to the extension author or patch it yourself.

Access denied before or after login

• If the line above contains "Access denied." or a similar string that string will be output and the login page contains nothing else:

  -defined('TYPO3_MODE') or die('Access denied.');
  +defined('TYPO3') or die('Access denied.');

  Copied!

  The solution is the same like for White screen before or after login.

• Check file permissions on the TYPO3 files.
• Check the .htaccess or Nginx configurations

"Account locked" message

• Wait the required time
• Or delete the folder var/cache

"Page Not Found" or 404 Error

• Check file permissions on the TYPO3 files.
• Check the .htaccess or Nginx configurations

Broken login form or missing elements

• Try deleting all browser cookies and caches or use a different browser / device. There might be an outdated cookie that prevents log-in.
• Clear all TYPO3 caches via console command or install tool.
• Was there a warning during composer install? The _assets folder might not have been properly symlinked during installation.
• Check the browser console for errors.

Tips for choosing the right TYPO3 extension

Selecting the right extension is essential for ensuring that it meets your needs and integrates well into your TYPO3 setup. Here are a few key factors to consider:

• Compatibility:

  Verify that the extension is compatible with your version of TYPO3. The TER and Packagist often display compatibility information. Choosing an incompatible extension can lead to errors or unexpected issues.

• Popularity and reviews:

  Extensions that are frequently used and have good reviews are often more reliable. Look at download numbers, ratings, and user feedback in the TER or on GitHub to get a sense of the extension’s quality.

• Support and updates:

  Check if the extension is actively maintained and updated to work with the latest TYPO3 versions. An extension with recent updates is more likely to be secure and compatible with modern TYPO3 standards.

• Documentation:

  Good documentation is essential, especially for beginners. Ensure that the extension has clear setup and configuration guides, either in the TER, on the developer's website, or on GitHub.

• Performance and security:

  Extensions can affect your site’s performance, so choose extensions that are optimized and well-coded. Additionally, check for any reported security vulnerabilities, particularly for older extensions, to keep your site secure.

• Customizability and flexibility:

  If you have specific needs, ensure that the extension is flexible enough to be customized or configured as required. Some extensions provide PSR-14 events or APIs, which are beneficial for custom development.

Find the Composer package name for an extension

Visit the Extension Repository, and search for the extension.

On the extension page , under "Composer support", will be the Composer command required to install that extension.

For example, the extension EXT:news has the package name georgringer/news .

Typically the package name will be vendor + slash + extension key. However, if the extension key contains an underscore, it is replaced with a dash in the package name. For example: EXT:extension_builder:

extension key

extension_builder

vendor

friendsoftypo3

Composer package name

friendsoftypo3/extension-builder

Use composer require to install the extension

composer require <packagename>

To install the news extension:

composer require georgringer/news

This will add the extension requirement to the installations composer.json and install the extension.

Whilst the extension is installed and activated automatically, it still needs to be set up before it can be used:

Setup the extension

./vendor/bin/typo3 extension:setup

The extension setup command takes care of executing additional installation procedures, such as database migrations and clearing caches if necessary. The extension setup command is not specific to a single extension but instead looks at the overall state and executes all necessary steps.

composer remove georgringer/news

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/*/"
        },
    ],
}

composer require vendor/my-local-extension:@dev

Find out the extension key for an extension

The extension key of an extension can be found in its composer.json.

{
    "name": "t3docs/blog-example",
    "type": "typo3-cms-extension",
    "..": "...",
    "extra": {
        "typo3/cms": {
            "extension-key": "blog_example",
        }
    }
}

Before installing an extension, the extension key can be found on its page in the TYPO3 Extension Repository (TER).

The extension key is listed on the top. For the extension EXT:news, the extension key is news.

Prerequisites

• A working TYPO3 installation using Composer.
• Familiarity with Composer
• Basic knowledge of PHP and TYPO3 development concepts
• CLI access to your TYPO3 instance

Why create an extension?

Creating an extension allows you to:

• Add custom features and modules to TYPO3
• Share functionality across multiple TYPO3 instances

How to start developing an extension

Developing an extension involves several steps, from setting up the extension structure to implementing your custom functionality. To guide you through this process, TYPO3 provides a detailed tutorial on extension development.

Please refer to this link for comprehensive, step-by-step instructions on how to create an extension.

Basic steps to create an extension

• Define the purpose of your extension.

  Determine what specific functionality or feature you want to add to TYPO3

• Create the extension skeleton

  Set up the basic structure for your extension.

• Implement the desired features

  Add the necessary PHP classes, TypoScript configuration and templates that will bring your extension's functionality to life.

• Register the extension in TYPO3

  Register your extension so TYPO3 can recognize it. This includes adding it to your instance's configuration.

• Test and refine

  Test your extension to ensure it works as expected and make any needed adjustments.

Development

• TYPO3 console: helhum/typo3-console

  TYPO3 Console is a powerful command-line tool that simplifies many backend tasks for TYPO3. It allows developers to efficiently manage caches, extensions and system maintenance from the command line, making it an essential tool for automated workflows.

Content elements

• Content Blocks: friendsoftypo3/content-blocks

  Content Blocks enable the creation of reusable content elements that can be added to pages in a modular way. This extension is beneficial for sites requiring flexible, component-based design, and simplifies content structuring for editors.

• Containers: b13/container

  The Container extension offers a grid layout system, allowing developers to group multiple content elements into a container. This helps organize page layouts more flexibly, especially useful for responsive or complex designs.

News

• News Management: georgringer/news

  The News extension is a feature-rich solution for managing news articles and blog posts within TYPO3. It offers a comprehensive set of tools for categorizing, tagging, and displaying news content, making it perfect for content-heavy sites.

Search

• Enterprise Search Integration: apache-solr-for-typo3/solr

  Apache Solr for TYPO3 provides a powerful, scalable search solution for TYPO3 sites. Leveraging Apache Solr, this extension enables advanced search functionality and is ideal for large or data-intensive projects where high-performance search is required.

• Built-in TYPO3 Search: typo3/cms-indexed-search

  The Indexed Search extension provides an out-of-the-box search feature for TYPO3. It is straightforward to set up and integrates well with TYPO3's core, making it a great solution for sites that require basic search without additional configuration.

• Elasticsearch Integration: pagemachine/searchable

  Searchable for TYPO3 provides an integration of the Elasticsearch engine, known for its high-speed search capabilities and scalability. This extension is ideal for large-scale websites or applications that demand robust search functionality.

Testing in TYPO3: Unit and Functional Test

Testing ensures that changes to your code do not cause unexpected side effects and that your TYPO3 installation remains reliable. TYPO3 offers robust tools for Unit and Functional Testing.

See here for more information.

Coding Guidelines

Following coding guidelines (CGL) ensures your code is consistent, readable and maintaineble. TYPO3 adheres to strict standards for PHP, TypoScript and JavaScript.

More information about CGL can be found here.

Rich Text Editor Configuration

The Rich Text Editor (RTE) in TYPO3 enables content creation and editing in the backend. Custom configurations can improve usability and consistency. It can be configured using TypoScript and YAML.

You can find more information here.

Multilanguage Handling

TYPO3 provides powerful tools for multilingual websites. See here for further information.

For more details see here.

Keep Security In Mind

Security is taken very seriously by the developers of TYPO3. The TYPO3 Security Team manage all security incidents. They review them and consider their impact. Security advisories are regularly published.

More information about security can be found in the Security guidelines.

Contributing

Giving back to the TYPO3 community is a great way to grow as a developer and ensure TYPO3 continues to evolve.

Look here for more information about contributing

French Translation

A French translation has been created by Jonathan Iroulin.

We are currently working on optimizing the rendering. Due to this, there was an issue with rendering the translation. The translated version still exists in a separate branch fr and only needs to be reactivated once the issues with rendering have been solved and the French branch has been reviewed for TYPO3 v9.

Status of This Manual

The current version was updated to reflect TYPO3 CMS 13.4.

Credits

This manual was originally written by Kasper Skårhøj and adapted to TYPO3 CMS 4.5 LTS by Philipp Gampe, Martin Holtz, Susanne Moog and François Suter. It was revised and updated to version 6.2 LTS by Guido Haase, to version 7 LTS by Francois Suter and to version 9.5 LTS by Sybille Peters. Tom Warwick made several language improvements on the 9.5 branch for better readability.

Since TYPO3 documentation can now be edited by the TYPO3 community collaboratively, a number of other people have made changes and improved this tutorial. You can see the list of contributors on GitHub.