Study guide · Software Architecture and Design Patterns

Well-built code: architecture, patterns and tests in TYPO3

As of November 15, 2026 · TYPO3 14.3 LTS · about 18 min read

Where does a piece of code belong? On this page our extension my_extension for conferences grows step by step. You will learn MVC, the repository, Domain-Driven Design, design patterns and SOLID. After that we cover recurring tasks, tests and three small data structures from the core.

Three roles: model, view, controller

MVC stands for Model-View-Controller. The pattern splits an application into three roles:

  • The model holds the data and the business logic. In our case it is the class Conference with properties such as title and date. The model knows neither the controller nor the view.
  • The view presents the data. In Extbase, Fluid templates take on this role.
  • The controller receives the request and evaluates its arguments. It calls the model, repository or services, passes the result to the view and returns a response, such as HTML or a redirect.

In Extbase, models live in Classes, Domain, Model, and controllers in Classes, Controller. This way you can swap a template without touching the logic.

A controller should stay thin and only mediate. Business rules belong in the model and in services, queries in the repository.

Repository and Domain-Driven Design

A repository is the central place to find and store objects of one kind. It behaves like a collection. Martin Fowler describes it as a mediator between the domain and the data mapping layer. The business logic does not know how the query works technically. In tests you can replace it with a test double.

Every Extbase repository extends the class Repository and comes with methods such as findAll(), findByUid(), findBy(), add(), update() and remove(). Your own queries get meaningful names. A controller should not fetch upcoming conferences in a city with its own QueryBuilder call. That query belongs in a method such as findUpcomingByCity() in the ConferenceRepository.

Domain-Driven Design, or DDD for short, aligns the software with the business domain. The key terms are:

  • Ubiquitous Language is the shared language of domain experts and developers. Its words appear directly in classes and methods.
  • A Bounded Context is a clearly delimited area in which this language has one meaning.
  • An entity has its own identity. Two attendees with the same name remain two people. In Extbase the identity is the uid.
  • A value object is defined only by its values. Two identical addresses are equal. It has no identity and is immutable.
  • An aggregate is a group of objects treated as one unit. Its aggregate root is the only way in.

There is one repository per aggregate root. An order gets an OrderRepository, its items get none. You add items only through the order, so the total stays correct.

Design patterns in practice

A design pattern is a proven solution idea for a recurring design problem. It is not a library and not finished code, you adapt it to your situation. If the problem is simple, a pattern only adds abstraction, so leave it out.

The TYPO3 core uses many patterns:

  • Observer: observers register for an event and get notified. The EventDispatcher delivers PSR-14 events to all listeners this way.
  • Chain of Responsibility: each middleware in the PSR-15 stack handles the request or passes it on.
  • Factory: a factory decides which concrete object is created, like the ResponseFactory from PSR-17 or a method createExporter() that returns the right exporter for a format.
  • Decorator: a class with the same interface wraps an object and adds behavior. A caching repository asks the cache first and then the real repository, and the caller does not notice.
  • Strategy: each variant lives in its own class with a shared interface.

TYPO3 does not use Active Record. You write records through repositories, the DataHandler or the QueryBuilder.

The builder assembles a complex object step by step and returns the result at the end. Instead of a constructor with many optional parameters, you set the parts one by one. The QueryBuilder builds a query this way, from calls such as select(), from() and where(). Other builders are the Extbase UriBuilder and the backend UriBuilder. ConnectionPool and CacheManager, on the other hand, are not builders, they hand out finished objects.

A builder collects state. Reused, it still holds the old settings. So you get a fresh QueryBuilder for every query. In an Extbase controller you reset the UriBuilder with reset() before each new link. Otherwise, for example, the target page of the first link ends up in the second one too.

$uri = $this->uriBuilder
    ->reset()
    ->setTargetPageUid(12)
    ->uriFor('show', ['conference' => $conference]);
Code example. The UriBuilder is reset, gets target page 12 and uses uriFor to build a link to the show action with the argument conference.

The SOLID principles

SOLID sums up five principles by Robert C. Martin. They aim at code that is easy to maintain and extend.

  • S for Single Responsibility: a class has exactly one job and only one reason to change. A class that sends mails, writes logs and calculates invoices breaks this rule.
  • O for Open-Closed: classes are open for extension but closed for modification. New cases arrive as new classes. PSR-14 events follow this idea, adding behavior without changing the core. Inheritance is still allowed.
  • L for Liskov Substitution: a subclass must work wherever its parent is expected. A square subclass of a rectangle that throws an exception for different width and height breaks this.
  • I for Interface Segregation: prefer several small interfaces over one big one. If a JSON exporter has to fill empty methods for CSV, PDF and XML, the interface is too big.
  • D for Dependency Inversion: classes depend on abstractions, not on concrete classes.

Our InvoiceService creates a SmtpMailer with new in its constructor. Dependency inversion means it should accept a MailerInterface through dependency injection instead. The concrete class then comes from outside, and a test passes a test double. Calling GeneralUtility::makeInstance() instead of new does not change the hard dependency.

