Merge branch '4.x' into 4.next

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
 
     - uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: 3.11
 
     - name: Install dependencies
       run: |

.github/workflows/stale.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/stale@v7
+    - uses: actions/stale@v8
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         stale-issue-message: 'This issue is stale because it has been open for 120 days with no activity. Remove the `stale` label or comment or this will be closed in 15 days'

Dockerfile

@@ -1,22 +1,26 @@
-FROM debian:bullseye
+FROM debian:bookworm
 
 ENV DEBIAN_FRONTEND noninteractive
 
 LABEL Description="This image is used to create an environment to contribute to the cakephp/docs"
 
 RUN apt-get update && apt-get install -y \
+    build-essential \
     latexmk \
     php \
-    python3-pip \
+    python3-full \
     texlive-fonts-recommended \
     texlive-lang-all \
     texlive-latex-extra \
     texlive-latex-recommended \
   && apt-get clean \
   && rm -rf /var/lib/apt/lists/*
 
+RUN python3 -m venv /tmp/venv
+ENV PATH="/tmp/venv/bin:$PATH"
+
 COPY requirements.txt /tmp/
-RUN pip3 install -r /tmp/requirements.txt
+RUN pip install -r /tmp/requirements.txt
 
 WORKDIR /data
 VOLUME "/data"

README.md

@@ -146,3 +146,4 @@ Making Search Work Locally
 * Start elasticsearch with the default configuration.
 * Populate the search using tooling found in the [cakephp docs builder](https://github.com/cakephp/docs-builder) project.
 * You should now be able to search the docs using elasticsearch.
+

config/conf.py

@@ -112,6 +112,6 @@
 epub_tocdepth = 2
 
 rst_epilog = """
-.. |phpversion| replace:: **8.1**
+.. |phpversion| replace:: **8.2**
 .. |minphpversion| replace:: 7.4
 """

en/Makefile

@@ -8,13 +8,12 @@ PAPER         =
 BUILDDIR      = ../build
 CONFDIR       = ../config
 PYTHON        = python3
-LANG          = en
 SPHINX_LANG   = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(SPHINX_LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
@@ -41,9 +40,9 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(LANG)
+	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(LANG)."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(SPHINX_LANG)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -66,10 +65,10 @@ json:
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(LANG)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(LANG)."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)."
 
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@@ -90,22 +89,22 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(SPHINX_LANG)."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(LANG)."
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex/$(LANG) all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(LANG)."
+	make -C $(BUILDDIR)/latex/$(SPHINX_LANG) all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

en/appendices/4-3-migration-guide.rst

@@ -86,7 +86,9 @@ ORM
 - ``ModelAwareTrait::loadModel()`` is deprecated. Use the new ``LocatorAwareTrait::fetchTable()`` instead.
   For example, in controllers you can do ``$this->fetchTable()`` to get the default table instance or use
   ``$this->fetchTable('Foos')`` for a non-default table.  You can set the ``LocatorAwareTrait::$defaultTable``
-  property to specify the default table alias for ``fetchTable()``.
+  property to specify the default table alias for ``fetchTable()``. But be aware that
+  ``LocatorAwareTrait::fetchTable()`` does not create a property with the name of the table alias on the
+  calling object, e.g. ``$this->Articles``, as  ``ModelAwareTrait::loadModel()`` does.
 - Query proxying all ``ResultSetInterface`` methods (including ```CollectionInterface```), which forces
   fetching results and calls the proxied method on the results, is now deprecated. An example of the
   deprecated usage is ``$query->combine('id', 'title');``. This should be

en/appendices/4-4-migration-guide.rst

@@ -112,10 +112,12 @@ ORM
 Plugins
 -------
 
-- Plugin class names now match the plugin name with a "Plugin" suffix. For
-  example, the plugin class for "ADmad/I18n" would be ``ADmad\I18n\I18nPlugin``
+- Plugin class names should now match the plugin name with a "Plugin" suffix. For
+  example, the plugin class for ``ADmad/I18n`` plugin would be ``ADmad\I18n\I18nPlugin``
   instead of ``ADmad\I18n\Plugin``, as was the case for CakePHP 4.3 and below.
-  The old style name is still supported for backwards compatibility.
+  The old style name for existing majors should be kept to avoid BC breaks.
+  The new naming convention should be followed when developing a new plugin or
+  when doing a major release.
 
 Routing
 -------
@@ -190,6 +192,12 @@ Controller
   need to implement the static method ``contentType()`` to participate in
   content-type negotiation.
 
+Core
+----
+
+* The previously experimental API for the :doc:`/development/dependency-injection` container,
+  introduced in CakePHP 4.2, is now considered stable.
+
 Database
 --------
 
@@ -209,7 +217,7 @@ Error
 Http
 ----
 
-* ``Response::checkNotModified()`` was deprecated. 
+* ``Response::checkNotModified()`` was deprecated.
   Use ``Response::isNotModified()`` instead.
 * ``BaseApplication::handle()`` now adds the ``$request`` into the service
   container all the time.
@@ -228,11 +236,11 @@ ORM
 * The ``cascadeCallbacks`` option was added to ``TreeBehavior``. When enabled,
   ``TreeBehavior`` will iterate a ``find()`` result and delete records
   individually. This enables ORM callbacks to be used when deleting tree nodes.
-  
+
 Plugins
 -------
 
-* Plugin classes can now be named to match the plugin name instead of just ``Plugin``.
+* Plugin classes should now be named to match the plugin name instead of just ``Plugin``.
   For example, you should now use ``ADmad\I18n\I18nPlugin`` instead of ``ADmad\I18n\Plugin``.
 
 Routing

en/appendices/fixture-upgrade.rst

@@ -18,7 +18,7 @@ To upgrade to the new fixture system, you need to make a few updates:
 
    This removes schema management from the test fixture manager. Instead your
    application needs to create/update schema at the beginning of each test run.
-#. Next, update ``tests/boostrap.php`` to create schema. There are a few
+#. Next, update ``tests/bootstrap.php`` to create schema. There are a few
    different ways to create schema. Refer to :ref:`creating-test-database-schema`
    for the methods provided by CakePHP.
 #. Then, remove all the ``$fields`` and ``$import`` properties from your fixtures.

en/controllers.rst

@@ -428,7 +428,7 @@ set as properties on your controller::
     // Get an ElasticSearch model
     $articles = $this->fetchModel('Articles', 'Elastic');
 
-    // Get a webservices model 
+    // Get a webservices model
     $github = $this->fetchModel('GitHub', 'Webservice');
 
 .. versionadded:: 4.5.0
@@ -448,6 +448,10 @@ the controller's default one::
 .. versionadded:: 4.3.0
     ``Controller::fetchTable()`` was added. Prior to 4.3 you need to use ``Controller::loadModel()``.
 
+.. note::
+
+    ``Controller::fetchTable()`` does not create a proeprty controller property with the name of the table alias,
+    e.g. ``$this->Articles``, as  ``Controller::loadModel()`` does.
 
 Paginating a Model
 ==================

en/controllers/components/security.rst

@@ -1,6 +1,10 @@
 Security
 ########
 
+.. deprecated:: 4.0.0
+    ``SecurityComponent`` has been deprecated. Use :doc:`/controllers/components/form-protection` instead
+    for form tampering protection or :doc:`/security/https-enforcer` to enforce use of HTTPS (TLS) for requests.
+
 .. php:class:: SecurityComponent(ComponentCollection $collection, array $config = [])
 
 The Security Component creates a way to integrate tighter

en/core-libraries/caching.rst

@@ -214,9 +214,9 @@ the ``fallback`` configuration key::
         'fallback' => 'default',
     ]);
 
-If the Redis server unexpectedly failed, writing to the ``redis`` cache
-configuration would fall back to writing to the ``default`` cache configuration.
-If writing to the ``default`` cache configuration *also* failed in this scenario, the
+If initializing the ``RedisEngine`` instance fails, the ``redis`` cache configuration
+would fall back to using the ``default`` cache configuration. If initializing the
+engine for the ``default`` cache configuration *also* fails, in this scenario the
 engine would fall back once again to the ``NullEngine`` and prevent the application
 from throwing an uncaught exception.
 

en/core-libraries/file-folder.rst

@@ -94,24 +94,30 @@ Folder API
         $dir = new Folder();
         $dir->chmod('/path/to/folder', 0755, true, ['skip_me.php']);
 
-.. php:method:: copy(array|string $options = [])
+.. php:method:: copy(string $to, array $options = [])
 
-    Recursively copy a directory. The only parameter $options can either
-    be a path into copy to or an array of options::
+    Recursively copy a directory. The parameter $to is the location to copy to. The $options an array of options::
 
         $folder1 = new Folder('/path/to/folder1');
         $folder1->copy('/path/to/folder2');
         // Will put folder1 and all its contents into folder2
 
         $folder = new Folder('/path/to/folder');
-        $folder->copy([
-            'to' => '/path/to/new/folder',
+        $folder->copy('/path/to/new/folder', [
             'from' => '/path/to/copy/from', // Will cause a cd() to occur
             'mode' => 0755,
             'skip' => ['skip-me.php', '.git'],
             'scheme' => Folder::SKIP  // Skip directories/files that already exist.
         ]);
 
+    Available options:
+
+    * ``from`` The directory to copy from, this will cause a cd() to occur, changing the results of pwd().
+    * ``mode`` The mode to copy the files/directories with as integer, e.g. 0775.
+    * ``skip`` Files/directories to skip.
+    * ``scheme`` Folder::MERGE, Folder::OVERWRITE, Folder::SKIP
+    * ``recursive`` Whether to copy recursively or not (default: true - recursive)
+
     There are 3 supported schemes:
 
     * ``Folder::SKIP`` skip copying/moving files & directories that exist in the

en/core-libraries/logging.rst

@@ -227,7 +227,7 @@ If a level is not supplied, :php:const:`LOG_ERR` is used which writes to the
 error log. The default log location is **logs/$level.log**::
 
     // Executing this inside a CakePHP class
-    $this->log('Something didn't work!');
+    $this->log("Something didn't work!");
 
     // Results in this being appended to logs/error.log
     // 2007-11-02 10:22:02 Error: Something didn't work!

en/development/errors.rst

@@ -228,7 +228,7 @@ If you want to control the entire exception rendering and logging process you
 can use the ``Error.exceptionRenderer`` option in **config/app.php** to choose
 a class that will render exception pages. Changing the ExceptionRenderer is
 useful when you want to change the logic used to create an error controller,
-choose the error template, or control how the overall rendering process.
+choose the error template, or control the overall rendering process.
 
 Your custom exception renderer class should be placed in **src/Error**. Let's
 assume our application uses ``App\Exception\MissingWidgetException`` to indicate
@@ -427,16 +427,17 @@ If your application contained the following exception::
 
     use Cake\Core\Exception\CakeException;
 
-    class MissingWidgetException extends Exception
+    class MissingWidgetException extends CakeException
     {
     }
 
 You could provide nice development errors, by creating
 **templates/Error/missing_widget.php**. When in production mode, the above
 error would be treated as a 500 error and use the **error500** template.
 
-If your exceptions have a code between ``400`` and ``506`` the exception code
-will be used as the HTTP response code.
+Exceptions that subclass ``Cake\Http\Exception\HttpException``, will have their
+error code used as an HTTP status code if the error code is between ``400`` and
+``506``.
 
 The constructor for :php:exc:`Cake\\Core\\Exception\\CakeException` allows you to
 pass in additional data. This additional data is interpolated into the the

en/development/routing.rst

@@ -1099,6 +1099,23 @@ only connect specific resource routes you can use the ``only`` option::
 Would create read only resource routes. The route names are ``create``,
 ``update``, ``view``, ``index``, and ``delete``.
 
+The default **route name and controller action used** are as follows:
+
+=========== =======================
+Route name  Controller action used    
+=========== =======================
+create      add      
+----------- -----------------------
+update      edit  
+----------- -----------------------
+view        view      
+----------- -----------------------
+index       index  
+----------- -----------------------
+delete      delete  
+=========== =======================
+
+
 Changing the Controller Actions Used
 ------------------------------------
 

en/intro/cakephp-folder-structure.rst

@@ -58,8 +58,8 @@ View
 
 .. note::
 
-    The folders ``Shell`` is not present by default.
-    You can add them when you need them.
+    The folder ``Shell`` is not present by default.
+    You can add it when you need it.
 
 .. meta::
     :title lang=en: CakePHP Folder Structure

en/orm/entities.rst

@@ -221,7 +221,7 @@ looping mutator methods. For example::
         {
             $this->slug = Text::slug($title);
 
-            return strtouppercase($title);
+            return strtoupper($title);
         }
     }