Study guide · Software Architecture and Design Patterns
Well-built code: architecture, patterns and tests in TYPO3
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
Conferencewith 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]);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,
) {}
}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
layoutRootPathsandpartialRootPaths. - The model
Conferencecomes with the repositoryConferenceRepositoryin 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_conferenceThe 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();
}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.
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'],
];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:runCode 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 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');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');
}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 = 6For 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.