Upgrading to 4.0 from 3.x

4.0.0 replaces every optional parameter on the send*/handle* methods — relayState, sessionIndex, nameIdPolicyFormat, nameId, validate/issuer, and the attribute array — with a single variadic ContextList parameter. It also adds first-class NameID Format support, which changes nameId from a plain string to a value object. Both changes are breaking; this guide covers everything you need to update.

Why

Each send*/handle* method had accumulated its own positional/named optional parameter per protocol detail, with bool $validate / ?Entity $issuer duplicated across all eight call sites. That made signatures hard to extend — adding NameID Format support would have meant a ninth parameter on some methods and not others.

4.0.0 replaces all of it with one typed, variadic collection: ContextList, made of Context value objects (RelayState, SessionIndex, NameIdPolicyFormat, NameId, Attribute, Validate). Every method now takes the same shape — ContextList $context = new ContextList() — and you pass only the pieces relevant to that call.

What changed

Area	3.x	4.0
Optional parameters	Named parameters (relayState:, sessionIndex:, validate:, issuer:, ...)	Context objects passed to a single ContextList $context parameter
Signature validation	validate: true, issuer: $idp	new Validate($idp) in the context list
nameId on AuthnResponse / LogoutRequest	?string	?Litesaml\Models\Messages\Context\NameId (value + format)
sendLogoutRequest()'s NameID	Positional string $nameId argument	new NameId($value) in the context list — required, throws SamlException at call time if absent
sendAuthnResponse()'s attributes	array $attributes positional argument	new Attribute(...) entries in the context list
Attribute namespace	Litesaml\Models\Messages\Attribute	Litesaml\Models\Messages\Context\Attribute
NameID Format	Not supported	NameIdPolicyFormat context (SP request), Idp/Sp nameIdFormats (metadata), IdP can set the response NameId

1. Replace named parameters with a ContextList

Every Context class implements Litesaml\Models\Messages\Context\Context. Pass as many as you need to the $context parameter — order doesn't matter.

RelayState

Before

$response = $spWrapper->sendAuthnRequest($idp, relayState: '/dashboard');

After

use Litesaml\Models\Messages\Context\ContextList;
use Litesaml\Models\Messages\Context\RelayState;

$response = $spWrapper->sendAuthnRequest($idp, new ContextList(
    new RelayState('/dashboard'),
));

Signature validation (validate/issuer → Validate)

Before

$authnResponse = $spWrapper->handleAuthnResponse($request, validate: true, issuer: $idp);

After

use Litesaml\Models\Messages\Context\ContextList;
use Litesaml\Models\Messages\Context\Validate;

$authnResponse = $spWrapper->handleAuthnResponse($request, new ContextList(
    new Validate($idp),
));

Validate merges the old validate/issuer pair into one object — since $issuer is now a required constructor argument, there's no way to ask for "validate without an issuer" anymore.

Combining multiple contexts

Before

$response = $spWrapper->sendLogoutRequest(
    recipient: $idp,
    nameId: $nameId,
    relayState: '/logged-out',
    sessionIndex: $sessionIndex,
);

After

use Litesaml\Models\Messages\Context\ContextList;
use Litesaml\Models\Messages\Context\NameId;
use Litesaml\Models\Messages\Context\RelayState;
use Litesaml\Models\Messages\Context\SessionIndex;

$response = $spWrapper->sendLogoutRequest($idp, new ContextList(
    new NameId($nameIdValue),
    new RelayState('/logged-out'),
    new SessionIndex($sessionIndex),
));

sendLogoutRequest() no longer takes $nameId as a positional argument. A NameId context is now required — omitting it throws a SamlException at call time ('A NameId is required to send a LogoutRequest') instead of being enforced by the method signature.

sendAuthnResponse()'s attribute array

Before

use Litesaml\Models\Messages\Attribute;

$response = $idpWrapper->sendAuthnResponse($sp, [
    new Attribute('email', ['user@example.com']),
    new Attribute('displayName', ['Jane Doe']),
]);

After

use Litesaml\Models\Messages\Context\Attribute;
use Litesaml\Models\Messages\Context\ContextList;

$response = $idpWrapper->sendAuthnResponse($sp, new ContextList(
    new Attribute('email', ['user@example.com']),
    new Attribute('displayName', ['Jane Doe']),
));

Note the Attribute import path change — see 3. Namespace changes below.

2. nameId is now a value object

AuthnResponse::$nameId and LogoutRequest::$nameId are no longer ?string. They're ?Litesaml\Models\Messages\Context\NameId, carrying both the identifier value and its format.

Before

$nameId = $authnResponse->nameId; // string|null

After

$nameId       = $authnResponse->nameId?->value;  // string|null
$nameIdFormat = $authnResponse->nameId?->format; // string|null

If you were forwarding $authnResponse->nameId straight into sendLogoutRequest()'s old positional $nameId argument, pass the NameId object itself instead — no need to unwrap it:

Before

$response = $spWrapper->sendLogoutRequest($idp, $authnResponse->nameId);

After

use Litesaml\Models\Messages\Context\ContextList;

$response = $spWrapper->sendLogoutRequest($idp, new ContextList(
    $authnResponse->nameId,
));

3. Namespace changes

Two classes moved into the new Litesaml\Models\Messages\Context namespace, since they now also implement the Context marker interface:

Class	3.x namespace	4.0 namespace
Attribute	Litesaml\Models\Messages\Attribute	Litesaml\Models\Messages\Context\Attribute
NameId	(did not exist)	Litesaml\Models\Messages\Context\NameId

Update any use Litesaml\Models\Messages\Attribute; import to use Litesaml\Models\Messages\Context\Attribute;.

4. New: NameID Format support

These are additive — nothing to change unless you want to use them.

• SP requests a format: pass a NameIdPolicyFormat context to sendAuthnRequest() to set the request's NameIDPolicy. The IdP receives it via AuthnRequest::$nameIdPolicyFormat in handleAuthnRequest().
• IdP sets the response NameID: pass a NameId context to sendAuthnResponse() so the assertion's Subject/NameID is populated — previously the subject had no identifier at all.
• Metadata: Idp and Sp now accept a nameIdFormats array (string[]), rendered as <NameIDFormat> elements in generateMetadata() and read back by MetadataParser::parse().

See Authentication request and Generate metadata for details.