Migration Guide 

This section provides guidance for upgrading between major versions.

Upgrading from 10.x to 12.x 

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

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 

PSR-14 Events 

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

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

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

See Events for the complete event reference.

Dependency Injection 

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

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

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

Configuration 

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

Migration Steps 

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

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)