more docs

TODO.txt

@@ -1,10 +1,9 @@
 # @TODO
 
 ## 5.0
-- fix template invalidation when migrating to 5.0
+- fix template invalidation when migrating to 5.0. https://github.com/smarty-php/smarty/pull/852#issuecomment-1412728329
 - document addExtension
 - review docs
-- maybe add nullsafe operator ?? as launching feature?
 
 ## CI-building optimization
 - compiled & cached templates should not contain references to local filesystem paths. Add an optional rootpath param

docs/api/variables/objects.md

@@ -0,0 +1,106 @@
+# Objects
+
+Smarty allows access to PHP [objects](https://www.php.net/object) through
+the templates.
+
+> **Note**
+>
+> When you assign/register objects to templates, be sure that all
+> properties and methods accessed from the template are for presentation
+> purposes only. It is very easy to inject application logic through
+> objects, and this leads to poor designs that are difficult to manage.
+> See the Best Practices section of the Smarty website.
+
+There are two ways to access them.
+
+## Assign the object
+You can assign objects to a template and access them much like any other assigned variable.
+
+Example:
+```php
+<?php
+// the object
+
+class My_Object {
+    public function meth1($params, $smarty_obj) {
+        return 'this is my meth1';
+    }
+}
+
+// We can also assign objects. assign_by_ref when possible.
+$smarty->assign('myobj', new My_Object());
+
+$smarty->display('index.tpl');
+```
+
+And here's how to access your object in `index.tpl`:
+
+```smarty
+{$myobj->meth1('foo',$bar)}
+```
+
+
+
+## Register the object
+Registerd objects use a different template syntax. Also, a registered object 
+can be restricted to certain methods or
+properties. However, **a registered object cannot be looped over or
+assigned in arrays of objects**, etc.
+
+If security is enabled, no private methods or functions can be accessed
+(beginning with '_'). If a method and property of the same name exist,
+the method will be used.
+
+You can restrict the methods and properties that can be accessed by
+listing them in an array as the third registration parameter.
+
+By default, parameters passed to objects through the templates are
+passed the same way [custom functions](../../designers/language-custom-functions/index.md) get
+them. An associative array is passed as the first parameter, and the
+smarty object as the second. If you want the parameters passed one at a
+time for each argument like traditional object parameter passing, set
+the fourth registration parameter to FALSE.
+
+The optional fifth parameter has only effect with `format` being TRUE
+and contains a list of methods that should be treated as blocks. That
+means these methods have a closing tag in the template
+(`{foobar->meth2}...{/foobar->meth2}`) and the parameters to the methods
+have the same synopsis as the parameters for
+[`block tags`](../extending/block-tags.md): They get the four
+parameters `$params`, `$content`, `$smarty` and `&$repeat` and they also
+behave like block tags.
+
+```php
+<?php
+// the object
+
+class My_Object {
+    function meth1($params, $smarty_obj) {
+        return 'this is my meth1';
+    }
+}
+
+$myobj = new My_Object;
+
+// registering the object
+$smarty->registerObject('foobar', $myobj);
+
+// if we want to restrict access to certain methods or properties, list them
+$smarty->registerObject('foobar', $myobj, array('meth1','meth2','prop1'));
+
+// if you want to use the traditional object parameter format, pass a boolean of false
+$smarty->registerObject('foobar', $myobj, null, false);
+
+$smarty->display('index.tpl');
+```
+
+And here's how to access your objects in `index.tpl`:
+
+```smarty
+{* access our registered object *}
+{foobar->meth1 p1='foo' p2=$bar}
+
+{* you can also assign the output *}
+{foobar->meth1 p1='foo' p2=$bar assign='output'}
+the output was {$output}
+```

docs/api/variables/static-class-methods.md

@@ -0,0 +1,39 @@
+# Static Classes
+
+You can directly access static classes. The syntax is roughly the same as in
+PHP.
+
+> **Note**
+>
+> Direct access to PHP classes is not recommended. This ties the
+> underlying application code structure directly to the presentation,
+> and also complicates template syntax. It is recommended to register
+> plugins which insulate templates from PHP classes/objects. Use at your
+> own discretion.
+
+## Examples
+
+**class constant BAR**
+```smarty
+{assign var=foo value=myclass::BAR}
+```
+
+**method result**
+```smarty
+{assign var=foo value=myclass::method()} 
+```
+
+**method chaining**
+```smarty
+{assign var=foo value=myclass::method1()->method2}
+```
+
+**property bar of class myclass**
+```smarty
+{assign var=foo value=myclass::$bar} 
+```
+
+**using Smarty variable bar as class name**
+```smarty
+{assign var=foo value=$bar::method}
+```

docs/api/variables/streams.md

@@ -0,0 +1,13 @@
+# Streams
+
+You can also use streams to call variables. *{$foo:bar}* will use the
+*foo://bar* stream to get the template variable.
+
+Using a PHP stream for a template variable resource from within a
+template.
+
+```smarty
+{$foo:bar}
+```
+
+See also [`Template Resources`](../resources.md)

docs/programmers/advanced-features/advanced-features-objects.md

@@ -1,95 +0,0 @@
-# Objects
-
-Smarty allows access to PHP [objects](https://www.php.net/object) through
-the templates.
-
-> **Note**
->
-> When you assign/register objects to templates, be sure that all
-> properties and methods accessed from the template are for presentation
-> purposes only. It is very easy to inject application logic through
-> objects, and this leads to poor designs that are difficult to manage.
-> See the Best Practices section of the Smarty website.
-
-There are two ways to access them.
-
--   One way is to [register objects](../api-functions/api-register-object.md) to the
-    template, then use access them via syntax similar to [custom
-    functions](../../designers/language-custom-functions/index.md).
-
--   The other way is to [`assign()`](../api-functions/api-assign.md) objects to the
-    templates and access them much like any other assigned variable.
-
-The first method has a much nicer template syntax. It is also more
-secure, as a registered object can be restricted to certain methods or
-properties. However, **a registered object cannot be looped over or
-assigned in arrays of objects**, etc. The method you choose will be
-determined by your needs, but use the first method whenever possible to
-keep template syntax to a minimum.
-
-If security is enabled, no private methods or functions can be accessed
-(beginning with '_'). If a method and property of the same name exist,
-the method will be used.
-
-You can restrict the methods and properties that can be accessed by
-listing them in an array as the third registration parameter.
-
-By default, parameters passed to objects through the templates are
-passed the same way [custom functions](../../designers/language-custom-functions/index.md) get
-them. An associative array is passed as the first parameter, and the
-smarty object as the second. If you want the parameters passed one at a
-time for each argument like traditional object parameter passing, set
-the fourth registration parameter to FALSE.
-
-The optional fifth parameter has only effect with `format` being TRUE
-and contains a list of methods that should be treated as blocks. That
-means these methods have a closing tag in the template
-(`{foobar->meth2}...{/foobar->meth2}`) and the parameters to the methods
-have the same synopsis as the parameters for
-[`block-function-plugins`](../plugins/plugins-block-functions.md): They get the four
-parameters `$params`, `$content`, `$smarty` and `&$repeat` and they also
-behave like block-function-plugins.
-
-```php
-<?php
-// the object
-
-class My_Object {
-    function meth1($params, $smarty_obj) {
-        return 'this is my meth1';
-    }
-}
-
-$myobj = new My_Object;
-
-// registering the object (will be by reference)
-$smarty->registerObject('foobar',$myobj);
-
-// if we want to restrict access to certain methods or properties, list them
-$smarty->registerObject('foobar',$myobj,array('meth1','meth2','prop1'));
-
-// if you want to use the traditional object parameter format, pass a boolean of false
-$smarty->registerObject('foobar',$myobj,null,false);
-
-// We can also assign objects. assign_by_ref when possible.
-$smarty->assign_by_ref('myobj', $myobj);
-
-$smarty->display('index.tpl');
-```
-
-And here's how to access your objects in `index.tpl`:
-
-```smarty
-{* access our registered object *}
-{foobar->meth1 p1='foo' p2=$bar}
-
-{* you can also assign the output *}
-{foobar->meth1 p1='foo' p2=$bar assign='output'}
-the output was {$output}
-
-{* access our assigned object *}
-{$myobj->meth1('foo',$bar)}
-```
-      
-See also [`registerObject()`](../api-functions/api-register-object.md) and
-[`assign()`](../api-functions/api-assign.md).

docs/programmers/advanced-features/advanced-features-static-classes.md

@@ -1,39 +0,0 @@
-# Static Classes
-
-You can directly access static classes. The syntax is roughly the same as in
-PHP.
-
-> **Note**
->
-> Direct access to PHP classes is not recommended. This ties the
-> underlying application code structure directly to the presentation,
-> and also complicates template syntax. It is recommended to register
-> plugins which insulate templates from PHP classes/objects. Use at your
-> own discretion. See the Best Practices section of the Smarty website.
-
-## Examples
-
-**class constant BAR** 
-```smarty
-{assign var=foo value=myclass::BAR}
-```
-
-**method result**
-```smarty
-{assign var=foo value=myclass::method()} 
-```
-
-**method chaining**
-```smarty
-{assign var=foo value=myclass::method1()->method2}
-```
-
-**property bar of class myclass**
-```smarty
-{assign var=foo value=myclass::$bar} 
-```
-
-**using Smarty variable bar as class name**
-```smarty
-{assign var=foo value=$bar::method}
-```

docs/programmers/advanced-features/advanced-features-streams.md

@@ -1,13 +0,0 @@
-# Streams
-
-You can also use streams to call variables. *{$foo:bar}* will use the
-*foo://bar* stream to get the template variable.
-
-Using a PHP stream for a template variable resource from within a
-template.
-
-```smarty
-{$foo:bar}
-```
-
-See also [`Template Resources`](../resources.md)