Bookmark
extends Crud
in package
A bookmark: a typed record plus its own persistence (Active Record).
Table of Contents
Properties
- $add : string|null
- $hlink : string
- $id : int|null
- $mod : string|null
- $text : string
- $title : string
- $user : int
- $username : string
- Owner's display name, read via JOIN; never written back.
- $visibility : Visibility
- $db : PDO|null
Methods
- __construct() : mixed
- Open the shared database connection (once).
- delete() : void
- Delete this bookmark and its tag links.
- deleteTags() : void
- Unlink every tag from this bookmark.
- find() : self|null
- Find a bookmark by id.
-
orderByDate()
: array{bookmarks: list
, pages: int} - Read one page of bookmarks ordered by modification date.
- pageWindow() : array<int, int|null>
- The page numbers a pager should display: first, last, and a window around the current page, with null marking each gap (an ellipsis).
- parseTags() : array<int, string>
- Split a comma-separated tag string into normalised tag names.
- save() : void
- Insert this bookmark when it is new, or update it when it has an id.
- saveTags() : void
- Replace this bookmark's tags with the ones in a comma-separated string.
- tags() : array<int, string>
- The names of this bookmark's tags.
- visibleTo() : bool
- Whether a viewer may see this bookmark.
- read() : array<int, array<string, mixed>>
- Prepare and run a read query, then return its rows.
- count() : int
- Count the bookmarks the current listing can see.
-
filter()
: array{0: string, 1: list
- Build the WHERE clause a listing needs (visibility and tag filters).
- hydrate() : self
- Build a Bookmark from a database row.
- select() : array<int, array<string, mixed>>
- Read bookmark rows matching an SQL condition.
Properties
$add
public
string|null
$add
= \null
$hlink
public
string
$hlink
= ''
$id
public
int|null
$id
= \null
$mod
public
string|null
$mod
= \null
$text
public
string
$text
= ''
$title
public
string
$title
= ''
$user
public
int
$user
= 0
$username
Owner's display name, read via JOIN; never written back.
public
string
$username
= ''
$visibility
public
Visibility
$visibility
= \Visibility::Private
$db
protected
static PDO|null
$db
= \null
Shared PDO connection, created once on first construction.
Methods
__construct()
Open the shared database connection (once).
public
final __construct() : mixed
On the first instantiation it builds the PDO instance from the configured
DB_* constants; later instantiations reuse it. Triggers E_USER_ERROR
if the connection fails. With DEBUG on, statements are created as
DebugStatement so every query execution is timed.
delete()
Delete this bookmark and its tag links.
public
delete() : void
deleteTags()
Unlink every tag from this bookmark.
public
deleteTags() : void
find()
Find a bookmark by id.
public
static find(int $id) : self|null
Parameters
- $id : int
-
The bookmark id.
Return values
self|null —The hydrated bookmark, or null if none has that id.
orderByDate()
Read one page of bookmarks ordered by modification date.
public
final orderByDate([int|null $viewer = null ][, int $page = 1 ][, array<int, string> $tags = [] ][, string|null $username = null ][, bool $order = false ]) : array{bookmarks: list, pages: int}
Parameters
- $viewer : int|null = null
-
The viewer's user id (
Auth::id()), or null for anonymous. A viewer sees public bookmarks plus their own private ones. - $page : int = 1
-
1-based page number; each page holds
PAGE_SIZEbookmarks. - $tags : array<int, string> = []
-
Only bookmarks carrying ALL these tag names; empty for all.
- $username : string|null = null
-
Only bookmarks added by this user, or null for all.
- $order : bool = false
-
true for ascending order, false (default) for descending.
Return values
array{bookmarks: listThe page's bookmarks (newest first by default) and the total number of pages (at least 1).
pageWindow()
The page numbers a pager should display: first, last, and a window around the current page, with null marking each gap (an ellipsis).
public
static pageWindow(int $page, int $pages[, int $radius = 2 ]) : array<int, int|null>
Parameters
- $page : int
-
Current 1-based page number.
- $pages : int
-
Total number of pages.
- $radius : int = 2
-
How many pages to show on each side of the current one.
Return values
array<int, int|null> —Page numbers in order, null where pages are skipped.
parseTags()
Split a comma-separated tag string into normalised tag names.
public
static parseTags(string $tags) : array<int, string>
Parameters
- $tags : string
-
Comma-separated tag names, as typed by the user.
Return values
array<int, string> —Lower-case, trimmed names with inner whitespace collapsed, deduplicated; empties dropped.
save()
Insert this bookmark when it is new, or update it when it has an id.
public
save() : void
saveTags()
Replace this bookmark's tags with the ones in a comma-separated string.
public
saveTags(string $tags) : void
Each name is upserted into tag (reusing the id when the name exists)
and linked in bookmark_tag.
Parameters
- $tags : string
-
Comma-separated tag names, as typed by the user.
tags()
The names of this bookmark's tags.
public
tags() : array<int, string>
Return values
array<int, string> —Tag names, alphabetical.
visibleTo()
Whether a viewer may see this bookmark.
public
visibleTo(int|null $viewer) : bool
Public bookmarks are visible to everyone; private ones only to their owner (no role sees another user's private bookmarks).
Parameters
- $viewer : int|null
-
The viewer's user id, or null for anonymous.
Return values
boolread()
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.
count()
Count the bookmarks the current listing can see.
private
count(int|null $viewer[, array<int, string> $tags = [] ][, string|null $username = null ]) : int
Parameters
- $viewer : int|null
-
The viewer's user id, or null for anonymous.
- $tags : array<int, string> = []
-
Only bookmarks carrying ALL these tag names; empty for all.
- $username : string|null = null
-
Only bookmarks added by this user, or null for all.
Return values
int —The bookmark count.
filter()
Build the WHERE clause a listing needs (visibility and tag filters).
private
filter(int|null $viewer[, array<int, string> $tags = [] ][, string|null $username = null ]) : array{0: string, 1: list|false}
Parameters
- $viewer : int|null
-
The viewer's user id, or null for anonymous.
- $tags : array<int, string> = []
-
Only bookmarks carrying ALL these tag names; empty for all.
- $username : string|null = null
-
Only bookmarks added by this user, or null for all.
Return values
array{0: string, 1: listThe WHERE clause (never empty) and its bind parameters.
hydrate()
Build a Bookmark from a database row.
private
static hydrate(array<string, mixed> $row) : self
Parameters
- $row : array<string, mixed>
-
A bookmark row with the selected columns.
Return values
self —The hydrated bookmark.
select()
Read bookmark rows matching an SQL condition.
private
select(string|false $cond, array<int, array{0: string, 1: mixed, 2: int, 3: int}>|false $param) : array<int, array<string, mixed>>
Parameters
- $cond : string|false
-
Extra SQL appended to the base SELECT, or false.
- $param : array<int, array{0: string, 1: mixed, 2: int, 3: int}>|false
-
Bind parameters for $cond (each: [name, value, PDO type, length]), or false.
Return values
array<int, array<string, mixed>> —One raw row per bookmark.