Text
in package
Text
Includes access methods and data layer. Do not, I repeat, do not mess with protected fields, or even try to access the database directly (unless you know what you are doing, but you most probably don't).
Tags
Table of Contents
Properties
Methods
- __construct() : mixed
- Create a Text object
- add() : int
- OBSOLETE -- see {@see replace()} Add a new Text object directly to the database table
- content() : string
- Returns the text
- delete() : bool
- Deletes the Text record from the database
- deleteById() : bool
- Delete a record from the database.
- deleteByKey() : bool
- Deletes the Text records with the given section and key from the database
- deleteLanguage() : bool
- Delete all Text with the given language ID from the database.
- errorHandler() : bool
- Handle any error occurring in this class.
- getArrayById() : array<string|int, mixed>
- OBSOLETE Returns an array of objects selected by language ID, section, and key, plus optional text IDs from the database.
- getById() : Text
- Select an object by ID from the database.
- getByKey() : Text
- OBSOLETE Select an object by its key from the database
- getIdArrayBySearch() : array<string|int, mixed>
- OBSOLETE Returns an array of Text and language IDs of records matching the search pattern and optional section, key, language, and text IDs
- getSqlSnippets() : array<string|int, mixed>
- Returns an array of SQL snippets to include the selected Text records in the query.
- id() : int
- Get the ID
- insert() : bool
- Insert this object into the database.
- key() : string
- Returns the key
- lang_id() : int
- Returns the language ID
- makeClone() : mixed
- Clone the object
- markDifferentLanguage() : mixed
- If the language ID given is different from the language of this Text object, the content may be marked here.
- nextId() : int
- OBSOLETE Returns the next available ID
- recordExists() : bool
- Test whether a record of this is already present in the database.
- replace() : int
- Replace or insert the Text record
- section() : string
- Returns the section
- store() : bool
- Stores the object in the database.
- update() : bool
- Update this object in the database.
Properties
$id
protected
int
$id
= \null
The object ID
$key
protected
string
$key
= \null
The optional key
$lang_id
protected
int
$lang_id
= \null
The language ID
$replacement
protected
bool
$replacement
= \null
True if a replacement language was used
$section
protected
string
$section
= \null
The optional section
$text
protected
string
$text
= \null
The content
Methods
__construct()
Create a Text object
public
__construct(string $text, int $lang_id, string $section, string $key[, int $id = null ]) : mixed
Parameters
- $text : string
-
The content
- $lang_id : int
-
The language ID
- $section : string
-
The section
- $key : string
-
The key
- $id : int = null
-
The optional Text ID. Defaults to null
Tags
add()
OBSOLETE -- see {@see replace()} Add a new Text object directly to the database table
public
static add(string $text, string $key[, mixed $lang_id = 0 ]) : int
Mind that this method uses the MODULE_ID global constant. This is but a handy shortcut for those in the know.
Parameters
- $text : string
-
The optional language ID, defaults to FRONTEND_LANG_ID
- $key : string
-
The key
- $lang_id : mixed = 0
Return values
int —The object ID on success, false otherwise
content()
Returns the text
public
content([string $text = null ]) : string
Optionally sets the text. The string value is used as-is, but is ignored if null. Nothing is checked, trimmed nor stripped. Mind your step! Note: This method cannot be called text() for obscure reasons. :)
Parameters
- $text : string = null
-
The optional text
Tags
Return values
string —The text
delete()
Deletes the Text record from the database
public
delete([bool $all_languages = false ]) : bool
If the optional $all_languages parameter evaluates to boolean true, all records with the same ID are deleted. Otherwise, only the language of this object is affected.
Parameters
- $all_languages : bool = false
-
Delete all languages if true
Tags
Return values
bool —True on success, false otherwise
deleteById()
Delete a record from the database.
public
static deleteById(int $id, string $section, string $key[, int $lang_id = null ]) : bool
Deletes the Text record in the selected language, if not empty. If the optional $lang_id parameter is missing or empty, all languages are removed. Note that you SHOULD NOT call this from outside the module classes as all of these SHOULD take care of cleaning up by themselves. Remark: See for details on nuking entire sections.
Parameters
- $id : int
-
The ID
- $section : string
-
The section
- $key : string
-
The key
- $lang_id : int = null
-
The optional language ID
Tags
Return values
bool —True on success, false otherwise
deleteByKey()
Deletes the Text records with the given section and key from the database
public
static deleteByKey(string $section, string $key) : bool
Use with due care! If you entirely omit the key, or set it to null, no change will take place. Explicitly set it to the empty string, zero, or false to have it ignored in the process. In that case, the complete section will be deleted! If you set $section to null, "global" entries are affected, where the section field is indeed NULL.
Parameters
- $section : string
-
The section
- $key : string
-
The key to match
Tags
Return values
bool —True on success, false otherwise
deleteLanguage()
Delete all Text with the given language ID from the database.
public
static deleteLanguage(int $lang_id) : bool
This is dangerous stuff -- mind your step!
Parameters
- $lang_id : int
-
The language ID
Tags
Return values
bool —True on success, false otherwise
errorHandler()
Handle any error occurring in this class.
public
static errorHandler() : bool
Tries to fix known problems with the database table.
Tags
Return values
bool —False. Always.
getArrayById()
OBSOLETE Returns an array of objects selected by language ID, section, and key, plus optional text IDs from the database.
public
static getArrayById(int $lang_id, string $section, string $key[, int $ids = '' ]) : array<string|int, mixed>
You may multiply the $lang_id parameter with -1 to get a negative value, in which case this method behaves very much like and returns other languages or a warning if the language with the same positive ID is unavailable. This is intended for backend use only. The array returned looks like this: array( text_id => obj_text, ... more ... )
Parameters
- $lang_id : int
-
The language ID
- $section : string
-
The section
- $key : string
-
The key
- $ids : int = ''
-
The optional comma separated list of Text IDs
Tags
Return values
array<string|int, mixed> —The array of Text objects on success, null otherwise
getById()
Select an object by ID from the database.
public
static getById(int $id, string $section, string $key[, int $lang_id = null ]) : Text
Note that if the $lang_id parameter is empty, this method picks the first language of the Text that it encounters. This is useful for displaying records in languages which haven't been edited yet. If the Text cannot be found for the language ID given, the first language encountered is returned. If no record is found for the given ID, creates a new object with an empty string content, and returns it.
Parameters
- $id : int
-
The ID
- $section : string
-
The section, may be null
- $key : string
-
The key
- $lang_id : int = null
-
The optional language ID
Tags
Return values
Text —The Text
getByKey()
OBSOLETE Select an object by its key from the database
public
static getByKey(int $key, int $lang_id) : Text
This method is intended to provide a means to store arbitrary texts in various languages that don't need to be referred to by an ID, but some distinct key. If the key is not unique, however, you will not be able to retrieve any particular of those records, but only the first one that is encountered. Note that if the $lang_id parameter is zero, this method picks the first language of the Text that it encounters. This is useful for displaying records in languages which haven't been edited yet. If the Text cannot be found for the language ID given, the first language encountered is returned. If no record is found for the given key, creates a new object with a warning message and returns it. Note that in the last case, neither the module nor the text ID are set and remain at their default (null) value. You should set them to the desired values before storing the object.
Parameters
- $key : int
-
The key, must not be empty
- $lang_id : int
-
The language ID
Tags
Return values
Text —The object on success, false otherwise
getIdArrayBySearch()
OBSOLETE Returns an array of Text and language IDs of records matching the search pattern and optional section, key, language, and text IDs
public
static getIdArrayBySearch(string $pattern[, int $section = false ][, string $key = false ][, int $lang_id = false ][, int $ids = false ]) : array<string|int, mixed>
Note that you have to add "%" signs to the pattern if you want the match to be open ended. The array returned looks like this: array( id => array( 0 => Language ID, ... 1 => more language IDs ... ), ... more ids ... )
Parameters
- $pattern : string
-
The search pattern
- $section : int = false
-
The optional section, or false
- $key : string = false
-
The optional key, or false
- $lang_id : int = false
-
The optional language ID, or false
- $ids : int = false
-
The optional comma separated list of Text IDs, or false
Tags
Return values
array<string|int, mixed> —The array of Text and language IDs on success, false otherwise
getSqlSnippets()
Returns an array of SQL snippets to include the selected Text records in the query.
public
static getSqlSnippets(string $field_id, int $lang_id, string $section, mixed $keys) : array<string|int, mixed>
Provide a single value for the $key, or an array.
If you use an array, the array keys MUST contain distinct alias names
for the respective text keys.
The array returned looks as follows:
array(
'alias' => The array of Text field aliases:
array(key => field name alias, ...)
Use the alias to access the text content in the resulting
recordset, or if you need to sort the result by that
column.
'field' => Field snippet to be included in the SQL SELECT, uses
aliased field names for the id ("text_#id") and text
("text#text") fields.
No leading comma is included!
'join' => SQL JOIN snippet, the LEFT JOIN with the core_text table
and conditions
)
The '#' is replaced by a unique integer number.
The '*' may be any descriptive part of the name that disambiguates
multiple foreign keys in a single table, like 'name', or 'value'.
Note that the $lang_id parameter is mandatory and MUST NOT be
emtpy. $alias may be null (or omitted), in which case it is ignored,
and the default form "text
Parameters
- $field_id : string
-
The name of the text ID foreign key field. Note that this is not part of the SELECTed fields, but used in the JOIN only.
- $lang_id : int
-
The language ID
- $section : string
-
The section
- $keys : mixed
-
A single key, or an array thereof
Tags
Return values
array<string|int, mixed> —The array with SQL code parts
id()
Get the ID
public
id() : int
Tags
Return values
int —The Text ID
insert()
Insert this object into the database.
public
insert() : bool
Fails if either the ID or lang_id is empty.
Tags
Return values
bool —True on success, false otherwise
key()
Returns the key
public
key() : string
Tags
Return values
string —The key
lang_id()
Returns the language ID
public
lang_id([int $lang_id = null ]) : int
Optionally sets the language ID. Returns null on invalid values.
Parameters
- $lang_id : int = null
-
The optional language ID
Tags
Return values
int —The language ID, or null
makeClone()
Clone the object
public
makeClone() : mixed
Note that this does NOT create a copy in any way, but simply clears the Text ID. Upon storing this Text, a new ID is created.
Tags
markDifferentLanguage()
If the language ID given is different from the language of this Text object, the content may be marked here.
public
markDifferentLanguage() : mixed
Customize as desired.
Tags
nextId()
OBSOLETE Returns the next available ID
public
static nextId() : int
Tags
Return values
int —The next ID on success, false otherwise
recordExists()
Test whether a record of this is already present in the database.
public
recordExists() : bool
Tags
Return values
bool —True if the record exists, false otherwise
replace()
Replace or insert the Text record
public
static replace(int $id, int $lang_id, int $section, string $key, string $strText) : int
If the Text ID is specified, looks for the same record in the given language, or any other language if that is not found. If no record to update is found, a new one is created. The parameters are applied, and the Text is then stored.
Parameters
- $id : int
-
The Text ID
- $lang_id : int
-
The language ID
- $section : int
-
The section
- $key : string
-
The key
- $strText : string
-
The text
Tags
Return values
int —The Text ID on success, null otherwise
section()
Returns the section
public
section() : string
Tags
Return values
string —The section
store()
Stores the object in the database.
public
store() : bool
Either updates or inserts the object, depending on the outcome of the call to . Calling is necessary, as there may be no record in the current language, although the Text ID is valid.
Tags
Return values
bool —True on success, false otherwise
update()
Update this object in the database.
public
update() : bool
Tags
Return values
bool —True on success, false otherwise