Moodle PHP Documentation 4.4
Moodle 4.4.1 (Build: 20240610) (db07c09afc5)
lang_string Class Reference

The lang_string class. More...

Public Member Functions

 __construct ($identifier, $component='', $a=null, $lang=null)
 Constructs a lang_string object.
 
 __sleep ()
 Prepares the lang_string for sleep and stores only the forcedstring and string properties... the string cannot be regenerated so we need to ensure it is generated for this.
 
 __toString ()
 Magic __toString method for printing a string.
 
 get_component ()
 Returns the component.
 
 get_identifier ()
 Returns the identifier.
 
 out ($lang=null)
 Returns the string.
 

Static Public Member Functions

static __set_state (array $array)
 Magic __set_state method used for var_export.
 

Protected Member Functions

 get_string ()
 Processes the string.
 

Protected Attributes

array stdClass $a = null
 Any arguments required for the string.
 
string $component = ''
 The strings component.
 
bool $forcedstring = false
 A special boolean.
 
string $identifier
 The strings identifier.
 
string $lang = null
 The language to use when processing the string.
 
string $string = null
 The processed string (once processed)
 

Detailed Description

The lang_string class.

This special class is used to create an object representation of a string request. It is special because processing doesn't occur until the object is first used. The class was created especially to aid performance in areas where strings were required to be generated but were not necessarily used. As an example the admin tree when generated uses over 1500 strings, of which normally only 1/3 are ever actually printed at any time. The performance advantage is achieved by not actually processing strings that arn't being used, as such reducing the processing required for the page.

How to use the lang_string class? There are two methods of using the lang_string class, first through the forth argument of the get_string function, and secondly directly. The following are examples of both.

  1. Through get_string calls e.g. $string = get_string($identifier, $component, $a, true); $string = get_string('yes', 'moodle', null, true);
  2. Direct instantiation $string = new lang_string($identifier, $component, $a, $lang); $string = new lang_string('yes');

How do I use a lang_string object? The lang_string object makes use of a magic __toString method so that you are able to use the object exactly as you would use a string in most cases. This means you are able to collect it into a variable and then directly echo it, or concatenate it into another string, or similar. The other thing you can do is manually get the string by calling the lang_strings out method e.g. $string = new lang_string('yes'); $string->out(); Also worth noting is that the out method can take one argument, $lang which allows the developer to change the language on the fly.

When should I use a lang_string object? The lang_string object is designed to be used in any situation where a string may not be needed, but needs to be generated. The admin tree is a good example of where lang_string objects should be used. A more practical example would be any class that requries strings that may not be printed (after all classes get renderer by renderers and who knows what they will do ;))

When should I not use a lang_string object? Don't use lang_strings when you are going to use a string immediately. There is no need as it will be processed immediately and there will be no advantage, and in fact perhaps a negative hit as a class has to be instantiated for a lang_string object, however get_string won't require that.

Limitations:

  1. You cannot use a lang_string object as an array offset. Doing so will result in PHP throwing an error. (You can use it as an object property!)
License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

lang_string::__construct ( $identifier,
$component = '',
$a = null,
$lang = null )

Constructs a lang_string object.

This function should do as little processing as possible to ensure the best performance for strings that won't be used.

Parameters
string$identifierThe strings identifier
string$componentThe strings component
stdClass | array | mixed$aAny arguments the string requires
string$langThe language to use when processing the string.
Exceptions
coding_exception

Member Function Documentation

◆ __set_state()

static lang_string::__set_state ( array $array)
static

Magic __set_state method used for var_export.

Parameters
array$array
Return values
self

◆ __sleep()

lang_string::__sleep ( )

Prepares the lang_string for sleep and stores only the forcedstring and string properties... the string cannot be regenerated so we need to ensure it is generated for this.

Return values
array

◆ __toString()

lang_string::__toString ( )

Magic __toString method for printing a string.

Return values
string

◆ get_component()

lang_string::get_component ( )

Returns the component.

Return values
string

◆ get_identifier()

lang_string::get_identifier ( )

Returns the identifier.

Return values
string

◆ get_string()

lang_string::get_string ( )
protected

Processes the string.

This function actually processes the string, stores it in the string property and then returns it. You will notice that this function is VERY similar to the get_string method. That is because it is pretty much doing the same thing. However as this function is an upgrade it isn't as tolerant to backwards compatibility.

Return values
string
Exceptions
coding_exception

◆ out()

lang_string::out ( $lang = null)

Returns the string.

Parameters
string$langThe langauge to use when processing the string
Return values
string

Member Data Documentation

◆ $a

array stdClass lang_string::$a = null
protected

Any arguments required for the string.

Default null

◆ $component

string lang_string::$component = ''
protected

The strings component.

Default ''

◆ $forcedstring

bool lang_string::$forcedstring = false
protected

A special boolean.

If set to true then the object has been woken up and cannot be regenerated. If this is set then $this->string MUST be used.

◆ $lang

string lang_string::$lang = null
protected

The language to use when processing the string.

Default null


The documentation for this class was generated from the following file: