diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst deleted file mode 100644 index d82accf36c..0000000000 --- a/en/appendices/5-0-migration-guide.rst +++ /dev/null @@ -1,428 +0,0 @@ -5.0 Migration Guide -################### - -CakePHP 5.0 contains breaking changes, and is not backwards compatible with 4.x -releases. Before attempting to upgrade to 5.0, first upgrade to 4.5 and resolve -all deprecation warnings. - -Refer to the :doc:`/appendices/5-0-upgrade-guide` for step by step instructions -on how to upgrade to 5.0. - -Deprecated Features Removed -=========================== - -All methods, properties and functionality that were emitting deprecation warnings -as of 4.5 have been removed. - -Breaking Changes -================ - -In addition to the removal of deprecated features there have been breaking -changes made: - -Global ------- - -- Type declarations were added to all function parameter and returns where possible. These are intended - to match the docblock annotations, but include fixes for incorrect annotations. -- Type declarations were added to all class properties where possible. These also include some fixes for - incorrect annotations. -- The ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``, ``WEEK``, ``MONTH``, ``YEAR`` constants were removed. -- Use of ``#[\AllowDynamicProperties]`` removed everywhere. It was used for the following classes: - - ``Command/Command`` - - ``Console/Shell`` - - ``Controller/Component`` - - ``Controller/Controller`` - - ``Mailer/Mailer`` - - ``View/Cell`` - - ``View/Helper`` - - ``View/View`` -- The supported database engine versions were updated: - - MySQL (5.7 or higher) - - MariaDB (10.1 or higher) - - PostgreSQL (9.6 or higher) - - Microsoft SQL Server (2012 or higher) - - SQLite 3 (3.16 or higher) - -Auth ----- - -- `Auth` has been removed. Use the `cakephp/authentication `__ and - `cakephp/authorization `__ plugins instead. - -Cache ------ - -- The ``Wincache`` engine was removed. The wincache extension is not supported - on PHP 8. - -Collection ----------- - -- ``combine()`` now throws an exception if the key path or group path doesn't exist or contains a null value. - This matches the behavior of ``indexBy()`` and ``groupBy()``. - -Console -------- - -- ``BaseCommand::__construct()`` was removed. -- ``ConsoleIntegrationTestTrait::useCommandRunner()`` was removed since it's no longer needed. -- ``Shell`` has been removed and should be replaced with `Command `__ -- ``ConsoleOptionParser::addSubcommand()`` was removed alongside the removal of - ``Shell``. Subcommands should be replaced with ``Command`` classes that - implement ``Command::defaultName()`` to define the necessary command name. -- ``BaseCommand`` now emits ``Command.beforeExecute`` and - ``Command.afterExecute`` events around the command's ``execute()`` method - being invoked by the framework. - -Connection ----------- - -- ``Connection::prepare()`` has been removed. You can use ``Connection::execute()`` - instead to execute a SQL query by specifing the SQL string, params and types in a single call. -- ``Connection::enableQueryLogging()`` has been removed. If you haven't enabled logging - through the connection config then you can later set the logger instance for the - driver to enable query logging ``$connection->getDriver()->setLogger()``. - -Controller ----------- - -- The method signature for ``Controller::__construct()`` has changed. - So you need to adjust your code accordingly if you are overriding the constructor. -- After loading components are no longer set as dynamic properties. Instead - ``Controller`` uses ``__get()`` to provide property access to components. This - change can impact applications that use ``property_exists()`` on components. -- The components' ``Controller.shutdown`` event callback has been renamed from - ``shutdown`` to ``afterFilter`` to match the controller one. This makes the callbacks more consistent. -- ``PaginatorComponent`` has been removed and should be replaced by calling ``$this->paginate()`` in your controller or - using ``Cake\Datasource\Paging\NumericPaginator`` directly -- ``RequestHandlerComponent`` has been removed. See the `4.4 migration `__ guide for how to upgrade -- ``SecurityComponent`` has been removed. Use ``FormProtectionComponent`` for form tampering protection - or ``HttpsEnforcerMiddleware`` to enforce use of HTTPS for requests instead. -- ``Controller::paginate()`` no longer accepts query options like ``contain`` for - its ``$settings`` argument. You should instead use the ``finder`` option - ``$this->paginate($this->Articles, ['finder' => 'published'])``. Or you can - create required select query before hand and then pass it to ``paginate()`` - ``$query = $this->Articles->find()->where(['is_published' => true]); $this->paginate($query);``. - -Core ----- - -- The function ``getTypeName()`` has been dropped. Use PHP's ``get_debug_type()`` instead. -- The dependency on ``league/container`` was updated to ``4.x``. This will - require the addition of typehints to your ``ServiceProvider`` implementations. -- ``deprecationWarning()`` now has a ``$version`` parameter. -- The ``App.uploadedFilesAsObjects`` configuration option has been removed - alongside of support for PHP file upload shaped arrays throughout the - framework. -- ``ClassLoader`` has been removed. Use composer to generate autoload files instead. - -Database --------- - -- The ``DateTimeType`` and ``DateType`` now always return immutable objects. - Additionally the interface for ``Date`` objects reflects the ``ChronosDate`` - interface which lacks all of the time related methods that were present in - CakePHP 4.x. -- ``DateType::setLocaleFormat()`` no longer accepts an array. -- ``Query`` now accepts only ``\Closure`` parameters instead of ``callable``. Callables can be converted - to closures using the new first-class array syntax in PHP 8.1. -- ``Query::execute()`` no longer runs results decorator callbacks. You must use ``Query::all()`` instead. -- ``TableSchemaAwareInterface`` was removed. -- ``Driver::quote()`` was removed. Use prepared statements instead. -- ``Query::orderBy()`` was added to replace ``Query::order()``. -- ``Query::groupBy()`` was added to replace ``Query::group()``. -- ``SqlDialectTrait`` has been removed and all its functionality has been moved - into the ``Driver`` class itself. -- ``CaseExpression`` has been removed and should be replaced with - ``QueryExpression::case()`` or ``CaseStatementExpression`` -- ``Connection::connect()`` has been removed. Use - ``$connection->getDriver()->connect()`` instead. -- ``Connection::disconnect()`` has been removed. Use - ``$connection->getDriver()->disconnect()`` instead. -- ``cake.database.queries`` has been added as an alternative to the ``queriesLog`` scope -- The ability to enable/disable ResultSet buffering has been removed. Results are always buffered. - -Datasource ----------- - -- The ``getAccessible()`` method was added to ``EntityInterface``. Non-ORM - implementations need to implement this method now. -- The ``aliasField()`` method was added to ``RepositoryInterface``. Non-ORM - implementations need to implement this method now. - -Event ------ - -- Event payloads must be an array. Other object such as ``ArrayAccess`` are no longer cast to array and will raise a ``TypeError`` now. -- It is recommended to adjust event handlers to be void methods and use ``$event->setResult()`` instead of returning the result - -Error ------ - -- ``ErrorHandler`` and ``ConsoleErrorHandler`` have been removed. See the `4.4 migration `__ guide for how to upgrade -- ``ExceptionRenderer`` has been removed and should be replaced with ``WebExceptionRenderer`` -- ``ErrorLoggerInterface::log()`` has been removed and should be replaced with ``ErrorLoggerInterface::logException()`` -- ``ErrorLoggerInterface::logMessage()`` has been removed and should be replaced with ``ErrorLoggerInterface::logError()`` - -Filesystem ----------- - -- The Filesystem package was removed, and ``Filesystem`` class was moved to the Utility package. - -Http ----- - -- ``ServerRequest`` is no longer compatible with ``files`` as arrays. This - behavior has been disabled by default since 4.1.0. The ``files`` data will now - always contain ``UploadedFileInterfaces`` objects. - -I18n ----- - -- ``FrozenDate`` was renamed to `Date` and ``FrozenTime`` was renamed to `DateTime`. -- ``Time`` now extends ``Cake\Chronos\ChronosTime`` and is therefore immutable. -- ``Date`` objects do not extend ``DateTimeInterface`` anymore - therefore you can't compare them with ``DateTime`` objects. - See the `cakephp/chronos release documentation `__ for more information. -- ``Date::parseDateTime()`` was removed. -- ``Date::parseTime()`` was removed. -- ``Date::setToStringFormat()`` and ``Date::setJsonEncodeFormat()`` no longer accept an array. -- ``Date::i18nFormat()`` and ``Date::nice()`` no longer accept a timezone parameter. -- Translation files for plugins with vendor prefixed names (``FooBar/Awesome``) will now have that - prefix in the file name, e.g. ``foo_bar_awesome.po`` to avoid collision with a ``awesome.po`` file - from a corresponding plugin (``Awesome``). - -Log ---- - -- Log engine config now uses ``null`` instead of ``false`` to disable scopes. - So instead of ``'scopes' => false`` you need to use ``'scopes' => null`` in your log config. - -Mailer ------- - -- ``Email`` has been removed. Use `Mailer `__ instead. -- ``cake.mailer`` has been added as an alternative to the ``email`` scope - -ORM ---- - -- ``EntityTrait::has()`` now returns ``true`` when an attribute exists and is - set to ``null``. In previous versions of CakePHP this would return ``false``. - See the release notes for 4.5.0 for how to adopt this behavior in 4.x. -- ``EntityTrait::extractOriginal()`` now returns only existing fields, similar to ``extractOriginalChanged()``. -- Finder arguments are now required to be associative arrays as they were always expected to be. -- ``TranslateBehavior`` now defaults to the ``ShadowTable`` strategy. If you are - using the ``Eav`` strategy you will need to update your behavior configuration - to retain the previous behavior. -- ``allowMultipleNulls`` option for ``isUnique`` rule now default to true matching - the original 3.x behavior. -- ``Table::query()`` has been removed in favor of query-type specific functions. -- ``Table::updateQuery()``, ``Table::selectQuery()``, ``Table::insertQuery()``, and - ``Table::deleteQuery()``) were added and return the new type-specific query objects below. -- ``SelectQuery``, ``InsertQuery``, ``UpdateQuery`` and ``DeleteQuery`` were added - which represent only a single type of query and do not allow switching between query types nor - calling functions unrelated to the specific query type. -- ``Table::_initializeSchema()`` has been removed and should be replaced by calling - ``$this->getSchema()`` inside the ``initialize()`` method. -- ``SaveOptionsBuilder`` has been removed. Use a normal array for options instead. - -Routing -------- - -- Static methods ``connect()``, ``prefix()``, ``scope()`` and ``plugin()`` of the ``Router`` have been removed and - should be replaced by calling their non-static method variants via the ``RouteBuilder`` instance. -- ``RedirectException`` has been removed. Use ``\Cake\Http\Exception\RedirectException`` instead. - -TestSuite ---------- - -- ``TestSuite`` was removed. Users should use environment variables to customize - unit test settings instead. -- ``TestListenerTrait`` was removed. PHPUnit dropped support for these listeners. - See :doc:`/appendices/phpunit10` -- ``IntegrationTestTrait::configRequest()`` now merges config when called multiple times - instead of replacing the currently present config. - -Validation ----------- - -- ``Validation::isEmpty()`` is no longer compatible with file upload shaped - arrays. Support for PHP file upload arrays has been removed from - ``ServerRequest`` as well so you should not see this as a problem outside of - tests. -- Previously, most data validation error messages were simply ``The provided value is invalid``. - Now, the data validation error messages are worded more precisely. - For example, ``The provided value must be greater than or equal to \`5\```. - -View ----- - -- ``ViewBuilder`` options are now truly associative (string keys). -- ``NumberHelper`` and ``TextHelper`` no longer accept an ``engine`` config. -- ``ViewBuilder::setHelpers()`` parameter ``$merge`` was removed. Use ``ViewBuilder::addHelpers()`` instead. -- Inside ``View::initialize()``, prefer using ``addHelper()`` instead of ``loadHelper()``. - All configured helpers will be loaded afterwards, anyway. -- ``View\Widget\FileWidget`` is no longer compatible with PHP file upload shaped - arrays. This is aligned with ``ServerRequest`` and ``Validation`` changes. -- ``FormHelper`` no longer sets ``autocomplete=off`` on CSRF token fields. This - was a workaround for a Safari bug that is no longer relevant. - -Deprecations -============ - -The following is a list of deprecated methods, properties and behaviors. These -features will continue to function in 5.x and will be removed in 6.0. - -Database --------- - -- ``Query::order()`` was deprecated. Use ``Query::orderBy()`` instead now that - ``Connection`` methods are no longer proxied. This aligns the function name - with the SQL statement. -- ``Query::group()`` was deprecated. Use ``Query::groupBy()`` instead now that - ``Connection`` methods are no longer proxied. This aligns the function name - with the SQL statement. - -ORM ---- - -- Calling ``Table::find()`` with options array is deprecated. Use `named arguments `__ - instead. For e.g. instead of ``find('all', ['conditions' => $array])`` use - ``find('all', conditions: $array)``. Similarly for custom finder options, instead - of ``find('list', ['valueField' => 'name'])`` use ``find('list', valueField: 'name')`` - or multiple named arguments like ``find(type: 'list', valueField: 'name', conditions: $array)``. - -New Features -============ - -Improved type checking ------------------------ - -CakePHP 5 leverages the expanded type system feature available in PHP 8.1+. -CakePHP also uses ``assert()`` to provide improved error messages and additional -type soundness. In production mode, you can configure PHP to not generate -code for ``assert()`` yielding improved application performance. See the -:ref:`symlink-assets` for how to do this. - -Collection ----------- - -- Added ``unique()`` which filters out duplicate value specified by provided callback. -- ``reject()`` now supports a default callback which filters out truthy values which is - the inverse of the default behavior of ``filter()`` - -Core ----- - -- The ``services()`` method was added to ``PluginInterface``. -- ``PluginCollection::addFromConfig()`` has been added to :ref:`simplify plugin loading `. - -Database --------- - -- ``ConnectionManager`` now supports read and write connection roles. Roles can be configured - with ``read`` and ``write`` keys in the connection config that override the shared config. -- ``Query::all()`` was added which runs result decorator callbacks and returns a result set for select queries. -- ``Query::comment()`` was added to add a SQL comment to the executed query. This makes it easier to debug queries. -- ``EnumType`` was added to allow mapping between PHP backed enums and a string or integer column. -- ``getMaxAliasLength()`` and ``getConnectionRetries()`` were added - to ``DriverInterface``. -- Supported drivers now automatically add auto-increment only to integer primary keys named "id" instead - of all integer primary keys. Setting 'autoIncrement' to false always disables on all supported drivers. - -Http ----- - -- Added support for `PSR-17 `__ factories - interface. This allows ``cakephp/http`` to provide a client implementation to - libraries that allow automatic interface resolution like php-http. -- Added ``CookieCollection::__get()`` and ``CookieCollection::__isset()`` to add - ergonomic ways to access cookies without exceptions. - -ORM ---- - -Required Entity Fields ----------------------- - -Entities have a new opt-in functionality that allows making entities handle -properties more strictly. The new behavior is called 'required fields'. When -enabled, accessing properties that are not defined in the entity will raise -exceptions. This impacts the following usage:: - - $entity->get(); - $entity->has(); - $entity->getOriginal(); - isset($entity->attribute); - $entity->attribute; - -Fields are considered defined if they pass ``array_key_exists``. This includes -null values. Because this can be a tedious to enable feature, it was deferred to -5.0. We'd like any feedback you have on this feature as we're considering making -this the default behavior in the future. - - -Typed Finder Parameters ------------------------ - -Table finders can now have typed arguments as required instead of an options array. -For e.g. a finder for fetching posts by category or user:: - - public function findByCategoryOrUser(SelectQuery $query, array $options) - { - if (isset($options['categoryId'])) { - $query->where(['category_id' => $options['categoryId']]); - } - if (isset($options['userId'])) { - $query->where(['user_id' => $options['userId']]); - } - - return $query; - } - -can now be written as:: - - public function findByCategoryOrUser(SelectQuery $query, ?int $categoryId = null, ?int $userId = null) - { - if ($categoryId) { - $query->where(['category_id' => $categoryId]); - } - if ($userId) { - $query->where(['user_id' => $userId]); - } - - return $query; - } - -The finder can then be called as ``find('byCategoryOrUser', userId: $somevar)``. -You can even include the special named arguments for setting query clauses. -``find('byCategoryOrUser', userId: $somevar, conditions: ['enabled' => true])``. - -A similar change has been applied to the ``RepositoryInterface::get()`` method:: - - public function view(int $id) - { - $author = $this->Authors->get($id, [ - 'contain' => ['Books'], - 'finder' => 'latest', - ]); - } - -can now be written as:: - - public function view(int $id) - { - $author = $this->Authors->get($id, contain: ['Books'], finder: 'latest'); - } - -TestSuite ---------- - -- ``IntegrationTestTrait::requestAsJson()`` has been added to set JSON headers for the next request. - -Plugin Installer ----------------- -- The plugin installer has been updated to automatically handle class autoloading - for your app plugins. So you can remove the namespace to path mappings for your - plugins from your ``composer.json`` and just run ``composer dumpautoload``. diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst deleted file mode 100644 index caac02853f..0000000000 --- a/en/appendices/5-1-migration-guide.rst +++ /dev/null @@ -1,198 +0,0 @@ -5.1 Migration Guide -################### - -The 5.1.0 release is a backwards compatible with 5.0. It adds new functionality -and introduces new deprecations. Any functionality deprecated in 5.x will be -removed in 6.0.0. - -Behavior Changes -================ - -- Connection now creates unique read and write drivers if the keys ``read`` or - ``write`` are present in the config regardless of values. -- FormHelper no longer generates ``aria-required`` attributes on input elements - that also have the ``required`` attribute set. The ``aria-required`` attribute - is redundant on these elements and generates HTML validation warnings. If you - are using ``aria-required`` attribute in styling or scripting you'll need to - update your application. -- Adding associations with duplicate names will now raise exceptions. You can - use ``$table->associations()->has()`` to conditionally define associations if - required. -- Text Utility and TextHelper methods around truncation and maximum length are using - a UTF-8 character for ``ellipsis`` instead of ``...`` legacy characters. -- ``TableSchema::setColumnType()`` now throws an exception if the specified column - does not exist. -- ``PluginCollection::addPlugin()`` now throws an exception if a plugin of the same - name is already added. -- ``TestCase::loadPlugins()`` will now clear out any previously loaded plugins. So - you must specify all plugins required for any subsequent tests. -- The hashing algorithm for ``Cache`` configurations that use ``groups``. Any - keys will have new group prefix hashes generated which will cause cache - misses. Consider an incremental deploy to avoid operating on an entirely cold - cache. -- ``FormHelper::getFormProtector()`` now returns ``null`` in addition to its - previous types. This allows dynamic view code to run with fewer errors and - shouldn't impact most applications. -- The default value for ``valueSeparator`` in ``Table::findList()`` is now - a single space instead of ``;``. -- ``ErrorLogger`` uses ``Psr\Log\LogTrait`` now. -- ``Database\QueryCompiler::$_orderedUnion`` was removed. - -Deprecations -============ - -I18n ----- - -- The ``_cake_core_`` cache config key has been renamed to ``_cake_translations_``. - -Mailer ------- - -- ``Mailer::setMessage()`` is deprecated. It has unintuitive behavior and very - low usage. - - -New Features -============ - -Cache ------ - -- ``RedisEngine`` now supports a ``tls`` option that enables connecting to redis - over a TLS connection. You can use the ``ssl_ca``, ``ssl_cert`` and - ``ssl_key`` options to define the TLS context for redis. - -Command -------- - -- ``bin/cake plugin list`` has been added to list all available plugins, - their load configuration and version. -- Optional ``Command`` arguments can now have a ``default`` value. -- ``BannerHelper`` was added. This command helper can format text as a banner - with a coloured background and padding. -- Additional default styles for ``info.bg``, ``warning.bg``, ``error.bg`` and - ``success.bg`` were added to ``ConsoleOutput``. - -Console -------- - -- ``Arguments::getBooleanOption()`` and ``Arguments::getMultipleOption()`` were added. -- ``Arguments::getArgument()`` will now raise an exception if an unknown - argument name is provided. This helps prevent mixing up option/argument names. - - -Controller ----------- - -- Components can now use the DI container to have dependencies resolved and - provided as constructor parameters just like Controllers and Commands do. - -Core ----- - -- ``PluginConfig`` was added. Use this class to get all available plugins, their load config and versions. -- The ``toString``, ``toInt``, ``toBool`` functions were added. They give you - a typesafe way to cast request data or other input and return ``null`` when conversion fails. -- ``pathCombine()`` was added to help build paths without worrying about duplicate and trailing slashes. -- A new ``events`` hook was added to the ``BaseApplication`` as well as the ``BasePlugin`` class. This hook - is the recommended way to register global event listeners for you application. See :ref:`Registering Listeners ` - -Database --------- - -- Support for ``point``, ``linestring``, ``polygon`` and ``geometry`` types were - added. These types are useful when working with geospatial or cartesian - co-ordinates. Sqlite support uses text columns under the hood and lacks - functions to manipulate data as geospatial values. -- ``SelectQuery::__debugInfo()`` now includes which connection role the query - is for. -- ``SelectQuery::intersect()`` and ``SelectQuery::intersectAll()`` were added. - These methods enable queries using ``INTERSECT`` and ``INTERSECT ALL`` - conjunctions to be expressed. -- New supports features were added for ``intersect``, ``intersect-all`` and - ``set-operations-order-by`` features. -- The ability to fetch records without buffering which existed in 4.x has been restored. - Methods ``SelectQuery::enableBufferedResults()``, ``SelectQuery::disableBufferedResults()`` - and ``SelectQuery::isBufferedResultsEnabled()`` have been re-added. - -Datasource ----------- - -- ``RulesChecker::remove()``, ``removeCreate()``, ``removeUpdate()``, and - ``removeDelete()`` methods were added. These methods allow you to remove rules - by name. - - -Http ----- - -- ``SecurityHeadersMiddleware::setPermissionsPolicy()`` was added. This method - adds the ability to define ``permissions-policy`` header values. -- ``Client`` now emits ``HttpClient.beforeSend`` and ``HttpClient.afterSend`` - events when requests are sent. You can use these events to perform logging, - caching or collect telemetry. -- ``Http\Server::terminate()`` was added. This method triggers the - ``Server.terminate`` event which can be used to run logic after the response - has been sent in fastcgi environments. In other environments the - ``Server.terminate`` event runs *before* the response has been sent. - -I18n ----- - -- ``Number::formatter()`` and ``currency()`` now accept a ``roundingMode`` - option to override how rounding is done. -- The ``toDate``, and ``toDateTime`` functions were added. They give you - a typesafe way to cast request data or other input and return ``null`` when - conversion fails. - -ORM ---- - -- Setting the ``preserveKeys`` option on association finder queries. This can be - used with ``formatResults()`` to replace association finder results with an - associative array. -- SQLite columns with names containing ``json`` can now be mapped to ``JsonType``. - This is currently an opt-in feature which is enabled by setting the ``ORM.mapJsonTypeForSqlite`` - configure value to ``true`` in your app. - -TestSuite ---------- - -- CakePHP as well as the app template have been updated to use PHPUnit ``^10.5.5 || ^11.1.3"``. -- ``ConnectionHelper`` methods are now all static. This class has no state and - its methods were updated to be static. -- ``LogTestTrait`` was added. This new trait makes it easy to capture logs in - your tests and make assertions on the presence or absence of log messages. -- ``IntegrationTestTrait::replaceRequest()`` was added. - -Utility -------- - -- ``Hash::insert()`` and ``Hash::remove()`` now accept ``ArrayAccess`` objects along with ``array`` data. - -Validation ----------- - -- ``Validation::enum()`` and ``Validator::enum()`` were added. These validation - methods simplify validating backed enum values. -- ``Validation::enumOnly()`` and ``Validation::enumExcept()`` were added to check for specific cases - and further simplify validating backed enum values. - -View ----- - -- View cells now emit events around their actions ``Cell.beforeAction`` and - ``Cell.afterAction``. -- ``NumberHelper::format()`` now accepts a ``roundingMode`` option to override how - rounding is done. - -Helpers -------- - -- ``TextHelper::autoLinkUrls()`` has options added for better link label printing: - * ``stripProtocol``: Strips ``http://`` and ``https://`` from the beginning of the link. Default off. - * ``maxLength``: The maximum length of the link label. Default off. - * ``ellipsis``: The string to append to the end of the link label. Defaults to UTF8 version. -- ``HtmlHelper::meta()`` can now create a meta tag containing the current CSRF - token using ``meta('csrfToken')``. diff --git a/en/appendices/5-2-migration-guide.rst b/en/appendices/5-2-migration-guide.rst deleted file mode 100644 index 3e0151969c..0000000000 --- a/en/appendices/5-2-migration-guide.rst +++ /dev/null @@ -1,68 +0,0 @@ -5.2 Migration Guide -################### - -The 5.2.0 release is a backwards compatible with 5.0. It adds new functionality -and introduces new deprecations. Any functionality deprecated in 5.x will be -removed in 6.0.0. - -Behavior Changes -================ - -- ``ValidationSet::add()`` will now raise errors when a rule is added with - a name that is already defined. This change aims to prevent rules from being - overwritten by accident. -- ``Http\Session`` will now raise an exception when an invalid session preset is - used. -- ``FormProtectionComponent`` now raises ``Cake\Controller\Exception\FormProtectionException``. This - class is a subclass of ``BadRequestException``, and offers the benefit of - being filterable from logging. -- ``NumericPaginator::paginate()`` now uses the ``finder`` option even when a ``SelectQuery`` instance is passed to it. - -Deprecations -============ - -Console -------- - -- ``Arguments::getMultipleOption()`` is deprecated. Use ``getArrayOption()`` - instead. - - -New Features -============ - -Console -------- - -- The ``cake counter_cache`` command was added. This command can be used to - regenerate counters for models that use ``CounterCacheBehavior``. -- ``ConsoleIntegrationTestTrait::debugOutput()`` makes it easier to debug - integration tests for console commands. -- ``ConsoleInputArgument`` now supports a ``separator`` option. This option - allows positional arguments to be delimited with a character sequence like - ``,``. CakePHP will split the positional argument into an array when arguments - are parsed. -- ``Arguments::getArrayArgumentAt()``, and ``Arguments::getArrayArgument()`` - were added. These methods allow you to read ``separator`` delimitered - positional arguments as arrays. -- ``ConsoleInputOption`` now supports a ``separator`` option. This option - allows option values to be delimited with a character sequence like - ``,``. CakePHP will split the option value into an array when arguments - are parsed. -- ``Arguments::getArrayArgumentAt()``, ``Arguments::getArrayArgument()``, and - ``Arguments::getArrayOption()`` - were added. These methods allow you to read ``separator`` delimitered - positional arguments as arrays. - -ORM ---- - -- ``CounterCacheBehavior::updateCounterCache()`` has been addded. This method - allows you to update the counter cache values for all records of the configured - associations. - -Error ------ - -- Custom exceptions can have specific error handling logic defined in - ``ErrorController``. diff --git a/en/appendices/5-0-upgrade-guide.rst b/en/appendices/6-0-upgrade-guide.rst similarity index 62% rename from en/appendices/5-0-upgrade-guide.rst rename to en/appendices/6-0-upgrade-guide.rst index 5f34ec911c..7e5ba17b17 100644 --- a/en/appendices/5-0-upgrade-guide.rst +++ b/en/appendices/6-0-upgrade-guide.rst @@ -1,12 +1,12 @@ -5.0 Upgrade Guide +6.0 Upgrade Guide ################# -First, check that your application is running on latest CakePHP 4.x version. +First, check that your application is running on latest CakePHP 5.x version. Fix Deprecation Warnings ======================== -Once your application is running on latest CakePHP 4.x, enable deprecation warnings in **config/app.php**:: +Once your application is running on latest CakePHP 5.x, enable deprecation warnings in **config/app.php**:: 'Error' => [ 'errorLevel' => E_ALL, @@ -17,16 +17,15 @@ Now that you can see all the warnings, make sure these are fixed before proceedi Some potentially impactful deprecations you should make sure you have addressed are: -- ``Table::query()`` was deprecated in 4.5.0. Use ``selectQuery()``, - ``updateQuery()``, ``insertQuery()`` and ``deleteQuery()`` instead. +To be defined -Upgrade to PHP 8.1 +Upgrade to PHP 8.4 ================== -If you are not running on **PHP 8.1 or higher**, you will need to upgrade PHP before updating CakePHP. +If you are not running on **PHP 8.4 or higher**, you will need to upgrade PHP before updating CakePHP. .. note:: - CakePHP 5.0 requires **a minimum of PHP 8.1**. + CakePHP 6.0 requires **a minimum of PHP 8.4**. .. _upgrade-tool-use: @@ -34,25 +33,22 @@ Use the Upgrade Tool ==================== .. note:: - The upgrade tool only works on applications running on latest CakePHP 4.x. You cannot run the upgrade tool after updating to CakePHP 5.0. + The upgrade tool only works on applications running on latest CakePHP 5.x. You cannot run the upgrade tool after updating to CakePHP 6.0. -Because CakePHP 5 leverages union types and ``mixed``, there are many -backwards incompatible changes concerning method signatures and file renames. -To help expedite fixing these tedious changes there is an upgrade CLI tool: +To help expedite fixing tedious changes there is an upgrade CLI tool: .. code-block:: console # Install the upgrade tool git clone https://github.com/cakephp/upgrade cd upgrade - git checkout 5.x + git checkout 6.x composer install --no-dev With the upgrade tool installed you can now run it on your application or plugin:: - bin/cake upgrade rector --rules cakephp50 - bin/cake upgrade rector --rules chronos3 + bin/cake upgrade rector --rules cakephp60 Update CakePHP Dependency ========================= @@ -61,7 +57,7 @@ After applying rector refactorings you need to upgrade CakePHP, its plugins, PHP and maybe other dependencies in your ``composer.json``. This process heavily depends on your application so we recommend you compare your ``composer.json`` with what is present in `cakephp/app -`__. +`__. After the version strings are adjusted in your ``composer.json`` execute ``composer update -W`` and check its output. @@ -71,4 +67,4 @@ Update app files based upon latest app template Next, ensure the rest of your application has been updated to be based upon the latest version of `cakephp/app -`__. +`__. diff --git a/en/appendices/migration-guides.rst b/en/appendices/migration-guides.rst index b2bb03dd6a..e597858e3a 100644 --- a/en/appendices/migration-guides.rst +++ b/en/appendices/migration-guides.rst @@ -7,9 +7,6 @@ each version and the migration path between 5.x minor releases. .. toctree:: :maxdepth: 1 - ./5-0-upgrade-guide - ./5-0-migration-guide - ./5-1-migration-guide - ./5-2-migration-guide + ./6-0-upgrade-guide ./6-0-migration-guide ./phpunit10