diff --git a/CHANGELOG.md b/CHANGELOG.md index 1dd1486..29655b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,11 +4,15 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) -## [3.12.3] - 2021-12-03 +## [3.13.0] - 2022-02-07 ### Enhancements -- PHP 8.1 compatibility +- Compatibility with PHP 8.1 + +### Added + +- New methods SetVarRefItem() and GetVarRefItem() : uniformize and ensure compatibility to set a VarRef items. ## [3.12.2] - 2020-11-03 diff --git a/tbs_class.php b/tbs_class.php index db05682..55250de 100644 --- a/tbs_class.php +++ b/tbs_class.php @@ -3,8 +3,8 @@ * * TinyButStrong - Template Engine for Pro and Beginners * - * @version 3.12.3-beta-1 for PHP 5, 7, 8 - * @date 2021-12-03 + * @version 3.13.0 for PHP 5, 7, 8 + * @date 2022-02-07 * @link http://www.tinybutstrong.com Web site * @author http://www.tinybutstrong.com/onlyyou.html * @license http://opensource.org/licenses/LGPL-3.0 LGPL-3.0 @@ -655,7 +655,7 @@ class clsTinyButStrong { public $ExtendedMethods = array(); public $ErrCount = 0; // Undocumented (can change at any version) -public $Version = '3.12.3-beta-1'; +public $Version = '3.13.0'; public $Charset = ''; public $TurboBlock = true; public $VarPrefix = ''; @@ -822,6 +822,66 @@ public function ResetVarRef($ToGlobal) { } +/** + * Get an item value from VarRef. + * Ensure the compatibility with PHP 8.1 if VarRef is set to Global. + * + * @param string $key The item key. + * @param mixed $default The default value. + * + * @return mixed + */ +public function GetVarRefItem($key, $default) { + + if (is_null($this->VarRef)) { + + if (array_key_exists($key, $GLOBALS)) { + return $GLOBALS[$key]; + } else { + return $default; + } + + } else { + + if (array_key_exists($key, $this->VarRef)) { + return $this->VarRef[$key]; + } else { + return $default; + } + + } + +} + +/** + * Set an item value to VarRef. + * Ensure the compatibility with PHP 8.1 if VarRef is set to Global. + * + * @param string $key The item key. + * @param mixed $value The item value. Use NULL in order to delete the item. + */ +public function SetVarRefItem($key, $value) { + + if (is_null($this->VarRef)) { + + if (is_null($value)) { + unset($GLOBALS[$key]); + } else { + $GLOBALS[$key] = $value; + } + + } else { + + if (is_null($value)) { + unset($this->VarRef[$key]); + } else { + $this->VarRef[$key] = $value; + } + + } + +} + // Public methods public function LoadTemplate($File,$Charset='') { if ($File==='') { diff --git a/tbs_us_manual.htm b/tbs_us_manual.htm index 5819b29..3d55719 100644 --- a/tbs_us_manual.htm +++ b/tbs_us_manual.htm @@ -169,12 +169,15 @@ border: 1px dotted #6699CC; } .note { - background-color: #D9FFD9; + background-color: #D9FFD9; /* green */ border: thin solid #00EC9F; padding: 2px; margin-top: 3px; margin-left: 20px; } +.warning { + background-color: #f4dfdf; /* light red */ +} --> @@ -188,13 +191,13 @@ Date: - 2021-08-27 + 2022-02-07

TinyButStrong Documentation

-
version 3.12
+
version 3.13
Template Engine for Pro and Beginners
PHP 8
PHP 7
@@ -270,7 +273,19 @@

Table of Contents:

        method GetOption() - get TBS options + get TBS options + + +         method ResetVarRef() + reset the VarRef property + + +         method GetVarRefItem() + get an item in the VarRef property + + +         method SetVarRefItem() + set an item in the VarRef property         method ReplaceFields() @@ -1322,6 +1337,45 @@

Method GetOption():

Versioning: methods GetOption() is supported since TBS version 3.8.0.

+

Method ResetVarRef():

+
+

Reset the VarRef property.

+

By default, VarRef refers to the PHP global variable $GLOBALS.

+

Syntax: mixed $TBS->ResetVarRef(boolean $to_globals)

+ + + + + + + + + +
ArgumentDescription
$to_globalsIndicates if the property VarRef refers to $GLOBALS or is a new empty array. +
- if $to_globals is true then VarRef refers to $GLOBALS. +
- if $to_globals is false then VarRef is a new empty array.
+
+ +

Method GetVarRefItem():

+
+

Get an item value in the VarRef property.

+

This function uniformizes the way to get a VarRef item, whether VarRef refers to $GLOBALS or not.

+

Syntax: mixed $TBS->GetVarRefItem(string $key, mixed $default = null)

+

If VarRef if a dedicated array, then this function is the same as doing $TBS->VarRef[$key] ?? $default;

+

Versioning: methods GetVarRefItem() is supported since TBS version 3.13.0.

+
+ +

Method SetVarRefItem():

+
+

Set an item value in the VarRef property.

+

This function uniformizes the way to set a VarRef item, whether VarRef refers to $GLOBALS or not.

+

Syntax: mixed $TBS->SetVarRefItem(string $key, mixed $value)

+

If VarRef if a dedicated array, then this function is the same as doing $TBS->VarRef[$key] = $value;

+

Versioning: methods SetVarRefItem() is supported since TBS version 3.13.0.

+
+ + +

Method ReplaceFields():

Replace a set of simple TBS fields in the template with new definitions prepared at the PHP side. Note than this function does not merges any field ; it only replaces the definition of fields.

@@ -1388,7 +1442,7 @@

Method GetAttValue():

  • null if the TBS field is not found or if it has no parameter att,
  • false if the target XML/HTML element is not found or if the asked attribute is not found.
    • -

    Versioning: methods GetAttValue() is supported since TBS version 3.11.0.

    +

    Versioning: methods GetAttValue() is supported since TBS version 3.11.0.

    Method PlugIn():

    @@ -1416,29 +1470,56 @@

    Installing a plug-in:

    Versioning: the method PlugIn() is supported since TBS version 3.0.

    +

    Property VarRef:

    -

    This property enables you to set the scope of variables availables for automatic fields ([onload], [onshow] and [var]).

    -

    By default, VarRef is a reference to the $GLOBALS PHP variable, which means all global PHP variables are available for automatic field.

    +

    Property VarRef is the array of the items that will be merged with automatic fields ([onload], [onshow] and [var]).

    Syntax: array $TBS->VarRef

    +

    + By default $TBS->VarRef refers + to the special $GLOBALS variable of PHP. + This is for compatibility reasons, but it is recommended to use another array instead (see below). +

    +

    You can set $TBS->VarRef to be a new empty array using the method $TBS->ResetVarRef(false);

    +

    You can also set $TBS->VarRef to be a reference to your own array : $TBS->VarRef =& $my_array;

    + +
    + Warning +
    As of TBS version 3.13.0, is not possible to access directly to the VarRef items when the property refers to $GLOBALS. This is because of the PHP restriction on $GLOBALS that occurs with PHP 8.1. +
    In order to ensure the compatibility to any situation, you can manage the items of VarRef using the methods $TBS->SetVarRefItem() and $TBS->GetVarRefItem(). +
    +

    Notes:

    -

    Example for setting VarRef to global variables :

    -
    $TBS->VarRef = &$GLOBALS;
+	
+	
    Example when VarRef is a custom array (recommended): 
    
+	
    $TBS->ResetVarRef(false); // VarRef is now a new empty array
+$TBS->VarRef['my_item'] = "my value";
+$TBS->SetVarRefItem('my_item', "my value"); // same as above but ensure the compatibility with any situation
    
 
-which is the same as:
+	
    Example when VarRef is attached to $GLOBALS (by default): 
    
+	
    $TBS->VarRef['my_item'] = "my value"; // this will raise an error as of TBS version 3.13.0
+$GLOBALS['my_item'] = "my value";
+$TBS->SetVarRefItem('my_item', "my value"); // same as above but ensure the compatibility with any situation
    
+
+	
    
+		
    Versioning:
    
+		
      
+			
    • Property VarRef is supported since TBS version 3.8. Before this version, the scope of automatic fields was PHP global variables.
      • 
+			
    • 
+			  Since TBS version 3.13.0, you cannot directly use the property $TBS->VarRef when it refers to $GLOBAL. This is because of a PHP 8.1 restriction. Use SetVarRefItem() and GetVarRefItem() instead.
+			  
      Before TBS version 3.13.0, property $TBS->VarRef used to be by default a PHP reference the $GLOBAL variable.
+			
      • 
+	
    
+	
+
    + + +

    Property Assigned:

    -$TBS->ResetVarRef(true); - -

    Example for setting VarRef to a custome scope of variables:

    -
    $TBS->ResetVarRef(false); // VarRef is now a new empty array
-$TBS->VarRef['x'] = 'This is value X';
    -

    Versioning: property VarRef is supported since TBS version 3.8. Before this version, the scope of automatic fields was PHP global variables.

    - -

    Property Assigned:

    Enables you to define information for a subsequent merging which can be automatic or manual.

    Syntax: array $TBS->Assigned