1.12. Upgrading

1.12.1. 1.x to 2.x

Upgrading from Qiq 1.x to 2.x is straightforward but may be time consuming. Assigned Variables

Magic __get(), __set(), etc. access to assigned variables has been removed.

This means template files no longer use $this->var for assigned variables.

Instead, they now use $var (without the $this-> prefix). This is in support of static analysis in template files.

If you need to modify the assigned variables directly, use &refData() to get a reference to the array of assigned data. Modifications to this array will be honored on the next call to render(). Sections and Blocks

Sections have been removed entirely in favor of blocks. Instead of setSection(), preSection(), addSection(), and getSection(), use setBlock(), parentBlock(), and getBlock(). Please see the blocks documentation for more information. Helpers

The HelperLocator has been removed entirely in favor of Helpers and a Container. If you have custom helpers, you will need to following the custom helpers documentation to make them available in your templates.

The tag-related helpers no longer use arrays for attributes; instead, they use named parameters. For example, an input text field helper in 1.x would have been called like this:

{{= textField ([
  'name' => 'foo',
  'value' => 'foo text',
  'id' => 'foo-id',
]) }}

In 2.x, you call it like this; note that the array and its keys are replaced by named parameters:

{{= textField (
  name: 'foo',
  value: 'foo text',
  id: 'foo-id',
) }}

As a transitional aid, you may use the spread (...) operator to expand the array into named parameters:

{{= textField (...[
  'name' => 'foo',
  'value' => 'foo text',
  'id' => 'foo-id',
]) }}


  • All HTML helpers have been moved from the Qiq\Helper namespace to the Qiq\Helper\Html namespace; the Helper class has been renamed to TagHelper.

  • The Escape class is now defined in the the Qiq\Helper\Html namespace, not the Qiq namespace.

  • The attribute builder no longer honors the _raw pseudo-attribute. If you want tag body text to be unescaped, you will need to build it manually.

  • The _default pseudo-attribute in various form-related helpers has been replaced with the named parameter default.

  • The _options pseudo-attribute in various form-related helpers has been replaced with the named parameter options. Static Analysis

All Qiq code now declares strict_types=1 and is covered by static analysis. Normally this would mean your calling code might have to be more strict about what it sends to Qiq.

However, most string-like parameters are typed as mixed, with @param docblocks indicating the type as null|scalar|Stringable (or arrays thereof). This is because casting a mixed value to string is flagged by static analysis tools when being escaped for string output.

As a result, you should not have to recast the values you send to Qiq much, if at all -- but be aware of these changes nonetheless. Other Changes

  • An Engine interface has been introduced.

  • TemplateCore has been renamed to Kernel, and implements the Engine interface.

  • Template::new() has been moved to Kernel::new().

  • TemplateLocator has been renamed to Catalog; TemplateLocator::get() is now Catalog::getCompiled().

  • The Compiler interface is now defined in the Qiq namespace, not the Qiq\Compiler namespace.

  • The Exception class is now defined in the Qiq namespace, not the Qiq\Exception namespace.

  • The HelperNotFound exception has been renamed to ObjectNotFound, and implements the PSR-11 NotFoundExceptionInterface.

  • The TemplateNotFound exception has been renamed to FileNotFound.

  • The Indent class now uses instance methods, not static methods, and is shared as an instance in the Container.