Upgrading Nette
Form::FILLED is now Form::Filled, IRouter is
Nette\Routing\Router, and invalidateControl() is called redrawControl(). Nette libraries
have made over 900 such changes since version 3.0, and the package dresscode/upgrade-nette knows every one of them:
DressCode fixes roughly 700 right away, and for the rest it says what to write instead.
Two moves have a page of their own: from Nette 2.4 to Nette 3, and
to Nette 4, that is, to nette/utils,
nette/php-generator, nette/mail and nette/robot-loader in version 4.
Installation
To upgrade an application that still runs on Nette 3 or on PHP older than 8.4, install DressCode globally, because DressCode
itself needs PHP 8.4 and nette/utils 4.1 (see Where DressCode Runs):
composer global require dresscode/dresscode dresscode/upgrade-nette phpstan/phpstan
dresscode upgrade today
These two lines are enough: upgrade today finds the data and the rewrites of the package on its own, needs no
configuration, and leaves the style of the code as it is. The data of each library applies only when the project uses that
library, and only for the versions the project has reached.
Upgrading Code describes how to go one major version at a time and what to do with
what is left. A project that already runs on PHP 8.4 to 8.6 and on the current versions can also add the package as a
development dependency, composer require --dev dresscode/upgrade-nette phpstan/phpstan, and then run
vendor/bin/dresscode upgrade today.
What Gets Fixed
This is a model class written for Nette 3.0, in a project that now uses the current versions:
public function add(string $code): void
{
$section = $this->session->getSection('cart');
$items = $section->items ?? []; // Method `Nette\Http\SessionSection::__get()` is replaced by `get($name)`.
$items[] = Strings::match($code, '~^[A-Z]+-\d+$~', PREG_OFFSET_CAPTURE); // Static method `Nette\Utils\Strings::match()` takes `captureOffset: true` instead of `PREG_OFFSET_CAPTURE`.
$section->items = $items; // Method `Nette\Http\SessionSection::__set()` is replaced by `set($name, $value)`.
$section->source = $this->request->getQuery('utm_source', 'direct'); // Method `Nette\Http\SessionSection::__set()` is replaced by `set($name, $value)`.
// Method `Nette\Http\IRequest::getQuery()` is replaced by `getQuery($key) ?? $default`.
}
After dresscode upgrade today:
public function add(string $code): void
{
$section = $this->session->getSection('cart');
$items = $section->items ?? [];
$items[] = Strings::match($code, '~^[A-Z]+-\d+$~', captureOffset: true);
$section->set('items', $items);
$section->set('source', $this->request->getQuery('utm_source') ?? 'direct');
}
The line $items = $section->items ?? [] was left alone: on the left of ??, PHP first asks
SessionSection whether the property is set, while get() does not ask. So the fix is risky, and DressCode makes it once you accept it in
dresscode upgrade today --ask-risky, or once you list the decision upgrading.api.replacedCalls in the
key fixRisky.
What the package fixes:
- renamed classes and interfaces:
Nette\ConfiguratortoNette\Bootstrap\Configurator,IRoutertoNette\Routing\Router,IControltoNette\Forms\Controland others; the import, the type,new,instanceofand the attribute are all rewritten, - constants that used to be in uppercase:
Form::FILLEDtoForm::Filled,IResponse::S404_NOT_FOUNDtoIResponse::S404_NotFound,Presenter::INVALID_LINK_WARNINGtoInvalidLinkWarning, including renames chained across several versions, - renamed methods:
invalidateControl()toredrawControl(),getUnsafeValues()togetUntrustedValues(),Strings::contains()tostr_contains(), - renamed parameters in calls with named arguments:
setExpiration(time: ...)tosetExpiration(expire: ...),Arrays::map(callback: ...)toArrays::map(transformer: ...), also inparent::__construct()of a child class, - the default value after
??:getParameter('page', 1)togetParameter('page') ?? 1, and the same forgetQuery(),getPost(),getCookie(),getHeader()andgetOption(), - magic properties to getters and setters:
$form->action,$control->caption,$section->user,$section['user'], - flags to named arguments:
Json::encode($value, Json::PRETTY),Strings::match()and other functions with the constantsPREG_*,Neon::encode()withNeon::BLOCK, the router withRouter::ONE_WAY, - calls of a different shape:
addUpload($name, $label, true)toaddMultiUpload(),getValues(true)togetValues('array'),Callback::closure()toClosure::fromCallable(), - annotations to attributes:
@persistentand@crossOriginin presenters,@filterand@functionin Latte template parameter classes, and the attribute#[CrossOrigin]to#[Requires(sameOrigin: false)], - the component hooks
attached()anddetached()to callbacks ofmonitor()in the constructor, and the query string and fragment in a link destination,link('Product:show?id=1#reviews'), to arguments.
What Is Left to You
Where there is no replacement, or the replacement is used differently, DressCode reports the place and says what to write. This
covers, for example, methods of Url and UrlScript that moved elsewhere, constants that disappeared
without a replacement, or an attached() hook where DressCode cannot tell which type it was called for:
Method `Nette\Http\UrlScript::setPath()` is forbidden: the class is immutable; take a changed copy with `withPath()`.
Constant `Nette\Application\IRouter::SECURED` is forbidden: write the protocol, `https://`, into the mask of the route.
What a library only quietly marks as deprecated is not in the data. With the types, DressCode reports it anyway, and where the annotation names the replacement, it rewrites the code. The data does not capture changes in behavior, in NEON configuration or in the syntax of Latte templates at all; you will find those in the upgrade guides of the individual libraries.
Keeping the Old API from Coming Back
If you want every check to catch the old API too, for example in continuous integration, add three things to the configuration:
the types, the set deprecations, and the name of the package, which enables its rewrites in the section
nette (see Upgrading
Code):
typeAnalysis: phpstan
use:
- nette # your standard
- deprecations
- upgrade-nette
Together with the data, the set deprecations turns on the map
nette.flagsAsNamedArguments, which converts flags to named arguments. The data also turns on the decisions for link
destinations and for component hooks, nette.linkArguments from nette/application 3.3 and
nette.monitorCallbacks from nette/component-model 3.0, so you do not have to add them to the
configuration, and upgrade today runs them too. If you do not want one of them, turn it off in the section
nette with the value keep.
What the Package Covers
| library | versions |
|---|---|
nette/application |
3.0 to 3.3 |
nette/assets |
1.0 |
nette/bootstrap |
3.0 to 3.2 |
nette/caching |
3.0 to 3.4 |
nette/command-line |
1.9 to 2.0 |
nette/component-model |
3.0 to 4.0 |
nette/database |
3.0 to 3.2 |
nette/di |
3.0 to 3.2 |
nette/forms |
3.0 to 3.3 |
nette/http |
3.0 to 3.4 |
nette/mail |
3.1 to 4.1 |
nette/neon |
3.2 to 3.4 |
nette/php-generator |
3.3 to 4.2 |
nette/robot-loader |
3.2 to 4.1 |
nette/routing |
3.0 to 3.1 |
nette/schema |
1.2 to 1.3 |
nette/security |
3.0 to 3.2 |
nette/tester |
2.2 to 2.6 |
nette/utils |
3.0 to 4.1 |
latte/latte |
3.0 to 3.1 |
tracy/tracy |
2.6 to 2.10 |
The versions show the releases in which a library changed something the data captures; a newer version that renamed nothing needs no new data. An application on Nette 2.4 is upgraded the same way, with version 3.0 as the first step; Upgrading Code describes how to proceed one major version at a time.