---
title: "Migration Guide"
manual: "Netresearch SAML Auth"
version: "main"
source: "Migration/Index.rst"
rendered: "2026-10-01T05:49:07+00:00"
---

# Migration Guide {#migration}

This section provides guidance for upgrading between major versions.

## Upgrading from 10.x to 12.x {#upgrading-from-10-x-to-12-x}

Version 12.x includes breaking changes for TYPO3 12.4/13.4 compatibility.

### Requirements Changes {#requirements-changes}

-   **PHP 8.1+ required**: Upgrade your PHP version
-   **TYPO3 12.4+ required**: Upgrade your TYPO3 installation
-   **onelogin/php-saml 4.0**: Library upgraded with security improvements

### Breaking Changes {#breaking-changes}

#### PSR-14 Events {#psr-14-events}

Legacy hooks have been replaced with PSR-14 events. If you used the old
hook system, migrate to the new events:

```php
// OLD: Legacy hook (removed)
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['nr_saml_auth']['beforeUserCreation']

// NEW: PSR-14 event
Netresearch\NrSamlAuth\Event\BeforeUserCreationEvent
```

See [Events](../Developer/Events.html#events) for the complete event reference.

#### Dependency Injection {#dependency-injection}

Services now use TYPO3's DI container. Direct instantiation is deprecated:

```php
// OLD: Direct instantiation (deprecated)
$service = new \Netresearch\NrSamlAuth\Service\SamlService();

// NEW: Dependency injection
public function __construct(
    private readonly SamlService $samlService
) {}
```

#### Configuration {#configuration}

The SAML Settings record structure remains unchanged. No database migrations
are required.

### Migration Steps {#migration-steps}

1.  **Update PHP**: Ensure PHP 8.1 or higher is installed
1.  **Update TYPO3**: Upgrade to TYPO3 12.4 LTS or 13.4 LTS
1.  **Update Extension**: Run `composer update netresearch/nr-saml-auth`
1.  **Clear Caches**: Clear all TYPO3 caches
1.  **Test Authentication**: Verify SAML login still works
1.  **Update Custom Code**: Migrate any custom hooks to PSR-14 events

## Backward Compatibility {#backward-compatibility}

The extension maintains backward compatibility for:

-   SAML Settings record structure
-   Database schema
-   SAML response handling

The following are NOT backward compatible:

-   PHP 7.x support (requires 8.1+)
-   TYPO3 10.4/11.5 support (requires 12.4+)
-   Legacy hook system (use PSR-14 events)