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!)

Copyright

2011 Sam Hemelryk

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	$identifier	The strings identifier
string	$component	The strings component
stdClass | array | mixed	$a	Any arguments the string requires
string	$lang	The 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

$lang

The 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:

• lib/moodlelib.php