Nette Documentation Preview

syntax
Migrating to Version 2.2
************************

.[perex]
This version brings a huge change in structure of the framework -- the "main repository":https://github.com/nette/nette has been split into several standalone components.

The main repository has been physically split into the following repositories:
"Application":[https://github.com/nette/application],
"Bootstrap":[https://github.com/nette/bootstrap],
"Caching":[https://github.com/nette/caching],
"ComponentModel":[https://github.com/nette/component-model],
"Nette Database":[https://github.com/nette/database],
"DI":[https://github.com/nette/di],
"Finder":[https://github.com/nette/finder],
"Forms":[https://github.com/nette/forms],
"Http":[https://github.com/nette/http],
"Latte":[https://github.com/nette/latte],
"Mail":[https://github.com/nette/mail],
"Neon":[https://github.com/nette/neon],
"PhpGenerator":[https://github.com/nette/php-generator],
"Reflection":[https://github.com/nette/reflection],
"RobotLoader":[https://github.com/nette/robot-loader],
"SafeStream":[https://github.com/nette/safe-stream],
"Security":[https://github.com/nette/security],
"Tokenizer":[https://github.com/nette/tokenizer],
"Tracy":[https://github.com/nette/tracy] and
"Utils":[https://github.com/nette/utils]. Each repository represents one component and has its own history, releases, issues, pull-requests, and, of course, `composer.json`.

You can still download the distribution package or install the whole framework using [best-practices:Composer] by requiring `nette/nette` in your `composer.json`.
In addition, you can use each of the components on its own, without installing the rest of the framework.


Latte
=====

Latte was an integral part of the framework for a long time, and it was integrated with the rest of the framework (mainly with the `Nette\Templating` namespace). In the new release, the Latte API was completely rewritten with stand-alone usage in mind:

```php
$latte = new Latte\Engine; // not the Nette\Latte\Engine
$latte->setTempDirectory('/path/to/cache');

$latte->addFilter('money', function ($val) { return /* ... */; });
// addFilter() replaced registerHelper() from previous releases

$latte->onCompile[] = function ($latte) {
	$latte->addMacro(/* ... */);
	// if you want add your own macros, see http://goo.gl/d5A1u2
};

$latte->render('template.latte', $parameters);
// or $html = $latte->renderToString('template.latte', $parameters);
```

Latte now handles template loading and caching. The original `FileTemplate` and the `Nette\Templating` namespaces have been deprecated.

In addition, `Nette\Application` provides its own `Template` class, which replaces `FileTemplate`, and `TemplateFactory`, which creates and initializes the templates for use in presenters and controls.


Tracy
=====

The whole debugger and diagnostics classes were moved to the `Tracy` namespace. This means that the most important class, `Nette\Diagnostics\Debugger`, was renamed to `Tracy\Debugger`.

Prefix of the CSS classes in the debugger panel was changed from `nette-` to `tracy-` and the `nette-toggle-collapsed` CSS class was replaced by the pair of `tracy-toggle` and `tracy-collapsed`. In old extensions, these classes are automatically rewritten.


Other Changes
=============

Classes `ArrayHash`, `ArrayList`, `DateTime`, `Image` and `ObjectMixin` are now part of the `Utils` package and they were moved from `Nette` to the `Nette\Utils` namespace. `NetteLoader` automatically creates aliases for these classes so they can be referenced by their old name. Aliases for other renamed classes are created at run-time (i.e. during the auto loading), and a warning is raised each time you use class by its old name.

`Nette\Utils\MimeTypeDetector` class was deprecated, the "Fileinfo":[https://www.php.net/manual/en/book.fileinfo.php] should be used directly since PHP 5.3.

Support for `@serializationVersion` annotation and custom annotation classes lookup was dropped, since it was not used and only decreased the application performance.

When an error during link creation occurs, the returned path starts with `#error:` instead of `error` to prevent browser errors. If you are using CSS to highlight incorrect links, please update your "CSS styles for invalid links":[https://github.com/nette/sandbox/commit/ac7a0fd2d707160426ab184442b8d68c590f8de2#diff-2].


New Features
============

The `do` parameter for forms is now transferred in the `POST` data to keep the URL more user-friendly. The form values are passed as the second parameter to the `onSuccess` callback, to spare you from writing `$form->getValues();` in each form handler. New validators, `Form::MIN` and `Form::MAX`, were introduced.

`data-` attributes in `Nette\Utils\Html` now accepts arrays. They will be automatically encoded to JSON.

New function `fetchAssoc()` was added to the `Nette\Database`. The usage example can be found in "test suite for ResultSet.fetchAssoc()":[https://github.com/nette/database/blob/master/tests/Database/ResultSet.fetchAssoc().phpt].

`@inject` annotations now respect aliases defined by `use` statements. This means you are no longer required to write fully qualified names when injecting dependencies.

Class `Nette\Security\Passwords` with static methods for password hashing and verification was introduced. This class uses bcrypt algorithm and requires PHP 5.3.7 or higher. The bcrypt algorithm is more secure than traditionally used MD5 and SHA-* hashing, so we recommend using bcrypt functions instead. Semantics of these functions is compatible with the "Password Hashing extension":[https://www.php.net/manual/en/book.password.php] from PHP 5.5.

Last, but not least, when defining users in the `config.neon` file, you can specify role for each user:

```neon
nette:
	security:
		users:
			john:
				password: **********
				roles:
					- manager
					- reporter
```

{{priority: -5}}

Migrating to Version 2.2

This version brings a huge change in structure of the framework – the main repository has been split into several standalone components.

The main repository has been physically split into the following repositories: Application, Bootstrap, Caching, ComponentModel, Nette Database, DI, Finder, Forms, Http, Latte, Mail, Neon, PhpGenerator, Reflection, RobotLoader, SafeStream, Security, Tokenizer, Tracy and Utils. Each repository represents one component and has its own history, releases, issues, pull-requests, and, of course, composer.json.

You can still download the distribution package or install the whole framework using best-practices:Composer by requiring nette/nette in your composer.json. In addition, you can use each of the components on its own, without installing the rest of the framework.

Latte

Latte was an integral part of the framework for a long time, and it was integrated with the rest of the framework (mainly with the Nette\Templating namespace). In the new release, the Latte API was completely rewritten with stand-alone usage in mind:

$latte = new Latte\Engine; // not the Nette\Latte\Engine
$latte->setTempDirectory('/path/to/cache');

$latte->addFilter('money', function ($val) { return /* ... */; });
// addFilter() replaced registerHelper() from previous releases

$latte->onCompile[] = function ($latte) {
	$latte->addMacro(/* ... */);
	// if you want add your own macros, see http://goo.gl/d5A1u2
};

$latte->render('template.latte', $parameters);
// or $html = $latte->renderToString('template.latte', $parameters);

Latte now handles template loading and caching. The original FileTemplate and the Nette\Templating namespaces have been deprecated.

In addition, Nette\Application provides its own Template class, which replaces FileTemplate, and TemplateFactory, which creates and initializes the templates for use in presenters and controls.

Tracy

The whole debugger and diagnostics classes were moved to the Tracy namespace. This means that the most important class, Nette\Diagnostics\Debugger, was renamed to Tracy\Debugger.

Prefix of the CSS classes in the debugger panel was changed from nette- to tracy- and the nette-toggle-collapsed CSS class was replaced by the pair of tracy-toggle and tracy-collapsed. In old extensions, these classes are automatically rewritten.

Other Changes

Classes ArrayHash, ArrayList, DateTime, Image and ObjectMixin are now part of the Utils package and they were moved from Nette to the Nette\Utils namespace. NetteLoader automatically creates aliases for these classes so they can be referenced by their old name. Aliases for other renamed classes are created at run-time (i.e. during the auto loading), and a warning is raised each time you use class by its old name.

Nette\Utils\MimeTypeDetector class was deprecated, the Fileinfo should be used directly since PHP 5.3.

Support for @serializationVersion annotation and custom annotation classes lookup was dropped, since it was not used and only decreased the application performance.

When an error during link creation occurs, the returned path starts with #error: instead of error to prevent browser errors. If you are using CSS to highlight incorrect links, please update your CSS styles for invalid links.

New Features

The do parameter for forms is now transferred in the POST data to keep the URL more user-friendly. The form values are passed as the second parameter to the onSuccess callback, to spare you from writing $form->getValues(); in each form handler. New validators, Form::MIN and Form::MAX, were introduced.

data- attributes in Nette\Utils\Html now accepts arrays. They will be automatically encoded to JSON.

New function fetchAssoc() was added to the Nette\Database. The usage example can be found in test suite for ResultSet.fetchAssoc().

@inject annotations now respect aliases defined by use statements. This means you are no longer required to write fully qualified names when injecting dependencies.

Class Nette\Security\Passwords with static methods for password hashing and verification was introduced. This class uses bcrypt algorithm and requires PHP 5.3.7 or higher. The bcrypt algorithm is more secure than traditionally used MD5 and SHA-* hashing, so we recommend using bcrypt functions instead. Semantics of these functions is compatible with the Password Hashing extension from PHP 5.5.

Last, but not least, when defining users in the config.neon file, you can specify role for each user:

nette:
	security:
		users:
			john:
				password: **********
				roles:
					- manager
					- reporter