User
extends Crud
in package
User records: look up accounts for authentication.
Table of Contents
Constants
- RESERVED : mixed = ['me']
- Usernames no account may take, compared case-insensitively: `me` backs the `/user/me` alias for one's own page.
- ROLES : mixed = ['owner', 'admin', 'user']
- The roles a user account may hold.
Methods
- dsn() : string
- Build a MySQL DSN, for the app's connection and for the CLI scripts that open their own.
- findByEmail() : array{id: int, username: string, email: string, hash: string, role: string}|null
- Find a user by email address.
- validate() : array<string, string>
- Validate the fields needed to create a user account.
- db() : PDO
- The shared database connection, opened on first use.
- read() : array<int, array<string, mixed>>
- Prepare and run a read query, then return its rows.
Constants
RESERVED
Usernames no account may take, compared case-insensitively: `me` backs the `/user/me` alias for one's own page.
public
mixed
RESERVED
= ['me']
ROLES
The roles a user account may hold.
public
mixed
ROLES
= ['owner', 'admin', 'user']
Methods
dsn()
Build a MySQL DSN, for the app's connection and for the CLI scripts that open their own.
public
static dsn(string $host, int $port, string $name) : string
Parameters
- $host : string
-
Host name or IP address, or the path of a Unix socket (it starts with
/). - $port : int
-
TCP port, left out of the DSN when it is MySQL's default (3306) and ignored for a socket.
- $name : string
-
Database name.
Return values
string —The PDO DSN, with the utf8mb4 charset.
findByEmail()
Find a user by email address.
public
findByEmail(string $email) : array{id: int, username: string, email: string, hash: string, role: string}|null
Parameters
- $email : string
-
Normalised (lower-case) email to look up.
Return values
array{id: int, username: string, email: string, hash: string, role: string}|null —The user row, or null if no user has that email.
validate()
Validate the fields needed to create a user account.
public
static validate(string $email, string $username, string $password, string $role) : array<string, string>
Parameters
- $email : string
-
Email address (identity + login).
- $username : string
-
Public display name.
- $password : string
-
Plain password (checked before hashing).
- $role : string
-
One of
self::ROLES.
Return values
array<string, string> —Error message per invalid field; empty if valid.
db()
The shared database connection, opened on first use.
protected
final static db() : PDO
Building, validating or formatting a model therefore needs no database. The connection comes from the DB_*
constants; a failure triggers E_USER_ERROR. With DEBUG on, statements are created as DebugStatement so every
query execution is timed.
Prepared statements are native, so integer columns come back as int; the charset is utf8mb4 and the timezone
is the server's.
Return values
PDO —The shared connection.
read()
Prepare and run a read query, then return its rows.
protected
final read(string $sql[, array<int, array{0: string, 1: mixed, 2: int, 3: int}>|false $param = false ]) : array<int, array<string, mixed>>
Parameters
- $sql : string
-
SQL query with bind placeholders.
- $param : array<int, array{0: string, 1: mixed, 2: int, 3: int}>|false = false
-
Bind parameters (each: [name, value, PDO type, length]), or false for none.
Return values
array<int, array<string, mixed>> —The result rows.