Exceptions

SPL Exceptions

The Standard PHP Library (SPL) provides some exceptions that should be used whenever possible.

Custom Exceptions

Do not use wcf\system\exception\SystemException anymore, use specific exception classes!

The following table contains a list of custom exceptions that are commonly used. All of the exceptions are found in the wcf\system\exception namespace.

Class name	(examples) when to use
IllegalLinkException	access to a page that belongs to a non-existing object, executing actions on specific non-existing objects (is shown as http 404 error to the user)
ImplementationException	a class does not implement an expected interface
InvalidObjectArgument	5.4+ API method support generic objects but specific implementation requires objects of specific (sub)class and different object is given
InvalidObjectTypeException	object type is not of an expected object type definition
InvalidSecurityTokenException	given security token does not match the security token of the active user's session
ParentClassException	a class does not extend an expected (parent) class
PermissionDeniedException	page access without permission, action execution without permission (is shown as http 403 error to the user)
UserInputException	user input does not pass validation

Sensitive Arguments in Stack Traces

Sometimes sensitive values are passed as a function or method argument. If the callee throws an Exception, these values will be part of the Exception’s stack trace and logged, unless the Exception is caught and ignored.

WoltLab Suite will automatically suppress the values of parameters named like they might contain sensitive values, namely arguments matching the regular expression /(?:^(?:password|passphrase|secret)|(?:Password|Passphrase|Secret))/.

If you need to suppress additional arguments from appearing in the stack trace, you can add the \wcf\SensitiveArgument attribute to such parameters. Arguments are only supported as of PHP 8 and ignored as comments in lower PHP versions. In PHP 7, such arguments will not be suppressed, but the code will continue to work. Make sure to insert a linebreak between the attribute and the parameter name.

Example:

<?php

namespace wcf\data\user;

// …

final class User extends DatabaseObject implements IPopoverObject, IRouteController, IUserContent
{
    // …

    public function checkPassword(
        #[\wcf\SensitiveArgument()]
        $password
    ) {
        // …
    }

    // …
}

---

Last update: 2021-12-16