Add option to return null instead throwing an exception when the key …

…doesn't exist

PhpEcho.php

@@ -146,6 +146,10 @@ class PhpEcho
      * @var bool
      */
     private static bool $std_helpers_injected = false;
+    /**
+     * @var bool
+     */
+    private static bool $null_if_not_exist = false;
 
     //region MAGIC METHODS
     /**
@@ -455,6 +459,14 @@ public function unsetAnyParam(string $name): void
         }
     }
 
+    /**
+     * @param bool $p
+     */
+    public static function setNullIfNotExists(bool $p): void
+    {
+        self::$null_if_not_exist = $p;
+    }
+
     /**
      * Generate a unique execution id based on random_bytes()
      * Always start with a letter
@@ -541,18 +553,18 @@ private function getOffsetRawValue($offset): mixed
                 if (isset($data[$k])) {
                     $data = $data[$k];
                 } else {
-                    throw new InvalidArgumentException("unknown.offset.{$k}");
+                    return self::$null_if_not_exist ? null : throw new InvalidArgumentException("unknown.offset.{$k}");
                 }
             }
             if (array_key_exists($last, $data)) {
                 return $data[$last];
             } else {
-                throw new InvalidArgumentException("unknown.offset.{$last}");
+                return self::$null_if_not_exist ? null : throw new InvalidArgumentException("unknown.offset.{$last}");
             }
         } elseif (isset($this->vars[$offset])) {
             return $this->vars[$offset];
         } else {
-            throw new InvalidArgumentException("unknown.offset.{$offset}");
+            return self::$null_if_not_exist ? null : throw new InvalidArgumentException("unknown.offset.{$offset}");
         }
     }
 

README.md

@@ -1,6 +1,6 @@
 # **PhpEcho**
 
-`2023-03-19` `PHP 8.0+` `v.5.3.0`
+`2023-04-09` `PHP 8.0+` `v.5.3.1`
 
 ## **A native PHP template engine : One class to rule them all**
 ## **VERSION 5.X IS ONLY FOR PHP 8 AND ABOVE**
@@ -35,13 +35,18 @@ The class will manage :
 ```bash
 composer require rawsrc/phpecho
 ```
+**Changelog v5.3.1:**<br>
+1. Add option to return natively `null` when a key doesn't exist instead of throwing an `Exception`
+By default this option is not activated. To activate, use: `PhpEcho::setNullIfNotExist(true);`; to deactivate, 
+use: `PhpEcho::setNullIfNotExist(false);` 
 
 **Changelog v5.3.0:**<br>
 1. Code optimization and improvement of the parameters management
 2. The method `hasGlobalParam(string $name)` is now `static`
 3. You can now define the seek order to get the first value either 
 from the `local` or `global` context using `getAnyParam(string $name, string $seek_order = 'local'): mixed`
-4. It's possible to unset at once a parameter from the local and the global context using `unsetAnyParam(string $name): void`
+4. It's possible to set at once a parameter into the local and global context using `setAnyParam(string $name, mixed $value)`
+4. It's possible to unset at once a parameter from the local and the global context using `unsetAnyParam(string $name)`<br>
 Test files are updated
 
 **Changelog v5.2.1:**<br>
@@ -169,9 +174,7 @@ PhpEcho::setTemplateDirRoot(__DIR__.DIRECTORY_SEPARATOR.'View'.DIRECTORY_SEPARAT
 ```
 Then you will code for example the homepage `page/homepage.php` based on `layout/main.php` like that:
 ```php
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 use rawsrc\PhpEcho\PhpEcho;
 
@@ -299,9 +302,7 @@ echo new PhpEcho('layout main.php', [
 ```
 This is also equivalent:<br>
 ```php
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 use rawsrc\PhpEcho\PhpEcho;
 

stdPhpEchoHelpers.php

@@ -1,6 +1,4 @@
-<?php
-
-declare(strict_types=1);
+<?php declare(strict_types=1);
 
 use rawsrc\PhpEcho\PhpEcho;
 

tests/core.php

@@ -26,17 +26,35 @@
 );
 $pilot->assertException(InvalidArgumentException::class);
 
-$block['foo bar'] = 'xyz';
+
+PhpEcho::setNullIfNotExists(true);
 $pilot->run(
     id: 'core_003',
+    test: fn() => $block['abc'],
+    description: 'after setting setNullIfNotExists to true try to extract a undefined key from a block'
+);
+$pilot->assertEqual(null);
+
+PhpEcho::setNullIfNotExists(false);
+$pilot->run(
+    id: 'core_004',
+    test: fn() => $block['abc'],
+    description: 'after setting setNullIfNotExists to false try to extract a undefined key from a block'
+);
+$pilot->assertException(InvalidArgumentException::class);
+
+
+$block['foo bar'] = 'xyz';
+$pilot->run(
+    id: 'core_005',
     test: fn() => $block['foo'],
     description: 'using space notation by default, check auto creation of sub-arrays'
 );
 $pilot->assertIsArray();
 $pilot->assertEqual(['bar' => 'xyz']);
 
 $pilot->run(
-    id: 'core_004',
+    id: 'core_006',
     test: fn() => $block['foo bar'],
     description: 'using space notation by default, check auto expanding into sub-array'
 );
@@ -46,7 +64,7 @@
 PhpEcho::setUseSpaceNotation(false);
 $block['foo bar'] = 'xxx';
 $pilot->run(
-    id: 'core_005',
+    id: 'core_007',
     test: fn() => $block['foo bar'],
     description: 'space notation disabled, check if key with space is preserved'
 );
@@ -55,7 +73,7 @@
 
 $block['klm'] = 12;
 $pilot->run(
-    id: 'core_006',
+    id: 'core_008',
     test: fn() => $block['klm'],
     description: 'for non string values, check data type preservation (int)'
 );
@@ -64,7 +82,7 @@
 
 $block['klm'] = true;
 $pilot->run(
-    id: 'core_007',
+    id: 'core_009',
     test: fn() => $block['klm'],
     description: 'for non string values, check data type preservation (bool)'
 );
@@ -73,7 +91,7 @@
 
 $block['klm'] = new stdClass();
 $pilot->run(
-    id: 'core_008',
+    id: 'core_010',
     test: fn() => $block['klm'],
     description: 'for non string values, check data type preservation (object without __toString)'
 );
@@ -89,7 +107,7 @@ public function __toString(): string
 
 $block['klm'] = new Foo();
 $pilot->run(
-    id: 'core_009',
+    id: 'core_011',
     test: fn() => $block['klm'],
     description: 'for non string values, object with __toString is assimilated to a string and escaped'
 );

tests/tests.php

@@ -15,7 +15,7 @@
 
 use Exacodis\Pilot;
 
-$pilot = new Pilot('PhpEcho - A native PHP template engine - v.5.3.0');
+$pilot = new Pilot('PhpEcho - A native PHP template engine - v.5.3.1');
 $pilot->injectStandardHelpers();
 
 include 'filepath.php';