Open-closed often means a strategy. Our checkout picks the payment method with a switch, so every new method changes this class. Instead, each payment method gets its own class with the PaymentProviderInterface. A tag on the interface collects them all.

#[AutoconfigureTag('myext.payment')]
interface PaymentProviderInterface { /* ... */ }

final class CheckoutService
{
    public function __construct(
        #[AutowireIterator('myext.payment')] private iterable $providers,
    ) {}
}
Code example. The interface carries the tag myext.payment. Through AutowireIterator, the checkout service receives all tagged classes and asks each one whether it is responsible.

New payment methods, even from other extensions, now need no change to the service. Moving the switch into a static method would not help.

Convention and metaprogramming

Convention over Configuration means conventions replace settings as long as you do not deviate. Only deviations need configuration. Examples in TYPO3:

  • Extbase finds the template of an action from the controller and action names. For the show action in the ConferenceController, that is the file Show in the folder Templates, Conference.
  • A layout named Default is expected in the folder Layouts below Resources, Private, partials in the folder Partials. Other locations are set with layoutRootPaths and partialRootPaths.
  • The model Conference comes with the repository ConferenceRepository in the folder Domain, Repository.
  • The table of a model is derived from the extension name and the class name.
Resources/Private/Templates/Conference/Show.fluid.html
Resources/Private/Layouts/Default.html
tx_myextension_domain_model_conference
Example paths for the show template, the Default layout, and the table name of the model Conference.

The benefit is less boilerplate and a uniform structure across projects. The drawback: newcomers who do not know the conventions see magic. Deviations need extra, sometimes hidden configuration, for example in the file Classes.php below Configuration, Extbase, Persistence.

The second idea here is metaprogramming: code that generates, analyzes or changes other code at runtime. A description replaces many similar classes and saves repeated code. You still have to test the result.

Typical techniques in PHP:

  • With reflection you read the attributes of a class or method and react to them.
  • The magic method __call() intercepts calls to methods that do not exist.
  • Proxy classes and other code are generated at build time.

In TYPO3, Extbase reads the attribute Validate through reflection. The Symfony container is generated as PHP code during compilation and then cached. A simple loop or a type declaration, on the other hand, is not metaprogramming.

$attributes = (new \ReflectionMethod($class, $method))->getAttributes(Exportable::class);
foreach ($attributes as $attribute) {
    $exportable = $attribute->newInstance();
}
Code example. getAttributes on a ReflectionMethod returns the Exportable attributes, and newInstance builds each attribute object.

Single table inheritance

Our talks and workshops are both subclasses of Session and live in one shared table. This is single table inheritance. A type field in every row says which class a record is.

One table for all sessions tx_myextension_domain_model_session uid type title room 1 talk Caching empty 2 workshop Extbase Room B 3 talk Testing empty Type field from ctrl type in the TCA talk workshop Talk Workshop extend Session
One table, several classes. The type field decides.

In the TCA, the setting type in the ctrl section names the type field. Its value decides the record type and the fields shown in the backend. The core works the same way. The table tt_content uses the type field CType, the table pages uses the field doktype.

Extbase maps the types to classes in the file Classes.php. The parent class lists its subclasses under subclasses. Each subclass names its value in the type field under recordType and its table under tableName. There is no special attribute for this.

return [
    Session::class => [
        'subclasses' => ['talk' => Talk::class, 'workshop' => Workshop::class],
    ],
    Talk::class => ['tableName' => 'tx_myextension_domain_model_session', 'recordType' => 'talk'],
    Workshop::class => ['tableName' => 'tx_myextension_domain_model_session', 'recordType' => 'workshop'],
];
Code example. Session lists Talk and Workshop as subclasses. Each subclass names its recordType and the shared sessions table.

Queries across all types are simple and fast, because there are no JOINs. But many columns stay empty depending on the type. And a column cannot be NOT NULL for all types if only one type needs it.

Recurring tasks

Every night, a custom console command of my_extension imports conferences. The attribute AsCommand makes the command known, but does not schedule it. There are two ways to run it regularly:

  • In the Scheduler you create a task of the type “Execute console commands” with the command and an interval. A cron job on the server regularly starts scheduler run, and the Scheduler decides which tasks are due.
  • Or a cron job calls the Symfony command directly.
*/5 * * * * /var/www/html/vendor/bin/typo3 scheduler:run
Line for the crontab. Every five minutes the TYPO3 command scheduler run is called.

Code in ext_localconf.php or a plugin that runs on every page request is not suitable.

A few rules make such tasks reliable:

  • The import is idempotent: running it several times gives the same result. It matches records by an external ID, so a restart after a crash creates no duplicates.
  • A lock prevents two runs from overlapping.
  • Results and errors are logged and monitored. You do not suppress errors.
  • Large amounts of data are processed in batches, not in one huge task, so runtime and memory limits hold.

Testing software

Three kinds of tests complement each other:

  • Unit tests check a single class on its own, without a database. They run very fast.
  • Functional tests check how things work together with the database and the framework.
  • Acceptance tests check the application from the user's view in the browser, and are the slowest.
