# Multi-Factor Authentication (MFA)

## `onMfaGetMethod`

Reports the availability of an MFA method

```php
function onMfaGetMethod(): \Akeeba\Panopticon\Library\MultiFactorAuth\DataShape\MethodDescriptor
```

## `onMfaBeforeDisplayMethods`

Executes before displaying the available MFA methods for a user who has logged-in but not cleared the MFA captive page yet.

```php
function onMfaBeforeDisplayMethods(
    \Awf\User\UserInterface $user
): void
```

* `$user` The user object of the logged-in user.

## `onMfaCaptive`

Returns the information necessary to render the MFA captive page.

If the `$record` does not match the handler's MFA method, the method should return NULL.

```php
function onMfaCaptive(
    \Akeeba\Panopticon\Model\Mfa $record
): ?\Akeeba\Panopticon\Library\MultiFactorAuth\DataShape\CaptiveRenderOptions
```

* `$record` The MFA record the user has selected to authenticate with.

## `onMfaValidate`

Validates the user's MFA authentication attempt.

If the `$record` does not match the handler's MFA method, the method should return NULL.

Return boolean TRUE to indicate that the authentication is successful, boolean FALSE to indicate that the authentication failed, or there was an error.

Methods should NOT throw exceptions if they are not handling the current MFA authentication attempt. Doing so would prevent the correct handler from executing.

```php
function onMfaValidate(
    \Akeeba\Panopticon\Model\Mfa $record,
    \Awf\User\UserInterface $user, 
    ?string $code
): ?bool
```

* `$record` The MFA record the user has selected to authenticate with.
* `$code` The user-provided authentication information which needs to be validated.

## `onMfaGetSetup`

Returns the information necessary to render the MFA setup page.

```php
function onMfaGetSetup(
    \Akeeba\Panopticon\Model\Mfa $record
): \Akeeba\Panopticon\Library\MultiFactorAuth\DataShape\SetupRenderOptions
```

* `$record` The MFA record being edited


## `onMfaSaveSetup`

Returns the information to save to the user's MFA configuration upon successful configuration of an MFA method.

```php
function onMfaSaveSetup(
    \Akeeba\Panopticon\Model\Mfa $record,
    \Awf\Input\Input $input
): array
```

* `$record` The MFA record being edited
* `$input` The application input object.

You must return the array of information which will be saved in the database.

# Editors

## ACE editor (plain text)

### `onACEEditorConfig`

```php
function onACEEditorConfig(
    string $name, 
    string $id, 
    array &$options
): void
```

## TinyMCE editor (HTML)

### `onTinyMCEConfig`

```php
function onTinyMCEConfig(
    string $name, 
    string $id, 
    array &$options
): void
```

# User Avatars

## `onUserAvatar`

```php
function onUserAvatar(
    ?int $id,
    ?string $email,
    ?\Awf\Registry\Registry $params
): ?string
```

## `onUserAvatarEditURL`

```php
function onUserAvatarEditURL(
    ?int $id,
    ?string $email,
    ?\Awf\Registry\Registry $params
): ?string
```

# Models

## `onBeforeBuildQuery`

```php
function onBeforeBuildQuery(
    \Awf\Mvc\DataModel $model,
    \Awf\Database\Query $query
): void
```

## `onAfterBuildQuery`

```php
function onBeforeBuildQuery(
    \Awf\Mvc\DataModel $model,
    \Awf\Database\Query $query
): void
```

# Joomla! Update

## `onTaskBeforeJoomlaUpdate`

```php
function onTaskBeforeJoomlaUpdate(
    object $task,
    \Awf\Registry\Registry $storage
): int
```

Integers expected are the values of the `\Akeeba\Panopticon\Library\Task\Status` enumeration.

# Uptime Monitoring

## `onGetUptimeProvider`

Called by the System Configuration page to display the list of uptime monitoring providers.

```php
function onGetUptimeProvider(): array
```

Your plugin must return the following array:

```php
[
    'myName' => 'SOME_TRANSLATION_STRING'
]
```

where

* `myName` is a name unique to your plugin. Recommended to use `$this->getName()` to return your plugin's name. Do not use `panopticon` or `none`, they are respectively reserved for the core uptime monitoring feature, and disabling uptime monitoring.
* `SOME_TRANSLATION_STRING` is a translation string key with the name of the service or software you are integrating with.

## `onSiteIsBackUp`

The uptime monitoring has detected that a site which was previously down has just come back up.

Custom uptime service integrations MUST call this event when they detect a site is back up. This event MUST NOT be called if the site was already up.

```php
function onSiteIsBackUp(
    \Akeeba\Panopticon\Model\Site $site,
    ?int $downSince
): void
```

* `$site` The site object in question.
* `$downSince` The timestamp on which the site was first detected as being down.

## `onSiteHasGoneDown`

The uptime monitoring has detected that a site which was previously up has just gone down.

Custom uptime service integrations MUST call this event when they detect a site has just gone down. This event MUST NOT be called if the site was already down.

```php
function onSiteHasGoneDown(
    \Akeeba\Panopticon\Model\Site $site
): void
```

* `$site` The site object in question.

## `onSiteGetUptimeStatus`

Returns the uptime status of a site.

Custom uptime service integrations MUST provide an implementation of this event handler. It is used to convey the uptime status in the interface.

```php
function onSiteGetUptimeStatus(
    \Akeeba\Panopticon\Model\Site $site
): ?\Akeeba\Panopticon\Library\Uptime\UptimeStatus
```

* `$site` The site object in question.

ℹ️ The URL is rendered in the interface as a link surrounding the status. Custom uptime service integrations SHOULD populate the `detailsUrl` field of the returned object with a URL to the third party service providing the uptime monitoring, if the currently logged-in user is reasonably expected to have access to that page.