--- title: "Breaking: Section-based AcademicPersons settings" manual: "Academic Profiles" version: "main" source: "Changelog/3.0/Breaking-SectionBasedAcademicPersonsSettings.rst" rendered: "2026-10-02T20:47:49+00:00" --- # Breaking: Section-based AcademicPersons settings {#breaking-section-based-academic-persons-settings} > [!NOTE] > **See also** > > [Upgrading from 2.4 to 3.0.0](../../Upgrade/Index.html#upgrade) is the order in which the 3.0 changes have to be applied. ## Description {#description} `Configuration/AcademicPersons/Settings.yaml` changes shape. The flat schema of two top-level maps - `profileInformationsTypes` listing the seven timeline entry types, and `validations` with one flag list per record type - could say which fields are required or locked, and nothing else. The editing frontend of [`fgtclb/academic-persons-edit`](https://packagist.org/packages/fgtclb/academic-persons-edit) needs the order of the fields, the control each one is rendered with, its help text, the rows and actions of a sortable list, and the character limit of a rich text field. All of that is now declared in one place, in four top-level maps: `profile`, `special`, `contracts` and `documentSections`. The [Profile sections](../../Configuration/Sections/Index.html#configuration-sections) page documents the shape, the [Validation settings](../../Configuration/Validations/Index.html#configuration-validations) page the flags. There is still **one file, one factory and one cache entry**. The public detail layout - `structure` and `details` \- lives in the same `profile` map as the editable fields, and since the files merge recursively an override changes one of the two without restating the other. The backend TCA **does** consume the graph: the validation set of each section is merged into the TCA of its table, and the profile information table, one table shared by the seven timeline types, gets a `types` fragment so a section's flags land in the `columnsOverrides` of its own record type. This happens after the TCA overrides, see [Breaking: Settings apply after the TCA overrides](Breaking-SettingsApplyAfterTcaOverrides.html#breaking-settings-apply-after-tca-overrides). The normalised graph is cached in the core cache under `AcademicPersons_Settings_v3`, the identifier the move of the validation primitives to `EXT:academic_base` introduced in the same release; it is not changed a second time. What an integrator sees: - `profileInformationsTypes` is gone. The seven relations of a profile to its timeline entries (`scientific_research`, `vita`, `memberships`, `cooperation`, `publications`, `lectures`, `press_media`) are part of the domain model and are declared by the TCA file of the profile table. They used to be generated from the map, so an override that dropped an entry silently lost a backend column; they now exist whatever the settings say. The same seven appear as `documentSections`, which carry their label, record type, relation field, row fields, actions and validators. **The record type and the relation field of a timeline type are no longer configurable.** They used to be one value each, generating the backend column and selecting the frontend records together; since the column is TCA, a changed `type` or `fieldName` would move the frontend half alone and every record created through it would be invisible in the backend. An override of either is therefore not applied, and the legacy mapping reports it per key instead of copying it, see [Feature: Legacy settings overlay and migration command](Feature-LegacySettingsOverlayAndMigrationCommand.html#feature-legacy-settings-overlay-and-migration-command). A timeline type of a project's own needs its own column in a TCA override of the profile table, and a `documentSections` entry that names it. - `validations` is gone. The flags of a field are declared on the field: `profile..validators` for the profile, `contracts.fields..validators` for the contract, `contracts.contactSections.
.fields..validators` for the address, email and phone records, and `documentSections.
.validators.` for the timeline entries. Every set keeps to its own section: a timeline section reaches the backend as `columnsOverrides` of its record type, never as a column configuration all seven types share. - The flag vocabulary grows by `url`, `tel`, `textarea` and `html`, and a rich text field can carry a `characterLimit`. `fieldType` and `renderType` describe the frontend control only; **the TCA column keeps the type its TCA file declares**. - The shipped flags change, and both editing contexts apply that. **Newly required**: the profile's `gender` \- the profile TCA column gets `required` and `minitems`, so the backend record editor refuses to save a profile without a gender, and the editing frontend runs its *not empty* validation - and the contract's `validFrom`. **Newly validated**: `website`, `publicationsLink` and the `link` of six of the seven timeline sections carry the `url` flag - `cooperation` offers no link field and therefore no flag on one. **Relaxed**: the `type` of an email address or phone number is no longer required, and the address's `streetNumber` and `zip` lose the `number` flag - their columns return from the `number` TCA type the flag set to the `input` their TCA file declares, so a street number like `12a` is stored as entered instead of being cast to `12`. Unchanged: the address's `country`, and the `title` and `year` of every timeline entry were required before. - The timeline entry validators address the year columns: `year` is the record's year, and the keys `from` and `to` alias its `yearStart` and `yearEnd` properties. - Every field of the shipped file carries a `helptext`, and the label file of **academic_persons** gains the 38 `helptext.*` units they reference - the help of the profile, contract, contact and timeline fields, rendered by the editing frontend. A project replaces the text either by pointing `helptext` at an `LLL:EXT:` key of its own - literal text works for the contract, contact and timeline fields only - or by overriding the shipped unit through `locallangXMLOverride` on TYPO3 v13, `resourceOverrides` on TYPO3 v14, or `plugin.tx_academicpersonsedit._LOCAL_LANG`. The internal PHP API changes with the file. `AcademicPersonsSettings` exposes the graph - `profileSections`, `specialFields`, `contractFields`, `contractContactSections`, `documentSections` and `publicProfile` \- built from the new value objects `ProfileSection`, `ProfileField`, `SpecialField`, `ContractField`, `ContractContactSection`, `ContractContactField`, `DocumentSection` and `PublicProfileSettings`, and answers validation questions per section. Removed without replacement: | Removed | Instead | | --- | --- | | `\FGTCLB\AcademicPersons\Settings\ProfileInformationType` | `DocumentSection`, resolved through `AcademicPersonsSettings::getDocumentSection()` or `getDocumentSectionByType()` | | `AcademicPersonsSettings::getProfileInformationType()` | `getDocumentSection()` | | `AcademicPersonsSettings::getValidationSet()`, `getValidationSetWithFallback()` | `getProfileValidationSet()`, `getProfileUpdateValidationSet()`, `getContractContactValidationSet()` and `getDocumentValidationSet()`, plus `getProfileValidationSetForFields()` and `getContractContactValidationSetForFields()` for a subset of a section's fields - every one of them returns an empty set for an unknown identifier, there is no separate fallback method | | `AcademicPersonsSettings::$profileInformationTypes`, `$validations` | the graph properties above | All of it is `@internal` and was consumed by `EXT:academic_persons_edit` only, which is adapted. ## Impact {#impact} **Every site package that overrides the file has to be migrated.** The old maps are not read as such any more. A file that still declares `validations` or `profileInformationsTypes` is mapped onto the section maps at runtime with a logged warning, until 4.0 - see the Feature entry on the legacy settings overlay and the migration command, and the [migration section](../../Configuration/Validations/Index.html#configuration-validations-migration) of the validation settings page. Without that mapping the installation would run on the shipped defaults: locked name fields, the required contact fields, and the seven shipped timeline sections. An eighth timeline entry type that an override declared under `profileInformationsTypes` used to get a backend inline column for free. It no longer does: the profile relations are fixed. Such a type can be kept by declaring the column in a TCA override of the profile table and its section under `documentSections` \- the TCA file's loop over the seven relations is the template for the column. The Extbase model of this extension never had a property for an additional type, so it was reachable in the backend only. Code that reads the removed methods or the removed class fails with an undefined method or a class not found error. **Existing profiles without a gender can no longer be saved in the backend** until a gender is chosen, and a frontend profile form that does not post one is rejected. An installation that does not want the gender required removes the flag in its override. Street numbers and zip codes accept non-numeric values again; values already cast to integers stay as they are. ## Affected Installations {#affected-installations} Every installation with a site package shipping `Configuration/AcademicPersons/Settings.yaml`, and every installation whose project code reads `AcademicPersonsSettings` directly. ## Migration {#migration} 1. Copy the shipped `EXT:academic_persons/Configuration/AcademicPersons/Settings.yaml` over the override in the site package, and re-apply the project's changes to it: a locked or unlocked profile field is its `validators` list under `profile`, a required contact field its list under `contracts.contactSections`, a required timeline field its entry under the `validators` map of every section it applies to. 1. Mind the merge while you do it. The files are merged recursively, so a map names only the keys it changes - and a key it leaves out is inherited rather than removed, whatever level it sits on. An entry the project does not want is set to `~`, a flag list that is to be empty to `[]`. This is a change of its own in the same release, with the complete rules and the migration: [Breaking: Settings files merge recursively](Breaking-SettingsFilesMergeRecursively.html#breaking-settings-files-merge-recursively). 1. Decide on the changed defaults: drop `required` from `profile.gender.validators` if profiles without a gender are to stay saveable, restore `number` on `streetNumber` and `zip` if numeric values are to be enforced, and add `required` back to the two `
Type` fields if a contact type is mandatory. 1. Re-declare a renamed timeline relation in TCA. An override that changed `profileInformationsTypes..type` or `...fieldName` no longer reaches the profile table, and the value it named is reported by `vendor/bin/typo3 academic:persons:settings:migrate` rather than applied. Either accept the shipped record type and relation, or declare the column in a TCA override of `tx_academicpersons_domain_model_profile` and give it a `documentSections` entry. 1. Flush all TYPO3 caches.