trim and improve code comments

class.TplBlock.php

@@ -3,6 +3,12 @@ class InvalidTemplateException extends UnexpectedValueException{
 
 }
 class TplBlock {
+/*
+* Class TplBlog
+* By gnieark https://blog-du-grouik.tinad.fr 2018
+* Licenced under the GNU General Public License V3
+* https://www.gnu.org/licenses/gpl-3.0.fr.html
+*/
   const blockStartStart = '<!-- BEGIN ';
   const blockStartEnd = ' -->';
   const blockEndStart = '<!-- END ';
@@ -18,6 +24,7 @@ class TplBlock {
   /*
   * Initialise TplBlock
   * Input object name
+  * Can be empty only for the top one block
   */
 
   public function __construct($name = NULL){
@@ -33,6 +40,10 @@ class TplBlock {
     $this->vars = array_merge($this->vars,$vars);
   }
 
+  /*
+  * add_sub_block
+  * Input: a TplBlock object.
+  */
   public function add_sub_block(TplBlock $bloc){
     if(is_null($bloc->name) || empty($bloc->name)){
       throw new InvalidTemplateException("A sub tpl bloc can't have an empty name");
@@ -43,8 +54,14 @@ class TplBlock {
 
   /*
   * Shake template and input vars and returns the text
+  * Input: 
+  *   $str String containing the template to parse
+  *   $subBlocsPath String optional, for this class internal use. The path like "bloc.subbloc"
+  *   $trim Boolean
+  *       if true(default), the potentials Carriages returns beginning 
+  *       and ending the bloc are deleted
   */
-  public function apply_tpl_str($str,$subBlocsPath = ""){
+  public function apply_tpl_str($str,$subBlocsPath = "", $trim = true){
 
     //replace all simple vars
     $prefix = (empty($subBlocsPath)? "" : $subBlocsPath.".");
@@ -63,24 +80,33 @@ class TplBlock {
           '(.*?)'.
           self::blockEndStart . preg_quote($prefix . $blocName). self::blockEndEnd. 
         '/is',
-        function($m) use($blocName,$blocsArr,$prefix) {
+        function($m) use($blocName,$blocsArr,$prefix, $trim) {
+          echo gettype($trim).$trim;
           $out = "";
           foreach($blocsArr as $bloc){
-            $out.=$bloc->apply_tpl_str( $m[1] , $prefix . $blocName );
+            $out.=$bloc->apply_tpl_str( $m[1] , $prefix . $blocName , $trim );
           }
           return $out;
         }
         ,$str
       );
     }
-    return $str;
+
+    if($trim){
+      return trim($str,"\n");
+    }else{
+      return $str;
+    }
   }
 
-  public function apply_tpl_file($file){
+  /*
+  * load a file, and pass his content to apply_tpl_str function.
+  */
+  public function apply_tpl_file($file, $trim = true){
     if(!$tplStr = file_get_contents($file)){
       throw new InvalidTemplateException("Cannot read given file ".$file);
       return false;
     }
-    return $this->apply_tpl_str($tplStr);
+    return $this->apply_tpl_str($tplStr, null, $trim);
   }
 }

test-TplBlock/test.php

@@ -44,4 +44,4 @@ for ($i = 2; $i < 121; $i++){
 
 
 
-echo $tpl->apply_tpl_file("sample.txt");
+echo $tpl->apply_tpl_file("sample.txt",true);