izartu API

Bookmark extends Crud
in package

Application

A bookmark: a typed record plus its own persistence (Active Record).

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

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.
tagsFor() : array<int, array<int, string>>: The tag names of several bookmarks in a single query (one page's worth), the batch counterpart of `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|false}: Build the WHERE clause a listing needs (visibility and tag filters).
hydrate() : self: Build a Bookmark from a database row.
select() : array<int, array{id: int, title: string, hlink: string, text: string, user: int, visibility: string, add: string, mod: string, username: string|null}>: Read bookmark rows matching an SQL condition.

$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
    $db

Shared PDO connection, created once on first construction.

__construct()

Open the shared database connection, once.


    public
        final            __construct() : mixed

The first instantiation builds it from the DB_* constants and the rest reuse it; 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.

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_SIZE bookmarks.
$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: list, pages: int} —

The 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

add and mod are left to the database, so both come from one clock; this object does not learn their values until it is read back.

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>

For a listing, fetch every row's tags in one query with tagsFor() instead of calling this per bookmark.

Return values

array<int, string> —

Tag names, alphabetical.

tagsFor()

The tag names of several bookmarks in a single query (one page's worth), the batch counterpart of `tags()`.


    public
                    tagsFor(array<int, int> $ids) : array<int, array<int, string>>

Parameters

$ids : array<int, int>: Bookmark ids.

Return values

array<int, array<int, string>> —

Tag names (alphabetical) per bookmark id; ids without tags are absent.

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

bool

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.

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: list|false} —

The WHERE clause (never empty) and its bind parameters.

hydrate()

Build a Bookmark from a database row.


    private
            static        hydrate(array{id: int, title: string, hlink: string, text: string, user: int, visibility: string, add: string, mod: string, username: string|null} $row) : self

Parameters

$row : array{id: int, title: string, hlink: string, text: string, user: int, visibility: string, add: string, mod: string, username: string|null}: A bookmark row (see select).

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{id: int, title: string, hlink: string, text: string, user: int, visibility: string, add: string, mod: string, username: string|null}>

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{id: int, title: string, hlink: string, text: string, user: int, visibility: string, add: string, mod: string, username: string|null}> —

One raw row per bookmark.

Bookmark extends Crud in package Application

Table of Contents

Properties

Methods

Properties

$add

$hlink

$id

$mod

$text

$title

$user

$username

$visibility

$db

Methods

__construct()

delete()

deleteTags()

find()

Parameters

Return values

orderByDate()

Parameters

Return values

pageWindow()

Parameters

Return values

parseTags()

Parameters

Return values

save()

saveTags()

Parameters

tags()

Return values

tagsFor()

Parameters

Return values

visibleTo()

Parameters

Return values

read()

Parameters

Return values

count()

Parameters

Return values

filter()

Parameters

Return values

hydrate()

Parameters

Return values

select()

Parameters

Return values

Bookmark extends Crud
in package

Application