/** Lists the available database drivers, as an associative array with
/** Lists the available database drivers, as an associative array with
* fully-qualified class names as keys, and human-readable descriptions as values
*/
public static function driverList(): array {
@ -105,9 +105,9 @@ class Database {
}
/** Computes the column and value text of an SQL "SET" clause, validating arbitrary input against a whitelist
*
*
* Returns an indexed array containing the clause text, an array of types, and another array of values
*
*
* @param array $props An associative array containing untrusted data; keys are column names
* @param array $valid An associative array containing a whitelist: keys are column names, and values are strings representing data types
*/
@ -130,9 +130,9 @@ class Database {
}
/** Computes the contents of an SQL "IN()" clause, for each input value either embedding the value or producing a parameter placeholder
*
*
* Returns an indexed array containing the clause text, an array of types, and an array of values. Note that the array of output values may not match the array of input values
*
*
* @param array $values Arbitrary values
* @param string $type A single data type applied to each value
* @param string $passwordThe user's password in cleartext. It will be stored hashed
*/
@ -298,7 +298,7 @@ class Database {
}
/** Sets the password of an existing user
*
*
* @param string $user The user for whom to set the password
* @param string $password The new password, in cleartext. The password will be stored hashed. If null is passed, the password is unset and authentication not possible
*/
@ -329,10 +329,10 @@ class Database {
}
/** Explicitly removes a session from the database
*
* Sessions may also be invalidated as they expire, and then be automatically pruned.
*
* Sessions may also be invalidated as they expire, and then be automatically pruned.
* This function can be used to explicitly invalidate a session after a user logs out
*
*
* @param string $user The user who owns the session to be destroyed
* @param string $id The identifier of the session to destroy
*/
@ -346,7 +346,7 @@ class Database {
}
/** Resumes a session, returning available session data
*
*
* This also has the side effect of refreshing the session if it is near its timeout
*/
public function sessionResume(string $id): array {
/** Creates a new token for the given user in the given class
*
/** Creates a new token for the given user in the given class
*
* @param string $user The user for whom to create the token
* @param string $class The class of the token e.g. the protocol name
* @param string|null $id The value of the token; if none is provided a UUID will be generated
@ -403,7 +403,7 @@ class Database {
}
/** Revokes one or all tokens for a user in a class
*
*
* @param string $user The user who owns the token to be revoked
* @param string $class The class of the token e.g. the protocol name
* @param string|null $id The ID of a specific token, or null for all tokens in the class
@ -436,14 +436,14 @@ class Database {
}
/** Adds a folder for containing newsfeed subscriptions, returning an integer identifying the created folder
*
*
* The $data array may contain the following keys:
*
*
* - "name": A folder name, which must be a non-empty string not composed solely of whitespace; this key is required
* - "parent": An integer (or null) identifying a parent folder; this key is optional
*
*
* If a folder with the same name and parent already exists, this is an error
*
*
* @param string $user The user who will own the folder
* @param array $data An associative array defining the folder
*/
@ -462,15 +462,15 @@ class Database {
}
/** Returns a result set listing a user's folders
*
*
* Each record in the result set contains:
*
*
* - "id": The folder identifier, an integer
* - "name": The folder's name, a string
* - "parent": The integer identifier of the folder's parent, or null
* - "children": The number of child folders contained in the given folder
* - "feeds": The number of newsfeed subscriptions contained in the given folder, not including subscriptions in descendent folders
*
* - "feeds": The number of newsfeed subscriptions contained in the given folder, not including subscriptions in descendent folders
*
* @param string $uer The user whose folders are to be listed
* @param integer|null $parent Restricts the list to the descendents of the specified folder identifier
* @param boolean $recursive Whether to list all descendents (true) or only direct children (false)
@ -505,9 +505,9 @@ class Database {
}
/** Deletes a folder from the database
*
*
* Any descendent folders are also deleted, as are all newsfeed subscriptions contained in the deleted folder tree
*
*
* @param string $user The user to whom the folder to be deleted belongs
* @param integer $id The identifier of the folder to delete
*/
@ -541,14 +541,14 @@ class Database {
}
/** Modifies the properties of a folder
*
*
* The $data array must contain one or more of the following keys:
*
*
* - "name": A new folder name, which must be a non-empty string not composed solely of whitespace
* - "parent": An integer (or null) identifying a parent folder
*
*
* If a folder with the new name and parent combination already exists, this is an error; it is also an error to move a folder to itself or one of its descendents
*
*
* @param string $user The user who owns the folder to be modified
* @param integer $id The identifier of the folder to be modified
* @param array $data An associative array of properties to modify. Anything not specified will remain unchanged
@ -590,9 +590,9 @@ class Database {
}
/** Ensures the specified folder exists and raises an exception otherwise
*
* Returns an associative array containing the id, name, and parent of the folder if it exists
*
*
* Returns an associative array containing the id, name, and parent of the folder if it exists
*
* @param string $user The user who owns the folder to be validated
* @param integer|null $id The identifier of the folder to validate; null or zero represent the implied root folder
* @param boolean $subject Whether the folder is the subject (true) rather than the object (false) of the operation being performed; this only affects the semantics of the error message if validation fails
@ -668,7 +668,7 @@ class Database {
}
/** Ensures a prospective folder name is valid, and optionally ensure it is not a duplicate if renamed
*
*
* @param string $name The name to check
* @param boolean $checkDuplicates Whether to also check if the new name would cause a collision
* @param integer|null $parent The parent folder context in which to check for duplication
@ -695,7 +695,7 @@ class Database {
}
/** Adds a subscription to a newsfeed, and returns the numeric identifier of the added subscription
*
*
* @param string $user The user which will own the subscription
* @param string $url The URL of the newsfeed or discovery source
* @param string $fetchUser The user name required to access the newsfeed, if applicable
@ -731,7 +731,7 @@ class Database {
}
/** Lists a user's subscriptions, returning various data
*
*
* @param string $user The user whose subscriptions are to be listed
* @param integer|null $folder The identifier of the folder under which to list subscriptions; by default the root folder is used
* @param boolean $recursive Whether to list subscriptions of descendent folders as well as the selected folder
@ -802,8 +802,8 @@ class Database {
}
/** Deletes a subscription from the database
*
* This has the side effect of deleting all marks the user has set on articles
*
* This has the side effect of deleting all marks the user has set on articles
* belonging to the newsfeed, but may not delete the articles themselves, as
* other users may also be subscribed to the same newsfeed. There is also a
* configurable retention period for newsfeeds
@ -823,7 +823,7 @@ class Database {
}
/** Retrieves data about a particular subscription, as an associative array with the following keys:
*
*
* - "id": The numeric identifier of the subscription
* - "feed": The numeric identifier of the underlying newsfeed
* - "url": The URL of the newsfeed, after discovery and HTTP redirects
@ -855,14 +855,14 @@ class Database {
}
/** Modifies the properties of a subscription
*
*
* The $data array must contain one or more of the following keys:
*
*
* - "title": The title of the newsfeed
* - "folder": The numeric identifier (or null) of the subscription's folder
* - "pinned": Whether the subscription is pinned
* - "order_type": Whether articles should be sorted in reverse cronological order (2), chronological order (1), or the default (0)
*
*
* @param string $user The user whose subscription is to be modified
* @param integer $id the numeric identifier of the subscription to modfify
* @param array $data An associative array of properties to modify; any keys not specified will be left unchanged
@ -908,7 +908,7 @@ class Database {
}
/** Returns an indexed array listing the tags assigned to a subscription
*
*
* @param string $user The user whose tags are to be listed
* @param integer $id The numeric identifier of the subscription whose tags are to be listed
* @param boolean $byName Whether to return the tag names (true) instead of the numeric tag identifiers (false)
@ -924,14 +924,14 @@ class Database {
}
/** Retrieves the URL of the icon for a subscription.
*
*
* Note that while the $user parameter is optional, it
* is NOT recommended to omit it, as this can lead to
* leaks of private information. The parameter is only
* is NOT recommended to omit it, as this can lead to
* leaks of private information. The parameter is only
* optional because this is required for Tiny Tiny RSS,
* the original implementation of which leaks private
* information due to a design flaw.
*
*
* @param integer $id The numeric identifier of the subscription
* @param string|null $user The user who owns the subscription being queried
*/
@ -965,9 +965,9 @@ class Database {
}
/** Ensures the specified subscription exists and raises an exception otherwise
*
*
* Returns an associative array containing the id of the subscription and the id of the underlying newsfeed
*
*
* @param string $user The user who owns the subscription to be validated
* @param integer $id The identifier of the subscription to validate
* @param boolean $subject Whether the subscription is the subject (true) rather than the object (false) of the operation being performed; this only affects the semantics of the error message if validation fails
@ -990,7 +990,7 @@ class Database {
}
/** Attempts to refresh a newsfeed, returning an indication of success
*
*
* @param integer $feedID The numerical identifier of the newsfeed to refresh
* @param boolean $throwError Whether to throw an exception on failure in addition to storing error information in the database
*/
@ -1146,7 +1146,7 @@ class Database {
}
/** Deletes orphaned newsfeeds from the database
*
*
* Newsfeeds are orphaned if no users are subscribed to them. Deleting a newsfeed also deletes its articles
*/
public function feedCleanup(): bool {
@ -1167,14 +1167,14 @@ class Database {
}
/** Retrieves various identifiers for the latest $count articles in the given newsfeed. The identifiers are:
*
*
* - "id": The database record key for the article
* - "guid": The (theoretically) unique identifier for the article
* - "edited": The time at which the article was last edited, per the newsfeed
* - "url_title_hash": A cryptographic hash of the article URL and its title
* - "url_content_hash": A cryptographic hash of the article URL and its content
* - "title_content_hash": A cryptographic hash of the article title and its content
*
*
* @param integer $feedID The numeric identifier of the feed
* @param integer $count The number of records to return
*/
@ -1187,14 +1187,14 @@ class Database {
}
/** Retrieves various identifiers for articles in the given newsfeed which match the input identifiers. The output identifiers are:
*
*
* - "id": The database record key for the article
* - "guid": The (theoretically) unique identifier for the article
* - "edited": The time at which the article was last edited, per the newsfeed
* - "url_title_hash": A cryptographic hash of the article URL and its title
* - "url_content_hash": A cryptographic hash of the article URL and its content
* - "title_content_hash": A cryptographic hash of the article title and its content
*
*
* @param integer $feedID The numeric identifier of the feed
* @param array $ids An array of GUIDs of articles
* @param array $hashesUT An array of hashes of articles' URL and title
@ -1219,7 +1219,7 @@ class Database {
}
/** Returns an associative array of result column names and their SQL computations for article queries
*
*
* This is used for whitelisting and defining both output column and order-by columns, as well as for resolution of some context options
*/
protected function articleColumns(): array {
@ -1250,9 +1250,9 @@ class Database {
}
/** Computes an SQL query to find and retrieve data about articles in the database
*
*
* If an empty column list is supplied, a count of articles matching the context is queried instead
*
*
* @param string $user The user whose articles are to be queried
* @param Context $context The search context
* @param array $cols The columns to request in the result set
/** Lists articles in the database which match a given query context
*
*
* If an empty column list is supplied, a count of articles is returned instead
*
*
* @param string $user The user whose articles are to be listed
* @param Context $context The search context
* @param array $fieldss The columns to return in the result set, any of: id, edition, url, title, author, content, guid, fingerprint, folder, subscription, feed, starred, unread, note, published_date, edited_date, modified_date, marked_date, subscription_title, media_url, media_type
@ -1576,7 +1576,7 @@ class Database {
}
/** Returns a count of articles which match the given query context
*
*
* @param string $user The user whose articles are to be counted
* @param Context $context The search context
*/
@ -1590,13 +1590,13 @@ class Database {
}
/** Applies one or multiple modifications to all articles matching the given query context
*
*
* The $data array enumerates the modifications to perform and must contain one or more of the following keys:
*
*
* - "read": Whether the article should be marked as read (true) or unread (false)
* - "starred": Whether the article should (true) or should not (false) be marked as starred/favourite
* - "note": A string containing a freeform plain-text note for the article
*
*
* @param string $user The user who owns the articles to be modified
* @param array $data An associative array of properties to modify. Anything not specified will remain unchanged
* @param Context $context The query context to match articles against
@ -1680,9 +1680,9 @@ class Database {
}
/** Returns statistics about the articles starred by the given user
*
*
* The associative array returned has the following keys:
*
*
* - "total": The count of all starred articles
* - "unread": The count of starred articles which are unread
* - "read": The count of starred articles which are read
@ -1704,7 +1704,7 @@ class Database {
}
/** Returns an indexed array listing the labels assigned to an article
*
*
* @param string $user The user whose labels are to be listed
* @param integer $id The numeric identifier of the article whose labels are to be listed
* @param boolean $byName Whether to return the label names (true) instead of the numeric label identifiers (false)
@ -1768,9 +1768,9 @@ class Database {
}
/** Ensures the specified article exists and raises an exception otherwise
*
* Returns an associative array containing the id and latest edition of the article if it exists
*
*
* Returns an associative array containing the id and latest edition of the article if it exists
*
* @param string $user The user who owns the article to be validated
* @param integer $id The identifier of the article to validate
*/
@ -1795,9 +1795,9 @@ class Database {
}
/** Ensures the specified article edition exists and raises an exception otherwise
*
* Returns an associative array containing the edition id, article id, and latest edition of the edition if it exists
*
*
* Returns an associative array containing the edition id, article id, and latest edition of the edition if it exists
*
* @param string $user The user who owns the edition to be validated
* @param integer $id The identifier of the edition to validate
*/
@ -1848,9 +1848,9 @@ class Database {
}
/** Creates a label, and returns its numeric identifier
*
*
* Labels are discrete objects in the database and can be associated with multiple articles; an article may in turn be associated with multiple labels
*
*
* @param string $user The user who will own the created label
* @param array $data An associative array defining the label's properties; currently only "name" is understood
*/
@ -1867,14 +1867,14 @@ class Database {
}
/** Lists a user's article labels
*
*
* The following keys are included in each record:
*
*
* - "id": The label's numeric identifier
* - "name" The label's textual name
* - "articles": The count of articles which have the label assigned to them
* - "read": How many of the total articles assigned to the label are read
*
*
* @param string $user The user whose labels are to be listed
* @param boolean $includeEmpty Whether to include (true) or supress (false) labels which have no articles assigned to them
*/
@ -1911,9 +1911,9 @@ class Database {
}
/** Deletes a label from the database
*
*
* Any articles associated with the label remains untouched
*
*
* @param string $user The owner of the label to remove
* @param integer|string $id The numeric identifier or name of the label
* @param boolean $byName Whether to interpret the $id parameter as the label's name (true) or identifier (false)
@ -1933,14 +1933,14 @@ class Database {
}
/** Retrieves the properties of a label
*
*
* The following keys are included in the output array:
*
*
* - "id": The label's numeric identifier
* - "name" The label's textual name
* - "articles": The count of articles which have the label assigned to them
* - "read": How many of the total articles assigned to the label are read
*
*
* @param string $user The owner of the label to remove
* @param integer|string $id The numeric identifier or name of the label
* @param boolean $byName Whether to interpret the $id parameter as the label's name (true) or identifier (false)
@ -1981,7 +1981,7 @@ class Database {
}
/** Sets the properties of a label
*
*
* @param string $user The owner of the label to query
* @param integer|string $id The numeric identifier or name of the label
* @param array $data An associative array defining the label's properties; currently only "name" is understood
@ -2013,7 +2013,7 @@ class Database {
}
/** Returns an indexed array of article identifiers assigned to a label
*
*
* @param string $user The owner of the label to query
* @param integer|string $id The numeric identifier or name of the label
* @param boolean $byName Whether to interpret the $id parameter as the label's name (true) or identifier (false)
@ -2039,7 +2039,7 @@ class Database {
}
/** Makes or breaks associations between a given label and articles matching the given query context
*
*
* @param string $user The owner of the label
* @param integer|string $id The numeric identifier or name of the label
* @param Context $context The query context matching the desired articles
@ -2080,9 +2080,9 @@ class Database {
}
/** Ensures the specified label identifier or name is valid (and optionally whether it exists) and raises an exception otherwise
*
* Returns an associative array containing the id, name of the label if it exists
*
*
* Returns an associative array containing the id, name of the label if it exists
*
* @param string $user The user who owns the label to be validated
* @param integer|string $id The numeric identifier or name of the label to validate
* @param boolean $byName Whether to interpret the $id parameter as the label's name (true) or identifier (false)
@ -2127,9 +2127,9 @@ class Database {
}
/** Creates a tag, and returns its numeric identifier
*
*
* Tags are discrete objects in the database and can be associated with multiple subscriptions; a subscription may in turn be associated with multiple tags
*
*
* @param string $user The user who will own the created tag
* @param array $data An associative array defining the tag's properties; currently only "name" is understood
*/
@ -2146,13 +2146,13 @@ class Database {
}
/** Lists a user's subscription tags
*
*
* The following keys are included in each record:
*
*
* - "id": The tag's numeric identifier
* - "name" The tag's textual name
* - "subscriptions": The count of subscriptions which have the tag assigned to them
*
*
* @param string $user The user whose tags are to be listed
* @param boolean $includeEmpty Whether to include (true) or supress (false) tags which have no subscriptions assigned to them
*/
@ -2177,14 +2177,14 @@ class Database {
}
/** Lists the associations between all tags and subscription
*
*
* The following keys are included in each record:
*
*
* - "tag_id": The tag's numeric identifier
* - "tag_name" The tag's textual name
* - "subscription_id": The numeric identifier of the associated subscription
* - "subscription_name" The subscription's textual name
*
*
* @param string $user The user whose tags are to be listed
*/
public function tagSummarize(string $user): Db\Result {
@ -2205,9 +2205,9 @@ class Database {
}
/** Deletes a tag from the database
*
*
* Any subscriptions associated with the tag remains untouched
*
*
* @param string $user The owner of the tag to remove
* @param integer|string $id The numeric identifier or name of the tag
* @param boolean $byName Whether to interpret the $id parameter as the tag's name (true) or identifier (false)
@ -2227,13 +2227,13 @@ class Database {
}
/** Retrieves the properties of a tag
*
*
* The following keys are included in the output array:
*
*
* - "id": The tag's numeric identifier
* - "name" The tag's textual name
* - "subscriptions": The count of subscriptions which have the tag assigned to them
*
*
* @param string $user The owner of the tag to remove
* @param integer|string $id The numeric identifier or name of the tag
* @param boolean $byName Whether to interpret the $id parameter as the tag's name (true) or identifier (false)
@ -2262,7 +2262,7 @@ class Database {
}
/** Sets the properties of a tag
*
*
* @param string $user The owner of the tag to query
* @param integer|string $id The numeric identifier or name of the tag
* @param array $data An associative array defining the tag's properties; currently only "name" is understood
@ -2294,7 +2294,7 @@ class Database {
}
/** Returns an indexed array of subscription identifiers assigned to a tag
*
*
* @param string $user The owner of the tag to query
* @param integer|string $id The numeric identifier or name of the tag
* @param boolean $byName Whether to interpret the $id parameter as the tag's name (true) or identifier (false)
@ -2320,7 +2320,7 @@ class Database {
}
/** Makes or breaks associations between a given tag and specified subscriptions
*
*
* @param string $user The owner of the tag
* @param integer|string $id The numeric identifier or name of the tag
* @param integer[] $context The query context matching the desired subscriptions
@ -2339,7 +2339,7 @@ class Database {
$q1 = $this->db->prepare(
"UPDATE arsse_tag_members
set assigned = ?, modified = CURRENT_TIMESTAMP
where tag = ? and assigned <> ? and subscription in (select id from arsse_subscriptions where owner = ? and id in ($inClause))",
where tag = ? and assigned <> ? and subscription in (select id from arsse_subscriptions where owner = ? and id in ($inClause))",
"bool",
"int",
"bool",
@ -2370,9 +2370,9 @@ class Database {
}
/** Ensures the specified tag identifier or name is valid (and optionally whether it exists) and raises an exception otherwise
*
* Returns an associative array containing the id, name of the tag if it exists
*
*
* Returns an associative array containing the id, name of the tag if it exists
*
* @param string $user The user who owns the tag to be validated
* @param integer|string $id The numeric identifier or name of the tag to validate
* @param boolean $byName Whether to interpret the $id parameter as the tag's name (true) or identifier (false)
/** Returns the version of the schema of the opened database; if uninitialized should return 0
*
*
* Normally the version is stored under the 'schema_version' key in the arsse_meta table, but another method may be used if appropriate
*/
public function schemaVersion(): int;
@ -32,7 +32,7 @@ interface Driver {
public function begin(bool $lock = false): Transaction;
/** Manually begins a real or synthetic transactions, with real or synthetic nesting, and returns its numeric ID
*
*
* If the database backend does not implement savepoints, IDs must still be tracked as if it does
*/
public function savepointCreate(): int;
@ -44,7 +44,7 @@ interface Driver {
public function savepointUndo(int $index = null): bool;
/** Performs an in-place upgrade of the database schema
*
*
* The driver may choose not to implement in-place upgrading, in which case an exception should be thrown
*/
public function schemaUpdate(int $to): bool;
@ -62,15 +62,15 @@ interface Driver {
public function prepareArray(string $query, array $paramTypes): Statement;
/** Reports whether the database character set is correct/acceptable
*
*
* The backend must be able to accept and provide UTF-8 text; information may be stored in any encoding capable of representing the entire range of Unicode
*/
public function charsetAcceptable(): bool;
/** Returns an implementation-dependent form of a reference SQL function or operator
*
*
* The tokens the implementation must understand are:
*
*
* - "greatest": the GREATEST function implemented by PostgreSQL and MySQL
* - "nocase": the name of a general-purpose case-insensitive collation sequence
* - "like": the case-insensitive LIKE operator
@ -78,7 +78,7 @@ interface Driver {
public function sqlToken(string $token): string;
/** Returns a string literal which is properly escaped to guard against SQL injections. Delimiters are included in the output string
*
*
* This functionality should be avoided in favour of using statement parameters whenever possible
*/
public function literalString(string $str): string;