The test pyramid Acceptance few · browser Functional fewer · test database Unit many · one class, no database slower, more realistic
Many fast tests at the bottom, few slow ones at the top.

The TYPO3 Testing Framework comes from the Composer package typo3/testing-framework, as a development dependency, not shipped to customers. It builds on PHPUnit and does not replace it. Unit tests extend UnitTestCase, functional tests extend FunctionalTestCase. In the core, acceptance tests run with Codeception.

Testable code does not create its dependencies with new, or you cannot replace them. Through dependency injection, the test passes in a stub or a mock:

  • A stub only returns predefined values. You build it with the static method createStub().
  • A mock also checks how it is called. You build it with createMock() and expect, for example, that the mailer's send method runs exactly once. In PHPUnit 13 a mock without expectations triggers a notice, so use a stub then.
$repository = self::createStub(ConferenceRepository::class);
$repository->method('findUpcoming')->willReturn([$conference]);

$mailer = $this->createMock(MailerInterface::class);
$mailer->expects($this->once())->method('send');
Code example. A repository stub returns a fixed list. A mailer mock expects send to be called exactly once.

Several inputs come from a data provider. In PHPUnit 13 the test carries the attribute DataProvider with the name of a public static provider method. Since version 12, PHPUnit ignores DocBlock annotations. Each data set runs as a separate test, while a loop inside one test stops at the first failure.

Exceptions: call expectException() before the call that should throw. Afterwards is too late, because the exception ends the test. expectExceptionCode() also checks the code.

Functional tests set up their own TYPO3 instance with a fresh test database. Your own extensions go into the property testExtensionsToLoad, system extensions such as the Scheduler into coreExtensionsToLoad. importCSVDataSet() loads the initial data from a CSV file. assertCSVDataSet() compares the result with an expected CSV file.

protected array $testExtensionsToLoad = ['my-vendor/my-events'];

#[Test]
public function importCreatesRecords(): void
{
    $this->importCSVDataSet(__DIR__ . '/Fixtures/Import.csv');
    $this->get(ConferenceImporter::class)->run();
    $this->assertCSVDataSet(__DIR__ . '/Fixtures/ImportResult.csv');
}
Code example. The test loads the extension my-events, imports Import.csv, runs the import and compares the database with ImportResult.csv.

Small data structures in the core

BitSet stores several yes-or-no options in one single integer. Each bit stands for an option, for example a permission. Instead of calculating with bitwise operators by hand, you use set(), unset() and get(). These methods expect the value of the bit, so 1, 2 or 4, not its position. The method __toInt() returns the number.

$bits = new BitSet(0b011);  // 3
$bits->unset(0b001);        // 0b010 = 2
$bits->set(0b100);          // 0b110 = 6
The BitSet starts at 3. Unset with 1 leaves 2. Set with 4 gives 6.

For readable permissions, a class Permissions extends BitSet, names the bits with constants and offers a method such as isGranted() that calls get() internally. There is no separate interface for bit sets. Two drawbacks: the number of options is limited by the PHP integer size of 64 bits. And the stored number is hard to read without knowing what each bit means.

Map also accepts objects as keys. In a PHP WeakMap, an entry disappears once the key object is no longer referenced elsewhere. SplObjectStorage, for historic reasons, returns the key as the value in a foreach loop. The TYPO3 Map avoids both and returns key and value correctly.

TypeInterface only requires a class to have the method __toString(). That way the value can be used as a string. Extbase can convert request values into such types with a type converter.

Key points

  • Model holds data and logic, view presents, controller mediates and stays thin.
  • One repository per aggregate root, with meaningful names for custom queries.
  • Value objects are immutable, a change creates a new object.
  • Builders collect state, so use a fresh QueryBuilder and call reset() on the UriBuilder.
  • SOLID: one job per class, open for extension, replaceable subclasses, small interfaces, depend on abstractions.
  • Single table inheritance: a type field in the TCA, the mapping in the file Classes.php.
  • Recurring tasks run via Scheduler and cron job, idempotent and locked.
  • A stub returns values, a mock checks calls, and expectException() comes before the call.
  • BitSet works with bit values, not with positions.

Terms

Aggregate root
The only entry point to a group of objects that belong together.
Bounded context
An area in which a domain language has one clear meaning.
Decorator
A wrapper with the same interface that adds behavior.
Entity
An object with its own identity.
Idempotent
Running it several times gives the same result as once.
Mock
A test double that checks how it is called.
Stub
A test double that only returns predefined values.
Value object
An immutable object without identity, defined by its values.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • TYPO3 Explained 14.3, chapters Software design principles, Extbase, Services and Testing
  • TYPO3 14.3 source code (typo3/cms-core, typo3/cms-extbase), checked for BitSet, Map, TypeInterface, UriBuilder and Classes.php
  • PHPUnit 13 and typo3/testing-framework, checked for stubs, mocks and data providers
  • Learning objectives TYPO3 CMS Certified Developer 14 LTS, area software concepts

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications