{

public const DEFAULT_BCRYPT_COST = 10;

public const DEFAULT_OPTION = self::OPTION_ACL_COMMENT_CREATE;

public const DEFAULT_TZ = null; // null means no timezone preference/automatic.

// Maximum SQL field lengths, alter as appropriate

public const MAX_DISPLAY_NAME = 0xFF;

public const MAX_EMAIL = 0xFF;

public const MAX_ID = 0x7FFFFFFFFFFFFFFF;

public const MAX_OPTIONS = 0x7FFFFFFFFFFFFFFF;

public const MAX_PASSWORD_HASH = 0xFF;

public const MAX_PASSWORD_SALT = 0xFF;

public const MAX_TIMEZONE = 0xFF;

public const MAX_USERNAME = 0xFF;

public const MAX_VERIFIER_TOKEN = 0xFF;

public const OPTION_DISABLED = 0x00000001; // User login disabled, active sessions force-expired

public const OPTION_VERIFIED = 0x00000002; // A token sent via email was returned to us

public const OPTION_ACL_DOCUMENT_CREATE = 0x00000004;

public const OPTION_ACL_DOCUMENT_MODIFY = 0x00000008;

public const OPTION_ACL_DOCUMENT_DELETE = 0x00000010;

public const OPTION_ACL_COMMENT_CREATE = 0x00000020;

public const OPTION_ACL_COMMENT_MODIFY = 0x00000040;

public const OPTION_ACL_COMMENT_DELETE = 0x00000080;

public const OPTION_ACL_EVENT_LOG_VIEW = 0x00000100;

public const OPTION_ACL_EVENT_LOG_MODIFY = 0x00000200;

public const OPTION_ACL_EVENT_LOG_DELETE = 0x00000400;

public const OPTION_ACL_NEWS_CREATE = 0x00000800;

public const OPTION_ACL_NEWS_MODIFY = 0x00001000;

public const OPTION_ACL_NEWS_DELETE = 0x00002000;

public const OPTION_ACL_PACKET_CREATE = 0x00004000;

public const OPTION_ACL_PACKET_MODIFY = 0x00008000;

public const OPTION_ACL_PACKET_DELETE = 0x00010000;

public const OPTION_ACL_SERVER_CREATE = 0x00020000;

public const OPTION_ACL_SERVER_MODIFY = 0x00040000;

public const OPTION_ACL_SERVER_DELETE = 0x00080000;

public const OPTION_ACL_USER_CREATE = 0x00100000;

public const OPTION_ACL_USER_MODIFY = 0x00200000;

public const OPTION_ACL_USER_DELETE = 0x00400000;

public const OPTION_ACL_PHPINFO = 0x00800000;

public const OPTION_ACL_ANALYTICS_VIEW = 0x01000000;

public const OPTION_STAFF = self::DEFAULT_OPTION

| self::OPTION_ACL_COMMENT_DELETE

| self::OPTION_ACL_COMMENT_MODIFY

| self::OPTION_ACL_DOCUMENT_CREATE

| self::OPTION_ACL_DOCUMENT_DELETE

| self::OPTION_ACL_DOCUMENT_MODIFY

| self::OPTION_ACL_EVENT_LOG_DELETE

| self::OPTION_ACL_EVENT_LOG_MODIFY

| self::OPTION_ACL_EVENT_LOG_VIEW

| self::OPTION_ACL_NEWS_CREATE

| self::OPTION_ACL_NEWS_DELETE

| self::OPTION_ACL_NEWS_MODIFY

| self::OPTION_ACL_PACKET_CREATE

| self::OPTION_ACL_PACKET_DELETE

| self::OPTION_ACL_PACKET_MODIFY

| self::OPTION_ACL_PHPINFO

| self::OPTION_ACL_SERVER_CREATE

| self::OPTION_ACL_SERVER_DELETE

| self::OPTION_ACL_SERVER_MODIFY

| self::OPTION_ACL_USER_CREATE

| self::OPTION_ACL_USER_DELETE

| self::OPTION_ACL_USER_MODIFY;

protected DateTimeInterface $created_datetime;

protected ?string $display_name;

protected string $email;

protected ?int $id;

protected int $options;

protected ?string $password_hash;

protected ?string $password_salt;

protected DateTimeInterface $record_updated;

protected ?string $timezone;

protected string $username;

protected ?DateTimeInterface $verified_datetime;

protected ?string $verifier_token;

/**

public function __construct(StdClass|int|null $value)

{

if ($value instanceof StdClass)

{

$this->allocateObject($value);

}

else

{

$this->setId($value);

if (!$this->allocate()) throw new \BNETDocs\Exceptions\UserNotFoundException($this);

}

}

/**

public function allocate(): bool

{

// Set initial property values, but skip the id property.

$this->setCreatedDateTime(new DateTimeImmutable('now'));

$this->setDisplayName(null);

$this->setEmail('', true);

$this->setOptions(self::DEFAULT_OPTION);

$this->setPasswordHash(null);

$this->setPasswordSalt(null);

$this->setRecordUpdated(new DateTimeImmutable('now'));

$this->setTimezone(self::DEFAULT_TZ);

$this->setUsername('', true);

$this->setVerifiedDateTime(null);

$this->setVerifierToken(null);

// Get database record only if the id property is not null.

$id = $this->getId();

if (is_null($id)) return true;

$q = MariaDb::instance()->prepare('

');

if (!$q || !$q->execute([':id' => $id]) || $q->rowCount() != 1) return false;

$this->allocateObject($q->fetchObject());

$q->closeCursor();

return true;

}

/**

protected function allocateObject(StdClass $value): void

{

$this->setCreatedDateTime($value->created_datetime);

$this->setDisplayName($value->display_name);

$this->setEmail($value->email);

$this->setId($value->id);

$this->setOptions($value->options_bitmask);

$this->setPasswordHash($value->password_hash);

$this->setPasswordSalt($value->password_salt);

$this->setRecordUpdated($value->record_updated);

$this->setTimezone($value->timezone);

$this->setUsername($value->username);

$this->setVerifiedDateTime($value->verified_datetime);

$this->setVerifierToken($value->verifier_token);

}

/**

public function commit(): bool

{

$q = MariaDb::instance()->prepare('

');

$this->setRecordUpdated(new DateTimeImmutable('now', new DateTimeZone(self::DATE_TZ)));

$p = [

':cdt' => $this->getCreatedDateTime(),

':dn' => $this->getDisplayName(),

':e' => $this->getEmail(),

':id' => $this->getId(),

':o' => $this->getOptions(),

':pwh' => $this->getPasswordHash(),

':pws' => $this->getPasswordSalt(),

':rudt' => $this->getRecordUpdated(),

':tz' => $this->getTimezone(),

':u' => $this->getUsername(),

':vdt' => $this->getVerifiedDateTime(),

':vt' => $this->getVerifierToken(),

];

foreach ($p as $k => $v)

{

if ($v instanceof DateTimeInterface)

{

$p[$k] = $v->format(self::DATE_SQL);

}

}

if (!$q || !$q->execute($p)) return false;

if (is_null($p[':id'])) $this->setId(MariaDb::instance()->lastInsertId());

$q->closeCursor();

return true;

}

/**

public function checkPassword(string $password): bool // This function was refactored by OpenAI

{

if (is_null($this->password_hash))

{

return false;

}

else if (substr($this->password_hash, 0, 1) == '$')

{

// new style bcrypt password

$cost = Config::get('bnetdocs.user_password_bcrypt_cost') ?? self::DEFAULT_BCRYPT_COST;

$match = password_verify($password, $this->password_hash);

$rehash = password_needs_rehash(

$this->password_hash, PASSWORD_BCRYPT, array('cost' => $cost)

);

return $match && !$rehash;

}

else

{

// old style peppered and salted sha256 password

$salt = $this->password_salt;

if (is_null($salt)) return false;

$pepper = Config::get('bnetdocs.user_password_pepper') ?? '';

$hash = strtoupper(hash('sha256', $password.$salt.$pepper));

return strtoupper($this->password_hash) === $hash;

}

}

/**

public static function createPassword(string $password): string

{

$cost = Config::get('bnetdocs.user_password_bcrypt_cost') ?? self::DEFAULT_BCRYPT_COST;

return password_hash($password, PASSWORD_BCRYPT, array('cost' => $cost));

}

/**

public function deallocate(): bool

{

$id = $this->getId();

if (is_null($id)) return false;

$q = MariaDb::instance()->prepare('DELETE FROM `users` WHERE `id` = ? LIMIT 1;');

try { return $q && $q->execute([$id]); }

finally { $q->closeCursor(); }

}

/**

public static function findIdByEmail(string $value): ?int

{

if (!filter_var($value, FILTER_VALIDATE_EMAIL))

throw new UnexpectedValueException('email is not formatted as a valid email address');

$q = MariaDb::instance()->prepare('SELECT `id` FROM `users` WHERE `email` = ? LIMIT 1;');

if (!$q || !$q->execute([$value]) || $q->rowCount() == 0) return null;

$r = $q->fetchObject();

$q->closeCursor();

return (int) $r->id;

}

/**

public static function findIdByUsername(string $value): ?int

{

$q = MariaDb::instance()->prepare('SELECT `id` FROM `users` WHERE `username` = ? LIMIT 1;');

if (!$q || !$q->execute([$value]) || $q->rowCount() == 0) return null;

$r = $q->fetchObject();

$q->closeCursor();

return (int) $r->id;

}

/**

public static function generateVerifierToken(string $username, string $email): string

{

return hash('sha256', sprintf('%s%s%s', mt_rand(), $username, $email));

}

/**

public static function &getAllUsers(?array $order = null, ?int $limit = null, ?int $index = null): ?array

{

if (!is_null($limit) && !is_null($index))

{

$limit_clause = sprintf('LIMIT %d,%d', $index, $limit);

}

else if (!is_null($limit))

{

$limit_clause = sprintf('LIMIT %d', $limit);

}

else

{

$limit_clause = '';

}

$q = MariaDb::instance()->prepare(sprintf('

', (

$order ? (sprintf('`%s` %s, `id` %s', $order[0], $order[1], $order[1])) : '`id` ASC'

), $limit_clause));

if (!$q || !$q->execute()) return null;

$r = [];

while ($row = $q->fetchObject()) $r[] = new self($row);

$q->closeCursor();

return $r;

}

public function getAsDiscordEmbedAuthor(): DiscordEmbedAuthor

{

return new DiscordEmbedAuthor($this->getName(), $this->getURI(), $this->getAvatarURI(null));

}

public function getAsMarkdown(): string

{

return \sprintf('[%s](%s)', $this->getName(), $this->getURI());

}

/**

public function getAvatarURI(?int $size): string

{

return UrlFormatter::format(

(new \BNETDocs\Libraries\User\Gravatar($this->getEmail()))->getUrl($size, 'identicon')

);

}

/**

public function getCreatedDateTime(): ?DateTimeInterface

{

return $this->created_datetime;

}

/**

public function getCreatedEstimate(): string

{

$c = $this->getCreatedDateTime();

$now = new DateTimeImmutable('now');

$d = $c->diff($now);

$i = 0;

$r = '';

$t = 3;

if ($d->y > 0 && $i < $t) { ++$i; $r .= sprintf('%s%d %s%s', ($r ? ', ' : ''), $d->y, 'year', ($d->y !== 1 ? 's' : '')); }

if ($d->m > 0 && $i < $t) { ++$i; $r .= sprintf('%s%d %s%s', ($r ? ', ' : ''), $d->m, 'month', ($d->m !== 1 ? 's' : '')); }

if ($d->d > 0 && $i < $t) { ++$i; $r .= sprintf('%s%d %s%s', ($r ? ', ' : ''), $d->d, 'day', ($d->d !== 1 ? 's' : '')); }

if ($d->h > 0 && $i < $t) { ++$i; $r .= sprintf('%s%d %s%s', ($r ? ', ' : ''), $d->h, 'hour', ($d->h !== 1 ? 's' : '')); }

if ($d->i > 0 && $i < $t) { ++$i; $r .= sprintf('%s%d %s%s', ($r ? ', ' : ''), $d->i, 'minute', ($d->i !== 1 ? 's' : '')); }

if ($i === 0) $r = 'created a moment ago';

if ($c > $now) $r = '-' . $r;

return $r;

}

/**

public function getDisplayName(): ?string

{

return $this->display_name;

}

/**

public function getEmail(): string

{

return $this->email;

}

/**

public function getId(): ?int

{

return $this->id;

}

/**

public function getName(): string

{

return $this->display_name ?? $this->username;

}

/**

public function getOption(int $option): bool

{

if ($option < 0 || $option > self::MAX_OPTIONS)

{

throw new OutOfBoundsException(sprintf(

'value must be between 0-%d', self::MAX_OPTIONS

));

}

return ($this->options & $option) === $option;

}

/**

public function getOptions(): int

{

return $this->options;

}

/**

public function getPasswordHash(): ?string

{

return $this->password_hash;

}

/**

public function getPasswordSalt(): ?string

{

return $this->password_salt;

}

/**

public function getRecordUpdated(): DateTimeInterface

{

return $this->record_updated;

}

/**

public function getTags(): array

{

$id = $this->getId();

return is_null($id) ? [] : (Tag::allocateAll(TagTypes::User, $this->getId()) ?? []);

}

/**

public function getTimezone(): ?string

{

return $this->timezone;

}

/**

public function getURI(): ?string

{

$id = $this->getId();

if (is_null($id)) return null;

return UrlFormatter::format(sprintf(

'/user/%s/%s', $id, StringProcessor::sanitizeForUrl($this->getName(), true)

));

}

/**

public static function getUserCount(): int|false

{

$q = MariaDb::instance()->prepare('SELECT COUNT(*) AS `count` FROM `users`;');

if (!$q || !$q->execute() || $q->rowCount() != 1) return false;

$r = (int) $q->fetchObject()->count;

$q->closeCursor();

return $r;

}

/**

public function getUsername(): string

{

return $this->username;

}

/**

public function getUserProfile(): ?UserProfile

{

try

{

return is_null($this->id) ? null : new UserProfile($this->id);

}

catch (\BNETDocs\Exceptions\UserProfileNotFoundException)

{

return null;

}

}

/**

public function getVerifiedDateTime(): ?DateTimeInterface

{

return $this->verified_datetime;

}

/**

public function getVerifierToken(): ?string

{

return $this->verifier_token;

}

/**

public function isDisabled(): bool

{

return $this->getOption(self::OPTION_DISABLED);

}

/**

public function isStaff(): bool

{

return $this->getOption(self::OPTION_STAFF);

}

/**

public function isVerified(): bool

{

return $this->getOption(self::OPTION_VERIFIED);

}

/**

public function jsonSerialize(): mixed

{

return [

'avatar_url' => $this->getAvatarURI(null),

'id' => $this->getId(),

'member_for' => $this->getCreatedEstimate(),

'name' => $this->getName(),

'timezone' => $this->getTimezone(),

'url' => $this->getURI(),

];

}

/**

public function setCreatedDateTime(DateTimeInterface|string $value): void

{

$this->created_datetime = (is_string($value) ?

new DateTimeImmutable($value, new DateTimeZone(self::DATE_TZ)) : $value

);

}

/**

public function setDisplayName(?string $value): void

{

if (!is_null($value) && (empty($value) || strlen($value) > self::MAX_DISPLAY_NAME))

{

throw new OutOfBoundsException(sprintf(

'value must be null or between 1-%d characters', self::MAX_DISPLAY_NAME

));

}

$this->display_name = $value;

}

/**

public function setEmail(string $value, bool $ignore_empty = false): void

{

if ((!$ignore_empty && empty($value)) || strlen($value) > self::MAX_EMAIL)

{

throw new OutOfBoundsException(sprintf(

'value must be between 1-%d characters', self::MAX_EMAIL

));

}

if (!empty($value) && !filter_var($value, FILTER_VALIDATE_EMAIL))

{

throw new UnexpectedValueException('value is not formatted as a valid email address');

}

$this->email = $value;

}

/**

public function setId(?int $value): void

{

if (!is_null($value) && ($value < 0 || $value > self::MAX_ID))

{

throw new OutOfBoundsException(sprintf(

'value must be null or an integer between 0-%d', self::MAX_ID

));

}

$this->id = $value;

}

/**

public function setOption(int $option, bool $value): void

{

if ($option < 0 || $option > self::MAX_OPTIONS)

{

throw new OutOfBoundsException(sprintf(

'value must be between 0-%d', self::MAX_OPTIONS

));

}

if ($value) $this->options |= $option; // bitwise or

else $this->options &= ~$option; // bitwise and ones complement

}

/**

public function setOptions(int $value): void

{

if ($value < 0 || $value > self::MAX_OPTIONS)

{

throw new OutOfBoundsException(sprintf(

'value must be an integer between 0-%d', self::MAX_OPTIONS

));

}

$this->options = $value;

}

/**

public function setPassword(string $value): void

{

$this->setPasswordHash(self::createPassword($value));

$this->setPasswordSalt(null); // Deprecated

}

/**

public function setPasswordHash(?string $value): void

{

if (!is_null($value) && (empty($value) || strlen($value) > self::MAX_PASSWORD_HASH))

{

throw new OutOfBoundsException(sprintf(

'value must be null or between 1-%d characters', self::MAX_PASSWORD_HASH

));

}

$this->password_hash = $value;

}

/**

public function setPasswordSalt(?string $value): void

{

if (!is_null($value) && (empty($value) || strlen($value) > self::MAX_PASSWORD_SALT))

{

throw new OutOfBoundsException(sprintf(

'value must be null or between 1-%d characters', self::MAX_PASSWORD_SALT

));

}

$this->password_salt = $value;

}

/**

public function setRecordUpdated(DateTimeInterface|string $value): void

{

$this->record_updated = (is_string($value) ?

new DateTimeImmutable($value, new DateTimeZone(self::DATE_TZ)) : $value

);

}

/**

public function setTimezone(?string $value): void

{

if (!is_null($value) && (empty($value) || strlen($value) > self::MAX_TIMEZONE))

{

throw new OutOfBoundsException(sprintf(

'value must be null or between 1-%d characters', self::MAX_TIMEZONE

));

}

// Create anonymous DateTimeZone object with $value to test for unknown or bad timezone.

// PHP throws Exception(sprintf("Unknown or bad timezone (%s)", $value)) if so.

// This Exception is wrapped into a new UnexpectedValueException.

try

{

if (!is_null($value) && !empty($value)) new DateTimeZone($value);

}

catch (\Exception $e)

{

throw new UnexpectedValueException('value must be a valid timezone', 0, $e);

}

$this->timezone = $value;

}

/**

public function setUsername(string $value, bool $ignore_empty = false): void

{

if ((!$ignore_empty && empty($value)) || strlen($value) > self::MAX_USERNAME)

{

throw new OutOfBoundsException(sprintf(

'value must be a string between 1-%d characters', self::MAX_USERNAME

));

}

$this->username = $value;

}

/**

public function setVerified(bool $value, bool $reset = false): void

{

$old_value = $this->getOption(self::OPTION_VERIFIED);

if (!$reset && $old_value === $value) return; // avoid resetting values every call

$this->setOption(self::OPTION_VERIFIED, $value);

if ($value)

{

// verified

$this->setVerifiedDateTime(new DateTimeImmutable('now'));

$this->setVerifierToken(null);

}

else

{

// not verified

$this->setVerifiedDateTime(null);

$this->setVerifierToken(self::generateVerifierToken($this->username ?? '', $this->email ?? ''));

}

}

/**

public function setVerifiedDateTime(DateTimeInterface|string|null $value): void

{

$this->verified_datetime = (is_string($value) ?

new DateTimeImmutable($value, new DateTimeZone(self::DATE_TZ)) : $value

);

}

/**

public function setVerifierToken(?string $value): void

{

if (!is_null($value) && (empty($value) || strlen($value) > self::MAX_VERIFIER_TOKEN))

{

throw new OutOfBoundsException(sprintf(

'value must be null or between 1-%d characters', self::MAX_VERIFIER_TOKEN

));

}