From 8833fe6fba442ae6baebe0eaef379d73d4ecf742 Mon Sep 17 00:00:00 2001 From: mscherer Date: Tue, 12 Sep 2023 23:43:39 +0200 Subject: [PATCH 001/337] Changed behavior of extractOriginal() --- en/appendices/5-0-migration-guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index bcd24efbcd..02ff52c8d6 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -176,6 +176,7 @@ 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 From c6b73269a51796bc2a4d3700da4f8b417a570844 Mon Sep 17 00:00:00 2001 From: ADmad Date: Wed, 13 Sep 2023 18:55:36 +0530 Subject: [PATCH 002/337] Update plugin docs links --- en/contents.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/en/contents.rst b/en/contents.rst index 772bd4e52c..d8261f8c3a 100644 --- a/en/contents.rst +++ b/en/contents.rst @@ -71,15 +71,15 @@ Contents :caption: Plugins & Packages standalone-packages - Authentication - Authorization - Bake - Debug Kit - Migrations - Elasticsearch + Authentication + Authorization + Bake + Debug Kit + Migrations + Elasticsearch Phinx - Chronos - Queue + Chronos + Queue .. toctree:: :caption: Other From a4cabd360a98a2090923048085f443c6ff859785 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?wowDAS=20Ing=2E=20Markus=20Ram=C5=A1ak?= Date: Wed, 13 Sep 2023 17:37:43 +0200 Subject: [PATCH 003/337] Update installation.rst its not in beta anymore --- en/installation.rst | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/en/installation.rst b/en/installation.rst index fe4d6838c5..be9af018c7 100644 --- a/en/installation.rst +++ b/en/installation.rst @@ -86,13 +86,7 @@ command: .. code-block:: console - composer create-project --prefer-dist cakephp/app:5.0.0-beta1 my_app_name - -CakePHP 5 is still in beta. While in beta, new projects may require using the 5.x-dev branch instead. Like so: - -.. code-block:: console - - composer create-project --prefer-dist cakephp/app:5.x-dev my_app_name + composer create-project --prefer-dist cakephp/app:~5.0 my_app_name Once Composer finishes downloading the application skeleton and the core CakePHP library, you should have a functioning CakePHP application installed via From d4c7f0ea2de3c63bfa6e5855c822b83f66452a63 Mon Sep 17 00:00:00 2001 From: Roland Waldner <126562443+rolandwaldner@users.noreply.github.com> Date: Wed, 13 Sep 2023 17:57:00 +0200 Subject: [PATCH 004/337] Update logging.rst --- en/core-libraries/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/core-libraries/logging.rst b/en/core-libraries/logging.rst index 83f3b049fd..188005ca4a 100644 --- a/en/core-libraries/logging.rst +++ b/en/core-libraries/logging.rst @@ -254,7 +254,7 @@ custom paths to be used:: .. note:: - In debug mode missing directories will be automatically created to avoid + Missing directories will be automatically created to avoid unnecessary errors thrown when using the FileEngine. .. _syslog-log: From a33eade563fb4357a35abf0a9487193d8c92ae5c Mon Sep 17 00:00:00 2001 From: ADmad Date: Sat, 16 Sep 2023 08:35:48 +0530 Subject: [PATCH 005/337] Add info about dropped Connection methods. Refs cakephp/cakephp#17277, cakephp/cakephp#17278 --- en/appendices/5-0-migration-guide.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index bcd24efbcd..38944081d9 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -60,6 +60,15 @@ Console ``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 ---------- From bf196cce8352923b18a1c1aaa493a2da9a264955 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20M=2E=20Gonz=C3=A1lez=20Mart=C3=ADn?= Date: Sat, 16 Sep 2023 17:59:29 +0100 Subject: [PATCH 006/337] Update security-headers.rst Remove outdated options from the example, add references to all headers and Mozilla security recommendations --- en/security/security-headers.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/en/security/security-headers.rst b/en/security/security-headers.rst index 573103cf78..4597f6f054 100644 --- a/en/security/security-headers.rst +++ b/en/security/security-headers.rst @@ -10,7 +10,6 @@ headers to responses: * ``X-Content-Type-Options`` * ``X-Download-Options`` * ``X-Frame-Options`` -* ``X-Permitted-Cross-Domain-Policies`` * ``Referrer-Policy`` This middleware is configured using a fluent interface before it is applied to @@ -20,15 +19,17 @@ your application's middleware stack:: $securityHeaders = new SecurityHeadersMiddleware(); $securityHeaders - ->setCrossDomainPolicy() ->setReferrerPolicy() ->setXFrameOptions() - ->setXssProtection() ->noOpen() ->noSniff(); $middlewareQueue->add($securityHeaders); +Here's a list of common HTTP headers https://en.wikipedia.org/wiki/List_of_HTTP_header_fields. + +And the Mozilla recommended settings https://infosec.mozilla.org/guidelines/web_security.html. + .. meta:: :title lang=en: Security Header Middleware :keywords lang=en: x-frame-options, cross-domain, referrer-policy, download-options, middleware, content-type-options From 83f7d1f9e25a2150b0c0fd6e73d5ada33a433324 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20M=2E=20Gonz=C3=A1lez=20Mart=C3=ADn?= Date: Sat, 16 Sep 2023 20:01:23 +0100 Subject: [PATCH 007/337] Update https-enforcer.rst Add note about sts header and ssl never used --- en/security/https-enforcer.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/en/security/https-enforcer.rst b/en/security/https-enforcer.rst index a118261660..63e99beeea 100644 --- a/en/security/https-enforcer.rst +++ b/en/security/https-enforcer.rst @@ -36,6 +36,10 @@ use the ``HttpsEnforcerMiddleware``:: If a non-HTTP request is received that does not use GET a ``BadRequestException`` will be raised. +NOTE: The Strict-Transport-Security header is ignored by the browser when your site has only been +accessed using HTTP. Once your site is accessed over HTTPS with no certificate errors, the browser +knows your site is HTTPS capable and will honor the Strict-Transport-Security header. + Adding Strict-Transport-Security ================================ From ea6d5237b58bdee9eb796521669214e033f721e6 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 16 Sep 2023 23:26:04 -0400 Subject: [PATCH 008/337] Improve wording --- en/security/security-headers.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/en/security/security-headers.rst b/en/security/security-headers.rst index 4597f6f054..8494454dcb 100644 --- a/en/security/security-headers.rst +++ b/en/security/security-headers.rst @@ -26,9 +26,9 @@ your application's middleware stack:: $middlewareQueue->add($securityHeaders); -Here's a list of common HTTP headers https://en.wikipedia.org/wiki/List_of_HTTP_header_fields. - -And the Mozilla recommended settings https://infosec.mozilla.org/guidelines/web_security.html. +Here's a list of `common HTTP headers `__, +and the Mozilla `recommended settings `__ +for securing web applications. .. meta:: :title lang=en: Security Header Middleware From ac70ad735f261819d3a1da4e8d3b5a2c65306be5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Federico=20Jaramillo=20Mart=C3=ADnez?= Date: Sun, 17 Sep 2023 15:28:48 +0200 Subject: [PATCH 009/337] Fix pagination instructions. (#7711) * Fix pagination instructions. The examples are still using the deprecated pagination from 3.x. * Paginate inside sub-controller Co-authored-by: Kevin Pfeifer * No need for initialize method * Remove duplicate query --------- Co-authored-by: Kevin Pfeifer --- .../cms/articles-controller.rst | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/en/tutorials-and-examples/cms/articles-controller.rst b/en/tutorials-and-examples/cms/articles-controller.rst index 8e7a9f012e..06d30ad314 100644 --- a/en/tutorials-and-examples/cms/articles-controller.rst +++ b/en/tutorials-and-examples/cms/articles-controller.rst @@ -33,8 +33,7 @@ look like this:: { public function index() { - $this->loadComponent('Paginator'); - $articles = $this->Paginator->paginate($this->Articles->find()); + $articles = $this->paginate($this->Articles); $this->set(compact('articles')); } } @@ -180,17 +179,9 @@ to be created. Start by creating an ``add()`` action in the class ArticlesController extends AppController { - public function initialize(): void - { - parent::initialize(); - - $this->loadComponent('Paginator'); - $this->loadComponent('Flash'); // Include the FlashComponent - } - public function index() { - $articles = $this->Paginator->paginate($this->Articles->find()); + $articles = $this->paginate($this->Articles); $this->set(compact('articles')); } @@ -224,7 +215,7 @@ to be created. Start by creating an ``add()`` action in the You need to include the :doc:`/controllers/components/flash` component in any controller where you will use it. Often it makes sense to include it in - your ``AppController``. + your ``AppController``, which is there already for this tutorial. Here's what the ``add()`` action does: From cdfae01e511622626429a1e3d3cc50803f818169 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Sun, 17 Sep 2023 15:44:02 +0200 Subject: [PATCH 010/337] cleanup last AuthComponent references --- en/core-libraries/number.rst | 7 ++++--- en/core-libraries/registry-objects.rst | 12 ++++++------ en/core-libraries/time.rst | 5 +++-- 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/en/core-libraries/number.rst b/en/core-libraries/number.rst index 6a68d87da3..f59429a03f 100644 --- a/en/core-libraries/number.rst +++ b/en/core-libraries/number.rst @@ -17,12 +17,13 @@ use the ``Number`` class:: public function initialize(): void { parent::initialize(); - $this->loadComponent('Auth'); + $this->loadComponent('Authentication.Authentication'); } public function afterLogin() { - $storageUsed = $this->Auth->user('storage_used'); + $identity = $this->Authentication->getIdentity(); + $storageUsed = $identity->storage_used; if ($storageUsed > 5000000) { // Notify users of quota $this->Flash->success(__('You are using {0} storage', Number::toReadableSize($storageUsed))); @@ -118,7 +119,7 @@ Getting the Default Currency .. php:method:: getDefaultCurrency() Getter for the default currency. If default currency was set earlier using -``setDefaultCurrency()``, then that value will be returned. By default, it will +``setDefaultCurrency()``, then that value will be returned. By default, it will retrieve the ``intl.default_locale`` ini value if set and ``'en_US'`` if not. Formatting Floating Point Numbers diff --git a/en/core-libraries/registry-objects.rst b/en/core-libraries/registry-objects.rst index 1a46a1e1b1..25fb6580fa 100644 --- a/en/core-libraries/registry-objects.rst +++ b/en/core-libraries/registry-objects.rst @@ -28,8 +28,8 @@ used to alias objects in a registry. This allows you to have component names that do not reflect the classnames, which can be helpful when extending core components:: - $this->Auth = $this->loadComponent('Auth', ['className' => 'MyCustomAuth']); - $this->Auth->user(); // Actually using MyCustomAuth::user(); + $this->Flash = $this->loadComponent('Flash', ['className' => 'MyCustomFlash']); + $this->Flash->error(); // Actually using MyCustomFlash::error(); Triggering Callbacks ==================== @@ -46,11 +46,11 @@ objects from receiving callbacks. You should use the features in the events syst accomplish this now. For example, you could disable component callbacks in the following way:: - // Remove Auth from callbacks. - $this->getEventManager()->off($this->Auth); + // Remove MyComponent from callbacks. + $this->getEventManager()->off($this->MyComponent); - // Re-enable Auth for callbacks. - $this->getEventManager()->on($this->Auth); + // Re-enable MyComponent for callbacks. + $this->getEventManager()->on($this->MyComponent); .. meta:: :title lang=en: Object Registry diff --git a/en/core-libraries/time.rst b/en/core-libraries/time.rst index f71381a359..b60b05a09c 100644 --- a/en/core-libraries/time.rst +++ b/en/core-libraries/time.rst @@ -15,12 +15,13 @@ use the ``DateTime`` class:: public function initialize(): void { parent::initialize(); - $this->loadComponent('Auth'); + $this->loadComponent('Authentication.Authentication'); } public function afterLogin() { - $time = new DateTime($this->Auth->user('date_of_birth')); + $identity = $this->Authentication->getIdentity(); + $time = new DateTime($identity->date_of_birth); if ($time->isToday()) { // Greet user with a happy birthday message $this->Flash->success(__('Happy birthday to you...')); From ee460ca4eff45e9e02d3490804d8fcf49f26dd8e Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Sun, 17 Sep 2023 15:55:23 +0200 Subject: [PATCH 011/337] cleanup last AuthComponent references --- en/core-libraries/app.rst | 4 +- en/development/configuration.rst | 2 +- en/development/sessions.rst | 2 +- en/development/testing.rst | 77 -------------------------------- 4 files changed, 4 insertions(+), 81 deletions(-) diff --git a/en/core-libraries/app.rst b/en/core-libraries/app.rst index 1c43895376..1b1bb6f926 100644 --- a/en/core-libraries/app.rst +++ b/en/core-libraries/app.rst @@ -16,8 +16,8 @@ This method is used to resolve class names throughout CakePHP. It resolves the short form names CakePHP uses and returns the fully resolved class name:: // Resolve a short class name with the namespace + suffix. - App::className('Auth', 'Controller/Component', 'Component'); - // Returns Cake\Controller\Component\AuthComponent + App::className('Flash', 'Controller/Component', 'Component'); + // Returns Cake\Controller\Component\FlashComponent // Resolve a plugin name. App::className('DebugKit.Toolbar', 'Controller/Component', 'Component'); diff --git a/en/development/configuration.rst b/en/development/configuration.rst index 0c17b3f9d9..54fdd8c70e 100644 --- a/en/development/configuration.rst +++ b/en/development/configuration.rst @@ -114,7 +114,7 @@ App.base The base directory the app resides in. If ``false`` this will be auto detected. If not ``false``, ensure your string starts with a `/` and does NOT end with a `/`. For example, `/basedir` is a valid - App.base. Otherwise, the AuthComponent will not work properly. + App.base. App.encoding Define what encoding your application uses. This encoding is used to generate the charset in the layout, and encode entities. diff --git a/en/development/sessions.rst b/en/development/sessions.rst index 3a8d2310a2..aee792140e 100644 --- a/en/development/sessions.rst +++ b/en/development/sessions.rst @@ -441,7 +441,7 @@ Rotating Session Identifiers .. php:method:: renew() -While ``AuthComponent`` automatically renews the session id when users login and +While the ``Authentication Plugin`` automatically renews the session id when users login and logout, you may need to rotate the session id's manually. To do this use the ``renew()`` method:: diff --git a/en/development/testing.rst b/en/development/testing.rst index d48bd0fd6d..6aeb8fa152 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1104,83 +1104,6 @@ to configure the requests you will send to your application under test:: The state set by these helper methods is reset in the ``tearDown()`` method. -.. _testing-authentication: - -Testing Actions That Require Authentication -------------------------------------------- - -If you are using ``AuthComponent`` you will need to stub out the session data -that AuthComponent uses to validate a user's identity. You can use helper -methods in ``IntegrationTestTrait`` to do this. Assuming you had an -``ArticlesController`` that contained an add method, and that add method -required authentication, you could write the following tests:: - - public function testAddUnauthenticatedFails(): void - { - // No session data set. - $this->get('/articles/add'); - - $this->assertRedirect(['controller' => 'Users', 'action' => 'login']); - } - - public function testAddAuthenticated(): void - { - // Set session data - $this->session([ - 'Auth' => new User([ - 'id' => 1, - 'username' => 'testing', - // other keys. - ]) - ]); - $this->get('/articles/add'); - - $this->assertResponseOk(); - // Other assertions. - } - -Testing Stateless Authentication and APIs ------------------------------------------ - -To test APIs that use stateless authentication, such as Basic authentication, -you can configure the request to inject environment conditions or headers that -simulate actual authentication request headers. - -When testing Basic or Digest Authentication, you can add the environment -variables that `PHP creates `_ -automatically.:: - - public function testBasicAuthentication(): void - { - $this->configRequest([ - 'environment' => [ - 'PHP_AUTH_USER' => 'username', - 'PHP_AUTH_PW' => 'password', - ] - ]); - - $this->get('/api/posts'); - $this->assertResponseOk(); - } - -If you are testing other forms of authentication, such as OAuth2, you can set -the Authorization header directly:: - - public function testOauthToken(): void - { - $this->configRequest([ - 'headers' => [ - 'authorization' => 'Bearer: oauth-token' - ] - ]); - - $this->get('/api/posts'); - $this->assertResponseOk(); - } - -The headers key in ``configRequest()`` can be used to configure any additional -HTTP headers needed for an action. - Testing Actions Protected by CsrfComponent or SecurityComponent --------------------------------------------------------------- From 6a48c5e8c8699794bc51d3e55765e22449e5d0e2 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Sun, 17 Sep 2023 16:34:41 +0200 Subject: [PATCH 012/337] more cleanup --- en/contents.rst | 1 - en/core-libraries/file-folder.rst | 455 ------------------------ en/core-libraries/security.rst | 2 +- en/core-libraries/validation.rst | 6 +- en/debug-kit.rst | 2 +- en/development/configuration.rst | 8 +- en/development/dependency-injection.rst | 2 +- en/development/testing.rst | 2 +- en/epub-contents.rst | 1 - en/installation.rst | 4 +- en/pdf-contents.rst | 1 - en/views/helpers/form.rst | 14 +- en/views/helpers/paginator.rst | 2 +- en/views/helpers/time.rst | 2 +- en/views/helpers/url.rst | 2 +- 15 files changed, 23 insertions(+), 481 deletions(-) delete mode 100644 en/core-libraries/file-folder.rst diff --git a/en/contents.rst b/en/contents.rst index 772bd4e52c..7c086f5811 100644 --- a/en/contents.rst +++ b/en/contents.rst @@ -56,7 +56,6 @@ Contents core-libraries/app core-libraries/collections - core-libraries/file-folder core-libraries/hash core-libraries/httpclient core-libraries/inflector diff --git a/en/core-libraries/file-folder.rst b/en/core-libraries/file-folder.rst deleted file mode 100644 index 5378f97cd2..0000000000 --- a/en/core-libraries/file-folder.rst +++ /dev/null @@ -1,455 +0,0 @@ -Folder & File -############# - -.. php:namespace:: Cake\Filesystem - -The Folder and File utilities are convenience classes to help you read from and -write/append to files; list files within a folder and other common directory -related tasks. - -.. deprecated:: 4.0 - The ``File`` and ``Folder`` classes will be removed in 5.0. - Use SPL classes like ``SplFileInfo`` or ``SplFileObject`` and iterator - classes like ``RecursiveDirectoryIterator``, ``RecursiveRegexIterator`` etc. instead. - -Basic Usage -=========== - -Ensure the classes are loaded:: - - use Cake\Filesystem\Folder; - use Cake\Filesystem\File; - -Then we can setup a new folder instance:: - - $dir = new Folder('/path/to/folder'); - -and search for all *.php* files within that folder using regex:: - - $files = $dir->find('.*\.php'); - -Now we can loop through the files and read from or write/append to the contents or -simply delete the file:: - - foreach ($files as $file) { - $file = new File($dir->pwd() . DS . $file); - $contents = $file->read(); - // $file->write('I am overwriting the contents of this file'); - // $file->append('I am adding to the bottom of this file.'); - // $file->delete(); // I am deleting this file - $file->close(); // Be sure to close the file when you're done - } - -Folder API -========== - -.. php:class:: Folder(string $path = false, boolean $create = false, string|boolean $mode = false) - -:: - - // Create a new folder with 0755 permissions - $dir = new Folder('/path/to/folder', true, 0755); - -.. php:attr:: path - - Path of the current folder. :php:meth:`Folder::pwd()` will return the same - information. - -.. php:attr:: sort - - Whether or not the list results should be sorted by name. - -.. php:attr:: mode - - Mode to be used when creating folders. Defaults to ``0755``. Does nothing on - Windows machines. - -.. php:staticmethod:: addPathElement(string $path, string $element) - - Returns $path with $element added, with correct slash in-between:: - - $path = Folder::addPathElement('/a/path/for', 'testing'); - // $path equals /a/path/for/testing - - $element can also be an array:: - - $path = Folder::addPathElement('/a/path/for', ['testing', 'another']); - // $path equals /a/path/for/testing/another - -.. php:method:: cd( $path ) - - Change directory to $path. Returns ``false`` on failure:: - - $folder = new Folder('/foo'); - echo $folder->path; // Prints /foo - $folder->cd('/bar'); - echo $folder->path; // Prints /bar - $false = $folder->cd('/non-existent-folder'); - -.. php:method:: chmod(string $path, integer $mode = false, boolean $recursive = true, array $exceptions = []) - - Change the mode on a directory structure recursively. This includes - changing the mode on files as well:: - - $dir = new Folder(); - $dir->chmod('/path/to/folder', 0755, true, ['skip_me.php']); - -.. php:method:: copy(string $to, array $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('/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 - destination directory. - * ``Folder::MERGE`` merge the source/destination directories. Files in the - source directory will replace files in the target directory. Directory - contents will be merged. - * ``Folder::OVERWRITE`` overwrite existing files & directories in the target - directory with those in the source directory. If both the target and - destination contain the same subdirectory, the target directory's contents - will be removed and replaced with the source's. - -.. php:staticmethod:: correctSlashFor(string $path) - - Returns a correct set of slashes for given $path ('\\' for - Windows paths and '/' for other paths). - -.. php:method:: create(string $pathname, integer $mode = false) - - Create a directory structure recursively. Can be used to create - deep path structures like `/foo/bar/baz/shoe/horn`:: - - $folder = new Folder(); - if ($folder->create('foo' . DS . 'bar' . DS . 'baz' . DS . 'shoe' . DS . 'horn')) { - // Successfully created the nested folders - } - -.. php:method:: delete(string $path = null) - - Recursively remove directories if the system allows:: - - $folder = new Folder('foo'); - if ($folder->delete()) { - // Successfully deleted foo and its nested folders - } - -.. php:method:: dirsize() - - Returns the size in bytes of this Folder and its contents. - -.. php:method:: errors() - - Get the error from latest method. - -.. php:method:: find(string $regexpPattern = '.*', boolean $sort = false) - - Returns an array of all matching files in the current directory:: - - // Find all .png in your webroot/img/ folder and sort the results - $dir = new Folder(WWW_ROOT . 'img'); - $files = $dir->find('.*\.png', true); - /* - Array - ( - [0] => cake.icon.png - [1] => test-error-icon.png - [2] => test-fail-icon.png - [3] => test-pass-icon.png - [4] => test-skip-icon.png - ) - */ - -.. note:: - - The folder find and findRecursive methods will only find files. If you - would like to get folders and files see :php:meth:`Folder::read()` or - :php:meth:`Folder::tree()` - -.. php:method:: findRecursive(string $pattern = '.*', boolean $sort = false) - - Returns an array of all matching files in and below the current directory:: - - // Recursively find files beginning with test or index - $dir = new Folder(WWW_ROOT); - $files = $dir->findRecursive('(test|index).*'); - /* - Array - ( - [0] => /var/www/cake/webroot/index.php - [1] => /var/www/cake/webroot/test.php - [2] => /var/www/cake/webroot/img/test-skip-icon.png - [3] => /var/www/cake/webroot/img/test-fail-icon.png - [4] => /var/www/cake/webroot/img/test-error-icon.png - [5] => /var/www/cake/webroot/img/test-pass-icon.png - ) - */ - -.. php:method:: inCakePath(string $path = '') - - Returns ``true`` if the file is in a given CakePath. - -.. php:method:: inPath(string $path = '', boolean $reverse = false) - - Returns ``true`` if the file is in the given path:: - - $Folder = new Folder(WWW_ROOT); - $result = $Folder->inPath(APP); - // $result = false, /var/www/example/src/ is not in /var/www/example/webroot/ - - $result = $Folder->inPath(WWW_ROOT . 'img' . DS, true); - // $result = true, /var/www/example/webroot/img/ is in /var/www/example/webroot/ - -.. php:staticmethod:: isAbsolute(string $path) - - Returns ``true`` if the given $path is an absolute path. - -.. php:staticmethod:: isSlashTerm(string $path) - - Returns ``true`` if given $path ends in a slash (i.e. is slash-terminated):: - - $result = Folder::isSlashTerm('/my/test/path'); - // $result = false - $result = Folder::isSlashTerm('/my/test/path/'); - // $result = true - -.. php:staticmethod:: isWindowsPath(string $path) - - Returns ``true`` if the given $path is a Windows path. - -.. php:method:: messages() - - Get the messages from the latest method. - -.. php:method:: move(array $options) - - Recursive directory move. - -.. php:staticmethod:: normalizeFullPath(string $path) - - Returns a path with slashes normalized for the operating system. - -.. php:method:: pwd() - - Return current path. - -.. php:method:: read(boolean $sort = true, array|boolean $exceptions = false, boolean $fullPath = false) - - Returns an array of the contents of the current directory. The - returned array holds two sub arrays: One of directories and one of files:: - - $dir = new Folder(WWW_ROOT); - $files = $dir->read(true, ['files', 'index.php']); - /* - Array - ( - [0] => Array // Folders - ( - [0] => css - [1] => img - [2] => js - ) - [1] => Array // Files - ( - [0] => .htaccess - [1] => favicon.ico - [2] => test.php - ) - ) - */ - -.. php:method:: realpath(string $path) - - Get the real path (taking ".." and such into account). - -.. php:staticmethod:: slashTerm(string $path) - - Returns $path with added terminating slash (corrected for - Windows or other OS). - -.. php:method:: tree(null|string $path = null, array|boolean $exceptions = true, null|string $type = null) - - Returns an array of nested directories and files in each directory. - -File API -======== - -.. php:class:: File(string $path, boolean $create = false, integer $mode = 755) - -:: - - // Create a new file with 0644 permissions - $file = new File('/path/to/file.php', true, 0644); - -.. php:attr:: Folder - - The Folder object of the file. - -.. php:attr:: name - - The name of the file with the extension. Differs from - :php:meth:`File::name()` which returns the name without the extension. - -.. php:attr:: info - - An array of file info. Use :php:meth:`File::info()` instead. - -.. php:attr:: handle - - Holds the file handler resource if the file is opened. - -.. php:attr:: lock - - Enable locking for file reading and writing. - -.. php:attr:: path - - The current file's absolute path. - -.. php:method:: append(string $data, boolean $force = false) - - Append the given data string to the current file. - -.. php:method:: close() - - Closes the current file if it is opened. - -.. php:method:: copy(string $dest, boolean $overwrite = true) - - Copy the file to the absolute path ``$dest``. - -.. php:method:: create() - - Creates the file. - -.. php:method:: delete() - - Deletes the file. - -.. php:method:: executable() - - Returns ``true`` if the file is executable. - -.. php:method:: exists() - - Returns ``true`` if the file exists. - -.. php:method:: ext() - - Returns the file extension. - -.. php:method:: Folder() - - Returns the current folder. - -.. php:method:: group() - - Returns the file's group, or ``false`` in case of an error. - -.. php:method:: info() - - Returns the file info. - -.. php:method:: lastAccess( ) - - Returns last access time. - -.. php:method:: lastChange() - - Returns last modified time, or ``false`` in case of an error. - -.. php:method:: md5(integer|boolean $maxsize = 5) - - Get the MD5 Checksum of file with previous check of filesize, - or ``false`` in case of an error. - -.. php:method:: name() - - Returns the file name without extension. - -.. php:method:: offset(integer|boolean $offset = false, integer $seek = 0) - - Sets or gets the offset for the currently opened file. - -.. php:method:: open(string $mode = 'r', boolean $force = false) - - Opens the current file with the given $mode. - -.. php:method:: owner() - - Returns the file's owner. - -.. php:method:: perms() - - Returns the "chmod" (permissions) of the file. - -.. php:staticmethod:: prepare(string $data, boolean $forceWindows = false) - - Prepares a ascii string for writing. Converts line endings to the - correct terminator for the current platform. For Windows "\\r\\n" - will be used, "\\n" for all other platforms. - -.. php:method:: pwd() - - Returns the full path of the file. - -.. php:method:: read(string $bytes = false, string $mode = 'rb', boolean $force = false) - - Return the contents of the current file as a string or return ``false`` on failure. - -.. php:method:: readable() - - Returns ``true`` if the file is readable. - -.. php:method:: safe(string $name = null, string $ext = null) - - Makes filename safe for saving. - -.. php:method:: size() - - Returns the filesize in bytes. - -.. php:method:: writable() - - Returns ``true`` if the file is writable. - -.. php:method:: write(string $data, string $mode = 'w', boolean$force = false) - - Write given data to the current file. - -.. php:method:: mime() - - Get the file's mimetype, returns ``false`` on failure. - -.. php:method:: replaceText( $search, $replace ) - - Replaces text in a file. Returns ``false`` on failure and ``true`` on success. - -.. todo:: - - Better explain how to use each method with both classes. - -.. meta:: - :title lang=en: Folder & File - :description lang=en: The Folder and File utilities are convenience classes to help you read, write, and append to files; list files within a folder and other common directory related tasks. - :keywords lang=en: file,folder,cakephp utility,read file,write file,append file,recursively copy,copy options,folder path,class folder,file php,php files,change directory,file utilities,new folder,directory structure,delete file diff --git a/en/core-libraries/security.rst b/en/core-libraries/security.rst index e0b0fd7af4..d1f1524087 100644 --- a/en/core-libraries/security.rst +++ b/en/core-libraries/security.rst @@ -6,7 +6,7 @@ Security Utility .. php:class:: Security The `security library -`_ +`_ handles basic security measures such as providing methods for hashing and encrypting data. diff --git a/en/core-libraries/validation.rst b/en/core-libraries/validation.rst index a9db41a4e4..7ae3a6d14a 100644 --- a/en/core-libraries/validation.rst +++ b/en/core-libraries/validation.rst @@ -6,7 +6,7 @@ Validation The validation package in CakePHP provides features to build validators that can validate arbitrary arrays of data with ease. You can find a `list of available Validation rules in the API -`__. +`__. .. _creating-validators: @@ -146,7 +146,7 @@ like:: ->lengthBetween('username', [4, 8]); See the `Validator API documentation -`_ for the +`_ for the full set of validator methods. .. _custom-validation-rules: @@ -611,7 +611,7 @@ class. The Validation class contains a variety of static methods that provide validators for several common validation situations. The `API documentation -`_ for the +`_ for the ``Validation`` class provides a good list of the validation rules that are available, and their basic usage. diff --git a/en/debug-kit.rst b/en/debug-kit.rst index 92327b5d56..050b73a5c6 100644 --- a/en/debug-kit.rst +++ b/en/debug-kit.rst @@ -1,4 +1,4 @@ Debug Kit ######### -This page has `moved `__. +This page has `moved `__. diff --git a/en/development/configuration.rst b/en/development/configuration.rst index 0c17b3f9d9..9e87fdac34 100644 --- a/en/development/configuration.rst +++ b/en/development/configuration.rst @@ -555,12 +555,12 @@ Configuration Engines CakePHP provides the ability to load configuration files from a number of different sources, and features a pluggable system for `creating your own configuration engines -`__. +`__. The built in configuration engines are: -* `JsonConfig `__ -* `IniConfig `__ -* `PhpConfig `__ +* `JsonConfig `__ +* `IniConfig `__ +* `PhpConfig `__ By default your application will use ``PhpConfig``. diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst index 0fb0c40e37..de471e7351 100644 --- a/en/development/dependency-injection.rst +++ b/en/development/dependency-injection.rst @@ -311,4 +311,4 @@ caching:: ); Read more about auto wiring in the `PHP League Container documentation -`_. +`_. diff --git a/en/development/testing.rst b/en/development/testing.rst index d48bd0fd6d..719deb6431 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1605,7 +1605,7 @@ make testing responses much simpler. Some examples are:: In addition to the above assertion methods, you can also use all of the assertions in `TestSuite -`_ and those +`_ and those found in `PHPUnit `__. diff --git a/en/epub-contents.rst b/en/epub-contents.rst index 149c145460..823b29183d 100644 --- a/en/epub-contents.rst +++ b/en/epub-contents.rst @@ -41,7 +41,6 @@ Contents core-libraries/app core-libraries/collections - core-libraries/file-folder core-libraries/hash core-libraries/httpclient core-libraries/inflector diff --git a/en/installation.rst b/en/installation.rst index be9af018c7..ef0a340287 100644 --- a/en/installation.rst +++ b/en/installation.rst @@ -114,8 +114,8 @@ By default this is what your application **composer.json** looks like:: } Each time you run ``php composer.phar update`` you will receive patch -releases for this minor version. You can instead change this to ``^4.4`` to -also receive the latest stable minor releases of the ``4.x`` branch. +releases for this minor version. You can instead change this to ``^5.0`` to +also receive the latest stable minor releases of the ``5.x`` branch. Installation using Oven ----------------------- diff --git a/en/pdf-contents.rst b/en/pdf-contents.rst index 5e2702f4a2..d061c5b09b 100644 --- a/en/pdf-contents.rst +++ b/en/pdf-contents.rst @@ -41,7 +41,6 @@ Contents core-libraries/app core-libraries/collections - core-libraries/file-folder core-libraries/hash core-libraries/httpclient core-libraries/inflector diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 4e9078bf9b..5f27685e1b 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -41,16 +41,16 @@ a following section. The built-in providers map to the following values of * An ``Entity`` instance or an iterator will map to `EntityContext - `_; + `_; this context class allows FormHelper to work with results from the built-in ORM. * An array containing the ``'schema'`` key, will map to - `ArrayContext `_ + `ArrayContext `_ which allows you to create simple data structures to build forms against. * ``null`` will map to - `NullContext `_; + `NullContext `_; this context class simply satisfies the interface FormHelper requires. This context is useful if you want to build a short form that doesn't require ORM persistence. @@ -332,7 +332,7 @@ While the built-in context classes are intended to cover the basic cases you'll encounter you may need to build a new context class if you are using a different ORM. In these situations you need to implement the `Cake\\View\\Form\\ContextInterface -`_ . Once +`_ . Once you have implemented this interface you can wire your new context into the FormHelper. It is often best to do this in a ``View.beforeRender`` event listener, or in an application view class:: @@ -661,10 +661,10 @@ as well as HTML attributes. This subsection will cover the options specific to As seen above you can set the error message for each validation rule you have in your models. In addition you can provide i18n messages for your forms. - + To disable the HTML entity encoding for error messages only, the ``'escape'`` sub key can be used:: - + $this->Form->control('name', [ 'error' => ['escape' => false], ]); @@ -2215,7 +2215,7 @@ List of Templates The list of default templates, their default format and the variables they expect can be found in the -`FormHelper API documentation `_. +`FormHelper API documentation `_. Using Distinct Custom Control Containers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/en/views/helpers/paginator.rst b/en/views/helpers/paginator.rst index 936a79e76b..b5aa6911ba 100644 --- a/en/views/helpers/paginator.rst +++ b/en/views/helpers/paginator.rst @@ -470,7 +470,7 @@ the PaginatorHelper available in views doesn't always need to be restricted as such. See the details on -`PaginatorHelper `_ in +`PaginatorHelper `_ in the API. As mentioned, the PaginatorHelper also offers sorting features which can be integrated into your table column headers: diff --git a/en/views/helpers/time.rst b/en/views/helpers/time.rst index 5361c1f616..775a63cf23 100644 --- a/en/views/helpers/time.rst +++ b/en/views/helpers/time.rst @@ -43,7 +43,7 @@ ORM returns :php:class:`Cake\\I18n\\Time` instances for every ``timestamp`` and ``datetime`` column, you can use the methods there to do most tasks. For example, to read about the accepted formatting strings take a look at the `Cake\\I18n\\Time::i18nFormat() -`_ method. +`_ method. .. meta:: :title lang=en: TimeHelper diff --git a/en/views/helpers/url.rst b/en/views/helpers/url.rst index e8b8a41682..58d389f40b 100644 --- a/en/views/helpers/url.rst +++ b/en/views/helpers/url.rst @@ -154,7 +154,7 @@ When using the ``assetUrlClassName`` you must implement the same methods as ``Cake\Routing\Asset`` does. For further information check -`Router::url `_ +`Router::url `_ in the API. .. meta:: From 2d59e15178f6937f35ca5204e087dd59a50594ca Mon Sep 17 00:00:00 2001 From: Hari K T Date: Mon, 18 Sep 2023 13:17:24 +0530 Subject: [PATCH 013/337] Update authentication.rst (#7714) Fix version 3.0 to support 5.x --- en/tutorials-and-examples/cms/authentication.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/authentication.rst b/en/tutorials-and-examples/cms/authentication.rst index e10d57d3c8..667c9fcc4d 100644 --- a/en/tutorials-and-examples/cms/authentication.rst +++ b/en/tutorials-and-examples/cms/authentication.rst @@ -14,7 +14,7 @@ Use composer to install the Authentication Plugin: .. code-block:: console - composer require "cakephp/authentication:^2.4" + composer require "cakephp/authentication:^3.0" Adding Password Hashing From 5ecee7f01d69141efd4deadd4dd998fd4aefd140 Mon Sep 17 00:00:00 2001 From: Hari K T Date: Mon, 18 Sep 2023 13:17:38 +0530 Subject: [PATCH 014/337] Update authorization.rst (#7715) Change version --- en/tutorials-and-examples/cms/authorization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/authorization.rst b/en/tutorials-and-examples/cms/authorization.rst index 4e97fa729e..6e2ffa8f23 100644 --- a/en/tutorials-and-examples/cms/authorization.rst +++ b/en/tutorials-and-examples/cms/authorization.rst @@ -12,7 +12,7 @@ Use composer to install the Authorization Plugin: .. code-block:: console - composer require "cakephp/authorization:^2.0" + composer require "cakephp/authorization:^3.0" Load the plugin by adding the following statement to the ``bootstrap()`` method in **src/Application.php**:: From 3a3b8b66e9e6778f186db15eb8b13ec173cd8b1b Mon Sep 17 00:00:00 2001 From: ijij <71110616+mr-ijij@users.noreply.github.com> Date: Mon, 18 Sep 2023 20:56:27 +0900 Subject: [PATCH 015/337] Update index.rst --- ja/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/index.rst b/ja/index.rst index a0ce8e6676..bc9292b66c 100644 --- a/ja/index.rst +++ b/ja/index.rst @@ -1,7 +1,7 @@ ようこそ ######## -CakePHP 4 は、 PHP |phpversion| (最小は PHP |minphpversion|) 上で動作するウェブ開発フレームワークです。 +CakePHP 5 は、 PHP |phpversion| (最小は PHP |minphpversion|) 上で動作するウェブ開発フレームワークです。 CakePHP の基礎に入門するには :doc:`CakePHP 概要 ` を読んでください。 CakePHP クックブックは、オープンに開発されている、コミュニティーで編集可能なドキュメントのプロジェクトです。 From 77d83b7d33784d4998423292b5f2cf0df0db8c45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20M=2E=20Gonz=C3=A1lez=20Mart=C3=ADn?= Date: Wed, 20 Sep 2023 15:41:43 +0100 Subject: [PATCH 016/337] Update database-basics.rst Change references from DriverInterface to Driver, add strict types to method signatures --- en/orm/database-basics.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index e45bc15b4e..5a56929b63 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -508,13 +508,13 @@ class:: namespace App\Database\Type; - use Cake\Database\DriverInterface; + use Cake\Database\Driver; use Cake\Database\Type\BaseType; use PDO; class JsonType extends BaseType { - public function toPHP($value, DriverInterface $driver) + public function toPHP(mixed $value, Driver $driver): mixed { if ($value === null) { return null; @@ -522,7 +522,7 @@ class:: return json_decode($value, true); } - public function marshal($value) + public function marshal(mixed $value): mixed { if (is_array($value) || $value === null) { return $value; @@ -530,12 +530,12 @@ class:: return json_decode($value, true); } - public function toDatabase($value, DriverInterface $driver) + public function toDatabase(mixed $value, Driver $driver): mixed { return json_encode($value); } - public function toStatement($value, DriverInterface $driver) + public function toStatement(mixed $value, Driver $driver): int { if ($value === null) { return PDO::PARAM_NULL; @@ -555,7 +555,7 @@ the type mapping. During our application bootstrap we should do the following:: use Cake\Database\TypeFactory; - TypeFactory::map('json', 'App\Database\Type\JsonType'); + TypeFactory::map('json', \App\Database\Type\JsonType:class); We then have two ways to use our datatype in our models. @@ -572,7 +572,7 @@ following:: { public function getSchema(): TableSchemaInterface { - $this->getSchema()->setColumnType('widget_prefs', 'json'); + return parent::getSchema()->setColumnType('widget_prefs', 'json'); } } @@ -586,7 +586,7 @@ used:: namespace App\Database\Type; - use Cake\Database\DriverInterface; + use Cake\Database\Driver; use Cake\Database\Type\BaseType; use Cake\Database\Type\ColumnSchemaAwareInterface; use Cake\Database\Schema\TableSchemaInterface; @@ -606,7 +606,7 @@ used:: public function getColumnSql( TableSchemaInterface $schema, string $column, - DriverInterface $driver + Driver $driver ): ?string { $data = $schema->getColumn($column); $sql = $driver->quoteIdentifier($column); @@ -625,7 +625,7 @@ used:: */ public function convertColumnDefinition( array $definition, - DriverInterface $driver + Driver $driver ): ?array { return [ 'type' => $this->_name, @@ -697,7 +697,7 @@ value object and into SQL expressions:: namespace App\Database\Type; use App\Database\Point; - use Cake\Database\DriverInterface; + use Cake\Database\Driver; use Cake\Database\Expression\FunctionExpression; use Cake\Database\ExpressionInterface; use Cake\Database\Type\BaseType; @@ -705,12 +705,12 @@ value object and into SQL expressions:: class PointType extends BaseType implements ExpressionTypeInterface { - public function toPHP($value, DriverInterface $d) + public function toPHP($value, Driver $d): mixed { return $value === null ? null : Point::parse($value); } - public function marshal($value) + public function marshal($value): mixed { if (is_string($value)) { $value = explode(',', $value); @@ -738,7 +738,7 @@ value object and into SQL expressions:: // Handle other cases. } - public function toDatabase($value, DriverInterface $driver) + public function toDatabase($value, Driver $driver): mixed { return $value; } From c5f8621d73b206bd64060b50d0c1afc90852e6ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?wowDAS=20Ing=2E=20Markus=20Ram=C5=A1ak?= Date: Thu, 21 Sep 2023 11:39:49 +0200 Subject: [PATCH 017/337] Update 5-0-migration-guide.rst typo --- en/appendices/5-0-migration-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index cd71e21dd3..d1488c7b3c 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -53,7 +53,7 @@ Cache Console ------- -- ``BaseCommand::__constructor()`` was removed. +- ``BaseCommand::__construct()`` was removed. - ``ConsoleIntegrationTestTrait::useCommandRunner()`` was removed since it's no longer needed. - ``Shell`` has been removed and should be replaced with `Command `__ - ``BaseCommand`` now emits ``Command.beforeExecute`` and @@ -72,7 +72,7 @@ Connection Controller ---------- -- The method signature for ``Controller::__constructor()`` has changed. +- 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 From 8b51f7a7860ac10d398c5da599096ccf439f02b4 Mon Sep 17 00:00:00 2001 From: Alex Mayer Date: Thu, 21 Sep 2023 11:52:26 -0400 Subject: [PATCH 018/337] Remove Double Slash From AbstractTransport Class Name --- en/core-libraries/email.rst | 2 +- fr/core-libraries/email.rst | 2 +- pt/core-libraries/email.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/en/core-libraries/email.rst b/en/core-libraries/email.rst index 0c81dbd685..9b40fa1acf 100644 --- a/en/core-libraries/email.rst +++ b/en/core-libraries/email.rst @@ -529,7 +529,7 @@ Sending emails without using Mailer =================================== The ``Mailer`` is a higher level abstraction class which acts as a bridge between -the ``Cake\Mailer\Message``, ``Cake\Mailer\Renderer`` and ``Cake\Mailer\\AbstractTransport`` +the ``Cake\Mailer\Message``, ``Cake\Mailer\Renderer`` and ``Cake\Mailer\AbstractTransport`` classes to configure emails with a fluent interface. If you want you can use these classes directly with the ``Mailer`` too. diff --git a/fr/core-libraries/email.rst b/fr/core-libraries/email.rst index 7711a1cbb4..b28dad2cf6 100644 --- a/fr/core-libraries/email.rst +++ b/fr/core-libraries/email.rst @@ -601,7 +601,7 @@ Envoyer des Emails sans utiliser Mailer Le ``Mailer`` est une classe à haut niveau d'abstraction, qui agit commme un pont entre les classes ``Cake\Mailer\Message``, ``Cake\Mailer\Renderer`` et -``Cake\Mailer\\AbstractTransport`` pour configuer les emails avec une interface +``Cake\Mailer\AbstractTransport`` pour configuer les emails avec une interface fluide. Si vous voulez, vous pouvez aussi utiliser ces classes directement avec le diff --git a/pt/core-libraries/email.rst b/pt/core-libraries/email.rst index 5ff3b7bba0..2dce0dcc7f 100644 --- a/pt/core-libraries/email.rst +++ b/pt/core-libraries/email.rst @@ -553,7 +553,7 @@ Enviar Emails sem Usar o Mailer =============================== O ``Mailer`` é uma classe de abstração de nível superior que atua como uma ponte entre as -classes ``Cake\Mailer\Message``, ``Cake\Mailer\Renderer`` e ``Cake\Mailer\\AbstractTransport`` +classes ``Cake\Mailer\Message``, ``Cake\Mailer\Renderer`` e ``Cake\Mailer\AbstractTransport`` para facilitar a configuração e entrega do e-mail. Se você quiser, pode usar essas classes diretamente com o ``Mailer`` também. From 2e95213a6d1d79ec7002bc2d50c0219482d2fd32 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 24 Sep 2023 04:54:55 -0400 Subject: [PATCH 019/337] 5.x Update error handling docs (#7724) - Remove outdated information - Exclude exception classes from the table of contents. --- en/development/errors.rst | 323 ++++++++++++++------------------------ 1 file changed, 115 insertions(+), 208 deletions(-) diff --git a/en/development/errors.rst b/en/development/errors.rst index 0642aad342..0ed86d1a7d 100644 --- a/en/development/errors.rst +++ b/en/development/errors.rst @@ -7,8 +7,8 @@ into error pages automatically. .. _error-configuration: -Error & Exception Configuration -=============================== +Configuration +============= Error configuration is done in your application's **config/app.php** file. By default CakePHP uses ``Cake\Error\ErrorTrap`` and ``Cake\Error\ExceptionTrap`` @@ -58,7 +58,7 @@ message, file and line (``debug`` enabled). .. _deprecation-warnings: Deprecation Warnings --------------------- +==================== CakePHP uses deprecation warnings to indicate when features have been deprecated. We also recommend this system for use in your plugins and @@ -85,25 +85,25 @@ You can temporarily disable deprecation warnings in one of a few ways: Would ignore all deprecations from your ``Models`` directory and the ``Contacts`` plugin in your application. -.. php:class:: ExceptionRenderer(Exception $exception) - Changing Exception Handling =========================== -Exception handling offers several ways to tailor how exceptions are handled. Each -approach gives you different amounts of control over the exception handling -process. +Exception handling in CakePHP offers several ways to tailor how exceptions are +handled. Each approach gives you different amounts of control over the +exception handling process. #. *Listen to events* This allows you to be notified through CakePHP events when errors and exceptions have been handled. -#. *Custom error templates* This allows you to change the rendered view +#. *Custom templates* This allows you to change the rendered view templates as you would any other template in your application. -#. *Custom ErrorController* This allows you to control how exception +#. *Custom Controller* This allows you to control how exception pages are rendered. #. *Custom ExceptionRenderer* This allows you to control how exception pages and logging are performed. -#. *Create & register your own error handler* This gives you complete - control over how errors & exceptions are handled, logged and rendered. +#. *Create & register your own traps* This gives you complete + control over how errors & exceptions are handled, logged and rendered. Use + ``Cake\Error\ExceptionTrap`` and ``Cake\Error\ErrorTrap`` as reference when + implementing your traps. Listen to Events ================ @@ -136,11 +136,11 @@ Within an ``Exception.beforeRender`` handler you have a few options: .. _error-views: -Custom Error Templates -====================== +Custom Templates +================ -The default error handler renders all uncaught exceptions your application -raises with the help of ``Cake\Error\ExceptionRenderer``, and your application's +The default exception trap renders all uncaught exceptions your application +raises with the help of ``Cake\Error\WebExceptionRenderer``, and your application's ``ErrorController``. The error page views are located at **templates/Error/**. All 4xx errors use @@ -176,8 +176,8 @@ Many exceptions raised by CakePHP will render specific view templates in debug mode. With debug turned off all exceptions raised by CakePHP will use either **error400.php** or **error500.php** based on their status code. -Custom ErrorController -====================== +Custom Controller +================= The ``App\Controller\ErrorController`` class is used by CakePHP's exception rendering to render the error page view and receives all the standard request @@ -219,7 +219,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 the overall rendering process. +choose the 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 @@ -229,9 +229,9 @@ error pages when this error is handled:: // In src/Error/AppExceptionRenderer.php namespace App\Error; - use Cake\Error\ExceptionRenderer; + use Cake\Error\WebExceptionRenderer; - class AppExceptionRenderer extends ExceptionRenderer + class AppExceptionRenderer extends WebExceptionRenderer { public function missingWidget($error) { @@ -259,9 +259,9 @@ additional logic when handling CakePHP errors:: // In src/Error/AppExceptionRenderer.php namespace App\Error; - use Cake\Error\ExceptionRenderer; + use Cake\Error\WebExceptionRenderer; - class AppExceptionRenderer extends ExceptionRenderer + class AppExceptionRenderer extends WebExceptionRenderer { public function notFound($error) { @@ -281,9 +281,9 @@ override the ``_getController()`` method in your exception renderer:: use App\Controller\SuperCustomErrorController; use Cake\Controller\Controller; - use Cake\Error\ExceptionRenderer; + use Cake\Error\WebExceptionRenderer; - class AppExceptionRenderer extends ExceptionRenderer + class AppExceptionRenderer extends WebExceptionRenderer { protected function _getController(): Controller { @@ -298,103 +298,6 @@ override the ``_getController()`` method in your exception renderer:: ], // ... -Custom Error Logging -==================== - -Error handlers use instances of ``Cake\Error\ErrorLoggingInterface`` to create -log messages and log them to the appropriate place. You can replace the error -logger using the ``Error.errorLogger`` configure value. An example error -logger:: - - namespace App\Error; - - use Cake\Error\ErrorLoggerInterface; - use Cake\Error\PhpError; - use Psr\Http\Message\ServerRequestInterface; - use Throwable; - - /** - * Log errors and unhandled exceptions to `Cake\Log\Log` - */ - class ErrorLogger implements ErrorLoggerInterface - { - /** - * @inheritDoc - */ - public function logError( - PhpError $error, - ?ServerRequestInterface $request, - bool $includeTrace = false - ): void { - // Log PHP Errors - } - - /** - * @inheritDoc - */ - public function logException( - ?ServerRequestInterface $request, - bool $includeTrace = false - ): void { - // Log exceptions. - } - } - -Prior to CakePHP 4.4.0, you should implement ``logMessage()`` and ``log()``:: - - namespace App\Error; - - use Cake\Error\ErrorLoggerInterface; - use Psr\Http\Message\ServerRequestInterface; - use Throwable; - - /** - * Log errors and unhandled exceptions to `Cake\Log\Log` - */ - class ErrorLogger implements ErrorLoggerInterface - { - /** - * @inheritDoc - */ - public function logMessage($level, string $message, array $context = []): bool - { - // Log PHP Errors - } - - public function log(Throwable $exception, ?ServerRequestInterface $request = null): bool - { - // Log exceptions. - } - } - -Custom Error Rendering -====================== - -By default CakePHP ships with error renderers for both web and console -environments. If however, you would like to replace the logic that renders -errors you can create a class:: - - // src/Error/CustomErrorRenderer.php - namespace App\Error; - - use Cake\Error\ErrorRendererInterface; - use Cake\Error\PhpError; - - class CustomErrorRenderer implements ErrorRendererInterface - { - public function write(string $out): void - { - // output the rendered error to the appropriate output stream - } - - public function render(PhpError $error, bool $debug): string - { - // Convert the error into the output string. - } - } - -The constructor of your renderer will be passed an array of all the Error -configuration. .. index:: application exceptions @@ -476,52 +379,64 @@ internal framework exceptions, there are several exceptions for HTTP methods .. php:exception:: BadRequestException + :nocontentsentry: Used for doing 400 Bad Request error. .. php:exception:: UnauthorizedException + :nocontentsentry: Used for doing a 401 Unauthorized error. .. php:exception:: ForbiddenException + :nocontentsentry: Used for doing a 403 Forbidden error. .. php:exception:: InvalidCsrfTokenException + :nocontentsentry: Used for doing a 403 error caused by an invalid CSRF token. .. php:exception:: NotFoundException + :nocontentsentry: Used for doing a 404 Not found error. .. php:exception:: MethodNotAllowedException + :nocontentsentry: Used for doing a 405 Method Not Allowed error. .. php:exception:: NotAcceptableException + :nocontentsentry: Used for doing a 406 Not Acceptable error. .. php:exception:: ConflictException + :nocontentsentry: Used for doing a 409 Conflict error. .. php:exception:: GoneException + :nocontentsentry: Used for doing a 410 Gone error. For more details on HTTP 4xx error status codes see :rfc:`2616#section-10.4`. .. php:exception:: InternalErrorException + :nocontentsentry: Used for doing a 500 Internal Server Error. .. php:exception:: NotImplementedException + :nocontentsentry: Used for doing a 501 Not Implemented Errors. .. php:exception:: ServiceUnavailableException + :nocontentsentry: Used for doing a 503 Service Unavailable error. @@ -576,82 +491,100 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\View\Exception .. php:exception:: MissingViewException + :nocontentsentry: The chosen view class could not be found. .. php:exception:: MissingTemplateException + :nocontentsentry: The chosen template file could not be found. .. php:exception:: MissingLayoutException + :nocontentsentry: The chosen layout could not be found. .. php:exception:: MissingHelperException + :nocontentsentry: The chosen helper could not be found. .. php:exception:: MissingElementException + :nocontentsentry: The chosen element file could not be found. .. php:exception:: MissingCellException + :nocontentsentry: The chosen cell class could not be found. .. php:exception:: MissingCellViewException + :nocontentsentry: The chosen cell view file could not be found. .. php:namespace:: Cake\Controller\Exception .. php:exception:: MissingComponentException + :nocontentsentry: A configured component could not be found. .. php:exception:: MissingActionException + :nocontentsentry: The requested controller action could not be found. .. php:exception:: PrivateActionException + :nocontentsentry: Accessing private/protected/_ prefixed actions. .. php:namespace:: Cake\Console\Exception .. php:exception:: ConsoleException + :nocontentsentry: A console library class encounter an error. .. php:namespace:: Cake\Database\Exception .. php:exception:: MissingConnectionException + :nocontentsentry: A model's connection is missing. .. php:exception:: MissingDriverException + :nocontentsentry: A database driver could not be found. .. php:exception:: MissingExtensionException + :nocontentsentry: A PHP extension is missing for the database driver. .. php:namespace:: Cake\ORM\Exception .. php:exception:: MissingTableException + :nocontentsentry: A model's table could not be found. .. php:exception:: MissingEntityException + :nocontentsentry: A model's entity could not be found. .. php:exception:: MissingBehaviorException + :nocontentsentry: A model's behavior could not be found. .. php:exception:: PersistenceFailedException + :nocontentsentry: An entity couldn't be saved/deleted while using :php:meth:`Cake\\ORM\\Table::saveOrFail()` or :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. @@ -659,6 +592,7 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Datasource\Exception .. php:exception:: RecordNotFoundException + :nocontentsentry: The requested record could not be found. This will also set HTTP response headers to 404. @@ -666,20 +600,24 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Routing\Exception .. php:exception:: MissingControllerException + :nocontentsentry: The requested controller could not be found. .. php:exception:: MissingRouteException + :nocontentsentry: The requested URL cannot be reverse routed or cannot be parsed. .. php:exception:: MissingDispatcherFilterException + :nocontentsentry: The dispatcher filter could not be found. .. php:namespace:: Cake\Core\Exception .. php:exception:: Exception + :nocontentsentry: Base exception class in CakePHP. All framework layer exceptions thrown by CakePHP will extend this class. @@ -698,117 +636,86 @@ MethodNotAllowedException the rfc2616 says:: "The response MUST include an Allow header containing a list of valid methods for the requested resource." -Creating your Own Error Handler -=============================== -.. deprecated:: 4.4.0 - ``ErrorHandler`` has been deprecated. Use ``ErrorTrap`` or ``ExceptionTrap`` - instead. +Customizing PHP Error Handling +============================== + +By default PHP errors are rendered to console or HTML output, and also logged. +If necessary, you can swap out CakePHP's error handling logic with your own. -By replacing the error handler you can customize how PHP errors and exceptions -that are not caught by middleware are handled. Error handlers are different for -the HTTP and Console parts of your application. +Custom Error Logging +-------------------- -To create an error handler for HTTP requests, you should extend -``Cake\Error\ErrorHandler``. As an example, we could build -a class called ``AppError`` to handle errors during HTTP requests:: +Error handlers use instances of ``Cake\Error\ErrorLoggingInterface`` to create +log messages and log them to the appropriate place. You can replace the error +logger using the ``Error.errorLogger`` configure value. An example error +logger:: - // In src/Error/AppError.php namespace App\Error; - use Cake\Error\ErrorHandler; + use Cake\Error\ErrorLoggerInterface; + use Cake\Error\PhpError; + use Psr\Http\Message\ServerRequestInterface; use Throwable; - class AppError extends ErrorHandler + /** + * Log errors and unhandled exceptions to `Cake\Log\Log` + */ + class ErrorLogger implements ErrorLoggerInterface { - protected function _displayError(array $error, bool $debug): void - { - echo 'There has been an error!'; - } - - protected function _displayException(Throwable $exception): void - { - echo 'There has been an exception!'; + /** + * @inheritDoc + */ + public function logError( + PhpError $error, + ?ServerRequestInterface $request, + bool $includeTrace = false + ): void { + // Log PHP Errors } - } -Then we can register our error handler as the PHP error handler:: - - // In config/bootstrap.php - use App\Error\AppError; - - if (PHP_SAPI !== 'cli') { - $errorHandler = new AppError(); - $errorHandler->register(); - } - -Finally, we can use our error handler in the ``ErrorHandlerMiddleware``:: - - // in src/Application.php - public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue - { - $error = new AppError(Configure::read('Error')); - $middleware->add(new ErrorHandlerMiddleware($error)); - - return $middleware; - } - -For console error handling, you should extend ``Cake\Error\ConsoleErrorHandler`` instead:: - - // In /src/Error/AppConsoleErrorHandler.php - namespace App\Error; - use Cake\Error\ConsoleErrorHandler; - - class AppConsoleErrorHandler extends ConsoleErrorHandler { - - protected function _displayException(Throwable $exception): void { - parent::_displayException($exception); - if (isset($exception->queryString)) { - $this->_stderr->write('Query String: ' . $exception->queryString); - } + /** + * @inheritDoc + */ + public function logException( + ?ServerRequestInterface $request, + bool $includeTrace = false + ): void { + // Log exceptions. } - } -Then we can register our console error handler as the PHP error handler:: - - // In config/bootstrap.php - use App\Error\AppConsoleErrorHandler; - $isCli = PHP_SAPI === 'cli'; - if ($isCli) { - (new AppConsoleErrorHandler(Configure::read('Error')))->register(); - } - -ErrorHandler objects have a few methods you may want to implement: - -* ``_displayError(array $error, bool $debug)`` is used when errors are triggered. -* ``_displayException(Throwable $exception)`` method is called when there is an uncaught exception. -* ``_logError($level, array $error)`` is called when there is an error to log. -* ``logException(Throwable $exception)`` is called when there is an exception to log. - - -Changing Fatal Error Behavior ------------------------------ +Custom Error Rendering +---------------------- -Error handlers convert fatal errors into exceptions and re-use the -exception handling logic to render an error page. If you do not want to show the -standard error page, you can override it:: +CakePHP includes error renderers for both web and console environments. If +however, you would like to replace the logic that renders errors you can create +a class:: - // In src/Error/AppError.php + // src/Error/CustomErrorRenderer.php namespace App\Error; - use Cake\Error\BaseErrorHandler; + use Cake\Error\ErrorRendererInterface; + use Cake\Error\PhpError; - class AppError extends BaseErrorHandler + class CustomErrorRenderer implements ErrorRendererInterface { - // Other methods. + public function write(string $out): void + { + // output the rendered error to the appropriate output stream + } - public function handleFatalError(int $code, string $description, string $file, int $line): bool + public function render(PhpError $error, bool $debug): string { - echo 'A fatal error has happened'; + // Convert the error into the output string. } } +The constructor of your renderer will be passed an array of all the Error +configuration. You connect your custom error renderer to CakePHP via the +``Error.errorRenderer`` config value. When replacing error handling you will +need to account for both web and command line environments. + .. meta:: :title lang=en: Error & Exception Handling :keywords lang=en: stack traces,error constants,error array,default displays,anonymous functions,error handlers,default error,error level,exception handler,php error,error handler,write error,core classes,exception handling,configuration error,application code,callback,custom error,exceptions,bitmasks,fatal error, http status codes From 4b974ac24039438a409cdaa67cd18eaa829b0fb9 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Sun, 24 Sep 2023 11:23:04 +0200 Subject: [PATCH 020/337] fix exception docs --- en/development/errors.rst | 35 ----------------------------------- 1 file changed, 35 deletions(-) diff --git a/en/development/errors.rst b/en/development/errors.rst index 0ed86d1a7d..9c4b5cd461 100644 --- a/en/development/errors.rst +++ b/en/development/errors.rst @@ -379,64 +379,52 @@ internal framework exceptions, there are several exceptions for HTTP methods .. php:exception:: BadRequestException - :nocontentsentry: Used for doing 400 Bad Request error. .. php:exception:: UnauthorizedException - :nocontentsentry: Used for doing a 401 Unauthorized error. .. php:exception:: ForbiddenException - :nocontentsentry: Used for doing a 403 Forbidden error. .. php:exception:: InvalidCsrfTokenException - :nocontentsentry: Used for doing a 403 error caused by an invalid CSRF token. .. php:exception:: NotFoundException - :nocontentsentry: Used for doing a 404 Not found error. .. php:exception:: MethodNotAllowedException - :nocontentsentry: Used for doing a 405 Method Not Allowed error. .. php:exception:: NotAcceptableException - :nocontentsentry: Used for doing a 406 Not Acceptable error. .. php:exception:: ConflictException - :nocontentsentry: Used for doing a 409 Conflict error. .. php:exception:: GoneException - :nocontentsentry: Used for doing a 410 Gone error. For more details on HTTP 4xx error status codes see :rfc:`2616#section-10.4`. .. php:exception:: InternalErrorException - :nocontentsentry: Used for doing a 500 Internal Server Error. .. php:exception:: NotImplementedException - :nocontentsentry: Used for doing a 501 Not Implemented Errors. .. php:exception:: ServiceUnavailableException - :nocontentsentry: Used for doing a 503 Service Unavailable error. @@ -491,100 +479,82 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\View\Exception .. php:exception:: MissingViewException - :nocontentsentry: The chosen view class could not be found. .. php:exception:: MissingTemplateException - :nocontentsentry: The chosen template file could not be found. .. php:exception:: MissingLayoutException - :nocontentsentry: The chosen layout could not be found. .. php:exception:: MissingHelperException - :nocontentsentry: The chosen helper could not be found. .. php:exception:: MissingElementException - :nocontentsentry: The chosen element file could not be found. .. php:exception:: MissingCellException - :nocontentsentry: The chosen cell class could not be found. .. php:exception:: MissingCellViewException - :nocontentsentry: The chosen cell view file could not be found. .. php:namespace:: Cake\Controller\Exception .. php:exception:: MissingComponentException - :nocontentsentry: A configured component could not be found. .. php:exception:: MissingActionException - :nocontentsentry: The requested controller action could not be found. .. php:exception:: PrivateActionException - :nocontentsentry: Accessing private/protected/_ prefixed actions. .. php:namespace:: Cake\Console\Exception .. php:exception:: ConsoleException - :nocontentsentry: A console library class encounter an error. .. php:namespace:: Cake\Database\Exception .. php:exception:: MissingConnectionException - :nocontentsentry: A model's connection is missing. .. php:exception:: MissingDriverException - :nocontentsentry: A database driver could not be found. .. php:exception:: MissingExtensionException - :nocontentsentry: A PHP extension is missing for the database driver. .. php:namespace:: Cake\ORM\Exception .. php:exception:: MissingTableException - :nocontentsentry: A model's table could not be found. .. php:exception:: MissingEntityException - :nocontentsentry: A model's entity could not be found. .. php:exception:: MissingBehaviorException - :nocontentsentry: A model's behavior could not be found. .. php:exception:: PersistenceFailedException - :nocontentsentry: An entity couldn't be saved/deleted while using :php:meth:`Cake\\ORM\\Table::saveOrFail()` or :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. @@ -592,7 +562,6 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Datasource\Exception .. php:exception:: RecordNotFoundException - :nocontentsentry: The requested record could not be found. This will also set HTTP response headers to 404. @@ -600,24 +569,20 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Routing\Exception .. php:exception:: MissingControllerException - :nocontentsentry: The requested controller could not be found. .. php:exception:: MissingRouteException - :nocontentsentry: The requested URL cannot be reverse routed or cannot be parsed. .. php:exception:: MissingDispatcherFilterException - :nocontentsentry: The dispatcher filter could not be found. .. php:namespace:: Cake\Core\Exception .. php:exception:: Exception - :nocontentsentry: Base exception class in CakePHP. All framework layer exceptions thrown by CakePHP will extend this class. From 8d6ed105adde2ccc08d9c7eee5212c0de597e153 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 24 Sep 2023 22:55:29 -0400 Subject: [PATCH 021/337] Fix indentation in no-contents-entry usage. --- en/development/errors.rst | 39 +++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/en/development/errors.rst b/en/development/errors.rst index 9c4b5cd461..0bb33e1b8f 100644 --- a/en/development/errors.rst +++ b/en/development/errors.rst @@ -379,52 +379,64 @@ internal framework exceptions, there are several exceptions for HTTP methods .. php:exception:: BadRequestException + :no-contents-entry: Used for doing 400 Bad Request error. .. php:exception:: UnauthorizedException + :no-contents-entry: Used for doing a 401 Unauthorized error. .. php:exception:: ForbiddenException + :no-contents-entry: Used for doing a 403 Forbidden error. .. php:exception:: InvalidCsrfTokenException + :no-contents-entry: Used for doing a 403 error caused by an invalid CSRF token. .. php:exception:: NotFoundException + :no-contents-entry: Used for doing a 404 Not found error. .. php:exception:: MethodNotAllowedException + :no-contents-entry: Used for doing a 405 Method Not Allowed error. .. php:exception:: NotAcceptableException + :no-contents-entry: Used for doing a 406 Not Acceptable error. .. php:exception:: ConflictException + :no-contents-entry: Used for doing a 409 Conflict error. .. php:exception:: GoneException + :no-contents-entry: Used for doing a 410 Gone error. For more details on HTTP 4xx error status codes see :rfc:`2616#section-10.4`. .. php:exception:: InternalErrorException + :no-contents-entry: Used for doing a 500 Internal Server Error. .. php:exception:: NotImplementedException + :no-contents-entry: Used for doing a 501 Not Implemented Errors. .. php:exception:: ServiceUnavailableException + :no-contents-entry: Used for doing a 503 Service Unavailable error. @@ -479,82 +491,100 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\View\Exception .. php:exception:: MissingViewException + :no-contents-entry: The chosen view class could not be found. .. php:exception:: MissingTemplateException + :no-contents-entry: The chosen template file could not be found. .. php:exception:: MissingLayoutException + :no-contents-entry: The chosen layout could not be found. .. php:exception:: MissingHelperException + :no-contents-entry: The chosen helper could not be found. .. php:exception:: MissingElementException + :no-contents-entry: The chosen element file could not be found. .. php:exception:: MissingCellException + :no-contents-entry: The chosen cell class could not be found. .. php:exception:: MissingCellViewException + :no-contents-entry: The chosen cell view file could not be found. .. php:namespace:: Cake\Controller\Exception .. php:exception:: MissingComponentException + :no-contents-entry: A configured component could not be found. .. php:exception:: MissingActionException + :no-contents-entry: The requested controller action could not be found. .. php:exception:: PrivateActionException + :no-contents-entry: Accessing private/protected/_ prefixed actions. .. php:namespace:: Cake\Console\Exception .. php:exception:: ConsoleException + :no-contents-entry: A console library class encounter an error. .. php:namespace:: Cake\Database\Exception .. php:exception:: MissingConnectionException + :no-contents-entry: A model's connection is missing. .. php:exception:: MissingDriverException + :no-contents-entry: A database driver could not be found. .. php:exception:: MissingExtensionException + :no-contents-entry: A PHP extension is missing for the database driver. .. php:namespace:: Cake\ORM\Exception .. php:exception:: MissingTableException + :no-contents-entry: A model's table could not be found. .. php:exception:: MissingEntityException + :no-contents-entry: A model's entity could not be found. .. php:exception:: MissingBehaviorException + :no-contents-entry: A model's behavior could not be found. .. php:exception:: PersistenceFailedException + :no-contents-entry: An entity couldn't be saved/deleted while using :php:meth:`Cake\\ORM\\Table::saveOrFail()` or :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. @@ -562,6 +592,7 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Datasource\Exception .. php:exception:: RecordNotFoundException + :no-contents-entry: The requested record could not be found. This will also set HTTP response headers to 404. @@ -569,20 +600,19 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Routing\Exception .. php:exception:: MissingControllerException + :no-contents-entry: The requested controller could not be found. .. php:exception:: MissingRouteException + :no-contents-entry: The requested URL cannot be reverse routed or cannot be parsed. -.. php:exception:: MissingDispatcherFilterException - - The dispatcher filter could not be found. - .. php:namespace:: Cake\Core\Exception .. php:exception:: Exception + :no-contents-entry: Base exception class in CakePHP. All framework layer exceptions thrown by CakePHP will extend this class. @@ -591,6 +621,7 @@ These exception classes all extend :php:exc:`Exception`. By extending Exception, you can create your own 'framework' errors. .. php:method:: responseHeader($header = null, $value = null) + :no-contents-entry: See :php:func:`Cake\\Network\\Request::header()` From 3aa6b284a06854976599857cd21014b5dd48a337 Mon Sep 17 00:00:00 2001 From: ADmad Date: Mon, 25 Sep 2023 09:00:30 +0530 Subject: [PATCH 022/337] Update pagination docs. Passing query options to the paginator is no longer supported. --- en/appendices/5-0-migration-guide.rst | 5 +++++ en/controllers/pagination.rst | 29 +++++---------------------- 2 files changed, 10 insertions(+), 24 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index d1488c7b3c..2c4358ed66 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -84,6 +84,11 @@ Controller - ``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 ---- diff --git a/en/controllers/pagination.rst b/en/controllers/pagination.rst index fd24fb865f..ea1da541a0 100644 --- a/en/controllers/pagination.rst +++ b/en/controllers/pagination.rst @@ -26,8 +26,8 @@ You can call ``paginate()`` using an ORM table instance or ``Query`` object:: // Paginate the ORM table. $this->set('articles', $this->paginate($this->Articles)); - // Paginate a partially completed query - $query = $this->Articles->find('published'); + // Paginate a select query + $query = $this->Articles->find('published')->contain('Comments'); $this->set('articles', $this->paginate($query)); } @@ -53,11 +53,7 @@ from the URL:: .. tip:: Default ``order`` options must be defined as an array. -While you can include any of the options supported by -:php:meth:`~Cake\\ORM\\Table::find()` such as ``fields`` in your pagination -settings. It is cleaner and simpler to bundle your pagination options into -a :ref:`custom-find-methods`. You can use your finder in pagination by using the -``finder`` option:: +You can also use :ref:`custom-find-methods` in pagination by using the ``finder`` option:: class ArticlesController extends AppController { @@ -108,8 +104,8 @@ as a key in the ``$paginate`` property:: ]; } -The values of the ``Articles`` and ``Authors`` keys could contain all the -properties that a basic ``$paginate`` array would. +The values of the ``Articles`` and ``Authors`` keys could contain all the keys +that a basic ``$paginate`` array would. ``Controller::paginate()`` returns an instance of ``Cake\Datasource\Paging\PaginatedResultSet`` which implements the ``Cake\Datasource\Paging\PaginatedInterface``. @@ -245,21 +241,6 @@ example reducing it to ``10``:: If the request's limit param is greater than this value, it will be reduced to the ``maxLimit`` value. -Joining Additional Associations -=============================== - -Additional associations can be loaded to the paginated table by using the -``contain`` parameter:: - - public function index() - { - $this->paginate = [ - 'contain' => ['Authors', 'Comments'] - ]; - - $this->set('articles', $this->paginate($this->Articles)); - } - Out of Range Page Requests ========================== From e7d560d3811f7e45d3c260dde20293cb5472dc19 Mon Sep 17 00:00:00 2001 From: Corey Taylor Date: Mon, 25 Sep 2023 06:20:12 -0500 Subject: [PATCH 023/337] Fix nocontentsentry domain option --- en/development/errors.rst | 70 +++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/en/development/errors.rst b/en/development/errors.rst index 0bb33e1b8f..1bdabf4e6b 100644 --- a/en/development/errors.rst +++ b/en/development/errors.rst @@ -379,64 +379,64 @@ internal framework exceptions, there are several exceptions for HTTP methods .. php:exception:: BadRequestException - :no-contents-entry: + :nocontentsentry: Used for doing 400 Bad Request error. .. php:exception:: UnauthorizedException - :no-contents-entry: + :nocontentsentry: Used for doing a 401 Unauthorized error. .. php:exception:: ForbiddenException - :no-contents-entry: + :nocontentsentry: Used for doing a 403 Forbidden error. .. php:exception:: InvalidCsrfTokenException - :no-contents-entry: + :nocontentsentry: Used for doing a 403 error caused by an invalid CSRF token. .. php:exception:: NotFoundException - :no-contents-entry: + :nocontentsentry: Used for doing a 404 Not found error. .. php:exception:: MethodNotAllowedException - :no-contents-entry: + :nocontentsentry: Used for doing a 405 Method Not Allowed error. .. php:exception:: NotAcceptableException - :no-contents-entry: + :nocontentsentry: Used for doing a 406 Not Acceptable error. .. php:exception:: ConflictException - :no-contents-entry: + :nocontentsentry: Used for doing a 409 Conflict error. .. php:exception:: GoneException - :no-contents-entry: + :nocontentsentry: Used for doing a 410 Gone error. For more details on HTTP 4xx error status codes see :rfc:`2616#section-10.4`. .. php:exception:: InternalErrorException - :no-contents-entry: + :nocontentsentry: Used for doing a 500 Internal Server Error. .. php:exception:: NotImplementedException - :no-contents-entry: + :nocontentsentry: Used for doing a 501 Not Implemented Errors. .. php:exception:: ServiceUnavailableException - :no-contents-entry: + :nocontentsentry: Used for doing a 503 Service Unavailable error. @@ -491,100 +491,100 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\View\Exception .. php:exception:: MissingViewException - :no-contents-entry: + :nocontentsentry: The chosen view class could not be found. .. php:exception:: MissingTemplateException - :no-contents-entry: + :nocontentsentry: The chosen template file could not be found. .. php:exception:: MissingLayoutException - :no-contents-entry: + :nocontentsentry: The chosen layout could not be found. .. php:exception:: MissingHelperException - :no-contents-entry: + :nocontentsentry: The chosen helper could not be found. .. php:exception:: MissingElementException - :no-contents-entry: + :nocontentsentry: The chosen element file could not be found. .. php:exception:: MissingCellException - :no-contents-entry: + :nocontentsentry: The chosen cell class could not be found. .. php:exception:: MissingCellViewException - :no-contents-entry: + :nocontentsentry: The chosen cell view file could not be found. .. php:namespace:: Cake\Controller\Exception .. php:exception:: MissingComponentException - :no-contents-entry: + :nocontentsentry: A configured component could not be found. .. php:exception:: MissingActionException - :no-contents-entry: + :nocontentsentry: The requested controller action could not be found. .. php:exception:: PrivateActionException - :no-contents-entry: + :nocontentsentry: Accessing private/protected/_ prefixed actions. .. php:namespace:: Cake\Console\Exception .. php:exception:: ConsoleException - :no-contents-entry: + :nocontentsentry: A console library class encounter an error. .. php:namespace:: Cake\Database\Exception .. php:exception:: MissingConnectionException - :no-contents-entry: + :nocontentsentry: A model's connection is missing. .. php:exception:: MissingDriverException - :no-contents-entry: + :nocontentsentry: A database driver could not be found. .. php:exception:: MissingExtensionException - :no-contents-entry: + :nocontentsentry: A PHP extension is missing for the database driver. .. php:namespace:: Cake\ORM\Exception .. php:exception:: MissingTableException - :no-contents-entry: + :nocontentsentry: A model's table could not be found. .. php:exception:: MissingEntityException - :no-contents-entry: + :nocontentsentry: A model's entity could not be found. .. php:exception:: MissingBehaviorException - :no-contents-entry: + :nocontentsentry: A model's behavior could not be found. .. php:exception:: PersistenceFailedException - :no-contents-entry: + :nocontentsentry: An entity couldn't be saved/deleted while using :php:meth:`Cake\\ORM\\Table::saveOrFail()` or :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. @@ -592,7 +592,7 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Datasource\Exception .. php:exception:: RecordNotFoundException - :no-contents-entry: + :nocontentsentry: The requested record could not be found. This will also set HTTP response headers to 404. @@ -600,19 +600,19 @@ In addition, CakePHP uses the following exceptions: .. php:namespace:: Cake\Routing\Exception .. php:exception:: MissingControllerException - :no-contents-entry: + :nocontentsentry: The requested controller could not be found. .. php:exception:: MissingRouteException - :no-contents-entry: + :nocontentsentry: The requested URL cannot be reverse routed or cannot be parsed. .. php:namespace:: Cake\Core\Exception .. php:exception:: Exception - :no-contents-entry: + :nocontentsentry: Base exception class in CakePHP. All framework layer exceptions thrown by CakePHP will extend this class. @@ -621,7 +621,7 @@ These exception classes all extend :php:exc:`Exception`. By extending Exception, you can create your own 'framework' errors. .. php:method:: responseHeader($header = null, $value = null) - :no-contents-entry: + :nocontentsentry: See :php:func:`Cake\\Network\\Request::header()` From ba0922d3f7d9b9f1c6d50d41e19c193bd60dcce2 Mon Sep 17 00:00:00 2001 From: ADmad Date: Mon, 25 Sep 2023 19:32:26 +0530 Subject: [PATCH 024/337] Fix code example Closes cakephp/cakephp#17313 --- en/tutorials-and-examples/cms/database.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/database.rst b/en/tutorials-and-examples/cms/database.rst index 575e3aedc0..cc30579208 100644 --- a/en/tutorials-and-examples/cms/database.rst +++ b/en/tutorials-and-examples/cms/database.rst @@ -212,7 +212,7 @@ look like this:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false, 'slug' => false, From 945823f486944dd1eaf24ba62b267c30bffd3029 Mon Sep 17 00:00:00 2001 From: Robert Zelnik Date: Tue, 26 Sep 2023 05:25:15 +0200 Subject: [PATCH 025/337] Update tags-and-users.rst $_accessible should be declared as array, according to https://github.com/cakephp/docs/commit/ba0922d3f7d9b9f1c6d50d41e19c193bd60dcce2 --- en/tutorials-and-examples/cms/tags-and-users.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/tags-and-users.rst b/en/tutorials-and-examples/cms/tags-and-users.rst index f69adb2322..4adb88cabe 100644 --- a/en/tutorials-and-examples/cms/tags-and-users.rst +++ b/en/tutorials-and-examples/cms/tags-and-users.rst @@ -334,7 +334,7 @@ can add a virtual/computed field to the entity. In use Cake\Collection\Collection; // Update the accessible property to contain `tag_string` - protected $_accessible = [ + protected array $_accessible = [ //other fields... 'tag_string' => true ]; From 5cb5512dbd8604218904b7676e52df8831aafc8c Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 25 Sep 2023 23:50:14 -0400 Subject: [PATCH 026/337] Fix more occurrences of $_accessible Add the missing array typehint to other occurrences of $_accessible Refs #7728 --- en/orm/entities.rst | 4 ++-- en/orm/saving-data.rst | 2 +- en/tutorials-and-examples/blog-auth-example/auth.rst | 2 +- en/tutorials-and-examples/cms/tags-and-users.rst | 2 +- es/tutorials-and-examples/blog-auth-example/auth.rst | 2 +- es/tutorials-and-examples/bookmarks/part-two.rst | 2 +- es/tutorials-and-examples/cms/database.rst | 2 +- fr/orm/entities.rst | 4 ++-- fr/orm/saving-data.rst | 2 +- fr/tutorials-and-examples/blog-auth-example/auth.rst | 2 +- fr/tutorials-and-examples/bookmarks/part-two.rst | 2 +- fr/tutorials-and-examples/cms/database.rst | 2 +- fr/tutorials-and-examples/cms/tags-and-users.rst | 2 +- ja/orm/entities.rst | 4 ++-- ja/orm/saving-data.rst | 2 +- ja/tutorials-and-examples/blog-auth-example/auth.rst | 2 +- ja/tutorials-and-examples/bookmarks/part-two.rst | 2 +- ja/tutorials-and-examples/cms/database.rst | 2 +- ja/tutorials-and-examples/cms/tags-and-users.rst | 2 +- pt/orm/entities.rst | 4 ++-- pt/orm/saving-data.rst | 2 +- pt/tutorials-and-examples/blog-auth-example/auth.rst | 2 +- pt/tutorials-and-examples/bookmarks/part-two.rst | 2 +- pt/tutorials-and-examples/cms/database.rst | 2 +- 24 files changed, 28 insertions(+), 28 deletions(-) diff --git a/en/orm/entities.rst b/en/orm/entities.rst index 02a3800d42..0f61863ef2 100644 --- a/en/orm/entities.rst +++ b/en/orm/entities.rst @@ -371,7 +371,7 @@ indicate whether a field can or cannot be mass-assigned:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true ]; @@ -386,7 +386,7 @@ fallback behavior if a field is not specifically named:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true, '*' => false, diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst index 1b611754a3..691a72916d 100644 --- a/en/orm/saving-data.rst +++ b/en/orm/saving-data.rst @@ -480,7 +480,7 @@ an important caveat: If a Product belongsToMany Tag:: // in the Product Entity - protected $_accessible = [ + protected array $_accessible = [ // .. other properties 'tags' => true, ]; diff --git a/en/tutorials-and-examples/blog-auth-example/auth.rst b/en/tutorials-and-examples/blog-auth-example/auth.rst index ae76498dea..a83c4b2e3b 100644 --- a/en/tutorials-and-examples/blog-auth-example/auth.rst +++ b/en/tutorials-and-examples/blog-auth-example/auth.rst @@ -156,7 +156,7 @@ Next, we'll create the ``User`` entity and add password hashing. Create the class User extends Entity { // Make all fields mass assignable except for primary key field "id". - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false ]; diff --git a/en/tutorials-and-examples/cms/tags-and-users.rst b/en/tutorials-and-examples/cms/tags-and-users.rst index f69adb2322..4adb88cabe 100644 --- a/en/tutorials-and-examples/cms/tags-and-users.rst +++ b/en/tutorials-and-examples/cms/tags-and-users.rst @@ -334,7 +334,7 @@ can add a virtual/computed field to the entity. In use Cake\Collection\Collection; // Update the accessible property to contain `tag_string` - protected $_accessible = [ + protected array $_accessible = [ //other fields... 'tag_string' => true ]; diff --git a/es/tutorials-and-examples/blog-auth-example/auth.rst b/es/tutorials-and-examples/blog-auth-example/auth.rst index 36f13b78da..cb107e286a 100644 --- a/es/tutorials-and-examples/blog-auth-example/auth.rst +++ b/es/tutorials-and-examples/blog-auth-example/auth.rst @@ -205,7 +205,7 @@ Crea el archivo **src/Model/Entity/User.php** y agrega las siguientes lineas:: { // Make all fields mass assignable for now. - protected $_accessible = ['*' => true]; + protected array $_accessible = ['*' => true]; // ... diff --git a/es/tutorials-and-examples/bookmarks/part-two.rst b/es/tutorials-and-examples/bookmarks/part-two.rst index dad36a097d..900acd1c6f 100644 --- a/es/tutorials-and-examples/bookmarks/part-two.rst +++ b/es/tutorials-and-examples/bookmarks/part-two.rst @@ -362,7 +362,7 @@ entidad para poder 'guardarla' más adelante. En **src/Model/Entity/Bookmark.php** añade ``tag_string`` a ``$_accessible`` de este modo:: - protected $_accessible = [ + protected array $_accessible = [ 'user_id' => true, 'title' => true, 'description' => true, diff --git a/es/tutorials-and-examples/cms/database.rst b/es/tutorials-and-examples/cms/database.rst index d9d5880015..ce208c8011 100644 --- a/es/tutorials-and-examples/cms/database.rst +++ b/es/tutorials-and-examples/cms/database.rst @@ -209,7 +209,7 @@ archivo completo debería verse así:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false, 'slug' => false, diff --git a/fr/orm/entities.rst b/fr/orm/entities.rst index 11454075c5..4075493bec 100644 --- a/fr/orm/entities.rst +++ b/fr/orm/entities.rst @@ -398,7 +398,7 @@ d'indiquer s'ils peuvent être assignés en masse ou non. Les valeurs ``true`` e class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true ]; @@ -413,7 +413,7 @@ comportement par défaut si un champ n'est pas nommé spécifiquement:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true, '*' => false, diff --git a/fr/orm/saving-data.rst b/fr/orm/saving-data.rst index 0e51707f2a..0a2b4d606b 100644 --- a/fr/orm/saving-data.rst +++ b/fr/orm/saving-data.rst @@ -506,7 +506,7 @@ belongsToMany, avec cependant un point d'attention important: Si Product belongsToMany Tag:: // Dans l'entity Product - protected $_accessible = [ + protected array $_accessible = [ // .. autres propriétés 'tags' => true, ]; diff --git a/fr/tutorials-and-examples/blog-auth-example/auth.rst b/fr/tutorials-and-examples/blog-auth-example/auth.rst index c866295469..c4b0b6f632 100755 --- a/fr/tutorials-and-examples/blog-auth-example/auth.rst +++ b/fr/tutorials-and-examples/blog-auth-example/auth.rst @@ -165,7 +165,7 @@ suit:: { // Rend les champs assignables en masse sauf pour la clé primaire "id". - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false ]; diff --git a/fr/tutorials-and-examples/bookmarks/part-two.rst b/fr/tutorials-and-examples/bookmarks/part-two.rst index 9a6fc1144a..78bdb31913 100644 --- a/fr/tutorials-and-examples/bookmarks/part-two.rst +++ b/fr/tutorials-and-examples/bookmarks/part-two.rst @@ -346,7 +346,7 @@ entity, puisque nous voulons la 'sauvegarder' plus tard. Dans le fichier **src/Model/Entity/Bookmark.php**, ajoutez ``tag_string`` à la propriété ``_accessible`` comme ceci:: - protected $_accessible = [ + protected array $_accessible = [ 'user_id' => true, 'title' => true, 'description' => true, diff --git a/fr/tutorials-and-examples/cms/database.rst b/fr/tutorials-and-examples/cms/database.rst index 7f0eb24af9..68c07c5e33 100644 --- a/fr/tutorials-and-examples/cms/database.rst +++ b/fr/tutorials-and-examples/cms/database.rst @@ -214,7 +214,7 @@ Le fichier devra ressembler à ceci:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false, 'slug' => false, diff --git a/fr/tutorials-and-examples/cms/tags-and-users.rst b/fr/tutorials-and-examples/cms/tags-and-users.rst index a4ad5c35f3..a2894c8bd9 100644 --- a/fr/tutorials-and-examples/cms/tags-and-users.rst +++ b/fr/tutorials-and-examples/cms/tags-and-users.rst @@ -344,7 +344,7 @@ entity, nous ajoutons un champ virtuel/pré-calculé pour l'entity. Dans use Cake\Collection\Collection; // Mettez à jour la propriété accessible pour qu'elle contienne `tag_string` - protected $_accessible = [ + protected array $_accessible = [ //autres champs... 'tag_string' => true ]; diff --git a/ja/orm/entities.rst b/ja/orm/entities.rst index 3d7cd2169c..7ff2db1dda 100644 --- a/ja/orm/entities.rst +++ b/ja/orm/entities.rst @@ -318,7 +318,7 @@ CakePHP は一括代入から保護しません。 class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true ]; @@ -333,7 +333,7 @@ CakePHP は一括代入から保護しません。 class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true, '*' => false, diff --git a/ja/orm/saving-data.rst b/ja/orm/saving-data.rst index adf412b9bd..24ede83c00 100644 --- a/ja/orm/saving-data.rst +++ b/ja/orm/saving-data.rst @@ -484,7 +484,7 @@ hasMany の belongsToMany アソシエーションについても同じことが もし、 Product belongsToMany Tag であれば、こうなります。 :: // Product エンティティーの中で - protected $_accessible = [ + protected array $_accessible = [ // .. 他のプロパティー 'tags' => true, ]; diff --git a/ja/tutorials-and-examples/blog-auth-example/auth.rst b/ja/tutorials-and-examples/blog-auth-example/auth.rst index 563242b7fd..8acbcc39d7 100644 --- a/ja/tutorials-and-examples/blog-auth-example/auth.rst +++ b/ja/tutorials-and-examples/blog-auth-example/auth.rst @@ -139,7 +139,7 @@ composerを使ってAuthenticationプラグインをインストールします class User extends Entity { // 主キーフィールドである「id」以外のすべてのフィールドを一括代入可能にします。 - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false ]; diff --git a/ja/tutorials-and-examples/bookmarks/part-two.rst b/ja/tutorials-and-examples/bookmarks/part-two.rst index d453108dcb..433e60b80d 100644 --- a/ja/tutorials-and-examples/bookmarks/part-two.rst +++ b/ja/tutorials-and-examples/bookmarks/part-two.rst @@ -322,7 +322,7 @@ AppController に追加しましょう。 :: **src/Model/Entity/Bookmark.php** で ``$_accessible`` に ``tag_string`` を このように追加してください。 :: - protected $_accessible = [ + protected array $_accessible = [ 'user_id' => true, 'title' => true, 'description' => true, diff --git a/ja/tutorials-and-examples/cms/database.rst b/ja/tutorials-and-examples/cms/database.rst index 9961e40be4..78c6f16be3 100644 --- a/ja/tutorials-and-examples/cms/database.rst +++ b/ja/tutorials-and-examples/cms/database.rst @@ -151,7 +151,7 @@ Table オブジェクトを ``ArticlesTable`` と名付けることで、CakePHP class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false, 'slug' => false, diff --git a/ja/tutorials-and-examples/cms/tags-and-users.rst b/ja/tutorials-and-examples/cms/tags-and-users.rst index ad11a0b03e..8098e41a72 100644 --- a/ja/tutorials-and-examples/cms/tags-and-users.rst +++ b/ja/tutorials-and-examples/cms/tags-and-users.rst @@ -320,7 +320,7 @@ CakePHP では、コントローラーのアクションをスリムに保ち、 use Cake\Collection\Collection; // アクセス可能なプロパティに `tag_string` を含めるよう更新します - protected $_accessible = [ + protected array $_accessible = [ // その他のフィールドも追加可能 'tag_string' => true ]; diff --git a/pt/orm/entities.rst b/pt/orm/entities.rst index 238e71ed0d..f27dcb5385 100644 --- a/pt/orm/entities.rst +++ b/pt/orm/entities.rst @@ -298,7 +298,7 @@ indicam se um campo pode ou não ser atribuído em massa:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true ]; @@ -313,7 +313,7 @@ de falbback se um campo não for especificamente nomeado:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ 'title' => true, 'body' => true, '*' => false, diff --git a/pt/orm/saving-data.rst b/pt/orm/saving-data.rst index 1a1f56524d..45a792fed5 100644 --- a/pt/orm/saving-data.rst +++ b/pt/orm/saving-data.rst @@ -532,7 +532,7 @@ advertência importante: Se um Produto pertence a várias (belongsToMany) Tag:: // Na classe da entidade Product - protected $_accessible = [ + protected array $_accessible = [ // .. outras propriedades 'tags' => true, ]; diff --git a/pt/tutorials-and-examples/blog-auth-example/auth.rst b/pt/tutorials-and-examples/blog-auth-example/auth.rst index 43dfd633f8..bf5c47d832 100644 --- a/pt/tutorials-and-examples/blog-auth-example/auth.rst +++ b/pt/tutorials-and-examples/blog-auth-example/auth.rst @@ -227,7 +227,7 @@ e adicione a seguinte trecho:: { // Gera conjunto de todos os campos exceto o com a chave primária. - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false ]; diff --git a/pt/tutorials-and-examples/bookmarks/part-two.rst b/pt/tutorials-and-examples/bookmarks/part-two.rst index 896fa6f8f0..2bcb1c0af2 100644 --- a/pt/tutorials-and-examples/bookmarks/part-two.rst +++ b/pt/tutorials-and-examples/bookmarks/part-two.rst @@ -327,7 +327,7 @@ propriedade ``tag_string`` a lista ``_accessible`` em sua entidade. Em **src/Model/Entity/Bookmark.php** adicione o ``tag_string`` ao ``_accessible`` desta forma:: - protected $_accessible = [ + protected array $_accessible = [ 'user_id' => true, 'title' => true, 'description' => true, diff --git a/pt/tutorials-and-examples/cms/database.rst b/pt/tutorials-and-examples/cms/database.rst index bc108778cf..925cb5b54b 100644 --- a/pt/tutorials-and-examples/cms/database.rst +++ b/pt/tutorials-and-examples/cms/database.rst @@ -225,7 +225,7 @@ com este:: class Article extends Entity { - protected $_accessible = [ + protected array $_accessible = [ '*' => true, 'id' => false, 'slug' => false, From db3a140a2d3c22fbfebf6956fa4a66a561b2c793 Mon Sep 17 00:00:00 2001 From: Alex Mayer Date: Wed, 27 Sep 2023 11:50:53 -0400 Subject: [PATCH 027/337] Fix Container Auto-Wiring Link --- en/development/dependency-injection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst index de471e7351..0fb0c40e37 100644 --- a/en/development/dependency-injection.rst +++ b/en/development/dependency-injection.rst @@ -311,4 +311,4 @@ caching:: ); Read more about auto wiring in the `PHP League Container documentation -`_. +`_. From d8198c59987c784be21e83c37c721b398f8ad506 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Wed, 27 Sep 2023 13:44:56 -0400 Subject: [PATCH 028/337] Imporove content-type negotiation docs - Try to improve the flow in the rest chapter. - Provide more examples in controller chapter --- en/controllers.rst | 38 ++++++++++++---- en/development/rest.rst | 88 ++++++++++++++++++++++---------------- en/development/routing.rst | 19 ++++---- 3 files changed, 89 insertions(+), 56 deletions(-) diff --git a/en/controllers.rst b/en/controllers.rst index 8cafbcbc30..ba7cf57c1f 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -286,10 +286,11 @@ Content Type Negotiation Controllers can define a list of view classes they support. After the controller's action is complete CakePHP will use the view list to perform -content-type negotiation. This enables your application to re-use the same -controller action to render an HTML view or render a JSON or XML response. To -define the list of supported view classes for a controller is done with the -``viewClasses()`` method:: +content-type negotiation with either :ref:`file-extensions` or ``Content-Type`` +headers. This enables your application to re-use the same controller action to +render an HTML view or render a JSON or XML response. To define the list of +supported view classes for a controller is done with the ``viewClasses()`` +method:: namespace App\Controller; @@ -305,10 +306,31 @@ define the list of supported view classes for a controller is done with the } The application's ``View`` class is automatically used as a fallback when no -other view can be selected based on the requests' ``Accept`` header or routing -extension. If your application needs to perform different logic for different -response formats you can use ``$this->request->is()`` to build the required -conditional logic. You can also set your controllers' supported view classes +other view can be selected based on the request's ``Accept`` header or routing +extension. If your application only supports content types for a specific +actions, you can define that logic within ``viewClasses()``:: + + public function viewClasses(): array + { + if ($this->request->getParam('action') === 'export') { + // Use a custom CSV view for data exports. + return [CsvView::class]; + } + return [JsonView::class]; + } + +If within your controller actions you need to process request or load data +differently based on the controller action you can use +:ref:`check-the-request`:: + + // In a controller action + + // Load additional data when preparing JSON responses + if ($this->request->is('json')) { + $query->contain('Authors'); + } + +You can also set your controllers' supported view classes using the ``addViewClasses()`` method which will merge the provided views with those held in the ``viewClasses`` property. diff --git a/en/development/rest.rst b/en/development/rest.rst index c56472a042..39f49c5184 100644 --- a/en/development/rest.rst +++ b/en/development/rest.rst @@ -1,24 +1,21 @@ REST #### -Many newer application programmers are realizing the need to open their core -functionality to a greater audience. Providing unfettered access to your -core API can help get your platform accepted, and allows for mashups and -integration with other systems. +REST is a foundational concept to the open web. CakePHP provides functionality +to build applications that expose REST APIs with low complexity abstractions and +interfaces. -While other solutions exist, REST is a great way to provide access to the -logic you've created in your application. It's simple, usually XML-based (we're -talking simple XML, nothing like a SOAP envelope), and depends on HTTP headers -for direction. Exposing an API via REST in CakePHP is simple. +CakePHP provides methods for exposing your controller actions via HTTP methods, +and serializing view variables based on content-type negotiation. Content-Type +negotiation allows clients of your application to send requests with serialize +data and receive responses with serialized data via the ``Accept`` and +``Content-Type`` headers, or URL extensions. -The Simple Setup -================ - -The fastest way to get up and running with REST is to add a few lines to setup -:ref:`resource routes ` in your config/routes.php file. +Getting Started +=============== -Once the router has been set up to map REST requests to certain controller -actions, we can move on to creating the logic in our controller actions. A basic +To get started with adding a REST API to your application, we'll first need +a controller containing actions that we want to expose as an API. A basic controller might look something like this:: // src/Controller/RecipesController.php @@ -91,17 +88,44 @@ controller might look something like this:: } } +In our ``RecipesController``, we have several actions that define the logic +to create, edit, view and delete recipes. In each of our actions we're using +the ``serialize`` option to tell CakePHP which view variables should be +serialized when making API responses. We'll connect our controller to the +application URLs with :ref:`resource-routes`:: + + // in config/routes.php + $routes->scope('/', function (RouteBuilder $routes) { + $routes->setExtensions(['json']); + $routes->resources('Recipes'); + }); + +These routes will enable URLs like ``/recipes.json`` to return a JSON encoded +response. Clients could also make a request to ``/recipes`` with the +``Content-Type: application/json`` header as well. + +Encoding Response Data +====================== + +In the above controller, we're defining a ``viewClasses()`` method. This method +We're including CakePHP's ``JsonView``. To learn more about it and Xml based +views see :doc:`/views/json-and-xml-views`. is used by CakePHP to select a view +class to render a REST response with. -RESTful controllers often use parsed extensions to serve up different views -based on different kinds of requests. We're defining the content-type based -views we support in this controller. We're including CakePHP's ``JsonView``. To -learn more about it and Xml based views see :doc:`/views/json-and-xml-views`. By -using :php:class:`JsonView` we can define a ``serialize`` option. This option -is used to define which view variables ``JsonView`` should serialize into JSON. +Next, we have several methods that expose basic logic to create, edit, view and +delete recipes. In each of our actions we're using the ``serialize`` option to +tell CakePHP which view variables should be serialized when making API +responses. If we wanted to modify the data before it is converted into JSON we should not -define the ``serialize`` option, and instead use template files. We place -the REST views for our RecipesController inside **templates/Recipes/json**. +define the ``serialize`` option, and instead use template files. We would place +the REST templates for our RecipesController inside **templates/Recipes/json**. + +See the :ref:`controller-viewclasses` for more information on how CakePHP's +response negotiation functionality. + +Parsing Request Bodies +====================== Creating the logic for the edit action requires another step. Because our resources are serialized as JSON it would be ergonomic if our requests also @@ -114,25 +138,13 @@ In our ``Application`` class ensure the following is present:: This middleware will use the ``content-type`` header to detect the format of request data and parse enabled formats. By default only ``JSON`` parsing is enabled by default. You can enable XML support by enabling the ``xml`` -constructor option. - -Accepting Input in Other Formats -================================ +constructor option. When a request is made with a ``Content-Type`` of +``application/json``, CakePHP will decode the request data and update the +request so that ``$request->getData()`` contains the parsed body. -Typically REST applications not only output content in alternate data formats, -but also accept data in different formats. In CakePHP, the -:php:class:`BodyParserMiddleware` helps facilitate this. By default, -it will decode any incoming JSON/XML input data for POST/PUT requests -and supply the array version of that data in ``$this->request->getData()``. You can also wire in additional deserializers for alternate formats if you need them, using :php:meth:`BodyParserMiddleware::addParser()`. -RESTful Routing -=============== - -CakePHP's Router lets you connect RESTful resource routes with a fluent -interface. See the section on :ref:`resource-routes` for more information. - .. meta:: :title lang=en: REST :keywords lang=en: application programmers,default routes,core functionality,result format,mashups,recipe database,request method,access,config,soap,recipes,logic,audience,cakephp,running,api diff --git a/en/development/routing.rst b/en/development/routing.rst index dc7f6998dd..b5a23f8f65 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -990,10 +990,9 @@ can:: RESTful Routing =============== -Router helps generate RESTful routes for your controllers. RESTful -routes are helpful when you are creating API endpoints for your application. If -we wanted to allow REST access to a recipe controller, we'd do something like -this:: +Router helps generate RESTful routes for your controllers. RESTful routes are +helpful when you are creating API endpoints for your application. If we wanted +to allow REST access to a recipe controller, we'd do something like this:: // In config/routes.php... @@ -1099,17 +1098,17 @@ Would create read only resource routes. The route names are ``create``, The default **route name and controller action used** are as follows: =========== ======================= -Route name Controller action used +Route name Controller action used =========== ======================= -create add +create add ----------- ----------------------- -update edit +update edit ----------- ----------------------- -view view +view view ----------- ----------------------- -index index +index index ----------- ----------------------- -delete delete +delete delete =========== ======================= From 838b5dd82b8c2b2477cdbc0644b265302f14bd0d Mon Sep 17 00:00:00 2001 From: Mark Story Date: Wed, 27 Sep 2023 13:08:32 -0700 Subject: [PATCH 029/337] Fix mistake. --- en/development/rest.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/en/development/rest.rst b/en/development/rest.rst index 39f49c5184..2f51587b5c 100644 --- a/en/development/rest.rst +++ b/en/development/rest.rst @@ -108,9 +108,10 @@ Encoding Response Data ====================== In the above controller, we're defining a ``viewClasses()`` method. This method -We're including CakePHP's ``JsonView``. To learn more about it and Xml based -views see :doc:`/views/json-and-xml-views`. is used by CakePHP to select a view -class to render a REST response with. +defines which views your controller has available for content-negotitation. +We're including CakePHP's ``JsonView`` which enables JSON based responses. To +learn more about it and Xml based views see :doc:`/views/json-and-xml-views`. is +used by CakePHP to select a view class to render a REST response with. Next, we have several methods that expose basic logic to create, edit, view and delete recipes. In each of our actions we're using the ``serialize`` option to From 263a1266b35dbc060b29bff09104676ca5e57721 Mon Sep 17 00:00:00 2001 From: Mark Scherer Date: Wed, 27 Sep 2023 22:15:17 +0200 Subject: [PATCH 030/337] Fix CS --- en/controllers.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/controllers.rst b/en/controllers.rst index ba7cf57c1f..353709a36e 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -316,6 +316,7 @@ actions, you can define that logic within ``viewClasses()``:: // Use a custom CSV view for data exports. return [CsvView::class]; } + return [JsonView::class]; } From ececfccb400fe879e8bcbe4248cc31fb3a7471aa Mon Sep 17 00:00:00 2001 From: Mark Story Date: Wed, 27 Sep 2023 18:00:21 -0700 Subject: [PATCH 031/337] Update en/development/rest.rst Co-authored-by: Mark Scherer --- en/development/rest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/rest.rst b/en/development/rest.rst index 2f51587b5c..0d7ea46662 100644 --- a/en/development/rest.rst +++ b/en/development/rest.rst @@ -95,7 +95,7 @@ serialized when making API responses. We'll connect our controller to the application URLs with :ref:`resource-routes`:: // in config/routes.php - $routes->scope('/', function (RouteBuilder $routes) { + $routes->scope('/', function (RouteBuilder $routes): void { $routes->setExtensions(['json']); $routes->resources('Recipes'); }); From 34c53ca7e3d99e9c4c8fb93d185f29f1983a3779 Mon Sep 17 00:00:00 2001 From: Alex Mayer Date: Thu, 28 Sep 2023 08:00:11 -0400 Subject: [PATCH 032/337] Remove References to useCommandRunner --- en/console-commands/commands.rst | 6 ------ fr/console-commands/commands.rst | 15 --------------- ja/console-commands/commands.rst | 14 -------------- 3 files changed, 35 deletions(-) diff --git a/en/console-commands/commands.rst b/en/console-commands/commands.rst index 8bedd02249..36179c703e 100644 --- a/en/console-commands/commands.rst +++ b/en/console-commands/commands.rst @@ -335,12 +335,6 @@ moment, but let's just test that our command's description is displayed in ``std { use ConsoleIntegrationTestTrait; - public function setUp(): void - { - parent::setUp(); - $this->useCommandRunner(); - } - public function testDescriptionOutput() { $this->exec('update_table --help'); diff --git a/fr/console-commands/commands.rst b/fr/console-commands/commands.rst index 6a4f6bf5e4..c60537262e 100644 --- a/fr/console-commands/commands.rst +++ b/fr/console-commands/commands.rst @@ -342,12 +342,6 @@ moment, mais testons simplement si la description de notre shell description s'a { user ConsoleIntegrationTestTrait; - public function setUp(): void - { - parent::setUp(); - $this->useCommandRunner(); - } - public function testDescriptionOutput() { $this->exec('update_table --help'); @@ -540,15 +534,6 @@ Dans le premier cas de test, nous confirmons la question, et les enregistrements ne confirmons pas et les enregistrements ne sont pas mis à jour, et nous pouvons vérifier que le message d'erreur a été écrit dans ``stderr``. - -Tester le CommandRunner ------------------------ - -Pour tester les shells qui sont dispatchés en utilisant la classe -``CommandRunner``, activez-la dans vos cas de test avec la méthode suivante:: - - $this->useCommandRunner(); - Méthodes d'Assertion -------------------- diff --git a/ja/console-commands/commands.rst b/ja/console-commands/commands.rst index adc0b8ae38..939ad7d25e 100644 --- a/ja/console-commands/commands.rst +++ b/ja/console-commands/commands.rst @@ -313,12 +313,6 @@ CLI で使用するのと同じ文字列を渡すことができます。 { use ConsoleIntegrationTestTrait; - public function setUp(): void - { - parent::setUp(); - $this->useCommandRunner(); - } - public function testDescriptionOutput() { $this->exec('update_table --help'); @@ -508,14 +502,6 @@ CLI で使用するのと同じ文字列を渡すことができます。 2番目のテストでは確認していませんし、レコードが更新されていないので、 エラーメッセージが ``stderr`` に書き込まれていることを確認できます。 -CommandRunner のテスト ----------------------- - -``CommandRunner`` クラスを使ってディスパッチされたシェルをテストするには、 -次のメソッドを使ってテストケースでそれを有効にしてください。 :: - - $this->useCommandRunner(); - アサーションメソッド ---------------------- From 5ba4108e9675213cf4a78c04a678df3f9496dd23 Mon Sep 17 00:00:00 2001 From: othercorey Date: Fri, 29 Sep 2023 23:17:58 -0500 Subject: [PATCH 033/337] Add read/write connections to new features in 5.0 --- en/appendices/5-0-migration-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 2c4358ed66..39538c6918 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -301,6 +301,8 @@ Core 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. From add074bfd1de74f90d35ad8605254eb249ab775b Mon Sep 17 00:00:00 2001 From: ADmad Date: Sat, 30 Sep 2023 14:26:15 +0530 Subject: [PATCH 034/337] Add warning about fallback routes. Refs cakephp/cakephp#17294 --- en/development/routing.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/en/development/routing.rst b/en/development/routing.rst index b5a23f8f65..f48899af4c 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -1655,6 +1655,14 @@ Is equivalent to the following explicit calls:: with ``{plugin}`` and/or ``{controller}`` route elements will result in inconsistent URL case. +.. warning:: + Given that the fallback routes templates are quite generic, they allow mapping + URLs to even non-existent controllers/actions and when reverse routing + (generating URL string for URL arrays) generate invalid URLs. + + Hence it's not recommeneded to not use fallback routes in production and + instead connect routes as required using the various other route builder methods. + Creating Persistent URL Parameters ================================== From e304244071ae57325546c7b2356d6f40053ed6b3 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sat, 30 Sep 2023 18:32:00 +0530 Subject: [PATCH 035/337] Fix typo Co-authored-by: Mark Scherer --- en/development/routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/routing.rst b/en/development/routing.rst index f48899af4c..de4dd560f4 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -1660,7 +1660,7 @@ Is equivalent to the following explicit calls:: URLs to even non-existent controllers/actions and when reverse routing (generating URL string for URL arrays) generate invalid URLs. - Hence it's not recommeneded to not use fallback routes in production and + Hence it's not recommended to not use fallback routes in production and instead connect routes as required using the various other route builder methods. Creating Persistent URL Parameters From 083f6ced9a6a08825cec6a070146559fb7a058c2 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 1 Oct 2023 00:24:11 +0530 Subject: [PATCH 036/337] Fix grammar Co-authored-by: Kevin Pfeifer --- en/development/routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/routing.rst b/en/development/routing.rst index de4dd560f4..d01e50bcd0 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -1660,7 +1660,7 @@ Is equivalent to the following explicit calls:: URLs to even non-existent controllers/actions and when reverse routing (generating URL string for URL arrays) generate invalid URLs. - Hence it's not recommended to not use fallback routes in production and + Hence it's not recommended to use fallback routes in production and instead connect routes as required using the various other route builder methods. Creating Persistent URL Parameters From ed8888fcc971b1fd7b33fae7ac809e1d32d2c250 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 30 Sep 2023 12:13:53 -0700 Subject: [PATCH 037/337] Tweak wording --- en/development/routing.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/en/development/routing.rst b/en/development/routing.rst index d01e50bcd0..5aa93cff3d 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -1656,12 +1656,12 @@ Is equivalent to the following explicit calls:: inconsistent URL case. .. warning:: - Given that the fallback routes templates are quite generic, they allow mapping - URLs to even non-existent controllers/actions and when reverse routing - (generating URL string for URL arrays) generate invalid URLs. - - Hence it's not recommended to use fallback routes in production and - instead connect routes as required using the various other route builder methods. + Fallback route templates are very generic and allow URLs to be generated + and parsed for controllers & actions that do not exist. Fallback URLs can + also introduce ambiguity and duplication in your URLs. + + As your application grows, it is recommended to move away from fallback URLs + and explicitly define the routes in your application. Creating Persistent URL Parameters ================================== From 348c6acccb9451e3f7d03806e2bd8e841a5a4286 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 1 Oct 2023 01:50:45 +0530 Subject: [PATCH 038/337] Update docs related to plugin loading. --- en/appendices/5-0-migration-guide.rst | 8 +- en/plugins.rst | 155 +++++++++++--------------- 2 files changed, 69 insertions(+), 94 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 39538c6918..2e2f2140b1 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -296,7 +296,7 @@ Core ---- - The ``services()`` method was added to ``PluginInterface``. -- ``PluginCollection::addFromConfig()`` has been added to :ref:`simplify plugin loading `. +- ``PluginCollection::addFromConfig()`` has been added to :ref:`simplify plugin loading `. Database -------- @@ -400,3 +400,9 @@ 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/plugins.rst b/en/plugins.rst index f07514537e..428b6f65a1 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -51,27 +51,16 @@ Manually Autoloading Plugin Classes If you install your plugins via ``composer`` or ``bake`` you shouldn't need to configure class autoloading for your plugins. -If we were installing a plugin named ``MyPlugin`` manually you would need to -modify your application's **composer.json** file to contain the following -information: +If you create a plugin manually under the ``plugins`` folder then will need to +tell ``composer`` to refresh its autoloading cache: -.. code-block:: json +.. code-block:: console - { - "autoload": { - "psr-4": { - "MyPlugin\\": "plugins/MyPlugin/src/" - } - }, - "autoload-dev": { - "psr-4": { - "MyPlugin\\Test\\": "plugins/MyPlugin/tests/" - } - } - } + php composer.phar dumpautoload -If you are using vendor namespaces for your plugins, the namespace to path mapping -should resemble the following: +If you are using vendor namespaces for your plugins, you'll have to add the +namespace to path mapping to the ``composer.json`` resembling the following +before running the above composer command: .. code-block:: json @@ -79,55 +68,35 @@ should resemble the following: "autoload": { "psr-4": { "AcmeCorp\\Users\\": "plugins/AcmeCorp/Users/src/", + } + }, + "autoload-dev": { + "psr-4": { "AcmeCorp\\Users\\Test\\": "plugins/AcmeCorp/Users/tests/" } } } -Additionally, you will need to tell Composer to refresh its autoloading cache: - -.. code-block:: console - - php composer.phar dumpautoload +.. _loading-a-plugin: Loading a Plugin ================ If you want to use a plugin's routes, console commands, middlewares, event listeners, templates or webroot assets you will need to load the plugin. -Plugins are loaded in your application's ``bootstrap()`` function:: - - // In src/Application.php - use Cake\Http\BaseApplication; - use ContactManager\ContactManagerPlugin; - - class Application extends BaseApplication { - public function bootstrap() - { - parent::bootstrap(); - // Load the contact manager plugin by class name - $this->addPlugin(ContactManagerPlugin::class); - - // Load a plugin with a vendor namespace by 'short name' - $this->addPlugin('AcmeCorp/ContactManager'); - - // Load a dev dependency that will not exist in production builds. - $this->addOptionalPlugin('AcmeCorp/ContactManager'); - } - } If you just want to use helpers, behaviors or components from a plugin you do not need to explicitly load a plugin yet it's recommended to always do so. -There is also a handy console command to enable the plugin. Execute the following +There is also a handy console command to load the plugin. Execute the following line: .. code-block:: console bin/cake plugin load ContactManager -This would update your application's bootstrap method, or put the -``$this->addPlugin('ContactManager');`` snippet in the bootstrap for you. +This would update the array in your application's ``config/plugins.php`` with +an entry similar to ``'ContactManager' => []``. .. _plugin-configuration: @@ -147,16 +116,52 @@ appropriate parts of your application. The hooks are: collection. * ``services`` Used to register application container services -When loading plugins you can configure which hooks are enabled. By default -plugins without a :ref:`plugin-objects` have all hooks disabled. New style plugins -allow plugin authors to set defaults, which can be configured by you in your -application:: +By default all plugins hooks are enabled. You can disable hooks by using the +related options of the ``plugin load`` command:: - // In Application::bootstrap() +.. code-block:: console + + bin/cake plugin load ContactManager --no-routes + +This would update the array in your application's ``config/plugins.php`` with +an entry similar to ``'ContactManager' => ['routes' => false]``. + +Plugin Loading Options +====================== + +Apart from the options for plugin hooks the ``plugin load`` command has the +following options to control plugin loading: + +- ``--only-debug`` Load the plugin only when debug mode is enabled. +- ``--only-cli`` Load the plugin only for CLI. +- ``--optional`` Do not throw an error if the plugin is not available. + +Loading plugins through ``Application::bootstrap()`` +==================================================== + +Apart from the config array in ``config/plugins.php``, plugins can also be +loaded in your application's ``bootstrap()`` method:: + + // In src/Application.php + use Cake\Http\BaseApplication; use ContactManager\ContactManagerPlugin; - // Disable routes for the ContactManager plugin - $this->addPlugin(ContactManagerPlugin::class, ['routes' => false]); + class Application extends BaseApplication + { + public function bootstrap() + { + parent::bootstrap(); + + // Load the contact manager plugin by class name + $this->addPlugin(ContactManagerPlugin::class); + + // Load a plugin with a vendor namespace by 'short name' with options + $this->addPlugin('AcmeCorp/ContactManager', ['console' => false]); + + // Load a dev dependency that will not exist in production builds. + $this->addOptionalPlugin('AcmeCorp/ContactManager'); + } + } You can configure hooks with array options, or the methods provided by plugin classes:: @@ -183,33 +188,6 @@ Plugin objects also know their names and path information:: $path = $plugin->getConfigPath(); $path = $plugin->getClassPath(); -.. _loading-plugins-via-configuration-array: - -Loading plugins via configuration array -======================================= - -.. versionadded:: 5.0.0 - -Alternatively you can also load plugins via adding a ``config/plugins.php`` -to your application with the following content:: - - ['onlyDebug' => true], - 'Named' => ['routes' => false], - ]; - -You still have full control over which plugins are loaded in debug and/or -CLI mode only via the following config values: - -- ``onlyDebug`` -- ``onlyCli`` -- ``optional`` - -The usual plugin hooks ``bootstrap``, ``routes``, ``middleware`` and ``console`` -are available as well. - Using Plugin Classes ==================== @@ -274,7 +252,8 @@ Note the name of the plugin folder, '**ContactManager**'. It is important that this folder has the same name as the plugin. Inside the plugin folder, you'll notice it looks a lot like a CakePHP -application, and that's basically what it is. You don't have to +application, and that's basically what it is. Just instead of an ``Application.php`` +you have a ``ContactManagerPlugin.php``. You don't have to include any of the folders you are not using. Some plugins might only define a Component and a Behavior, and in that case they can completely omit the 'templates' directory. @@ -316,7 +295,7 @@ Plugin Objects Plugin Objects allow a plugin author to define set-up logic, define default hooks, load routes, middleware and console commands. Plugin objects live in -**src/Plugin.php**. For our ContactManager plugin, our plugin class could look +**src/Plugin.php**. For our ContactManager plugin, our plugin class could look like:: namespace ContactManager; @@ -378,7 +357,7 @@ like:: * * @param \Cake\Core\ContainerInterface $container The Container to update. * @return void - * @link https://book.cakephp.org/4/en/development/dependency-injection.html#dependency-injection + * @link https://book.cakephp.org/5/en/development/dependency-injection.html#dependency-injection */ public function services(ContainerInterface $container): void { @@ -415,12 +394,6 @@ ContactManager plugin routes, put the following into The above will connect default routes for your plugin. You can customize this file with more specific routes later on. -Before you can access your controllers, you'll need to ensure the plugin is -loaded and the plugin routes are loaded. In your **src/Application.php** add -the following:: - - $this->addPlugin('ContactManager', ['routes' => true]); - You can also load plugin routes in your application's routes list. Doing this provides you more control on how plugin routes are loaded and allows you to wrap plugin routes in additional scopes or prefixes:: @@ -494,10 +467,6 @@ also connect routes that use the following pattern:: See the section on :ref:`plugin-configuration` for information on how to load plugin specific route files. -For plugins you did not create with bake, you will also need to edit the -**composer.json** file to add your plugin to the autoload classes, this can be -done as per the documentation :ref:`autoloading-plugin-classes`. - .. _plugin-models: Plugin Models From e5b830406f8c32390381e1c8478507d1309cc21d Mon Sep 17 00:00:00 2001 From: kolorafa Date: Sat, 30 Sep 2023 23:05:20 +0200 Subject: [PATCH 039/337] Update testing.rst phpunit version --- en/development/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index f586d808fd..52edac6a03 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -23,7 +23,7 @@ To install PHPUnit with Composer: .. code-block:: console - $ php composer.phar require --dev phpunit/phpunit:"^8.5" + $ php composer.phar require --dev phpunit/phpunit:"^10.1" This will add the dependency to the ``require-dev`` section of your ``composer.json``, and then install PHPUnit along with any dependencies. From a4bca00a137b01dabaa078a33583de5134d861f0 Mon Sep 17 00:00:00 2001 From: johnd486 Date: Mon, 2 Oct 2023 13:41:56 +0100 Subject: [PATCH 040/337] Need to create database first When first setting up database cake_cms, you need to have created the database first. I've added a line to the SQL code to do that :). --- en/tutorials-and-examples/cms/database.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/tutorials-and-examples/cms/database.rst b/en/tutorials-and-examples/cms/database.rst index cc30579208..e97c7fd7a9 100644 --- a/en/tutorials-and-examples/cms/database.rst +++ b/en/tutorials-and-examples/cms/database.rst @@ -10,6 +10,8 @@ necessary tables: .. code-block:: SQL + CREATE DATABASE cake_cms; + USE cake_cms; CREATE TABLE users ( From fae06354af060053dad35c7045c2063052d349a9 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 3 Oct 2023 15:40:43 -0400 Subject: [PATCH 041/337] Start 5.next book --- config/conf.py | 12 ++++++------ en/appendices.rst | 1 + en/appendices/5-1-upgrade-guide.rst | 16 ++++++++++++++++ en/security/security-headers.rst | 1 + 4 files changed, 24 insertions(+), 6 deletions(-) create mode 100644 en/appendices/5-1-upgrade-guide.rst diff --git a/config/conf.py b/config/conf.py index 6b7f6cc14d..36c7840741 100644 --- a/config/conf.py +++ b/config/conf.py @@ -10,13 +10,13 @@ # built documents. # # The short X.Y version. -version = '5.x' +version = '5.next' # The full version, including alpha/beta/rc tags. -release = '5.x' +release = '5.next' # The search index version. -search_version = '5' +search_version = '5-next' # The marketing diplay name for the book. version_name = 'Chiffon' @@ -31,15 +31,15 @@ {'name': '1.2', 'number': '1.2', 'title': '1.2 Book'}, {'name': '1.1', 'number': '1.1', 'title': '1.1 Book'}, ] -# 5.x is pre-release still. -is_prerelease = False +# 5.next is pre-release still. +is_prerelease = True # Languages available. languages = ['en', 'pt_BR', 'es', 'ja', 'fr'] # The GitHub branch name for this version of the docs # for edit links to point at. -branch = '5.x' +branch = '5.next' # Add any paths that contain custom themes here, relative to this directory. html_theme_path = [] diff --git a/en/appendices.rst b/en/appendices.rst index 2ce90232a9..1e43c1844d 100644 --- a/en/appendices.rst +++ b/en/appendices.rst @@ -12,6 +12,7 @@ introduced in each version and the migration path between versions. appendices/5-0-upgrade-guide appendices/5-0-migration-guide + appendices/5-1-upgrade-guide Backwards Compatibility Shimming ================================ diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst new file mode 100644 index 0000000000..0f65e60547 --- /dev/null +++ b/en/appendices/5-1-upgrade-guide.rst @@ -0,0 +1,16 @@ +5.1 Upgrade 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. + + +New Features +============ + +Http +---- + +- ``SecurityHeadersMiddleware::setPermissionsPolicy()`` was added. This method + adds the ability to define ``permissions-policy`` header values. diff --git a/en/security/security-headers.rst b/en/security/security-headers.rst index 8494454dcb..4fd7ed8031 100644 --- a/en/security/security-headers.rst +++ b/en/security/security-headers.rst @@ -11,6 +11,7 @@ headers to responses: * ``X-Download-Options`` * ``X-Frame-Options`` * ``Referrer-Policy`` +* ``Permissions-Policy`` This middleware is configured using a fluent interface before it is applied to your application's middleware stack:: From 3f1a6c4e111650cf13f3bce893458aa43090ae5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?wowDAS=20Markus=20Ram=C5=A1ak?= Date: Wed, 4 Oct 2023 12:12:15 +0200 Subject: [PATCH 042/337] Update 5-0-migration-guide.rst --- en/appendices/5-0-migration-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 2e2f2140b1..9b0568667a 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -123,6 +123,8 @@ Database ``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 Datasource From 3acfff568ad0cacb23ac2f68d98a89fa1fdc3b46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?wowDAS=20Markus=20Ram=C5=A1ak?= Date: Thu, 5 Oct 2023 02:57:54 +0200 Subject: [PATCH 043/337] Update 5-0-migration-guide.rst #[\AllowDynamicProperties] removed --- en/appendices/5-0-migration-guide.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 9b0568667a..b08e66c7bb 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -27,6 +27,15 @@ Global 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. +- 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 ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``, ``WEEK``, ``MONTH``, ``YEAR`` constants were removed. - Global functions are now opt-in. If your application uses global function aliases be sure to add ``require CAKE . 'functions.php'`` to you application's From 94b5e958c5d2554c157658748537f7b4bb0d5687 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?wowDAS=20Markus=20Ram=C5=A1ak?= Date: Thu, 5 Oct 2023 03:33:36 +0200 Subject: [PATCH 044/337] Update 5-0-migration-guide.rst --- en/appendices/5-0-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index b08e66c7bb..4320c4f822 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -27,7 +27,7 @@ Global 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. -- Use of #[\AllowDynamicProperties] removed everywhere. It was used for the following classes: +- Use of ``#[\AllowDynamicProperties]`` removed everywhere. It was used for the following classes: - ``Command/Command`` - ``Console/Shell`` - ``Controller/Component`` From 49bd9cec79bd855c1f8feca4038e7b52b1b7a482 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?wowDAS=20Markus=20Ram=C5=A1ak?= Date: Thu, 5 Oct 2023 04:34:41 +0200 Subject: [PATCH 045/337] Update 5-0-migration-guide.rst list must have 3 spaces instead of 2 --- en/appendices/5-0-migration-guide.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 4320c4f822..f6ba926155 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -28,24 +28,24 @@ Global - Type declarations were added to all class properties where possible. These also include some fixes for incorrect annotations. - 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`` + - ``Command/Command`` + - ``Console/Shell`` + - ``Controller/Component`` + - ``Controller/Controller`` + - ``Mailer/Mailer`` + - ``View/Cell`` + - ``View/Helper`` + - ``View/View`` - The ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``, ``WEEK``, ``MONTH``, ``YEAR`` constants were removed. - Global functions are now opt-in. If your application uses global function aliases be sure to add ``require CAKE . 'functions.php'`` to you application's ``config/bootstrap.php``. - 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 + - MySQL (5.7 or higher) + - MariaDB (10.1 or higher) + - PostgreSQL (9.6 or higher) + - Microsoft SQL Server (2012 or higher) + - SQLite 3 Auth ---- From ca81618e71d03f9e429259aa8dd626c629f8a224 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?wowDAS=20Markus=20Ram=C5=A1ak?= Date: Thu, 5 Oct 2023 04:35:36 +0200 Subject: [PATCH 046/337] Update 5-0-migration-guide.rst --- en/appendices/5-0-migration-guide.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index f6ba926155..b40f1d3631 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -27,6 +27,10 @@ Global 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. +- Global functions are now opt-in. If your application uses global function + aliases be sure to add ``require CAKE . 'functions.php'`` to you application's + ``config/bootstrap.php``. - Use of ``#[\AllowDynamicProperties]`` removed everywhere. It was used for the following classes: - ``Command/Command`` - ``Console/Shell`` @@ -36,10 +40,6 @@ Global - ``View/Cell`` - ``View/Helper`` - ``View/View`` -- The ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``, ``WEEK``, ``MONTH``, ``YEAR`` constants were removed. -- Global functions are now opt-in. If your application uses global function - aliases be sure to add ``require CAKE . 'functions.php'`` to you application's - ``config/bootstrap.php``. - The supported database engine versions were updated: - MySQL (5.7 or higher) - MariaDB (10.1 or higher) From c20d6ff1f8522d56f1c339ac14666fea1fa71a78 Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 5 Oct 2023 18:50:26 +0200 Subject: [PATCH 047/337] Fix up CI, paths, signatures, typos. --- en/appendices/5-0-migration-guide.rst | 2 +- en/console-commands/commands.rst | 22 +++---- en/console-commands/option-parsers.rst | 22 +++---- en/controllers.rst | 4 +- en/controllers/components.rst | 4 +- en/controllers/components/flash.rst | 4 +- en/controllers/pagination.rst | 8 +-- en/controllers/request-response.rst | 2 +- en/core-libraries/caching.rst | 6 +- en/core-libraries/collections.rst | 22 +++---- en/core-libraries/email.rst | 10 +-- en/core-libraries/hash.rst | 6 +- en/core-libraries/httpclient.rst | 62 +++++++++---------- .../internationalization-and-localization.rst | 28 ++++----- en/core-libraries/validation.rst | 38 ++++++------ en/core-libraries/xml.rst | 8 +-- en/development/configuration.rst | 12 ++-- en/development/errors.rst | 2 +- en/development/routing.rst | 4 +- en/development/sessions.rst | 24 +++---- en/development/testing.rst | 4 +- en/installation.rst | 3 +- en/orm/associations.rst | 14 ++--- en/orm/behaviors/counter-cache.rst | 26 ++++---- en/orm/behaviors/translate.rst | 6 +- en/orm/database-basics.rst | 2 +- en/orm/entities.rst | 2 +- en/orm/query-builder.rst | 38 +++++++----- en/orm/retrieving-data-and-resultsets.rst | 20 +++--- en/orm/saving-data.rst | 18 +++--- en/orm/validation.rst | 16 ++--- .../blog-auth-example/auth.rst | 2 +- en/tutorials-and-examples/blog/blog.rst | 22 +++---- .../cms/authentication.rst | 2 +- .../cms/installation.rst | 25 ++++---- en/views/cells.rst | 3 +- en/views/helpers.rst | 2 +- en/views/helpers/breadcrumbs.rst | 12 ++-- en/views/helpers/form.rst | 52 ++++++++-------- en/views/helpers/paginator.rst | 6 +- en/views/json-and-xml-views.rst | 4 +- 41 files changed, 287 insertions(+), 282 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 9b0568667a..e61d485dc4 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -387,7 +387,7 @@ A similar change has been applied to the ``RepositoryInterface::get()`` method:: { $author = $this->Authors->get($id, [ 'contain' => ['Books'], - 'finder' => 'latest' + 'finder' => 'latest', ]); } diff --git a/en/console-commands/commands.rst b/en/console-commands/commands.rst index 36179c703e..0320143a2c 100644 --- a/en/console-commands/commands.rst +++ b/en/console-commands/commands.rst @@ -27,7 +27,7 @@ simple Hello world command. In your application's **src/Command** directory crea public function execute(Arguments $args, ConsoleIo $io): int { $io->out('Hello world.'); - + return static::CODE_SUCCESS; } } @@ -60,7 +60,7 @@ command line:: protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser { $parser->addArgument('name', [ - 'help' => 'What is your name' + 'help' => 'What is your name', ]); return $parser; } @@ -69,7 +69,7 @@ command line:: { $name = $args->getArgument('name'); $io->out("Hello {$name}."); - + return static::CODE_SUCCESS; } } @@ -111,11 +111,11 @@ add a ``yell`` option to our ``HelloCommand``:: { $parser ->addArgument('name', [ - 'help' => 'What is your name' + 'help' => 'What is your name', ]) ->addOption('yell', [ 'help' => 'Shout the name', - 'boolean' => true + 'boolean' => true, ]); return $parser; @@ -128,7 +128,7 @@ add a ``yell`` option to our ``HelloCommand``:: $name = mb_strtoupper($name); } $io->out("Hello {$name}."); - + return static::CODE_SUCCESS; } @@ -202,7 +202,7 @@ to terminate execution:: $io->error('Name must be at least 4 characters long.'); $this->abort(); } - + return static::CODE_SUCCESS; } @@ -215,7 +215,7 @@ You can also use ``abort()`` on the ``$io`` object to emit a message and code:: // Halt execution, output to stderr, and set exit code to 99 $io->abort('Name must be at least 4 characters long.', 99); } - + return static::CODE_SUCCESS; } @@ -376,7 +376,7 @@ conventions. Let's continue by adding more logic to our command:: 'modified' => new DateTime() ]) ->execute(); - + return static::CODE_SUCCESS; } } @@ -397,7 +397,7 @@ Modify your test case to the following snippet of code:: protected $fixtures = [ // assumes you have a UsersFixture - 'app.Users' + 'app.Users', ]; public function testDescriptionOutput() @@ -477,7 +477,7 @@ Update the command class to the following:: 'modified' => new DateTime() ]) ->execute(); - + return static::CODE_SUCCESS; } } diff --git a/en/console-commands/option-parsers.rst b/en/console-commands/option-parsers.rst index b90eaa6cff..e9c0565ca7 100644 --- a/en/console-commands/option-parsers.rst +++ b/en/console-commands/option-parsers.rst @@ -74,7 +74,7 @@ If you have an array with multiple arguments you can use $parser->addArguments([ 'node' => ['help' => 'The node to create', 'required' => true], - 'parent' => ['help' => 'The parent node', 'required' => true] + 'parent' => ['help' => 'The parent node', 'required' => true], ]); As with all the builder methods on ConsoleOptionParser, addArguments @@ -91,7 +91,7 @@ valid choices:: $parser->addArgument('type', [ 'help' => 'The type of node to interact with.', 'required' => true, - 'choices' => ['aro', 'aco'] + 'choices' => ['aro', 'aco'], ]); The above will create an argument that is required and has validation on the @@ -101,7 +101,7 @@ will be raised and the shell will be stopped. Using Options ============= -.. php:method:: addOption($name, $options = []) +.. php:method:: addOption($name, array $options = []) Options or flags are used in command line tools to provide unordered key/value arguments for your commands. Options can define both verbose and short aliases. @@ -154,7 +154,7 @@ to add multiple options at once. :: $parser->addOptions([ 'node' => ['short' => 'n', 'help' => 'The node to create'], - 'parent' => ['short' => 'p', 'help' => 'The parent node'] + 'parent' => ['short' => 'p', 'help' => 'The parent node'], ]); As with all the builder methods on ConsoleOptionParser, addOptions can be used @@ -169,7 +169,7 @@ for an option. All other values will raise an ``InvalidArgumentException``:: $parser->addOption('accept', [ 'help' => 'What version to accept.', - 'choices' => ['working', 'theirs', 'mine'] + 'choices' => ['working', 'theirs', 'mine'], ]); Using Boolean Options @@ -204,14 +204,14 @@ subcommand parsers easier, as everything is an array:: 'description' => [ __("Use this command to grant ACL permissions. Once executed, the "), __("ARO specified (and its children, if any) will have ALLOW access "), - __("to the specified ACO action (and the ACO's children, if any).") + __("to the specified ACO action (and the ACO's children, if any)."), ], 'arguments' => [ 'aro' => ['help' => __('ARO to check.'), 'required' => true], 'aco' => ['help' => __('ACO to check.'), 'required' => true], - 'action' => ['help' => __('Action to check')] - ] - ] + 'action' => ['help' => __('Action to check')], + ], + ], ]); Inside the parser spec, you can define keys for ``arguments``, ``options``, @@ -232,8 +232,8 @@ use buildFromArray on its own, to build an option parser:: 'arguments' => [ 'aro' => ['help' => __('ARO to check.'), 'required' => true], 'aco' => ['help' => __('ACO to check.'), 'required' => true], - 'action' => ['help' => __('Action to check')] - ] + 'action' => ['help' => __('Action to check')], + ], ]); } diff --git a/en/controllers.rst b/en/controllers.rst index 353709a36e..e23efdff7d 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -476,8 +476,8 @@ behaves:: { protected array $paginate = [ 'Articles' => [ - 'conditions' => ['published' => 1] - ] + 'conditions' => ['published' => 1], + ], ]; } diff --git a/en/controllers/components.rst b/en/controllers/components.rst index 62e52fc9fd..fb0b6ea190 100644 --- a/en/controllers/components.rst +++ b/en/controllers/components.rst @@ -78,7 +78,7 @@ implementation:: public function initialize(): void { $this->loadComponent('Flash', [ - 'className' => 'MyFlash' + 'className' => 'MyFlash', ]); } } @@ -212,7 +212,7 @@ the Component:: parent::initialize(); $this->loadComponent('Math', [ 'precision' => 2, - 'randomGenerator' => 'srand' + 'randomGenerator' => 'srand', ]); $this->loadComponent('Csrf'); } diff --git a/en/controllers/components/flash.rst b/en/controllers/components/flash.rst index cb6012e501..a8d3674439 100644 --- a/en/controllers/components/flash.rst +++ b/en/controllers/components/flash.rst @@ -57,8 +57,8 @@ An example of using these options:: 'clear' => true, 'params' => [ 'name' => $user->name, - 'email' => $user->email - ] + 'email' => $user->email, + ], ]); // In your View diff --git a/en/controllers/pagination.rst b/en/controllers/pagination.rst index ea1da541a0..1e91b6e738 100644 --- a/en/controllers/pagination.rst +++ b/en/controllers/pagination.rst @@ -45,8 +45,8 @@ from the URL:: protected array $paginate = [ 'limit' => 25, 'order' => [ - 'Articles.title' => 'asc' - ] + 'Articles.title' => 'asc', + ], ]; } @@ -215,8 +215,8 @@ pagination query:: protected array $paginate = [ 'sortableFields' => [ - 'id', 'title', 'Users.username', 'created' - ] + 'id', 'title', 'Users.username', 'created', + ], ]; Any requests that attempt to sort on fields not in the allowed list will be diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index ee09ed9431..47f1c5671c 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -653,7 +653,7 @@ are using it. Sending Files ------------- -.. php:method:: withFile($path, $options = []) +.. php:method:: withFile(string $path, array $options = []) There are times when you want to send files as responses for your requests. You can accomplish that by using :php:meth:`Cake\\Http\\Response::withFile()`:: diff --git a/en/core-libraries/caching.rst b/en/core-libraries/caching.rst index 4d9c47c719..ec0c0ddfa4 100644 --- a/en/core-libraries/caching.rst +++ b/en/core-libraries/caching.rst @@ -65,7 +65,7 @@ following:: 'className' => 'File', 'duration' => '+1 hours', 'path' => CACHE, - 'prefix' => 'cake_short_' + 'prefix' => 'cake_short_', ], // Using a fully namespaced name. 'long' => [ @@ -73,7 +73,7 @@ following:: 'duration' => '+1 week', 'probability' => 100, 'path' => CACHE . 'long' . DS, - ] + ], ] // ... @@ -499,7 +499,7 @@ group. This is possible by declaring the groups in cache configuration:: Cache::setConfig('site_home', [ 'className' => 'Redis', 'duration' => '+999 days', - 'groups' => ['comment', 'article'] + 'groups' => ['comment', 'article'], ]); .. php:method:: clearGroup($group, $config = 'default') diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index 223d9635ad..ce52f2f81a 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -150,15 +150,15 @@ helpful when matching HasMany and BelongsToMany association data:: ['number' => 'number-1'], ['number' => 'number-2'], ['number' => 'number-3'], - ] + ], ], [ 'name' => 'James', 'phone_numbers' => [ ['number' => 'number-4'], ['number' => 'number-5'], - ] - ] + ], + ], ]; $numbers = (new Collection($data))->extract('phone_numbers.{*}.number'); @@ -185,7 +185,7 @@ dot notation paths:: ]; $combined = (new Collection($items))->combine('id', 'name'); $result = $combined->toArray(); - + // $result contains [ 1 => 'foo', @@ -214,7 +214,7 @@ instances by the ORM) you may want to group results by date:: function ($entity) { return $entity->date->toDateString(); } ); $result = $combined->toArray(); - + // $result contains [ 'date string like 2015-05-01' => ['entity1->id' => entity1, 'entity2->id' => entity2, ..., 'entityN->id' => entityN] @@ -317,7 +317,7 @@ chunking associative arrays:: ]); $chunked = $collection->chunkWithKeys(2); $result = $chunked->toList(); - + // $result contains [ ['a' => 1, 'b' => 2], @@ -592,7 +592,7 @@ You can also zip multiple collections at once:: $rows = $years->zip($salaries, $increments); $result = $rows->toList(); - + // $result contains [ [2013, 1000, 0], @@ -705,7 +705,7 @@ property representing the identifier for the parent item:: ]); $nested = $collection->nest('id', 'parent_id'); $result = $nested->toList(); - + // $result contains [ [ @@ -716,7 +716,7 @@ property representing the identifier for the parent item:: ['id' => 2, 'parent_id' => 1, 'name' => 'Land Birds', 'children' => []], ['id' => 3, 'parent_id' => 1, 'name' => 'Eagle', 'children' => []], ['id' => 4, 'parent_id' => 1, 'name' => 'Seagull', 'children' => []], - ] + ], ], [ 'id' => 6, @@ -724,8 +724,8 @@ property representing the identifier for the parent item:: 'name' => 'Fish', 'children' => [ ['id' => 5, 'parent_id' => 6, 'name' => 'Clown Fish', 'children' => []], - ] - ] + ], + ], ]; Children elements are nested inside the ``children`` property inside each of the diff --git a/en/core-libraries/email.rst b/en/core-libraries/email.rst index 9b40fa1acf..2256268e8d 100644 --- a/en/core-libraries/email.rst +++ b/en/core-libraries/email.rst @@ -259,8 +259,8 @@ you want the filenames to appear in the recipient's mail client: 'photo.png' => [ 'file' => '/full/some_hash.png', 'mimetype' => 'image/png', - 'contentId' => 'my-unique-id' - ] + 'contentId' => 'my-unique-id', + ], ]); The above will attach the file with different mimetype and with custom @@ -382,7 +382,7 @@ instructions. For example, we could add the following to our ``UserMailer``:: public function implementedEvents() { return [ - 'Model.afterSave' => 'onRegistration' + 'Model.afterSave' => 'onRegistration', ]; } @@ -429,8 +429,8 @@ change the configuration data. An example transport configuration looks like:: 'username' => 'my@gmail.com', 'password' => 'secret', 'className' => 'Smtp', - 'tls' => true - ] + 'tls' => true, + ], ], Transports can also be configured at runtime using diff --git a/en/core-libraries/hash.rst b/en/core-libraries/hash.rst index bab09fdde3..2a0c2a74ff 100644 --- a/en/core-libraries/hash.rst +++ b/en/core-libraries/hash.rst @@ -388,7 +388,7 @@ Attribute Matching Types 0 => ['name' => 'main'], 1 => ['name' => 'about'], 2 => ['name' => 'contact'], - 'a' => 'b' + 'a' => 'b', ]; $result = Hash::contains($a, $a); @@ -538,7 +538,7 @@ Attribute Matching Types [ 'id' => '48c2570e-dfa8-4c32-a35e-0d71cbdd56cb', 'name' => 'mysql raleigh-workshop-08 < 2008-09-05.sql ', - 'description' => 'Importing an sql dump' + 'description' => 'Importing an sql dump', ], [ 'id' => '48c257a8-cf7c-4af2-ac2f-114ecbdd56cb', @@ -792,7 +792,7 @@ Attribute Matching Types 'Limit', 'Bindable', 'Validator', - 'Transactional' + 'Transactional', ]; $result = Hash::normalize($b); /* $result now looks like: diff --git a/en/core-libraries/httpclient.rst b/en/core-libraries/httpclient.rst index 3160faae30..cdb11bcc3b 100644 --- a/en/core-libraries/httpclient.rst +++ b/en/core-libraries/httpclient.rst @@ -26,7 +26,7 @@ Doing requests is simple and straight forward. Doing a GET request looks like:: // Simple get with querystring & additional headers $response = $http->get('http://example.com/search', ['q' => 'widget'], [ - 'headers' => ['X-Requested-With' => 'XMLHttpRequest'] + 'headers' => ['X-Requested-With' => 'XMLHttpRequest'], ]); Doing POST and PUT requests is equally simple:: @@ -35,13 +35,13 @@ Doing POST and PUT requests is equally simple:: $http = new Client(); $response = $http->post('http://example.com/posts/add', [ 'title' => 'testing', - 'body' => 'content in the post' + 'body' => 'content in the post', ]); // Send a PUT request with application/x-www-form-urlencoded encoded data $response = $http->put('http://example.com/posts/add', [ 'title' => 'testing', - 'body' => 'content in the post' + 'body' => 'content in the post', ]); // Other methods as well. @@ -178,7 +178,7 @@ An example of basic authentication:: $http = new Client(); $response = $http->get('http://example.com/profile/1', [], [ - 'auth' => ['username' => 'mark', 'password' => 'secret'] + 'auth' => ['username' => 'mark', 'password' => 'secret'], ]); By default ``Cake\Http\Client`` will use basic authentication if there is no @@ -191,15 +191,15 @@ An example of basic authentication:: $http = new Client(); $response = $http->get('http://example.com/profile/1', [], [ - 'auth' => [ - 'type' => 'digest', - 'username' => 'mark', - 'password' => 'secret', - 'realm' => 'myrealm', - 'nonce' => 'onetimevalue', - 'qop' => 1, - 'opaque' => 'someval' - ] + 'auth' => [ + 'type' => 'digest', + 'username' => 'mark', + 'password' => 'secret', + 'realm' => 'myrealm', + 'nonce' => 'onetimevalue', + 'qop' => 1, + 'opaque' => 'someval', + ], ]); By setting the 'type' key to 'digest', you tell the authentication subsystem to @@ -224,14 +224,14 @@ key and consumer secret:: $http = new Client(); $response = $http->get('http://example.com/profile/1', [], [ - 'auth' => [ - 'type' => 'oauth', - 'consumerKey' => 'bigkey', - 'consumerSecret' => 'secret', - 'token' => '...', - 'tokenSecret' => '...', - 'realm' => 'tickets', - ] + 'auth' => [ + 'type' => 'oauth', + 'consumerKey' => 'bigkey', + 'consumerSecret' => 'secret', + 'token' => '...', + 'tokenSecret' => '...', + 'realm' => 'tickets', + ], ]); OAuth 2 Authentication @@ -241,7 +241,7 @@ Because OAuth2 is often a single header, there is not a specialized authentication adapter. Instead you can create a client with the access token:: $http = new Client([ - 'headers' => ['Authorization' => 'Bearer ' . $accessToken] + 'headers' => ['Authorization' => 'Bearer ' . $accessToken], ]); $response = $http->get('https://example.com/api/profile/1'); @@ -254,11 +254,11 @@ Http\\Client will assume Basic authentication, unless the type key is set:: $http = new Client(); $response = $http->get('http://example.com/test.php', [], [ - 'proxy' => [ - 'username' => 'mark', - 'password' => 'testing', - 'proxy' => '127.0.0.1:8080', - ] + 'proxy' => [ + 'username' => 'mark', + 'password' => 'testing', + 'proxy' => '127.0.0.1:8080', + ], ]); The second proxy parameter must be a string with an IP or a domain without @@ -278,9 +278,9 @@ tedium, you can create scoped clients:: // Create a scoped client. $http = new Client([ - 'host' => 'api.example.com', - 'scheme' => 'https', - 'auth' => ['username' => 'mark', 'password' => 'testing'] + 'host' => 'api.example.com', + 'scheme' => 'https', + 'auth' => ['username' => 'mark', 'password' => 'testing'], ]); // Do a request to api.example.com @@ -345,7 +345,7 @@ request's ``$options`` parameters:: // Replace a stored cookie with a custom value. $response = $http->get('/changelogs', [], [ - 'cookies' => ['sessionid' => '123abc'] + 'cookies' => ['sessionid' => '123abc'], ]); You can add cookie objects to the client after creating it using the ``addCookie()`` diff --git a/en/core-libraries/internationalization-and-localization.rst b/en/core-libraries/internationalization-and-localization.rst index 33a117b153..8747c58c6c 100644 --- a/en/core-libraries/internationalization-and-localization.rst +++ b/en/core-libraries/internationalization-and-localization.rst @@ -41,14 +41,14 @@ application. The default format for CakePHP translation files is the placed under **resources/locales/** and within this directory, there should be a subfolder for each language the application needs to support:: - /resources - /locales - /en_US + resources/ + locales/ + en_US/ default.po - /en_GB + en_GB/ default.po validation.po - /es + es/ default.po The default domain is 'default', therefore the locale folder should at least @@ -68,13 +68,13 @@ Plugins can also contain translation files, the convention is to use the ``under_scored`` version of the plugin name as the domain for the translation messages:: - MyPlugin - /resources - /locales - /fr + MyPlugin/ + resources/ + locales/ + fr/ my_plugin.po additional.po - /de + de/ my_plugin.po Translation folders can be the two or three letter ISO code of the language or @@ -529,8 +529,8 @@ in different contexts:: [ 'He reads the letter {0}' => [ 'alphabet' => 'Él lee la letra {0}', - 'written communication' => 'Él lee la carta {0}' - ] + 'written communication' => 'Él lee la carta {0}', + ], ] Similarly, you can express Gettext-style plurals using the messages array by @@ -540,8 +540,8 @@ having a nested array key per plural form:: 'I have read one book' => 'He leído un libro', 'I have read {0} books' => [ 'He leído un libro', - 'He leído {0} libros' - ] + 'He leído {0} libros', + ], ] Using Different Formatters diff --git a/en/core-libraries/validation.rst b/en/core-libraries/validation.rst index 7ae3a6d14a..4af34141b5 100644 --- a/en/core-libraries/validation.rst +++ b/en/core-libraries/validation.rst @@ -38,12 +38,12 @@ validate:: ]) ->allowEmptyDateTime('published') ->add('published', 'boolean', [ - 'rule' => 'boolean' + 'rule' => 'boolean', ]) ->requirePresence('body') ->add('body', 'length', [ 'rule' => ['minLength', 50], - 'message' => 'Articles must have a substantial body.' + 'message' => 'Articles must have a substantial body.', ]); As seen in the example above, validators are built with a fluent interface that @@ -87,7 +87,7 @@ If you have multiple fields that are required, you can define them as a list:: 'published' => [ 'mode' => 'update', 'message' => 'The published state is required.', - ] + ], ]); Allowing Empty Fields @@ -321,12 +321,12 @@ a specific rule has failed, you can set the ``last`` option to ``true``:: 'minLength' => [ 'rule' => ['minLength', 10], 'last' => true, - 'message' => 'Comments must have a substantial body.' + 'message' => 'Comments must have a substantial body.', ], 'maxLength' => [ 'rule' => ['maxLength', 250], - 'message' => 'Comments cannot be too long.' - ] + 'message' => 'Comments cannot be too long.', + ], ]); If the minLength rule fails in the example above, the maxLength rule will not be @@ -450,8 +450,8 @@ and need to store an article and its comments:: $data = [ 'title' => 'Best article', 'comments' => [ - ['comment' => ''] - ] + ['comment' => ''], + ], ]; To validate the comments you would use a nested validator:: @@ -521,7 +521,7 @@ sending an email you could do the following:: ->requirePresence('email') ->add('email', 'validFormat', [ 'rule' => 'email', - 'message' => 'E-mail must be valid' + 'message' => 'E-mail must be valid', ]) ->requirePresence('name') ->notEmptyString('name', 'We need your name.') @@ -537,7 +537,7 @@ The ``getErrors()`` method will return a non-empty array when there are validati failures. The returned array of errors will be structured like:: $errors = [ - 'email' => ['E-mail must be valid'] + 'email' => ['E-mail must be valid'], ]; If you have multiple errors on a single field, an array of error messages will @@ -546,7 +546,7 @@ the 'create' mode. If you'd like to apply 'update' rules you can do the following:: $errors = $validator->validate($this->request->getData(), false); - if (empty($errors)) { + if (!$errors) { // Send an email. } @@ -590,12 +590,12 @@ methods allow you to specify which associations are validated, and which validation sets to apply using the ``options`` parameter:: $valid = $this->Articles->newEntity($article, [ - 'associated' => [ - 'Comments' => [ - 'associated' => ['User'], - 'validate' => 'special', - ] - ] + 'associated' => [ + 'Comments' => [ + 'associated' => ['User'], + 'validate' => 'special', + ], + ], ]); Apart from validating user provided data maintaining integrity of data regardless @@ -622,10 +622,10 @@ options as follows:: $validator = new Validator(); $validator ->add('title', 'minLength', [ - 'rule' => ['minLength', 10] + 'rule' => ['minLength', 10], ]) ->add('rating', 'validValue', [ - 'rule' => ['range', 1, 5] + 'rule' => ['range', 1, 5], ]); Core rules that take additional parameters should have an array for the diff --git a/en/core-libraries/xml.rst b/en/core-libraries/xml.rst index f8fb99e98e..f0681b44c7 100644 --- a/en/core-libraries/xml.rst +++ b/en/core-libraries/xml.rst @@ -38,7 +38,7 @@ You can also build Xml objects using an array:: 'post' => [ 'id' => 1, 'title' => 'Best post', - 'body' => ' ... ' + 'body' => ' ... ', ] ]; $xml = Xml::build($data); @@ -115,8 +115,8 @@ attributes with ``@``. For value text, use ``@`` as the key:: 'project' => [ '@id' => 1, 'name' => 'Name of project, as tag', - '@' => 'Value of project' - ] + '@' => 'Value of project', + ], ]; $xmlObject = Xml::fromArray($xmlArray); $xmlString = $xmlObject->asXML(); @@ -136,7 +136,7 @@ the samples:: $xmlArray = [ 'root' => [ 'xmlns:' => 'https://cakephp.org', - 'child' => 'value' + 'child' => 'value', ] ]; $xml1 = Xml::fromArray($xmlArray); diff --git a/en/development/configuration.rst b/en/development/configuration.rst index c7308b45cb..d3a43a7ab1 100644 --- a/en/development/configuration.rst +++ b/en/development/configuration.rst @@ -269,17 +269,17 @@ paths for these resources. In your **config/app.php** you can set these variable 'paths' => [ 'plugins' => [ ROOT . DS . 'plugins' . DS, - '/path/to/other/plugins/' + '/path/to/other/plugins/', ], 'templates' => [ ROOT . DS . 'templates' . DS, - ROOT . DS . 'templates2' . DS + ROOT . DS . 'templates2' . DS, ], 'locales' => [ - ROOT . DS . 'resources' . DS . 'locales' . DS - ] - ] - ] + ROOT . DS . 'resources' . DS . 'locales' . DS, + ], + ], + ], ]; Paths should end with a directory separator, or they will not work properly. diff --git a/en/development/errors.rst b/en/development/errors.rst index 1bdabf4e6b..b8fcf1a8ad 100644 --- a/en/development/errors.rst +++ b/en/development/errors.rst @@ -79,7 +79,7 @@ You can temporarily disable deprecation warnings in one of a few ways: 'ignoredDeprecationPaths' => [ 'vendors/company/contacts/*', 'src/Models/*', - ] + ], ], Would ignore all deprecations from your ``Models`` directory and the diff --git a/en/development/routing.rst b/en/development/routing.rst index 5aa93cff3d..bbfe38cc73 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -1151,9 +1151,9 @@ name:: 'updateAll' => [ 'action' => 'updateAll', 'method' => 'PUT', - 'path' => '/update-many' + 'path' => '/update-many', ], - ] + ], ]); // This would connect /articles/update-many diff --git a/en/development/sessions.rst b/en/development/sessions.rst index aee792140e..d4e2a785a2 100644 --- a/en/development/sessions.rst +++ b/en/development/sessions.rst @@ -56,8 +56,8 @@ You can change the default value by setting ``session.cookie_samesite`` php.ini Configure::write('Session', [ 'defaults' => 'php', 'ini' => [ - 'session.cookie_samesite' => 'Strict' - ] + 'session.cookie_samesite' => 'Strict', + ], ]); The session cookie path defaults to app's base path. To change this you can use @@ -68,8 +68,8 @@ persist across all subdomains you can do:: 'defaults' => 'php', 'ini' => [ 'session.cookie_path' => '/', - 'session.cookie_domain' => '.yourdomain.com' - ] + 'session.cookie_domain' => '.yourdomain.com', + ], ]); By default PHP sets the session cookie to expire as soon as the browser is @@ -144,8 +144,8 @@ You can then read those values out from inside your handler:: 'Session' => [ 'handler' => [ 'engine' => 'DatabaseSession', - 'model' => 'CustomSessions' - ] + 'model' => 'CustomSessions', + ], ] The above shows how you could setup the Database session handler with an @@ -184,8 +184,8 @@ You can also use your own ``Table`` class to handle the saving of the sessions:: 'defaults' => 'database', 'handler' => [ 'engine' => 'DatabaseSession', - 'model' => 'CustomSessions' - ] + 'model' => 'CustomSessions', + ], ] The above will tell Session to use the built-in 'database' defaults, and @@ -207,8 +207,8 @@ To use Cache based sessions you can configure you Session config like:: Configure::write('Session', [ 'defaults' => 'cache', 'handler' => [ - 'config' => 'session' - ] + 'config' => 'session', + ], ]); This will configure Session to use the ``CacheSession`` class as the @@ -331,8 +331,8 @@ In **config/app.php** make the session block look like:: 'handler' => [ 'engine' => 'ComboSession', 'model' => 'Session', - 'cache' => 'apc' - ] + 'cache' => 'apc', + ], ], // Make sure to add a apc cache config 'Cache' => [ diff --git a/en/development/testing.rst b/en/development/testing.rst index 52edac6a03..a0a20503c0 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -73,7 +73,7 @@ CakePHP for fixture tables and data:: 'host' => 'dbhost', 'username' => 'dblogin', 'password' => 'dbpassword', - 'database' => 'test_database' + 'database' => 'test_database', ], ], @@ -690,7 +690,7 @@ Fixture directory. You can also load fixtures from CakePHP core, or plugins:: protected $fixtures = [ 'plugin.DebugKit.Articles', 'plugin.MyVendorName/MyPlugin.Messages', - 'core.Comments' + 'core.Comments', ]; } diff --git a/en/installation.rst b/en/installation.rst index ef0a340287..935376b8a2 100644 --- a/en/installation.rst +++ b/en/installation.rst @@ -234,7 +234,7 @@ After installing your application using one of the methods above into the directory of your choosing - we'll assume you chose /cake_install - your production setup will look like this on the file system:: - /cake_install/ + cake_install/ bin/ config/ logs/ @@ -248,7 +248,6 @@ production setup will look like this on the file system:: webroot/ (this directory is set as DocumentRoot) .gitignore .htaccess - .travis.yml composer.json index.php phpunit.xml.dist diff --git a/en/orm/associations.rst b/en/orm/associations.rst index ab37e274f3..093f6f49e5 100644 --- a/en/orm/associations.rst +++ b/en/orm/associations.rst @@ -94,11 +94,11 @@ self-associated tables to create parent-child relationships:: public function initialize(array $config): void { $this->hasMany('SubCategories', [ - 'className' => 'Categories' + 'className' => 'Categories', ]); $this->belongsTo('ParentCategories', [ - 'className' => 'Categories' + 'className' => 'Categories', ]); } } @@ -113,10 +113,10 @@ table names indexed by association type as an argument:: { $this->addAssociations([ 'belongsTo' => [ - 'Users' => ['className' => 'App\Model\Table\UsersTable'] + 'Users' => ['className' => 'App\Model\Table\UsersTable'], ], 'hasMany' => ['Comments'], - 'belongsToMany' => ['Tags'] + 'belongsToMany' => ['Tags'], ]); } } @@ -394,7 +394,7 @@ Sometimes you may want to configure composite keys in your associations:: $this->hasMany('Comments') ->setForeignKey([ 'article_id', - 'article_hash' + 'article_hash', ]); Relying on the example above, we have passed an array containing the desired @@ -407,11 +407,11 @@ manually with ``setBindingKey()``:: $this->hasMany('Comments') ->setForeignKey([ 'article_id', - 'article_hash' + 'article_hash', ]) ->setBindingKey([ 'whatever_id', - 'whatever_hash' + 'whatever_hash', ]); Like hasOne associations, ``foreignKey`` is in the other (Comments) diff --git a/en/orm/behaviors/counter-cache.rst b/en/orm/behaviors/counter-cache.rst index 7ba3157b4b..46b0d0a63c 100644 --- a/en/orm/behaviors/counter-cache.rst +++ b/en/orm/behaviors/counter-cache.rst @@ -64,9 +64,9 @@ counter value:: $this->addBehavior('CounterCache', [ 'Articles' => [ 'comment_count' => [ - 'finder' => 'published' - ] - ] + 'finder' => 'published', + ], + ], ]); If you don't have a custom finder method you can provide an array of conditions @@ -75,9 +75,9 @@ to find records instead:: $this->addBehavior('CounterCache', [ 'Articles' => [ 'comment_count' => [ - 'conditions' => ['Comments.spam' => false] - ] - ] + 'conditions' => ['Comments.spam' => false], + ], + ], ]); If you want CounterCache to update multiple fields, for example both showing a @@ -86,9 +86,9 @@ conditional count and a basic count you can add these fields in the array:: $this->addBehavior('CounterCache', [ 'Articles' => ['comment_count', 'published_comment_count' => [ - 'finder' => 'published' - ] - ] + 'finder' => 'published', + ], + ], ]); If you want to calculate the CounterCache field value on your own, you can set @@ -99,9 +99,9 @@ before:: $this->addBehavior('CounterCache', [ 'Articles' => [ 'comment_count' => [ - 'ignoreDirty' => true - ] - ] + 'ignoreDirty' => true, + ], + ], ]); Lastly, if a custom finder and conditions are not suitable you can provide @@ -112,7 +112,7 @@ a callback function. Your function must return the count value to be stored:: 'rating_avg' => function ($event, $entity, $table, $original) { return 4.5; } - ] + ], ]); Your function can return ``false`` to skip updating the counter column, or diff --git a/en/orm/behaviors/translate.rst b/en/orm/behaviors/translate.rst index 547cd04492..bdf9f64612 100644 --- a/en/orm/behaviors/translate.rst +++ b/en/orm/behaviors/translate.rst @@ -206,7 +206,7 @@ for each different table:: { $this->addBehavior('Translate', [ 'fields' => ['title', 'body'], - 'translationTable' => 'ArticlesI18n' + 'translationTable' => 'ArticlesI18n', ]); } } @@ -470,7 +470,7 @@ Now, You can populate translations before saving them:: $translations = [ 'fr' => ['title' => "Un article"], - 'es' => ['title' => 'Un artículo'] + 'es' => ['title' => 'Un artículo'], ]; foreach ($translations as $lang => $data) { @@ -516,7 +516,7 @@ behavior during ``newEntity()`` or ``patchEntity()``:: { $this->addBehavior('Translate', [ 'fields' => ['title'], - 'validator' => 'translated' + 'validator' => 'translated', ]); } } diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 5a56929b63..b3a5d3283e 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -128,7 +128,7 @@ like:: 'encoding' => 'utf8mb4', 'timezone' => 'UTC', 'cacheMetadata' => true, - ] + ], ], The above will create a 'default' connection, with the provided parameters. You diff --git a/en/orm/entities.rst b/en/orm/entities.rst index 0f61863ef2..d13241d39e 100644 --- a/en/orm/entities.rst +++ b/en/orm/entities.rst @@ -132,7 +132,7 @@ value:: 'title' => 'First post', 'user_id' => null, 'text' => '', - 'links' => [] + 'links' => [], ]); $article->has('title'); // true $article->isEmpty('title'); // false diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 301b88d332..685ae5cd33 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -366,7 +366,7 @@ safely add user data to SQL functions. For example:: ' - Age: ', $query->func()->dateDiff([ 'NOW()' => 'literal', - 'Articles.created' => 'identifier' + 'Articles.created' => 'identifier', ]) ]); $query->select(['link_title' => $concat]); @@ -1044,7 +1044,7 @@ can may be able to use ``bind()`` to manually bind parameters into conditions:: $query = $cities->find() ->where([ - 'start_date BETWEEN :start AND :end' + 'start_date BETWEEN :start AND :end', ]) ->bind(':start', '2014-01-01', 'date') ->bind(':end', '2014-12-31', 'date'); @@ -1236,7 +1236,7 @@ typically using comparison operators like ``<, >, =``:: ['unit_price' => 20, 'tax_percentage <=' => 5], ] ]); - + # WHERE (unit_price < 20 OR (unit_price = 20 AND tax_percentage <= 5)) The same result can be achieved using ``TupleComparison``:: @@ -1255,7 +1255,7 @@ The same result can be achieved using ``TupleComparison``:: # WHERE (unit_price, tax_percentage) <= (20, 5)) -Tuple Comparison can also be used with ``IN`` and the result can be transformed +Tuple Comparison can also be used with ``IN`` and the result can be transformed even on DBMS that does not natively support it:: $articles->find() @@ -1491,11 +1491,15 @@ SQL. In addition to ``join()`` you can use ``rightJoin()``, ``leftJoin()`` and $query->innerJoin( ['Authors' => 'authors'], [ - 'Authors.promoted' => true, - 'Authors.created' => new DateTime('-5 days'), - 'Authors.id = Articles.author_id' + 'Authors.promoted' => true, + 'Authors.created' => new DateTime('-5 days'), + 'Authors.id = Articles.author_id', ], - ['Authors.promoted' => 'boolean', 'Authors.created' => 'datetime']); + [ + 'Authors.promoted' => 'boolean', + 'Authors.created' => 'datetime', + ] + ); It should be noted that if you set the ``quoteIdentifiers`` option to ``true`` when defining your ``Connection``, join conditions between table fields should be set as follow:: @@ -1506,8 +1510,8 @@ defining your ``Connection``, join conditions between table fields should be set 'table' => 'comments', 'type' => 'LEFT', 'conditions' => [ - 'c.article_id' => new \Cake\Database\Expression\IdentifierExpression('articles.id') - ] + 'c.article_id' => new \Cake\Database\Expression\IdentifierExpression('articles.id'), + ], ], ]); @@ -1524,7 +1528,7 @@ Instead, create a new ``InsertQuery`` object using ``insertQuery()``:: $query->insert(['title', 'body']) ->values([ 'title' => 'First post', - 'body' => 'Some body text' + 'body' => 'Some body text', ]) ->execute(); @@ -1535,11 +1539,11 @@ method as many times as you need:: $query->insert(['title', 'body']) ->values([ 'title' => 'First post', - 'body' => 'Some body text' + 'body' => 'Some body text', ]) ->values([ 'title' => 'Second post', - 'body' => 'Another body text' + 'body' => 'Another body text', ]) ->execute(); @@ -1652,7 +1656,7 @@ example given above:: $query ->where([ 'MATCH (comment) AGAINST (:userData)', - 'created < NOW() - :moreUserData' + 'created < NOW() - :moreUserData', ]) ->bind(':userData', $userData, 'string') ->bind(':moreUserData', $moreUserData, 'datetime'); @@ -1858,7 +1862,7 @@ To build that query with the ORM query builder we would use:: $q = $this->Orders->subquery(); $q->select([ 'order_count' => $q->func()->count('*'), - 'customer_id' + 'customer_id', ]) ->groupBy('customer_id'); @@ -1877,8 +1881,8 @@ To build that query with the ORM query builder we would use:: // Define the join with our table expression 'orders_per_customer' => [ 'table' => 'orders_per_customer', - 'conditions' => 'orders_per_customer.customer_id = Customers.id' - ] + 'conditions' => 'orders_per_customer.customer_id = Customers.id', + ], ]); Executing Complex Queries diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index 18d544be52..e39b27107a 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -42,7 +42,7 @@ viewing entities and their related data. You can do this by using ``get()``:: // Get a single article, and related comments $article = $articles->get($id, [ - 'contain' => ['Comments'] + 'contain' => ['Comments'], ]); If the get operation does not find any results a @@ -529,18 +529,18 @@ statements:: 'fields' => [ // Aliased fields in contain() must include // the model prefix to be mapped correctly. - 'Attributes__name' => 'attr_name' - ] - ] - ] + 'Attributes__name' => 'attr_name', + ], + ], + ], ]) ->contain([ 'RealestateAttributes' => [ 'fields' => [ 'RealestateAttributes.realestate_id', - 'RealestateAttributes.value' - ] - ] + 'RealestateAttributes.value', + ], + ], ]) ->where($condition); @@ -1043,8 +1043,8 @@ can load additional associations using ``loadInto()``:: $articles = $this->Articles->find()->all(); $withMore = $this->Articles->loadInto($articles, ['Comments', 'Users']); -It is possible to restrict the data returned by the associations and filter them -by conditions. To specify conditions, pass an anonymous function that receives +It is possible to restrict the data returned by the associations and filter them +by conditions. To specify conditions, pass an anonymous function that receives as the first argument a query object, ``\Cake\ORM\Query``:: $user = $this->Users->get($id); diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst index 691a72916d..6ee1aec049 100644 --- a/en/orm/saving-data.rst +++ b/en/orm/saving-data.rst @@ -150,7 +150,7 @@ request data should resemble:: 'body' => 'Baking with CakePHP makes web development fun!', 'user_id' => 1, 'user' => [ - 'username' => 'mark' + 'username' => 'mark', ], 'comments' => [ ['body' => 'The CakePHP features are outstanding'], @@ -174,7 +174,7 @@ associations should be marshalled:: // New entity with nested associations $entity = $articles->newEntity($this->request->getData(), [ 'associated' => [ - 'Tags', 'Comments' => ['associated' => ['Users']] + 'Tags', 'Comments' => ['associated' => ['Users']], ] ]); @@ -187,7 +187,7 @@ should be marshalled. Alternatively, you can use dot notation for brevity:: // New entity with nested associations using dot notation $entity = $articles->newEntity($this->request->getData(), [ - 'associated' => ['Tags', 'Comments.Users'] + 'associated' => ['Tags', 'Comments.Users'], ]); You may also disable marshalling of possible nested associations like so:: @@ -208,8 +208,8 @@ change the validation set to be used per association:: $entity = $articles->newEntity($this->request->getData(), [ 'associated' => [ 'Tags' => ['validate' => false], - 'Comments.Users' => ['validate' => 'signup'] - ] + 'Comments.Users' => ['validate' => 'signup'], + ], ]); The :ref:`using-different-validators-per-association` chapter has more @@ -853,8 +853,8 @@ the singular, :ref:`underscored ` version of the asso 'title' => 'First Post', 'user' => [ 'id' => 1, - 'username' => 'mark' - ] + 'username' => 'mark', + ], ]; $articles = $this->getTableLocator()->get('Articles'); @@ -875,8 +875,8 @@ singular, :ref:`underscored ` version of the associat 'id' => 1, 'username' => 'cakephp', 'profile' => [ - 'twitter' => '@cakephp' - ] + 'twitter' => '@cakephp', + ], ]; $users = $this->getTableLocator()->get('Users'); diff --git a/en/orm/validation.rst b/en/orm/validation.rst index 3a4e3c1f9d..ecf5d21819 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -134,20 +134,20 @@ of the associations to be converted:: 'body' => 'The text', 'user_id' => 1, 'user' => [ - 'username' => 'mark' + 'username' => 'mark', ], 'comments' => [ ['body' => 'First comment'], ['body' => 'Second comment'], - ] + ], ]; $article = $articles->patchEntity($article, $data, [ 'validate' => 'update', 'associated' => [ 'Users' => ['validate' => 'signup'], - 'Comments' => ['validate' => 'custom'] - ] + 'Comments' => ['validate' => 'custom'], + ], ]); Combining Validators @@ -519,7 +519,7 @@ by the ones returned from the rule:: 'ruleName', [ 'errorField' => 'length', - 'message' => 'Generic error message used when `false` is returned' + 'message' => 'Generic error message used when `false` is returned', ] ); @@ -540,7 +540,7 @@ You may want to re-use custom domain rules. You can do so by creating your own i { $rules->add(new IsUniqueWithNulls(['parent_id', 'instance_id', 'name']), 'uniqueNamePerParent', [ 'errorField' => 'name', - 'message' => 'Name must be unique per parent.' + 'message' => 'Name must be unique per parent.', ]); return $rules; } @@ -679,7 +679,7 @@ for data transitions generated inside your application:: }; $rules->add($check, [ 'errorField' => 'shipping_mode', - 'message' => 'No free shipping for orders under 100!' + 'message' => 'No free shipping for orders under 100!', ]); return $rules; @@ -702,7 +702,7 @@ come up when running a CLI script that directly sets properties on entities:: { $validator->add('email', 'valid_email', [ 'rule' => 'email', - 'message' => 'Invalid email' + 'message' => 'Invalid email', ]); // ... diff --git a/en/tutorials-and-examples/blog-auth-example/auth.rst b/en/tutorials-and-examples/blog-auth-example/auth.rst index a83c4b2e3b..6b389432e7 100644 --- a/en/tutorials-and-examples/blog-auth-example/auth.rst +++ b/en/tutorials-and-examples/blog-auth-example/auth.rst @@ -238,7 +238,7 @@ Then add the following:: 'fields' => [ 'username' => 'email', 'password' => 'password', - ] + ], ]); // Load the authenticators, you want session first diff --git a/en/tutorials-and-examples/blog/blog.rst b/en/tutorials-and-examples/blog/blog.rst index 6b5f126c8d..498a9a3b03 100755 --- a/en/tutorials-and-examples/blog/blog.rst +++ b/en/tutorials-and-examples/blog/blog.rst @@ -55,16 +55,16 @@ Composer, check out the :doc:`/installation` section. Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup should look something like the following:: - /cake_install - /bin - /config - /logs - /plugins - /src - /tests - /tmp - /vendor - /webroot + cake_install/ + bin/ + config/ + logs/ + plugins/ + src/ + tests/ + tmp/ + vendor/ + webroot/ .editorconfig .gitignore .htaccess @@ -184,7 +184,7 @@ array might look something like the following:: 'password' => 'AngelF00dC4k3~', 'database' => 'cake_blog', 'encoding' => 'utf8', - 'timezone' => 'UTC' + 'timezone' => 'UTC', ], ], // More configuration below. diff --git a/en/tutorials-and-examples/cms/authentication.rst b/en/tutorials-and-examples/cms/authentication.rst index 667c9fcc4d..7ff48410e1 100644 --- a/en/tutorials-and-examples/cms/authentication.rst +++ b/en/tutorials-and-examples/cms/authentication.rst @@ -149,7 +149,7 @@ Then add the following:: 'fields' => [ 'username' => 'email', 'password' => 'password', - ] + ], ]); // Load the authenticators, you want session first diff --git a/en/tutorials-and-examples/cms/installation.rst b/en/tutorials-and-examples/cms/installation.rst index fee369deb6..25de250972 100644 --- a/en/tutorials-and-examples/cms/installation.rst +++ b/en/tutorials-and-examples/cms/installation.rst @@ -67,22 +67,21 @@ Composer, check out the :doc:`/installation` section. Regardless of how you downloaded and installed CakePHP, once your set up is completed, your directory setup should look something like the following:: - /cms - /bin - /config - /logs - /plugins - /resources - /src - /templates - /tests - /tmp - /vendor - /webroot + cms/ + bin/ + config/ + logs/ + plugins/ + resources/ + src/ + templates/ + tests/ + tmp/ + vendor/ + webroot/ .editorconfig .gitignore .htaccess - .travis.yml composer.json index.php phpunit.xml.dist diff --git a/en/views/cells.rst b/en/views/cells.rst index 20ed05e3fa..cdd7c0f3f8 100644 --- a/en/views/cells.rst +++ b/en/views/cells.rst @@ -292,7 +292,8 @@ Loading a specific Helper just for a specific cell can be done via the following class FavoritesCell extends Cell { - public function initialize(): void { + public function initialize(): void + { $this->viewBuilder()->addHelper('MyCustomHelper'); } } diff --git a/en/views/helpers.rst b/en/views/helpers.rst index 8628a6f717..5c603d7789 100644 --- a/en/views/helpers.rst +++ b/en/views/helpers.rst @@ -170,7 +170,7 @@ implementation:: public function initialize(): void { $this->addHelper('Html', [ - 'className' => 'MyHtml' + 'className' => 'MyHtml', ]); } } diff --git a/en/views/helpers/breadcrumbs.rst b/en/views/helpers/breadcrumbs.rst index 00643491b8..b3db2b67c4 100644 --- a/en/views/helpers/breadcrumbs.rst +++ b/en/views/helpers/breadcrumbs.rst @@ -32,7 +32,7 @@ In addition to adding to the end of the trail, you can do a variety of operation // Add multiple crumbs at the end of the trail $this->Breadcrumbs->add([ ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']], - ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]] + ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]], ]); // Prepended crumbs will be put at the top of the list @@ -44,7 +44,7 @@ In addition to adding to the end of the trail, you can do a variety of operation // Prepend multiple crumbs at the top of the trail, in the order given $this->Breadcrumbs->prepend([ ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']], - ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]] + ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]], ]); // Insert in a specific slot. If the slot is out of @@ -144,8 +144,8 @@ crumb to the trail:: ['controller' => 'products', 'action' => 'index'], [ 'templateVars' => [ - 'icon' => '' - ] + 'icon' => '', + ], ] ); @@ -167,8 +167,8 @@ rendered as HTML attributes:: 'data-foo' => 'bar', 'innerAttrs' => [ 'class' => 'inner-products-crumb', - 'id' => 'the-products-crumb' - ] + 'id' => 'the-products-crumb', + ], ] ); diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 5f27685e1b..40cd97ae25 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -185,7 +185,7 @@ change where ``FormHelper`` reads input data from:: // Use query string instead of request data: echo $this->Form->create($article, [ 'type' => 'get', - 'valueSources' => ['query', 'context'] + 'valueSources' => ['query', 'context'], ]); // Same effect: @@ -199,7 +199,7 @@ where request data is retained, you need to put ``context`` first:: // Prioritize context over request data: echo $this->Form->create($article, - 'valueSources' => ['context', 'data'] + 'valueSources' => ['context', 'data'], ]); The value sources will be reset to the default ``['data', 'context']`` when ``end()`` @@ -264,8 +264,8 @@ CakePHP application:: echo $this->Form->create(null, [ 'url' => [ 'controller' => 'Articles', - 'action' => 'publish' - ] + 'action' => 'publish', + ], ]); Output: @@ -278,7 +278,7 @@ Or you can point to an external domain:: echo $this->Form->create(null, [ 'url' => 'https://www.google.com/search', - 'type' => 'get' + 'type' => 'get', ]); Output: @@ -298,7 +298,7 @@ action is going to apply. For example, your Users table has specific validation rules that only apply when an account is being registered:: echo $this->Form->create($user, [ - 'context' => ['validator' => 'register'] + 'context' => ['validator' => 'register'], ]); The above will use validation rules defined in the ``register`` validator, which @@ -310,9 +310,9 @@ can define validation rules for each association by using an array:: 'context' => [ 'validator' => [ 'Users' => 'register', - 'Comments' => 'default' - ] - ] + 'Comments' => 'default', + ], + ], ]); The above would use ``register`` for the user, and ``default`` for the user's @@ -924,7 +924,7 @@ methods are described in each method's own section.) such as ``date()``, ``time()``, ``dateTime()``:: echo $this->Form->time('close_time', [ - 'value' => '13:30:00' + 'value' => '13:30:00', ]); .. note:: @@ -1356,11 +1356,11 @@ For example:: $options = [ 'Group 1' => [ 'Value 1' => 'Label 1', - 'Value 2' => 'Label 2' + 'Value 2' => 'Label 2', ], 'Group 2' => [ - 'Value 3' => 'Label 3' - ] + 'Value 3' => 'Label 3', + ], ]; echo $this->Form->select('field', $options); @@ -2269,7 +2269,7 @@ For example:: // Generate an input and populate the help variable echo $this->Form->control('password', [ - 'templateVars' => ['help' => 'At least 8 characters long.'] + 'templateVars' => ['help' => 'At least 8 characters long.'], ]); Output: @@ -2334,7 +2334,7 @@ You can customize the generated controls by defining additional options in the ``$fields`` parameter:: echo $this->Form->controls([ - 'name' => ['label' => 'custom label'] + 'name' => ['label' => 'custom label'], ]); When customizing, ``$fields``, you can use the ``$options`` parameter to @@ -2344,9 +2344,11 @@ For example:: echo $this->Form->controls( [ - 'name' => ['label' => 'custom label'] + 'name' => ['label' => 'custom label'], ], - ['legend' => 'Update your post'] + [ + 'legend' => 'Update your post', + ] ); If you disable the ``fieldset``, the ``legend`` will not print. @@ -2354,7 +2356,7 @@ If you disable the ``fieldset``, the ``legend`` will not print. Creating Controls for a Whole Entity ------------------------------------ -.. php:method:: allControls(array $fields, $options = []) +.. php:method:: allControls(array $fields, array $options = []) * ``$fields`` - Optional. An array of customizations for the fields that will be generated. Allows setting custom types, labels and other options. @@ -2429,8 +2431,8 @@ the following code in your controller:: 'Authors', 'Authors.Profiles', 'Tags', - 'Comments' - ] + 'Comments', + ], ]); The above example shows an expanded example for belongs to many associations, @@ -2539,8 +2541,8 @@ a setting:: // In View class $this->loadHelper('Form', [ 'widgets' => [ - 'autocomplete' => ['Autocomplete'] - ] + 'autocomplete' => ['Autocomplete'], + ], ]); If your widget requires other widgets, you can have FormHelper populate those @@ -2551,9 +2553,9 @@ dependencies by declaring them:: 'autocomplete' => [ 'App\View\Widget\AutocompleteWidget', 'text', - 'label' - ] - ] + 'label', + ], + ], ]); In the above example, the ``autocomplete`` widget would depend on the ``text`` and diff --git a/en/views/helpers/paginator.rst b/en/views/helpers/paginator.rst index b5aa6911ba..19810632b6 100644 --- a/en/views/helpers/paginator.rst +++ b/en/views/helpers/paginator.rst @@ -19,7 +19,7 @@ Setting the paginated resultset By default the helper uses the first instance of ``Cake\Datasource\Paging\PaginatedInterface`` it finds in the view variables. (Generally the result of ``Controller::paginate()``). -You can use ``PaginatorHelper::setPaginated()`` to explicity set the paginated +You can use ``PaginatorHelper::setPaginated()`` to explicitly set the paginated resultset that the helper should use. .. _paginator-templates: @@ -573,8 +573,8 @@ you can include the scope names in ``options()``:: // Additional URL parameters for the 'comments' scope 'comments' => [ 'articleId' => 1234, - ] - ] + ], + ], ]); .. meta:: diff --git a/en/views/json-and-xml-views.rst b/en/views/json-and-xml-views.rst index 7472db1905..4f37ade368 100644 --- a/en/views/json-and-xml-views.rst +++ b/en/views/json-and-xml-views.rst @@ -151,7 +151,7 @@ prefix:: 'loc' => Router::url(['controller' => 'Pages', 'action' => 'view', $page->slug, '_full' => true]), 'lastmod' => $page->modified->format('Y-m-d'), 'changefreq' => 'daily', - 'priority' => '0.5' + 'priority' => '0.5', ]; } @@ -162,7 +162,7 @@ prefix:: $this->set([ // Define an attribute on the root node. '@xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9', - 'url' => $urls + 'url' => $urls, ]); } From 385a7eeb6535a5aa2bf0d5027c93d159fdcaef8a Mon Sep 17 00:00:00 2001 From: othercorey Date: Tue, 10 Oct 2023 06:23:04 -0500 Subject: [PATCH 048/337] Fix I18n\DateTime name in Collections::combine() (#7746) --- en/core-libraries/collections.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index ce52f2f81a..f7b57deb70 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -205,7 +205,7 @@ You can also optionally use a ``groupPath`` to group results based on a path:: ]; Finally you can use *closures* to build keys/values/groups paths dynamically, -for example when working with entities and dates (converted to ``Cake/Time`` +for example when working with entities and dates (converted to ``I18n\DateTime`` instances by the ORM) you may want to group results by date:: $combined = (new Collection($entities))->combine( From 8c0aad9439f6fbf63ab0dd94767de7fa439cbb5d Mon Sep 17 00:00:00 2001 From: ADmad Date: Wed, 11 Oct 2023 13:21:21 +0530 Subject: [PATCH 049/337] Promote use of addViewClasses() instead of overriding viewClasses() --- en/controllers.rst | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/en/controllers.rst b/en/controllers.rst index e23efdff7d..88f6c47aa6 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -282,14 +282,14 @@ This would render **plugins/Users/templates/UserDetails/custom_file.php** Content Type Negotiation ======================== -.. php:method:: viewClasses() +.. php:method:: addViewClasses() Controllers can define a list of view classes they support. After the controller's action is complete CakePHP will use the view list to perform content-type negotiation with either :ref:`file-extensions` or ``Content-Type`` headers. This enables your application to re-use the same controller action to render an HTML view or render a JSON or XML response. To define the list of -supported view classes for a controller is done with the ``viewClasses()`` +supported view classes for a controller is done with the ``addViewClasses()`` method:: namespace App\Controller; @@ -299,25 +299,23 @@ method:: class PostsController extends AppController { - public function viewClasses(): array + public function initialize(): void { - return [JsonView::class, XmlView::class]; + $this->addViewClasses([JsonView::class, XmlView::class]); } } The application's ``View`` class is automatically used as a fallback when no other view can be selected based on the request's ``Accept`` header or routing extension. If your application only supports content types for a specific -actions, you can define that logic within ``viewClasses()``:: +actions, you can call ``addClasses()`` within your action too:: - public function viewClasses(): array + public function export(): void { - if ($this->request->getParam('action') === 'export') { - // Use a custom CSV view for data exports. - return [CsvView::class]; - } + // Use a custom CSV view for data exports. + $this->addViewClasses([CsvView::class]); - return [JsonView::class]; + // Rest of the action code } If within your controller actions you need to process request or load data @@ -331,9 +329,9 @@ differently based on the controller action you can use $query->contain('Authors'); } -You can also set your controllers' supported view classes -using the ``addViewClasses()`` method which will merge the provided views with -those held in the ``viewClasses`` property. +In case your app need more complex logic to decide which view classes to use +then you can override the ``Controller::viewClasses()`` method and return +an array of view classes as required. .. note:: View classes must implement the static ``contentType()`` hook method to @@ -344,13 +342,13 @@ Content Type Negotiation Fallbacks If no View can be matched with the request's content type preferences, CakePHP will use the base ``View`` class. If you want to require content-type -negotiation, you can use the ``NegotiationRequiredView`` which sets a 406 status +negotiation, you can use the ``NegotiationRequiredView`` which sets a ``406`` status code:: - public function viewClasses(): array + public function initialize(): void { // Require Accept header negotiation or return a 406 response. - return [JsonView::class, NegotiationRequiredView::class]; + $this->addViewClasses([JsonView::class, NegotiationRequiredView::class]); } You can use the ``TYPE_MATCH_ALL`` content type value to build your own fallback From 62d646fd5bca92f02a09347560436209e0ed5323 Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 12 Oct 2023 18:34:45 +0530 Subject: [PATCH 050/337] Make code examples newbie friendly --- en/controllers.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/en/controllers.rst b/en/controllers.rst index 88f6c47aa6..6f6e2810fa 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -301,6 +301,8 @@ method:: { public function initialize(): void { + parent::initialize(); + $this->addViewClasses([JsonView::class, XmlView::class]); } } @@ -347,6 +349,8 @@ code:: public function initialize(): void { + parent::initialize(); + // Require Accept header negotiation or return a 406 response. $this->addViewClasses([JsonView::class, NegotiationRequiredView::class]); } From a46f134841d2e12aafece07c08984e5084ca0b31 Mon Sep 17 00:00:00 2001 From: Alejandro Ibarra Date: Fri, 13 Oct 2023 04:21:52 +0200 Subject: [PATCH 051/337] ES - CakePHP Development Process --- es/appendices/cakephp-development-process.rst | 61 ++++++++++++++++--- 1 file changed, 53 insertions(+), 8 deletions(-) diff --git a/es/appendices/cakephp-development-process.rst b/es/appendices/cakephp-development-process.rst index 770870ec5c..1045bbeb06 100644 --- a/es/appendices/cakephp-development-process.rst +++ b/es/appendices/cakephp-development-process.rst @@ -1,15 +1,60 @@ CakePHP Development Process ########################### -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +Los proyectos de CakePHP en general siguen `semver `__. Ésto significa que: - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +- Las versiones se numeran en el formato **A.B.C** +- Las versiones **A** son *lanzamientos principales*. Contienen cambios importantes y + requerirán una cantidad significativa de trabajo para actualizar desde una version **A** inferior. +- Las versiones **A.B** son *lanzamientos de mejoras*. Cada versión será compatible con + las anteriores, pero puede marcar algunas características como **obsoletas**. Si es absolutamente + necesario realizar un cambio que rompa la compatibilidad, se indicará en la guía de migración para ese lanzamiento. +- Las versiones **A.B.C** son *lanzamientos de parches*. Deben ser compatibles con el lanzamiento de parche anterior. La excepción + a esta regla es si se descubre un problema de seguridad y la única solución es romper una API existente. - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +Consulta el :doc:/contributing/backwards-compatibility para ver lo que consideramos como compatible hacia atrás y cambios que rompen la compatibilidad. + +Lanzamientos Principales +========================= + +Los lanzamientos principales introducen nuevas características y pueden eliminar funcionalidades que se hayan +marcado como obsoletas en un lanzamiento anterior. Estos lanzamientos se encuentran en las ramas ``next`` +que coinciden con su número de versión, como ``5.next``. Una vez que se lanzan, se promocionan a la rama +``master`` y luego la rama ``5.next`` se utiliza para futuros lanzamientos de características. + +Lanzamientos de Mejoras +======================== + +Los lanzamientos de mejoras son donde se envían nuevas funcionalidades o extensiones a las funcionalidades +existentes. Cada serie de lanzamientos que recibe actualizaciones tendrá una rama ``next``, por ejemplo, ``4.next``. +Si deseas contribuir con una nueva característica, por favor dirígete a estas ramas. + +Lanzamientos de Parches +======================== + +Los lanzamientos de parches corrigen errores en el código/documentación existente y siempre deben ser compatibles +con los lanzamientos de parches anteriores de la misma serie. Estos lanzamientos +se crean a partir de las ramas estables. Las ramas estables a menudo se nombran según la serie de lanzamientos, como ``3.x``. + +Frecuencia de Lanzamiento +========================== + +- Los *Lanzamientos Principales* se entregan aproximadamente cada dos o tres años. Este período de tiempo nos obliga a + ser deliberados y considerados con los cambios que rompen la compatibilidad, y brinda tiempo a la comunidad para + ponerse al día sin sentir que se están quedando atrás. +- Los *Lanzamientos de Mejoras* se entregan cada cinco a ocho meses. +- Los *Lanzamientos de Parches* se entregan inicialmente cada dos semanas. A medida que un lanzamiento de características madura, esta frecuencia se relaja a una entrega mensual. + +Política de Obsolescencia +========================== + +Antes de que una característica pueda ser eliminada en un lanzamiento principal, necesita ser marcada como obsoleta. Cuando +una funcionalidad se marca como obsoleta en el lanzamiento **A.x**, seguirá funcionando durante el resto de todos los lanzamientos +**A.x**. Las obsolescencias generalmente se indican mediante advertencias en PHP. Puedes habilitar las advertencias de obsolescencia +agregando ``E_USER_DEPRECATED`` al valor de ``Error.level`` de tu aplicación. + +El comportamiento marcado como obsoleto no se elimina hasta el próximo lanzamiento principal. Por ejemplo, un comportamiento marcado como obsoleto en ``4.1`` se eliminará en ``5.0``. .. meta:: - :title lang=es: CakePHP Development Process - :keywords lang=es: maintenance branch,community interaction,community feature,necessary feature,stable release,ticket system,advanced feature,power users,feature set,chat irc,leading edge,router,new features,members,attempt,development branches,branch development + :title lang=es: Proceso de Desarrollo CakePHP + :keywords lang=en: maintenance branch,community interaction,community feature,necessary feature,stable release,ticket system,advanced feature,power users,feature set,chat irc,leading edge,router,new features,members,attempt,development branches,branch development From 9e225ffb8cf48de3dc645d18f887cc01277574f9 Mon Sep 17 00:00:00 2001 From: Alejandro Ibarra Date: Fri, 13 Oct 2023 09:24:48 +0200 Subject: [PATCH 052/337] ES - Caching,Email,Inflector,Configuration,DispatchFilters,Errors,Sessions,Topics --- es/core-libraries/caching.rst | 585 ++++++++++++++++++++++++- es/core-libraries/email.rst | 620 +++++++++++++++++++++++++- es/core-libraries/inflector.rst | 176 +++++++- es/development/configuration.rst | 503 +++++++++++++++++++++- es/development/dispatch-filters.rst | 16 - es/development/errors.rst | 644 +++++++++++++++++++++++++++- es/development/sessions.rst | 395 ++++++++++++++++- es/topics.rst | 13 +- 8 files changed, 2877 insertions(+), 75 deletions(-) delete mode 100644 es/development/dispatch-filters.rst diff --git a/es/core-libraries/caching.rst b/es/core-libraries/caching.rst index 6bb1c5fa93..482822a995 100644 --- a/es/core-libraries/caching.rst +++ b/es/core-libraries/caching.rst @@ -1,15 +1,586 @@ Caching ####### +.. php:namespace:: Cake\Cache + +.. php:class:: Cache + +El almacenamiento en caché se puede utilizar para acelerar la lectura de recursos caros o lentos, manteniendo una segunda copia de los datos requeridos en un sistema de almacenamiento más rápido o más cercano. Por ejemplo, puedes almacenar los resultados de consultas costosas o el acceso a servicios web remotos que no cambian con frecuencia en una caché. Una vez que los datos están en la caché, leerlos desde la caché es mucho más económico que acceder al recurso remoto. + +En CakePHP, el almacenamiento en caché se facilita mediante la clase ``Cache``. Esta clase proporciona una interfaz estática y uniforme para interactuar con diversas implementaciones de almacenamiento en caché. CakePHP proporciona varios motores de caché y ofrece una interfaz sencilla si necesitas construir tu propio backend. Los motores de almacenamiento en caché integrados son: + +- ``File``: el almacenamiento en caché de archivos es una caché simple que utiliza archivos locales. Es el motor de caché más lento y no proporciona muchas características para operaciones atómicas. Sin embargo, dado que el almacenamiento en disco a menudo es bastante económico, almacenar objetos grandes o elementos que rara vez se escriben funciona bien en archivos. +- ``Memcached``: utiliza la extensión `Memcached `_. +- ``Redis``: utiliza la extensión `phpredis `_. Redis proporciona un sistema de caché rápido y persistente similar a Memcached y también ofrece operaciones atómicas. +- ``Apcu``: la caché de APCu utiliza la extensión PHP `APCu `_. Esta extensión utiliza memoria compartida en el servidor web para almacenar objetos. Esto lo hace muy rápido y capaz de proporcionar funciones de lectura/escritura atómicas. +- ``Array``: almacena todos los datos en una matriz. Este motor no proporciona almacenamiento persistente y está destinado a su uso en suites de pruebas de aplicaciones. +- ``Null``: el motor nulo en realidad no almacena nada y falla en todas las operaciones de lectura. + +Independientemente del motor de caché que elijas usar, tu aplicación interactúa con :php:class:`Cake\\Cache\\Cache`. + +.. _configuracion-caché: + +Configuración de los Motores de Caché +====================================== + +.. php:staticmethod:: setConfig($clave, $configuracion = null) + +Tu aplicación puede configurar cualquier número de 'motores' durante su proceso de inicio. Las configuraciones del motor de caché se definen en **config/app.php**. + +Para un rendimiento óptimo, CakePHP requiere que se definan dos motores de caché. + +- ``_cake_core_`` se utiliza para almacenar mapas de archivos y resultados analizados de archivos de :doc:`/core-libraries/internationalization-and-localization`. +- ``_cake_model_`` se utiliza para almacenar descripciones de esquemas para los modelos de tu aplicación. + +Usar múltiples configuraciones de motores también te permite cambiar incrementalmente el almacenamiento según sea necesario. Por ejemplo, en tu **config/app.php** podrías poner lo siguiente:: + + // ... + 'Cache' => [ + 'short' => [ + 'className' => 'File', + 'duration' => '+1 hours', + 'path' => CACHE, + 'prefix' => 'cake_short_', + ], + // Usando un nombre completamente calificado. + 'long' => [ + 'className' => 'Cake\Cache\Engine\FileEngine', + 'duration' => '+1 week', + 'probability' => 100, + 'path' => CACHE . 'long' . DS, + ], + ] + // ... + +Las opciones de configuración también se pueden proporcionar como una cadena :term:`DSN`. Esto es útil cuando se trabaja con variables de entorno o proveedores de :term:`PaaS`:: + + Cache::setConfig('short', [ + 'url' => 'memcached://user:password@cache-host/?timeout=3600&prefix=myapp_', + ]); + +Cuando usas una cadena DSN, puedes definir cualquier parámetro/opción adicional como argumentos de cadena de consulta. + +También puedes configurar los motores de caché en tiempo de ejecución:: + + // Usando un nombre corto + Cache::setConfig('short', [ + 'className' => 'File', + 'duration' => '+1 hours', + 'path' => CACHE, + 'prefix' => 'cake_short_' + ]); + + // Usando un nombre completamente calificado. + Cache::setConfig('long', [ + 'className' => 'Cake\Cache\Engine\FileEngine', + 'duration' => '+1 week', + 'probability' => 100, + 'path' => CACHE . 'long' . DS, + ]); + + // Usando un objeto construido. + $objeto = new FileEngine($configuracion); + Cache::setConfig('otro', $objeto); + +Los nombres de estas configuraciones de motor ('short' y 'long') se utilizan como el parámetro ``$config`` +para :php:meth:`Cake\\Cache\\Cache::write()` y +:php:meth:`Cake\\Cache\\Cache::read()`. Al configurar los motores de caché, puedes +referenciar el nombre de la clase utilizando las siguientes sintaxis:: + + // Nombre corto (en App\ o en los espacios de nombres de Cake) + Cache::setConfig('long', ['className' => 'File']); + + // Nombre corto del plugin + Cache::setConfig('long', ['className' => 'MyPlugin.SuperCache']); + + // Espacio de nombres completo + Cache::setConfig('long', ['className' => 'Cake\Cache\Engine\FileEngine']); + + // Un objeto que implementa CacheEngineInterface + Cache::setConfig('long', ['className' => $miCache]); + +.. note:: + + Al utilizar FileEngine, es posible que necesites usar la opción ``mask`` para + asegurarte de que los archivos de caché se creen con los permisos correctos. + +Opciones del Motor +------------------ + +Cada motor acepta las siguientes opciones: + +- ``duration``: especifica cuánto tiempo duran los elementos en esta configuración de caché. Se especifica como una expresión compatible con ``strtotime()``. +- ``groups``: lista de grupos o 'etiquetas' asociados a cada clave almacenada en esta configuración. Útil cuando necesitas eliminar un subconjunto de datos de una caché. +- ``prefix``: se antepone a todas las entradas. Bueno cuando necesitas compartir + un espacio de claves con otra configuración de caché o con otra aplicación. +- ``probability``: probabilidad de activar una limpieza de la caché. Establecerlo en 0 deshabilitará automáticamente la llamada a ``Cache::gc()`` + +Opciones del Motor de FileEngine +-------------------------------- + +FileEngine utiliza las siguientes opciones específicas del motor: + +- ``isWindows``: se rellena automáticamente con si el host es Windows o no. +- ``lock``: ¿deberían bloquearse los archivos antes de escribir en ellos? +- ``mask``: la máscara utilizada para los archivos creados. +- ``path``: ruta donde deben guardarse los archivos de caché. Por defecto, es el directorio temporal del sistema. + +.. _motor-redisengine: + +Opciones del Motor RedisEngine +------------------------------ + +RedisEngine utiliza las siguientes opciones específicas del motor: + +- ``port``: el puerto en el que se está ejecutando tu servidor Redis. +- ``host``: el host en el que se está ejecutando tu servidor Redis. +- ``database``: el número de base de datos a usar para la conexión. +- ``password``: contraseña del servidor Redis. +- ``persistent``: ¿se debe realizar una conexión persistente a Redis? +- ``timeout``: tiempo de espera de conexión para Redis. +- ``unix_socket``: ruta a un socket Unix para Redis. + +Opciones del Motor MemcacheEngine +--------------------------------- + +- ``compress``: si comprimir datos o no. +- ``username``: usuario para acceder al servidor Memcache. +- ``password``: contraseña para acceder al servidor Memcache. +- ``persistent``: el nombre de la conexión persistente. Todas las configuraciones que usan + el mismo valor persistente compartirán una única conexión subyacente. +- ``serialize``: el motor de serialización utilizado para serializar datos. Los motores disponibles son php, + igbinary y json. Además de php, la extensión memcached debe estar compilada con el + soporte adecuado para el serializador correspondiente. +- ``servers``: cadena o array de servidores memcached. Si es un array, MemcacheEngine los usará + como un grupo. +- ``duration``: ten en cuenta que cualquier duración mayor de 30 días se tratará como un valor de tiempo Unix real + en lugar de un desfase desde el tiempo actual. +- ``options``: opciones adicionales para el cliente memcached. Debe ser un array de opción => valor. + Usa las constantes ``\Memcached::OPT_*`` como claves. + +.. _configuracion-fallback-caché: + +Configuración de la Caída de Caché +---------------------------------- + +En caso de que un motor no esté disponible, como el ``FileEngine`` que intenta +escribir en una carpeta no escribible o el ``RedisEngine`` que no puede conectarse a +Redis, el motor volverá al ``NullEngine`` y generará un error que se puede registrar. +Esto evita que la aplicación genere una excepción no capturada debido a un error de caché. + +Puedes configurar las configuraciones de la caché para que vuelvan a una configuración especificada usando la clave de configuración ``fallback``:: + + Cache::setConfig('redis', [ + 'className' => 'Redis', + 'duration' => '+1 hours', + 'prefix' => 'cake_redis_', + 'host' => '127.0.0.1', + 'port' => 6379, + 'fallback' => 'default', + ]); + +Si falla la inicialización de la instancia ``RedisEngine``, la configuración de caché ``redis`` +volverá a usar la configuración de caché ``default``. Si también falla la inicialización del +motor para la configuración de caché ``default`` en este escenario, el motor volvería nuevamente al ``NullEngine`` +y evitaría que la aplicación genere una excepción no capturada. + +Puedes desactivar las caídas de caché con ``false``:: + + Cache::setConfig('redis', [ + 'className' => 'Redis', + 'duration' => '+1 hours', + 'prefix' => 'cake_redis_', + 'host' => '127.0.0.1', + 'port' => 6379, + 'fallback' => false + ]); + +Cuando no hay una caída, los errores de caché se generarán como excepciones. + +Eliminación de Motores de Caché Configurados +--------------------------------------------- + +.. php:staticmethod:: drop($clave) + +Una vez que se crea una configuración, no puedes cambiarla. En su lugar, debes eliminar +la configuración y volver a crearla usando :php:meth:`Cake\\Cache\\Cache::drop()` y +:php:meth:`Cake\\Cache\\Cache::setConfig()`. Eliminar un motor de caché eliminará +la configuración y destruirá el adaptador si se construyó. + +Escritura en Caché +================== + +.. php:staticmethod:: write($clave, $valor, $configuracion = 'default') + +``Cache::write()`` escribirá un $valor en la caché. Puedes leer o +eliminar este valor más tarde refiriéndote a él por ``$clave``. Puedes +especificar una configuración opcional para almacenar la caché también. Si +no se especifica ninguna ``$configuración``, se usará la predeterminada. ``Cache::write()`` +puede almacenar cualquier tipo de objeto y es ideal para almacenar resultados de +búsquedas de modelos:: + + $entradas = Cache::read('entradas'); + if ($entradas === null) { + $entradas = $servicio->obtenerTodasLasEntradas(); + Cache::write('entradas', $entradas); + } + +Usar ``Cache::write()`` y ``Cache::read()`` para reducir el número +de consultas realizadas a la base de datos para obtener las entradas. + +.. note:: + + Si planeas almacenar en caché el resultado de las consultas realizadas con el ORM de CakePHP, + es mejor utilizar las capacidades de almacenamiento en caché integradas del objeto de consulta + como se describe en la sección de :ref:`caching-query-results` + +Escritura de Múltiples Claves a la Vez +-------------------------------------- + +.. php:staticmethod:: writeMany($datos, $configuracion = 'default') + +Puede que necesites escribir múltiples claves de caché a la vez. Aunque podrías usar múltiples llamadas a ``write()``, ``writeMany()`` permite a CakePHP utilizar +API de almacenamiento más eficientes cuando están disponibles. Por ejemplo, usando ``writeMany()`` +ahorras múltiples conexiones de red cuando usas Memcached:: + + $resultado = Cache::writeMany([ + 'articulo-' . $slug => $articulo, + 'articulo-' . $slug . '-comentarios' => $comentarios + ]); + + // $resultado contendrá + ['articulo-primer-post' => true, 'articulo-primer-post-comentarios' => + + true] + +Escrituras Atómicas +------------------- + +.. php:staticmethod:: add($clave, $valor, $configuracion = 'default') + +Usar ``Cache::add()`` te permitirá establecer atómicamente una clave en un valor si la clave +aún no existe en la caché. Si la clave ya existe en el backend de la caché o la escritura falla, ``add()`` devolverá ``false``:: + + // Establecer una clave para actuar como bloqueo + $resultado = Cache::add($claveBloqueo, true); + if (!$resultado) { + return; + } + // Realizar una acción donde solo puede haber un proceso activo a la vez. + + // Eliminar la clave de bloqueo. + Cache::delete($claveBloqueo); + +.. warning:: + + La caché basada en archivos no admite escrituras atómicas. + +Caché de Lectura Directa +------------------------ + +.. php:staticmethod:: remember($clave, $callable, $configuracion = 'default') + +La caché ayuda con la caché de lectura directa. Si la clave de caché nombrada existe, +se devolverá. Si la clave no existe, se invocará la función de llamada +y los resultados se almacenarán en la caché en la clave proporcionada. + +Por ejemplo, a menudo quieres cachear los resultados de las llamadas a servicios remotos. Puedes usar +``remember()`` para hacerlo simple:: + + class ServicioDeAsunto + { + public function todasLasTemas($repositorio) + { + return Cache::remember($repositorio . '-temas', function () use ($repositorio) { + return $this->obtenerTodos($repositorio); + }); + } + } + +Lectura Desde la Caché +====================== + +.. php:staticmethod:: read($clave, $configuracion = 'default') + +``Cache::read()`` se usa para leer el valor en caché almacenado bajo +``$clave`` desde la ``$configuración``. Si ``$configuración`` es nulo, se usará la configuración predeterminada +configuración. ``Cache::read()`` devolverá el valor en caché +si es una caché válida o ``null`` si la caché ha caducado o +no existe. Utiliza los operadores de comparación estricta ``===`` o ``!==`` +para comprobar el éxito de la operación ``Cache::read()``. + +Por ejemplo:: + + $nube = Cache::read('nube'); + if ($nube !== null) { + return $nube; + } + + // Generar datos de la nube + // ... + + // Almacenar datos en la caché + Cache::write('nube', $nube); + + return $nube; + +O si estás usando otra configuración de caché llamada ``corta``, puedes +especificarlo en las llamadas a ``Cache::read()`` y ``Cache::write()`` de la siguiente manera:: + + // Leer la clave "nube", pero de la configuración corta en lugar de la predeterminada + $nube = Cache::read('nube', 'corta'); + if ($nube === null) { + // Generar datos de la nube + // ... + + // Almacenar datos en la caché, usando la configuración de caché corta en lugar de la predeterminada + Cache::write('nube', $nube, 'corta'); + } + + return $nube; + +Lectura de Múltiples Claves a la Vez +------------------------------------- + +.. php:staticmethod:: readMany($claves, $configuracion = 'default') + +Después de haber escrito múltiples claves a la vez, probablemente querrás leerlas también. Aunque podrías usar múltiples llamadas a ``read()``, ``readMany()`` permite +a CakePHP utilizar API de almacenamiento más eficientes donde estén disponibles. Por ejemplo, usando +``readMany()`` ahorras múltiples conexiones de red cuando usas Memcached:: + + $resultado = Cache::readMany([ + 'articulo-' . $slug, + 'articulo-' . $slug . '-comentarios' + ]); + // $resultado contendrá + ['articulo-primer-post' => '...', 'articulo-primer-post-comentarios' => '...'] + +Eliminación de la Caché +======================= + +.. php:staticmethod:: delete($clave, $configuracion = 'default') + +``Cache::delete()`` te permitirá eliminar completamente un objeto en caché +del almacén:: + + // Eliminar una clave + Cache::delete('mi_clave'); + +A partir de la versión 4.4.0, el ``RedisEngine`` también proporciona un método ``deleteAsync()`` que utiliza la operación ``UNLINK`` para eliminar las claves de caché:: + + Cache::pool('redis')->deleteAsync('mi_clave'); + +Eliminación de Múltiples Claves a la Vez +---------------------------------------- + +.. php:staticmethod:: deleteMany($claves, $configuracion = 'default') + +Después de haber escrito múltiples claves a la vez, es posible que desees eliminarlas. Aunque +podrías usar múltiples llamadas a ``delete()``, ``deleteMany()`` permite a CakePHP utilizar +API de almacenamiento más eficientes donde estén disponibles. Por ejemplo, usando ``deleteMany()`` +ahorras múltiples conexiones de red cuando usas Memcached:: + + $resultado = Cache::deleteMany([ + 'articulo-' . $slug, + 'articulo-' . $slug . '-comentarios' + ]); + // $resultado contendrá + ['articulo-primer-post' => true, 'articulo-primer-post-comentarios' => true] + +Limpieza de Datos en Caché +========================== + +.. php:staticmethod:: clear($configuracion = 'default') + +Elimina todos los valores en caché para una configuración de caché. En motores como: Apcu, +Memcached, se utiliza el prefijo de la configuración de caché para eliminar +entradas de caché. Asegúrate de que las diferentes configuraciones de caché tengan diferentes +prefijos:: + + // Eliminará todas las claves. + Cache::clear(); + +A partir de la versión 4.4.0, el ``RedisEngine`` también proporciona un método ``clearBlocking()`` que utiliza la operación ``UNLINK`` para eliminar las claves de caché:: + + Cache::pool('redis')->clearBlocking(); + +.. note:: + + Debido a que APCu utiliza cachés aisladas para el servidor web y la interfaz de línea de comandos, + deben ser limpiadas por separado (la CLI no puede limpiar el servidor web y viceversa). + +Uso de Caché para Almacenar Contadores +======================================= + +.. php:staticmethod:: increment($key, $offset = 1, $config = 'default') + +.. php:staticmethod:: decrement($key, $offset = 1, $config = 'default') + +Los contadores en tu aplicación son buenos candidatos para ser almacenados en caché. Por ejemplo, +una contador de días para un evento puede ser guardado en la caché. La clase Cache +expone formas de incrementar y decrementar los valores del contador. El hecho de que estas +operaciones sean atómicas es importante para que se reduzca el riesgo de contención y la abilidad de que +dos usuarios simultaneamente incrementen o decrementen el mismo valor. + +Después de guardar un valor entero en la caché, puedes manipularlo usando ``increment()`` y +``decrement()``:: + + Cache::write('initial_count', 10); + + // Later on + Cache::decrement('initial_count'); + + // Or + Cache::increment('initial_count'); + + .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + Recuerda que las operaciones de incremento y decremento no están disponibles en FileEngine. Debes usar APCu, Redis o Memcached. + +.. _caching-query-results: + +Utilizando la Caché para Almacenar Resultados Comunes de Consultas +=================================================================== + +Puedes mejorar significativamente el rendimiento de tu aplicación almacenando en caché los resultados +que rara vez cambian o que están sujetos a lecturas frecuentes. Un ejemplo perfecto de esto son los resultados de +:php:meth:`Cake\\ORM\\Table::find()`. El objeto de consulta te permite almacenar en caché +los resultados utilizando el método ``cache()``. Consulta la sección :ref:`caching-query-results` +para obtener más información. + +.. _cache-groups: + +Uso de Grupos +============= + +A veces querrás marcar varias entradas en caché para que pertenezcan a cierto grupo o espacio de nombres. Esta es una necesidad común para invalidar masivamente claves cada vez que cambia alguna información que se comparte entre todas las entradas en el mismo grupo. Esto es posible declarando los grupos en la configuración de la caché:: + + Cache::setConfig('site_home', [ + 'className' => 'Redis', + 'duration' => '+999 days', + 'groups' => ['comment', 'article'], + ]); + +.. php:method:: clearGroup($group, $config = 'default') + +Digamos que quieres almacenar en caché el HTML generado para tu página de inicio, pero también quieres invalidar automáticamente esta caché cada vez que se agrega un comentario o una publicación a tu base de datos. Al agregar los grupos ``comment`` y ``article``, hemos etiquetado efectivamente cualquier clave almacenada en esta configuración de caché con ambos nombres de grupo. + +Por ejemplo, cada vez que se añade una nueva publicación, podríamos decirle al motor de caché que elimine todas las entradas asociadas al grupo ``article``:: + + // src/Model/Table/ArticlesTable.php + public function afterSave($event, $entity, $options = []) + { + if ($entity->isNew()) { + Cache::clearGroup('article', 'site_home'); + } + } + +.. php:staticmethod:: groupConfigs($group = null) + +``groupConfigs()`` se puede utilizar para recuperar la asignación entre el grupo y las configuraciones, es decir, tener el mismo grupo:: + + // src/Model/Table/ArticlesTable.php + + /** + * Una variación del ejemplo anterior que limpia todas las configuraciones de caché + * que tienen el mismo grupo + */ + public function afterSave($event, $entity, $options = []) + { + if ($entity->isNew()) { + $configs = Cache::groupConfigs('article'); + foreach ($configs['article'] as $config) { + Cache::clearGroup('article', $config); + } + } + } + +Los grupos se comparten en todas las configuraciones de caché que utilizan el mismo motor y el mismo prefijo. Si estás usando grupos y quieres aprovechar la eliminación de grupos, elige un prefijo común para todas tus configuraciones. + +Habilitar o Deshabilitar Globalmente la Caché +============================================= + +.. php:staticmethod:: disable() + +Puede que necesites deshabilitar todas las lecturas y escrituras en la caché cuando intentas resolver problemas relacionados con la expiración de la caché. Puedes hacerlo usando ``enable()`` y ``disable()``:: + + // Deshabilitar todas las lecturas y escrituras en la caché. + Cache::disable(); + +Una vez deshabilitada, todas las lecturas y escrituras devolverán ``null``. + +.. php:staticmethod:: enable() + +Una vez deshabilitada, puedes usar ``enable()`` para habilitar nuevamente la caché:: + + // Habilitar nuevamente todas las lecturas y escrituras en la caché. + Cache::enable(); + +.. php:staticmethod:: enabled() + +Si necesitas verificar el estado de la caché, puedes usar ``enabled()``. + +Creación de un Motor de Caché +============================= + +Puedes proporcionar motores de ``Cache`` personalizados en ``App\Cache\Engine``, así como en plugins usando ``$plugin\Cache\Engine``. Los motores de caché deben estar en un directorio de caché. Si tuvieras un motor de caché llamado ``MyCustomCacheEngine``, se colocaría en **src/Cache/Engine/MyCustomCacheEngine.php**. O en **plugins/MyPlugin/src/Cache/Engine/MyCustomCacheEngine.php** como parte de un plugin. Las configuraciones de caché de los plugins deben utilizar la sintaxis de puntos del plugin:: + + Cache::setConfig('custom', [ + 'className' => 'MyPlugin.MyCustomCache', + // ... + ]); + +Los motores de caché personalizados deben extender :php:class:`Cake\\Cache\\CacheEngine`, que define varios métodos abstractos y también proporciona algunos métodos de inicialización. + +La API requerida para un CacheEngine es + +.. php:class:: CacheEngine + + La clase base para todos los motores de caché utilizados con Cache. + +.. php:method:: write($key, $value) + + :return: booleano para indicar el éxito. + + Escribe el valor de una clave en la caché, devuelve ``true`` si los datos se almacenaron correctamente, ``false`` en caso de fallo. + +.. php:method:: read($key) + + :return: El valor en caché o ``null`` en caso de fallo. + + Lee una clave de la caché. Devuelve ``null`` para indicar que la entrada ha caducado o no existe. + +.. php:method:: delete($key) + + :return: Booleano ``true`` en caso de éxito. + + Elimina una clave de la caché. Devuelve ``false`` para indicar que la entrada no existía o no se pudo eliminar. + +.. php:method:: clear($check) + + :return: Booleano ``true`` en caso de éxito. + + Elimina todas las claves de la caché. Si $check es ``true``, debes validar que cada valor realmente ha caducado. + +.. php:method:: clearGroup($group) + + :return: Booleano ``true`` en caso de éxito. + + Elimina todas las claves de la caché pertenecientes al mismo grupo. + +.. php:method:: decrement($key, $offset = 1) + + :return: Booleano ``true`` en caso de éxito. + + Decrementa un número bajo la clave y devuelve el valor decrecido. + +.. php:method:: increment($key, $offset = 1) + + :return: Booleano ``true`` en caso de éxito. - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + Incrementa un número bajo la clave y devuelve el valor incrementado. .. meta:: - :title lang=es: Caching - :keywords lang=es: uniform api,xcache,cache engine,cache system,atomic operations,php class,disk storage,static methods,php extension,consistent manner,similar features,apc,memcache,queries,cakephp,elements,servers,memory + :title lang=es: Almacenamiento en Caché + :keywords lang=en: uniform api,cache engine,cache system,atomic operations,php class,disk storage,static methods,php extension,consistent manner,similar features,apcu,apc,memcache,queries,cakephp,elements,servers,memory diff --git a/es/core-libraries/email.rst b/es/core-libraries/email.rst index aceaad7e25..1ab482d10d 100644 --- a/es/core-libraries/email.rst +++ b/es/core-libraries/email.rst @@ -1,15 +1,617 @@ -Email -##### +Mailer +###### + +.. php:namespace:: Cake\Mailer + +.. php:class:: Mailer(string|array|null $profile = null) + +``Mailer`` es una clase de conveniencia para enviar correos electrónicos. Con esta clase, puedes enviar correos electrónicos desde cualquier lugar dentro de tu aplicación. + +Uso Básico +========== + +Primero, asegúrate de que la clase esté cargada:: + + use Cake\Mailer\Mailer; + +Después de cargar ``Mailer``, puedes enviar un correo electrónico de la siguiente manera:: + + $mailer = new Mailer('default'); + $mailer->setFrom(['me@example.com' => 'Mi Sitio']) + ->setTo('you@example.com') + ->setSubject('Acerca de') + ->deliver('Mi mensaje'); + +Dado que los métodos setter de ``Mailer`` devuelven una instancia de la clase, puedes configurar sus propiedades encadenando los métodos. + +``Mailer`` tiene varios métodos para definir destinatarios: ``setTo()``, ``setCc()``, ``setBcc()``, ``addTo()``, ``addCc()`` y ``addBcc()``. +La principal diferencia es que los primeros tres sobrescribirán lo que ya se haya establecido, mientras que los últimos simplemente +agregarán más destinatarios a su campo respectivo:: + + $mailer = new Mailer(); + $mailer->setTo('to@example.com', 'Destinatario Ejemplo'); + $mailer->addTo('to2@example.com', 'Destinatario2 Ejemplo'); + // Los destinatarios del correo electrónico son: to@example.com y to2@example.com + $mailer->setTo('test@example.com', 'DestinatarioPrueba Ejemplo'); + // El destinatario del correo electrónico es: test@example.com + +Elección del Remitente +---------------------- + +Cuando envíes correos electrónicos en nombre de otras personas, suele ser una buena idea definir el remitente original usando el encabezado del remitente (Sender header). Puedes hacerlo usando ``setSender()``:: + + $mailer = new Mailer(); + $mailer->setSender('app@example.com', 'Mi aplicación de correo'); .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + También es una buena idea establecer el remitente del sobre (envelope sender) al enviar correos electrónicos en nombre de otra persona. Esto evita que reciban mensajes sobre la entregabilidad. + +.. _email-configuration: + +Configuración +============= + +Los perfiles de Mailer y las configuraciones de transporte de correo electrónico se definen en los archivos de configuración de tu aplicación. Las claves ``'Email'`` y ``'EmailTransport'`` definen perfiles de Mailer y configuraciones de transporte de correo electrónico respectivamente. Durante el inicio de la aplicación, los valores de configuración se pasan desde ``Configure`` a las clases ``Mailer`` y ``TransportFactory`` utilizando ``setConfig()``. Al definir perfiles y transportes, puedes mantener el código de tu aplicación libre de datos de configuración y evitar la duplicación que complica el mantenimiento y el despliegue. + +Para cargar una configuración predefinida, puedes usar el método ``setProfile()`` o pasarlo al constructor de ``Mailer``:: + + $mailer = new Mailer(); + $mailer->setProfile('default'); + + // O en el constructor + $mailer = new Mailer('default'); + +En lugar de pasar una cadena que coincida con un nombre de configuración preestablecido, también puedes cargar simplemente un array de opciones:: + + $mailer = new Mailer(); + $mailer->setProfile(['from' => 'me@example.org', 'transport' => 'my_custom']); + + // O en el constructor + $mailer = new Mailer(['from' => 'me@example.org', 'transport' => 'my_custom']); + +.. _email-configurations: + +Perfiles de Configuración +------------------------- + +Definir perfiles de entrega te permite consolidar la configuración común del correo electrónico en perfiles reutilizables. Tu aplicación puede tener tantos perfiles como sea necesario. Se utilizan las siguientes claves de configuración: + +- ``'from'``: Mailer o array del remitente. Ver ``Mailer::setFrom()``. +- ``'sender'``: Mailer o array del remitente real. Ver ``Mailer::setSender()``. +- ``'to'``: Mailer o array del destino. Ver ``Mailer::setTo()``. +- ``'cc'``: Mailer o array de copia carbono. Ver ``Mailer::setCc()``. +- ``'bcc'``: Mailer o array de copia carbono oculta. Ver ``Mailer::setBcc()``. +- ``'replyTo'``: Mailer o array para responder al correo electrónico. Ver ``Mailer::setReplyTo()``. +- ``'readReceipt'``: Dirección del Mailer o un array de direcciones para recibir + el recibo de lectura. Ver ``Mailer::setReadReceipt()``. +- ``'returnPath'``: Dirección del Mailer o un array de direcciones para devolver si hay + algún error. Ver ``Mailer::setReturnPath()``. +- ``'messageId'``: ID del mensaje del correo electrónico. Ver ``Mailer::setMessageId()``. +- ``'subject'``: Asunto del mensaje. Ver ``Mailer::setSubject()``. +- ``'message'``: Contenido del mensaje. No establezcas este campo si estás usando contenido renderizado. +- ``'priority'``: Prioridad del correo electrónico como valor numérico (generalmente de 1 a 5, siendo 1 el más alto). +- ``'headers'``: Cabeceras a incluir. Ver ``Mailer::setHeaders()``. +- ``'viewRenderer'``: Si estás usando contenido renderizado, establece el nombre de la clase de vista. + Ver ``ViewBuilder::setClassName()``. +- ``'template'``: Si estás usando contenido renderizado, establece el nombre de la plantilla. Ver + ``ViewBuilder::setTemplate()``. +- ``'theme'``: Tema utilizado al renderizar la plantilla. Ver ``ViewBuilder::setTheme()``. +- ``'layout'``: Si estás usando contenido renderizado, establece el diseño a renderizar. Ver + ``ViewBuilder::setTemplate()``. +- ``'autoLayout'``: Si quieres renderizar una plantilla sin diseño, establece este campo en + ``false``. Ver ``ViewBuilder::disableAutoLayout()``. +- ``'viewVars'``: Si estás usando contenido renderizado, establece el array con + variables que se utilizarán en la vista. Ver ``Mailer::setViewVars()``. +- ``'attachments'``: Lista de archivos para adjuntar. Ver ``Mailer::setAttachments()``. +- ``'emailFormat'``: Formato del correo electrónico (html, texto o ambos). Ver ``Mailer::setEmailFormat()``. +- ``'transport'``: Nombre de la configuración del transporte. Ver :ref:`email-transport`. +- ``'log'``: Nivel de registro para registrar las cabeceras y el mensaje del correo electrónico. ``true`` utilizará + LOG_DEBUG. Ver :ref:`logging-levels`. Ten en cuenta que los registros se emitirán bajo el ámbito denominado ``email``. + Ver también :ref:`logging-scopes`. +- ``'helpers'``: Array de helpers utilizados en la plantilla del correo electrónico. + ``ViewBuilder::setHelpers()``/``ViewBuilder::addHelpers()``. + +.. note:: + + Los valores de las claves mencionadas anteriormente que usan Mailer o array, como from, to, cc, etc., se pasarán + como el primer parámetro de los métodos correspondientes. El equivalente a: + ``$mailer->setFrom('mi@example.com', 'Mi Sitio')`` + se definiría como ``'from' => ['mi@example.com' => 'Mi Sitio']`` en tu configuración. + +Configurando Cabeceras +====================== + +En ``Mailer``, eres libre de establecer las cabeceras que desees. No olvides agregar el prefijo ``X-`` a tus cabeceras personalizadas. + +Consulta ``Mailer::setHeaders()`` y ``Mailer::addHeaders()`` + +Envío de Correos Electrónicos con Plantillas +============================================= + +Los correos electrónicos a menudo son mucho más que un simple mensaje de texto. Para facilitar eso, CakePHP proporciona una forma de enviar correos electrónicos utilizando la :doc:`capa de vista ` de CakePHP. + +Las plantillas para correos electrónicos residen en una carpeta especial ``templates/email`` de tu aplicación. Las vistas del Mailer también pueden utilizar diseños y elementos al igual que las vistas normales:: + + $mailer = new Mailer(); + $mailer + ->setEmailFormat('html') + ->setTo('bob@example.com') + ->setFrom('app@domain.com') + ->viewBuilder() + ->setTemplate('bienvenida') + ->setLayout('elegante'); + + $mailer->deliver(); + +Lo anterior utilizará **templates/email/html/bienvenida.php** para la vista +y **templates/layout/email/html/elegante.php** para el diseño. También puedes +enviar mensajes de correo electrónico con varias partes de plantilla:: + + $mailer = new Mailer(); + $mailer + ->setEmailFormat('both') + ->setTo('bob@example.com') + ->setFrom('app@domain.com') + ->viewBuilder() + ->setTemplate('bienvenida') + ->setLayout('elegante'); + + $mailer->deliver(); + +Esto utilizará los siguientes archivos de plantilla: + +* **templates/email/text/bienvenida.php** +* **templates/layout/email/text/elegante.php** +* **templates/email/html/bienvenida.php** +* **templates/layout/email/html/elegante.php** + +Cuando envíes correos electrónicos con plantillas, tienes la opción de enviar ``texto``, ``html`` o ``ambos``. + +Puedes configurar toda la configuración relacionada con la vista usando la instancia de creador de vistas ``Mailer::viewBuilder()`` de manera similar a como lo haces en el controlador. + +Puedes establecer variables de vista con ``Mailer::setViewVars()``:: + + $mailer = new Mailer('plantilla'); + $mailer->setViewVars(['valor' => 12345]); + +O puedes usar los métodos del creador de vistas ``ViewBuilder::setVar()`` y ``ViewBuilder::setVars()``. + +En tus plantillas de correo electrónico, puedes usarlos de la siguiente manera:: + +

Aquí está tu valor:

+ +También puedes usar ayudantes en los correos electrónicos, al igual que en los archivos de plantilla normales. De forma predeterminada, solo se carga el ``HtmlHelper``. Puedes cargar ayudantes adicionales utilizando el método ``ViewBuilder::addHelpers()``:: + + $mailer->viewBuilder()->addHelpers(['Html', 'Custom', 'Text']); + +Cuando agregues ayudantes, asegúrate de incluir 'Html' o se eliminará de los ayudantes cargados en tu plantilla de correo electrónico. + +.. note:: + En versiones anteriores a 4.3.0, deberás usar ``setHelpers()`` en su lugar. + +Si deseas enviar correos electrónicos utilizando plantillas en un plugin, puedes usar la familiar :term:`Sintaxis de plugin` para hacerlo:: + + $mailer = new Mailer(); + $mailer->viewBuilder()->setTemplate('Blog.new_comment'); + +Lo anterior utilizará la plantilla y el diseño del plugin Blog como ejemplo. + +En algunos casos, es posible que necesites anular la plantilla predeterminada proporcionada por los complementos. +Puedes hacer esto usando temas:: + + $mailer->viewBuilder() + ->setTemplate('Blog.new_comment') + ->setLayout('Blog.auto_message') + ->setTheme('MiTema'); + +Esto te permite anular la plantilla "new_comment" en tu tema sin modificar el complemento Blog. El archivo de plantilla debe crearse en la siguiente ruta: +**templates/plugin/MiTema/plugin/Blog/email/text/new_comment.php**. + +Envío de Archivos Adjuntos +=========================== + +.. php:method:: setAttachments($adjuntos) + +También puedes adjuntar archivos a los mensajes de correo electrónico. Hay algunos formatos diferentes dependiendo del tipo de archivos que tengas y de cómo quieras que aparezcan los nombres de archivo en el cliente de correo del destinatario: + +1. Array: ``$mailer->setAttachments(['/ruta/completa/archivo.png'])`` adjuntará este archivo con el nombre archivo.png.. +2. Array con clave: + ``$mailer->setAttachments(['foto.png' => '/ruta/completa/algun_hash.png'])`` adjuntará some_hash.png con el nombre foto.png. El destinatario verá + foto.png, no some_hash.png. +3. Arrays anidados:: + + $mailer->setAttachments([ + 'foto.png' => [ + 'archivo' => '/ruta/completa/algun_hash.png', + 'mimetype' => 'image/png', + 'contentId' => 'mi-id-unico', + ], + ]); + + Lo anterior adjuntará el archivo con un tipo MIME diferente y con un ID de contenido personalizado (cuando se establece el ID de contenido, el archivo adjunto se convierte en incrustado). + El tipo MIME y contentId son opcionales en esta forma. + + 3.1. Cuando estás usando el ``contentId``, puedes usar el archivo en el cuerpo HTML + como ````. + + 3.2. Puedes usar la opción ``contentDisposition`` para desactivar el encabezado ``Content-Disposition`` para un archivo adjunto. Esto es útil cuando + envías invitaciones ical a clientes que usan Outlook. + + 3.3 En lugar de la opción ``archivo``, puedes proporcionar el contenido del archivo como + una cadena utilizando la opción ``datos``. Esto te permite adjuntar archivos sin + necesidad de tener rutas de archivo para ellos. + +Relajando las Reglas de Validación de Direcciones +-------------------------------------------------- + +.. php:method:: setEmailPattern($patrón) + +Si tienes problemas de validación al enviar a direcciones no conformes, puedes relajar el patrón utilizado para validar direcciones de correo electrónico. Esto es a veces +necesario al tratar con algunos proveedores de servicios de Internet:: + + $mailer = new Mailer('predeterminado'); + + // Relaja el patrón de correo electrónico, para que puedas enviar + // a direcciones no conformes. + $mailer->setEmailPattern($nuevoPatrón); + +Envío de Correos Electrónicos desde la CLI +=========================================== + +Cuando envíes correos electrónicos dentro de un script de CLI (Shells, Tasks, ...), debes establecer manualmente +el nombre de dominio que Mailer utilizará. Servirá como el nombre de host para el +ID del mensaje (ya que no hay un nombre de host en un entorno CLI):: + + $mailer->setDomain('www.ejemplo.org'); + // Da como resultado IDs de mensajes como ```` (válidos) + // En lugar de ```` (inválidos) + +Un ID de mensaje válido puede ayudar a evitar que los correos electrónicos terminen en carpetas de spam. + +Creación de Correos Electrónicos Reutilizables +=============================================== + +Hasta ahora hemos visto cómo usar directamente la clase ``Mailer`` para crear y +enviar un correo electrónico. Pero la característica principal del mailer es permitir la creación de correos electrónicos reutilizables +en toda tu aplicación. También se pueden usar para contener múltiples +configuraciones de correo electrónico en un solo lugar. Esto ayuda a mantener tu código DRY y a evitar la configuración de correo electrónico +en otras áreas de tu aplicación. + +En este ejemplo, crearemos un ``Mailer`` que contiene correos electrónicos relacionados con el usuario. +Para crear nuestro ``UserMailer``, crea el archivo +**src/Mailer/UserMailer.php**. El contenido del archivo debería verse así:: + + namespace App\Mailer; + + use Cake\Mailer\Mailer; + + class UserMailer extends Mailer + { + public function welcome($user) + { + $this + ->setTo($user->email) + ->setSubject(sprintf('Welcome %s', $user->name)) + ->viewBuilder() + ->setTemplate('welcome_mail'); // Por defecto, se utiliza la plantilla con el mismo nombre que el nombre del método. + } + + public function resetPassword($user) + { + $this + ->setTo($user->email) + ->setSubject('Reset password') + ->setViewVars(['token' => $user->token]); + } + } + + +En nuestro ejemplo, hemos creado dos métodos, uno para enviar un correo electrónico de bienvenida y +otro para enviar un correo electrónico de restablecimiento de contraseña. Cada uno de estos métodos espera una entidad de usuario +y utiliza sus propiedades para configurar cada correo electrónico. + +Ahora podemos usar nuestro ``UserMailer`` para enviar nuestros correos electrónicos relacionados con el usuario +desde cualquier parte de nuestra aplicación. Por ejemplo, si queremos enviar nuestro correo de bienvenida +podríamos hacer lo siguiente:: + + namespace App\Controller; + + use Cake\Mailer\MailerAwareTrait; + + class UsersController extends AppController + { + use MailerAwareTrait; + + public function register() + { + $user = + + $this->Users->newEmptyEntity(); + if ($this->request->is('post')) { + $user = $this->Users->patchEntity($user, $this->request->getData()); + if ($this->Users->save($user)) { + // Enviar correo electrónico de bienvenida. + $this->getMailer('User')->send('welcome', [$user]); + // Redirigir a la página de inicio de sesión u otra página de destino. + return $this->redirect(['controller' => 'Users', 'action' => 'login']); + } + $this->Flash->error(__('Unable to register user. Please try again.')); + } + $this->set(compact('user')); + } + } + +Si quisiéramos separar por completo el envío del correo de bienvenida del usuario de nuestro código de aplicación, podemos hacer que nuestro +`UserMailer` se suscriba al evento `Model.afterSave`. Al suscribirse a un evento, podemos mantener nuestras clases relacionadas con el +usuario completamente libres de lógica e instrucciones relacionadas con el correo electrónico de nuestra aplicación. Por ejemplo, +podríamos agregar lo siguiente a nuestro `UserMailer`:: + + public function implementedEvents() + { + return [ + 'Model.afterSave' => 'onRegistration', + ]; + } + + public function onRegistration(EventInterface $event, EntityInterface $entity, ArrayObject $options) + { + if ($entity->isNew()) { + $this->send('welcome', [$entity]); + } + } + +Ahora puedes registrar el mailer como un oyente de eventos y el método `onRegistration()` se invocará cada vez que se dispare el evento `Model.afterSave`:: + + // Adjuntar al gestor de eventos de Usuarios + $this->Users->getEventManager()->on($this->getMailer('User')); + +:: note :: + + Para obtener información sobre cómo registrar objetos oyentes de eventos, consulta la documentación de :ref:`registro-de-oyentes-de-eventos`. + +.. _email-transport: + +Configuración de Transportes +============================ + +Los mensajes de correo electrónico se entregan mediante transportes. Diferentes transportes te permiten enviar mensajes a través de la función `mail()` +de PHP, servidores SMTP o no enviarlos en absoluto, lo cual es útil para depurar. Configurar transportes te permite mantener los datos de configuración +fuera del código de tu aplicación y simplifica la implementación, ya que simplemente puedes cambiar los datos de configuración. Una configuración de +transporte de ejemplo se ve así:: + + // En config/app.php + 'EmailTransport' => [ + // Configuración de ejemplo para correo + 'default' => [ + 'className' => 'Mail', + ], + // Configuración de ejemplo para SMTP + 'gmail' => [ + 'host' => 'smtp.gmail.com', + 'port' => 587, + 'username' => 'mi@gmail.com', + 'password' => 'secreto', + 'className' => 'Smtp', + 'tls' => true, + ], + ], + +Los transportes también se pueden configurar en tiempo de ejecución utilizando `TransportFactory::setConfig()`:: + + use Cake\Mailer\TransportFactory; + + // Definir un transporte SMTP + TransportFactory::setConfig('gmail', [ + 'host' => 'ssl://smtp.gmail.com', + 'port' => 465, + 'username' => 'mi@gmail.com', + 'password' => 'secreto', + 'className' => 'Smtp' + ]); + +Puedes configurar servidores SMTP SSL, como Gmail. Para hacerlo, coloca el prefijo `ssl://` en el host y configura el valor del puerto en consecuencia. También puedes habilitar SMTP TLS usando la opción `tls`:: + + use Cake\Mailer\TransportFactory; + + TransportFactory::setConfig('gmail', [ + 'host' => 'smtp.gmail.com', + 'port' => 587, + 'username' => 'mi@gmail.com', + 'password' => 'secreto', + 'className' => 'Smtp', + 'tls' => true + ]); + +La configuración anterior habilitaría la comunicación TLS para los mensajes de correo electrónico. + +Para configurar tu mailer para usar un transporte específico, puedes usar el método :php:meth:`Cake\\Mailer\\Mailer::setTransport()` o tener el transporte en tu configuración:: + + + // Usa un transporte con nombre ya configurado usando TransportFactory::setConfig() + $mailer->setTransport('gmail'); + + // Usa un objeto construido. + $mailer->setTransport(new \Cake\Mailer\Transport\DebugTransport()); + +:: warning :: + + Deberás tener habilitado el acceso para aplicaciones menos seguras en tu cuenta de Google para que funcione: + `Permitir que aplicaciones menos seguras accedan a tu cuenta `__. + +:: note :: +   `Configuración SMTP de Gmail `__. + +:: note :: + Para usar SSL + SMTP, necesitarás tener SSL configurado en tu instalación de PHP. + +También se pueden proporcionar opciones de configuración como una cadena :term:`DSN`. Esto es útil cuando trabajas con variables de entorno o proveedores de :term:`PaaS`:: + + TransportFactory::setConfig('default', [ + 'url' => 'smtp://mi@gmail.com:secreto@smtp.gmail.com:587?tls=true', + ]); + +Cuando usas una cadena DSN, puedes definir cualquier parámetro / opción adicional como argumentos de cadena de consulta. + +.. php:staticmethod:: drop($key) + +Una vez configurados, los transportes no se pueden modificar. Para modificar un transporte, primero debes eliminarlo y luego reconfigurarlo. + +Creación de Transportes Personalizados +-------------------------------------- + +Puedes crear tus propios transportes para situaciones como enviar correos electrónicos utilizando servicios como SendGrid, MailGun +o Postmark. Para crear tu transporte, primero crea el archivo **src/Mailer/Transport/ExampleTransport.php** (donde Example es el +nombre de tu transporte). Para empezar, tu archivo debería verse así:: + + namespace App\Mailer\Transport; + + use Cake\Mailer\AbstractTransport; + use Cake\Mailer\Message; + + class ExampleTransport extends AbstractTransport + { + public function send(Message $message): array + { + // Haz algo. + } + } + +Debes implementar el método ``send(Message $message)`` con tu lógica personalizada. + +Envío de correos electrónicos sin usar Mailer +============================================= + +El ``Mailer`` es una clase de abstracción de nivel superior que actúa como un puente entre las clases ``Cake\Mailer\Message``, ``Cake\Mailer\Renderer`` y ``Cake\Mailer\AbstractTransport`` para configurar correos electrónicos con una interfaz fluida. + +Si lo deseas, también puedes usar estas clases directamente con el ``Mailer``. + +Por ejemplo:: + + $render = new \Cake\Mailer\Renderer(); + $render->viewBuilder() + ->setTemplate('custom') + ->setLayout('sparkly'); + + $message = new \Cake\Mailer\Message(); + $message + ->setFrom('admin@cakephp.org') + ->setTo('user@foo.com') + ->setBody($render->render()); + + $transport = new \Cake\Mailer\Transport\MailTransport(); + $result = $transport->send($message); + +Incluso puedes omitir el uso del ``Renderer`` y establecer el cuerpo del mensaje directamente +usando los métodos ``Message::setBodyText()`` y ``Message::setBodyHtml()``. + +.. _email-testing: + +Pruebas de Mailers +================== + +Para probar mailers, agrega ``Cake\TestSuite\EmailTrait`` a tu caso de prueba.El ``MailerTrait`` +utiliza ganchos de PHPUnit para reemplazar los transportes de correo electrónico de tu aplicación +con un proxy que intercepta los mensajes de correo electrónico y te permite hacer afirmaciones +sobre el correo que se enviaría. + +Agrega el trait a tu caso de prueba para comenzar a probar correos electrónicos, y carga rutas si tus +correos electrónicos necesitan generar URL:: + + namespace App\Test\TestCase\Mailer; + + use App\Mailer\WelcomeMailer; + use App\Model\Entity\User; + + use Cake\TestSuite\EmailTrait; + use Cake\TestSuite\TestCase; + + class WelcomeMailerTestCase extends TestCase + { + use EmailTrait; + + public function setUp(): void + { + parent::setUp(); + $this->loadRoutes(); + } + } + +Supongamos que tenemos un mailer que envía correos electrónicos de bienvenida cuando un nuevo usuario +se registra. Queremos comprobar que el asunto y el cuerpo contienen el nombre del usuario:: + + // en nuestra clase WelcomeMailerTestCase. + public function testName() + { + $user = new User([ + 'name' => 'Alice Alittea', + 'email' => 'alice@example.org', + ]); + $mailer = new WelcomeMailer(); + $mailer->send('welcome', [$user]); + + $this->assertMailSentTo($user->email); + $this->assertMailContainsText('Hola ' . $user->name); + $this->assertMailContainsText('¡Bienvenido a CakePHP!'); + } + +Métodos de afirmación +---------------------- + +El trait ``Cake\TestSuite\EmailTrait`` proporciona las siguientes afirmaciones:: + + // Asegura que se enviaron un número esperado de correos electrónicos + $this->assertMailCount($count); + + // Asegura que no se enviaron correos electrónicos + $this->assertNoMailSent(); + + // Asegura que se envió un correo electrónico a una dirección + $this->assertMailSentTo($address); + + // Asegura que se envió un correo electrónico desde una dirección + $this->assertMailSentFrom($emailAddress); + $this->assertMailSentFrom([$emailAddress => $displayName]); + + // Asegura que un correo electrónico contiene los contenidos esperados + $this->assertMailContains($contents); + + // Asegura que un correo electrónico contiene los contenidos HTML esperados + $this->assertMailContainsHtml($contents); + + // Asegura que un correo electrónico contiene los contenidos de texto esperados + $this->assertMailContainsText($contents); + + // Asegura que un correo electrónico contiene el valor esperado dentro de un getter de Message (por ejemplo, "subject") + $this->assertMailSentWith($expected, $parameter); + + // Asegura que un correo electrónico en un índice específico se envió a una dirección + $this->assertMailSentToAt($at, $address); + + // Asegura que un correo electrónico en un índice específico se envió desde una dirección + $this->assertMailSentFromAt($at, $address); + + // Asegura que un correo electrónico en un índice específico contiene los contenidos esperados + $this->assertMailContainsAt($at, $contents); + + // Asegura que un correo electrónico en un índice específico contiene los contenidos HTML esperados + $this->assertMailContainsHtmlAt($at, $contents); + + // Asegura que un correo electrónico en un índice específico contiene los contenidos de texto esperados + $this->assertMailContainsTextAt($at, $contents); + + // Asegura que un correo electrónico contiene un archivo adjunto + $this->assertMailContainsAttachment('test.png'); + + // Asegura que un correo electrónico en un índice específico contiene el valor esperado dentro de un getter de Message (por ejemplo, "cc") + $this->assertMailSentWithAt($at, $expected, $parameter); + + // Asegura que un correo electrónico contiene una subcadena en el asunto. + $this->assertMailSubjectContains('Oferta Gratuita'); - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + // Asegura que un correo electrónico en un índice específico contiene una subcadena en el asunto. + $this->assertMailSubjectContainsAt(1, 'Oferta Gratuita'); .. meta:: - :title lang=es: Email - :keywords lang=es: sending mail,email sender,envelope sender,php class,database configuration,sending emails,meth,shells,smtp,transports,attributes,array,config,flexibility,php email,new email,sending email,models + :title lang=es: Correo Electrónico + :keywords lang=en: sending mail,email sender,envelope sender,php class,database configuration,sending emails,commands,smtp,transports,attributes,array,config,flexibility,php email,new email,sending email,models diff --git a/es/core-libraries/inflector.rst b/es/core-libraries/inflector.rst index 2f857aa8aa..b5616621da 100644 --- a/es/core-libraries/inflector.rst +++ b/es/core-libraries/inflector.rst @@ -5,15 +5,177 @@ Inflector .. php:class:: Inflector +La clase `Inflector` toma una cadena y puede manipularla para manejar variaciones de palabras como +pluralización o conversión a formato camello (camelCase). Por lo general, se accede a esta clase de +manera estática. Por ejemplo: + +``Inflector::pluralize('example')`` devuelve "examples". + +Puedes probar las inflecciones en línea en `inflector.cakephp.org +`_ or `sandbox.dereuromark.de +`_. + +.. _inflector-methods-summary: + +Métodos integrados en Inflector y su resultado +============================================== + +Los métodos integrados en el Inflector y los resultados que generan al proporcionarles un argumento compuesto por varias palabras: + ++-------------------+---------------+---------------+ +| Método | Argumento | Resultado | ++===================+===============+===============+ +| ``pluralize()`` | BigApple | BigApples | ++ +---------------+---------------+ +| | big_apple | big_apples | ++-------------------+---------------+---------------+ +| ``singularize()`` | BigApples | BigApple | ++ +---------------+---------------+ +| | big_apples | big_apple | ++-------------------+---------------+---------------+ +| ``camelize()`` | big_apples | BigApples | ++ +---------------+---------------+ +| | big apple | BigApple | ++-------------------+---------------+---------------+ +| ``underscore()`` | BigApples | big_apples | ++ +---------------+---------------+ +| | Big Apples | big apples | ++-------------------+---------------+---------------+ +| ``humanize()`` | big_apples | Big Apples | ++ +---------------+---------------+ +| | bigApple | BigApple | ++-------------------+---------------+---------------+ +| ``classify()`` | big_apples | BigApple | ++ +---------------+---------------+ +| | big apple | BigApple | ++-------------------+---------------+---------------+ +| ``dasherize()`` | BigApples | big-apples | ++ +---------------+---------------+ +| | big apple | big apple | ++-------------------+---------------+---------------+ +| ``tableize()`` | BigApple | big_apples | ++ +---------------+---------------+ +| | Big Apple | big apples | ++-------------------+---------------+---------------+ +| ``variable()`` | big_apple | bigApple | ++ +---------------+---------------+ +| | big apples | bigApples | ++-------------------+---------------+---------------+ + +Generando formas Plural y Singular +================================== + +.. php:staticmethod:: singularize($singular) +.. php:staticmethod:: pluralize($singular) + +Both ``pluralize`` and ``singularize()`` work on most English nouns. If you need +to support other languages, you can use :ref:`inflection-configuration` to +customize the rules used:: + + // Apples + echo Inflector::pluralize('Apple'); + .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + ``pluralize()`` no debería ser usado en un nombre que ya está en su forma plural. + +.. code-block:: php + + // Person + echo Inflector::singularize('People'); + +.. note:: + + ``singularize()`` no debería ser usado en un nombre que ya está en su forma singular. + +Generando formas CamelCase y under_scored +========================================= + +.. php:staticmethod:: camelize($underscored) +.. php:staticmethod:: underscore($camelCase) + +Estos métodos son útiles cuando creas nombres de clases o de propiedades:: + + // ApplePie + Inflector::camelize('Apple_pie') + + // apple_pie + Inflector::underscore('ApplePie'); + +Nótese que el método *underscore* sólo convertirá palabras en formato *CamelCase*. +Palabras que contengan espacios serán transformadas a minúscula pero no contendrán un guión bajo. + +Generando formas legibles por humanos +===================================== + +.. php:staticmethod:: humanize($underscored) + +Este método es útil cuando se quiere convertir una palabra de la forma *under_scored* al formato "Título" para que sea legible por un ser humano:: + + // Apple Pie + Inflector::humanize('apple_pie'); + +Generando formas de tabla y nombre de clase +=========================================== + +.. php:staticmethod:: classify($underscored) +.. php:staticmethod:: dasherize($dashed) +.. php:staticmethod:: tableize($camelCase) + +Cuando se genera código, o usando las convenciones de CakePHP tu puedes necesitar generar inflecciones para los nombres de tabla o de clase:: + + // UserProfileSetting + Inflector::classify('user_profile_settings'); + + // user-profile-setting + Inflector::dasherize('UserProfileSetting'); + + // user_profile_settings + Inflector::tableize('UserProfileSetting'); + +Generando Nombres de Variables +============================== + +.. php:staticmethod:: variable($underscored) + +Los nombres de variable son a menudo útiles cuando se hacen tareas de meta-programación que involucran generar código o hacer trabajo basado en convenciones:: + + // applePie + Inflector::variable('apple_pie'); + + +.. _inflection-configuration: + +Configurando las Inflecciones +============================= + +Las convenciones de nomenclatura de CakePHP pueden ser muy útiles: puedes nombrar tu +tabla de base de datos como ``big_boxes``, tu modelo como ``BigBoxes``, tu controlador +como ``BigBoxesController``, y todo funcionará automáticamente juntos. La forma en que +CakePHP sabe cómo vincular las cosas es *inflectando* las palabras entre sus formas +singular y plural. + +Existen ocasiones (especialmente para nuestros amigos que no hablan inglés) en las que +podrías encontrarte con situaciones donde el inflector de CakePHP (la clase que pluraliza, +singulariza, utiliza notación camello y subrayados) puede no funcionar como deseas. Si +CakePHP no reconoce tus "Foci" o "Fish", puedes indicarle a CakePHP acerca de tus casos especiales. + +Cargando Inflecciones Personalizadas +------------------------------------ + +.. php:staticmethod:: rules($type, $rules, $reset = false) + +Define nuevas reglas de inflexión y transliteración para que Inflector las utilice. A menudo, este método se utiliza +en tu archivo **config/bootstrap.php**:: + + Inflector::rules('singular', ['/^(bil)er$/i' => '\1', '/^(inflec|contribu)tors$/i' => '\1ta']); + Inflector::rules('uninflected', ['singulars']); + Inflector::rules('irregular', ['phylum' => 'phyla']); // The key is singular form, value is plural form - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +Las reglas suministradas se fusionarán en los conjuntos de inflexión respectivos definidos en ``Cake/Utility/Inflector``, +y las reglas añadidas tendrán prioridad sobre las reglas principales del núcleo. Puedes usar ``Inflector::reset()`` +para eliminar las reglas y restaurar el estado original del Inflector." .. meta:: - :title lang=es: Inflector - :keywords lang=es: apple orange,word variations,apple pie,person man,latin versions,profile settings,php class,initial state,puree,slug,apples,oranges,user profile,underscore + :title lang=es: Objeto Inflector + :keywords lang=en: apple orange,word variations,apple pie,person man,latin versions,profile settings,php class,initial state,puree,slug,apples,oranges,user profile,underscore diff --git a/es/development/configuration.rst b/es/development/configuration.rst index 322d2a7453..195135d284 100644 --- a/es/development/configuration.rst +++ b/es/development/configuration.rst @@ -1,15 +1,504 @@ -Configuration +Configuración ############# +Aunque las convenciones eliminan la necesidad de configurar todas las partes de CakePHP, +todavía necesitarás configurar algunas cosas, como las credenciales de tu base de datos. + +Además, existen opciones de configuración opcionales que te permiten cambiar los valores +y las implementaciones predeterminadas por otros personalizados para tu aplicación. + +.. index:: app.php, app_local.example.php + +.. index:: configuration + +Configurando tu Aplicación +============================ + +La configuración generalmente se almacena en archivos PHP o INI, y se carga durante el inicio +de la aplicación. CakePHP viene con un archivo de configuración por defecto, pero si es necesario, +puedes agregar archivos de configuración adicionales y cargarlos en el código de inicio de tu +aplicación. La clase :php:class:`Cake\\Core\\Configure` se utiliza para la configuración global, +y clases como ``Cache`` proporcionan métodos como ``setConfig()`` para hacer que la configuración +sea simple y transparente. + +El esqueleto de la aplicación incluye un archivo **config/app.php** que debería contener configuraciones +que no varían en los diversos entornos en los que se despliega tu aplicación. El archivo **config/app_local.php** +debería contener datos de configuración que varían entre los entornos y deben ser gestionados por +herramientas de gestión de configuración o tus herramientas de implementación. Ambos archivos hacen +referencia a variables de entorno a través de la función ``env()`` que permite establecer valores +de configuración a través del entorno del servidor. + +Cargar Archivos de Configuración Adicionales +--------------------------------------------- + +Si tu aplicación tiene muchas opciones de configuración, puede ser útil dividir la configuración +en varios archivos. Después de crear cada uno de los archivos en tu directorio **config/**, puedes +cargarlos en **bootstrap.php**:: + + use Cake\Core\Configure; + use Cake\Core\Configure\Engine\PhpConfig; + + Configure::setConfig('default', new PhpConfig()); + Configure::load('app', 'default', false); + Configure::load('other_config', 'default'); + +.. _environment-variables: + +Variables de Entorno +===================== + +Muchos proveedores de servicios en la nube modernos, como Heroku, te permiten definir variables de +entorno para datos de configuración. Puedes configurar tu aplicación CakePHP a través de variables +de entorno en el estilo de aplicación `12factor `. Las variables de entorno +permiten que tu aplicación sea fácil de gestionar cuando se implementa en varios entornos. + +Como puedes ver en tu archivo **app.php**, la función ``env()`` se utiliza para leer la configuración +del entorno y construir la configuración de la aplicación. CakePHP utiliza cadenas de conexión :term:`DSN` +para bases de datos, registros, transportes de correo electrónico y configuraciones de caché, lo que +te permite variar fácilmente estas bibliotecas en cada entorno. + +Para el desarrollo local, CakePHP utiliza `dotenv `_ para +recargar automáticamente las variables de entorno locales. Utiliza Composer para requerir esta biblioteca +y luego hay un bloque de código en ``bootstrap.php`` que debe descomentarse para aprovecharla. + +Encontrarás un archivo ``config/.env.example`` en tu aplicación. Al copiar este archivo en ``config/.env`` +y personalizar los valores, puedes configurar tu aplicación. + +Debes evitar incluir el archivo ``config/.env`` en tu repositorio y, en su lugar, utilizar +``config/.env.example`` como una plantilla con valores predeterminados para que todos +en tu equipo sepan qué variables de entorno se están utilizando y qué debe ir en cada una. + +Una vez que se hayan establecido tus variables de entorno, puedes usar ``env()`` para leer datos del entorno:: + + $debug = env('APP_DEBUG', false); + +El segundo valor pasado a la función env es el valor predeterminado. Este valor se utilizará si no existe una +variable de entorno para la clave dada. + +.. _general-configuration: + +Configuración General +---------------------- + +A continuación se muestra una descripción de las variables y cómo afectan a tu aplicación CakePHP. + +- **debug** + Cambia la salida de depuración de CakePHP. ``false`` = Modo de producción. No se muestran mensajes de error o advertencias. ``true`` = Se muestran errores y advertencias. + +- **App.namespace** + El espacio de nombres para encontrar las clases de la aplicación. + + .. note:: + + Al cambiar el espacio de nombres en tu configuración, también deberás actualizar tu archivo **composer.json** para usar este espacio de nombres. Además, crea un nuevo autoloader ejecutando ``php composer.phar dumpautoload``. + +- **App.baseUrl** + Descomenta esta definición si **no** planeas usar mod_rewrite de Apache con CakePHP. No olvides eliminar tus archivos .htaccess también. + +- **App.base** + El directorio base en el que reside la aplicación. Si es ``false``, se detectará automáticamente. Si no es ``false``, asegúrate de que tu cadena comience con un `/` y **NO** termine con un `/`. Por ejemplo, `/basedir` es un valor válido para App.base. + +- **App.encoding** + Define qué codificación utiliza tu aplicación. Esta codificación se utiliza para definir la codificación en las vistas y codificar entidades. Debería coincidir con los valores de codificación especificados para tu base de datos. + +- **App.webroot** + El directorio webroot. + +- **App.wwwRoot** + La ruta de archivo al directorio webroot. + +- **App.fullBaseUrl** + El nombre de dominio completamente cualificado (incluyendo el protocolo) hasta la raíz de tu aplicación. Se utiliza al generar URLs absolutas. Por defecto, este valor se genera utilizando la variable ``$_SERVER`` del entorno. Sin embargo, debes definirlo manualmente para optimizar el rendimiento o si te preocupa que las personas manipulen el encabezado "Host". En un contexto CLI (desde la línea de comandos), el `fullBaseUrl` no se puede leer de $_SERVER, ya que no hay un servidor web involucrado. Debes especificarlo tú mismo si necesitas generar URLs desde una terminal (por ejemplo, al enviar correos electrónicos). + +- **App.imageBaseUrl** + Ruta web al directorio público de imágenes dentro del webroot. Si estás utilizando un :term:`CDN`, debes configurar este valor con la ubicación del CDN. + +- **App.cssBaseUrl** + Ruta web al directorio público de CSS dentro del webroot. Si estás utilizando un :term:`CDN`, debes configurar este valor con la ubicación del CDN. + +- **App.jsBaseUrl** + Ruta web al directorio público de JavaScript dentro del webroot. Si estás utilizando un :term:`CDN`, debes configurar este valor con la ubicación del CDN. + +- **App.paths** + Configura rutas para recursos que no son de clase. Admite las subclaves ``plugins``, ``templates``, ``locales``, que permiten la definición de rutas para los archivos de plugins, plantillas de vista y archivos de traducción, respectivamente. + +- **App.uploadedFilesAsObjects** + Define si los archivos cargados se representan como objetos (``true``) o como arrays (``false``). Esta opción está habilitada de forma predeterminada. Consulta la sección :ref:`File Uploads ` en el capítulo de Objetos de Request & Response para obtener más información. + +- **Security.salt** + Una cadena aleatoria utilizada en el cifrado. Esta cadena también se utiliza como la sal de HMAC al hacer cifrado simétrico. + +- **Asset.timestamp** + Añade una marca de tiempo, que es la última vez que se modificó el archivo en particular, al final de las URLs de los archivos de activos (CSS, JavaScript, Imagen) cuando se utilizan los ayudantes adecuados. Valores válidos: + + - (bool) ``false`` - No hace nada (predeterminado) + - (bool) ``true`` - Añade la marca de tiempo cuando el modo de depuración es ``true`` + - (string) 'force' - Siempre añade la marca de tiempo. + +- **Asset.cacheTime** + Establece el tiempo de caché del archivo de activo. Esto determina el encabezado ``Cache-Control`` de HTTP's ``max-age`` y el tiempo de ``Expire`` del encabezado de HTTP para los activos. Esto puede tomar cualquier valor que la función `strtotime `_ tu versión de PHP pueda tomar. El valor predeterminado es ``+1 día``. + +Usar un CDN +----------- + +Para utilizar un CDN para cargar tus activos estáticos, cambia las variables ``App.imageBaseUrl``, ``App.cssBaseUrl``, ``App.jsBaseUrl`` para que apunten a la URI del CDN, por ejemplo: ``https://micdn.ejemplo.com/`` (nota la barra diagonal al final ``/``). + +Todas las imágenes, scripts y estilos cargados a través de HtmlHelper agregarán la ruta absoluta del CDN, coincidiendo con la misma ruta relativa utilizado en la aplicación. Ten en cuenta que hay un caso de uso específico cuando se utilizan activos basados en plugins: los plugins no utilizarán el prefijo del plugin cuando se utiliza una URI absoluta ``...BaseUrl``, por ejemplo, por defecto: + +* ``$this->Helper->assetUrl('TestPlugin.logo.png')`` resuelve a ``test_plugin/logo.png`` + +Si configuras ``App.imageBaseUrl`` como ``https://micdn.ejemplo.com/``: + +* ``$this->Helper->assetUrl('TestPlugin.logo.png')`` se resuelve a ``https://micdn.ejemplo.com/logo.png``. + +Configuración de la Base de Datos +--------------------------------- + +Consulta la :ref:`Configuración de la Base de Datos ` para obtener información sobre cómo configurar las conexiones a tu base de datos. + +Configuración de Caché +----------------------- + +Consulta la :ref:`Configuración de Caché ` para obtener información sobre cómo configurar la caché en CakePHP. + +Configuración de Manejo de Errores y Excepciones +------------------------------------------------ + +Consulta la :ref:`Configuración de Errores y Excepciones ` para obtener información sobre cómo configurar los manejadores de errores y excepciones. + +Configuración de Registro (Logs) +-------------------------------- + +Consulta la :ref:`Configuración de Registro ` para obtener información sobre cómo configurar el registro (logs) en CakePHP. + +Configuración de Correo Electrónico +------------------------------------ + +Consulta la :ref:`Configuración de Correo Electrónico ` para obtener información sobre cómo configurar preajustes de correo electrónico en CakePHP. + +Configuración de Sesión +------------------------ + +Consulta la :ref:`Configuración de Sesión ` para obtener información sobre cómo configurar el manejo de sesiones en CakePHP. + +Configuración de Enrutamiento +------------------------------ + +Consulta la :ref:`Configuración de Rutas ` para obtener más información sobre cómo configurar el enrutamiento y crear rutas para tu aplicación. + +.. _additional-class-paths: + +Rutas de Clases Adicionales +============================ + +Las rutas de clases adicionales se configuran a través de los cargadores automáticos que utiliza tu aplicación. Cuando utilizas `composer` para generar tu cargador automático, puedes hacer lo siguiente para proporcionar rutas alternativas para los controladores en tu aplicación:: + + "autoload": { + "psr-4": { + "App\\Controller\\": "/ruta/a/directorio/con/carpetas/de/controladores/", + "App\\": "src/" + } + } + +El ejemplo anterior establecería rutas para los espacios de nombres `App` y `App\Controller`. Se buscará la primera clave y, si esa ruta no contiene la clase/archivo, se buscará la segunda clave. También puedes asignar un solo espacio de nombres a múltiples directorios de la siguiente manera:: + + "autoload": { + "psr-4": { + "App\\": ["src/", "/ruta/a/directorio/"] + } + } + +Rutas de Plugins, Plantillas de Vista y Localizaciones +----------------------------------------------------------- + +Dado que los plugins, las plantillas de vista y las localizaciones no son clases, no pueden tener un cargador automático configurado. CakePHP proporciona tres variables de configuración para establecer rutas adicionales para estos recursos. En tu **config/app.php**, puedes configurar estas variables:: + + return [ + // Otras configuraciones + 'App' => [ + 'paths' => [ + 'plugins' => [ + ROOT . DS . 'plugins' . DS, + '/ruta/a/otros/plugins/', + ], + 'templates' => [ + ROOT . DS . 'templates' . DS, + ROOT . DS . 'templates2' . DS, + ], + 'locales' => [ + ROOT . DS . 'resources' . DS . 'locales' . DS, + ], + ], + ], + ] + +Las rutas deben terminar con un separador de directorio, o no funcionarán correctamente. + +Configuración de Inflexión +============================== + +Consulta la documentación de :ref:`inflection-configuration` para obtener más información. + +Clase Configure +=================== + +.. php:namespace:: Cake\Core + +.. php:class:: Configure + +La clase Configure de CakePHP se puede utilizar para almacenar y recuperar valores específicos de la aplicación o en +tiempo de ejecución. Sin embargo, debes tener cuidado, ya que esta clase te permite almacenar cualquier cosa y usarla +en cualquier parte de tu código, lo que puede ser una tentación para romper el patrón MVC para el que CakePHP fue diseñado. +El principal objetivo de la clase Configure es mantener variables centralizadas que puedan compartirse entre varios objetos. +Recuerda intentar seguir el principio "convención sobre configuración" para no terminar rompiendo la estructura MVC que +CakePHP proporciona. + +Escritura de Datos de Configuración +----------------------------------- + +.. php:staticmethod:: write($clave, $valor) + +Utiliza ``write()`` para almacenar datos en la configuración de la aplicación:: + + Configure::write('Company.name', 'Pizza, Inc.'); + Configure::write('Company.slogan', 'Pizza for your body and soul'); + .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + La :term:`notación de punto` utilizada en el parámetro ``$clave`` se puede utilizar para organizar tus configuraciones en grupos lógicos. + +El ejemplo anterior también se podría escribir en una sola llamada:: + + Configure::write('Company', [ + 'name' => 'Pizza, Inc.', + 'slogan' => 'Pizza for your body and soul' + ]); + +Puedes utilizar ``Configure::write('debug', $boolean)`` para alternar entre los modos de depuración y producción sobre la marcha. + +.. note:: + + Cualquier cambio en la configuración realizado mediante ``Configure::write()`` se mantiene en memoria y no persistirá entre solicitudes. + +Lectura de Datos de Configuración +--------------------------------- + +.. php:staticmethod:: read($clave = null, $predeterminado = null) + +Se utiliza para leer datos de configuración de la aplicación. Si se proporciona una clave, se devolverán los datos. Usando nuestros ejemplos anteriores de ``write()``, podemos leer esos datos de la siguiente manera:: + + # Devuelve 'Pizza, Inc.' + Configure::read('Company.name'); + + # Devuelve 'Pizza for your body and soul' + Configure::read('Company.slogan'); + + Configure::read('Company'); + # Devuelve: + ['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul']; + + # Devuelve 'fallback' ya que Company.nope no está definido. + Configure::read('Company.nope', 'fallback'); + +Si se deja el parámetro ``$clave`` como nulo, se devolverán todos los valores en Configure. + +.. php:staticmethod:: readOrFail($clave) + +Lee datos de configuración igual que :meth:`Cake\\Core\\Configure::read`, pero espera encontrar un par clave/valor. Si el par solicitado no existe, se lanzará una :class:`RuntimeException`. + + Configure::readOrFail('Company.name'); # Devuelve: 'Pizza, Inc.' + Configure::readOrFail('Company.geolocation'); # Lanzará una excepción + + Configure::readOrFail('Company'); + + # Devuelve: + ['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul']; + +Comprobación para ver si los Datos de Configuración están Definidos +-------------------------------------------------------------------- + +.. php:staticmethod:: check($clave) + +Se utiliza para comprobar si una clave/ruta existe y tiene un valor distinto de nulo:: + + $existe = Configure::check('Company.name'); + +Eliminación de Datos de Configuración +------------------------------------- + +.. php:staticmethod:: delete($clave) + +Se utiliza para eliminar información de la configuración de la aplicación:: + + Configure::delete('Company.name'); + +Lectura y Eliminación de Datos de Configuración +------------------------------------------------ + +.. php:staticmethod:: consume($clave) + +Lee y elimina una clave de Configure. Esto es útil cuando deseas combinar la lectura y eliminación de valores en una sola operación. + +.. php:staticmethod:: consumeOrFail($clave) + +Consume datos de configuración de la misma manera que :meth:`Cake\\Core\\Configure::consume`, pero espera encontrar un par clave/valor. Si el par solicitado no existe, se lanzará una :class:`RuntimeException`. + + Configure::consumeOrFail('Company.name'); # Devuelve: 'Pizza, Inc.' + Configure::consumeOrFail('Company.geolocation'); # Lanzará una excepción + + Configure::consumeOrFail('Company'); + + # Devuelve: + ['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'] + +Lectura y Escritura de Archivos de Configuración +------------------------------------------------ + +.. php:staticmethod:: setConfig($nombre, $motor) + +CakePHP viene con dos motores de archivos de configuración integrados. +:php:class:`Cake\\Core\\Configure\\Engine\\PhpConfig` es capaz de leer archivos +de configuración PHP, en el mismo formato que Configure ha leído históricamente. +:php:class:`Cake\\Core\\Configure\\Engine\\IniConfig` es capaz de leer archivos +de configuración ini. Consulta la `documentación de PHP `_ para +obtener más información sobre los detalles de los archivos ini. Para utilizar un +motor de configuración central, debes adjuntarlo a Configure utilizando :php::meth:`Configure::config()`:: + + use Cake\Core\Configure\Engine\PhpConfig; + + # Leer archivos de configuración desde config + Configure::config('default', new PhpConfig()); + + # Leer archivos de configuración desde otra ruta. + Configure::config('default', new PhpConfig('/ruta/a/tus/archivos/de/configuración/')); + +Puedes tener varios motores adjuntos a Configure, cada uno leyendo diferentes tipos o fuentes de archivos de configuración. Puedes interactuar con los motores adjuntos usando los métodos definidos en Configure. Para verificar qué alias de motor están adjuntos, puedes usar :meth:`Configure::configured()`:: + + # Obtén el array de alias para los motores adjuntos. + Configure::configured(); + + # Comprueba si un motor específico está adjunto + Configure::configured('default'); + +.. php:staticmethod:: drop($nombre) + +También puedes eliminar motores adjuntos. ``Configure::drop('default')`` eliminaría el alias del motor predeterminado. Cualquier intento futuro de cargar archivos de configuración con ese motor fallaría:: + + Configure::drop('default'); + +Carga de Archivos de Configuración +---------------------------------- + +.. php:staticmethod:: load($clave, $config = 'default', $merge = true) + +Una vez que hayas adjuntado un motor de configuración a Configure, puedes cargar archivos de configuración:: + + # Cargar my_file.php usando el objeto de motor 'default'. + Configure::load('my_file', 'default'); + +Los archivos de configuración cargados fusionan sus datos con la configuración en tiempo de ejecución existente en Configure. Esto te permite sobrescribir y agregar nuevos valores a la configuración en tiempo de ejecución existente. Al establecer ``$merge`` en ``true``, los valores nunca sobrescribirán la configuración existente. + +.. warning:: + Al fusionar archivos de configuración con `$merge = true`, la notación de puntos en las claves no se expande:: + + # config1.php + 'Clave1' => [ + 'Clave2' => [ + 'Clave3' => ['ClaveAnidada1' => 'Valor'], + ], + ], + + # config2.php + 'Clave1.Clave2' => [ + 'Clave3' => ['ClaveAnidada2' => 'Valor2'], + ] + + Configure::load('config1', 'default'); + Configure::load('config2', 'default', true); + + # Ahora Clave1.Clave2.Clave3 tiene el valor ['ClaveAnidada2' => 'Valor2'] + # en lugar de ['ClaveAnidada1' => 'Valor', 'ClaveAnidada2' => 'Valor2'] + +Creación o Modificación de Archivos de Configuración +----------------------------------------------------- + +.. php:staticmethod:: dump($clave, $config = 'default', $claves = []) + +Vuelca todos o algunos de los datos en Configure en un archivo o sistema de almacenamiento compatible con un motor de configuración. El formato de serialización lo decide el motor de configuración adjunto como $config. Por ejemplo, si el motor 'default' es una :class:`Cake\\Core\\Configure\\Engine\\PhpConfig`, el archivo generado será un archivo de configuración PHP que se puede cargar mediante el :class:`Cake\\Core\\Configure\\Engine\\PhpConfig` + +Dado que el motor 'default' es una instancia de PhpConfig. Guarda todos los datos en Configure en el archivo `mi_configuracion.php`:: + + Configure::dump('mi_configuracion', 'default'); + +Guarda solo la configuración de manejo de errores:: + + Configure::dump('error', 'default', ['Error', 'Exception']); + +``Configure::dump()`` se puede utilizar para modificar o sobrescribir archivos de configuración que se pueden leer con :meth:`Configure::load()` + +Almacenamiento de Configuración en Tiempo de Ejecución +------------------------------------------------------ + +.. php:staticmethod:: store($nombre, $configuracionCache = 'default', $datos = null) + +También puedes almacenar valores de configuración en tiempo de ejecución para usarlos en solicitudes futuras. Dado que configure solo recuerda valores para la solicitud actual, deberás almacenar cualquier información de configuración modificada si deseas usarla en solicitudes posteriores:: + + # Almacena la configuración actual en la clave 'usuario_1234' en la caché 'default'. + Configure::store('usuario_1234', 'default'); + +Los datos de configuración almacenados persisten en la configuración de caché con el nombre especificado. Consulta la documentación sobre :doc:`/core-libraries/caching` para obtener más información sobre el almacenamiento en caché. + +Restauración de Configuración en Tiempo de Ejecución +----------------------------------------------------- + +.. php:staticmethod:: restore($nombre, $configuracionCache = 'default') + +Una vez que hayas almacenado la configuración en tiempo de ejecución, probablemente necesitarás restaurarla para poder acceder a ella nuevamente. ``Configure::restore()`` hace precisamente eso:: + + # Restaura la configuración en tiempo de ejecución desde la caché. + Configure::restore('usuario_1234', 'default'); + +Al restaurar información de configuración, es importante restaurarla con la misma clave y configuración de caché que se usó para almacenarla. La información restaurada se fusiona con la configuración en tiempo de ejecución existente. + +Motores de Configuración +------------------------ + +CakePHP proporciona la capacidad de cargar archivos de configuración desde varias fuentes diferentes y cuenta con un sistema plugable para `crear tus propios motores de configuración +`__. Los motores de configuración integrados son: + +* `JsonConfig `__ +* `IniConfig `__ +* `PhpConfig `__ + +Por defecto, tu aplicación utilizará ``PhpConfig``. + +Desactivación de Tablas Genéricas +================================== + +Aunque utilizar clases de tabla genéricas, también llamadas auto-tablas, al crear rápidamente nuevas aplicaciones y hornear +modelos es útil, las clases de tabla genéricas pueden dificultar la depuración en algunos escenarios. + +Puedes verificar si se emitió alguna consulta desde una clase de tabla genérica a través del panel SQL de DebugKit. Si +aún tienes problemas para diagnosticar un problema que podría ser causado por las auto-tablas, puedes lanzar una excepción +cuando CakePHP utiliza implícitamente una ``Cake\ORM\Table`` genérica en lugar de tu clase concreta de la siguiente manera:: + + # En tu bootstrap.php + use Cake\Event\EventManager; + use Cake\Http\Exception\InternalErrorException; - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + $seEjecutaCakeBakeShell = (PHP_SAPI === 'cli' && isset($argv[1]) && $argv[1] === 'bake'); + if (!$seEjecutaCakeBakeShell) { + EventManager::instance()->on('Model.initialize', function($event) { + $subject = $event->getSubject(); + if (get_class($subject) === 'Cake\ORM\Table') { + $mensaje = sprintf( + 'Clase de tabla faltante o alias incorrecto al registrar la clase de tabla para la tabla de base de datos %s.', + $subject->getTable()); + throw new InternalErrorException($mensaje); + } + }); + } .. meta:: - :title lang=es: Configuration + :title lang=es: Configuración :keywords lang=es: finished configuration,legacy database,database configuration,value pairs,default connection,optional configuration,example database,php class,configuration database,default database,configuration steps,index database,configuration details,class database,host localhost,inflections,key value,database connection,piece of cake,basic web diff --git a/es/development/dispatch-filters.rst b/es/development/dispatch-filters.rst deleted file mode 100644 index 06f9e8df0c..0000000000 --- a/es/development/dispatch-filters.rst +++ /dev/null @@ -1,16 +0,0 @@ -Dispatcher Filters -################## - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Dispatcher Filters - :description lang=es: Dispatcher filters are a middleware layer for CakePHP allowing to alter the request or response before it is sent - :keywords lang=es: middleware, filters, dispatcher, request, response, rack, application stack, events, beforeDispatch, afterDispatch, router diff --git a/es/development/errors.rst b/es/development/errors.rst index e0e93e9c99..4190d72e1b 100644 --- a/es/development/errors.rst +++ b/es/development/errors.rst @@ -1,15 +1,641 @@ -Error & Exception Handling -########################## +Manejo de Errores y Excepciones +################################ + +Las aplicaciones de CakePHP vienen con la configuración predeterminada de manejo de errores y excepciones. +Los errores de PHP son capturados y mostrados o registrados. Las excepciones no capturadas se representan +automáticamente en páginas de error. + +.. _error-configuration: + +Configuración +============= + +La configuración de errores se realiza en el archivo **config/app.php** de tu aplicación. Por defecto, CakePHP +utiliza ``Cake\Error\ErrorTrap`` y ``Cake\Error\ExceptionTrap`` para manejar tanto errores de PHP como excepciones, +respectivamente. La configuración de errores te permite personalizar el manejo de errores para tu aplicación. +Las siguientes opciones son compatibles: + +* ``errorLevel`` - int - El nivel de errores que te interesa capturar. Usa las constantes de error de PHP integradas + y las máscaras de bits para seleccionar el nivel de error que te interesa. Consulta :ref:`deprecation-warnings` + para deshabilitar advertencias de obsolescencia. +* ``trace`` - bool - Incluir trazas para errores en los archivos de registro. Las trazas se incluirán en el + registro después de cada error. Esto es útil para encontrar dónde/cuándo se están generando los errores. +* ``exceptionRenderer`` - string - La clase responsable de representar excepciones no capturadas. Si eliges + una clase personalizada, debes colocar el archivo para esa clase en **src/Error**. Esta clase debe implementar + un método ``render()``. +* ``log`` - bool - Cuando es ``true``, las excepciones y sus trazas se registrarán en :php:class:`Cake\\Log\\Log`. +* ``skipLog`` - array - Un array de nombres de clases de excepción que no deben ser registrados. Esto es útil para + eliminar mensajes de registro comunes pero poco interesantes, como NotFoundExceptions. +* ``extraFatalErrorMemory`` - int - Establece el número de megabytes para aumentar el límite de memoria cuando + se encuentra un error fatal. Esto permite espacio para completar el registro o el manejo de errores. +* ``logger`` (antes de la versión 4.4.0, usa ``errorLogger``) - ``Cake\Error\ErrorLoggerInterface`` - La clase + responsable de registrar errores y excepciones no controladas. Por defecto, es ``Cake\Error\ErrorLogger``. +* ``errorRenderer`` - ``Cake\Error\ErrorRendererInterface`` - La clase responsable de representar errores. Se + elige automáticamente en función del SAPI de PHP. +* ``ignoredDeprecationPaths`` - array - Una lista de rutas compatibles con la sintaxis Glob que deben ignorar errores de + obsolescencia. Añadido en la versión 4.2.0 + +Por defecto, los errores de PHP se muestran cuando ``debug`` es ``true``, y se registran cuando debug es ``false``. +El manejador de errores fatal se llamará independientemente del nivel de ``debug`` o la configuración de ``errorLevel``, +pero el resultado será diferente según el nivel de ``debug``. El comportamiento predeterminado para errores fatales es +mostrar una página de error interno del servidor (``debug`` deshabilitado) o una página con el mensaje, archivo y línea (``debug`` habilitado). .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + Si utilizas un manejador de errores personalizado, las opciones compatibles dependerán de tu manejador. + +.. _deprecation-warnings: + +Advertencias de Obsolescencia +============================== + +CakePHP utiliza advertencias de obsolescencia para indicar cuándo se ha marcado como obsoleta alguna característica. También +recomendamos este sistema para su uso en tus plugins y código de aplicación cuando sea útil. Puedes activar advertencias de +obsolescencia con ``deprecationWarning()``:: + + deprecationWarning('5.0', 'El método example() está obsoleto. Usa getExample() en su lugar.'); + +Al actualizar CakePHP o plugins, es posible que te encuentres con nuevas advertencias de obsolescencia. Puedes desactivar +temporalmente las advertencias de obsolescencia de varias formas: + +#. Usar la configuración ``Error.errorLevel`` con ``E_ALL ^ E_USER_DEPRECATED`` para ignorar *todas* las advertencias de + obsolescencia. +#. Usar la opción de configuración ``Error.ignoredDeprecationPaths`` para ignorar advertencias con expresiones compatibles + con la sintaxis Glob. Por ejemplo:: + + 'Error' => [ + 'ignoredDeprecationPaths' => [ + 'vendors/company/contacts/*', + 'src/Models/*', + ], + ], + + Ignoraría todas las advertencias de obsolescencia de tu directorio ``Models`` y el plugin ``Contacts`` en tu aplicación. + +Cambiar el Manejo de Excepciones +================================= + +El manejo de excepciones en CakePHP ofrece varias formas de personalizar cómo se manejan las excepciones. Cada enfoque te brinda +diferentes niveles de control sobre el proceso de manejo de excepciones. + +#. *Escucha eventos* Esto te permite recibir notificaciones a través de eventos de CakePHP cuando se han manejado errores y excepciones. +#. *Plantillas personalizadas* Esto te permite cambiar las plantillas de vista renderizadas como lo harías con cualquier otra + plantilla en tu aplicación. +#. *Controlador personalizado* Esto te permite controlar cómo se renderizan las páginas de excepción. +#. *ExceptionRenderer personalizado* Esto te permite controlar cómo se realizan las páginas de excepción y el registro. +#. *Crea y registra tus propios manejadores* Esto te brinda control total sobre cómo se manejan, registran y representan los errores y + excepciones. Utiliza ``Cake\Error\ExceptionTrap`` y ``Cake\Error\ErrorTrap`` como referencia cuando implementes tus manejadores. + +Escuchar Eventos +================ + +Los manejadores ``ErrorTrap`` y ``ExceptionTrap`` activarán eventos de CakePHP cuando manejan errores. Puedes escuchar el evento ``Error.beforeRender`` para ser notificado de los errores de PHP. El evento ``Exception.beforeRender`` se desencadena cuando se maneja una excepción:: + + $errorTrap = new ErrorTrap(Configure::read('Error')); + $errorTrap->getEventManager()->on( + 'Error.beforeRender', + function (EventInterface $event, PhpError $error) { + // haz lo que necesites + } + ); + +Dentro de un manejador ``Error.beforeRender``, tienes algunas opciones: + +* Detener el evento para evitar la representación. +* Devolver una cadena para omitir la representación y usar la cadena proporcionada en su lugar. + +Dentro de un manejador ``Exception.beforeRender``, también tienes algunas opciones: + +* Detener el evento para evitar la representación. +* Establecer el atributo de datos ``exception`` con ``setData('exception', $err)`` + para reemplazar la excepción que se está representando. +* Devolver una respuesta desde el evento para omitir la representación y usar + la respuesta proporcionada en su lugar. + +.. _error-views: + +Plantillas Personalizadas +========================== + +El atrapador de excepciones predeterminado representa todas las excepciones no capturadas que tu aplicación genera con la ayuda de ``Cake\Error\WebExceptionRenderer`` y tu ``ErrorController`` de la aplicación. + +Las vistas de página de error están ubicadas en **templates/Error/**. Todos los errores 4xx usan la plantilla **error400.php**, y los errores 5xx usan la plantilla **error500.php**. Tus plantillas de error tendrán las siguientes variables disponibles: + +* ``message`` El mensaje de la excepción. +* ``code`` El código de la excepción. +* ``url`` La URL de la solicitud. +* ``error`` El objeto de la excepción. + +En modo de depuración, si tu error se extiende de ``Cake\Core\Exception\CakeException``, los datos devueltos por ``getAttributes()`` se expondrán también como variables de vista. + +.. note:: + Necesitarás establecer ``debug`` en falso para ver tus plantillas **error404** y **error500**. En modo de depuración, verás la página de error de desarrollo de CakePHP. + +Diseño Personalizado para la Página de Error +-------------------------------------------- + +Por defecto, las plantillas de error usan **templates/layout/error.php** para un diseño. Puedes usar la propiedad ``layout`` para elegir un diseño diferente:: + + // dentro de templates/Error/error400.php + $this->layout = 'mi_error'; + +Lo anterior usaría **templates/layout/mi_error.php** como el diseño para tus páginas de error. + +Muchas excepciones generadas por CakePHP representarán plantillas de vista específicas en modo de depuración. Con la depuración desactivada, todas las excepciones generadas por CakePHP usarán **error400.php** o **error500.php** según su código de estado. + +Controlador Personalizado +========================= + +La clase ``App\Controller\ErrorController`` se utiliza para la representación de excepciones de CakePHP para renderizar la vista de la página de error y recibe todos los eventos estándar del ciclo de vida de la solicitud. Al modificar esta clase, puedes controlar qué componentes se utilizan y qué plantillas se representan. + +Si tu aplicación utiliza :ref:`rutas con prefijo `, puedes crear controladores de error personalizados para cada prefijo de enrutamiento. Por ejemplo, si tienes un prefijo ``Admin``, podrías crear la siguiente clase:: + + namespace App\Controller\Admin; + + use App\Controller\AppController; + use Cake\Event\EventInterface; + + class ErrorController extends AppController + { + /** + * Callback beforeRender. + * + * @param \Cake\Event\EventInterface $event Evento. + * @return void + */ + public function beforeRender(EventInterface $event) + { + $this->viewBuilder()->setTemplatePath('Error'); + } + } + +Este controlador solo se utilizaría cuando se encuentra un error en un controlador con prefijo y te permite definir lógica/plantillas específicas del prefijo según sea necesario. + +.. _custom-exceptionrenderer: + +ExceptionRenderer Personalizado +================================ + +Si deseas controlar todo el proceso de representación y registro de excepciones, puedes utilizar la opción ``Error.exceptionRenderer`` en **config/app.php** para elegir una clase que representará las páginas de excepciones. Cambiar el ExceptionRenderer es útil cuando quieres cambiar la lógica utilizada para crear un controlador de error, elegir la plantilla o controlar el proceso general de representación. + +Tu clase personalizada de ExceptionRenderer debe colocarse en **src/Error**. Supongamos que nuestra aplicación usa ``App\Exception\MissingWidgetException`` para indicar un widget faltante. Podríamos crear un ExceptionRenderer que represente páginas de error específicas cuando se maneja este error:: + + // En src/Error/AppExceptionRenderer.php + namespace App\Error; + + use Cake\Error\WebExceptionRenderer; + + class AppExceptionRenderer extends WebExceptionRenderer + { + public function missingWidget($error) + { + $response = $this->controller->getResponse(); + + return $response->withStringBody('Oops, ese widget está perdido.'); + } + } + + // En config/app.php + 'Error' => [ + 'exceptionRenderer' => 'App\Error\AppExceptionRenderer', + // ... + ], + // ... + +Lo anterior manejaría nuestro ``MissingWidgetException``, +y nos permitiría proporcionar lógica de visualización/manejo personalizado para esas excepciones de aplicación. + +Los métodos de representación de excepciones reciben la excepción manejada como argumento y deben devolver un objeto ``Response``. También puedes implementar métodos para agregar lógica adicional al manejar errores de CakePHP:: + + // En src/Error/AppExceptionRenderer.php + namespace App\Error; + + use Cake\Error\WebExceptionRenderer; + + class AppExceptionRenderer extends WebExceptionRenderer + { + public function notFound($error) + { + // Haz algo con objetos NotFoundException. + } + } + +Cambiar la Clase ErrorController +---------------------------------- + +El ExceptionRenderer dicta qué controlador se utiliza para la representación de excepciones. Si quieres cambiar qué controlador se utiliza para representar excepciones, puedes anular el método ``_getController()`` en tu ExceptionRenderer:: + + // en src/Error/AppExceptionRenderer + namespace App\Error; + + use App\Controller\SuperCustomErrorController; + use Cake\Controller\Controller; + use Cake\Error\WebExceptionRenderer; + + class AppExceptionRenderer extends WebExceptionRenderer + { + protected function _getController(): Controller + { + return new SuperCustomErrorController(); + } + } + + // en config/app.php + 'Error' => [ + 'exceptionRenderer' => 'App\Error\AppExceptionRenderer', + // ... + ], + + + // ... + +.. index:: excepciones de aplicación + +Crear tus Propias Excepciones de Aplicación +============================================ + +Puedes crear tus propias excepciones de aplicación utilizando cualquiera de las `excepciones SPL incorporadas `_, ``Exception`` +en sí, o :php:exc:`Cake\\Core\\Exception\\Exception`. +Si tu aplicación contiene la siguiente excepción:: + + use Cake\Core\Exception\CakeException; + + class MissingWidgetException extends CakeException + { + } + +Podrías proporcionar errores de desarrollo detallados, creando +**templates/Error/missing_widget.php**. Cuando estás en modo de producción, el error anterior se trataría como un error 500 y usaría la plantilla **error500**. + +Las excepciones que son subclases de ``Cake\Http\Exception\HttpException``, usarán su código de error como código de estado HTTP si el código de error está entre ``400`` y ``506``. + +El constructor para :php:exc:`Cake\\Core\\Exception\\CakeException` te permite pasar datos adicionales. Estos datos adicionales se interpolan en el ``_messageTemplate``. Esto te permite crear excepciones ricas en datos que proporcionen más contexto sobre tus errores:: + + use Cake\Core\Exception\CakeException; + + class MissingWidgetException extends Exception + { + // Los datos del contexto se interpolan en esta cadena de formato. + protected $_messageTemplate = 'Parece que falta %s.'; + + // También puedes establecer un código de excepción predeterminado. + protected $_defaultCode = 404; + } + + throw new MissingWidgetException(['widget' => 'Puntiagudo']); + +Cuando se representa, tu plantilla de vista tendría una variable ``$widget`` establecida. Si lanzas la excepción como una cadena o usas su método ``getMessage()``, obtendrás ``Parece que falta Puntiagudo.``. + +.. note:: + + Antes de CakePHP 4.2.0, usa la clase ``Cake\Core\Exception\Exception`` en lugar de ``Cake\Core\Exception\CakeException`` + +Registro de Excepciones +------------------------ + +Usando el manejo de excepciones incorporado, puedes registrar todas las excepciones que son tratadas por ErrorTrap configurando la opción ``log`` en ``true`` en tu **config/app.php**. Al habilitar esto, se registrarán todas las excepciones en :php:class:`Cake\\Log\\Log` y en los registradores configurados. + +.. note:: + + Si estás utilizando un manejador de excepciones personalizado, esta configuración no tendrá + ningún efecto, a menos que la referencies dentro de tu implementación. + +.. php:namespace:: Cake\Http\Exception + +.. _built-in-exceptions: + +Excepciones Incorporadas para CakePHP +====================================== + +Excepciones HTTP +--------------- + +Hay varias excepciones incorporadas en CakePHP, además de las excepciones internas del framework, hay varias +excepciones para métodos HTTP. + +.. php:exception:: BadRequestException + :nocontentsentry: + + Usado para el error 400 Bad Request. + +.. php:exception:: UnauthorizedException + :nocontentsentry: + + Usado para el error 401 Unauthorized. + +.. php:exception:: ForbiddenException + :nocontentsentry: + + Usado para el error 403 Forbidden. + +.. php:exception:: InvalidCsrfTokenException + :nocontentsentry: + + Usado para el error 403 causado por un token CSRF inválido. + +.. php:exception:: NotFoundException + :nocontentsentry: + + Usado para el error 404 Not found. + +.. php:exception:: MethodNotAllowedException + :nocontentsentry: + + Usado para el error 405 Method Not Allowed. + +.. php:exception:: NotAcceptableException + :nocontentsentry: + + Usado para el error 406 Not Acceptable. + +.. php:exception:: ConflictException + :nocontentsentry: + + Usado para el error 409 Conflict. + +.. php:exception:: GoneException + :nocontentsentry: + + Usado para el error 410 Gone. + +Para más detalles sobre los códigos de estado 4xx del protocolo HTTP, consulta :rfc:`2616#section-10.4`. + +.. php:exception:: InternalErrorException + :nocontentsentry: + + Usado para el error 500 Internal Server Error. + +.. php:exception:: NotImplementedException + :nocontentsentry: + + Usado para el error 501 Not Implemented Errors. + +.. php:exception:: ServiceUnavailableException + :nocontentsentry: + + Usado para el error 503 Service Unavailable. + +Para más detalles sobre los códigos de estado 5xx del protocolo HTTP, consulta :rfc:`2616#section-10.5`. + +Puedes lanzar estas excepciones desde tus controladores para indicar estados de error o errores HTTP. Un ejemplo de uso de las excepciones HTTP podría ser renderizar páginas 404 para los elementos que no se han encontrado:: + + use Cake\Http\Exception\NotFoundException; + + public function ver($id = null) + { + $articulo = $this->Articulos->findById($id)->first(); + if (empty($articulo)) { + throw new NotFoundException(__('Artículo no encontrado')); + } + $this->set('articulo', $articulo); + $this->viewBuilder()->setOption('serialize', [' + +articulo']); + } + +Usar excepciones para errores HTTP te permite mantener tu código limpio y dar respuestas RESTful a aplicaciones de clientes y usuarios. + +Uso de Excepciones HTTP en tus Controladores +-------------------------------------------- + +Puedes lanzar cualquiera de las excepciones relacionadas con HTTP desde las acciones de tu controlador para indicar estados de error. Por ejemplo:: + + use Cake\Network\Exception\NotFoundException; + + public function ver($id = null) + { + $articulo = $this->Articulos->findById($id)->first(); + if (empty($articulo)) { + throw new NotFoundException(__('Artículo no encontrado')); + } + $this->set('articulo', 'articulo'); + $this->viewBuilder()->setOption('serialize', ['articulo']); + } + +Lo anterior causaría que el manejador de excepciones configurado capture y +procese la :php:exc:`NotFoundException`. Por defecto, esto creará una página de error +y registrará la excepción. + +Otras Excepciones Incorporadas +------------------------------ + +Además, CakePHP utiliza las siguientes excepciones: + +.. php:namespace:: Cake\View\Exception + +.. php:exception:: MissingViewException + :nocontentsentry: + + No se pudo encontrar la clase de vista elegida. + +.. php:exception:: MissingTemplateException + :nocontentsentry: + + No se pudo encontrar el archivo de plantilla elegido. + +.. php:exception:: MissingLayoutException + :nocontentsentry: + + No se pudo encontrar el diseño elegido. + +.. php:exception:: MissingHelperException + :nocontentsentry: + + No se pudo encontrar el ayudante elegido. + +.. php:exception:: MissingElementException + :nocontentsentry: + + No se pudo encontrar el archivo de elemento elegido. + +.. php:exception:: MissingCellException + :nocontentsentry: + + No se pudo encontrar la clase de celda elegida. + +.. php:exception:: MissingCellViewException + :nocontentsentry: + + No se pudo encontrar el archivo de vista de celda elegido. + +.. php:namespace:: Cake\Controller\Exception + +.. php:exception:: MissingComponentException + :nocontentsentry: + + No se pudo encontrar el componente configurado. + +.. php:exception:: MissingActionException + :nocontentsentry: + + No se pudo encontrar la acción del controlador solicitada. + +.. php:exception:: PrivateActionException + :nocontentsentry: + + Acceder a acciones con prefijos privados/protegidos/_. + +.. php:namespace:: Cake\Console\Exception + +.. php:exception:: ConsoleException + :nocontentsentry: + + Una clase de biblioteca de consola encontró un error. + +.. php:namespace:: Cake\Database\Exception + +.. php:exception:: MissingConnectionException + :nocontentsentry: + + Falta una conexión de modelo. + +.. php:exception:: MissingDriverException + :nocontentsentry: + + No se pudo encontrar un controlador de base de datos. + +.. php:exception:: MissingExtensionException + :nocontentsentry: + + Falta una extensión de PHP para el controlador de base de datos. + +.. php:namespace:: Cake\ORM\Exception + +.. php:exception:: MissingTableException + :nocontentsentry: + + No se pudo encontrar la tabla de un modelo. + +.. php:exception:: MissingEntityException + :nocontentsentry: + + No se pudo encontrar la entidad de un modelo. + +.. php:exception:: MissingBehaviorException + :nocontentsentry: + + No se pudo encontrar el comportamiento de un modelo. + +.. php:exception:: PersistenceFailedException + :nocontentsentry: + + No se pudo guardar/eliminar una entidad al usar :php:meth:`Cake\\ORM\\Table::saveOrFail()` o + :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. + +.. php:namespace:: Cake\Datasource\Exception + +.. php:exception:: RecordNotFoundException + :nocontentsentry: + + No se pudo encontrar el registro solicitado. Esto también establecerá las cabeceras de respuesta HTTP en 404. + +.. php:namespace:: Cake\Routing\Exception + +.. php:exception:: MissingControllerException + :nocontentsentry: + + No se pudo encontrar el controlador solicitado. + +.. php:exception:: MissingRouteException + :nocontentsentry: + + No se pudo hacer coincidir la URL solicitada o no se pudo analizar. + +.. php:namespace:: Cake\Core\Exception + +.. php:exception:: Exception + :nocontentsentry: + + Clase base de excepción en CakePHP. Todas las excepciones de capa de framework lanzadas por + CakePHP extenderán esta clase. + +Estas clases de excepción se extienden de :php:exc:`Exception`. +Al extender Exception, puedes crear tus propios errores de 'framework'. + +.. php:method:: responseHeader($header = null, $value = null) + :nocontentsentry: + + Consulta :php:func:`Cake\\Network\\Request::header()` + +Todas las excepciones Http y Cake extienden la clase Exception, que tiene un método +para agregar encabezados a la respuesta. Por ejemplo, al lanzar un 405 +MethodNotAllowedException, el rfc2616 dice:: + + "La respuesta DEBE incluir un encabezado Allow que contenga una lista de métodos válidos + para el recurso solicitado." + +Manejo Personalizado de Errores de PHP +====================================== + +Por defecto, los errores de PHP se representan en la consola o en la salida HTML, y también se registran. +Si es necesario, puedes cambiar la lógica de manejo de errores de CakePHP con la tuya propia. + +Registro de Errores Personalizado +--------------------------------- + +Los manejadores de errores utilizan instancias de ``Cake\Error\ErrorLoggingInterface`` para crear +mensajes de registro y registrarlos en el lugar apropiado. Puedes reemplazar el +registrador de errores utilizando el valor de configuración ``Error.errorLogger``. Un ejemplo de registrador de errores:: + + namespace App\Error; + + use Cake\Error\ErrorLoggerInterface; + use Cake\Error\PhpError; + use Psr\Http\Message\ServerRequestInterface; + use Throwable; + + /** + * Registra errores y excepciones no manejadas en `Cake\Log\Log` + */ + class ErrorLogger implements ErrorLoggerInterface + { + /** + * @inheritDoc + */ + public function logError( + PhpError $error, + ?ServerRequestInterface $request, + bool $includeTrace = false + ): void { + // Registra errores de PHP + } + + /** + * @inheritDoc + */ + public function logException( + ?ServerRequestInterface $request, + bool $includeTrace = false + ): void { + // Registra excepciones. + } + } + +**Renderizado Personalizado de Errores** + +CakePHP incluye renderizadores de errores tanto para entornos web como de consola. Sin embargo, si deseas reemplazar la lógica que renderiza los errores, puedes crear una clase personalizada:: + + // src/Error/CustomErrorRenderer.php + namespace App\Error; + + use Cake\Error\ErrorRendererInterface; + use Cake\Error\PhpError; + + class CustomErrorRenderer implements ErrorRendererInterface + { + public function write(string $out): void + { + // enviar el error renderizado al flujo de salida apropiado + } + + public function render(PhpError $error, bool $debug): string + { + // Convertir el error en una cadena de salida. + } + } - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +El constructor de tu renderizador recibirá un array con la configuración almacenada en `Error`. Conecta tu renderizador de errores personalizado a CakePHP a través del valor de configuración `Error.errorRenderer`. Al reemplazar el manejo de errores, deberás tener en cuenta tanto los entornos web como los de línea de comandos. .. meta:: - :title lang=es: Error & Exception Handling - :keywords lang=es: stack traces,error constants,error array,default displays,anonymous functions,error handlers,default error,error level,exception handler,php error,error handler,write error,core classes,exception handling,configuration error,application code,callback,custom error,exceptions,bitmasks,fatal error + :title lang=es: Manejo de Errores y Excepciones + :keywords lang=en: stack traces,error constants,error array,default displays,anonymous functions,error handlers,default error,error level,exception handler,php error,error handler,write error,core classes,exception handling,configuration error,application code,callback,custom error,exceptions,bitmasks,fatal error, http status codes diff --git a/es/development/sessions.rst b/es/development/sessions.rst index 671d08ecd0..1167fb8a57 100644 --- a/es/development/sessions.rst +++ b/es/development/sessions.rst @@ -1,15 +1,390 @@ -Sessions -######## +Sesiones +########### -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +CakePHP proporciona una envoltura y una serie de funciones de utilidad sobre la extensión nativa de sesión de PHP. Las sesiones te permiten identificar usuarios únicos a lo largo de las solicitudes y almacenar datos persistentes para usuarios específicos. A diferencia de las cookies, los datos de sesión no están disponibles en el lado del cliente. En CakePHP, se evita el uso de `$_SESSION` y se prefiere el uso de las clases de Sesión. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +.. _session-configuration: - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +Configuración de Sesión +========================= + +La configuración de sesión generalmente se define en **/config/app.php**. Las opciones disponibles son: + +* ``Session.timeout`` - El número de *minutos* antes de que el manejador de sesiones de CakePHP expire la sesión. +* ``Session.defaults`` - Te permite usar las configuraciones de sesión predeterminadas incorporadas como base para tu configuración de sesión. Consulta a continuación para ver las configuraciones predeterminadas. +* ``Session.handler`` - Te permite definir un manejador de sesiones personalizado. Los manejadores de sesiones de base de datos y caché utilizan esto. Consulta a continuación para obtener información adicional sobre los manejadores de sesiones. +* ``Session.ini`` - Te permite establecer configuraciones adicionales de ini de sesión para tu configuración. Esto, combinado con ``Session.handler``, reemplaza las características de manejo de sesiones personalizadas de las versiones anteriores. +* ``Session.cookie`` - El nombre de la cookie que se utilizará. De forma predeterminada, se establece en el valor configurado para ``session.name`` en php.ini. +* ``Session.cookiePath`` - La ruta URL para la cual se establece la cookie de sesión. Se mapea a la configuración ``session.cookie_path`` de php.ini. De forma predeterminada, se establece en la ruta base de la aplicación. + +Las configuraciones predeterminadas de CakePHP establecen ``session.cookie_secure`` en ``true``, cuando tu aplicación +está en un protocolo SSL. Si tu aplicación se sirve tanto desde protocolos SSL como no SSL, podrías tener problemas +con las sesiones que se pierden. Si necesitas acceder a la sesión en dominios SSL y no SSL, deberás deshabilitar esto:: + + Configure::write('Session', [ + 'defaults' => 'php', + 'ini' => [ + 'session.cookie_secure' => false + ] + ]); + +A partir de la versión 4.0 de CakePHP, también se establece el atributo `SameSite `__ en ``Lax`` de forma predeterminada para las cookies de sesión, lo que ayuda a proteger contra ataques CSRF. Puedes cambiar el valor predeterminado configurando la opción ``session.cookie_samesite`` en php.ini:: + + Configure::write('Session', [ + 'defaults' => 'php', + 'ini' => [ + 'session.cookie_samesite' => 'Strict', + ], + ]); + + +La ruta de la cookie de sesión se establece de forma predeterminada en la ruta base de la aplicación. Para cambiar esto, puedes usar el valor de ``session.cookie_path`` en ini. Por ejemplo, si quieres que tu sesión persista en todos los subdominios, puedes hacerlo así:: + + Configure::write('Session', [ + 'defaults' => 'php', + 'ini' => [ + 'session.cookie_path' => '/', + 'session.cookie_domain' => '.tudominio.com', + ], + ]); + +De forma predeterminada, PHP configura la cookie de sesión para que caduque tan pronto como se cierre el navegador, independientemente del valor configurado en ``Session.timeout``. El tiempo de espera de la cookie está controlado por el valor de ``session.cookie_lifetime`` en ini y se puede configurar así:: + + Configure::write('Session', [ + 'defaults' => 'php', + 'ini' => [ + // Invalidar la cookie después de 30 minutos sin visitar + // ninguna página en el sitio. + 'session.cookie_lifetime' => 1800 + ] + ]); + +La diferencia entre ``Session.timeout`` y el valor de ``session.cookie_lifetime`` es que este último depende de que el cliente diga la verdad acerca de la cookie. Si necesitas una comprobación de tiempo de espera más estricta, sin depender de lo que el cliente informa, deberías usar ``Session.timeout``. + +Ten en cuenta que ``Session.timeout`` corresponde al tiempo total de inactividad para un usuario (es decir, el tiempo sin visitar ninguna página donde se utilice la sesión), y no limita el total de minutos que un usuario puede permanecer en el sitio. + +Manejadores de Sesiones Incorporados y Configuración +===================================================== + +CakePHP viene con varias configuraciones de sesión incorporadas. Puedes usar estas configuraciones como base para tu configuración de sesión o crear una solución completamente personalizada. Para usar las configuraciones predeterminadas, simplemente configura la clave 'defaults' con el nombre del predeterminado que deseas utilizar. Luego puedes anular cualquier configuración secundaria declarándola en tu configuración de Sesión:: + + Configure::write('Session', [ + 'defaults' => 'php' + ]); + +Lo anterior usará la configuración de sesión 'php' incorporada. Puedes agregar partes o la totalidad de ella haciendo lo siguiente:: + + Configure::write('Session', [ + 'defaults' => 'php', + 'cookie' => 'mi_app', + 'timeout' => 4320 // 3 días + ]); + +Lo anterior anula el tiempo de espera y el nombre de la cookie para la configuración de sesión 'php'. Las configuraciones incorporadas son: + +* ``php`` - Guarda sesiones con las configuraciones estándar en tu archivo php.ini. +* ``cake`` - Guarda sesiones como archivos dentro de ``tmp/sessions``. Esta es una buena opción cuando estás en hosts que no te permiten escribir fuera de tu propio directorio de inicio. +* ``database`` - Utiliza las sesiones de base de datos incorporadas. Consulta a continuación para obtener más información. +* ``cache`` - Utiliza las sesiones de caché incorporadas. Consulta a continuación para obtener más información. + +Manejadores de Sesiones +--------------------------- + +Los manejadores de sesiones también se pueden definir en el array de configuración de la sesión. Al definir la clave de configuración 'handler.engine', puedes nombrar la clase o proporcionar una instancia del manejador. La clase/objeto debe implementar la interfaz nativa de PHP ``SessionHandlerInterface``. Implementar esta interfaz permitirá que ``Session`` mapee automáticamente los métodos para el manejador. Tanto los manejadores de sesiones de base de datos como de caché utilizan este método para guardar sesiones. Las configuraciones adicionales + + para el manejador deben colocarse dentro del array del manejador. Luego puedes leer esos valores desde dentro de tu manejador:: + + 'Session' => [ + 'handler' => [ + 'engine' => 'DatabaseSession', + 'model' => 'SesionesPersonalizadas', + ], + ] + +Lo anterior muestra cómo podrías configurar el manejador de sesiones de base de datos con un modelo de aplicación. Al utilizar +nombres de clases como tu 'handler.engine', CakePHP esperará encontrar tu clase en el espacio de nombres ``Http\Session``. +Por ejemplo, si tenías una clase ``AppSessionHandler``, el archivo debería estar en **src/Http/Session/AppSessionHandler.php**, +y el nombre de la clase debería ser ``App\Http\Session\AppSessionHandler``. También puedes usar manejadores de sesiones desde +dentro de plugins, estableciendo el motor en ``MyPlugin.PluginSessionHandler``. + +Sesiones de Base de Datos +------------------------------- + +Si necesitas usar una base de datos para almacenar los datos de tu sesión, configúralo de la siguiente manera:: + + 'Session' => [ + 'defaults' => 'database' + ] + +Esta configuración requiere una tabla de base de datos con este esquema:: + + CREATE TABLE `sessions` ( + `id` char(40) CHARACTER SET ascii COLLATE ascii_bin NOT NULL, + `created` datetime DEFAULT CURRENT_TIMESTAMP, -- Opcional + `modified` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, -- Opcional + `data` blob DEFAULT NULL, -- para PostgreSQL, usa bytea en lugar de blob + `expires` int(10) unsigned DEFAULT NULL, + PRIMARY KEY (`id`) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +Puedes encontrar una copia del esquema para la tabla de sesiones en el `esqueleto de la aplicación `_ en **config/schema/sessions.sql**. + +También puedes usar tu propia clase de ``Table`` para manejar el guardado de las sesiones:: + + 'Session' => [ + 'defaults' => 'database', + 'handler' => [ + 'engine' => 'DatabaseSession', + 'model' => 'SesionesPersonalizadas', + ], + ] + +Lo anterior le dirá a Session que use las configuraciones predeterminadas de 'database' y especifica que una tabla llamada ``SesionesPersonalizadas`` será la encargada de guardar la información de la sesión en la base de datos. + +.. _sessions-cache-sessions: + +Sesiones de Caché +------------------ + +La clase Cache se puede utilizar para almacenar sesiones también. Esto te permite almacenar sesiones en una caché como APCu o Memcached. Hay algunas advertencias al usar sesiones en caché, ya que si agotas el espacio de la caché, las sesiones comenzarán a caducar a medida que se eliminan registros. + +Para usar sesiones basadas en caché, puedes configurar tu configuración de Sesión así:: + + Configure::write('Session', [ + 'defaults' => 'cache', + 'handler' => [ + 'config' => 'session', + ], + ]); + +Esto configurará Session para usar la clase ``CacheSession`` como el delegado para guardar las sesiones. Puedes usar la clave 'config' para especificar qué configuración de caché usar. La configuración de caché predeterminada es ``'default'``. + +Bloqueo de Sesiones +-------------------- + +El esqueleto de la aplicación viene preconfigurado con una configuración de sesión como esta:: + + 'Session' => [ + 'defaults' => 'php', + ], + +Esto significa que CakePHP manejará las sesiones según lo que esté configurado en tu ``php.ini``. +En la mayoría de los casos, esta será la configuración predeterminada, por lo que PHP guardará +cualquier sesión recién creada como un archivo en, por ejemplo, ``/var/lib/php/session``. + +Pero esto también significa que cualquier tarea computacionalmente intensiva, como consultar un gran +conjunto de datos combinada con una sesión activa, **bloqueará ese archivo de sesión**, lo que +bloqueará a los usuarios para, por ejemplo, abrir una segunda pestaña de tu aplicación para +hacer algo más mientras tanto. + +Para evitar este comportamiento, tendrás que cambiar la forma en que CakePHP maneja las sesiones +utilizando un manejador de sesiones diferente como :ref:`sessions-cache-sessions` combinado con +el :ref:`Motor Redis ` u otro motor de caché. + +.. tip:: + + Si deseas leer más sobre el Bloqueo de Sesiones, consulta `aquí `_. + +Configuración de Directivas de ini +==================================== + +Las configuraciones predeterminadas incorporadas intentan proporcionar una base común para la configuración de sesiones. +Es posible que necesites ajustar flags de ini específicos también. CakePHP expone la capacidad de personalizar las configuraciones +de ini tanto para las configuraciones predeterminadas como para las personalizadas. La clave ``ini`` en las configuraciones +de sesión te permite especificar valores de configuración individuales. Por ejemplo, puedes usarlo para controlar configuraciones como ``session.gc_divisor``:: + + Configure::write('Session', [ + 'defaults' => 'php', + 'ini' => [ + 'session.cookie_name' => 'MiCookie', + 'session.cookie_lifetime' => 1800, // Válido por 30 minutos + 'session.gc_divisor' => 1000, + 'session.cookie_httponly' => true + ] + ]); + +Creación de un Manejador de Sesiones Personalizado +=================================================== + +Crear un manejador de sesiones personalizado es sencillo en CakePHP. En este ejemplo, crearemos un +manejador de sesiones que almacene sesiones tanto en la Caché (APC) como en la base de datos. Esto +nos brinda lo mejor de ambas opciones: la entrada/salida rápida de APC, sin tener que preocuparnos +por las sesiones que desaparecen cuando la caché se llena. + +Primero necesitamos crear nuestra clase personalizada y ponerla en **src/Http/Session/ComboSession.php**. La clase debería verse algo así:: + + namespace App\Http\Session; + + use Cake\Cache\Cache; + use Cake\Core\Configure; + use Cake\Http\Session\DatabaseSession; + + class ComboSession extends DatabaseSession + { + protected $cacheKey; + + public function __construct() + { + $this->cacheKey = Configure::read('Session.handler.cache'); + parent::__construct(); + } + + // Lee datos de la sesión. + public function read($id): string + { + $result = Cache::read($id, $this->cacheKey); + if ($result) { + return $result; + } + return parent::read($id); + + + } + + // Escribe datos en la sesión. + public function write($id, $data): bool + { + Cache::write($id, $data, $this->cacheKey); + return parent::write($id, $data); + } + + // Destruye una sesión. + public function destroy($id): bool + { + Cache::delete($id, $this->cacheKey); + return parent::destroy($id); + } + + // Elimina sesiones caducadas. + public function gc($expires = null): bool + { + return parent::gc($expires); + } + } + +Nuestra clase extiende el ``DatabaseSession`` incorporado para no tener que duplicar toda su lógica y comportamiento. Envolvemos +cada operación con una operación de :php:class:`Cake\\Cache\\Cache`. Esto nos permite obtener sesiones de la caché rápida y no +tener que preocuparnos por lo que sucede cuando llenamos la caché. En **config/app.php** haz que el bloque de sesión se vea así:: + + 'Session' => [ + 'defaults' => 'database', + 'handler' => [ + 'engine' => 'ComboSession', + 'model' => 'Session', + 'cache' => 'apc', + ], + ], + // Asegúrate de agregar una configuración de caché apc + 'Cache' => [ + 'apc' => ['engine' => 'Apc'] + ] + +Ahora nuestra aplicación comenzará a usar nuestro manejador de sesiones personalizado para leer y escribir datos de sesión. + +.. php:class:: Sesión + +.. _accessing-session-object: + +Acceso al Objeto de Sesión +=========================== + +Puedes acceder a los datos de sesión en cualquier lugar donde tengas acceso a un objeto de solicitud. Esto significa que la sesión es accesible desde: + +* Controladores +* Vistas +* Ayudantes (Helpers) +* Celdas (Cells) +* Componentes + +Un ejemplo básico de uso de sesión en controladores, vistas y celdas sería:: + + $nombre = $this->request->getSession()->read('Usuario.nombre'); + + // Si accedes a la sesión varias veces, + // probablemente querrás una variable local. + $sesion = $this->request->getSession(); + $nombre = $sesion->read('Usuario.nombre'); + +En los ayudantes, usa ``$this->getView()->getRequest()`` para obtener el objeto de solicitud; +en los componentes, usa ``$this->getController()->getRequest()``. + +Lectura y Escritura de Datos de Sesión +======================================= + +.. php:method:: read($clave, $predeterminado = null) + +Puedes leer valores de la sesión utilizando una sintaxis compatible con :php:meth:`Hash::extract()`. Ejemplo:: + + $sesion->read('Config.idioma', 'es'); + +.. php:method:: readOrFail($clave) + +Lo mismo que una envoltura de conveniencia alrededor de un valor de retorno no nulo:: + + $sesion->readOrFail('Config.idioma'); + +Esto es útil cuando sabes que esta clave debe estar configurada y no deseas tener que comprobar su existencia en el código mismo. + +.. php:method:: write($clave, $valor) + +``$clave`` debería ser la ruta separada por puntos a la que deseas escribir ``$valor``:: + + $sesion->write('Config.idioma', 'es'); + +También puedes especificar uno o varios hashes así:: + + $sesion->write([ + 'Config.tema' => 'azul', + 'Config.idioma' => 'es', + ]); + +.. php:method:: delete($clave) + +Cuando necesitas eliminar datos de la sesión, puedes usar ``delete()``:: + + $sesion->delete('Algo.valor'); + +.. php:staticmethod:: consume($clave) + +Cuando necesitas leer y eliminar datos de la sesión, puedes usar ``consume()``:: + + $sesion->consume('Algo.valor'); + +.. php:method:: check($clave) + +Si deseas ver si los datos existen en la sesión, puedes usar ``check()``:: + + if ($sesion->check('Config.idioma')) { + // Config.idioma existe y no es nulo. + } + +Destrucción de la Sesión +========================= + +.. php:method:: destroy() + +Destruir la sesión es útil cuando los usuarios cierran sesión. Para destruir una sesión, usa el método ``destroy()``:: + + $sesion->destroy(); + +Destruir una sesión eliminará todos los datos del lado del servidor en la sesión, pero **no** eliminará la cookie de la sesión. + +Rotación de Identificadores de Sesión +====================================== + +.. php:method:: renew() + +Mientras que el ``Plugin de Autenticación`` renueva automáticamente el ID de sesión cuando los usuarios inician sesión y cierran sesión, es posible que necesites rotar los ID de sesión manualmente. Para hacerlo, usa el método ``renew()``:: + + $sesion->renew(); + +Mensajes Flash +=============== + +Los mensajes flash son pequeños mensajes que se muestran a los usuarios una vez. A menudo se utilizan para presentar mensajes de error o confirmar que las acciones se realizaron con éxito. + +Para establecer y mostrar mensajes flash, debes usar el :doc:`Componente Flash ` y :doc:`Ayudante Flash `. .. meta:: - :title lang=es: Sessions - :keywords lang=es: session defaults,session classes,utility features,session timeout,session ids,persistent data,session key,session cookie,session data,last session,core database,security level,useragent,security reasons,session id,attr,countdown,regeneration,sessions,config + :title lang=es: Sesiones + :keywords lang=en: session defaults,session classes,utility features,session timeout,session ids,persistent data,session key,session cookie,session data,last session,core database,security level,useragent,security reasons,session id,attr,countdown,regeneration,sessions,config diff --git a/es/topics.rst b/es/topics.rst index f95387889a..51e8f8c684 100644 --- a/es/topics.rst +++ b/es/topics.rst @@ -1,14 +1,7 @@ -Using CakePHP -############# +Usando CakePHP +############### -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +Introducción a las partes principales de CakePHP: * :doc:`/installation` * :doc:`/development/configuration` From 92da3a5749a312c2fbe7caea6c07b4ffc03503b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Sat, 14 Oct 2023 13:36:56 +0100 Subject: [PATCH 053/337] Update translations for file es/intro.rst --- es/intro.rst | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/es/intro.rst b/es/intro.rst index b35805aae6..f1aea892ef 100644 --- a/es/intro.rst +++ b/es/intro.rst @@ -34,15 +34,14 @@ relacionadas con el manejo de datos. En el caso de una red social la capa modelo se encargaría de tareas como guardar los datos del usuario, las asociaciones de amigos, almacenar y obtener fotos, buscar sugerencias de amistad, etc. Los objetos modelo serían "Amigo", -"Usuario", "Comentario" o "Foto". Si quisieramos obtener más datos de nuestra +"Usuario", "Comentario" o "Foto". Si quisiéramos obtener más datos de nuestra tabla ``usuarios`` podríamos hacer lo siguiente:: - use Cake\ORM\TableRegistry; + use Cake\ORM\Locator\LocatorAwareTrait; - // Prior to 3.6 use TableRegistry::get('Usuarios') - $usuarios = TableRegistry::getTableLocator()->get('Usuarios'); - $query = $usuarios->find(); - foreach ($query as $row) { + $usuarios = $this->getTableLocator()->get('Usuarios'); + $resultset = $usuarios->find()->all(); + foreach ($resultset as $row) { echo $row->nombreusuario; } @@ -53,10 +52,9 @@ usará clases estándar para tablas y clases de entidad que no hayan sido defini Si queremos crear un nuevo usuario y guardarlo (con validaciones) podríamos hacer algo como:: - use Cake\ORM\TableRegistry; + use Cake\ORM\Locator\LocatorAwareTrait; - // Prior to 3.6 use TableRegistry::get('Usuarios') - $usuarios = TableRegistry::getTableLocator()->get('Usuarios'); + $usuarios = $this->getTableLocator()->get('Usuarios'); $usuario = $usuarios->newEntity(['email' => 'mark@example.com']); $usuarios->save($usuario); @@ -101,7 +99,7 @@ el registro de un usuario sería:: public function add() { - $usuario = $this->Usuarios->newEntity(); + $usuario = $this->Usuarios->newEmptyEntity(); if ($this->request->is('post')) { $usuario = $this->Usuarios->patchEntity($usuario, $this->request->getData()); if ($this->Usuarios->save($usuario, ['validate' => 'registration'])) { @@ -127,7 +125,7 @@ como funciona el ciclo de una petición: .. figure:: /_static/img/typical-cake-request.png :align: center - :alt: Diagrama de flujo mostrando una petición tipica de CakePHP + :alt: Diagrama de flujo mostrando una petición típica de CakePHP El ciclo de petición típico de CakePHP comienza con un usuario solicitando una página o recurso en tu aplicación. A un alto nivel cada petición sigue los @@ -171,4 +169,4 @@ Lecturas complementarias .. meta:: :title lang=es: Empezando - :keywords lang=es: estructura de carpetas,nombres de tablas,petición inicial,tabla de base de datos,estructura orgaizativa,rst,nombres de archivo,convenciones,mvc,web página,sit + :keywords lang=es: estructura de carpetas,nombres de tablas,petición inicial,tabla de base de datos,estructura organizativa,rst,nombres de archivo,convenciones,mvc,web página,sit From 22c13617c65bcd5560bd180d03cbbbb1254d13ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 16 Oct 2023 10:45:18 +0100 Subject: [PATCH 054/337] Update en and es translations for file /intro/conventions.rst --- en/intro/conventions.rst | 8 +- es/intro/conventions.rst | 177 +++++++++++++++++++++++++++++++-------- 2 files changed, 146 insertions(+), 39 deletions(-) diff --git a/en/intro/conventions.rst b/en/intro/conventions.rst index 5aa060569e..a2bf72cee2 100644 --- a/en/intro/conventions.rst +++ b/en/intro/conventions.rst @@ -191,11 +191,13 @@ creating classes and files that you'd need to create anyway. +------------+-----------------------------+-------------------------+------------------------------------------------------+ | Controller | ArticlesController | MenuLinksController | Plural, CamelCased, end in Controller | +------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Templates | Articles/index.php | MenuLinks/index.php | View template files are named after | +| | Articles/add.php | MenuLinks/add.php | the controller functions they | +| | Articles/get_list.php | MenuLinks/get_list.php | display, in an underscored form | ++------------+-----------------------------+-------------------------+------------------------------------------------------+ | Behavior | ArticlesBehavior.php | MenuLinksBehavior.php | | +------------+-----------------------------+-------------------------+------------------------------------------------------+ -| View | ArticlesView.php | MenuLinksView.php | View template files are named after | -| | | | the controller functions they | -| | | | display, in an underscored form | +| View | ArticlesView.php | MenuLinksView.php | | +------------+-----------------------------+-------------------------+------------------------------------------------------+ | Helper | ArticlesHelper.php | MenuLinksHelper.php | | +------------+-----------------------------+-------------------------+------------------------------------------------------+ diff --git a/es/intro/conventions.rst b/es/intro/conventions.rst index e54947bda8..a8e01df51f 100644 --- a/es/intro/conventions.rst +++ b/es/intro/conventions.rst @@ -6,7 +6,7 @@ toma algo de tiempo aprender las convenciones de CakePHP, ahorrarás tiempo a la larga. Siguiendo las convenciones obtendrás funcionalidades gratuitas y te liberarás de la pesadilla de mantener archivos de configuración. Las convenciones también hacen que el desarrollo sea uniforme, permitiendo a -otros desarrolladores intervenir y ayudar facilmente. +otros desarrolladores intervenir y ayudar fácilmente. Convenciones de Controlador =========================== @@ -15,9 +15,9 @@ Los nombres de las clases Controlador son en plurar, en formato ``CamelCase``, y finalizan con ``Controller``. Ejemplos de nombres son: ``UsuariosController`` y ``CategoriasArticulosController``. -Los métodos publicos de los Controladores a menudo se exponen como 'acciones' -accesibles a través de un navegador web. Por ejemplo, ``/users/view`` mapea -al método ``view()`` de ``UsersController`` sin tener que hacer nada en el +Los métodos públicos de los Controladores a menudo se exponen como 'acciones' +accesibles a través de un navegador web. Tienen formato ``camelBacked``. Por ejemplo, ``/users/view-me`` mapea +al método ``viewMe()`` de ``UsersController`` sin tener que hacer nada en el enrutamiento de la aplicación. Los métodos protegidos o privados no son accesibles con el enrutamiento. @@ -52,8 +52,8 @@ consultar :ref:`routes-configuration`. Convenciones de nombre de clase y archivo ========================================= -En general los nombres de los archivos coinciden con los nombres de las clases -y siguen los estándares PSR-0 o PSR-4 para cargarse automáticamente. Los +En general, los nombres de los archivos coinciden con los nombres de las clases +y sigue el estándar PSR-4 para cargarse automáticamente. Los siguientes son ejemplos de nombres de clases y de sus archivos: - La clase Controlador ``LatestArticlesController`` debería estar en un archivo llamado **LatestArticlesController.php** @@ -69,25 +69,13 @@ tu carpeta de tu aplicación. .. _model-and-database-conventions: -Convenciones de Modelo y Base de datos -====================================== - -Los nombres de las clases ``table`` son en plural, ``CamelCase`` y terminan en -``Table``. Algunos ejemplos de convención de nombres son: ``UsersTable``, -``ArticleCategoriesTable`` y ``UserFavoritePagesTable``. +Convenciones de base de datos +============================= Los nombres de las tablas correspondientes a los modelos de CakePHP son en plural -y con '_'. Los nombres de las tablas para los modelos arriba mencionados serían -``users``, ``article_categories`` y ``user_favorite_pages`` respectivamente. - -La convención es utilizar palabras en inglés para los nombres de las tablas y de -las columnas. Si utilizas otro idioma CakePHP puede que no sea capaz de procesar -correctamente las conversiones (de singular a plural y viceversa). Si necesitas -añadir reglas para tu idioma para algunas palabras, puedes utilizar la clase -:php:class:`Cake\\Utility\\Inflector`. Además de definir tus reglas de -conversión personalizadas, esta clase te permite comprobar que CakePHP comprenda -tu sintaxis personalizada para palabras en plural y singular. Mira la documentación -sobre :doc:`/core-libraries/inflector` para más información. +y con con '_'. Por ejemplo ``users``, ``menu_links`` y ``user_favorite_pages`` respectivamente. +Los nombres de tablas formadas por múltiples palabras sólo deben usar el plural en la última +palabra, por ejemplo, ``menu_links``. Los nombres de campos con dos o más palabras se escriben con '_', por ejemplo: ``first_name``. @@ -95,19 +83,34 @@ Las claves foráneas en relaciones ``1-n`` (``hasMany``) y ``1-1`` (``belongsTo/ son reconocidas por defecto mediante el nombre (en singular) de la tabla relacionada seguido de ``_id``. De este modo si ``Users`` tiene varios ``Articles`` (relación ``hasMany``), la tabla ``articles`` se relacionará con la tabla ``users`` a través -de la clave foránea ``user_id``. Para una tabla como ``article_categories`` -cuyo nombre está formado por varias palabras, la clave foránea sería ``article_category_id``. +de la clave foránea ``user_id``. Para una tabla como ``menu_links`` +cuyo nombre está formado por varias palabras, la clave foránea sería ``menu_link_id``. Las tablas de unión, usadas en las relaciones ``n-n`` (``BelongsToMany``) entre -modelos, deberían ser nombradas después de las tablas que unirán y en orden -alfabético (``articles_tags`` en lugar de ``tags_articles``). +modelos, deberían ser nombradas después de las tablas que unirán. Los nombres deberán +estar en plural y en orden alfabético: ``articles_tags`` en lugar de ``tags_articles`` +o ``article_tags``. *El comando ``bake`` no funcionará correctamente si ésta convención +no se sigue.* Si la tabla de unión guarda alguna información que no sean las claves +foráneas, debes crear la clase de la entidad y modelo para esa tabla. Además de utilizar claves auto-incrementales como claves primarias, también puedes utilizar columnas UUID. CakePHP creará un único UUID de 36 caracteres (:php:meth:`Cake\\Utility\\Text::uuid()`) cada vez que guardes un nuevo registro usando el método ``Table::save()`` . -Convenciones de Vistas +Convenciones de modelo +====================== + +Los nombres de las clases para las tablas son en plural, formato ``CamelCase`` +y terminan en ``Table``. ``UsersTable``, ``MenuLinksTable`` y ``UserFavoritePagesTable`` +son ejemplos de nombres de clases que corresponden a las tablas ``users``, ``menu_links`` +y ``user_favorite_pages`` respectivamente. + +Los nombres de las clases para las entidades son en singular, formato ``CamelCase`` y no +tienen sufijo. ``User``, ``MenuLink`` y ``UserFavoritePage`` son ejemplos de nombres de clases +que corresponden a las entidades ``users``, ``menu_links`` y ``user_favorite_pages`` respectivamente. + +Convenciones de vistas ====================== Los archivos de las plantillas de vistas son nombrados según las @@ -116,28 +119,130 @@ de la clase ``ArticlesController`` mostrará la vista **templates/Articles/view_ El patrón base es **templates/Controller/nombre_funcion.php**. +.. note:: + + Por defecto CakePHP usa palabras en inglés para las convenciones de nombres. + Si utilizas otro idioma CakePHP puede que no sea capaz de procesar + correctamente las conversiones (de singular a plural y viceversa). Si necesitas + añadir reglas para tu idioma para algunas palabras, puedes utilizar la clase + :php:class:`Cake\\Utility\\Inflector`. Además de definir tus reglas de + conversión personalizadas, esta clase te permite comprobar que CakePHP comprenda + tu sintaxis personalizada para palabras en plural y singular. Mira la documentación + sobre :doc:`/core-libraries/inflector` para más información. + +Convenciones de plugins +======================= + +Es útil añadir el prefijo "cakephp-" en el nombre del paquete para los plugins de CakePHP. +Esto hace que el nombre esté relacionado semánticamente al "framework" del que depende. + +**No** uses el espacio de nombre de CakePHP (cakephp) como nombre de "vendor", ya que es +un espacio reservado para los plugins que son propiedad de CakePHP. La convención es usar +letras en minúscula y guiones como separadores:: + + // Bad + cakephp/foo-bar + + // Good + your-name/cakephp-foo-bar + +Ver `lista asombrosa de recomendaciones +`__ +par mas detalles. + +Resumen +======= + Nombrando los elementos de tu aplicación empleando las convenciones de CakePHP ganarás funcionalidad sin los fastidios y ataduras de mantenimiento de la configuración. Un último ejemplo que enlaza todas las convenciones: -- Tabla de base de datos: "articles" +- Tabla de base de datos: "articles", "menu_links" - Clase Tabla: ``ArticlesTable``, ubicada en **src/Model/Table/ArticlesTable.php** - Clase Entidad: ``Article``, ubicada en **src/Model/Entity/Article.php** - Clase Controlador: ``ArticlesController``, ubicada en **src/Controller/ArticlesController.php** - Plantilla vista, ubicada en **templates/Articles/index.php** -Usando estas convenciones CakePHP redirige una petición a http://example.com/articles/ -a una llamada a la función ``index()`` de la clase ArticlesController, -donde el modelo ``Article`` está disponible automáticamente (y enlazada, automáticamente -también, a la tabla ``articles`` en la base de datos) y renderiza un -archivo. Ninguna de estas relaciones han sido configuradas de ningún modo salvo -creando clases y archivos que has tenido que crear de todas formas. +Usando estas convenciones, CakePHP sabe que una petición a http://example.com/articles/ +hace una llamada a la función ``index()`` de la clase ``ArticlesController``, +donde el modelo ``Articles`` está disponible automáticamente y enlazada automáticamente +a la tabla ``articles`` en la base de datos . Ninguna de estas relaciones han sido +configuradas de ningún modo salvo creando clases y archivos que has tenido que crear de +todas formas. + ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Ejemplo | articles | menu_links | | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Tabla base | articles | menu_links | Nombres de tablas que se corresponden a modelos | +| de datos | | | son en plural y con guión bajo '_'. | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Archivo | ArticlesController.php | MenuLinksController.php | | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Tabla | ArticlesTable.php | MenuLinksTable.php | Los nombres de clase de las tablas son en plural, | +| | | | formato 'CamelCased' y acaban con el sufijo 'Table' | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Entidad | Article.php | MenuLink.php | Los nombres de clase de las entidades son en | +| | | | singular y 'CamelCased': Article and MenuLink | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Clase | ArticlesController | MenuLinksController | | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Controlador | ArticlesController | MenuLinksController | Plural, CamelCased, acaba en 'Controller' | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Plantillas | Articles/index.php | MenuLinks/index.php | Los archivos de plantillas de vistas son nombrados | +| de | Articles/add.php | MenuLinks/add.php | según las funciones que el controlador muestra, | +| vistas | Articles/edit.php | MenuLinks/add.php | en minúscula y guión bajo | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Comportamiento | ArticlesBehavior.php | MenuLinksBehavior.php | | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Vista | ArticlesView.php | MenuLinksView.php | | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Ayudante | ArticlesHelper.php | MenuLinksHelper.php | | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Componente | ArticlesComponent.php | MenuLinksComponent.php | | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Plugin | Mal: cakephp/articles | cakephp/menu-links | Útil añadir el prefijo "cakephp-" a los plugins | +| | Bien: you/cakephp-articles | you/cakephp-menu-links | en el nombre del paquete. No uses el espacio de | +| | | | nombre (cakephp) como nombre de vendor ya que está | +| | | | para los plugins propiedad de CakePHP. La | +| | | | convención es usar letras minúsculas y guiones | +| | | | como separadores. | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ +| Cada fichero estará localizado en la 'carpeta/espacio de nombre' apropiado dentro de la carpeta de tu aplicación. | ++----------------+-----------------------------+-------------------------+------------------------------------------------------+ + +Database Convention Summary +=========================== ++-----------------+--------------------------------------------------------------+ +| Claves foráneas | Las relaciones son reconocidas por defecto como el | +| | nombre (singular) de la tabla relacionada, | +| hasMany | seguida de ``_id``. | +| belongsTo/ | Para Users 'hasMany' Articles, la tabla ``articles`` | +| hasOne | hará referencia a ``users`` a través de la | +| BelongsToMany | clave foránea ``user_id``. | +| | | ++-----------------+--------------------------------------------------------------+ +| Múltiples | ``menu_links`` cuyo nombre contiene múltiples palabras, | +| palabras | su clave foránea será ``menu_link_id``. | ++-----------------+--------------------------------------------------------------+ +| Auto Increment | Además de utilizar claves auto-incrementales como claves | +| | primarias, también puedes utilizar columnas UUID. | +| | CakePHP creará un único UUID de 36 caracteres | +| | usando (:php:meth:`Cake\\Utility\\Text::uuid()`) | +| | cada vez que guardes un nuevo registro | +| | usando el método ``Table::save()`` . | ++-----------------+--------------------------------------------------------------+ +| Join tables | Deberán ser nombradas según las tablas que unirán o el | +| | comando de 'bake' no funcionará y ordenarse alfabéticamente | +| | (``articles_tags`` en vez de ``tags_articles``). | +| | Si tiene campos adicionales que guardan información, debes | +| | crear un archivo de entidad y modelo para esa tabla. | ++-----------------+--------------------------------------------------------------+ Ahora que te has introducido en los fundamentos de CakePHP. puedes tratar de -realizar el tutorial :doc:`/tutorials-and-examples/bookmarks/intro` para ver +realizar el tutorial :doc:`/tutorials-and-examples/cms/installation` para ver como las cosas encajan juntas. .. meta:: From 478b7044eea7448ded4f6ca9d997822f64856c1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 16 Oct 2023 12:09:50 +0100 Subject: [PATCH 055/337] Update en and es translations for files intro/cakephp-folder-structure.rst, intro/where-to-get-help.rst --- en/intro/cakephp-folder-structure.rst | 2 +- es/intro/cakephp-folder-structure.rst | 70 ++++++++++++--------------- es/intro/where-to-get-help.rst | 4 +- 3 files changed, 34 insertions(+), 42 deletions(-) diff --git a/en/intro/cakephp-folder-structure.rst b/en/intro/cakephp-folder-structure.rst index 93f52b7cf5..9fec23c0be 100644 --- a/en/intro/cakephp-folder-structure.rst +++ b/en/intro/cakephp-folder-structure.rst @@ -55,7 +55,7 @@ View .. note:: - The folder ``Shell`` is not present by default. + The folder ``Command`` is not present by default. You can add it when you need it. .. meta:: diff --git a/es/intro/cakephp-folder-structure.rst b/es/intro/cakephp-folder-structure.rst index f35a1858c5..cb9fb00b47 100644 --- a/es/intro/cakephp-folder-structure.rst +++ b/es/intro/cakephp-folder-structure.rst @@ -1,51 +1,39 @@ -CakePHP Folder Structure -######################## +Estructura de carpetas de CakePHP +################################# -Después de haber descargado y extraido la aplicación CakePHP, estos son los -archivos y directorios que podrás ver: - -- bin -- config -- logs -- plugins -- src -- tests -- tmp -- vendor -- webroot -- .htaccess -- composer.json -- index.php -- README.md - -Notarás unos cuantos directorios de primer nivel: +Después de haber descargado el esqueleto de aplicación de CakePHP, estos son los +directorios de primer nivel que deberías ver: - La carpeta *bin* contiene los ejecutables por consola de Cake. - La carpeta *config* contiene los documentos de :doc:`/development/configuration` que utiliza CakePHP. Detalles de la conexión - a la Base de Datos, bootstrapping, arhivos de configuración del core y otros, + a la Base de Datos, bootstrapping, archivos de configuración del core y otros, serán almacenados aquí. - La carpeta *plugins* es donde se almacenan los :doc:`/plugins` que utiliza tu aplicación. - La carpeta de *logs* contiene normalmente tus archivos de log, dependiendo de tu configuración de log. -- La carpeta *src* será donde tu crearás tu mágia: es donde se almacenarán los +- La carpeta *src* será donde tu crearás tu magia: es donde se almacenarán los archivos de tu aplicación. +- La carpeta *templates* contiene los archivos de presentación: + elementos, páginas de error, plantillas generales y plantillas de vistas. +- La carpeta *resources* contiene sub carpetas para varios tipos de archivos. +- La carpeta *locales* contiene sub carpetas para los archivos de traducción a otros idiomas. - La carpeta *tests* será donde pondrás los test para tu aplicación. - La carpeta *tmp* es donde CakePHP almacenará temporalmente la información. La información actual que almacenará dependerá de cómo se configure CakePHP, pero esta carpeta es normalmente utilizada para almacenar descripciones de modelos y a veces información de sesión. - La carpeta *vendor* es donde CakePHP y otras dependencias de la aplicación - serán instaladas. Comprométete a **no** editar los archivos de esta carpeta. - No podremos ayudarte si modificas el core. + serán instaladas por `Composer `_. Editar éstos archivos no es + recomendado, ya que Composer sobre escribirá tus cambios en la próxima actualización.. - El directorio *webroot* es la raíz de los documentos públicos de tu aplicación. Contiene todos los archivos que quieres que sean accesibles públicamente. -Asegúrate de que las carpetas *tmp* y *logs* existen y permiten escritura, en -caso contrario el rendimiento de tu aplicación se verá gravemente perjudicado. -En modo debug, CakePHP te avisará si este no es el caso. + Asegúrate de que las carpetas *tmp* y *logs* existen y permiten escritura, en + caso contrario el rendimiento de tu aplicación se verá gravemente perjudicado. + En modo debug, CakePHP te avisará si este no es el caso. La carpeta src ============== @@ -53,21 +41,25 @@ La carpeta src La carpeta *src* de CakePHP es donde tú harás la mayor parte del desarrollo de tu aplicación. Observemos más detenidamente dentro de la carpeta *src*. +Command + Contiene los comandos de consola de tu aplicación. + Para más información mirar :doc:`/console-commands/commands`. Console - Contiene los comandos de consola y las tareas de consola de tu aplicación. - Para más información mirar :doc:`/console-and-shells`. + Contiene los 'scripts' de instalación ejecutados por Composer. Controller - Contiene los controladores de tu aplicación y sus componentes. -Locale - Almacena los ficheros de string para la internacionalización. + Contiene los :doc:`/controllers` de tu aplicación y sus componentes. +Middleware + Contiene cualquier :doc:`/controllers/middleware` para tu aplicación. Model - Contiene las tablas, entidades y funcionamiento de tu aplicación. + Contiene las tablas, entidades y comportamientos de tu aplicación. View - Las clases de presentación se ubican aquí: cells, helpers y templates. -Template - Los archivos de presentación se almacenan aquí: elementos, páginas de error, - layouts, y templates. + Las clases de presentación se ubican aquí: plantillas de vistas, células y ayudantes. + +.. note:: + + La carpeta ``Command`` no está creada por defecto. + Puedes añadirla cuando la necesites. .. meta:: - :title lang=es: CakePHP Structura de Carpetas - :keywords lang=es: librerias internas,configuracion core,descripciones de modelos, vendors externos,detalles de conexión,estructura de carpetas,librerías,compromiso personal,conexión base de datos,internacionalización,archivos de configuración,carpetas,desarrollo de aplicaciones,léeme,lib,configurado,logs,config,third party,cakephp + :title lang=es: CakePHP Estructura de Carpetas + :keywords lang=es: librerías internas,configuración core,descripciones de modelos, vendors externos,detalles de conexión,estructura de carpetas,librerías,compromiso personal,conexión base de datos,internacionalización,archivos de configuración,carpetas,desarrollo de aplicaciones,léeme,lib,configurado,logs,config,third party,cakephp diff --git a/es/intro/where-to-get-help.rst b/es/intro/where-to-get-help.rst index 7c633758c1..b04f0eb312 100644 --- a/es/intro/where-to-get-help.rst +++ b/es/intro/where-to-get-help.rst @@ -17,7 +17,7 @@ El Cookbook Este manual probablemente debería ser el primer lugar al que debas acudir para obtener respuestas. Como muchos otros proyectos de código libre, nuevos -colaborades se unen regularmente. Intenta encontrar por ti mismo las respuestas +colaboradores se unen regularmente. Intenta encontrar por ti mismo las respuestas a tus preguntas primero, puede que así tardes más en encontrar las respuestas pero permanecerán durante más tiempo - y además aliviarás nuestra carga de soporte. Tanto el manual como la API tienen una versión online. @@ -62,7 +62,7 @@ El canal IRC - `#cakephp-fr `_ -- Canal francés. Si estás atascado, péganos un grito en el canal IRC de CakePHP. -Alguién del `equipo de desarrollo `_ +Alguien del `equipo de desarrollo `_ está normalmente, especialmente durante las horas de día para usuarios de América del Norte y del Sur. Estaremos encantados de escucharte, tanto si necesitas ayuda como si quieres encontrar usuarios en tu zona o si quieres From f39a9740844bdb3163a09f0b5e2ba943e52cf046 Mon Sep 17 00:00:00 2001 From: Antonio Reveron Date: Mon, 16 Oct 2023 12:47:00 +0100 Subject: [PATCH 056/337] Created migration guides files and update ES translation for migration-guides.rst and 5-0-updgrate-guide.rst --- es/appendices/4-0-migration-guide.rst | 15 - es/appendices/5-0-migration-guide.rst | 423 ++++++++++++++++++++++++++ es/appendices/5-0-upgrade-guide.rst | 77 +++++ es/appendices/migration-guides.rst | 16 + es/appendices/phpunit10.rst | 65 ++++ 5 files changed, 581 insertions(+), 15 deletions(-) delete mode 100644 es/appendices/4-0-migration-guide.rst create mode 100644 es/appendices/5-0-migration-guide.rst create mode 100644 es/appendices/5-0-upgrade-guide.rst create mode 100644 es/appendices/migration-guides.rst create mode 100644 es/appendices/phpunit10.rst diff --git a/es/appendices/4-0-migration-guide.rst b/es/appendices/4-0-migration-guide.rst deleted file mode 100644 index 4a690f257d..0000000000 --- a/es/appendices/4-0-migration-guide.rst +++ /dev/null @@ -1,15 +0,0 @@ -4.0 Migration Guide -################### - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: CakePHP Development Process - :keywords lang=es: maintenance branch,community interaction,community feature,necessary feature,stable release,ticket system,advanced feature,power users,feature set,chat irc,leading edge,router,new features,members,attempt,development branches,branch development diff --git a/es/appendices/5-0-migration-guide.rst b/es/appendices/5-0-migration-guide.rst new file mode 100644 index 0000000000..11f6c80514 --- /dev/null +++ b/es/appendices/5-0-migration-guide.rst @@ -0,0 +1,423 @@ +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. +- Global functions are now opt-in. If your application uses global function + aliases be sure to add ``require CAKE . 'functions.php'`` to you application's + ``config/bootstrap.php``. +- 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 + +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. + +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 `__ +- ``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 + +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::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``. + +.. meta:: + :title lang=es: 5.0 Guía de migración + :keywords lang=es: maintenance branch,community interaction,community feature,necessary feature,stable release,ticket system,advanced feature,power users,feature set,chat irc,leading edge,router,new features,members,attempt,development branches,branch development diff --git a/es/appendices/5-0-upgrade-guide.rst b/es/appendices/5-0-upgrade-guide.rst new file mode 100644 index 0000000000..44e75c798d --- /dev/null +++ b/es/appendices/5-0-upgrade-guide.rst @@ -0,0 +1,77 @@ +5.0 Guía de actualización +################# + +En primer lugar, compruebe que su aplicación se está ejecutando en la última versión de CakePHP 4.x. + +Arreglar avisos de obsolescencia +======================== + +Una vez que su aplicación se ejecuta en la última version de CakePHP 4.x, activar advertencias de obsoletos en **config/app.php**:: + + 'Error' => [ + 'errorLevel' => E_ALL, + ] + +Ahora que puede ver todas las advertencias, asegúrese de que están corregidas antes de proceder con la actualización. + +Algunas obsolescencia potencialmente impactantes que debes asegurarte de haber abordado +son: + +- ``Table::query()`` was deprecated in 4.5.0. Use ``selectQuery()``, + ``updateQuery()``, ``insertQuery()`` and ``deleteQuery()`` instead. + +Actualiza a PHP 8.1 +================== + +Si no estas ejecutando en **PHP 8.1 o superior**, tendrás que actualizar PHP antes de actualizar CakePHP. + +.. note:: + CakePHP 5.0 requiere **un mínimo de PHP 8.1**. + +.. _upgrade-tool-use: + +Usar la herramienta de actualización +==================== + +.. note:: + La herramienta de actualización sólo funciona en aplicaciones que se ejecutan en cakePHP 4.x. No puedes ejecutar la herramienta de actualización después de actualizar a CakePHP 5.0. + +Debido a que CakePHP 5 aprovecha los tipos de unión y ``mixed``, existen muchos +cambios incompatibles con versiones anteriores relativas a las definiciones de los métodos y cambios de nombre archivos. +Para ayudar a acelerar los arreglos de estos cambios tediosos, existe una herramienta CLI de actualización: + +.. code-block:: console + + # Instalar la herramienta de actualización + git clone https://github.com/cakephp/upgrade + cd upgrade + git checkout 5.x + composer install --no-dev + +Con la herramienta de actualización instalada, ahora puedes ejecutarla en su aplicación o +plugin:: + + bin/cake upgrade rector --rules cakephp50 + bin/cake upgrade rector --rules chronos3 + +Actualizar dependencias de CakePHP +========================= + +Después de aplicar las refactorizaciones de rector necesitas actualizar CakePHP, sus plugins, PHPUnit +y tal vez otras dependencias en tu ``composer.json``. +Este proceso depende de gran medida de tu aplicación por lo que le recomendamos que compare tu +``composer.json`` con el que esta presente en `cakephp/app +`__. + +After the version strings are adjusted in your ``composer.json`` execute +``composer update -W`` and check its output. + +Actualiza los archivos de la aplicación basándose en las últimas plantillas +=============================================== + +A continuación, asegurate de que el resto de tu aplicación este actualizado basándose en la ultima version de `cakephp/app +`__. + +.. meta:: + :title lang=es: 5.0 Guía de actualización + :keywords lang=es: maintenance branch,community interaction,community feature,necessary feature,stable release,ticket system,advanced feature,power users,feature set,chat irc,leading edge,router,new features,members,attempt,development branches,branch development diff --git a/es/appendices/migration-guides.rst b/es/appendices/migration-guides.rst new file mode 100644 index 0000000000..0fb412961f --- /dev/null +++ b/es/appendices/migration-guides.rst @@ -0,0 +1,16 @@ +Guías de migración +################ + +Las guías de migración contienen información relativa a las nuevas funcionalidades introducidas en +cada versión y la ruta de migración entre 4.x y 5.x + +.. toctree:: + :maxdepth: 1 + + ./5-0-upgrade-guide + ./5-0-migration-guide + ./phpunit10 + +.. meta:: + :title lang=es: Guías de migración + :keywords lang=es: maintenance branch,community interaction,community feature,necessary feature,stable release,ticket system,advanced feature,power users,feature set,chat irc,leading edge,router,new features,members,attempt,development branches,branch development diff --git a/es/appendices/phpunit10.rst b/es/appendices/phpunit10.rst new file mode 100644 index 0000000000..ff93663740 --- /dev/null +++ b/es/appendices/phpunit10.rst @@ -0,0 +1,65 @@ +PHPUnit 10 Upgrade +################## + +With CakePHP 5 the minimum PHPUnit version has changed from ``^8.5 || ^9.3`` to ``^10.1``. +This introduces a few breaking changes from PHPUnit as well as from CakePHP's side. + +phpunit.xml adjustments +======================= + +It is recommended to let PHPUnit update its configuration file via the following command:: + + vendor/bin/phpunit --migrate-configuration + +.. note:: + + Make sure you are already on PHPUnit 10 via ``vendor/bin/phpunit --version`` before executing this command! + +With this command out of the way your ``phpunit.xml`` already has most of the recommended changes present. + +New event system +---------------- + +PHPUnit 10 removed the old hook system and introduced a new `Event system +`_ +which requires the following code in your ``phpunit.xml`` to be adjusted from:: + + + + + +to:: + + + + + +``->withConsecutive()`` has been removed +======================================== + +You can convert the removed ``->withConsecutive()`` method to a +working interim solution like you can see here:: + + ->withConsecutive(['firstCallArg'], ['secondCallArg']) + +should be converted to:: + + ->with( + ...self::withConsecutive(['firstCallArg'], ['secondCallArg']) + ) + +the static ``self::withConsecutive()`` method has been added via the ``Cake\TestSuite\PHPUnitConsecutiveTrait`` +to the base ``Cake\TestSuite\TestCase`` class so you don't have to manually add that trait to your Testcase classes. + +data providers have to be static +================================ + +If your testcases leverage the data provider feature of PHPUnit then +you have to adjust your data providers to be static:: + + public function myProvider(): array + +should be converted to:: + + public static function myProvider(): array + From 46deb0732bc1112462d8d029248da050d8ac0d46 Mon Sep 17 00:00:00 2001 From: ADmad Date: Tue, 17 Oct 2023 18:47:28 +0530 Subject: [PATCH 057/337] Remove redundant info 5.x has only the immutable versions of datetime classes. --- en/orm/database-basics.rst | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index b3a5d3283e..7ccd4b4d73 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -757,23 +757,6 @@ The above class does a few interesting things: Once we've built our custom type, we'll need to :ref:`connect our type to our table class `. -.. _immutable-datetime-mapping: - -Enabling Immutable DateTime Objects ------------------------------------ - -Because Date/Time objects are easily mutated in place, CakePHP allows you to -enable immutable value objects. This is best done in your application's -**config/bootstrap.php** file:: - - TypeFactory::build('datetime')->useImmutable(); - TypeFactory::build('date')->useImmutable(); - TypeFactory::build('time')->useImmutable(); - TypeFactory::build('timestamp')->useImmutable(); - -.. note:: - New applications will have immutable objects enabled by default. - Connection Classes ================== From 55b15aad40be72217ac9cc9173cecdca828d098e Mon Sep 17 00:00:00 2001 From: ADmad Date: Tue, 17 Oct 2023 19:10:13 +0530 Subject: [PATCH 058/337] Improve field name e.g. --- en/views/helpers/form.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 40cd97ae25..f319100f62 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -1266,7 +1266,7 @@ Creating Select Pickers .. php:method:: select(string $fieldName, array $options, array $attributes) -* ``$fieldName`` - A field name in the form ``'Modelname.fieldname'``. This +* ``$fieldName`` - A field name in the form ``'fieldname'`` or ``'related_entity.fieldname'``. This will provide the ``name`` attribute of the ``select`` element. * ``$options`` - An optional array containing the list of items for the select picker. When this array is missing, the method will generate only the From 9134f22a4be39a672d60d0d56f74aa507b183b6c Mon Sep 17 00:00:00 2001 From: William Date: Wed, 18 Oct 2023 02:44:16 -0300 Subject: [PATCH 059/337] WebExceptionRenderer path --- en/development/errors.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/development/errors.rst b/en/development/errors.rst index b8fcf1a8ad..04385d0e7c 100644 --- a/en/development/errors.rst +++ b/en/development/errors.rst @@ -140,7 +140,7 @@ Custom Templates ================ The default exception trap renders all uncaught exceptions your application -raises with the help of ``Cake\Error\WebExceptionRenderer``, and your application's +raises with the help of ``Cake\Error\Renderer\WebExceptionRenderer``, and your application's ``ErrorController``. The error page views are located at **templates/Error/**. All 4xx errors use @@ -229,7 +229,7 @@ error pages when this error is handled:: // In src/Error/AppExceptionRenderer.php namespace App\Error; - use Cake\Error\WebExceptionRenderer; + use Cake\Error\Renderer\WebExceptionRenderer; class AppExceptionRenderer extends WebExceptionRenderer { @@ -259,7 +259,7 @@ additional logic when handling CakePHP errors:: // In src/Error/AppExceptionRenderer.php namespace App\Error; - use Cake\Error\WebExceptionRenderer; + use Cake\Error\Renderer\WebExceptionRenderer; class AppExceptionRenderer extends WebExceptionRenderer { @@ -281,7 +281,7 @@ override the ``_getController()`` method in your exception renderer:: use App\Controller\SuperCustomErrorController; use Cake\Controller\Controller; - use Cake\Error\WebExceptionRenderer; + use Cake\Error\Renderer\WebExceptionRenderer; class AppExceptionRenderer extends WebExceptionRenderer { From 4d61a05b0fb14c223fba089ce9dcbf572eae66b0 Mon Sep 17 00:00:00 2001 From: Andres Campanario Date: Wed, 18 Oct 2023 10:24:09 +0200 Subject: [PATCH 060/337] translate plugins page to spanish --- en/plugins.rst | 4 +- es/plugins.rst | 626 ++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 622 insertions(+), 8 deletions(-) diff --git a/en/plugins.rst b/en/plugins.rst index 428b6f65a1..03f0051cdf 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -117,7 +117,7 @@ appropriate parts of your application. The hooks are: * ``services`` Used to register application container services By default all plugins hooks are enabled. You can disable hooks by using the -related options of the ``plugin load`` command:: +related options of the ``plugin load`` command: .. code-block:: console @@ -195,7 +195,7 @@ You can reference a plugin's controllers, models, components, behaviors, and helpers by prefixing the name of the plugin. For example, say you wanted to use the ContactManager plugin's -ContactInfoHelper to output formatted contact information in +``ContactInfoHelper`` to output formatted contact information in one of your views. In your controller, using ``addHelper()`` could look like this:: diff --git a/es/plugins.rst b/es/plugins.rst index 14378d0b78..18d9ffa6b3 100644 --- a/es/plugins.rst +++ b/es/plugins.rst @@ -1,15 +1,629 @@ Plugins ####### +CakePHP te permite configurar una combinación de controladores, modelos y vistas y liberarlos como un plugin de aplicación pre-empaquetado que otros pueden usar en sus aplicaciones CakePHP. Si has creado una gran gestión de usuarios, un blog sencillo, o adaptadores de servicios web en una de tus aplicaciones ¿por qué no empaquetarlo como un plugin CakePHP? De esta manera puedes utilizarlo en tus otras aplicaciones y compartirlo con la comunidad. + +Un plugin de CakePHP es independiente de la aplicación principal y generalmente proporciona alguna funcionalidad bien definida que se puede empaquetar de forma ordenada y reutilizar con poco esfuerzo en otras aplicaciones. La aplicación y el plugin operan en sus respectivos espacios, pero comparten los datos de configuración de la aplicación (por ejemplo, conexiones de base de datos, transportes de correo electrónico). + +Los plugins deben definir su propio espacio de nombres (namespace) de nivel superior. Por ejemplo: ``DebugKit``. Por convención, los plugins utilizan el nombre de su paquete como su espacio de nombres. Si deseas utilizar un espacio de nombres diferente, puedes configurarlo cuando se cargan los plugins. + +Instalación de un plugin con Composer +===================================== + +Muchos plugins están disponibles en `Packagist `_ +y se pueden instalar con ``Composer``. Para instalar DebugKit +debes hacer lo siguiente: + +.. code-block:: console + + php composer.phar require cakephp/debug_kit + +Esto instalará la última versión de DebugKit y actualizará tus archivos **composer.json** y **composer.lock**, también actualizará el archivo **vendor/cakephp-plugins.php** y tu cargador automático (autoloader). + + +Instalación manual de un Plugin +=============================== + +Si el complemento que deseas instalar no está disponible en packagist.org, puedes clonar o copiar el código del complemento en tu directorio de **plugins**. Supongamos que deseas instalar un complemento llamado 'ContactManager', debes tener una carpeta en **plugins** llamada 'ContactManager'. En este directorio se encuentran las carpetas src, tests y cualquier otra carpeta del complemento. + +.. _autoloading-plugin-classes: + +Carga automática manual de clases de Plugins +-------------------------------------------- + +Si instalas tus complementos mediante ``composer`` o ``bake``, no deberías necesitar configurar la carga automática de clases para tus plugins. + +Si creas un plugin manualmente en el directorio ``plugins``, entonces necesitarás indicarle a ``composer`` que actualice su caché de carga automática: + +.. code-block:: console + + php composer.phar dumpautoload + +Si estás utilizando espacios de nombres de proveedores para tus plugins, deberás agregar el mapeo de espacio de nombres a la ruta en el archivo ``composer.json`` de la siguiente manera, antes de ejecutar el comando de composer mencionado anteriormente: + +.. code-block:: json + + { + "autoload": { + "psr-4": { + "AcmeCorp\\Users\\": "plugins/AcmeCorp/Users/src/", + } + }, + "autoload-dev": { + "psr-4": { + "AcmeCorp\\Users\\Test\\": "plugins/AcmeCorp/Users/tests/" + } + } + } + +.. _loading-a-plugin: + +Cargar un Plugin +================ + +Si deseas utilizar las rutas, comandos de consola, middlewares, listeners de eventos, plantillas o assets de la carpeta web (webroot) de un plugin, deberás cargar el plugin. + +Si solo deseas utilizar helpers, comportamientos o componentes de un plugin, no es necesario cargar explícitamente el plugin, aunque siempre es recomendable hacerlo. + +También hay un práctico comando de consola para cargar el plugin. Ejecuta la siguiente línea: + +.. code-block:: console + + bin/cake plugin load ContactManager + +Esto actualizaría el array en el archivo ``config/plugins.php`` de tu aplicación con una entrada similar a ``'ContactManager' => []``. + +Configuración de Hooks del Plugin +================================= + +Los plugins ofrecen varios hooks (ganchos) que permiten que un plugin se inyecte en las partes apropiadas de tu aplicación. Los hooks son: + +* ``bootstrap`` Se utiliza para cargar archivos de configuración predeterminados del plugin, definir constantes y otras funciones globales. +* ``routes`` Se utiliza para cargar las rutas de un plugin. Se activa después de que se cargan las rutas de la aplicación. +* ``middleware`` middleware Se utiliza para agregar el middleware del plugin a la cola de middlewares de una aplicación. +* ``console`` Se utiliza para agregar comandos de consola a la colección de comandos de una aplicación. +* ``services`` Se utiliza para registrar servicios del contenedor de aplicaciones. + +Por defecto, todos los hooks de los plugins están habilitados. Puedes deshabilitar los hooks utilizando las opciones relacionadas del comando plugin load: + +.. code-block:: console + + bin/cake plugin load ContactManager --no-routes + +Esto actualizaría el array en el archivo ``config/plugins.php`` de tu aplicación con una entrada similar a ``'ContactManager' => ['routes' => false]``. + +Opciones de Carga de Plugins +============================ + +Además de las opciones para los hooks de complementos, el comando ``plugin load`` tiene las siguientes opciones para controlar la carga del plugin: + +- ``--only-debug`` Carga el plugin solo cuando el modo de depuración (debug) está habilitado. +- ``--only-cli`` Carga el plugin solo para CLI. +- ``--optional`` No arroja un error si el plugin no está disponible. + +Cargar Plugins a través de ``Application::bootstrap()`` +============================================================== + +Además del array de configuración en ``config/plugins.php``, los plugins también se pueden cargar en el método ``bootstrap()`` de tu aplicación:: + + // In src/Application.php + use Cake\Http\BaseApplication; + use ContactManager\ContactManagerPlugin; + + class Application extends BaseApplication + { + public function bootstrap() + { + parent::bootstrap(); + + // Load the contact manager plugin by class name + $this->addPlugin(ContactManagerPlugin::class); + + // Load a plugin with a vendor namespace by 'short name' with options + $this->addPlugin('AcmeCorp/ContactManager', ['console' => false]); + + // Load a dev dependency that will not exist in production builds. + $this->addOptionalPlugin('AcmeCorp/ContactManager'); + } + } + +Puedes configurar hooks con opciones de array o utilizando los métodos proporcionados por las clases del plugin:: + + // In Application::bootstrap() + use ContactManager\ContactManagerPlugin; + + // Use the disable/enable to configure hooks. + $plugin = new ContactManagerPlugin(); + + $plugin->disable('bootstrap'); + $plugin->enable('routes'); + $this->addPlugin($plugin); + +Los objetos del plugin también conocen sus nombres e información de la ruta:: + + $plugin = new ContactManagerPlugin(); + + // Get the plugin name. + $name = $plugin->getName(); + + // Path to the plugin root, and other paths. + $path = $plugin->getPath(); + $path = $plugin->getConfigPath(); + $path = $plugin->getClassPath(); + +Uso de las Clases del Plugins +----------------------------- + +Puedes hacer referencia a los controladores, modelos, componentes, comportamientos y helpers de un plugin prefijando el nombre del plugin. + +Por ejemplo, supongamos que quieres usar el helper ``ContactInfoHelper`` del plugin ContactManager para mostrar información de contacto formateada en una de tus vistas. En tu controlador, usar ``addHelper()`` podría verse así:: + + $this->viewBuilder()->addHelper('ContactManager.ContactInfo'); + .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. + Este nombre de clase separado por puntos se denomina :term:`Sintaxis de plugin`. + +Luego podrías acceder al ``ContactInfoHelper`` de la misma manera que cualquier otro helper en tu vista, como por ejemplo:: + + echo $this->ContactInfo->address($contact); + +Los plugins pueden utilizar los modelos, componentes, comportamientos y helpers proporcionados por la aplicación, o por otros plugins si es necesario:: + + // Use an application component + $this->loadComponent('AppFlash'); + + // Use another plugin's behavior + $this->addBehavior('OtherPlugin.AuditLog'); + +.. _plugin-create-your-own: + +Creación de tus propios Plugins +------------------------------- + +Como ejemplo práctico, comencemos a crear el plugin ContactManager mencionado anteriormente. Para empezar, configuraremos la estructura básica del directorio de nuestro complemento. Debería verse así:: + + /src + /plugins + /ContactManager + /config + /src + /ContactManagerPlugin.php + /Controller + /Component + /Model + /Table + /Entity + /Behavior + /View + /Helper + /templates + /layout + /tests + /TestCase + /Fixture + /webroot + +Ten en cuenta el nombre de la carpeta del plugin, '**ContactManager**'. Es importante que esta carpeta tenga el mismo nombre que el plugin. + +Dentro de la carpeta del plugin, notarás que se parece mucho a una aplicación de CakePHP, y básicamente eso es lo que es. En lugar de un archivo ``Application.php``, tienes un archivo ``ContactManagerPlugin.php``. No es necesario incluir ninguna de las carpetas que no estés usando. Algunos plugins solo pueden definir un Component y un Behavior, y en ese caso pueden omitir completamente el directorio 'templates'. + +Un plugin también puede tener prácticamente cualquiera de los otros directorios que puede tener tu aplicación, como Config, Console, webroot, etc. + +Crear un Plugin Utilizando Bake +------------------------------- + +El proceso de creación de plugins puede simplificarse enormemente utilizando Bake. + +Para hornear (bakear) un plugin, utiliza el siguiente comando: + +.. code-block:: console + + bin/cake bake plugin ContactManager + +Bake puede utilizarse para crear clases en tu plugin. Por ejemplo, para generar +un controlador de plugin podrías ejecutar: + +.. code-block:: console + + bin/cake bake controller --plugin ContactManager Contacts + + +Por favor, consulta el capítulo +:doc:`/bake/usage` si tienes +problemas al utilizar la línea de comandos. Asegúrate de regenerar tu +cargador automático (autoloader) una vez que hayas creado tu plugin: + +.. code-block:: console + + php composer.phar dumpautoload + +.. _plugin-objects: + +Objetos del Plugin +================== + +Los Objetos de Plugin permiten a un autor de plugin definir lógica de configuración, ganchos (hooks) predeterminados, cargar rutas, middleware y comandos de consola. Los objetos de plugin se encuentran en +**src/Plugin.php**. Para nuestro plugin ContactManager, nuestra clase de plugin podría verse así:: + + namespace ContactManager; + + use Cake\Core\BasePlugin; + use Cake\Core\ContainerInterface; + use Cake\Core\PluginApplicationInterface; + use Cake\Console\CommandCollection; + use Cake\Http\MiddlewareQueue; + use Cake\Routing\RouteBuilder; + + class ContactManagerPlugin extends BasePlugin + { + + /** + * @inheritDoc + */ + public function middleware(MiddlewareQueue $middleware): MiddlewareQueue + { + // Add middleware here. + $middleware = parent::middleware($middleware); + + return $middleware; + } + + /** + * @inheritDoc + */ + public function console(CommandCollection $commands): CommandCollection + { + // Add console commands here. + $commands = parent::console($commands); + + return $commands; + } + + /** + * @inheritDoc + */ + public function bootstrap(PluginApplicationInterface $app): void + { + // Add constants, load configuration defaults. + // By default will load `config/bootstrap.php` in the plugin. + parent::bootstrap($app); + } + + /** + * @inheritDoc + */ + public function routes(RouteBuilder $routes): void + { + // Add routes. + // By default will load `config/routes.php` in the plugin. + parent::routes($routes); + } + + /** + * Register application container services. + * + * @param \Cake\Core\ContainerInterface $container The Container to update. + * @return void + * @link https://book.cakephp.org/5/en/development/dependency-injection.html#dependency-injection + */ + public function services(ContainerInterface $container): void + { + // Add your services here + } + } + +.. _plugin-routes: + +Rutas del Plugin +================ + +Los plugins pueden proporcionar archivos de rutas que contienen sus propias rutas. Cada plugin puede contener un archivo **config/routes.php** . Este archivo de rutas se puede cargar cuando se agrega el plugin o en el archivo de rutas de la aplicación. Para crear las rutas del plugin ContactManager, coloca lo siguiente en **plugins/ContactManager/config/routes.php**:: + + plugin( + 'ContactManager', + ['path' => '/contact-manager'], + function ($routes) { + $routes->setRouteClass(DashedRoute::class); + + $routes->get('/contacts', ['controller' => 'Contacts']); + $routes->get('/contacts/{id}', ['controller' => 'Contacts', 'action' => 'view']); + $routes->put('/contacts/{id}', ['controller' => 'Contacts', 'action' => 'update']); + } + ); + +Lo anterior conectará las rutas predeterminadas para tu plugin. Más adelante, puedes personalizar este archivo con rutas más específicas. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +También puedes cargar las rutas del plugin en la lista de rutas de tu aplicación. Hacer esto te proporciona un mayor control sobre cómo se cargan las rutas del plugin y te permite envolver las rutas del plugin en ámbitos o prefijos adicionales:: + + $routes->scope('/', function ($routes) { + // Connect other routes. + $routes->scope('/backend', function ($routes) { + $routes->loadPlugin('ContactManager'); + }); + }); + +Lo anterior resultaría en URLs como ``/backend/contact-manager/contacts``. + +Controladores del Plugin +======================== + +Los controladores para nuestro plugin ContactManager se almacenarán en **plugins/ContactManager/src/Controller/**. Dado que la principal tarea que realizaremos es gestionar contactos, necesitaremos un ContactsController para este plugin. + +Entonces, colocamos nuestro nuevo ContactsController en **plugins/ContactManager/src/Controller** y se verá así:: + + // plugins/ContactManager/src/Controller/ContactsController.php + namespace ContactManager\Controller; + + use ContactManager\Controller\AppController; + + class ContactsController extends AppController + { + public function index() + { + //... + } + } + +También crea el controlador ``AppController`` si aún no lo tienes:: + + // plugins/ContactManager/src/Controller/AppController.php + namespace ContactManager\Controller; + + use App\Controller\AppController as BaseController; + + class AppController extends BaseController + { + } + +El ``AppController`` de un plugin puede contener lógica de controlador común a todos los controladores en un plugin, pero no es obligatorio usarlo. + +Si deseas acceder a lo que hemos hecho hasta ahora, visita ``/contact-manager/contacts``. Deberías obtener un error de "Modelo faltante" porque aún no hemos definido un modelo Contact. + +Si tu aplicación incluye el enrutamiento predeterminado que proporciona CakePHP, podrás acceder a los controladores de tu plugin utilizando URLs como:: + + // Access the index route of a plugin controller. + /contact-manager/contacts + + // Any action on a plugin controller. + /contact-manager/contacts/view/1 + +Si tu aplicación define prefijos de enrutamiento, el enrutamiento predeterminado de CakePHP también conectará rutas que utilizan el siguiente patrón:: + + /{prefix}/{plugin}/{controller} + /{prefix}/{plugin}/{controller}/{action} + +Consulta la sección sobre :ref:`configuracion-de-hooks-del-plugin` para obtener información sobre cómo cargar archivos de rutas específicos del plugin. + +.. _plugin-models: + +Modelos del Plugin +================== + +Los modelos para el plugin se almacenan en **plugins/ContactManager/src/Model**. +Ya hemos definido un ContactsController para este plugin, así que creemos +la tabla y entidad para ese controlador:: + + // plugins/ContactManager/src/Model/Entity/Contact.php: + namespace ContactManager\Model\Entity; + + use Cake\ORM\Entity; + + class Contact extends Entity + { + } + + // plugins/ContactManager/src/Model/Table/ContactsTable.php: + namespace ContactManager\Model\Table; + + use Cake\ORM\Table; + + class ContactsTable extends Table + { + } + +Si necesitas hacer referencia a un modelo dentro de tu plugin al establecer asociaciones o definir clases de entidad, debes incluir el nombre del plugin con el nombre de la clase, separados por un punto. Por ejemplo:: + + // plugins/ContactManager/src/Model/Table/ContactsTable.php: + namespace ContactManager\Model\Table; + + use Cake\ORM\Table; + + class ContactsTable extends Table + { + public function initialize(array $config): void + { + $this->hasMany('ContactManager.AltName'); + } + } + +Si prefieres que las claves del array para la asociación no tengan el prefijo del plugin, puedes utilizar la sintaxis alternativa:: + + // plugins/ContactManager/src/Model/Table/ContactsTable.php: + namespace ContactManager\Model\Table; + + use Cake\ORM\Table; + + class ContactsTable extends Table + { + public function initialize(array $config): void + { + $this->hasMany('AltName', [ + 'className' => 'ContactManager.AltName', + ]); + } + } + +Puedes utilizar ``Cake\ORM\Locator\LocatorAwareTrait`` para cargar las tablas de tu plugin utilizando la familiar :term:`Sintaxis de plugin`:: + + // Controllers already use LocatorAwareTrait, so you don't need this. + use Cake\ORM\Locator\LocatorAwareTrait; + + $contacts = $this->fetchTable('ContactManager.Contacts'); + +Plantillas de Plugin +==================== + +Las vistas se comportan exactamente como lo hacen en las aplicaciones normales. Solo colócalas en la carpeta correcta dentro de la carpeta ``plugins/[NombreDelPlugin]/templates/``. Para nuestro plugin ContactManager, necesitaremos una vista para nuestra acción ``ContactsController::index()``, así que incluyámosla también:: + + // plugins/ContactManager/templates/Contacts/index.php: +

Contacts

+

Following is a sortable list of your contacts

+ + +Los plugins pueden proporcionar sus propios diseños. Para añadir diseños de plugin, coloca tus archivos de plantilla dentro de +``plugins/[NombreDelPlugin]/templates/layout``. Para usar un diseño de plugin en tu controlador, puedes hacer lo siguiente:: + + $this->viewBuilder()->setLayout('ContactManager.admin'); + +Si se omite el prefijo del plugin, el archivo de diseño/vista se ubicará de forma normal. + +.. nota:: + + Para obtener información sobre cómo usar elementos de un plugin, consulta + :ref:`elementos` + +Sobrescribir Plantillas de Plugin desde dentro de tu Aplicación +--------------------------------------------------------------- + +Puedes sobrescribir cualquier vista de un plugin desde dentro de tu aplicación usando rutas especiales. Si tienes un plugin llamado 'ContactManager', puedes sobrescribir los archivos de plantilla del plugin con lógica de vista específica de la aplicación creando archivos utilizando la siguiente plantilla **templates/plugin/[Plugin]/[Controlador]/[vista].php**. Para el controlador Contacts podrías crear el siguiente archivo:: + + templates/plugin/ContactManager/Contacts/index.php + +Crear este archivo te permitiría sobrescribir **plugins/ContactManager/templates/Contacts/index.php**. + +Si tu plugin está en una dependencia de Composer (por ejemplo, 'Company/ContactManager'), la ruta a la vista 'index' del controlador Contacts será:: + + templates/plugin/TheVendor/ThePlugin/Custom/index.php + +Crear este archivo te permitiría sobrescribir **vendor/elproveedor/elplugin/templates/Custom/index.php**. + +Si el plugin implementa un prefijo de enrutamiento, debes incluir el prefijo de enrutamiento en las sobrescrituras de plantillas de tu aplicación. Por ejemplo, si el plugin 'ContactManager' implementara un prefijo 'Admin', la ruta de sobrescritura sería:: + + templates/plugin/ContactManager/Admin/ContactManager/index.php + +.. _plugin-assets: + + +Recursos de Plugin +================== + +Los recursos web de un plugin (pero no los archivos PHP) se pueden servir a través del directorio ``webroot`` del plugin, al igual que los recursos de la aplicación principal:: + + /plugins/ContactManager/webroot/ + css/ + js/ + img/ + flash/ + pdf/ + +Puedes colocar cualquier tipo de archivo en cualquier directorio, al igual que en un webroot regular. + +.. advertencia:: + + Manejar recursos estáticos (como imágenes, archivos JavaScript y CSS) + a través del Dispatcher es muy ineficiente. Consulta :ref:`symlink-assets` + para obtener más información. + +Enlazar a Recursos en Plugins +----------------------------- + +Puedes utilizar la :term:`Sintaxis de plugin` al enlazar a recursos de plugins utilizando los métodos script, image o css del :php:class:`~Cake\\View\\Helper\\HtmlHelper`:: + + // Generates a URL of /contact_manager/css/styles.css + echo $this->Html->css('ContactManager.styles'); + + // Generates a URL of /contact_manager/js/widget.js + echo $this->Html->script('ContactManager.widget'); + + // Generates a URL of /contact_manager/img/logo.jpg + echo $this->Html->image('ContactManager.logo'); + +Los recursos de los plugins se sirven por defecto utilizando el middleware ``AssetMiddleware``. Esto solo se recomienda para desarrollo. En producción, debes :ref:`crear enlaces simbólicos para los recursos del plugin ` para mejorar el rendimiento. + +Si no estás usando los ayudantes (helpers), puedes agregar /nombre-del-plugin/ al principio de la URL para un recurso dentro del plugin y servirlo de esa manera. Enlazar a '/contact_manager/js/some_file.js' serviría el recurso **plugins/ContactManager/webroot/js/some_file.js**. + +Componentes, Helpers y Behaviours +================================= + +Un plugin puede tener Componentes, Helpers y Behaviours, al igual que una aplicación de CakePHP. Incluso puedes crear plugins que consistan solo en Componentes, Helpers y Behaviours, lo que puede ser una excelente manera de construir componentes reutilizables que se pueden integrar en cualquier proyecto. + +La construcción de estos componentes es exactamente igual a construirlos dentro de una aplicación regular, sin ninguna convención de nomenclatura especial. + +Hacer referencia a tu componente desde dentro o fuera de tu plugin solo requiere que agregues el nombre del plugin antes del nombre del componente. Por ejemplo:: + + // Component defined in 'ContactManager' plugin + namespace ContactManager\Controller\Component; + + use Cake\Controller\Component; + + class ExampleComponent extends Component + { + } + + // Within your controllers + public function initialize(): void + { + parent::initialize(); + $this->loadComponent('ContactManager.Example'); + } + +La misma técnica se aplica a Ayudantes y Comportamientos. + +.. _plugin-commands: + +Comandos +======== + +Los plugins pueden registrar sus comandos dentro del gancho ``console()``. Por defecto, todos los comandos de consola en el plugin se descubren automáticamente y se añaden a la lista de comandos de la aplicación. Los comandos de los plugins llevan el prefijo del nombre del plugin. Por ejemplo, el ``UserCommand`` proporcionado por el plugin ``ContactManager`` se registraría tanto como ``contact_manager.user`` como ``user``. El nombre sin prefijo solo será tomado por un plugin si no es utilizado por la aplicación o por otro plugin. + +Puedes personalizar los nombres de los comandos definiendo cada comando en tu plugin:: + + public function console($commands) + { + // Create nested commands + $commands->add('bake model', ModelCommand::class); + $commands->add('bake controller', ControllerCommand::class); + + return $commands; + } + +Probar tu Plugin +================ + +Si estás probando controladores o generando URL, asegúrate de que tu +plugin conecte las rutas en ``tests/bootstrap.php``. + +Para obtener más información, consulta la página de :doc:`pruebas de plugins `. + +Publicar tu Plugin +================== + +Los plugins de CakePHP deben publicarse en `Packagist `__. De esta manera, otras personas pueden usarlo como dependencia de Composer. También puedes proponer tu plugin a la lista de `awesome-cakephp `_. + +Elige un nombre semánticamente significativo para el nombre del paquete. Idealmente, este debería llevar el prefijo del framework, en este caso "cakephp" como el framework. El nombre del proveedor generalmente será tu nombre de usuario de GitHub. **No** uses el espacio de nombres de CakePHP (cakephp) ya que está reservado para los plugins propiedad de CakePHP. La convención es usar letras minúsculas y guiones como separadores. + +Entonces, si creaste un plugin "Logging" con tu cuenta de GitHub "FooBar", un buen nombre sería `foo-bar/cakephp-logging`. +Y el plugin propiedad de CakePHP llamado "Localized" se puede encontrar bajo `cakephp/localized`, respectivamente. + +.. index:: vendor/cakephp-plugins.php + +Archivo de Mapeo del Plugin +=========================== + +Cuando instalas plugins a través de Composer, es posible que notes que se crea **vendor/cakephp-plugins.php**. Este archivo de configuración contiene un mapa de nombres de plugins y sus rutas en el sistema de archivos. Permite que los plugins se instalen en el directorio estándar del proveedor que está fuera de las rutas de búsqueda normales. La clase ``Plugin`` utilizará este archivo para localizar plugins cuando se carguen con ``addPlugin()``. En general, no necesitarás editar este archivo manualmente, ya que Composer y el paquete ``plugin-installer`` se encargarán de gestionarlo por ti. + +Gestiona tus Plugins usando Mixer +================================= + +Otra forma de descubrir y gestionar plugins en tu aplicación de CakePHP es a través de `Mixer `_. Es un plugin de CakePHP que te ayuda a instalar plugins desde Packagist. También te ayuda a gestionar tus plugins existentes. + +.. note:: - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + IMPORTANTE: No uses esto en un entorno de producción. .. meta:: :title lang=es: Plugins - :keywords lang=es: plugin folder,configuration database,bootstrap,management module,little space,database connection,webroot,user management,contactmanager,array,config,cakephp,models,php,directories,blog,plugins,applications + :keywords lang=es: plugins, controladores, modelos, vistas, paquete, aplicación From 0cf83105117a2fc09a0e510067cbc4304eb2656f Mon Sep 17 00:00:00 2001 From: Andres Campanario Date: Thu, 19 Oct 2023 09:50:44 +0200 Subject: [PATCH 061/337] fix ref --- es/plugins.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/es/plugins.rst b/es/plugins.rst index 18d9ffa6b3..7e67630ed2 100644 --- a/es/plugins.rst +++ b/es/plugins.rst @@ -482,8 +482,7 @@ Si se omite el prefijo del plugin, el archivo de diseño/vista se ubicará de fo .. nota:: - Para obtener información sobre cómo usar elementos de un plugin, consulta - :ref:`elementos` + Para obtener información sobre cómo usar elementos de un plugin, consulta :ref:`elementos` Sobrescribir Plantillas de Plugin desde dentro de tu Aplicación --------------------------------------------------------------- From 3be4980221c98df7f51dc3b4d62796fedc7cd05f Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 19 Oct 2023 11:02:37 -0700 Subject: [PATCH 062/337] Add migration notes for cakephp/cakephp#17343 --- en/appendices/5-1-upgrade-guide.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 0f65e60547..1dd32a3942 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -14,3 +14,9 @@ Http - ``SecurityHeadersMiddleware::setPermissionsPolicy()`` was added. This method adds the ability to define ``permissions-policy`` header values. + +Validation +---------- + +- ``Validation::enum()`` and ``Validator::enum()`` were added. These validation + methods simplify validating backed enum values. From d557b5ec3e0678ca82274cc62c7b9c2d36195226 Mon Sep 17 00:00:00 2001 From: Alberto Rodriguez Date: Sat, 21 Oct 2023 14:08:38 -0400 Subject: [PATCH 063/337] lang: /es/console-commands/* --- es/console-commands/cache.rst | 14 + es/console-commands/commands.rst | 547 +++++++++++++++++++++++++ es/console-commands/completion.rst | 182 ++++++++ es/console-commands/cron-jobs.rst | 49 +++ es/console-commands/i18n.rst | 102 +++++ es/console-commands/input-output.rst | 369 +++++++++++++++++ es/console-commands/option-parsers.rst | 379 +++++++++++++++++ es/console-commands/plugin.rst | 67 +++ es/console-commands/repl.rst | 46 +++ es/console-commands/routes.rst | 39 ++ es/console-commands/schema-cache.rst | 30 ++ es/console-commands/server.rst | 30 ++ 12 files changed, 1854 insertions(+) create mode 100644 es/console-commands/cache.rst create mode 100644 es/console-commands/commands.rst create mode 100644 es/console-commands/completion.rst create mode 100644 es/console-commands/cron-jobs.rst create mode 100644 es/console-commands/i18n.rst create mode 100644 es/console-commands/input-output.rst create mode 100644 es/console-commands/option-parsers.rst create mode 100644 es/console-commands/plugin.rst create mode 100644 es/console-commands/repl.rst create mode 100644 es/console-commands/routes.rst create mode 100644 es/console-commands/schema-cache.rst create mode 100644 es/console-commands/server.rst diff --git a/es/console-commands/cache.rst b/es/console-commands/cache.rst new file mode 100644 index 0000000000..a44a002be6 --- /dev/null +++ b/es/console-commands/cache.rst @@ -0,0 +1,14 @@ +Herramienta de caché +#################### + +Para ayudarlo a administrar mejor los datos almacenados en caché desde un entorno CLI, un comando de consola +está disponible para borrar los datos almacenados en caché que tiene su aplicación:: + + // Borrar una configuración de caché + bin/cake cache clear + + // Borrar todas las configuraciones de caché + bin/cake cache clear_all + + // Borrar un grupo de caché + bin/cake cache clear_group diff --git a/es/console-commands/commands.rst b/es/console-commands/commands.rst new file mode 100644 index 0000000000..a5e7d14d31 --- /dev/null +++ b/es/console-commands/commands.rst @@ -0,0 +1,547 @@ +Objetos de comando +################## + +.. php:namespace:: Cake\Console +.. php:class:: Command + +CakePHP viene con una serie de comandos integrados para acelerar tu desarrollo y automatización de tareas rutinarias. +Puede utilizar estas mismas bibliotecas para crear comandos para su aplicación y complementos. + +Creando un comando +================== + +Creemos nuestro primer comando. Para este ejemplo, crearemos un comando simple Hola mundo. En el directorio +**src/Command** de su aplicación, cree **HelloCommand.php**. Coloca el siguiente código dentro:: + + out('Hello world.'); + + return static::CODE_SUCCESS; + } + } + +Las clases de comando deben implementar un método ``execute()`` que haga la mayor parte del trabajo. Este método se +llama cuando se invoca un comando. Llamemos a nuestro primer comando de aplicación, ejecute:: + +.. code-block:: console + + bin/cake hello + +Debería ver el siguiente resultado:: + + Hello world. + +Nuestro método ``execute()`` no es muy interesante, leamos algunas entradas desde la línea de comando:: + + addArgument('name', [ + 'help' => 'What is your name', + ]); + return $parser; + } + + public function execute(Arguments $args, ConsoleIo $io): int + { + $name = $args->getArgument('name'); + $io->out("Hello {$name}."); + + return static::CODE_SUCCESS; + } + } + + +Después de guardar este archivo, debería poder ejecutar el siguiente comando:: + +.. code-block:: console + + bin/cake hello jillian + + # Outputs + Hello jillian + +Cambiar el nombre del comando predeterminado +============================================ + +CakePHP usará convenciones para generar el nombre que usan sus comandos en la línea de comando. Si desea sobrescribir +el nombre generado, implemente el método ``defaultName()`` en tu comando:: + + public static function defaultName(): string + { + return 'oh_hi'; + } + +Lo anterior haría que nuestro ``HelloCommand`` fuera accesible mediante ``cake oh_hi`` en lugar de ``cake hello``. + +Definición de argumentos y opciones +=================================== + +Como vimos en el último ejemplo, podemos usar el método ``buildOptionParser()`` para definir argumentos. También +podemos definir opciones. Por ejemplo, podríamos agregar una opción ``yell`` a nuestro ``HelloCommand``:: + + // ... + protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser + { + $parser + ->addArgument('name', [ + 'help' => 'What is your name', + ]) + ->addOption('yell', [ + 'help' => 'Shout the name', + 'boolean' => true, + ]); + + return $parser; + } + + public function execute(Arguments $args, ConsoleIo $io): int + { + $name = $args->getArgument('name'); + if ($args->getOption('yell')) { + $name = mb_strtoupper($name); + } + $io->out("Hello {$name}."); + + return static::CODE_SUCCESS; + } + +Consulte la sección :doc:`/console-commands/option-parsers` para obtener más información. + +Creando la salida +================= + +Los comandos proporcionan la instancia ``ConsoleIo`` cuando se ejecutan. Este objeto le permite interactuar con +``stdout``, ``stderr`` y crear archivos. Consulte la sección :doc:`/console-commands/input-output` para obtener +más información. + +Usar modelos en comandos +======================== + +Utilice modelos en comandos. A menudo necesitará acceso a la lógica de negocio de su aplicación en los comandos +de la consola. Puede cargar modelos en comandos, tal como lo haría en un controlador usando ``$this->fetchTable()`` +ya que el comando usa ``LocatorAwareTrait``:: + + addArgument('name', [ + 'help' => 'What is your name' + ]); + + return $parser; + } + + public function execute(Arguments $args, ConsoleIo $io): int + { + $name = $args->getArgument('name'); + $user = $this->fetchTable()->findByUsername($name)->first(); + + $io->out(print_r($user, true)); + + return static::CODE_SUCCESS; + } + } + +El comando anterior buscará un usuario por nombre de usuario y mostrará la información almacenada en la base de datos. + +Códigos de salida y detención de la ejecución +============================================= + +Cuando sus comandos alcanzan un error irrecuperable, puede utilizar el método ``abort()`` para finalizar la ejecución:: + + // ... + public function execute(Arguments $args, ConsoleIo $io): int + { + $name = $args->getArgument('name'); + if (strlen($name) < 5) { + // Detener la ejecución, enviar a stderr y establecer el código de salida en 1 + $io->error('Name must be at least 4 characters long.'); + $this->abort(); + } + + return static::CODE_SUCCESS; + } + +También puedes usar ``abort()`` en el objeto ``$io`` para emitir un mensaje y código:: + + public function execute(Arguments $args, ConsoleIo $io): int + { + $name = $args->getArgument('name'); + if (strlen($name) < 5) { + // Detener la ejecución, enviar a stderr y establecer el código de salida en 99 + $io->abort('Name must be at least 4 characters long.', 99); + } + + return static::CODE_SUCCESS; + } + +Puede pasar cualquier código de salida que desee a ``abort()``. + +.. tip:: + + Evite los códigos de salida 64 - 78, ya que tienen significados específicos descritos por ``sysexits.h``. + Evite los códigos de salida superiores a 127, ya que se utilizan para indicar la salida del proceso mediante + una señal, como SIGKILL o SIGSEGV. + + Puede leer más sobre los códigos de salida convencionales en la página del manual de sysexit en la mayoría de + los sistemas Unix (``man sysexits``), o en la página de ayuda ``Códigos de error del sistema`` en Windows. + +Llamar a otros comandos +====================== + +Es posible que necesite llamar a otros comandos desde tu comando. Puedes usar ``executeCommand`` para hacer eso:: + + // Puede pasar una variedad de opciones y argumentos de CLI. + $this->executeCommand(OtherCommand::class, ['--verbose', 'deploy']); + + // Puede pasar una instancia del comando si tiene argumentos de constructor + $command = new OtherCommand($otherArgs); + $this->executeCommand($command, ['--verbose', 'deploy']); + +.. note:: + + Al llamar a ``executeCommand()`` en un bucle, se recomienda pasar la instancia ``ConsoleIo`` del comando principal + como tercer argumento opcional para evitar un posible límite de "archivos abiertos" que podría ocurrir en algunos + entornos. + +Configurando descripción del comando +==================================== + +Es posible que desee establecer una descripción de comando a través de:: + + class UserCommand extends Command + { + public static function getDescription(): string + { + return 'My custom description'; + } + } + +Esto mostrará la descripción en Cake CLI: + +.. code-block:: console + + bin/cake + + App: + - user + └─── My custom description + +Así como en la sección de ayuda de tu comando: + +.. code-block:: console + + cake user --help + My custom description + + Usage: + cake user [-h] [-q] [-v] + +.. _console-integration-testing: + +Pruebas de comandos +=================== + +Para facilitar las pruebas de aplicaciones de consola, CakePHP viene con un rasgo (trait) +``ConsoleIntegrationTestTrait`` que puede usarse para probar aplicaciones de consola y comparar sus resultados. + +Para comenzar a probar su aplicación de consola, cree un caso de prueba que utilice el rasgo +``Cake\TestSuite\ConsoleIntegrationTestTrait``. Este rasgo contiene un método ``exec()`` que se utiliza +para ejecutar su comando. Puede pasar la misma cadena que usaría en la CLI a este método. + +.. note:: + + Para CakePHP 4.4 en adelante, se debe utilizar el espacio de nombres + ``Cake\Console\TestSuite\ConsoleIntegrationTestTrait``. + +Comencemos con un comando muy simple, ubicado en **src/Command/UpdateTableCommand.php**:: + + namespace App\Command; + + use Cake\Command\Command; + use Cake\Console\Arguments; + use Cake\Console\ConsoleIo; + use Cake\Console\ConsoleOptionParser; + + class UpdateTableCommand extends Command + { + protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser + { + $parser->setDescription('My cool console app'); + + return $parser; + } + } + +Para escribir una prueba de integración para este comando, crearíamos un caso de prueba en +**tests/TestCase/Command/UpdateTableTest.php** que use el rasgo ``Cake\TestSuite\ConsoleIntegrationTestTrait``. +Este comando no hace mucho por el momento, pero probemos que la descripción de nuestro comando +se muestre en ``stdout``:: + + namespace App\Test\TestCase\Command; + + use Cake\TestSuite\ConsoleIntegrationTestTrait; + use Cake\TestSuite\TestCase; + + class UpdateTableCommandTest extends TestCase + { + use ConsoleIntegrationTestTrait; + + public function testDescriptionOutput() + { + $this->exec('update_table --help'); + $this->assertOutputContains('My cool console app'); + } + } + +¡Nuestra prueba pasa! Si bien este es un ejemplo muy trivial, muestra que la creación de un caso de +prueba de integración para aplicaciones de consola puede seguir las convenciones de la línea de comandos. +Sigamos agregando más lógica a nuestro comando:: + + namespace App\Command; + + use Cake\Command\Command; + use Cake\Console\Arguments; + use Cake\Console\ConsoleIo; + use Cake\Console\ConsoleOptionParser; + use Cake\I18n\DateTime; + + class UpdateTableCommand extends Command + { + protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser + { + $parser + ->setDescription('My cool console app') + ->addArgument('table', [ + 'help' => 'Table to update', + 'required' => true + ]); + + return $parser; + } + + public function execute(Arguments $args, ConsoleIo $io): int + { + $table = $args->getArgument('table'); + $this->fetchTable($table)->updateQuery() + ->set([ + 'modified' => new DateTime() + ]) + ->execute(); + + return static::CODE_SUCCESS; + } + } + +Este es un comando más completo que tiene opciones requeridas y lógica relevante. +Modifique su caso de prueba al siguiente fragmento de código:: + + namespace Cake\Test\TestCase\Command; + + use Cake\Command\Command; + use Cake\I18n\DateTime; + use Cake\TestSuite\ConsoleIntegrationTestTrait; + use Cake\TestSuite\TestCase; + + class UpdateTableCommandTest extends TestCase + { + use ConsoleIntegrationTestTrait; + + protected $fixtures = [ + // Se supone que tienes un UsersFixture + 'app.Users', + ]; + + public function testDescriptionOutput() + { + $this->exec('update_table --help'); + $this->assertOutputContains('My cool console app'); + } + + public function testUpdateModified() + { + $now = new DateTime('2017-01-01 00:00:00'); + DateTime::setTestNow($now); + + $this->loadFixtures('Users'); + + $this->exec('update_table Users'); + $this->assertExitCode(Command::CODE_SUCCESS); + + $user = $this->getTableLocator()->get('Users')->get(1); + $this->assertSame($user->modified->timestamp, $now->timestamp); + + DateTime::setTestNow(null); + } + } + +Como puede ver en el método ``testUpdateModified``, estamos probando que nuestro comando actualice +la tabla que pasamos como primer argumento. Primero, afirmamos que el comando salió con el código +de estado adecuado, ``0``. Luego verificamos que nuestro comando hizo su trabajo, es decir, actualizamos +la tabla que proporcionamos y configuramos la columna ``modificada`` a la hora actual. + +Recuerde, ``exec()`` tomará la misma cadena que escriba en su CLI, por lo que puede incluir +opciones y argumentos en su cadena de comando. + +Prueba de shells interactivos +----------------------------- + +Las consolas suelen ser interactivas. Probar comandos interactivos con el rasgo +``Cake\TestSuite\ConsoleIntegrationTestTrait`` solo requiere pasar las entradas que espera como segundo +parámetro de ``exec()``. Deben incluirse como una matriz en el orden esperado. + +Continuando con nuestro comando de ejemplo, agreguemos una confirmación interactiva. +Actualice la clase de comando a lo siguiente:: + + namespace App\Command; + + use Cake\Command\Command; + use Cake\Console\Arguments; + use Cake\Console\ConsoleIo; + use Cake\Console\ConsoleOptionParser; + use Cake\I18n\DateTime; + + class UpdateTableCommand extends Command + { + protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser + { + $parser + ->setDescription('My cool console app') + ->addArgument('table', [ + 'help' => 'Table to update', + 'required' => true + ]); + + return $parser; + } + + public function execute(Arguments $args, ConsoleIo $io): int + { + $table = $args->getArgument('table'); + if ($io->ask('Are you sure?', 'n', ['y', 'n']) !== 'y') { + $io->error('You need to be sure.'); + $this->abort(); + } + $this->fetchTable($table)->updateQuery() + ->set([ + 'modified' => new DateTime() + ]) + ->execute(); + + return static::CODE_SUCCESS; + } + } + +Ahora que tenemos un subcomando interactivo, podemos agregar un caso de prueba que pruebe que recibimos +la respuesta adecuada y otro que pruebe que recibimos una respuesta incorrecta. +Elimine el método ``testUpdateModified`` y agregue los siguientes métodos a +**tests/TestCase/Command/UpdateTableCommandTest.php**:: + + + public function testUpdateModifiedSure() + { + $now = new DateTime('2017-01-01 00:00:00'); + DateTime::setTestNow($now); + + $this->loadFixtures('Users'); + + $this->exec('update_table Users', ['y']); + $this->assertExitCode(Command::CODE_SUCCESS); + + $user = $this->getTableLocator()->get('Users')->get(1); + $this->assertSame($user->modified->timestamp, $now->timestamp); + + DateTime::setTestNow(null); + } + + public function testUpdateModifiedUnsure() + { + $user = $this->getTableLocator()->get('Users')->get(1); + $original = $user->modified->timestamp; + + $this->exec('my_console best_framework', ['n']); + $this->assertExitCode(Command::CODE_ERROR); + $this->assertErrorContains('You need to be sure.'); + + $user = $this->getTableLocator()->get('Users')->get(1); + $this->assertSame($original, $user->timestamp); + } + +En el primer caso de prueba, confirmamos la pregunta y se actualizan los registros. En la segunda prueba +no confirmamos y los registros no se actualizan, y podemos verificar que nuestro mensaje de error +fue escrito en ``stderr``. + +Metodos de aserción +----------------- + +El rasgo ``Cake\TestSuite\ConsoleIntegrationTestTrait`` proporciona una serie de métodos de aserción +que ayudan a afirmar contra la salida de la consola:: + + // afirmar que el comando salió con éxito + $this->assertExitSuccess(); + + // afirmar que el comando salió como un error + $this->assertExitError(); + + // afirmar que el comando salió con el código esperado + $this->assertExitCode($expected); + + // afirmar que la salida estándar contiene un texto + $this->assertOutputContains($expected); + + // afirmar que stderr contiene una texto + $this->assertErrorContains($expected); + + // afirmar que la salida estándar coincide con una expresión regular + $this->assertOutputRegExp($expected); + + // afirmar que stderr coincide con una expresión regular + $this->assertErrorRegExp($expected); + +Ciclo de vida de las devoluciones de llamada +=================== + +Al igual que los controladores, los comandos ofrecen eventos de ciclo de vida que le permiten observar +el marco que llama al código de su aplicación. Los comandos tienen: + +- ``Command.beforeExecute`` Se llama antes que el método ``execute()`` de un comando. + Al evento se le pasa el parámetro ``ConsoleArguments`` como ``args``. + Este evento no se puede detener ni reemplazar su resultado. +- ``Command.afterExecute`` Se llama después de que se completa el método ``execute()`` + de un comando. El evento contiene ``ConsoleArguments`` como ``args`` y el resultado + del comando como ``result``. Este evento no se puede detener ni reemplazar su resultado. diff --git a/es/console-commands/completion.rst b/es/console-commands/completion.rst new file mode 100644 index 0000000000..ab7e6dd530 --- /dev/null +++ b/es/console-commands/completion.rst @@ -0,0 +1,182 @@ +Herramienta de completación +################ + +Trabajar con la consola le brinda al desarrollador muchas posibilidades, pero tener que conocer y escribir +completamente esos comandos puede resultar tedioso. Especialmente cuando se desarrollan nuevos shells donde +los comandos difieren por minuto de iteración. Completion Shells ayuda en este asunto al proporcionar una +API para escribir scripts de completación para shells como bash, zsh, fish, etc. + +Sub Comandos +============ + +El Shell de completación consta de varios subcomandos para ayudar al desarrollador a crear su script +de finalización. Cada uno para un paso diferente en el proceso de autocompletar. + +Comandos +-------- + +Para los comandos del primer paso, se generan los comandos de Shell disponibles, incluido el nombre del +complemento cuando corresponda. (Todas las posibilidades devueltas, para este y otros subcomandos, están +separadas por un espacio). Por ejemplo:: + + bin/cake Completion commands + +Regresará:: + + acl api bake command_list completion console i18n schema server test testsuite upgrade + +Su secuencia de comandos de completación puede seleccionar los comandos relevantes de esa lista para continuar. +(Para este y los siguientes subcomandos). + +subcomandos +----------- + +Una vez que se ha elegido el comando preferido, los subCommands entran como segundo paso y generan +el posible subcomando para el comando de shell dado. Por ejemplo:: + + bin/cake Completion subcommands bake + +Regresará:: + + controller db_config fixture model plugin project test view + +opciones +-------- + +Como tercera y última opción, genera opciones para el (sub)comando dado, tal como se establece en getOptionParser. +(Incluidas las opciones predeterminadas heredadas de Shell). +Por ejemplo:: + + bin/cake Completion options bake + +Regresará:: + + --help -h --verbose -v --quiet -q --everything --connection -c --force -f --plugin -p --prefix --theme -t + +También puede pasar un argumento adicional que sea el subcomando del shell: generará las opciones +específicas de este subcomando. + +Cómo habilitar el autocompletado de Bash para la consola CakePHP +================================================================ + +Primero, asegúrese de que la biblioteca **bash-completion** esté instalada. +Si no, lo haces con el siguiente comando:: + + apt-get install bash-completion + +Cree un archivo llamado **cake** en **/etc/bash_completion.d/** y coloque el +:ref:`bash-completion-file-content` dentro de él. + +Guarde el archivo y luego reinicie su consola. + +.. note:: + + Si está utilizando MacOS X, puede instalar la biblioteca **bash-completion** usando **homebrew** + con el comando ``brew install bash-completion``. + El directorio de destino para el archivo **cake** será **/usr/local/etc/bash_completion.d/**. + +.. _bash-completion-file-content: + +Contenido del archivo de completación de Bash +---------------------------- + +Este es el código que debes colocar dentro del archivo **cake** en la ubicación correcta para obtener el autocompletado al usar la consola CakePHP: + +.. code-block:: bash + + # + # Bash completion file for CakePHP console + # + + _cake() + { + local cur prev opts cake + COMPREPLY=() + cake="${COMP_WORDS[0]}" + cur="${COMP_WORDS[COMP_CWORD]}" + prev="${COMP_WORDS[COMP_CWORD-1]}" + + if [[ "$cur" == -* ]] ; then + if [[ ${COMP_CWORD} = 1 ]] ; then + opts=$(${cake} Completion options) + elif [[ ${COMP_CWORD} = 2 ]] ; then + opts=$(${cake} Completion options "${COMP_WORDS[1]}") + else + opts=$(${cake} Completion options "${COMP_WORDS[1]}" "${COMP_WORDS[2]}") + fi + + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + return 0 + fi + + if [[ ${COMP_CWORD} = 1 ]] ; then + opts=$(${cake} Completion commands) + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + return 0 + fi + + if [[ ${COMP_CWORD} = 2 ]] ; then + opts=$(${cake} Completion subcommands $prev) + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + if [[ $COMPREPLY = "" ]] ; then + _filedir + return 0 + fi + return 0 + fi + + opts=$(${cake} Completion fuzzy "${COMP_WORDS[@]:1}") + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + if [[ $COMPREPLY = "" ]] ; then + _filedir + return 0 + fi + return 0; + } + + complete -F _cake cake bin/cake + +Usando el autocompletado +======================== + +Una vez habilitado, el autocompletado se puede usar de la misma manera que para otros comandos integrados, +usando la tecla **TAB**. +Se proporcionan tres tipos de autocompletado. El siguiente resultado proviene de una nueva instalación de CakePHP. + +Comandos +-------- + +Salida de muestra para comandos de autocompletar: + +.. code-block:: console + + $ bin/cake + bake i18n schema_cache routes + console migrations plugin server + +Subcomandos +----------- + +Salida de muestra para el autocompletado de subcomandos: + +.. code-block:: console + + $ bin/cake bake + behavior helper command + cell mailer command_helper + component migration template + controller migration_snapshot test + fixture model + form plugin + +Opciones +-------- + +Salida de muestra para el autocompletado de opciones de subcomandos: + +.. code-block:: console + + $ bin/cake bake - + -c --everything --force --help --plugin -q -t -v + --connection -f -h -p --prefix --quiet --theme --verbose + diff --git a/es/console-commands/cron-jobs.rst b/es/console-commands/cron-jobs.rst new file mode 100644 index 0000000000..858af21361 --- /dev/null +++ b/es/console-commands/cron-jobs.rst @@ -0,0 +1,49 @@ +Ejecutar shells como trabajos cron +################################## + +Una cosa común que se puede hacer con un shell es ejecutarlo como un cronjob para limpiar la base de datos +de vez en cuando o enviar boletines. Esto es trivial de configurar, por ejemplo:: + + */5 * * * * cd /full/path/to/root && bin/cake myshell myparam + # * * * * * command to execute + # │ │ │ │ │ + # │ │ │ │ │ + # │ │ │ │ \───── day of week (0 - 6) (0 to 6 are Sunday to Saturday, + # | | | | or use names) + # │ │ │ \────────── month (1 - 12) + # │ │ \─────────────── day of month (1 - 31) + # │ \──────────────────── hour (0 - 23) + # \───────────────────────── min (0 - 59) + +Puedes ver más información aquí: https://es.wikipedia.org/wiki/Cron_(Unix) + +.. tip:: + + Utilice ``-q`` (o `--quiet`) para silenciar cualquier salida de cronjobs. + +Trabajos cron en hosting compartido +----------------------------------- + +En algunos hosting compartidos ``cd /full/path/to/root && bin/cake mycommand myparam`` +Puede que no funcione. En su lugar puedes usar +``php /full/path/to/root/bin/cake.php mycomando myparam``. + +.. note:: + + register_argc_argv has to be turned on by including ``register_argc_argv + = 1`` in your php.ini. If you cannot change register_argc_argv globally, + you can tell the cron job to use your own configuration by + specifying it with ``-d register_argc_argv=1`` parameter. Example: ``php + -d register_argc_argv=1 /full/path/to/root/bin/cake.php myshell + myparam`` + + register_argc_argv debe activarse incluyendo ``register_argc_argv = 1`` + en su php.ini. Si no puede cambiar register_argc_argv globalmente, puede + indicarle al trabajo cron que use su propia configuración especificándola + con el parámetro ``-d register_argc_argv=1``. + Ejemplo: ``php -d register_argc_argv=1 /full/path/to/root/bin/cake.php myshell + myparam`` + +.. meta:: + :title lang=es: Ejecutar shells como trabajos cron + :keywords lang=es: cronjob,bash script,crontab diff --git a/es/console-commands/i18n.rst b/es/console-commands/i18n.rst new file mode 100644 index 0000000000..0bee4f8b03 --- /dev/null +++ b/es/console-commands/i18n.rst @@ -0,0 +1,102 @@ +Herramienta de internacionalización (i18n) +######### + +Las características i18n de CakePHP usan `archivos po `_ +como fuente de traducción. Los archivos PO se integran con herramientas de traducción de uso común +como `Poedit `_. + +Los comandos i18n proporcionan una forma rápida de generar archivos de plantilla po. +Estos archivos de plantilla luego se pueden entregar a los traductores para que puedan +traducir los textos en su aplicación. Una vez que haya terminado las traducciones, +los archivos pueden ser fusionados con traducciones existentes para ayudar a actualizar sus traducciones. + +Generando archivos POT +====================== + +POT files can be generated for an existing application using the ``extract`` +command. This command will scan your entire application for ``__()`` style +function calls, and extract the message string. Each unique string in your +application will be combined into a single POT file: + +Los archivos POT se pueden generar para una aplicación existente usando el +comando ``extract``. Este comando escaneará toda su aplicación en busca de +llamadas a funciones de estilo ``__()`` y extraerá la cadena del mensaje. +Cada cadena única en su aplicación se combinará en un único archivo POT: + +.. code-block:: console + + bin/cake i18n extract + +Lo anterior ejecutará el comando de extracción. El resultado de este comando será +el archivo **resources/locales/default.pot**. Utilice el archivo pot como plantilla +para crear archivos po. Si está creando archivos po manualmente a partir del +archivo pot, asegúrese de configurar correctamente la línea de encabezado ``Plural-Forms``. + +Generando archivos POT para complementos +-------------------------------- + +Puede generar un archivo POT para un complemento específico usando: + +.. code-block:: console + + bin/cake i18n extract --plugin + +Esto generará los archivos POT necesarios utilizados en los complementos. + +Extraer de varias carpetas a la vez +----------------------------------- + +A veces, es posible que necesites extraer textos de más de un directorio de tu +aplicación. Por ejemplo, si está definiendo algunas cadenas en el directorio +``config`` de su aplicación, probablemente desee extraer textos de este directorio +así como del directorio ``src``. Puedes hacerlo usando la opción ``--paths``. +Se necesita una lista de rutas absolutas separadas por comas para extraer: + +.. code-block:: console + + bin/cake i18n extract --paths /var/www/app/config,/var/www/app/src + +Excluyendo carpetas +------------------- + +Puede pasar una lista separada por comas de las carpetas que desea excluir. +Se ignorará cualquier ruta que contenga un segmento de ruta con los valores +proporcionados: + +.. code-block:: console + + bin/cake i18n extract --exclude vendor,tests + +Omitir advertencias de sobrescritura para archivos POT existentes +----------------------------------------------------------------- + +Al agregar ``--overwrite``, el script de shell ya no le advertirá si ya existe +un archivo POT y lo sobrescribirá de forma predeterminada: + +.. code-block:: console + + bin/cake i18n extract --overwrite + +Extracción de mensajes de las bibliotecas principales de CakePHP +---------------------------------------------------------------- + +By default, the extract shell script will ask you if you like to extract +the messages used in the CakePHP core libraries. Set ``--extract-core`` to yes +or no to set the default behavior: + +orma predeterminada, el script de extracción le preguntará si desea extraer +los mensajes utilizados en las bibliotecas principales de CakePHP. +Configure ``--extract-core`` en sí o no para establecer el comportamiento +predeterminado: + +.. code-block:: console + + bin/cake i18n extract --extract-core yes + + // or + + bin/cake i18n extract --extract-core no + +.. meta:: + :title lang=es: Herramienta de internacionalización (i18n) + :keywords lang=es: pot files,locale default,translation tools,message string,app locale,php class,validation,i18n,translations,command,models diff --git a/es/console-commands/input-output.rst b/es/console-commands/input-output.rst new file mode 100644 index 0000000000..1aaf81443f --- /dev/null +++ b/es/console-commands/input-output.rst @@ -0,0 +1,369 @@ +Comandos Entrada/Salida (Input/Output) +#################### + +.. php:namespace:: Cake\Console +.. php:class:: ConsoleIo + +CakePHP proporciona el objeto ``ConsoleIo`` a los comandos para que puedan +leer interactivamente la información de entrada y salida del usuario. + +.. _command-helpers: + +Ayudantes de comando (Helpers) +=============== + +Se puede acceder y utilizar los ayudantes (helpers) de comandos desde cualquier comando:: + + // Generar algunos datos como una tabla.. + $io->helper('Table')->output($data); + + // Obtenga una ayuda de un complemento. + $io->helper('Plugin.HelperName')->output($data); + +También puede obtener instancias de ayudantes y llamar a cualquier método público sobre ellos:: + + // Obtenga y utilice Progress Helper. + $progress = $io->helper('Progress'); + $progress->increment(10); + $progress->draw(); + +Creando ayudantes +================ + +Si bien CakePHP viene con algunos comandos auxiliares, puedes crear más en tu +aplicación o complementos. Como ejemplo, crearemos un asistente simple para +generar encabezados sofisticados. Primero cree +**src/Command/Helper/HeadingHelper.php** y coloque lo siguiente en él:: + + _io->out($marker . ' ' . $args[0] . ' ' . $marker); + } + } + +Luego podemos usar este nuevo asistente en uno de nuestros comandos de +shell llamándolo:: + + // Con ### a cada lado + $this->helper('Heading')->output(['It works!']); + + // Con ~~~~ a cada lado + $this->helper('Heading')->output(['It works!', '~', 4]); + +Los ayudantes generalmente implementan el método ``output()`` que toma una serie +de parámetros. Sin embargo, debido a que los Console Helpers son clases básicas, +pueden implementar métodos adicionales que toman cualquier forma de argumentos. + +.. note:: + Los ayudantes también pueden vivir en ``src/Shell/Helper`` para + compatibilidad con versiones anteriores. + +Ayudantes incorporados +====================== + +Table Helper +------------ + +TableHelper ayuda a crear tablas artísticas ASCII bien formateadas. +Usarlo es bastante simple:: + + $data = [ + ['Header 1', 'Header', 'Long Header'], + ['short', 'Longish thing', 'short'], + ['Longer thing', 'short', 'Longest Value'], + ]; + $io->helper('Table')->output($data); + + // Outputs + +--------------+---------------+---------------+ + | Header 1 | Header | Long Header | + +--------------+---------------+---------------+ + | short | Longish thing | short | + | Longer thing | short | Longest Value | + +--------------+---------------+---------------+ + +Puede utilizar la etiqueta de formato ```` en las tablas para +alinear el contenido a la derecha:: + + $data = [ + ['Name', 'Total Price'], + ['Cake Mix', '1.50'], + ]; + $io->helper('Table')->output($data); + + // Outputs + +----------+-------------+ + | Name 1 | Total Price | + +----------+-------------+ + | Cake Mix | 1.50 | + +----------+-------------+ + +Progress Helper +--------------- + +ProgressHelper se puede utilizar de dos maneras diferentes. El modo simple +le permite proporcionar una devolución de llamada que se invoca hasta que +se completa el progreso:: + + $io->helper('Progress')->output(['callback' => function ($progress) { + // Funciona aqui + $progress->increment(20); + $progress->draw(); + }]); + +Puede controlar más la barra de progreso proporcionando opciones adicionales: + +- ``total`` El número total de elementos en la barra de progreso. + El valor predeterminado es 100. +- ``width`` El ancho de la barra de progreso. El valor predeterminado es 80. +- ``callback`` La devolución de llamada que se llamará en un bucle para avanzar + en la barra de progreso. + +Un ejemplo de todas las opciones en uso sería:: + + $io->helper('Progress')->output([ + 'total' => 10, + 'width' => 20, + 'callback' => function ($progress) { + $progress->increment(2); + $progress->draw(); + } + ]); + +El asistente de progreso también se puede utilizar manualmente para incrementar +y volver a representar la barra de progreso según sea necesario:: + + $progress = $io->helper('Progress'); + $progress->init([ + 'total' => 10, + 'width' => 20, + ]); + + $progress->increment(4); + $progress->draw(); + + +Obtener información del usuario +=============================== + +.. php:method:: ask($question, $choices = null, $default = null) + +Al crear aplicaciones de consola interactivas, necesitará obtener información +del usuario. CakePHP proporciona una manera de hacer esto:: + + // Obtenga texto arbitrario del usuario. + $color = $io->ask('What color do you like?'); + + // Obtenga una opción del usuario. + $selection = $io->askChoice('Red or Green?', ['R', 'G'], 'R'); + +La validación de la selección no distingue entre mayúsculas y minúsculas. + +Creando archivos +================ + +.. php:method:: createFile($path, $contents) + +La creación de archivos suele ser una parte importante de muchos comandos de +consola que ayudan a automatizar el desarrollo y la implementación. +El método ``createFile()`` le brinda una interfaz simple para crear archivos +con confirmación interactiva:: + + // Crear un archivo con confirmación de sobrescritura + $io->createFile('bower.json', $stuff); + + // Forzar sobrescritura sin preguntar + $io->createFile('bower.json', $stuff, true); + +Creando salidas (Output) +=============== + +.. php:method:out($message, $newlines, $level) +.. php:method:err($message, $newlines) + +Escribir en ``stdout`` y ``stderr`` es otra operación común en CakePHP:: + + // Escribir a stdout + $io->out('Normal message'); + + // Escribir a stderr + $io->err('Error message'); + +Además de los métodos de salida básicos, CakePHP proporciona métodos envolventes +que diseñan la salida con colores ANSI apropiados: + + // Texto verde en stdout + $io->success('Success message'); + + // Texto cian en stdout + $io->info('Informational text'); + + // Texto azul en stdout + $io->comment('Additional context'); + + // Texto rojo en stderr + $io->error('Error text'); + + // Texto amarillo en stderr + $io->warning('Warning text'); + +El formato de color se desactivará automáticamente si ``posix_isatty`` devuelve +verdadero o si se establece la variable de entorno ``NO_COLOR``. + +``ConsoleIo`` proporciona dos métodos convenientes con respecto al nivel +de salida:: + + // Solo aparecerá cuando la salida detallada esté habilitada (-v) + $io->verbose('Verbose message'); + + // Aparecería en todos los niveles. + $io->quiet('Quiet message'); + +También puedes crear líneas en blanco o dibujar líneas de guiones:: + + // Salida 2 nuevas líneas + $io->out($io->nl(2)); + + // Dibuja una línea horizontal + $io->hr(); + +Por último, puede actualizar la línea de texto actual en la pantalla:: + + $io->out('Counting down'); + $io->out('10', 0); + for ($i = 9; $i > 0; $i--) { + sleep(1); + $io->overwrite($i, 0, 2); + } + +.. note:: + Es importante recordar que no puede sobrescribir texto una vez + que se ha generado una nueva línea. + +.. _shell-output-level: + +Niveles de salida +================= + +Las aplicaciones de consola a menudo necesitan diferentes niveles de detalle. +Por ejemplo, cuando se ejecuta como una tarea cron, la mayor parte del resultado +es innecesario. Puede utilizar niveles de salida para marcar la salida de forma +adecuada. El usuario del shell puede entonces decidir qué nivel de detalle le +interesa configurando el indicador correcto al llamar al comando. Hay 3 niveles: + +* ``QUIET`` - Sólo la información absolutamente importante debe marcarse para + una salida silenciosa. +* ``NORMAL`` - El nivel predeterminado y el uso normal. +* ``VERBOSE`` - Marque los mensajes que pueden ser demasiado ruidosos para el + uso diario, pero útiles para la depuración como ``VERBOSE``. + +Puede marcar la salida de la siguiente manera:: + + // Aparecería en todos los niveles. + $io->out('Quiet message', 1, ConsoleIo::QUIET); + $io->quiet('Quiet message'); + + // No aparecería cuando se alterna la salida silenciosa. + $io->out('normal message', 1, ConsoleIo::NORMAL); + $io->out('loud message', 1, ConsoleIo::VERBOSE); + $io->verbose('Verbose output'); + + // Solo aparecería cuando la salida detallada esté habilitada. + $io->out('extra message', 1, ConsoleIo::VERBOSE); + $io->verbose('Verbose output'); + +Puede controlar el nivel de salida de los comandos utilizando las opciones +``--quiet`` y ``--verbose``. Estas opciones se agregan de forma predeterminada +y le permiten controlar consistentemente los niveles de salida dentro de sus +comandos de CakePHP. + +Las opciones ``--quiet`` y ``--verbose`` también controlan cómo se envían los +datos de registro a stdout/stderr. Normalmente, la información y los mensajes de +registro superiores se envían a stdout/stderr. Cuando se utiliza ``--verbose``, +los registros de depuración se enviarán a la salida estándar. Cuando se usa +``--quiet``, solo se enviarán a stderr mensajes de advertencia y de registro +superiores. + +Estilos en salidas +================== + +El estilo de la salida se logra incluyendo etiquetas, al igual que HTML, en la +salida. Estas etiquetas se reemplazarán con la secuencia de códigos ansi +correcta o se eliminarán si estás en una consola que no admite códigos ansi. +Hay varios estilos integrados y puedes crear más. Los incorporados son + +* ``success`` Mensajes de éxito. Texto verde. +* ``error`` Mensajes de error. Texto rojo. +* ``warning`` Mensajes de advertencia. Texto amarillo. +* ``info`` Mensajes informativos. Texto cian. +* ``comment`` Texto adicional. Texto azul. +* ``question`` Texto que es una pregunta, agregado automáticamente por shell. + +Puede crear estilos adicionales usando ``$io->setStyle()``. Para declarar un +nuevo estilo de salida que podrías hacer:: + + $io->setStyle('flashy', ['text' => 'magenta', 'blink' => true]); + +This would then allow you to use a ```` tag in your shell output, and if +ansi colours are enabled, the following would be rendered as blinking magenta +text ``$this->out('Whoooa Something went wrong');``. When +defining styles you can use the following colours for the ``text`` and +``background`` attributes: + +Esto le permitiría usar una etiqueta ```` en la salida de su shell, y si +los colores ansi están habilitados, lo siguiente se representaría como texto +magenta parpadeante ``$this->out('Whoooa Algo salió mal');``. +Al definir estilos, puede utilizar los siguientes colores para los atributos +``text`` y ``background``: + +* black +* blue +* cyan +* green +* magenta +* red +* white +* yellow + +También puede utilizar las siguientes opciones como modificadores booleanos, +configurarlas en un valor verdadero las habilita. + +* blink +* bold +* reverse +* underline + +Agregar un estilo también lo hace disponible en todas las instancias de +ConsoleOutput, por lo que no es necesario volver a declarar estilos para los +objetos stdout y stderr. + +Desactivar la coloración +===================== + +Aunque el color es bonito, puede haber ocasiones en las que desees apagarlo o forzarlo: + + $io->outputAs(ConsoleOutput::RAW); + +Lo anterior pondrá el objeto de salida en modo de salida sin formato. En el modo +de salida sin formato, no se aplica ningún estilo. Hay tres modos que puedes +usar. + +* ``ConsoleOutput::COLOR`` - Salida con códigos de escape de color implementados. +* ``ConsoleOutput::PLAIN`` - Salida de texto sin formato, las etiquetas de + estilo conocidas se eliminarán de la salida. +* ``ConsoleOutput::RAW`` - Salida sin formato, no se realizará ningún estilo ni + formato. Este es un buen modo para usar si está generando XML o desea depurar + por qué su estilo no funciona. + +De forma predeterminada, en los sistemas \*nix, los objetos ConsoleOutput tienen +una salida de color predeterminada. En los sistemas Windows, la salida simple es +la predeterminada a menos que la variable de entorno ``ANSICON`` esté presente. diff --git a/es/console-commands/option-parsers.rst b/es/console-commands/option-parsers.rst new file mode 100644 index 0000000000..a6bb97e188 --- /dev/null +++ b/es/console-commands/option-parsers.rst @@ -0,0 +1,379 @@ +Opcion de analizadores (Parsers) +############## + +.. php:namespace:: Cake\Console +.. php:class:: ConsoleOptionParser + +Las aplicaciones de consola normalmente toman opciones y argumentos como la +forma principal de obtener información del terminal en sus comandos. + +Definición de un OptionParser +======================== + +Los comandos y shells proporcionan un método de enlace +``buildOptionParser($parser)`` que puede utilizar para definir las opciones y +argumentos de sus comandos:: + + protected function buildOptionParser(ConsoleOptionParser $parser): ConsoleOptionParser + { + // Defina sus opciones y argumentos. + + // Devolver el analizador completo + return $parser; + } + +Las clases Shell usan el método de enlace ``getOptionParser()`` para definir su analizador de opciones:: + + public function getOptionParser() + { + // Obtenga un analizador vacío del marco. + $parser = parent::getOptionParser(); + + // Defina sus opciones y argumentos. + + // Devolver el analizador completo + return $parser; + } + + +Usando argumentos +================= + +.. php:method:: addArgument($name, $params = []) + +Los argumentos posicionales se utilizan con frecuencia en herramientas de línea +de comandos, y ``ConsoleOptionParser`` le permite definir argumentos +posicionales así como hacerlos obligatorios. Puede agregar argumentos uno a la +vez con ``$parser->addArgument();`` o varios a la vez con +``$parser->addArguments();``:: + + $parser->addArgument('model', ['help' => 'The model to bake']); + +Puede utilizar las siguientes opciones al crear un argumento: + +* ``help`` El texto de ayuda que se mostrará para este argumento. +* ``required`` Si este parámetro es necesario. +* ``index`` El índice del argumento, si no se define, el argumento se colocará + al final de los argumentos. Si define el mismo índice dos veces, se + sobrescribirá la primera opción. +* ``choices`` Una serie de opciones válidas para este argumento. Si se deja + vacío, todos los valores son válidos. Se generará una excepción cuando parse() + encuentre un valor no válido. + +Los argumentos que se han marcado como obligatorios generarán una excepción al +analizar el comando si se han omitido. Entonces no tienes que manejar eso en tu +shell. + +Agregar múltiples argumentos +---------------------------- + +.. php:method:: addArguments(array $args) + +Si tiene una matriz con múltiples argumentos, puede usar +``$parser->addArguments()`` para agregar múltiples argumentos a la vez. :: + + $parser->addArguments([ + 'node' => ['help' => 'The node to create', 'required' => true], + 'parent' => ['help' => 'The parent node', 'required' => true], + ]); + +Al igual que con todos los métodos de creación de ConsoleOptionParser, +addArguments se puede utilizar como parte de una cadena de métodos fluida. + +Validación de Argumentos +------------------------ + +Al crear argumentos posicionales, puede utilizar el indicador ``required`` para +indicar que un argumento debe estar presente cuando se llama a un shell.Además, +puedes usar ``choices`` para forzar que un argumento provenga de una lista de +opciones válidas:: + + $parser->addArgument('type', [ + 'help' => 'The type of node to interact with.', + 'required' => true, + 'choices' => ['aro', 'aco'], + ]); + +Lo anterior creará un argumento que es obligatorio y tiene validación en la +entrada. Si falta el argumento o tiene un valor incorrecto, se generará una +excepción y se detendrá el shell. + +Usando opciones +=============== + +.. php:method:: addOption($name, array $options = []) + +Las opciones o indicadores se utilizan en las herramientas de línea de comandos +para proporcionar argumentos clave/valor desordenados para sus comandos. Las +opciones pueden definir alias tanto detallados como cortos. Pueden aceptar un +valor (por ejemplo, ``--connection=default``) o ser opciones booleanas(por +ejemplo, ``--verbose``). Las opciones se definen con el método ``addOption()``:: + + $parser->addOption('connection', [ + 'short' => 'c', + 'help' => 'connection', + 'default' => 'default', + ]); + +Lo anterior le permitiría usar ``cake myshell --connection=other``, +``cake myshell --connection other`` o ``cake myshell -c other`` +al invocar el shell. + +Los modificadores booleanos no aceptan ni consumen valores, y su presencia +simplemente los habilita en los parámetros analizados:: + + $parser->addOption('no-commit', ['boolean' => true]); + +Esta opción, cuando se usa como ``cake mycommand --no-commit something``, +tendría un valor de ``true`` y 'something' se trataría como un argumento posicional. + +Al crear opciones, puede utilizar las siguientes opciones para definir el +comportamiento de la opción: + +* ``short`` - La variante de una sola letra para esta opción, déjela sin definir + para ninguna. +* ``help`` - Texto de ayuda para esta opción. Se utiliza al generar ayuda para + la opción. +* ``default`` - El valor predeterminado para esta opción. Si no se define, el + valor predeterminado será ``true``. +* ``boolean`` - La opción no utiliza ningún valor, es solo un modificador booleano. + El valor predeterminado es ``false``. +* ``multiple`` - La opción se puede proporcionar varias veces. La opción + analizada será una matriz de valores cuando esta opción esté habilitada. +* ``choices`` - Una serie de opciones válidas para esta opción. Si se deja + vacío, todos los valores son válidos. Se generará una excepción cuando parse() + encuentre un valor no válido. + +Agregar múltiples opciones +-------------------------- + +.. php:method:: addOptions(array $options) + +Si tiene una matriz con múltiples opciones, puede usar ``$parser->addOptions()`` +para agregar múltiples opciones a la vez. :: + + $parser->addOptions([ + 'node' => ['short' => 'n', 'help' => 'The node to create'], + 'parent' => ['short' => 'p', 'help' => 'The parent node'], + ]); + +Al igual que con todos los métodos de creación de ConsoleOptionParser, +addOptions se puede utilizar como parte de una cadena de métodos fluida. + +Validación de Opciones +---------------------- + +Las opciones pueden contar con un conjunto de opciones de manera muy similar a +como lo pueden ser los argumentos posicionales. Cuando una opción tiene opciones +definidas, esas son las únicas opciones válidas para una opción. Todos los demás +valores generarán una ``InvalidArgumentException``:: + + $parser->addOption('accept', [ + 'help' => 'What version to accept.', + 'choices' => ['working', 'theirs', 'mine'], + ]); + +Usando opciones booleanas +------------------------- + +Las opciones se pueden definir como opciones booleanas, que son útiles cuando +necesitas crear algunas opciones de bandera. Al igual que las opciones con +valores predeterminados, las opciones booleanas siempre se incluyen en los +parámetros analizados. Cuando las banderas están presentes, se establecen +``true``; cuando están ausentes, se establecen en ``false``:: + + $parser->addOption('verbose', [ + 'help' => 'Enable verbose output.', + 'boolean' => true + ]); + +La siguiente opción siempre tendría un valor en el parámetro analizado. Cuando +no se incluye, su valor predeterminado será ``false`` y, cuando se defina, +será ``true``. + +Construyendo una consola OptionParser a partir de una matriz +------------------------------------------------------------ + +.. php:method:: buildFromArray($spec) + +Como se mencionó anteriormente, al crear analizadores de opciones de subcomando, +puede definir la especificación del analizador como una matriz para ese método. +Esto puede ayudar a facilitar la creación de analizadores de subcomandos, ya que +todo es una matriz:: + + $parser->addSubcommand('check', [ + 'help' => __('Check the permissions between an ACO and ARO.'), + 'parser' => [ + 'description' => [ + __("Use this command to grant ACL permissions. Once executed, the "), + __("ARO specified (and its children, if any) will have ALLOW access "), + __("to the specified ACO action (and the ACO's children, if any)."), + ], + 'arguments' => [ + 'aro' => ['help' => __('ARO to check.'), 'required' => true], + 'aco' => ['help' => __('ACO to check.'), 'required' => true], + 'action' => ['help' => __('Action to check')], + ], + ], + ]); + +Dentro de las especificaciones del analizador, puede definir claves para +``arguments``, ``options``, ``description`` y ``epilog``. No se pueden definir +``subcommands`` dentro de un generador de estilos de matriz. Los valores de los +argumentos y las opciones deben seguir el formato :php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` y +:php:func:`Cake\\Console\\ConsoleOptionParser::addOptions( )`. También puede +utilizar buildFromArray por sí solo para crear un analizador de opciones:: + + public function getOptionParser() + { + return ConsoleOptionParser::buildFromArray([ + 'description' => [ + __("Use this command to grant ACL permissions. Once executed, the "), + __("ARO specified (and its children, if any) will have ALLOW access "), + __("to the specified ACO action (and the ACO's children, if any).") + ], + 'arguments' => [ + 'aro' => ['help' => __('ARO to check.'), 'required' => true], + 'aco' => ['help' => __('ACO to check.'), 'required' => true], + 'action' => ['help' => __('Action to check')], + ], + ]); + } + +Fusionar analizadores de opciones +--------------------------------- + +.. php:method:: merge($spec) + +Al crear un comando de grupo, es posible que desee combinar varios analizadores +para esto:: + + $parser->merge($anotherParser); + +Tenga en cuenta que el orden de los argumentos para cada analizador debe ser el +mismo y que las opciones también deben ser compatibles para que funcione. Así +que no utilices claves para cosas diferentes. + +Obtener ayuda de comandos +======================= + +Al definir sus opciones y argumentos con el analizador de opciones, CakePHP +puede generar automáticamente información de ayuda rudimentaria y agregar +``--help`` y ``-h`` a cada uno de sus comandos. El uso de una de estas opciones +le permitirá ver el contenido de ayuda generado: + +.. code-block:: console + + bin/cake bake --help + bin/cake bake -h + +Ambos generarían la ayuda para hornear. También puede obtener ayuda para +comandos anidados: + +.. code-block:: console + + bin/cake bake model --help + bin/cake bake model -h + +Lo anterior le brindará ayuda específica para el comando ``bake model``. + +Obtener ayuda como XML +---------------------- + +Al crear herramientas automatizadas o herramientas de desarrollo que necesitan +interactuar con los comandos de CakePHP, es bueno tener ayuda disponible en un +formato que la máquina pueda analizar. Al proporcionar la opción ``xml`` al +solicitar ayuda, puede obtener el contenido de la ayuda como XML: + +.. code-block:: console + + cake bake --help xml + cake bake -h xml + +Lo anterior devolvería un documento XML con la ayuda, opciones, argumentos y +subcomandos generados para el shell seleccionado. Un documento XML de muestra +se vería así: + +.. code-block:: xml + + + + bake fixture + Generate fixtures for use with the test suite. You can use + `bake fixture all` to bake all fixtures. + + Omitting all arguments and options will enter into an interactive + mode. + + + + + + + + + + + + + + + + + +Personalización de salida de la ayuda +======================= + +Puede enriquecer aún más el contenido de ayuda generado agregando una +descripción y un epílogo. + +Establecer la descripción +------------------------- + +.. php:method:: setDescription($text) + +La descripción se muestra encima de la información del argumento y la opción. +Al pasar una matriz o una cadena, puede establecer el valor de la descripción:: + + // Establecer varias líneas a la vez + $parser->setDescription(['line one', 'line two']); + + // Leer el valor actual + $parser->getDescription(); + +Establecer el epilogo +-------------- + +.. php:method:: setEpilog($text) + +Obtiene o establece el epílogo del analizador de opciones. El epílogo se muestra +después de la información del argumento y la opción. Al pasar una matriz o una +cadena, puede establecer el valor del epílogo:: + + // Establecer varias líneas a la vez + $parser->setEpilog(['line one', 'line two']); + + // Leer el valor actual + $parser->getEpilog(); diff --git a/es/console-commands/plugin.rst b/es/console-commands/plugin.rst new file mode 100644 index 0000000000..5584d0baf9 --- /dev/null +++ b/es/console-commands/plugin.rst @@ -0,0 +1,67 @@ +.. _plugin-shell: + +Herramienta de complemento (Plugin) +################################### + +La herramienta de complemento le permite cargar y descargar complementos a +través del símbolo del sistema. Si necesita ayuda, ejecute: + +.. code-block:: console + + bin/cake plugin --help + +Cargando complementos +--------------------- + +A través de la tarea ``Load`` puedes cargar complementos en tu +**config/bootstrap.php**. Puedes hacer esto ejecutando: + +.. code-block:: console + + bin/cake plugin load MyPlugin + +Esto agregará lo siguiente a su **src/Application.php**:: + + // En el método bootstrap agregue: + $this->addPlugin('MyPlugin'); + +Descarga de complementos +----------------- + +Puede descargar un complemento especificando su nombre: + +.. code-block:: console + + bin/cake plugin unload MyPlugin + +Esto eliminará la línea ``$this->addPlugin('MyPlugin',...)`` de +**src/Application.php**. + +Activos del complemento (Assets) +------------- + +CakePHP sirve de forma predeterminada recursos de complementos utilizando el +middleware ``AssetMiddleware``. Si bien esto es una buena conveniencia, se +recomienda vincular/copiar los activos del complemento en la raíz web de la +aplicación para que el servidor web pueda servirlos directamente sin invocar +PHP. Puedes hacer esto ejecutando: + +.. code-block:: console + + bin/cake plugin assets symlink + +La ejecución del comando anterior vinculará simbólicamente todos los recursos de +los complementos en la raíz web de la aplicación. En Windows, que no admite +enlaces simbólicos, los activos se copiarán en las carpetas respectivas en lugar +de tener enlaces simbólicos. + +Puede vincular simbólicamente los activos de un complemento en particular +especificando su nombre: + +.. code-block:: console + + bin/cake plugin assets symlink MyPlugin + +.. meta:: + :title lang=es: Herramienta de complemento (Plugin) + :keywords lang=es: plugin,assets,tool,load,unload,complemento,activos diff --git a/es/console-commands/repl.rst b/es/console-commands/repl.rst new file mode 100644 index 0000000000..89e17276be --- /dev/null +++ b/es/console-commands/repl.rst @@ -0,0 +1,46 @@ +Consola interactiva (REPL) +########################## + +CakePHP ofrece el complemento +`REPL (Read Eval Print Loop) `__ para +permitirle explorar algo de CakePHP y su aplicación en una consola interactiva. + +Puede iniciar la consola interactiva usando: + +.. code-block:: console + + bin/cake console + +Esto iniciará su aplicación e iniciará una consola interactiva. En este punto, +puede interactuar con el código de su aplicación y ejecutar consultas utilizando +los modelos de su aplicación: + +.. code-block:: console + + bin/cake console + + >>> $articles = Cake\Datasource\FactoryLocator::get('Table')->get('Articles'); + // object(Cake\ORM\Table)( + // + // ) + >>> $articles->find()->all(); + +Dado que su aplicación ha sido iniciada, también puede probar el enrutamiento +usando REPL:: + + >>> Cake\Routing\Router::parse('/articles/view/1'); + // [ + // 'controller' => 'Articles', + // 'action' => 'view', + // 'pass' => [ + // 0 => '1' + // ], + // 'plugin' => NULL + // ] + +También puedes probar la generación de URL:: + + >>> Cake\Routing\Router::url(['controller' => 'Articles', 'action' => 'edit', 99]); + // '/articles/edit/99' + +Para salir de REPL, puede usar ``CTRL-C`` o escribir ``exit``. diff --git a/es/console-commands/routes.rst b/es/console-commands/routes.rst new file mode 100644 index 0000000000..4df63147bf --- /dev/null +++ b/es/console-commands/routes.rst @@ -0,0 +1,39 @@ +Herramienta de enrutamiento (Routes) +########### + +La herramienta de rutas proporciona una interfaz CLI fácil de usar para probar +y depurar rutas. Puede usarlo para probar cómo se analizan las rutas y qué +parámetros de enrutamiento de URL generarán. + +Obtener una lista de todas las rutas +------------------------------------ + +.. code-block:: console + + bin/cake routes + +Prueba de análisis de URL +------------------------- + +Puedes ver rápidamente cómo se analizará una URL usando el método ``check``: + +.. code-block:: console + + bin/cake routes check /articles/edit/1 + +Si su ruta contiene algún parámetro de cadena de consulta, recuerde encerrar +la URL entre comillas: + +.. code-block:: console + + bin/cake routes check "/articles/?page=1&sort=title&direction=desc" + +Prueba de generación de URL +--------------------------- + +Puede ver la URL que generará :term:`routing array` usando el método ``generar``: + +.. code-block:: console + + bin/cake routes generate controller:Articles action:edit 1 + diff --git a/es/console-commands/schema-cache.rst b/es/console-commands/schema-cache.rst new file mode 100644 index 0000000000..38d5894e76 --- /dev/null +++ b/es/console-commands/schema-cache.rst @@ -0,0 +1,30 @@ +Herramienta de esquemas de caché (Schema Cache) +################# + +SchemaCacheShell proporciona una herramienta CLI sencilla para administrar las +cachés de metadatos de su aplicación. En situaciones de implementación, resulta +útil reconstruir la caché de metadatos in situ sin borrar los datos de la caché +existente. Puedes hacer esto ejecutando: + +.. code-block:: console + + bin/cake schema_cache build --connection default + +Esto reconstruirá el caché de metadatos para todas las tablas en la conexión +``default``. Si solo necesita reconstruir una única tabla, puede hacerlo +proporcionando su nombre: + +.. code-block:: console + + bin/cake schema_cache build --connection default articles + +Además de crear datos almacenados en caché, también puede utilizar +SchemaCacheShell para eliminar metadatos almacenados en caché: + +.. code-block:: console + + # Borrar todos los metadatos + bin/cake schema_cache clear + + # Limpiar una sola tabla + bin/cake schema_cache clear articles diff --git a/es/console-commands/server.rst b/es/console-commands/server.rst new file mode 100644 index 0000000000..36ad9f91f2 --- /dev/null +++ b/es/console-commands/server.rst @@ -0,0 +1,30 @@ +Herramienta de servidor +####################### + +El ``ServerCommand`` le permite crear un servidor web simple utilizando el +servidor web PHP integrado. Si bien este servidor *no* está diseñado para uso +en producción, puede ser útil en el desarrollo cuando desea probar rápidamente +una idea y no quiere perder tiempo configurando Apache o Nginx. Puede iniciar +el comando del servidor con: + +.. code-block:: console + + bin/cake server + +Debería ver que el servidor arranca y se conecta al puerto 8765. Puede visitar +el servidor CLI visitando ``http://localhost:8765`` en su navegador web. +Puede cerrar el servidor presionando ``CTRL-C`` en su terminal. + +.. note:: + + Pruebe ``bin/cake server -H 0.0.0.0`` si no se puede acceder al servidor + desde otros hosts. + +Cambiar el puerto y la raíz del documento +========================================= + +Puede personalizar el puerto y la raíz del documento usando las opciones: + +.. code-block:: console + + bin/cake server --port 8080 --document_root path/to/app From 2844d6ec055a72b4bb5903a9f1ae864b0348fb73 Mon Sep 17 00:00:00 2001 From: githubrana <39762049+githubrana@users.noreply.github.com> Date: Mon, 23 Oct 2023 14:19:46 +0530 Subject: [PATCH 064/337] Update auth.rst reference to old Authentication DefaultPasswordHasher; now resolved to use the new authentication plugin with CakePHP 5.0 --- en/tutorials-and-examples/blog-auth-example/auth.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/tutorials-and-examples/blog-auth-example/auth.rst b/en/tutorials-and-examples/blog-auth-example/auth.rst index 6b389432e7..a9a5020dcf 100644 --- a/en/tutorials-and-examples/blog-auth-example/auth.rst +++ b/en/tutorials-and-examples/blog-auth-example/auth.rst @@ -134,7 +134,7 @@ install the Authentication Plugin: .. code-block:: console - composer require "cakephp/authentication:^2.0" + php composer.phar require cakephp/authentication Then add the following to your application's ``bootstrap()`` method:: @@ -150,7 +150,7 @@ Next, we'll create the ``User`` entity and add password hashing. Create the // src/Model/Entity/User.php namespace App\Model\Entity; - use Cake\Auth\DefaultPasswordHasher; + use Authentication\PasswordHasher\DefaultPasswordHasher; use Cake\ORM\Entity; class User extends Entity From dd42b7bfcd6425887856a372c2748c4642878485 Mon Sep 17 00:00:00 2001 From: Andres Campanario Date: Mon, 23 Oct 2023 12:31:27 +0200 Subject: [PATCH 065/337] translate /views to spanish --- es/views.rst | 670 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 662 insertions(+), 8 deletions(-) diff --git a/es/views.rst b/es/views.rst index 4c155ebaaa..cf3f36c03b 100644 --- a/es/views.rst +++ b/es/views.rst @@ -5,30 +5,684 @@ Vistas .. php:class:: View -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +Las vistas son la **V** en MVC. Son responsables de generar la salida específica requerida para la solicitud. A menudo, esto se hace en forma de HTML, XML o JSON, pero también es responsabilidad de la Capa de Vistas transmitir archivos y crear PDFs que los usuarios puedan descargar. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +CakePHP viene con algunas clases de Vista incorporadas para manejar los escenarios de renderizado más comunes: - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +- Para crear servicios web XML o JSON, puedes usar los :doc:`views/json-and-xml-views`. +- Para servir archivos protegidos o archivos generados dinámicamente, puedes usar :ref:`cake-response-file`. +- Para crear vistas con varios temas, puedes usar :doc:`views/themes`. + +.. _app-view: + +La Vista de la Aplicación +========================= + +``AppView`` es la clase de Vista predeterminada de tu aplicación. ``AppView`` en sí misma extiende la clase ``Cake\View\View`` incluida en CakePHP y está definida en **src/View/AppView.php** de la siguiente manera: + +.. code-block:: php + + addHelper('MyUtils'); + } + } .. _view-templates: -Plantillas de vistas -==================== +Plantillas de Vista +=================== + +La capa de vista de CakePHP es la forma en que te comunicas con tus usuarios. La mayor parte del tiempo, tus vistas estarán renderizando documentos HTML/XHTML para los navegadores, pero también podrías necesitar responder a una aplicación remota a través de JSON o generar un archivo CSV para un usuario. + +Los archivos de plantilla de CakePHP son archivos PHP regulares y utilizan la `sintaxis PHP alternativa `_ para las estructuras de control y la salida. Estos archivos contienen la lógica necesaria para preparar los datos recibidos del controlador en un formato de presentación que está listo para tu audiencia." + +Alternativas de impresion +------------------------- + +Puedes imprimir o mostrar una variable en tu plantilla de la siguiente manera:: + + + +Utilizando soporte para etiquetas cortas:: + + + +Estructuras de Control Alternativas +----------------------------------- + +Las estructuras de control, como ``if``, ``for``, ``foreach``, ``switch`` y ``while``, pueden escribirse en un formato simplificado. Observa que no hay llaves. En su lugar, la llave de cierre para el ``foreach`` se reemplaza con ``endforeach``. Cada una de las estructuras de control mencionadas anteriormente tiene una sintaxis de cierre similar: ``endif``, ``endfor``, ``endforeach`` y ``endwhile``. También observa que en lugar de usar un ``punto y coma`` después de cada estructura (excepto la última), hay dos puntos ``:``. + +El siguiente es un ejemplo utilizando ``foreach``: + + +.. code-block:: php + +
    + +
    • + +
+ +Otro ejemplo, usando if/elseif/else. Observa los dos puntos: + +.. code-block:: php + + +

Hi Sally

+ +

Hi Joe

+ +

Hi unknown user

+ + +Si prefieres utilizar un lenguaje de plantillas como +`Twig `_, una subclase de View facilitará la conexión +entre tu lenguaje de plantillas y CakePHP. + +Los archivos de plantilla se almacenan en **templates/**, en una carpeta nombrada según el +controlador que utiliza los archivos y el nombre de la acción a la que corresponde. +Por ejemplo, el archivo de vista para la acción ``view()`` del controlador ``Products``, normalmente se encontraría en **templates/Products/view.php**. + +La capa de vista en CakePHP puede estar compuesta por varias partes diferentes. Cada +parte tiene usos distintos y se cubrirán en este capítulo: + +- **templates**: Las plantillas son la parte de la página que es única para la acción + que se está ejecutando. Constituyen el contenido principal de la respuesta de tu aplicación. +- **elements**: pequeños fragmentos de código de vista reutilizables. Por lo general, los elementos se renderizan + dentro de las vistas. +- **layouts**: archivos de plantilla que contienen código de presentación que envuelve muchas + interfaces en tu aplicación. La mayoría de las vistas se renderizan dentro de un diseño. +- **helpers**: estas clases encapsulan la lógica de la vista que se necesita en muchos + lugares en la capa de vista. Entre otras cosas, los helpers en CakePHP pueden ayudarte a + construir formularios, funcionalidades AJAX, paginar datos de modelos o servir feeds RSS. +- **cells**: estas clases proporcionan características similares a un controlador para + crear componentes de interfaz de usuario autosuficientes. Consulta la :doc:`/views/cells` + documentación para obtener más información." + +Variables de Vista +------------------ + +Cualquier variable que establezcas en tu controlador con ``set()`` estará disponible tanto en la vista como en el diseño que tu acción renderiza. Además, cualquier variable establecida también estará disponible en cualquier elemento. Si necesitas pasar variables adicionales desde la vista al diseño, puedes llamar a ``set()`` en la plantilla de vista o utilizar :ref:`Bloques de Vista `. + +Debes recordar **siempre** escapar cualquier dato del usuario antes de mostrarlo, ya que CakePHP no escapa automáticamente la salida. Puedes escapar el contenido del usuario con la función ``h()``::" + + bio); ?> + +Estableciendo Variables de Vista +-------------------------------- + +.. php:method:: set(string $var, mixed $value) + +Las vistas tienen un método ``set()`` que es análogo al ``set()`` que se encuentra en +los objetos del Controlador. Utilizar ``set()`` desde tu archivo de vista agregará las variables al +diseño y a los elementos que se renderizarán más adelante. Consulta +:ref:`setting-view_variables` para obtener más información sobre el uso de ``set()``. + +En tu archivo de vista puedes hacer:: + + $this->set('activeMenuButton', 'posts'); + +Entonces, en tu diseño, la variable ``$activeMenuButton`` estará disponible y +contendrá el valor 'posts'." + +.. _extendiendo-vistas: + +Extendiendo Vistas +------------------ + +La extensión de vistas te permite envolver una vista dentro de otra. Combinar esto con los +:ref:`bloques de vista ` te brinda una forma poderosa de mantener tus vistas +:term:`DRY` (Don't Repeat Yourself o No te repitas). Por ejemplo, tu aplicación tiene una barra lateral que necesita cambiar +según la vista específica que se está renderizando. Al extender un archivo de vista común, +puedes evitar repetir el marcado común para tu barra lateral y solo definir las partes que cambian: + +.. code-block:: php + + +

fetch('title')) ?>

+ fetch('content') ?> + +
+

Acciones relacionadas

+
    + fetch('sidebar') ?> +
+
+ +El archivo de vista anterior podría ser utilizado como una vista principal. Espera que la vista +que lo extiende definirá los bloques ``sidebar`` y ``title``. El bloque ``content`` +es un bloque especial que CakePHP crea. Contendrá todo el contenido no capturado de la vista que lo extiende. Suponiendo que nuestro archivo de vista tiene una variable ``$post`` con los datos de nuestra publicación, la vista podría verse así: + +.. code-block:: php + + + extend('/Common/view'); + + $this->assign('title', $post->title); + + $this->start('sidebar'); + ?> +
  • + Html->link('edit', [ + 'action' => 'edit', + $post->id, + ]); + ?> +
    • + end(); ?> + + // The remaining content will be available as the 'content' block + // In the parent view. + body) ?> + +La vista de la publicación anterior muestra cómo puedes extender una vista y llenar un conjunto de bloques. Cualquier contenido que no esté ya definido en un bloque será capturado y colocado en un bloque especial llamado ``content``. Cuando una vista contiene una llamada a ``extend()``, la ejecución continúa hasta el final del archivo de vista actual. Una vez que se completa, se renderizará la vista extendida. Llamar a ``extend()`` más de una vez en un archivo de vista anulará la vista principal que se procesará a continuación:: + + $this->extend('/Common/view'); + $this->extend('/Common/index'); + +Lo anterior hará que **/Common/index.php** se renderice como la vista principal para la vista actual. + +Puedes anidar vistas extendidas tantas veces como sea necesario. Cada vista puede extender otra vista si así lo deseas. Cada vista principal obtendrá el contenido de la vista anterior como el bloque ``content``. + +.. nota:: + + Debes evitar usar ``content`` como nombre de bloque en tu aplicación. + CakePHP lo utiliza para el contenido no capturado en vistas extendidas. + +Extendiendo Layouts +=================== + +Al igual que las vistas, los layouts también pueden ser extendidos. Al igual que con las vistas, se utiliza ``extend()`` +para extender los layouts. Las extensiones de layouts pueden actualizar o reemplazar bloques y actualizar o +reemplazar el contenido renderizado por el layout secundario. Por ejemplo, si quisiéramos +envolver un bloque con un marcado adicional, podríamos hacer lo siguiente:: + + // Nuestro layout extiende el layout de la aplicación. + $this->extend('application'); + $this->prepend('content', '
    '); + $this->append('content', '
    '); + + // Generar más marcado. + + // Recuerda imprimir el contenido del layout anterior. + echo $this->fetch('content'); + +.. _view-blocks: + +Uso de Bloques de Vista +======================= + +Los bloques de vista proporcionan una API flexible que te permite definir ranuras o bloques en +tus vistas/diseños que se definirán en otro lugar. Por ejemplo, los bloques son ideales +para implementar cosas como barras laterales o regiones para cargar activos en la parte inferior o superior del diseño. Los bloques se pueden definir de dos maneras: como un +bloque capturador o mediante asignación directa. Los métodos ``start()``, ``append()``, +``prepend()``, ``assign()``, ``fetch()``, y ``end()`` te permiten +trabajar con bloques capturadores:: + + // Crear el bloque de la barra lateral. + $this->start('sidebar'); + echo $this->element('sidebar/recent_topics'); + echo $this->element('sidebar/recent_comments'); + $this->end(); + + // Anexar contenido al bloque de la barra lateral más adelante. + $this->start('sidebar'); + echo $this->fetch('sidebar'); + echo $this->element('sidebar/popular_topics'); + $this->end(); + +También puedes añadir contenido a un bloque usando ``append()``:: + + $this->append('sidebar'); + echo $this->element('sidebar/popular_topics'); + $this->end(); + + // Lo mismo que el ejemplo anterior. + $this->append('sidebar', $this->element('sidebar/popular_topics')); + +Si necesitas borrar u sobrescribir un bloque, hay un par de alternativas. +El método ``reset()`` eliminará o sobrescribirá un bloque en cualquier momento. El +método ``assign()`` con una cadena de contenido vacía también se puede utilizar para borrar el +bloque especificado.:: + + // Limpiar el contenido anterior del bloque de la barra lateral. + $this->reset('sidebar'); + + // Asignar una cadena vacía también borrará el bloque de la barra lateral. + $this->assign('sidebar', ''); + +Asignar el contenido de un bloque a menudo es útil cuando deseas convertir una variable de vista +en un bloque. Por ejemplo, es posible que desees usar un bloque para el título de la página y, a veces, asignar el título como una variable de vista en el controlador:: + + // En el archivo de vista o diseño, arriba de $this->fetch('title') + $this->assign('title', $title); + +El método ``prepend()`` te permite agregar contenido al principio de un bloque existente:: + + // Agregar al principio de la barra lateral + $this->prepend('sidebar', 'este contenido va en la parte superior de la barra lateral'); + +Mostrar Bloques +--------------- + +Puedes mostrar bloques usando el método ``fetch()``. ``fetch()`` mostrará un +bloque, devolviendo '' si un bloque no existe:: + + fetch('sidebar') ?> + +También puedes usar ``fetch()`` para mostrar condicionalmente contenido que debería rodear a un +bloque si existe. Esto es útil en diseños o vistas extendidas donde +quieres mostrar condicionalmente encabezados u otro marcado: + +.. code-block:: php + + // En templates/layout/default.php + fetch('menu')): ?> +
    +

    Opciones de Menú

    + fetch('menu') ?> +
    + + +También puedes proporcionar un valor predeterminado para un bloque si no existe. +Esto te permite agregar contenido de marcador de posición cuando un bloque no existe. +Puedes proporcionar un valor predeterminado usando el segundo argumento: + +.. code-block:: php + +
    +

    Tu Carrito

    + fetch('carrito', 'Tu carrito está vacío') ?> +
    + +Usando Bloques para Archivos de Scripts y CSS +--------------------------------------------- + +El `HtmlHelper` se integra con bloques de vista, y sus métodos `script()`, `css()`, y `meta()` actualizan un bloque con el mismo nombre cuando se usan con la opción `block = true`: + +.. code-block:: php + + Html->script('carousel', ['block' => true]); + $this->Html->css('carousel', ['block' => true]); + ?> + + // En tu archivo de diseño. + + + + <?= h($this->fetch('title')) ?> + fetch('script') ?> + fetch('css') ?> + + // El resto del diseño sigue + +El :php:meth:`Cake\\View\\Helper\\HtmlHelper` también te permite controlar a qué bloque van los scripts y el CSS:: + + // En tu vista + $this->Html->script('carousel', ['block' => 'scriptBottom']); + + // En tu diseño + fetch('scriptBottom') ?> .. _view-layouts: Layouts ======= +Un layout contiene código de presentación que envuelve una vista. Todo lo que desees +ver en todas tus vistas debe colocarse en un layout. + +El layout predeterminado de CakePHP se encuentra en **templates/layout/default.php**. +Si deseas cambiar el aspecto general de tu aplicación, este es el +lugar correcto para comenzar, porque el código de vista renderizado por el controlador se coloca dentro del layout predeterminado cuando se renderiza la página. + +Otros archivos de layout deben colocarse en **templates/layout**. Cuando creas +un layout, necesitas decirle a CakePHP dónde colocar la salida de tus vistas. Para +hacerlo, asegúrate de que tu layout incluye un lugar para ``$this->fetch('content')``. +Aquí tienes un ejemplo de cómo podría verse un layout predeterminado: + +.. code-block:: php + + + + + <?= h($this->fetch('title')) ?> + + + fetch('meta'); + echo $this->fetch('css'); + echo $this->fetch('script'); + ?> + + + + + + + + fetch('content') ?> + + + + + + + +Los bloques ``script``, ``css`` y ``meta`` contienen cualquier contenido definido en las +vistas usando el ayudante HTML incorporado. Útil para incluir archivos JavaScript y CSS +desde vistas. + +.. nota:: + + Al usar ``HtmlHelper::css()`` o ``HtmlHelper::script()`` en archivos de plantilla, + especifica ``'block' => true`` para colocar la fuente HTML en un bloque con + el mismo nombre. (Consulta la API para obtener más detalles sobre el uso). + +El bloque ``content`` contiene el contenido de la vista renderizada. + +Puedes establecer el contenido del bloque ``title`` desde dentro de tu archivo de vista:: + + $this->assign('title', 'Ver Usuarios Activos'); + +Los valores vacíos para el bloque ``title`` se reemplazarán automáticamente con +una representación de la ruta de la plantilla actual, como ``'Admin/Artículos'``. + +Puedes crear tantos layouts como desees: solo colócalos en el directorio +**templates/layout**, y alterna entre ellos dentro de tus +acciones del controlador usando la propiedad ``$layout`` del controlador o la vista:: + + // Desde un controlador + public function vista() + { + // Establecer el diseño. + $this->viewBuilder()->setLayout('admin'); + } + + // Desde un archivo de vista + $this->layout = 'registrado'; + +Por ejemplo, si una sección de mi sitio incluyera un espacio para un banner publicitario más pequeño, podría +crear un nuevo layout con el espacio publicitario más pequeño y especificarlo como el +layout para todas las acciones de los controladores usando algo como:: + + namespace App\Controller; + + class UsuariosController extends AppController + { + public function verActivos() + { + $this->set('title', 'Ver Usuarios Activos'); + $this->viewBuilder()->setLayout('default_small_ad'); + } + + public function verImagen() + { + $this->viewBuilder()->setLayout('imagen'); + + // Mostrar imagen del usuario + } + } + +Además de un layout predeterminado, la aplicación de esqueleto oficial de CakePHP también tiene un layout 'ajax'. +El layout Ajax es útil para crear respuestas AJAX; es un diseño vacío. +(La mayoría de las llamadas AJAX solo requieren un poco de marcado como respuesta, en lugar de una +interfaz completamente renderizada). + +La aplicación de esqueleto también tiene un diseño predeterminado para ayudar a generar RSS. + +Usando Layouts desde Plugins +---------------------------- + +Si deseas usar un layout que existe en un plugin, puedes utilizar la :term:`sintaxis de plugin`. Por ejemplo, para usar el diseño de contacto del plugin Contacts:: + + namespace App\Controller; + + class UsersController extends AppController + { + public function verActivos() + { + $this->viewBuilder()->setLayout('Contacts.contact'); + } + } + .. _view-elements: Elementos ========= +.. php:method:: element(string $elementPath, array $data, array $options = []) + +Muchas aplicaciones tienen pequeños bloques de código de presentación que deben +repetirse de una página a otra, a veces en diferentes lugares en el diseño. CakePHP +puede ayudarte a repetir partes de tu sitio web que necesitan ser reutilizadas. Estas partes reutilizables +se llaman Elementos. Los anuncios, los cuadros de ayuda, los controles de navegación, los menús adicionales, +los formularios de inicio de sesión y las llamadas a la acción a menudo se implementan en CakePHP como elementos. Un +elemento es básicamente una mini-vista que se puede incluir en otras vistas, en +diseños e incluso dentro de otros elementos. Los elementos se pueden usar para hacer que una vista +sea más legible, colocando la representación de elementos repetidos en su propio archivo. También +te pueden ayudar a reutilizar fragmentos de contenido en tu aplicación. + +Los elementos se encuentran en la carpeta **templates/element/** y tienen la extensión de archivo .php. +Se generan utilizando el método element de la vista:: + + echo $this->element('helpbox'); + +Pasar Variables a un Elemento +----------------------------- + +Puedes pasar datos a un elemento a través del segundo argumento del elemento:: + + echo $this->element('helpbox', [ + 'helptext' => 'Oh, este texto es muy útil.', + ]); + +Dentro del archivo del elemento, todas las variables pasadas están disponibles como miembros del +array de parámetros (de la misma manera que ``Controller::set()`` en el +controlador funciona con los archivos de plantilla). En el ejemplo anterior, el +archivo **templates/element/helpbox.php** puede usar la variable ``$helptext``:: + + // Dentro de templates/element/helpbox.php + echo $helptext; // Muestra `Oh, este texto es muy útil.` + +Ten en cuenta que en esas variables de vista se fusionan con las variables de vista desde la vista +en sí misma. Entonces, todas las variables de vista establecidas usando ``Controller::set()`` en el controlador y +``View::set()`` en la vista en sí también están disponibles dentro del elemento. + +El método ``View::element()`` también admite opciones para el elemento. +Las opciones admitidas son 'cache' y 'callbacks'. Un ejemplo:: + + echo $this->element('helpbox', [ + 'helptext' => "Esto se pasa al elemento como $helptext", + 'foobar' => "Esto se pasa al elemento como $foobar", + ], + [ + // utiliza la configuración de caché `long_view` + 'cache' => 'long_view', + // establece en true para que se llame a before/afterRender para el elemento + 'callbacks' => true, + ] + ); + +El almacenamiento en caché del elemento se facilita a través de la clase ``Cache``. Puedes configurar +elementos para que se almacenen en cualquier configuración de caché que hayas establecido. Esto te brinda +una gran cantidad de flexibilidad para decidir dónde y por cuánto tiempo se almacenan los elementos. +Para almacenar en caché diferentes versiones del mismo elemento en una aplicación, +proporciona un valor de clave de caché único usando el siguiente formato:: + + $this->element('helpbox', [], [ + 'cache' => ['config' => 'short', 'key' => 'valor único'], + ] + ); + +Si necesitas más lógica en tu elemento, como datos dinámicos de una fuente de datos, +considera usar un View Cell en lugar de un elemento. Descubre más :doc:`sobre View +Cells `. + +Almacenamiento en Caché de Elementos +------------------------------------ + +Puedes aprovechar el almacenamiento en caché de CakePHP si proporcionas un parámetro de caché. +Si se establece en ``true``, almacenará en caché el elemento en la configuración de Caché 'default'. +De lo contrario, puedes establecer qué configuración de caché se debe utilizar. +Consulta :doc:`/core-libraries/caching` para obtener más información sobre cómo configurar +``Cache``. Un ejemplo simple de cómo almacenar en caché un elemento sería:: + + echo $this->element('helpbox', [], ['cache' => true]); + +Si renderizas el mismo elemento más de una vez en una vista y tienes el almacenamiento en caché +habilitado, asegúrate de establecer el parámetro 'key' con un nombre diferente cada vez. Esto +evitará que cada llamada sucesiva sobrescriba el resultado en caché de la llamada anterior a ``element()``. +Por ejemplo:: + + echo $this->element( + 'helpbox', + ['var' => $var], + ['cache' => ['key' => 'primer_uso', 'config' => 'view_long']] + ); + + echo $this->element( + 'helpbox', + ['var' => $otraVar], + ['cache' => ['key' => 'segundo_uso', 'config' => 'view_long']] + ); + +Lo anterior asegurará que ambos resultados del elemento se almacenen en caché por separado. Si deseas que todos los elementos en caché utilicen la misma configuración de caché, puedes evitar algo de repetición configurando ``View::$elementCache`` con la configuración de caché que deseas utilizar. CakePHP utilizará esta configuración cuando no se proporcione ninguna. + +Solicitando Elementos desde un Plugin +------------------------------------- + +Si estás usando un plugin y deseas utilizar elementos desde dentro del plugin, simplemente +usa la conocida :term:`sintaxis de plugin`. Si la vista se está renderizando para un +controlador/acción del plugin, el nombre del plugin se agregará automáticamente +a todos los elementos utilizados, a menos que haya otro nombre de plugin presente. +Si el elemento no existe en el plugin, buscará en la carpeta principal de la APLICACIÓN +(APP):: + + echo $this->element('Contacts.helpbox'); + +Si tu vista es parte de un plugin, puedes omitir el nombre del plugin. Por ejemplo, +si estás en el ``ContactsController`` del plugin Contacts, lo siguiente:: + + echo $this->element('helpbox'); + // y + echo $this->element('Contacts.helpbox'); + +son equivalentes y darán como resultado que se renderice el mismo elemento. + +Para elementos dentro de una subcarpeta de un plugin +(por ejemplo, **plugins/Contacts/Template/element/sidebar/helpbox.php**), usa el +siguiente formato:: + + echo $this->element('Contacts.sidebar/helpbox'); + +Prefijo de Enrutamiento y Elementos +----------------------------------- + +Si tienes un prefijo de enrutamiento configurado, la resolución de la ruta del Elemento puede cambiar +a una ubicación con prefijo, como sucede con los Diseños (Layouts) y la Vista de acción. +Supongamos que tienes configurado un prefijo "Admin" y llamas a:: + + echo $this->element('mi_elemento'); + +El elemento se buscará primero en **templates/Admin/element/**. Si dicho archivo no existe, +se buscará en la ubicación predeterminada. + +Almacenamiento en Caché de Secciones de tu Vista +------------------------------------------------ + +.. php:method:: cache(callable $block, array $options = []) + +A veces, generar una sección de la salida de tu vista puede ser costoso debido a +:doc:`/views/cells` renderizados u operaciones de ayuda costosas. Para ayudar a que tu +aplicación se ejecute más rápido, CakePHP proporciona una forma de almacenar en caché secciones de vista:: + + // Suponiendo algunas variables locales + echo $this->cache(function () use ($usuario, $articulo) { + echo $this->cell('PerfilUsuario', [$usuario]); + echo $this->cell('ArticuloCompleto', [$articulo]); + }, ['key' => 'mi_clave_de_vista']); + +Por defecto, el contenido de la vista almacenado en caché se guardará en la configuración de caché ``View::$elementCache``, +pero puedes usar la opción ``config`` para cambiar esto. + +Eventos de Vista +================ + +Al igual que los Controladores, la vista activa varios eventos o llamadas de retorno (callbacks) que puedes utilizar para +insertar lógica alrededor del ciclo de vida de renderización: + +Lista de Eventos +---------------- + +* ``View.beforeRender`` +* ``View.beforeRenderFile`` +* ``View.afterRenderFile`` +* ``View.afterRender`` +* ``View.beforeLayout`` +* ``View.afterLayout`` + +Puedes adjuntar :doc:`escuchadores de eventos de la aplicación ` a +estos eventos o utilizar :ref:`Llamadas de Retorno de Ayudantes (Helper Callbacks) `. + +Creando tus Propias Clases de Vista +=================================== + +Puede que necesites crear clases de vista personalizadas para habilitar nuevos tipos de vistas de datos o +agregar lógica de renderización de vista personalizada adicional a tu aplicación. Como la mayoría de +componentes de CakePHP, las clases de vista tienen algunas convenciones: + +* Los archivos de clases de vista deben colocarse en **src/View**. Por ejemplo: + **src/View/PdfView.php** +* Las clases de vista deben tener el sufijo ``View``. Por ejemplo: ``PdfView``. +* Al referenciar nombres de clases de vista, deberías omitir el sufijo ``View``. Por ejemplo: ``$this->viewBuilder()->setClassName('Pdf');``. + +También querrás extender ``View`` para asegurar que las cosas funcionen correctamente:: + + // En src/View/PdfView.php + namespace App\View; + + use Cake\View\View; + + class PdfView extends View + { + public function render($view = null, $layout = null) + { + // Lógica personalizada aquí. + } + } + +Reemplazar el método render te permite tener control total sobre cómo se renderiza tu contenido. + Más acerca de Vistas ==================== From cbe6c2467e95decb3622af5f219a8c4ae702621b Mon Sep 17 00:00:00 2001 From: Andres Campanario Date: Mon, 23 Oct 2023 15:18:33 +0200 Subject: [PATCH 066/337] esolve link --- es/plugins.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/es/plugins.rst b/es/plugins.rst index 7e67630ed2..5d77801dc6 100644 --- a/es/plugins.rst +++ b/es/plugins.rst @@ -73,6 +73,8 @@ También hay un práctico comando de consola para cargar el plugin. Ejecuta la s Esto actualizaría el array en el archivo ``config/plugins.php`` de tu aplicación con una entrada similar a ``'ContactManager' => []``. +.. _plugin-configuration: + Configuración de Hooks del Plugin ================================= @@ -395,7 +397,7 @@ Si tu aplicación define prefijos de enrutamiento, el enrutamiento predeterminad /{prefix}/{plugin}/{controller} /{prefix}/{plugin}/{controller}/{action} -Consulta la sección sobre :ref:`configuracion-de-hooks-del-plugin` para obtener información sobre cómo cargar archivos de rutas específicos del plugin. +Consulta la sección sobre :ref:`plugin-configuration` para obtener información sobre cómo cargar archivos de rutas específicos del plugin. .. _plugin-models: @@ -482,7 +484,7 @@ Si se omite el prefijo del plugin, el archivo de diseño/vista se ubicará de fo .. nota:: - Para obtener información sobre cómo usar elementos de un plugin, consulta :ref:`elementos` + Para obtener información sobre cómo usar elementos de un plugin, consulta :ref:`view-elements` Sobrescribir Plantillas de Plugin desde dentro de tu Aplicación --------------------------------------------------------------- From 860343b48423ad8eb27ebce76f49d596544e0edd Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 23 Oct 2023 09:56:08 -0400 Subject: [PATCH 067/337] Re-add version constraint Refs #7753 --- en/tutorials-and-examples/blog-auth-example/auth.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/blog-auth-example/auth.rst b/en/tutorials-and-examples/blog-auth-example/auth.rst index a9a5020dcf..c4f9277fe1 100644 --- a/en/tutorials-and-examples/blog-auth-example/auth.rst +++ b/en/tutorials-and-examples/blog-auth-example/auth.rst @@ -134,7 +134,7 @@ install the Authentication Plugin: .. code-block:: console - php composer.phar require cakephp/authentication + php composer.phar require "cakephp/authentication:^2.0" Then add the following to your application's ``bootstrap()`` method:: From 1463d8508ffde3e69b8b76c248e78e54e747bdc3 Mon Sep 17 00:00:00 2001 From: nmaya <5668936+nmaya@users.noreply.github.com> Date: Tue, 24 Oct 2023 06:59:26 +0900 Subject: [PATCH 068/337] use SelectQuery instead of Query, and SelectQuery does not have method isEmpty apply PR #7579 to Japanese document. --- ja/orm/retrieving-data-and-resultsets.rst | 42 ++++++++++------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/ja/orm/retrieving-data-and-resultsets.rst b/ja/orm/retrieving-data-and-resultsets.rst index 1726a3b298..24b93cc72f 100644 --- a/ja/orm/retrieving-data-and-resultsets.rst +++ b/ja/orm/retrieving-data-and-resultsets.rst @@ -89,9 +89,9 @@ find メソッドは、あなたが求めるデータを検索するための簡 // すべての article を検索する $query = $articles->find('all'); -``find()`` メソッドの戻り値は常に :php:class:`Cake\\ORM\\Query` オブジェクトです。 -Query クラスにより、それの生成後は、クエリーをより精錬することができるようになります。 -Query オブジェクトは怠惰に評価され、行のフェッチ、配列への変換、 +``find()`` メソッドの戻り値は常に :php:class:`Cake\\ORM\\SelectQuery` オブジェクトです。 +SelectQuery クラスにより、それの生成後は、クエリーをより精錬することができるようになります。 +SelectQuery オブジェクトは怠惰に評価され、行のフェッチ、配列への変換、 もしくは ``all()`` メソッドの呼び出しをするまでは実行されません。 :: // コントローラーやテーブルのメソッド内で @@ -349,12 +349,12 @@ finder メソッドは、あなたが作成したい finder の名前が ``Foo`` 例えば、公開された記事を見つけるために articles テーブルに finder を追加したい場合、 次のようになります。 :: - use Cake\ORM\Query; + use Cake\ORM\SelectQuery; use Cake\ORM\Table; class ArticlesTable extends Table { - public function findOwnedBy(Query $query, array $options) + public function findOwnedBy(SelectQuery $query, array $options) { $user = $options['user']; return $query->where(['author_id' => $user->id]); @@ -537,11 +537,11 @@ contain に条件を渡す ``contain()`` を使う際、関連によって返される列を限定し、条件によってフィルターすることができます。 条件を指定するには、第１引数としてクエリーオブジェクト -``\Cake\ORM\Query`` を受け取る無名関数を渡します。 :: +``\Cake\ORM\SelectQuery`` を受け取る無名関数を渡します。 :: // コントローラーやテーブルのメソッド内で - $query = $articles->find()->contain('Comments', function (Query $q) { + $query = $articles->find()->contain('Comments', function (SelectQuery $q) { return $q ->select(['body', 'author_id']) ->where(['Comments.approved' => true]); @@ -550,7 +550,7 @@ contain に条件を渡す これは、またコントローラーレベルでページネーションが働きます。 :: $this->paginate['contain'] = [ - 'Comments' => function (Query $query) { + 'Comments' => function (SelectQuery $query) { return $query->select(['body', 'author_id']) ->where(['Comments.approved' => true]); } @@ -566,7 +566,7 @@ contain に条件を渡す $query = $articles->find()->contain([ 'Comments', - 'Authors.Profiles' => function (Query $q) { + 'Authors.Profiles' => function (SelectQuery $q) { return $q->where(['Profiles.is_published' => true]); } ]); @@ -578,7 +578,7 @@ contain に条件を渡す それらを使うことができます。 :: // すべての article を取り出すが、承認され (approved)、人気のある (popular) ものだけに限定する - $query = $articles->find()->contain('Comments', function (Query $q) { + $query = $articles->find()->contain('Comments', function (SelectQuery $q) { return $q->find('approved')->find('popular'); }); @@ -595,7 +595,7 @@ contain に条件を渡す $query = $articles->find()->contain([ 'Authors' => [ 'foreignKey' => false, - 'queryBuilder' => function (Query $q) { + 'queryBuilder' => function (SelectQuery $q) { return $q->where(...); // フィルターのための完全な条件 } ] @@ -616,7 +616,7 @@ contain に条件を渡す $query->select(['id', 'title']) ->contain(['Comments', 'Tags']) ->enableAutoFields(true) - ->contain(['Users' => function(Query $q) { + ->contain(['Users' => function(SelectQuery $q) { return $q->autoFields(true); }]); @@ -964,14 +964,10 @@ ResultSet から任意の場所を指定して取得する // ５番目のレコードを取得する $row = $result->skip(4)->first(); -Query や ResultSet が空かどうかをチェックする +ResultSet が空かどうかをチェックする --------------------------------------------- -Query や ResultSet オブジェクトの ``isEmpty()`` メソッドを使うことで１行以上あるかどうかを確認できます。 -Query オブジェクトで ``isEmpty()`` メソッドを呼び出した場合はクエリーが評価されます。 :: - - // クエリーをチェックします - $query->isEmpty(); +ResultSet オブジェクトの ``isEmpty()`` メソッドを使うことで１行以上あるかどうかを確認できます。 :: // 結果をチェックします $results = $query->all(); @@ -1003,7 +999,7 @@ Query オブジェクトで ``isEmpty()`` メソッドを呼び出した場合 ときには、より基本的な方法でデータ構造を変更する必要があることもあります。 このような場合に、データベースからフェッチした後で結果を処理する方法として、 -``Query`` オブジェクトは ``mapReduce()`` を提供します。 +``SelectQuery`` オブジェクトは ``mapReduce()`` を提供します。 データ構造を変更するよくある事例は、結果をとある条件に基いて仕分けするものです。 このために ``mapReduce()`` 関数を使うことができます。 @@ -1175,17 +1171,17 @@ reducer が呼ばれるごとに、reducer はユーザーごとのフォロワ これは :ref:`custom-find-methods` セクションで説明しているように、 カスタム Finder メソッドを構築するのに非常に便利です。 :: - public function findPublished(Query $query, array $options) + public function findPublished(SelectQuery $query, array $options) { return $query->where(['published' => true]); } - public function findRecent(Query $query, array $options) + public function findRecent(SelectQuery $query, array $options) { return $query->where(['created >=' => new DateTime('1 day ago')]); } - public function findCommonWords(Query $query, array $options) + public function findCommonWords(SelectQuery $query, array $options) { // 前のセクションで説明した共通の単語の件と同じもの $mapper = ...; @@ -1213,7 +1209,7 @@ reducer が呼ばれるごとに、reducer はユーザーごとのフォロワ stack されたすべての MapReduce 操作を取り除く --------------------------------------------- -ときには ``mapReduce`` 操作をまったく実行させずに ``Query`` オブジェクトを更新したいという +ときには ``mapReduce`` 操作をまったく実行させずに ``SelectQuery`` オブジェクトを更新したいという 状況もあるかもしれません。これは両方の引数に null を指定し、第３引数 (overwrite) で ``true`` を呼び出すことで達成できます。 :: From a7f70b338e3a7706d3a2292c5f12c42bd608e35b Mon Sep 17 00:00:00 2001 From: Alejandro Ibarra Date: Tue, 24 Oct 2023 10:40:07 +0200 Subject: [PATCH 069/337] Fix different missing links issues --- config/conf.py | 2 + es/appendices.rst | 23 +- es/appendices/4-0-migration-guide.rst | 15 - .../5-0-migration-guide.rst} | 14 +- es/appendices/5-0-upgrade-guide.rst | 13 + es/appendices/glossary.rst | 4 +- es/appendices/migration-guides.rst | 12 + es/appendices/phpunit10.rst | 14 + es/console-and-shells.rst | 34 - es/console-and-shells/cron-jobs.rst | 15 - es/console-and-shells/i18n-shell.rst | 15 - es/console-and-shells/orm-cache.rst | 11 - es/console-and-shells/routes-shell.rst | 11 - es/console-and-shells/server-shell.rst | 11 - es/console-and-shells/upgrade-shell.rst | 17 - es/console-commands.rst | 176 ++ es/console-commands/commands.rst | 6 +- es/console-commands/completion.rst | 4 +- es/console-commands/i18n.rst | 4 +- es/console-commands/input-output.rst | 10 +- es/console-commands/option-parsers.rst | 12 +- es/console-commands/plugin.rst | 4 +- es/console-commands/routes.rst | 4 +- es/console-commands/schema-cache.rst | 2 +- es/contents.rst | 44 +- es/controllers/components/csrf.rst | 15 - es/controllers/middleware.rst | 254 ++- .../pagination.rst} | 14 +- es/controllers/request-response.rst | 1197 +++++++++++- es/core-libraries/caching.rst | 4 +- es/core-libraries/file-folder.rst | 16 - es/core-libraries/logging.rst | 500 ++++- .../plugin.rst} | 12 +- es/deployment.rst | 145 +- .../cache.rst => development/application.rst} | 14 +- .../dependency-injection.rst} | 6 +- es/development/errors.rst | 2 +- es/development/routing.rst | 1713 ++++++++++++++++- es/epub-contents.rst | 20 +- es/orm.rst | 2 +- es/phinx.rst | 4 + es/release-policy.rst | 54 + es/security.rst | 24 +- es/security/content-security-policy.rst | 54 + es/security/csrf.rst | 174 ++ es/security/https-enforcer.rst | 65 + es/security/security-headers.rst | 34 + es/standalone-packages.rst | 76 + es/topics.rst | 7 +- es/views/helpers.rst | 341 +++- es/views/helpers/rss.rst | 20 - es/views/helpers/session.rst | 20 - 52 files changed, 4896 insertions(+), 368 deletions(-) delete mode 100644 es/appendices/4-0-migration-guide.rst rename es/{console-and-shells/completion-shell.rst => appendices/5-0-migration-guide.rst} (53%) create mode 100644 es/appendices/5-0-upgrade-guide.rst create mode 100644 es/appendices/migration-guides.rst create mode 100644 es/appendices/phpunit10.rst delete mode 100644 es/console-and-shells.rst delete mode 100644 es/console-and-shells/cron-jobs.rst delete mode 100644 es/console-and-shells/i18n-shell.rst delete mode 100644 es/console-and-shells/orm-cache.rst delete mode 100644 es/console-and-shells/routes-shell.rst delete mode 100644 es/console-and-shells/server-shell.rst delete mode 100644 es/console-and-shells/upgrade-shell.rst create mode 100644 es/console-commands.rst delete mode 100644 es/controllers/components/csrf.rst rename es/{console-and-shells/helpers.rst => controllers/pagination.rst} (55%) delete mode 100644 es/core-libraries/file-folder.rst rename es/{console-and-shells/plugin-shell.rst => core-libraries/plugin.rst} (66%) rename es/{console-and-shells/cache.rst => development/application.rst} (54%) rename es/{console-and-shells/repl.rst => development/dependency-injection.rst} (81%) create mode 100644 es/phinx.rst create mode 100644 es/release-policy.rst create mode 100644 es/security/content-security-policy.rst create mode 100644 es/security/csrf.rst create mode 100644 es/security/https-enforcer.rst create mode 100644 es/security/security-headers.rst create mode 100644 es/standalone-packages.rst delete mode 100644 es/views/helpers/rss.rst delete mode 100644 es/views/helpers/session.rst diff --git a/config/conf.py b/config/conf.py index 6b7f6cc14d..87cad35de4 100644 --- a/config/conf.py +++ b/config/conf.py @@ -115,3 +115,5 @@ .. |phpversion| replace:: **8.2** .. |minphpversion| replace:: 8.1 """ + +# todo_include_todos = True diff --git a/es/appendices.rst b/es/appendices.rst index b8b89fc1b0..6c3b11879c 100644 --- a/es/appendices.rst +++ b/es/appendices.rst @@ -4,15 +4,32 @@ Apéndices En los apéndices encontrarás información relacionada a las nuevas características introducidas en cada versión, así como también las guías de migración entre versiones. -Guía de Migración a 4.x +Guía de Migración a 5.x ======================= .. toctree:: :maxdepth: 1 - appendices/4-0-migration-guide + appendices/5-0-upgrade-guide + appendices/5-0-migration-guide -Información General +Retrocompatiblidad +=================== + +Si quieres utilizar funcionalidades de 3.x o 4.x o ir migrando poco a poco +el `Plugin Shim `__ puede ayudarte a mitigar algunos +de los cambios que rompen la compatibilidad. + +Antecompatiblidad +================= + +La Antecompatibilidad puede preparar tu aplicación 4.x para la próxima versión 5.x. + +Si quieres utilizar una funcionalidad de 5.x en 4.x, revisa el `Plugin Shim +`__. Este plugin te ayuda a mitigar los +problemas de compatibilidad y a llevar funcionalidades de 5.x a 4.x. + +General Information =================== .. toctree:: diff --git a/es/appendices/4-0-migration-guide.rst b/es/appendices/4-0-migration-guide.rst deleted file mode 100644 index 4a690f257d..0000000000 --- a/es/appendices/4-0-migration-guide.rst +++ /dev/null @@ -1,15 +0,0 @@ -4.0 Migration Guide -################### - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: CakePHP Development Process - :keywords lang=es: maintenance branch,community interaction,community feature,necessary feature,stable release,ticket system,advanced feature,power users,feature set,chat irc,leading edge,router,new features,members,attempt,development branches,branch development diff --git a/es/console-and-shells/completion-shell.rst b/es/appendices/5-0-migration-guide.rst similarity index 53% rename from es/console-and-shells/completion-shell.rst rename to es/appendices/5-0-migration-guide.rst index c6dace293e..2216d1b75c 100644 --- a/es/console-and-shells/completion-shell.rst +++ b/es/appendices/5-0-migration-guide.rst @@ -1,11 +1,13 @@ -Completion Shell -################ +Guía de Migración 5.0 +##################### .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. + La documentación no es compatible actualmente con el idioma español en esta + página. Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + `Github `_ o utilizar el botón + **Improve this Doc** para proponer directamente los cambios. - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + Usted puede hacer referencia a la versión en Inglés en el menú de selección + superior para obtener información sobre el tema de esta página. diff --git a/es/appendices/5-0-upgrade-guide.rst b/es/appendices/5-0-upgrade-guide.rst new file mode 100644 index 0000000000..89c8eda018 --- /dev/null +++ b/es/appendices/5-0-upgrade-guide.rst @@ -0,0 +1,13 @@ +Guía de Actualización 5.0 +########################## + +.. note:: + La documentación no es compatible actualmente con el idioma español en esta + página. + + Por favor, siéntase libre de enviarnos un pull request en + `Github `_ o utilizar el botón + **Improve this Doc** para proponer directamente los cambios. + + Usted puede hacer referencia a la versión en Inglés en el menú de selección + superior para obtener información sobre el tema de esta página. diff --git a/es/appendices/glossary.rst b/es/appendices/glossary.rst index f424acae5c..842404ae8b 100644 --- a/es/appendices/glossary.rst +++ b/es/appendices/glossary.rst @@ -3,8 +3,8 @@ Glosario .. glossary:: - array de rutas - Un array de atributos que son pasados a :php:meth:`Router::url()`. + arreglo de enrutamiento + Un arreglo de atributos que son pasados a :php:meth:`Router::url()`. Típicamente se ve algo así:: ['controller' => 'Posts', 'action' => 'view', 5] diff --git a/es/appendices/migration-guides.rst b/es/appendices/migration-guides.rst new file mode 100644 index 0000000000..6a312e36d4 --- /dev/null +++ b/es/appendices/migration-guides.rst @@ -0,0 +1,12 @@ +Guías de Migración +################## + +Las Guías de Migración contienen información relativa a las nuevas funcionalidades +introducidas en cada versión y la manera de migrar exitosamente desde 4.x a 5.x + +.. toctree:: + :maxdepth: 1 + + ./5-0-upgrade-guide + ./5-0-migration-guide + ./phpunit10 diff --git a/es/appendices/phpunit10.rst b/es/appendices/phpunit10.rst new file mode 100644 index 0000000000..8a612bd61e --- /dev/null +++ b/es/appendices/phpunit10.rst @@ -0,0 +1,14 @@ +Actualización PHPUnit 10 +######################### + +.. note:: + La documentación no es compatible actualmente con el idioma español en esta + página. + + Por favor, siéntase libre de enviarnos un pull request en + `Github `_ o utilizar el botón + **Improve this Doc** para proponer directamente los cambios. + + Usted puede hacer referencia a la versión en Inglés en el menú de selección + superior para obtener información sobre el tema de esta página. + diff --git a/es/console-and-shells.rst b/es/console-and-shells.rst deleted file mode 100644 index b7220cb2ab..0000000000 --- a/es/console-and-shells.rst +++ /dev/null @@ -1,34 +0,0 @@ -Shells, Tasks & Console Tools -############################# - -.. php:namespace:: Cake\Console - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -More Topics -=========== - -.. toctree:: - :maxdepth: 1 - - console-and-shells/helpers - console-and-shells/repl - console-and-shells/cron-jobs - console-and-shells/i18n-shell - console-and-shells/completion-shell - console-and-shells/plugin-shell - console-and-shells/routes-shell - console-and-shells/upgrade-shell - console-and-shells/server-shell - console-and-shells/cache - -.. meta:: - :title lang=es: Shells, Tasks & Console Tools - :keywords lang=es: shell scripts,system shell,application classes,background tasks,line script,cron job,request response,system path,acl,new projects,shells,specifics,parameters,i18n,cakephp,directory,maintenance,ideal,applications,mvc diff --git a/es/console-and-shells/cron-jobs.rst b/es/console-and-shells/cron-jobs.rst deleted file mode 100644 index 70be87e75b..0000000000 --- a/es/console-and-shells/cron-jobs.rst +++ /dev/null @@ -1,15 +0,0 @@ -Running Shells as Cron Jobs -########################### - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Running Shells as cronjobs - :keywords lang=es: cronjob,bash script,crontab diff --git a/es/console-and-shells/i18n-shell.rst b/es/console-and-shells/i18n-shell.rst deleted file mode 100644 index 2bfe87ffc2..0000000000 --- a/es/console-and-shells/i18n-shell.rst +++ /dev/null @@ -1,15 +0,0 @@ -I18N Shell -########## - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: I18N shell - :keywords lang=es: pot files,locale default,translation tools,message string,app locale,php class,validation,i18n,translations,shell,models diff --git a/es/console-and-shells/orm-cache.rst b/es/console-and-shells/orm-cache.rst deleted file mode 100644 index a9417ea1bc..0000000000 --- a/es/console-and-shells/orm-cache.rst +++ /dev/null @@ -1,11 +0,0 @@ -ORM Cache Shell -############### - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. diff --git a/es/console-and-shells/routes-shell.rst b/es/console-and-shells/routes-shell.rst deleted file mode 100644 index 03e8e1b6a5..0000000000 --- a/es/console-and-shells/routes-shell.rst +++ /dev/null @@ -1,11 +0,0 @@ -Routes Shell -############ - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. diff --git a/es/console-and-shells/server-shell.rst b/es/console-and-shells/server-shell.rst deleted file mode 100644 index 42e18df23d..0000000000 --- a/es/console-and-shells/server-shell.rst +++ /dev/null @@ -1,11 +0,0 @@ -Server Shell -############ - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. diff --git a/es/console-and-shells/upgrade-shell.rst b/es/console-and-shells/upgrade-shell.rst deleted file mode 100644 index 498b97b7de..0000000000 --- a/es/console-and-shells/upgrade-shell.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _upgrade-shell: - -Upgrade Shell -############# - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Upgrade Shell - :keywords lang=es: api docs,shell,upgrade diff --git a/es/console-commands.rst b/es/console-commands.rst new file mode 100644 index 0000000000..dc0636fa6b --- /dev/null +++ b/es/console-commands.rst @@ -0,0 +1,176 @@ +Comandos de Consola +################### + +.. php:namespace:: Cake\Console + +Además de ser un `framework` web, CakePHP también ofrece un `framework` +de consola para crear herramientas y aplicaciones de línea de comandos. Las aplicaciones +de consola son ideales para gestionar una variedad de tareas de mantenimiento +que aprovechan la configuración existente de tu aplicación, modelos, complementos y lógica de dominio. + +CakePHP proporciona varias herramientas de consola para interactuar con sus características, como i18n +y enrutamiento, lo que te permite inspeccionar tu aplicación y generar archivos relacionados. + +La Consola CakePHP +=================== + +La Console CakePHP utiliza un sistema de tipo `dispatcher` para cargar comandos, analizar sus +argumentos e invocar el comando correcto. Aunque los ejemplos a continuación usan bash, el +console de CakePHP es compatible con cualquier shell de Unix (\*nix) y Windows. + +Una aplicación CakePHP tiene un directorio **src/Command** que contiene sus comandos. Tambien incluye +un ejecutable en el directorio **bin** + +.. code-block:: console + + $ cd /path/to/app + $ bin/cake + +.. note:: + + Para Windows, el comando es ``bin\cake`` (note el `backslash`) + +Ejecutar la console sin argumentos listará todos los comandos disponibles. Tu +puedes, de esta manera, ejecutar cualquiera de los comandos listados usando su nombre: + +.. code-block:: console + + # ejecutar el comando server + bin/cake server + + # ejecutar el comando migrations + bin/cake migrations -h + + # ejecutar bake (con un prefijo de `plugin`) + bin/cake bake.bake -h + +Los comandos de los `plugins` pueden ser invocados sin un prefijo de `plugin` si el nombre del +comando no coincide con un comando de la aplicación o del `framework`. En el caso de que dos `plugins` +proporcionen un comando con el mismo nombre, el `plugin` que se ha cargado primero obtendrá el alias corto. Siempre +puedes utilizar el formato ``plugin.command`` para hacer referencia de manera inequívoca a un comando. + + +Aplicaciones de Consola +======================= + +Por defecto, CakePHP descubrirá automáticamente todos los comandos en tu aplicación y sus complementos. Puede que +desees reducir el número de comandos expuestos al construir aplicaciones de consola independientes. Puedes utilizar +el método ``console()`` de tu clase ``Application`` para limitar qué comandos se exponen y renombrar los comandos que se exponen:: + + // en src/Application.php + namespace App; + + use App\Command\UserCommand; + use App\Command\VersionCommand; + use Cake\Console\CommandCollection; + use Cake\Http\BaseApplication; + + class Application extends BaseApplication + { + public function console(CommandCollection $commands): CommandCollection + { + // Agregar por clase + $commands->add('user', UserCommand::class); + + // Agregar instancia + $commands->add('version', new VersionCommand()); + + return $commands; + } + } + +En el ejemplo anterior, los únicos comandos disponibles serían ``help``, ``version`` y ``user``. +Revisa la sección :ref:`plugin-commands` sobre como agregar comandos en los `plugins`. + +.. note:: + + Cuando agregas múltiples comandos que usan la misma clase, el comando ``help`` mostrará la opción más corta. + +.. _renaming-commands: +.. index:: nested commands, subcommands + +Renombrando Comandos +==================== + +Hay casos en los cuáles querrás renombrar comandos para crear comandos anidados o subcomandos. Mientras que +el descubrimiento automático de comandos no hará esto, tu pueds registrar tus comandos para darles el nombre +que desees. + +Puedes personalizar los nombre de los comandos definiéndolo en tu método ``console()``:: + + public function console(CommandCollection $commands): CommandCollection + { + // Agregar comandos anidados (subcomandos) + $commands->add('user dump', UserDumpCommand::class); + $commands->add('user:show', UserShowCommand::class); + + // Renombrar un comando completamente + $commands->add('lazer', UserDeleteCommand::class); + + return $commands; + } + +Cuando utilizas el método ``console()`` en tu aplicación, recuerda llamar +``$commands->autoDiscover()`` para agregar los comandos de CakePHP, de tu aplicación y +de tus `plugins`. + +Si necesitas renombrar/eliminar cualquier comando disponible, puedes usar el evento ``Console.buildCommands`` en +tu manejador de eventos para modificarlos. + +Comandos +======== + +Echa un vistazo al capítulo :doc:`/console-commands/commands` sobre como crear tu primer +comando. Luego aprende más sobre comandos. + +.. toctree:: + :maxdepth: 1 + + console-commands/commands + console-commands/input-output + console-commands/option-parsers + console-commands/cron-jobs + +Comandos provistos por CakePHP +============================== + +.. toctree:: + :maxdepth: 1 + + console-commands/cache + console-commands/completion + console-commands/i18n + console-commands/plugin + console-commands/schema-cache + console-commands/routes + console-commands/server + console-commands/repl + +Enrutando en el ambiente de consola +=================================== + +In command-line interface (CLI), specifically your console commands, +``env('HTTP_HOST')`` and other webbrowser specific environment variables are not +set. + +If you generate reports or send emails that make use of ``Router::url()`` those +will contain the default host ``http://localhost/`` and thus resulting in +invalid URLs. In this case you need to specify the domain manually. +You can do that using the Configure value ``App.fullBaseUrl`` from your +bootstrap or config, for example. + +For sending emails, you should provide Email class with the host you want to +send the email with:: + + use Cake\Mailer\Email; + + $email = new Email(); + $email->setDomain('www.example.org'); + +This asserts that the generated message IDs are valid and fit to the domain the +emails are sent from. + + +.. meta:: + :title lang=es: Comandos, Tareas & Herramientas de Consola + :keywords lang=es: shell scripts,system shell,application classes,background tasks,line script,cron job,request response,system path,acl,new projects,commands,specifics,parameters,i18n,cakephp,directory,maintenance,ideal,applications,mvc diff --git a/es/console-commands/commands.rst b/es/console-commands/commands.rst index a5e7d14d31..5d80bcd7c0 100644 --- a/es/console-commands/commands.rst +++ b/es/console-commands/commands.rst @@ -222,7 +222,7 @@ Puede pasar cualquier código de salida que desee a ``abort()``. los sistemas Unix (``man sysexits``), o en la página de ayuda ``Códigos de error del sistema`` en Windows. Llamar a otros comandos -====================== +======================== Es posible que necesite llamar a otros comandos desde tu comando. Puedes usar ``executeCommand`` para hacer eso:: @@ -507,7 +507,7 @@ no confirmamos y los registros no se actualizan, y podemos verificar que nuestro fue escrito en ``stderr``. Metodos de aserción ------------------ +------------------- El rasgo ``Cake\TestSuite\ConsoleIntegrationTestTrait`` proporciona una serie de métodos de aserción que ayudan a afirmar contra la salida de la consola:: @@ -534,7 +534,7 @@ que ayudan a afirmar contra la salida de la consola:: $this->assertErrorRegExp($expected); Ciclo de vida de las devoluciones de llamada -=================== +============================================= Al igual que los controladores, los comandos ofrecen eventos de ciclo de vida que le permiten observar el marco que llama al código de su aplicación. Los comandos tienen: diff --git a/es/console-commands/completion.rst b/es/console-commands/completion.rst index ab7e6dd530..d140e28ca7 100644 --- a/es/console-commands/completion.rst +++ b/es/console-commands/completion.rst @@ -1,5 +1,5 @@ Herramienta de completación -################ +########################### Trabajar con la consola le brinda al desarrollador muchas posibilidades, pero tener que conocer y escribir completamente esos comandos puede resultar tedioso. Especialmente cuando se desarrollan nuevos shells donde @@ -78,7 +78,7 @@ Guarde el archivo y luego reinicie su consola. .. _bash-completion-file-content: Contenido del archivo de completación de Bash ----------------------------- +---------------------------------------------- Este es el código que debes colocar dentro del archivo **cake** en la ubicación correcta para obtener el autocompletado al usar la consola CakePHP: diff --git a/es/console-commands/i18n.rst b/es/console-commands/i18n.rst index 0bee4f8b03..abe4752565 100644 --- a/es/console-commands/i18n.rst +++ b/es/console-commands/i18n.rst @@ -1,5 +1,5 @@ Herramienta de internacionalización (i18n) -######### +########################################## Las características i18n de CakePHP usan `archivos po `_ como fuente de traducción. Los archivos PO se integran con herramientas de traducción de uso común @@ -33,7 +33,7 @@ para crear archivos po. Si está creando archivos po manualmente a partir del archivo pot, asegúrese de configurar correctamente la línea de encabezado ``Plural-Forms``. Generando archivos POT para complementos --------------------------------- +----------------------------------------- Puede generar un archivo POT para un complemento específico usando: diff --git a/es/console-commands/input-output.rst b/es/console-commands/input-output.rst index 1aaf81443f..685bef35ab 100644 --- a/es/console-commands/input-output.rst +++ b/es/console-commands/input-output.rst @@ -1,5 +1,5 @@ Comandos Entrada/Salida (Input/Output) -#################### +###################################### .. php:namespace:: Cake\Console .. php:class:: ConsoleIo @@ -10,7 +10,7 @@ leer interactivamente la información de entrada y salida del usuario. .. _command-helpers: Ayudantes de comando (Helpers) -=============== +============================== Se puede acceder y utilizar los ayudantes (helpers) de comandos desde cualquier comando:: @@ -28,7 +28,7 @@ También puede obtener instancias de ayudantes y llamar a cualquier método púb $progress->draw(); Creando ayudantes -================ +================= Si bien CakePHP viene con algunos comandos auxiliares, puedes crear más en tu aplicación o complementos. Como ejemplo, crearemos un asistente simple para @@ -185,7 +185,7 @@ con confirmación interactiva:: $io->createFile('bower.json', $stuff, true); Creando salidas (Output) -=============== +======================== .. php:method:out($message, $newlines, $level) .. php:method:err($message, $newlines) @@ -347,7 +347,7 @@ ConsoleOutput, por lo que no es necesario volver a declarar estilos para los objetos stdout y stderr. Desactivar la coloración -===================== +========================= Aunque el color es bonito, puede haber ocasiones en las que desees apagarlo o forzarlo: diff --git a/es/console-commands/option-parsers.rst b/es/console-commands/option-parsers.rst index a6bb97e188..9c9ac46111 100644 --- a/es/console-commands/option-parsers.rst +++ b/es/console-commands/option-parsers.rst @@ -1,5 +1,5 @@ Opcion de analizadores (Parsers) -############## +################################# .. php:namespace:: Cake\Console .. php:class:: ConsoleOptionParser @@ -8,7 +8,7 @@ Las aplicaciones de consola normalmente toman opciones y argumentos como la forma principal de obtener información del terminal en sus comandos. Definición de un OptionParser -======================== +============================= Los comandos y shells proporcionan un método de enlace ``buildOptionParser($parser)`` que puede utilizar para definir las opciones y @@ -179,7 +179,7 @@ Usando opciones booleanas Las opciones se pueden definir como opciones booleanas, que son útiles cuando necesitas crear algunas opciones de bandera. Al igual que las opciones con valores predeterminados, las opciones booleanas siempre se incluyen en los -parámetros analizados. Cuando las banderas están presentes, se establecen +parámetros analizados. Cuando las banderas están presentes, se establecen ``true``; cuando están ausentes, se establecen en ``false``:: $parser->addOption('verbose', [ @@ -255,7 +255,7 @@ mismo y que las opciones también deben ser compatibles para que funcione. Así que no utilices claves para cosas diferentes. Obtener ayuda de comandos -======================= +========================== Al definir sus opciones y argumentos con el analizador de opciones, CakePHP puede generar automáticamente información de ayuda rudimentaria y agregar @@ -344,7 +344,7 @@ se vería así: Personalización de salida de la ayuda -======================= +===================================== Puede enriquecer aún más el contenido de ayuda generado agregando una descripción y un epílogo. @@ -364,7 +364,7 @@ Al pasar una matriz o una cadena, puede establecer el valor de la descripción:: $parser->getDescription(); Establecer el epilogo --------------- +--------------------- .. php:method:: setEpilog($text) diff --git a/es/console-commands/plugin.rst b/es/console-commands/plugin.rst index 5584d0baf9..8318caac95 100644 --- a/es/console-commands/plugin.rst +++ b/es/console-commands/plugin.rst @@ -26,7 +26,7 @@ Esto agregará lo siguiente a su **src/Application.php**:: $this->addPlugin('MyPlugin'); Descarga de complementos ------------------ +------------------------ Puede descargar un complemento especificando su nombre: @@ -38,7 +38,7 @@ Esto eliminará la línea ``$this->addPlugin('MyPlugin',...)`` de **src/Application.php**. Activos del complemento (Assets) -------------- +--------------------------------- CakePHP sirve de forma predeterminada recursos de complementos utilizando el middleware ``AssetMiddleware``. Si bien esto es una buena conveniencia, se diff --git a/es/console-commands/routes.rst b/es/console-commands/routes.rst index 4df63147bf..57540214b8 100644 --- a/es/console-commands/routes.rst +++ b/es/console-commands/routes.rst @@ -1,5 +1,5 @@ Herramienta de enrutamiento (Routes) -########### +#################################### La herramienta de rutas proporciona una interfaz CLI fácil de usar para probar y depurar rutas. Puede usarlo para probar cómo se analizan las rutas y qué @@ -31,7 +31,7 @@ la URL entre comillas: Prueba de generación de URL --------------------------- -Puede ver la URL que generará :term:`routing array` usando el método ``generar``: +Puede ver la URL que generará :term:`arreglo de enrutamiento` usando el método ``generar``: .. code-block:: console diff --git a/es/console-commands/schema-cache.rst b/es/console-commands/schema-cache.rst index 38d5894e76..a66620f13a 100644 --- a/es/console-commands/schema-cache.rst +++ b/es/console-commands/schema-cache.rst @@ -1,5 +1,5 @@ Herramienta de esquemas de caché (Schema Cache) -################# +################################################ SchemaCacheShell proporciona una herramienta CLI sencilla para administrar las cachés de metadatos de su aplicación. En situaciones de implementación, resulta diff --git a/es/contents.rst b/es/contents.rst index 973e108a3e..58d174f95b 100644 --- a/es/contents.rst +++ b/es/contents.rst @@ -2,24 +2,27 @@ Contenidos ########## .. toctree:: - :hidden: + :hidden: - index + index .. toctree:: - :caption: Prólogo + :caption: Prefacio intro quickstart - appendices/4-0-migration-guide + appendices/migration-guides tutorials-and-examples contributing + release-policy .. toctree:: :caption: Comenzando installation development/configuration + development/application + development/dependency-injection development/routing controllers/request-response controllers/middleware @@ -30,9 +33,8 @@ Contenidos .. toctree:: :caption: Usando CakePHP - controllers/components/authentication core-libraries/caching - console-and-shells + console-commands development/debugging deployment core-libraries/email @@ -41,7 +43,7 @@ Contenidos core-libraries/internationalization-and-localization core-libraries/logging core-libraries/form - controllers/components/pagination + controllers/pagination plugins development/rest security @@ -50,28 +52,33 @@ Contenidos core-libraries/validation .. toctree:: - :caption: Clases de utilidad + :caption: Clases de Utilidad core-libraries/app core-libraries/collections - core-libraries/file-folder core-libraries/hash core-libraries/httpclient core-libraries/inflector core-libraries/number + core-libraries/plugin core-libraries/registry-objects core-libraries/text core-libraries/time core-libraries/xml .. toctree:: - :caption: Plugins - - Bake - Chronos - Debug Kit - migrations - elasticsearch + :caption: Plugins & Paquetes + + standalone-packages + Authentication + Authorization + Bake + Debug Kit + Migrations + Elasticsearch + Phinx + Chronos + Queue .. toctree:: :caption: Otros @@ -85,9 +92,12 @@ Contenidos topics chronos debug-kit + elasticsearch bake - bake/usage bake/development + bake/usage + migrations + phinx .. todolist:: diff --git a/es/controllers/components/csrf.rst b/es/controllers/components/csrf.rst deleted file mode 100644 index 2055c79598..0000000000 --- a/es/controllers/components/csrf.rst +++ /dev/null @@ -1,15 +0,0 @@ -Cross Site Request Forgery -########################## - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Csrf - :keywords lang=es: configurable parameters,security component,configuration parameters,invalid request,csrf,submission diff --git a/es/controllers/middleware.rst b/es/controllers/middleware.rst index f0ae2d006c..b1806c5e94 100644 --- a/es/controllers/middleware.rst +++ b/es/controllers/middleware.rst @@ -34,33 +34,263 @@ Middleware en CakePHP CakePHP proporciona varios middleware para manejar tareas comunes en aplicaciones web: * ``Cake\Error\Middleware\ErrorHandlerMiddleware`` atrapa las excepciones del middleware envuelto - y presenta una página de error usando el controlador de + y presenta una página de error usando el controlador de :doc:`/development/errors` excepciones de manejo de errores y excepciones. -* ``Cake\Routing\AssetMiddleware`` comprueba si la solicitud se refiere a un archivo - de tema o complemento, como un archivo CSS, JavaScript o de imagen almacenado en +* ``Cake\Routing\AssetMiddleware`` comprueba si la solicitud se refiere a un archivo + de tema o complemento, como un archivo CSS, JavaScript o de imagen almacenado en la carpeta webroot de un complemento o la correspondiente para un Tema. -* ``Cake\Routing\Middleware\RoutingMiddleware`` utiliza ``Router`` para analizar la URL entrante +* ``Cake\Routing\Middleware\RoutingMiddleware`` utiliza ``Router`` para analizar la URL entrante y asignar parámetros de enrutamiento a la solicitud. -* ``Cake\I18n\Middleware\LocaleSelectorMiddleware`` permite el cambio automático de idioma desde +* ``Cake\I18n\Middleware\LocaleSelectorMiddleware`` permite el cambio automático de idioma desde el ``Accept-Languageencabezado`` enviado por el navegador. * ``Cake\Http\Middleware\SecurityHeadersMiddleware`` facilita la adición de encabezados relacionados con la seguridad ``X-Frame-Options`` a las respuestas. -* ``Cake\Http\Middleware\EncryptedCookieMiddleware`` le brinda la capacidad de manipular cookies +* ``Cake\Http\Middleware\EncryptedCookieMiddleware`` le brinda la capacidad de manipular cookies encriptadas en caso de que necesite manipular las cookies con datos confusos. * ``Cake\Http\Middleware\CsrfProtectionMiddleware`` agrega protección CSRF a su aplicación. -* ``Cake\Http\Middleware\BodyParserMiddleware`` le permite decodificar JSON, XML y otros cuerpos +* ``Cake\Http\Middleware\BodyParserMiddleware`` le permite decodificar JSON, XML y otros cuerpos de solicitud codificados basados ​​en ``Content-Type`` del encabezado. +.. _using-middleware: + +Usando Middlewares +================== + +Los Middlewares pueden ser agregados a tu aplicación globalmente, a rutas específicas o incluso controladores. + +Para agregar un middleware a todos los requests, usa el método ``middleware`` de tu +clase ``App\Application``. Este método se llama al inicio del procesamiento del request. +Puedes usar el objeto ``MiddlewareQueue`` para agregar el middleware:: + + namespace App; + + use Cake\Http\BaseApplication; + use Cake\Http\MiddlewareQueue; + use Cake\Error\Middleware\ErrorHandlerMiddleware; + + class Application extends BaseApplication + { + public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue + { + // Agregar el manejador de errores en la cola de middlewares. + $middlewareQueue->add(new ErrorHandlerMiddleware()); + + // Agregar middleware por clase. + // Desde la versión 4.5.0 el nombre de la clase del middleware es + // resuelto opcionalmente usando el contener DI. Si la clase no es encontrada + // en el contenedor, entonces una instancia es creada por la cola de middlewares + $middlewareQueue->add(UserRateLimiting::class); + + return $middlewareQueue; + } + } + +Adicionalmente, aparte de agregarlo al final de la ``MiddlewareQueue`` tu puedes realizar distintas +operaciones:: + + $layer = new \App\Middleware\CustomMiddleware; + + // El middleware agregado será el último de la cola. + $middlewareQueue->add($layer); + + // El middleware agregado será el primero de la cola. + $middlewareQueue->prepend($layer); + + // Inserta el middleware en un lugar especifico. Si el lugar no existe, + // será agregado al final + $middlewareQueue->insertAt(2, $layer); + + // Inserta el middleware antes de otro. + // Si el middleware especificado no existe, + // se lanzará una excepción + $middlewareQueue->insertBefore( + 'Cake\Error\Middleware\ErrorHandlerMiddleware', + $layer + ); + + // Inserta después que otro middleware + // Si el middleware especificado no existe, + // el middleware will added to the end. + $middlewareQueue->insertAfter( + 'Cake\Error\Middleware\ErrorHandlerMiddleware', + $layer + ); + + +Si tu middleware solo es aplicable a un subconjunto de rutas o controladores especificos puedes usar +:ref:`Middleware por Rutas `, o :ref:`Middleware por Controlador `. + +Agregando Middleware desde un Plugin +------------------------------------- + +Los Plugins pueden usar su propio método ``middleware`` para agregar cualquier middleware que +implementen a la cola de middlewares de la aplicación:: + + // en plugins/ContactManager/src/Plugin.php + namespace ContactManager; + + use Cake\Core\BasePlugin; + use Cake\Http\MiddlewareQueue; + use ContactManager\Middleware\ContactManagerContextMiddleware; + + class Plugin extends BasePlugin + { + public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue + { + $middlewareQueue->add(new ContactManagerContextMiddleware()); + + return $middlewareQueue; + } + } + +Creaando un Middleware +====================== + +Un Middleware puede ser implementado mediante funciones anónimas (Closures), o clases que extiendan +a ``Psr\Http\Server\MiddlewareInterface``. Mientras que los Closures son apropiados para +tareas pequeñas, las pruebas se vuelven complicadas y puedes complicar aún más la clase +``Application``. Las clases middleware en CakePHP tienen algunasconvenciones: + +* Los archivos deben ubicarse en **src/Middleware**. Por ejemplo: + **src/Middleware/CorsMiddleware.php** +* Deben tener ``Middleware`` como sufijo. Por ejemplo: + ``LinkMiddleware``. +* Deben implementar la interfaz ``Psr\Http\Server\MiddlewareInterface``. + +Un Middleware puede devolver la respuesta llamando a ``$handler->handle()`` o +creando su propia respuesta. Podemos ver ambas opciones en el siguiente ejemplo:: + + // En src/Middleware/TrackingCookieMiddleware.php + namespace App\Middleware; + + use Cake\Http\Cookie\Cookie; + use Cake\I18n\Time; + use Psr\Http\Message\ResponseInterface; + use Psr\Http\Message\ServerRequestInterface; + use Psr\Http\Server\RequestHandlerInterface; + use Psr\Http\Server\MiddlewareInterface; + + class TrackingCookieMiddleware implements MiddlewareInterface + { + public function process( + ServerRequestInterface $request, + RequestHandlerInterface $handler + ): ResponseInterface + { + // Llamando $handler->handle() delega el control al siguiente middleware + // en la cola de tu aplicación. + $response = $handler->handle($request); + + if (!$request->getCookie('landing_page')) { + $expiry = new Time('+ 1 year'); + $response = $response->withCookie(new Cookie( + 'landing_page', + $request->getRequestTarget(), + $expiry + )); + } + + return $response; + } + } + +Ahora que hemos hecho un middleware bastante simple, agreguémoslo a nuestra aplicación:: + + // En src/Application.php + namespace App; + + use App\Middleware\TrackingCookieMiddleware; + use Cake\Http\MiddlewareQueue; + + class Application + { + public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue + { + // Agrega tu middleware a la cola + $middlewareQueue->add(new TrackingCookieMiddleware()); + + // Agrega más middlewares a la cola si lo deseas + + return $middlewareQueue; + } + } + + +.. _routing-middleware: + +Middleware Routing +================== + +El middleware de enrutamiento es responsable de procesar las rutas de tu aplicación e +identificar el plugin, controlador, y acción hacia la cual va un request:: + + // En Application.php + public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue + { + // ... + $middlewareQueue->add(new RoutingMiddleware($this)); + } + +.. _encrypted-cookie-middleware: + +Middleware EncryptedCookie +=========================== + +Si tu aplicación tiene cookies que contienen información que +quieres ofuscar y proteger, puedes usar el middleware de Cookies encriptadas +de CakePHP para encriptar y desencriptar de manera transparente la información +vía middleware. La información del Cookie es encriptada vía OpenSSL using AES:: + + use Cake\Http\Middleware\EncryptedCookieMiddleware; + + $cookies = new EncryptedCookieMiddleware( + // Names of cookies to protect + ['secrets', 'protected'], + Configure::read('Security.cookieKey') + ); + + $middlewareQueue->add($cookies); .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. + Se recomienda que la clave de encriptación que se utiliza para la información + del Cookie sea **exclusivamente** para esto. + +Los algoritmos de encriptación y el estilo de relleno usado por el middleware son retrocompatibles +con el ``CookieComponent`` de versiones anteriores de CakePHP. + +.. _body-parser-middleware: + +Middleware BodyParser +====================== - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +Si tu aplicación acepta JSON, XML o algún `request` de este tipo, el +``BodyParserMiddleware`` te permitirá decodificar esos `requests` en un arreglo que +estará disponible via ``$request->getParsedData()`` y ``$request->getData()``. Por defecto sólo +``json`` será procesado, pero el procesamiento XML puede ser activado como opción. +También puedes definir tus propios procesadores:: - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + use Cake\Http\Middleware\BodyParserMiddleware; + + // solo JSON será procesado + $bodies = new BodyParserMiddleware(); + + // Activar procesamiento XML + $bodies = new BodyParserMiddleware(['xml' => true]); + + // Desactivar procesamiento JSON + $bodies = new BodyParserMiddleware(['json' => false]); + + // Agregar tu propio procesador aplicándolo a un content-type + // específico y asignandole una funcion de procesamiento + $bodies = new BodyParserMiddleware(); + $bodies->addParser(['text/csv'], function ($body, $request) { + // Use a CSV parsing library. + return Csv::parse($body); + }); .. meta:: :title lang=es: Http Middleware :keywords lang=es: http, middleware, psr-7, request, response, wsgi, application, baseapplication + + + diff --git a/es/console-and-shells/helpers.rst b/es/controllers/pagination.rst similarity index 55% rename from es/console-and-shells/helpers.rst rename to es/controllers/pagination.rst index 32c2f07175..63c3a4a4ea 100644 --- a/es/console-and-shells/helpers.rst +++ b/es/controllers/pagination.rst @@ -1,11 +1,13 @@ -Shell Helpers -############# +Paginación +########## .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. + La documentación no es compatible actualmente con el idioma español en esta + página. Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + `Github `_ o utilizar el botón + **Improve this Doc** para proponer directamente los cambios. - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + Usted puede hacer referencia a la versión en Inglés en el menú de selección + superior para obtener información sobre el tema de esta página. diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index ea6cc2dad7..280d8cc7a4 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -1,20 +1,1199 @@ Request & Response Objects ########################## -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +.. php:namespace:: Cake\Http - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +The request and response objects provide an abstraction around HTTP requests and +responses. The request object in CakePHP allows you to introspect an incoming +request, while the response object allows you to effortlessly create HTTP +responses from your controllers. +.. index:: $this->request .. _cake-request: Request ======= +.. php:class:: ServerRequest + +``ServerRequest`` is the default request object used in CakePHP. It centralizes a +number of features for interrogating and interacting with request data. +On each request one Request is created and then passed by reference to the +various layers of an application that use request data. By default the request +is assigned to ``$this->request``, and is available in Controllers, Cells, Views +and Helpers. You can also access it in Components using the controller +reference. + +.. versionchanged:: 4.4.0 + The ``ServerRequest`` is available via DI. + So you can get it from container or use it as a dependency for your service. + +Some of the duties ``ServerRequest`` performs include: + +* Processing the GET, POST, and FILES arrays into the data structures you are + familiar with. +* Providing environment introspection pertaining to the request. Information + like the headers sent, the client's IP address, and the subdomain/domain + names the server your application is running on. +* Providing access to request parameters both as array indexes and object + properties. + +CakePHP's request object implements the `PSR-7 +ServerRequestInterface `_ making it easier to +use libraries from outside of CakePHP. + +.. _request-parameters: + +Request Parameters +------------------ + +The request exposes routing parameters through the ``getParam()`` method:: + + $controllerName = $this->request->getParam('controller'); + +To get all routing parameters as an array use ``getAttribute()``:: + + $parameters = $this->request->getAttribute('params'); + +All :ref:`route-elements` are accessed through this interface. + +In addition to :ref:`route-elements`, you also often need access to +:ref:`passed-arguments`. These are both available on the request object as +well:: + + // Passed arguments + $passedArgs = $this->request->getParam('pass'); + +Will all provide you access to the passed arguments. There +are several important/useful parameters that CakePHP uses internally, these +are also all found in the routing parameters: + +* ``plugin`` The plugin handling the request. Will be null when there is no + plugin. +* ``controller`` The controller handling the current request. +* ``action`` The action handling the current request. +* ``prefix`` The prefix for the current action. See :ref:`prefix-routing` for + more information. + +Query String Parameters +----------------------- + +.. php:method:: getQuery($name, $default = null) + +Query string parameters can be read using the ``getQuery()`` method:: + + // URL is /posts/index?page=1&sort=title + $page = $this->request->getQuery('page'); + +You can either directly access the query property, or you can use +``getQuery()`` method to read the URL query array in an error-free manner. +Any keys that do not exist will return ``null``:: + + $foo = $this->request->getQuery('value_that_does_not_exist'); + // $foo === null + + // You can also provide default values + $foo = $this->request->getQuery('does_not_exist', 'default val'); + +If you want to access all the query parameters you can use +``getQueryParams()``:: + + $query = $this->request->getQueryParams(); + +Request Body Data +----------------- + +.. php:method:: getData($name, $default = null) + +All POST data normally available through PHP's ``$_POST`` global variable can be +accessed using :php:meth:`Cake\\Http\\ServerRequest::getData()`. For example:: + + // An input with a name attribute equal to 'title' is accessible at + $title = $this->request->getData('title'); + +You can use a dot separated names to access nested data. For example:: + + $value = $this->request->getData('address.street_name'); + +For non-existent names the ``$default`` value will be returned:: + + $foo = $this->request->getData('value.that.does.not.exist'); + // $foo == null + +You can also use :ref:`body-parser-middleware` to parse request body of different +content types into an array, so that it's accessible through ``ServerRequest::getData()``. + +If you want to access all the data parameters you can use +``getParsedBody()``:: + + $data = $this->request->getParsedBody(); + +.. _request-file-uploads: + +File Uploads +------------ + +Uploaded files can be accessed through the request body data, using the :php:meth:`Cake\\Http\\ServerRequest::getData()` +method described above. For example, a file from an input element with a name attribute of ``attachment``, can +be accessed like this:: + + $attachment = $this->request->getData('attachment'); + +By default file uploads are represented in the request data as objects that implement +`\\Psr\\Http\\Message\\UploadedFileInterface `__. In the current +implementation, the ``$attachment`` variable in the above example would by default hold an instance of +``\Laminas\Diactoros\UploadedFile``. + +Accessing the uploaded file details is fairly simple, here's how you can obtain the same data as provided by the old +style file upload array:: + + $name = $attachment->getClientFilename(); + $type = $attachment->getClientMediaType(); + $size = $attachment->getSize(); + $tmpName = $attachment->getStream()->getMetadata('uri'); + $error = $attachment->getError(); + +Moving the uploaded file from its temporary location to the desired target +location, doesn't require manually accessing the temporary file, instead it can +be easily done by using the objects ``moveTo()`` method:: + + $attachment->moveTo($targetPath); + +In an HTTP environment, the ``moveTo()`` method will automatically validate +whether the file is an actual uploaded file, and throw an exception in case +necessary. In an CLI environment, where the concept of uploading files doesn't +exist, it will allow to move the file that you've referenced irrespective of its +origins, which makes testing file uploads possible. + +.. php:method:: getUploadedFile($path) + +Returns the uploaded file at a specific path. The path uses the same dot syntax as the +:php:meth:`Cake\\Http\\ServerRequest::getData()` method:: + + $attachment = $this->request->getUploadedFile('attachment'); + +Unlike :php:meth:`Cake\\Http\\ServerRequest::getData()`, :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` would +only return data when an actual file upload exists for the given path, if there is regular, non-file request body data +present at the given path, then this method will return ``null``, just like it would for any non-existent path. + +.. php:method:: getUploadedFiles() + +Returns all uploaded files in a normalized array structure. For the above example with the file input name of +``attachment``, the structure would look like:: + + [ + 'attachment' => object(Laminas\Diactoros\UploadedFile) { + // ... + } + ] + +.. php:method:: withUploadedFiles(array $files) + +This method sets the uploaded files of the request object, it accepts an array of objects that implement +`\\Psr\\Http\\Message\\UploadedFileInterface `__. It will +replace all possibly existing uploaded files:: + + $files = [ + 'MyModel' => [ + 'attachment' => new \Laminas\Diactoros\UploadedFile( + $streamOrFile, + $size, + $errorStatus, + $clientFilename, + $clientMediaType + ), + 'anotherAttachment' => new \Laminas\Diactoros\UploadedFile( + '/tmp/hfz6dbn.tmp', + 123, + \UPLOAD_ERR_OK, + 'attachment.txt', + 'text/plain' + ), + ], + ]; + + $this->request = $this->request->withUploadedFiles($files); + +.. note:: + + Uploaded files that have been added to the request via this method, will *not* be available in the request body + data, ie you cannot retrieve them via :php:meth:`Cake\\Http\\ServerRequest::getData()`! If you need them in the + request data (too), then you have to set them via :php:meth:`Cake\\Http\\ServerRequest::withData()` or + :php:meth:`Cake\\Http\\ServerRequest::withParsedBody()`. + +PUT, PATCH or DELETE Data +------------------------- + +.. php:method:: input($callback, [$options]) + +When building REST services, you often accept request data on ``PUT`` and +``DELETE`` requests. Any ``application/x-www-form-urlencoded`` request body data +will automatically be parsed and set to ``$this->data`` for ``PUT`` and +``DELETE`` requests. If you are accepting JSON or XML data, see below for how +you can access those request bodies. + +When accessing the input data, you can decode it with an optional function. +This is useful when interacting with XML or JSON request body content. +Additional parameters for the decoding function can be passed as arguments to +``input()``:: + + $jsonData = $this->request->input('json_decode'); + +Environment Variables (from $_SERVER and $_ENV) +----------------------------------------------- + +.. php:method:: putenv($key, $value = null) + +``ServerRequest::getEnv()`` is a wrapper for ``getenv()`` global function and acts as +a getter/setter for environment variables without having to modify globals +``$_SERVER`` and ``$_ENV``:: + + // Get the host + $host = $this->request->getEnv('HTTP_HOST'); + + // Set a value, generally helpful in testing. + $this->request->withEnv('REQUEST_METHOD', 'POST'); + +To access all the environment variables in a request use ``getServerParams()``:: + + $env = $this->request->getServerParams(); + +XML or JSON Data +---------------- + +Applications employing :doc:`/development/rest` often exchange data in +non-URL-encoded post bodies. You can read input data in any format using +:php:meth:`~Cake\\Http\\ServerRequest::input()`. By providing a decoding function, +you can receive the content in a deserialized format:: + + // Get JSON encoded data submitted to a PUT/POST action + $jsonData = $this->request->input('json_decode'); + +Some deserializing methods require additional parameters when called, such as +the 'as array' parameter on ``json_decode``. If you want XML converted into a +DOMDocument object, :php:meth:`~Cake\\Http\\ServerRequest::input()` supports +passing in additional parameters as well:: + + // Get XML encoded data submitted to a PUT/POST action + $data = $this->request->input('Cake\Utility\Xml::build', ['return' => 'domdocument']); + +Path Information +---------------- + +The request object also provides useful information about the paths in your +application. The ``base`` and ``webroot`` attributes are useful for +generating URLs, and determining whether or not your application is in a +subdirectory. The attributes you can use are:: + + // Assume the current request URL is /subdir/articles/edit/1?page=1 + + // Holds /subdir/articles/edit/1?page=1 + $here = $request->getRequestTarget(); + + // Holds /subdir + $base = $request->getAttribute('base'); + + // Holds /subdir/ + $base = $request->getAttribute('webroot'); + +.. _check-the-request: + +Checking Request Conditions +--------------------------- + +.. php:method:: is($type, $args...) + +The request object provides a way to inspect certain conditions in a given +request. By using the ``is()`` method you can check a number of common +conditions, as well as inspect other application specific request criteria:: + + $isPost = $this->request->is('post'); + +You can also extend the request detectors that are available, by using +:php:meth:`Cake\\Http\\ServerRequest::addDetector()` to create new kinds of +detectors. There are different types of detectors that you can create: + +* Environment value comparison - Compares a value fetched from :php:func:`env()` + for equality with the provided value. +* Header value comparison - If the specified header exists with the specified + value, or if the callable returns true. +* Pattern value comparison - Pattern value comparison allows you to compare a + value fetched from :php:func:`env()` to a regular expression. +* Option based comparison - Option based comparisons use a list of options to + create a regular expression. Subsequent calls to add an already defined + options detector will merge the options. +* Callback detectors - Callback detectors allow you to provide a 'callback' type + to handle the check. The callback will receive the request object as its only + parameter. + +.. php:method:: addDetector($name, $options) + +Some examples would be:: + + // Add an environment detector. + $this->request->addDetector( + 'post', + ['env' => 'REQUEST_METHOD', 'value' => 'POST'] + ); + + // Add a pattern value detector. + $this->request->addDetector( + 'iphone', + ['env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i'] + ); + + // Add an option detector + $this->request->addDetector('internalIp', [ + 'env' => 'CLIENT_IP', + 'options' => ['192.168.0.101', '192.168.0.100'] + ]); + + + // Add a header detector with value comparison + $this->request->addDetector('fancy', [ + 'env' => 'CLIENT_IP', + 'header' => ['X-Fancy' => 1] + ]); + + // Add a header detector with callable comparison + $this->request->addDetector('fancy', [ + 'env' => 'CLIENT_IP', + 'header' => ['X-Fancy' => function ($value, $header) { + return in_array($value, ['1', '0', 'yes', 'no'], true); + }] + ]); + + // Add a callback detector. Must be a valid callable. + $this->request->addDetector( + 'awesome', + function ($request) { + return $request->getParam('awesome'); + } + ); + + // Add a detector that uses additional arguments. + $this->request->addDetector( + 'csv', + [ + 'accept' => ['text/csv'], + 'param' => '_ext', + 'value' => 'csv', + ] + ); + +There are several built-in detectors that you can use: + +* ``is('get')`` Check to see whether the current request is a GET. +* ``is('put')`` Check to see whether the current request is a PUT. +* ``is('patch')`` Check to see whether the current request is a PATCH. +* ``is('post')`` Check to see whether the current request is a POST. +* ``is('delete')`` Check to see whether the current request is a DELETE. +* ``is('head')`` Check to see whether the current request is HEAD. +* ``is('options')`` Check to see whether the current request is OPTIONS. +* ``is('ajax')`` Check to see whether the current request came with + X-Requested-With = XMLHttpRequest. +* ``is('ssl')`` Check to see whether the request is via SSL. +* ``is('flash')`` Check to see whether the request has a User-Agent of Flash. +* ``is('json')`` Check to see whether the request has 'json' extension and + accept 'application/json' mimetype. +* ``is('xml')`` Check to see whether the request has 'xml' extension and accept + 'application/xml' or 'text/xml' mimetype. + +``ServerRequest`` also includes methods like +:php:meth:`Cake\\Http\\ServerRequest::domain()`, +:php:meth:`Cake\\Http\\ServerRequest::subdomains()` and +:php:meth:`Cake\\Http\\ServerRequest::host()` to make applications that use +subdomains simpler. + +Session Data +------------ + +To access the session for a given request use the ``getSession()`` method or use the ``session`` attribute:: + + $session = $this->request->getSession(); + $session = $this->request->getAttribute('session'); + + $data = $session->read('sessionKey'); + +For more information, see the :doc:`/development/sessions` documentation for how +to use the session object. + +Host and Domain Name +-------------------- + +.. php:method:: domain($tldLength = 1) + +Returns the domain name your application is running on:: + + // Prints 'example.org' + echo $request->domain(); + +.. php:method:: subdomains($tldLength = 1) + +Returns the subdomains your application is running on as an array:: + + // Returns ['my', 'dev'] for 'my.dev.example.org' + $subdomains = $request->subdomains(); + +.. php:method:: host() + +Returns the host your application is on:: + + // Prints 'my.dev.example.org' + echo $request->host(); + +Reading the HTTP Method +----------------------- + +.. php:method:: getMethod() + +Returns the HTTP method the request was made with:: + + // Output POST + echo $request->getMethod(); + +Restricting Which HTTP method an Action Accepts +----------------------------------------------- + +.. php:method:: allowMethod($methods) + +Set allowed HTTP methods. If not matched, will throw +``MethodNotAllowedException``. The 405 response will include the required +``Allow`` header with the passed methods:: + + public function delete() + { + // Only accept POST and DELETE requests + $this->request->allowMethod(['post', 'delete']); + ... + } + +Reading HTTP Headers +-------------------- + +Allows you to access any of the ``HTTP_*`` headers that were used +for the request. For example:: + + // Get the header as a string + $userAgent = $this->request->getHeaderLine('User-Agent'); + + // Get an array of all values. + $acceptHeader = $this->request->getHeader('Accept'); + + // Check if a header exists + $hasAcceptHeader = $this->request->hasHeader('Accept'); + +While some apache installs don't make the ``Authorization`` header accessible, +CakePHP will make it available through apache specific methods as required. + +.. php:method:: referer($local = true) + +Returns the referring address for the request. + +.. php:method:: clientIp() + +Returns the current visitor's IP address. + +Trusting Proxy Headers +---------------------- + +If your application is behind a load balancer or running on a cloud service, you +will often get the load balancer host, port and scheme in your requests. Often +load balancers will also send ``HTTP-X-Forwarded-*`` headers with the original +values. The forwarded headers will not be used by CakePHP out of the box. To +have the request object use these headers set the ``trustProxy`` property to +``true``:: + + $this->request->trustProxy = true; + + // These methods will now use the proxied headers. + $port = $this->request->port(); + $host = $this->request->host(); + $scheme = $this->request->scheme(); + $clientIp = $this->request->clientIp(); + +Once proxies are trusted the ``clientIp()`` method will use the *last* IP +address in the ``X-Forwarded-For`` header. If your application is behind +multiple proxies, you can use ``setTrustedProxies()`` to define the IP addresses +of proxies in your control:: + + $request->setTrustedProxies(['127.1.1.1', '127.8.1.3']); + +After proxies are trusted ``clientIp()`` will use the first IP address in the +``X-Forwarded-For`` header providing it is the only value that isn't from a trusted +proxy. + +Checking Accept Headers +----------------------- + +.. php:method:: accepts($type = null) + +Find out which content types the client accepts, or check whether it accepts a +particular type of content. + +Get all types:: + + $accepts = $this->request->accepts(); + +Check for a single type:: + + $acceptsJson = $this->request->accepts('application/json'); + +.. php:method:: acceptLanguage($language = null) + +Get all the languages accepted by the client, +or check whether a specific language is accepted. + +Get the list of accepted languages:: + + $acceptsLanguages = $this->request->acceptLanguage(); + +Check whether a specific language is accepted:: + + $acceptsSpanish = $this->request->acceptLanguage('es-es'); + +.. _request-cookies: + +Reading Cookies +--------------- + +Request cookies can be read through a number of methods:: + + // Get the cookie value, or null if the cookie is missing. + $rememberMe = $this->request->getCookie('remember_me'); + + // Read the value, or get the default of 0 + $rememberMe = $this->request->getCookie('remember_me', 0); + + // Get all cookies as an hash + $cookies = $this->request->getCookieParams(); + + // Get a CookieCollection instance + $cookies = $this->request->getCookieCollection() + +See the :php:class:`Cake\\Http\\Cookie\\CookieCollection` documentation for how +to work with cookie collection. + + +Uploaded Files +-------------- + +Requests expose the uploaded file data in ``getData()`` or +``getUploadedFiles()`` as ``UploadedFileInterface`` objects:: + + // Get a list of UploadedFile objects + $files = $request->getUploadedFiles(); + + // Read the file data. + $files[0]->getStream(); + $files[0]->getSize(); + $files[0]->getClientFileName(); + + // Move the file. + $files[0]->moveTo($targetPath); + +Manipulating URIs +----------------- + +Requests contain a URI object, which contains methods for interacting with the +requested URI:: + + // Get the URI + $uri = $request->getUri(); + + // Read data out of the URI. + $path = $uri->getPath(); + $query = $uri->getQuery(); + $host = $uri->getHost(); + + +.. index:: $this->response + +Response +======== + +.. php:class:: Response + +:php:class:`Cake\\Http\\Response` is the default response class in CakePHP. +It encapsulates a number of features and functionality for generating HTTP +responses in your application. It also assists in testing, as it can be +mocked/stubbed allowing you to inspect headers that will be sent. + +``Response`` provides an interface to wrap the common response-related +tasks such as: + +* Sending headers for redirects. +* Sending content type headers. +* Sending any header. +* Sending the response body. + +Dealing with Content Types +-------------------------- + +.. php:method:: withType($contentType = null) + +You can control the Content-Type of your application's responses with +:php:meth:`Cake\\Http\\Response::withType()`. If your application needs to deal +with content types that are not built into Response, you can map them with +``setTypeMap()`` as well:: + + // Add a vCard type + $this->response->setTypeMap('vcf', ['text/v-card']); + + // Set the response Content-Type to vcard. + $this->response = $this->response->withType('vcf'); + +Usually, you'll want to map additional content types in your controller's +:php:meth:`~Controller::beforeFilter()` callback, so you can leverage the +automatic view switching features of :php:class:`RequestHandlerComponent` if you +are using it. + +.. _cake-response-file: + +Sending Files +------------- + +.. php:method:: withFile(string $path, array $options = []) + +There are times when you want to send files as responses for your requests. +You can accomplish that by using :php:meth:`Cake\\Http\\Response::withFile()`:: + + public function sendFile($id) + { + $file = $this->Attachments->getFile($id); + $response = $this->response->withFile($file['path']); + // Return the response to prevent controller from trying to render + // a view. + return $response; + } + +As shown in the above example, you must pass the file path to the method. +CakePHP will send a proper content type header if it's a known file type listed +in `Cake\\Http\\Response::$_mimeTypes`. You can add new types prior to calling +:php:meth:`Cake\\Http\\Response::withFile()` by using the +:php:meth:`Cake\\Http\\Response::withType()` method. + +If you want, you can also force a file to be downloaded instead of displayed in +the browser by specifying the options:: + + $response = $this->response->withFile( + $file['path'], + ['download' => true, 'name' => 'foo'] + ); + +The supported options are: + +name + The name allows you to specify an alternate file name to be sent to + the user. +download + A boolean value indicating whether headers should be set to force + download. + +Sending a String as File +------------------------ + +You can respond with a file that does not exist on the disk, such as a pdf or an +ics generated on the fly from a string:: + + public function sendIcs() + { + $icsString = $this->Calendars->generateIcs(); + $response = $this->response; + + // Inject string content into response body + $response = $response->withStringBody($icsString); + + $response = $response->withType('ics'); + + // Optionally force file download + $response = $response->withDownload('filename_for_download.ics'); + + // Return response object to prevent controller from trying to render + // a view. + return $response; + } + +Setting Headers +--------------- + +.. php:method:: withHeader($header, $value) + +Setting headers is done with the :php:meth:`Cake\\Http\\Response::withHeader()` +method. Like all of the PSR-7 interface methods, this method returns a *new* +instance with the new header:: + + // Add/replace a header + $response = $response->withHeader('X-Extra', 'My header'); + + // Set multiple headers + $response = $response->withHeader('X-Extra', 'My header') + ->withHeader('Location', 'http://example.com'); + + // Append a value to an existing header + $response = $response->withAddedHeader('Set-Cookie', 'remember_me=1'); + +Headers are not sent when set. Instead, they are held until the response is +emitted by ``Cake\Http\Server``. + +You can now use the convenience method +:php:meth:`Cake\\Http\\Response::withLocation()` to directly set or get the +redirect location header. + +Setting the Body +---------------- + +.. php:method:: withStringBody($string) + +To set a string as the response body, do the following:: + + // Set a string into the body + $response = $response->withStringBody('My Body'); + + // If you want a json response + $response = $response->withType('application/json') + ->withStringBody(json_encode(['Foo' => 'bar'])); + +.. php:method:: withBody($body) + +To set the response body, use the ``withBody()`` method, which is provided by the +:php:class:`Laminas\\Diactoros\\MessageTrait`:: + + $response = $response->withBody($stream); + +Be sure that ``$stream`` is a :php:class:`Psr\\Http\\Message\\StreamInterface` object. +See below on how to create a new stream. + +You can also stream responses from files using :php:class:`Laminas\\Diactoros\\Stream` streams:: + + // To stream from a file + use Laminas\Diactoros\Stream; + + $stream = new Stream('/path/to/file', 'rb'); + $response = $response->withBody($stream); + +You can also stream responses from a callback using the ``CallbackStream``. This +is useful when you have resources like images, CSV files or PDFs you need to +stream to the client:: + + // Streaming from a callback + use Cake\Http\CallbackStream; + + // Create an image. + $img = imagecreate(100, 100); + // ... + + $stream = new CallbackStream(function () use ($img) { + imagepng($img); + }); + $response = $response->withBody($stream); + +Setting the Character Set +------------------------- + +.. php:method:: withCharset($charset) + +Sets the charset that will be used in the response:: + + $this->response = $this->response->withCharset('UTF-8'); + +Interacting with Browser Caching +-------------------------------- + +.. php:method:: withDisabledCache() + +You sometimes need to force browsers not to cache the results of a controller +action. :php:meth:`Cake\\Http\\Response::withDisabledCache()` is intended for just +that:: + + public function index() + { + // Disable caching + $this->response = $this->response->withDisabledCache(); + } + +.. warning:: + + Disabling caching from SSL domains while trying to send + files to Internet Explorer can result in errors. + +.. php:method:: withCache($since, $time = '+1 day') + +You can also tell clients that you want them to cache responses. By using +:php:meth:`Cake\\Http\\Response::withCache()`:: + + public function index() + { + // Enable caching + $this->response = $this->response->withCache('-1 minute', '+5 days'); + } + +The above would tell clients to cache the resulting response for 5 days, +hopefully speeding up your visitors' experience. +The ``withCache()`` method sets the ``Last-Modified`` value to the first +argument. ``Expires`` header and the ``max-age`` directive are set based on the +second parameter. Cache-Control's ``public`` directive is set as well. + +.. _cake-response-caching: + +Fine Tuning HTTP Cache +---------------------- + +One of the best and easiest ways of speeding up your application is to use HTTP +cache. Under this caching model, you are only required to help clients decide if +they should use a cached copy of the response by setting a few headers such as +modified time and response entity tag. + +Rather than forcing you to code the logic for caching and for invalidating +(refreshing) it once the data has changed, HTTP uses two models, expiration and +validation, which usually are much simpler to use. + +Apart from using :php:meth:`Cake\\Http\\Response::withCache()`, you can also use +many other methods to fine-tune HTTP cache headers to take advantage of browser +or reverse proxy caching. + +The Cache Control Header +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. php:method:: withSharable($public, $time = null) + +Used under the expiration model, this header contains multiple indicators that +can change the way browsers or proxies use the cached content. A +``Cache-Control`` header can look like this:: + + Cache-Control: private, max-age=3600, must-revalidate + +``Response`` class helps you set this header with some utility methods that will +produce a final valid ``Cache-Control`` header. The first is the +``withSharable()`` method, which indicates whether a response is to be +considered sharable across different users or clients. This method actually +controls the ``public`` or ``private`` part of this header. Setting a response +as private indicates that all or part of it is intended for a single user. To +take advantage of shared caches, the control directive must be set as public. + +The second parameter of this method is used to specify a ``max-age`` for the +cache, which is the number of seconds after which the response is no longer +considered fresh:: + + public function view() + { + // ... + // Set the Cache-Control as public for 3600 seconds + $this->response = $this->response->withSharable(true, 3600); + } + + public function my_data() + { + // ... + // Set the Cache-Control as private for 3600 seconds + $this->response = $this->response->withSharable(false, 3600); + } + +``Response`` exposes separate methods for setting each of the directives in +the ``Cache-Control`` header. + +The Expiration Header +~~~~~~~~~~~~~~~~~~~~~ + +.. php:method:: withExpires($time) + +You can set the ``Expires`` header to a date and time after which the response +is no longer considered fresh. This header can be set using the +``withExpires()`` method:: + + public function view() + { + $this->response = $this->response->withExpires('+5 days'); + } + +This method also accepts a :php:class:`DateTime` instance or any string that can +be parsed by the :php:class:`DateTime` class. + +The Etag Header +~~~~~~~~~~~~~~~ + +.. php:method:: withEtag($tag, $weak = false) + +Cache validation in HTTP is often used when content is constantly changing, and +asks the application to only generate the response contents if the cache is no +longer fresh. Under this model, the client continues to store pages in the +cache, but it asks the application every time +whether the resource has changed, instead of using it directly. +This is commonly used with static resources such as images and other assets. + +The ``withEtag()`` method (called entity tag) is a string +that uniquely identifies the requested resource, as a checksum does for a file, +in order to determine whether it matches a cached resource. + +To take advantage of this header, you must either call the +``checkNotModified()`` method manually or include the +:doc:`/controllers/components/check-http-cache` in your controller:: + + public function index() + { + $articles = $this->Articles->find('all')->all(); + + // Simple checksum of the article contents. + // You should use a more efficient implementation + // in a real world application. + $checksum = md5(json_encode($articles)); + + $response = $this->response->withEtag($checksum); + if ($response->checkNotModified($this->request)) { + return $response; + } + + $this->response = $response; + // ... + } + +.. note:: + + Most proxy users should probably consider using the Last Modified Header + instead of Etags for performance and compatibility reasons. + +The Last Modified Header +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. php:method:: withModified($time) + +Also, under the HTTP cache validation model, you can set the ``Last-Modified`` +header to indicate the date and time at which the resource was modified for the +last time. Setting this header helps CakePHP tell caching clients whether the +response was modified or not based on their cache. + +To take advantage of this header, you must either call the +``checkNotModified()`` method manually or include the +:doc:`/controllers/components/check-http-cache` in your controller:: + + public function view() + { + $article = $this->Articles->find()->first(); + $response = $this->response->withModified($article->modified); + if ($response->checkNotModified($this->request)) { + return $response; + } + $this->response; + // ... + } + +The Vary Header +~~~~~~~~~~~~~~~ + +.. php:method:: withVary($header) + +In some cases, you might want to serve different content using the same URL. +This is often the case if you have a multilingual page or respond with different +HTML depending on the browser. Under such circumstances you can use the ``Vary`` +header:: + + $response = $this->response->withVary('User-Agent'); + $response = $this->response->withVary('Accept-Encoding', 'User-Agent'); + $response = $this->response->withVary('Accept-Language'); + +Sending Not-Modified Responses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. php:method:: checkNotModified(Request $request) + +Compares the cache headers for the request object with the cache header from the +response and determines whether it can still be considered fresh. If so, deletes +the response content, and sends the `304 Not Modified` header:: + + // In a controller action. + if ($this->response->checkNotModified($this->request)) { + return $this->response; + } + +.. _response-cookies: + +Setting Cookies +--------------- + +Cookies can be added to response using either an array or a :php:class:`Cake\\Http\\Cookie\\Cookie` +object:: + + use Cake\Http\Cookie\Cookie; + use DateTime; + + // Add a cookie + $this->response = $this->response->withCookie(Cookie::create( + 'remember_me', + 'yes', + // All keys are optional + [ + 'expires' => new DateTime('+1 year'), + 'path' => '', + 'domain' => '', + 'secure' => false, + 'httponly' => false, + 'samesite' => null // Or one of CookieInterface::SAMESITE_* constants + ] + )); + +See the :ref:`creating-cookies` section for how to use the cookie object. You +can use ``withExpiredCookie()`` to send an expired cookie in the response. This +will make the browser remove its local cookie:: + + $this->response = $this->response->withExpiredCookie(new Cookie('remember_me')); + +.. _cors-headers: + +Setting Cross Origin Request Headers (CORS) +=========================================== + +The ``cors()`` method is used to define `HTTP Access Control +`__ +related headers with a fluent interface:: + + $this->response = $this->response->cors($this->request) + ->allowOrigin(['*.cakephp.org']) + ->allowMethods(['GET', 'POST']) + ->allowHeaders(['X-CSRF-Token']) + ->allowCredentials() + ->exposeHeaders(['Link']) + ->maxAge(300) + ->build(); + +CORS related headers will only be applied to the response if the following +criteria are met: + +#. The request has an ``Origin`` header. +#. The request's ``Origin`` value matches one of the allowed Origin values. + +.. tip:: + + CakePHP has no built-in CORS middleware because dealing with CORS requests + is very application specific. We recommend you build your own ``CORSMiddleware`` + if you need one and adjust the response object as desired. + +Common Mistakes with Immutable Responses +======================================== + +Response objects offer a number of methods that treat +responses as immutable objects. Immutable objects help prevent difficult to +track accidental side-effects, and reduce mistakes caused by method calls caused +by refactoring that change ordering. While they offer a number of benefits, +immutable objects can take some getting used to. Any method that starts with +``with`` operates on the response in an immutable fashion, and will **always** +return a **new** instance. Forgetting to retain the modified instance is the most +frequent mistake people make when working with immutable objects:: + + $this->response->withHeader('X-CakePHP', 'yes!'); + +In the above code, the response will be lacking the ``X-CakePHP`` header, as the +return value of the ``withHeader()`` method was not retained. To correct the +above code you would write:: + + $this->response = $this->response->withHeader('X-CakePHP', 'yes!'); + +.. php:namespace:: Cake\Http\Cookie + +Cookie Collections +================== + +.. php:class:: CookieCollection + +``CookieCollection`` objects are accessible from the request and response objects. +They let you interact with groups of cookies using immutable patterns, which +allow the immutability of the request and response to be preserved. + +.. _creating-cookies: + +Creating Cookies +---------------- + +.. php:class:: Cookie + +``Cookie`` objects can be defined through constructor objects, or by using the +fluent interface that follows immutable patterns:: + + use Cake\Http\Cookie\Cookie; + + // All arguments in the constructor + $cookie = new Cookie( + 'remember_me', // name + 1, // value + new DateTime('+1 year'), // expiration time, if applicable + '/', // path, if applicable + 'example.com', // domain, if applicable + false, // secure only? + true // http only ? + ); + + // Using the builder methods + $cookie = (new Cookie('remember_me')) + ->withValue('1') + ->withExpiry(new DateTime('+1 year')) + ->withPath('/') + ->withDomain('example.com') + ->withSecure(false) + ->withHttpOnly(true); + +Once you have created a cookie, you can add it to a new or existing +``CookieCollection``:: + + use Cake\Http\Cookie\CookieCollection; + + // Create a new collection + $cookies = new CookieCollection([$cookie]); + + // Add to an existing collection + $cookies = $cookies->add($cookie); + + // Remove a cookie by name + $cookies = $cookies->remove('remember_me'); + +.. note:: + Remember that collections are immutable and adding cookies into, or removing + cookies from a collection, creates a *new* collection object. + +Cookie objects can be added to responses:: + + // Add one cookie + $response = $this->response->withCookie($cookie); + + // Replace the entire cookie collection + $response = $this->response->withCookieCollection($cookies); + +Cookies set to responses can be encrypted using the +:ref:`encrypted-cookie-middleware`. + +Reading Cookies +--------------- + +Once you have a ``CookieCollection`` instance, you can access the cookies it +contains:: + + // Check if a cookie exists + $cookies->has('remember_me'); + + // Get the number of cookies in the collection + count($cookies); + + // Get a cookie instance. Will throw an error if the cookie is not found + $cookie = $cookies->get('remember_me'); + + // Get a cookie or null + $cookie = $cookies->remember_me; + + // Check if a cookie exists + $exists = isset($cookies->remember_me) + +Once you have a ``Cookie`` object you can interact with it's state and modify +it. Keep in mind that cookies are immutable, so you'll need to update the +collection if you modify a cookie:: + + // Get the value + $value = $cookie->getValue() + + // Access data inside a JSON value + $id = $cookie->read('User.id'); + + // Check state + $cookie->isHttpOnly(); + $cookie->isSecure(); + .. meta:: - :title lang=es: Request and Response objects - :keywords lang=es: request controller,request parameters,array indexes,purpose index,response objects,domain information,request object,request data,interrogating,params,parameters,previous versions,introspection,dispatcher,rout,data structures,arrays,ip address,migration,indexes,cakephp + :title lang=es: Objetos Request y Response + :keywords lang=en: request controller,request parameters,array indexes,purpose index,response objects,domain information,request object,request data,interrogating,params,parameters,previous versions,introspection,dispatcher,rout,data structures,arrays,ip address,migration,indexes,cakephp,PSR-7,immutable diff --git a/es/core-libraries/caching.rst b/es/core-libraries/caching.rst index 482822a995..45eec8b243 100644 --- a/es/core-libraries/caching.rst +++ b/es/core-libraries/caching.rst @@ -18,7 +18,7 @@ En CakePHP, el almacenamiento en caché se facilita mediante la clase ``Cache``. Independientemente del motor de caché que elijas usar, tu aplicación interactúa con :php:class:`Cake\\Cache\\Cache`. -.. _configuracion-caché: +.. _cache-configuration: Configuración de los Motores de Caché ====================================== @@ -125,7 +125,7 @@ FileEngine utiliza las siguientes opciones específicas del motor: - ``mask``: la máscara utilizada para los archivos creados. - ``path``: ruta donde deben guardarse los archivos de caché. Por defecto, es el directorio temporal del sistema. -.. _motor-redisengine: +.. _caching-redisengine: Opciones del Motor RedisEngine ------------------------------ diff --git a/es/core-libraries/file-folder.rst b/es/core-libraries/file-folder.rst deleted file mode 100644 index 5ed8e5803b..0000000000 --- a/es/core-libraries/file-folder.rst +++ /dev/null @@ -1,16 +0,0 @@ -Folder & File -############# - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Folder & File - :description lang=es: The Folder and File utilities are convenience classes to help you read, write, and append to files; list files within a folder and other common directory related tasks. - :keywords lang=es: file,folder,cakephp utility,read file,write file,append file,recursively copy,copy options,folder path,class folder,file php,php files,change directory,file utilities,new folder,directory structure,delete file diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index 9b2206f53e..e645f7ccee 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -1,16 +1,500 @@ Logging ####### +While CakePHP core Configure Class settings can really help you see +what's happening under the hood, there are certain times that +you'll need to log data to the disk in order to find out what's +going on. With technologies like SOAP, AJAX, and REST APIs, debugging can be +rather difficult. + +Logging can also be a way to find out what's been going on in your +application over time. What search terms are being used? What sorts +of errors are my users being shown? How often is a particular query +being executed? + +Logging data in CakePHP is done with the ``log()`` function. It is provided by the +``LogTrait``, which is the common ancestor for many CakePHP classes. If the +context is a CakePHP class (Controller, Component, View,...), you can log your +data. You can also use ``Log::write()`` directly. See :ref:`writing-to-logs`. + +.. _log-configuration: + +Logging Configuration +===================== + +Configuring ``Log`` should be done during your application's bootstrap phase. +The **config/app.php** file is intended for just this. You can define +as many or as few loggers as your application needs. Loggers should be +configured using :php:class:`Cake\\Log\\Log`. An example would be:: + + use Cake\Log\Engine\FileLog; + use Cake\Log\Log; + + // Classname using logger 'class' constant + Log::setConfig('info', [ + 'className' => FileLog::class, + 'path' => LOGS, + 'levels' => ['info'], + 'file' => 'info', + ]); + + // Short classname + Log::setConfig('debug', [ + 'className' => 'File', + 'path' => LOGS, + 'levels' => ['notice', 'debug'], + 'file' => 'debug', + ]); + + // Fully namespaced name. + Log::setConfig('error', [ + 'className' => 'Cake\Log\Engine\FileLog', + 'path' => LOGS, + 'levels' => ['warning', 'error', 'critical', 'alert', 'emergency'], + 'file' => 'error', + ]); + +The above creates three loggers, named ``info``, ``debug`` and ``error``. +Each is configured to handle different levels of messages. They also store their +log messages in separate files, so we can separate debug/notice/info logs +from more serious errors. See the section on :ref:`logging-levels` for more +information on the different levels and what they mean. + +Once a configuration is created you cannot change it. Instead you should drop +the configuration and re-create it using :php:meth:`Cake\\Log\\Log::drop()` and +:php:meth:`Cake\\Log\\Log::setConfig()`. + +It is also possible to create loggers by providing a closure. This is useful +when you need full control over how the logger object is built. The closure +has to return the constructed logger instance. For example:: + + Log::setConfig('special', function () { + return new \Cake\Log\Engine\FileLog(['path' => LOGS, 'file' => 'log']); + }); + +Configuration options can also be provided as a :term:`DSN` string. This is +useful when working with environment variables or :term:`PaaS` providers:: + + Log::setConfig('error', [ + 'url' => 'file:///full/path/to/logs/?levels[]=warning&levels[]=error&file=error', + ]); + +.. warning:: + If you do not configure logging engines, log messages will not be stored. + +Error and Exception Logging +=========================== + +Errors and Exceptions can also be logged. By configuring the corresponding +values in your **config/app.php** file. Errors will be displayed when debug is +``true`` and logged when debug is ``false``. To log uncaught exceptions, set the +``log`` option to ``true``. See :doc:`/development/configuration` for more +information. + +.. _writing-to-logs: + +Writing to Logs +=============== + +Writing to the log files can be done in two different ways. The first +is to use the static :php:meth:`Cake\\Log\\Log::write()` method:: + + Log::write('debug', 'Something did not work'); + +The second is to use the ``log()`` shortcut function available on any +class using the ``LogTrait``. Calling ``log()`` will internally call +``Log::write()``:: + + // Executing this inside a class using LogTrait + $this->log('Something did not work!', 'debug'); + +All configured log streams are written to sequentially each time +:php:meth:`Cake\\Log\\Log::write()` is called. If you have not configured any +logging engines ``log()`` will return ``false`` and no log messages will be +written. + +Using Placeholders in Messages +------------------------------ + +If you need to log dynamically defined data, you can use placeholders in your +log messages and provide an array of key/value pairs in the ``$context`` +parameter:: + + // Will log `Could not process for userid=1` + Log::write('error', 'Could not process for userid={user}', ['user' => $user->id]); + +Placeholders that do not have keys defined will not be replaced. If you need to +use a literal braced word, you must escape the placeholder:: + + // Will log `No {replace}` + Log::write('error', 'No \\{replace}', ['replace' => 'no']); + +If you include objects in your logging placeholders those objects must implement +one of the following methods: + +* ``__toString()`` +* ``toArray()`` +* ``__debugInfo()`` + +.. _logging-levels: + +Using Levels +------------ + +CakePHP supports the standard POSIX set of logging levels. Each level represents +an increasing level of severity: + +* Emergency: system is unusable +* Alert: action must be taken immediately +* Critical: critical conditions +* Error: error conditions +* Warning: warning conditions +* Notice: normal but significant condition +* Info: informational messages +* Debug: debug-level messages + +You can refer to these levels by name when configuring loggers, and when writing +log messages. Alternatively, you can use convenience methods like +:php:meth:`Cake\\Log\\Log::error()` to clearly indicate the logging +level. Using a level that is not in the above levels will result in an +exception. + +.. note:: + When ``levels`` is set to an empty value in a logger's configuration, it + will take messages of any level. + +.. _logging-scopes: + +Logging Scopes +-------------- + +Often times you'll want to configure different logging behavior for different +subsystems or parts of your application. Take for example an e-commerce shop. +You'll probably want to handle logging for orders and payments differently than +you do other less critical logs. + +CakePHP exposes this concept as logging scopes. When log messages are written +you can include a scope name. If there is a configured logger for that scope, +the log messages will be directed to those loggers. For example:: + + use Cake\Log\Engine\FileLog; + + // Configure logs/shops.log to receive all levels, but only + // those with `orders` and `payments` scope. + Log::setConfig('shops', [ + 'className' => FileLog::class, + 'path' => LOGS, + 'levels' => [], + 'scopes' => ['orders', 'payments'], + 'file' => 'shops.log', + ]); + + // Configure logs/payments.log to receive all levels, but only + // those with `payments` scope. + Log::setConfig('payments', [ + 'className' => FileLog::class, + 'path' => LOGS, + 'levels' => [], + 'scopes' => ['payments'], + 'file' => 'payments.log', + ]); + + Log::warning('this gets written only to shops.log', ['scope' => ['orders']]); + Log::warning('this gets written to both shops.log and payments.log', ['scope' => ['payments']]); + +Scopes can also be passed as a single string or a numerically indexed array. +Note that using this form will limit the ability to pass more data as context:: + + Log::warning('This is a warning', ['orders']); + Log::warning('This is a warning', 'payments'); + +.. note:: + When ``scopes`` is set to an empty array or ``null`` in a logger's + configuration, it will take messages of any scope. Setting it to ``false`` + will only match messages without scope. + +.. _file-log: + +Logging to Files +================ + +As its name implies ``FileLog`` writes log messages to files. The level of log +message being written determines the name of the file the message is stored in. +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!"); + + // Results in this being appended to logs/error.log + // 2007-11-02 10:22:02 Error: Something didn't work! + +The configured directory must be writable by the web server user in +order for logging to work correctly. + +You can configure additional/alternate FileLog locations when configuring +a logger. FileLog accepts a ``path`` which allows for +custom paths to be used:: + + Log::setConfig('custom_path', [ + 'className' => 'File', + 'path' => '/path/to/custom/place/' + ]); + +``FileLog`` engine takes the following options: + +* ``size`` Used to implement basic log file rotation. If log file size + reaches specified size the existing file is renamed by appending timestamp + to filename and new log file is created. Can be integer bytes value or + human readable string values like '10MB', '100KB' etc. Defaults to 10MB. +* ``rotate`` Log files are rotated specified times before being removed. + If value is 0, old versions are removed rather then rotated. Defaults to 10. +* ``mask`` Set the file permissions for created files. If left empty the default + permissions are used. + .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + Missing directories will be automatically created to avoid + unnecessary errors thrown when using the FileEngine. + +.. _syslog-log: + +Logging to Syslog +================= + +In production environments it is highly recommended that you setup your system to +use syslog instead of the file logger. This will perform much better as any +writes will be done in a (almost) non-blocking fashion and your operating system +logger can be configured separately to rotate files, pre-process writes or use +a completely different storage for your logs. + +Using syslog is pretty much like using the default FileLog engine, you just need +to specify ``Syslog`` as the engine to be used for logging. The following +configuration snippet will replace the default logger with syslog, this should +be done in the **config/bootstrap.php** file:: + + Log::setConfig('default', [ + 'engine' => 'Syslog' + ]); + +The configuration array accepted for the Syslog logging engine understands the +following keys: + +* ``format``: An sprintf template string with two placeholders, the first one + for the error level, and the second for the message itself. This key is + useful to add additional information about the server or process in the + logged message. For example: ``%s - Web Server 1 - %s`` will look like + ``error - Web Server 1 - An error occurred in this request`` after + replacing the placeholders. This option is deprecated. You should use + :ref:`logging-formatters` instead. +* ``prefix``: An string that will be prefixed to every logged message. +* ``flag``: An integer flag to be used for opening the connection to the + logger, by default ``LOG_ODELAY`` will be used. See ``openlog`` documentation + for more options +* ``facility``: The logging slot to use in syslog. By default ``LOG_USER`` is + used. See ``syslog`` documentation for more options + +Creating Log Engines +===================== + +Log engines can be part of your application, or part of +plugins. If for example you had a database logger called +``DatabaseLog``. As part of your application it would be placed in +**src/Log/Engine/DatabaseLog.php**. As part of a plugin it would be placed in +**plugins/LoggingPack/src/Log/Engine/DatabaseLog.php**. To configure log +engine you should use :php:meth:`Cake\\Log\\Log::setConfig()`. For example +configuring our DatabaseLog would look like:: + + // For src/Log + Log::setConfig('otherFile', [ + 'className' => 'Database', + 'model' => 'LogEntry', + // ... + ]); + + // For plugin called LoggingPack + Log::setConfig('otherFile', [ + 'className' => 'LoggingPack.Database', + 'model' => 'LogEntry', + // ... + ]); + +When configuring a log engine the ``className`` parameter is used to +locate and load the log handler. All of the other configuration +properties are passed to the log engine's constructor as an array. :: + + namespace App\Log\Engine; + use Cake\Log\Engine\BaseLog; + + class DatabaseLog extends BaseLog + { + public function __construct(array $config = []) + { + parent::__construct($config); + // ... + } + + public function log($level, string $message, array $context = []) + { + // Write to the database. + } + } + +CakePHP requires that all logging engine implement ``Psr\Log\LoggerInterface``. +The class :php:class:`Cake\Log\Engine\BaseLog` is an easy way to satisfy the +interface as it only requires you to implement the ``log()`` method. + +.. _logging-formatters: + +Logging Formatters +------------------ + +Logging formatters allow you to control how log messages are formatted +independent of the storage engine. Each core provided logging engine comes with +a formatter configured to maintain backwards compatible output. However, you can +adjust the formatters to fit your requirements. Formatters are configured +alongside the logging engine:: + + use Cake\Log\Engine\SyslogLog; + use App\Log\Formatter\CustomFormatter; + + // Simple formatting configuration with no options. + Log::setConfig('error', [ + 'className' => SyslogLog::class, + 'formatter' => CustomFormatter::class, + ]); + + // Configure a formatter with additional options. + Log::setConfig('error', [ + 'className' => SyslogLog::class, + 'formatter' => [ + 'className' => CustomFormatter::class, + 'key' => 'value', + ], + ]); + +To implement your own logging formatter you need to extend +``Cake\Log\Format\AbstractFormatter`` or one of its subclasses. The primary +method you need to implement is ``format($level, $message, $context)`` which is +responsible for formatting log messages. + +Log API +======= + +.. php:namespace:: Cake\Log + +.. php:class:: Log + + A simple class for writing to logs. + +.. php:staticmethod:: setConfig($key, $config) + + :param string $name: Name for the logger being connected, used + to drop a logger later on. + :param array $config: Array of configuration information and + constructor arguments for the logger. + + Get or set the configuration for a Logger. See :ref:`log-configuration` for + more information. + +.. php:staticmethod:: configured() + + :returns: An array of configured loggers. + + Get the names of the configured loggers. + +.. php:staticmethod:: drop($name) + + :param string $name: Name of the logger you wish to no longer receive + messages. + +.. php:staticmethod:: write($level, $message, $scope = []) + + Write a message into all the configured loggers. + ``$level`` indicates the level of log message being created. + ``$message`` is the message of the log entry being written to. + ``$scope`` is the scope(s) a log message is being created in. + +.. php:staticmethod:: levels() + +Call this method without arguments, eg: `Log::levels()` to obtain current +level configuration. + +Convenience Methods +------------------- + +The following convenience methods were added to log `$message` with the +appropriate log level. + +.. php:staticmethod:: emergency($message, $scope = []) +.. php:staticmethod:: alert($message, $scope = []) +.. php:staticmethod:: critical($message, $scope = []) +.. php:staticmethod:: error($message, $scope = []) +.. php:staticmethod:: warning($message, $scope = []) +.. php:staticmethod:: notice($message, $scope = []) +.. php:staticmethod:: info($message, $scope = []) +.. php:staticmethod:: debug($message, $scope = []) + +Logging Trait +============= + +.. php:trait:: LogTrait + + A trait that provides shortcut methods for logging + +.. php:method:: log($msg, $level = LOG_ERR) + + Log a message to the logs. By default messages are logged as + ERROR messages. + +Using Monolog +============= + +Monolog is a popular logger for PHP. Since it implements the same interfaces as +the CakePHP loggers, you can use them in your application as the default +logger. + +After installing Monolog using composer, configure the logger using the +``Log::setConfig()`` method:: + + // config/bootstrap.php + + use Monolog\Logger; + use Monolog\Handler\StreamHandler; + + Log::setConfig('default', function () { + $log = new Logger('app'); + $log->pushHandler(new StreamHandler('path/to/your/combined.log')); + return $log; + }); + + // Optionally stop using the now redundant default loggers + Log::drop('debug'); + Log::drop('error'); + +Use similar methods if you want to configure a different logger for your console:: + + // config/bootstrap_cli.php + + use Monolog\Logger; + use Monolog\Handler\StreamHandler; + + Log::setConfig('default', function () { + $log = new Logger('cli'); + $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log')); + return $log; + }); + + // Optionally stop using the now redundant default CLI loggers + Configure::delete('Log.debug'); + Configure::delete('Log.error'); + +.. note:: - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + When using a console specific logger, make sure to conditionally configure + your application logger. This will prevent duplicate log entries. .. meta:: - :title lang=es: Logging - :description lang=es: Log CakePHP data to the disk to help debug your application over longer periods of time. - :keywords lang=es: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs + :title lang=es: Registro (Logging) + :description lang=en: Log CakePHP data to the disk to help debug your application over longer periods of time. + :keywords lang=en: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs diff --git a/es/console-and-shells/plugin-shell.rst b/es/core-libraries/plugin.rst similarity index 66% rename from es/console-and-shells/plugin-shell.rst rename to es/core-libraries/plugin.rst index cb8566496e..64f10b13d0 100644 --- a/es/console-and-shells/plugin-shell.rst +++ b/es/core-libraries/plugin.rst @@ -1,6 +1,4 @@ -.. _plugin-shell: - -Plugin Shell +Clase Plugin ############ .. note:: @@ -8,12 +6,8 @@ Plugin Shell página. Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve - this Doc** para proponer directamente los cambios. + `Github `_ o utilizar el botón + **Improve this Doc** para proponer directamente los cambios. Usted puede hacer referencia a la versión en Inglés en el menú de selección superior para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Plugin Shell - :keywords lang=es: api docs,shell,plugin,load,unload diff --git a/es/deployment.rst b/es/deployment.rst index 4f71474555..1421dfa20f 100644 --- a/es/deployment.rst +++ b/es/deployment.rst @@ -1,15 +1,140 @@ -ES - Deployment -############### +Despliegue +########## -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +Una vez que tu aplicación esté lista para ser desplegada, hay algunas cosas que debes hacer. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +Mover archivos +============== - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +Puedes clonar tu repositorio en tu servidor de producción y luego seleccionar la +revisión/etiqueta que deseas ejecutar. Luego, ejecuta ``composer install``. Aunque esto requiere +un cierto conocimiento sobre git y una instalación existente de ``git`` y ``composer``, +este proceso se encargará de las dependencias de las bibliotecas y los permisos de archivos y carpetas. + +Ten en cuenta que al desplegar a través de FTP deberás corregir los permisos de archivo y +carpeta. + +También puedes utilizar esta técnica de despliegue para configurar un servidor de pruebas o demostración +(preproducción) y mantenerlo sincronizado con tu entorno local. + +Ajustar la configuración +======================== + +Querrás hacer algunos ajustes en la configuración de tu aplicación para +un entorno de producción. El valor de ``debug`` es extremadamente importante. +Al desactivar debug = ``false`` se deshabilitan una serie de características de desarrollo que no deberían +ser expuestas a Internet en general. Deshabilitar debug cambia las siguientes +características: + +* Los mensajes de depuración, creados con :php:func:`pr()`, :php:func:`debug()` y :php:func:`dd()`, + están deshabilitados. +* La duración de las cachés básicas de CakePHP se establece en 365 días, en lugar de 10 segundos, + como en desarrollo. +* Las vistas de errores son menos informativas y se muestran páginas de error genéricas + en lugar de mensajes de error detallados con trazas de pila. +* Los avisos y errores de PHP no se muestran. + +Además de lo anterior, muchos complementos y extensiones de la aplicación usan ``debug`` +para modificar su comportamiento. + +Puedes utilizar una variable de entorno para establecer dinámicamente el nivel de depuración +entre entornos. Esto evitará desplegar una aplicación con debug +``true`` y también te ahorrará tener que cambiar el nivel de depuración cada vez +antes de desplegar en un entorno de producción. + +Por ejemplo, puedes establecer una variable de entorno en tu configuración de Apache:: + + SetEnv CAKEPHP_DEBUG 1 + +Y luego puedes establecer dinámicamente el nivel de depuración en **app_local.php**:: + + $debug = (bool)getenv('CAKEPHP_DEBUG'); + + return [ + 'debug' => $debug, + ..... + ]; + +Se recomienda que coloques la configuración que se comparte en todas +los entornos de tu aplicación en **config/app.php**. Para la configuración que +varía entre entornos, utiliza **config/app_local.php** o variables de entorno. + +Verificar tu Seguridad +====================== + +Si estás lanzando tu aplicación al mundo, es una buena idea asegurarte de que no tenga ningun problema de seguridad obvio: + +* Asegúrate de estar usando el componente o middleware :ref:`csrf-middleware`. +* Puedes habilitar el componente :doc:`/controllers/components/form-protection`. + Puede ayudar a prevenir varios tipos de manipulación de formularios y reducir la posibilidad + de problemas de asignación masiva. +* Asegúrate de que tus modelos tengan las reglas de :doc:`/core-libraries/validation` correctas + habilitadas. +* Verifica que solo tu directorio ``webroot`` sea públicamente visible y que tus + secretos (como tu sal de aplicación y cualquier clave de seguridad) sean privados y únicos + también. + +Establecer la Raíz (Document Root) +================================== + +Establecer correctamente la raíz en tu aplicación es un paso importante para +mantener tanto tu código como tu aplicación seguros. Las aplicaciones de CakePHP +deben tener la raíz establecida en el ``webroot`` de la aplicación. Esto +hace que los archivos de aplicación y configuración sean inaccesibles a través de una URL. +Establecer la raíz es diferente para diferentes servidores web. Consulta la +documentación de :ref:`url-rewriting` para obtener información específica del servidor web. + +En todos los casos, querrás establecer la raiz del host virtual/dominio en +``webroot/``. Esto elimina la posibilidad de que se ejecuten archivos fuera del directorio raíz. + +.. _symlink-assets: + +Mejora el Rendimiento de tu Aplicación +======================================= + +La carga de clases puede llevarse una gran parte del tiempo de procesamiento de tu aplicación. +Para evitar este problema, se recomienda que ejecutes este comando en tu servidor de producción una vez que la aplicación esté implementada:: + + php composer.phar dumpautoload -o + +Dado que manejar los archivos estáticos, como imágenes, archivos JavaScript y CSS de +los complementos, a través del ``Dispatcher`` es increíblemente ineficiente, se recomienda encarecidamente crear enlaces simbólicos para producción. Esto se puede hacer usando +el comando ``plugin``:: + + bin/cake plugin assets symlink + +El comando anterior creará enlaces simbólicos del directorio ``webroot`` de todos los complementos cargados +a la ruta adecuada en el directorio ``webroot`` de la aplicación. + +Si tu sistema de archivos no permite crear enlaces simbólicos, los directorios se copiarán en lugar de enlazarse. También puedes copiar explícitamente los directorios usando:: + + bin/cake plugin assets copy + +CakePHP utiliza internamente ``assert()`` para proporcionar comprobación de tipos en tiempo de ejecución y +proporcionar mejores mensajes de error durante el desarrollo. Puedes hacer que PHP omita estas +comprobaciones ``assert()`` actualizando tu ``php.ini`` para incluir: + +.. code-block:: ini + + ; Desactivar la generación de código assert(). + zend.assertions = -1 + +Omitir la generación de código para ``assert()`` proporcionará un rendimiento de ejecución más rápido, +y se recomienda para aplicaciones que tienen una buena cobertura de pruebas o que están +usando un analizador estático. + +Desplegar una actualización +============================ + +En cada implementación es probable que tengas algunas tareas para coordinar en tu servidor web. Algunas tareas típicas son: + +1. Instalar dependencias con ``composer install``. Evita usar ``composer + update`` al hacer implementaciones, ya que podrías obtener versiones inesperadas de paquetes. +2. Ejecutar `migraciones de base de datos `__ con el complemento Migrations + u otra herramienta. +3. Limpiar la caché del esquema del modelo con ``bin/cake schema_cache clear``. La página :doc:`/console-commands/schema-cache` + tiene más información sobre este comando. .. meta:: - :title lang=es: Deployment - :keywords lang=es: stack traces,application extensions,set document,installation documentation,development features,generic error,document root,func,debug,caches,error messages,configuration files,webroot,deployment,cakephp,applications + :title lang=es: Despliegue + :keywords lang=en: stack traces,application extensions,set document,installation documentation,development features,generic error,document root,func,debug,caches,error messages,configuration files,webroot,deployment,cakephp,applications diff --git a/es/console-and-shells/cache.rst b/es/development/application.rst similarity index 54% rename from es/console-and-shells/cache.rst rename to es/development/application.rst index 9fd9f36233..17dfbd0ad3 100644 --- a/es/console-and-shells/cache.rst +++ b/es/development/application.rst @@ -1,11 +1,13 @@ -Cache Shell -=========== +Clase Application +################# .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. + La documentación no es compatible actualmente con el idioma español en esta + página. Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + `Github `_ o utilizar el botón + **Improve this Doc** para proponer directamente los cambios. - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. + Usted puede hacer referencia a la versión en Inglés en el menú de selección + superior para obtener información sobre el tema de esta página. diff --git a/es/console-and-shells/repl.rst b/es/development/dependency-injection.rst similarity index 81% rename from es/console-and-shells/repl.rst rename to es/development/dependency-injection.rst index 0953970dfb..dbfb3a740a 100644 --- a/es/console-and-shells/repl.rst +++ b/es/development/dependency-injection.rst @@ -1,4 +1,4 @@ -Interactive Console (REPL) +Inyección de Dependencias ########################## .. note:: @@ -6,8 +6,8 @@ Interactive Console (REPL) página. Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve - this Doc** para proponer directamente los cambios. + `Github `_ o utilizar el botón + **Improve this Doc** para proponer directamente los cambios. Usted puede hacer referencia a la versión en Inglés en el menú de selección superior para obtener información sobre el tema de esta página. diff --git a/es/development/errors.rst b/es/development/errors.rst index 4190d72e1b..113fe078b2 100644 --- a/es/development/errors.rst +++ b/es/development/errors.rst @@ -308,7 +308,7 @@ Excepciones Incorporadas para CakePHP ====================================== Excepciones HTTP ---------------- +----------------- Hay varias excepciones incorporadas en CakePHP, además de las excepciones internas del framework, hay varias excepciones para métodos HTTP. diff --git a/es/development/routing.rst b/es/development/routing.rst index 122dddbee1..2babaf749a 100644 --- a/es/development/routing.rst +++ b/es/development/routing.rst @@ -3,33 +3,1720 @@ Routing .. php:namespace:: Cake\Routing -.. php:class:: Router +.. php:class:: RouterBuilder -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +Routing provides you tools that map URLs to controller actions. By defining +routes, you can separate how your application is implemented from how its URLs +are structured. + +Routing in CakePHP also encompasses the idea of reverse routing, where an array +of parameters can be transformed into a URL string. By using reverse routing, +you can re-factor your application's URL structure without having to update all +your code. + +.. index:: routes.php + +Quick Tour +========== + +This section will teach you by example the most common uses of the CakePHP +Router. Typically you want to display something as a landing page, so you add +this to your **config/routes.php** file:: + + /** @var \Cake\Routing\RouteBuilder $routes */ + $routes->connect('/', ['controller' => 'Articles', 'action' => 'index']); + +This will execute the index method in the ``ArticlesController`` when the +homepage of your site is visited. Sometimes you need dynamic routes that will +accept multiple parameters, this would be the case, for example of a route for +viewing an article's content:: + + $routes->connect('/articles/*', ['controller' => 'Articles', 'action' => 'view']); + +The above route will accept any URL looking like ``/articles/15`` and invoke the +method ``view(15)`` in the ``ArticlesController``. This will not, though, +prevent people from trying to access URLs looking like ``/articles/foobar``. If +you wish, you can restrict some parameters to conform to a regular expression:: + + // Using fluent interface + $routes->connect( + '/articles/{id}', + ['controller' => 'Articles', 'action' => 'view'], + ) + ->setPatterns(['id' => '\d+']) + ->setPass(['id']); + + // Using options array + $routes->connect( + '/articles/{id}', + ['controller' => 'Articles', 'action' => 'view'], + ['id' => '\d+', 'pass' => ['id']] + ); + +The previous example changed the star matcher by a new placeholder ``{id}``. +Using placeholders allows us to validate parts of the URL, in this case we used +the ``\d+`` regular expression so that only digits are matched. Finally, we told +the Router to treat the ``id`` placeholder as a function argument to the +``view()`` function by specifying the ``pass`` option. More on using this +option later. + +The CakePHP Router can also reverse match routes. That means that from an +array containing matching parameters, it is capable of generating a URL string:: + + use Cake\Routing\Router; - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + echo Router::url(['controller' => 'Articles', 'action' => 'view', 'id' => 15]); + // Will output + /articles/15 - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +Routes can also be labelled with a unique name, this allows you to quickly +reference them when building links instead of specifying each of the routing +parameters:: + // In routes.php + $routes->connect( + '/upgrade', + ['controller' => 'Subscriptions', 'action' => 'create'], + ['_name' => 'upgrade'] + ); + + use Cake\Routing\Router; + + echo Router::url(['_name' => 'upgrade']); + // Will output + /upgrade + +To help keep your routing code DRY, the Router has the concept of 'scopes'. +A scope defines a common path segment, and optionally route defaults. Any routes +connected inside a scope will inherit the path/defaults from their wrapping +scopes:: + + $routes->scope('/blog', ['plugin' => 'Blog'], function (RouteBuilder $routes) { + $routes->connect('/', ['controller' => 'Articles']); + }); + +The above route would match ``/blog/`` and send it to +``Blog\Controller\ArticlesController::index()``. + +The application skeleton comes with a few routes to get you started. Once you've +added your own routes, you can remove the default routes if you don't need them. + +.. index:: {controller}, {action}, {plugin} +.. index:: greedy star, trailing star +.. _connecting-routes: .. _routes-configuration: Connecting Routes ================= +To keep your code :term:`DRY` you should use 'routing scopes'. Routing +scopes not only let you keep your code DRY, they also help Router optimize its +operation. This method defaults to the ``/`` scope. To create a scope and connect +some routes we'll use the ``scope()`` method:: + + // In config/routes.php + use Cake\Routing\RouteBuilder; + use Cake\Routing\Route\DashedRoute; + + $routes->scope('/', function (RouteBuilder $routes) { + // Connect the generic fallback routes. + $routes->fallbacks(DashedRoute::class); + }); + +The ``connect()`` method takes up to three parameters: the URL template you wish +to match, the default values for your route elements, and the options for the +route. Options frequently include regular expression rules to help the router +match elements in the URL. + +The basic format for a route definition is:: + + $routes->connect( + '/url/template', + ['targetKey' => 'targetValue'], + ['option' => 'matchingRegex'] + ); + +The first parameter is used to tell the router what sort of URL you're trying to +control. The URL is a normal slash delimited string, but can also contain +a wildcard (\*) or :ref:`route-elements`. Using a wildcard tells the router +that you are willing to accept any additional arguments supplied. Routes without +a \* only match the exact template pattern supplied. + +Once you've specified a URL, you use the last two parameters of ``connect()`` to +tell CakePHP what to do with a request once it has been matched. The second +parameter defines the route 'target'. This can be defined either as an array, or +as a destination string. A few examples of route targets are:: + + // Array target to an application controller + $routes->connect( + '/users/view/*', + ['controller' => 'Users', 'action' => 'view'] + ); + $routes->connect('/users/view/*', 'Users::view'); + + // Array target to a prefixed plugin controller + $routes->connect( + '/admin/cms/articles', + ['prefix' => 'Admin', 'plugin' => 'Cms', 'controller' => 'Articles', 'action' => 'index'] + ); + $routes->connect('/admin/cms/articles', 'Cms.Admin/Articles::index'); + +The first route we connect matches URLs starting with ``/users/view`` and maps +those requests to the ``UsersController->view()``. The trailing ``/*`` tells the +router to pass any additional segments as method arguments. For example, +``/users/view/123`` would map to ``UsersController->view(123)``. + +The above example also illustrates string targets. String targets provide +a compact way to define a route's destination. String targets have the following +syntax:: + + [Plugin].[Prefix]/[Controller]::[action] + +Some example string targets are:: + + // Application controller + 'Articles::view' + + // Application controller with prefix + Admin/Articles::view + + // Plugin controller + Cms.Articles::edit + + // Prefixed plugin controller + Vendor/Cms.Management/Admin/Articles::view + +Earlier we used the greedy star (``/*``) to capture additional path segments, +there is also the trailing star (``/**``). Using a trailing double star, +will capture the remainder of a URL as a single passed argument. This is useful +when you want to use an argument that included a ``/`` in it:: + + $routes->connect( + '/pages/**', + ['controller' => 'Pages', 'action' => 'show'] + ); + +The incoming URL of ``/pages/the-example-/-and-proof`` would result in a single +passed argument of ``the-example-/-and-proof``. + +The second parameter of ``connect()`` can define any parameters that +compose the default route parameters:: + + $routes->connect( + '/government', + ['controller' => 'Pages', 'action' => 'display', 5] + ); + +This example uses the second parameter of ``connect()`` to +define default parameters. If you built an application that features products for +different categories of customers, you might consider creating a route. This +allows you to link to ``/government`` rather than ``/pages/display/5``. + +A common use for routing is to rename controllers and their actions. Instead of +accessing our users controller at ``/users/some-action/5``, we'd like to be able +to access it through ``/cooks/some-action/5``. The following route takes care of +that:: + + $routes->connect( + '/cooks/{action}/*', ['controller' => 'Users'] + ); + +This is telling the Router that any URL beginning with ``/cooks/`` should be +sent to the ``UsersController``. The action called will depend on the value of +the ``{action}`` parameter. By using :ref:`route-elements`, you can create +variable routes, that accept user input or variables. The above route also uses +the greedy star. The greedy star indicates that this route should accept any +additional positional arguments given. These arguments will be made available in +the :ref:`passed-arguments` array. + +When generating URLs, routes are used too. Using +``['controller' => 'Users', 'action' => 'some-action', 5]`` as +a URL will output ``/cooks/some-action/5`` if the above route is the +first match found. + +The routes we've connected so far will match any HTTP verb. If you are building +a REST API you'll often want to map HTTP actions to different controller methods. +The ``RouteBuilder`` provides helper methods that make defining routes for +specific HTTP verbs simpler:: + + // Create a route that only responds to GET requests. + $routes->get( + '/cooks/{id}', + ['controller' => 'Users', 'action' => 'view'], + 'users:view' + ); + + // Create a route that only responds to PUT requests + $routes->put( + '/cooks/{id}', + ['controller' => 'Users', 'action' => 'update'], + 'users:update' + ); + +The above routes map the same URL to different controller actions based on the +HTTP verb used. GET requests will go to the 'view' action, while PUT requests +will go to the 'update' action. There are HTTP helper methods for: + +* GET +* POST +* PUT +* PATCH +* DELETE +* OPTIONS +* HEAD + +All of these methods return the route instance allowing you to leverage the +:ref:`fluent setters ` to further configure your route. + +.. _route-elements: + +Route Elements +-------------- + +You can specify your own route elements and doing so gives you the +power to define places in the URL where parameters for controller +actions should lie. When a request is made, the values for these +route elements are found in ``$this->request->getParam()`` in the controller. +When you define a custom route element, you can optionally specify a regular +expression - this tells CakePHP how to know if the URL is correctly formed or +not. If you choose to not provide a regular expression, any non ``/`` character +will be treated as part of the parameter:: + + $routes->connect( + '/{controller}/{id}', + ['action' => 'view'] + )->setPatterns(['id' => '[0-9]+']); + + $routes->connect( + '/{controller}/{id}', + ['action' => 'view'], + ['id' => '[0-9]+'] + ); + +The above example illustrates how to create a quick way to view +models from any controller by crafting a URL that looks like +``/controllername/{id}``. The URL provided to ``connect()`` specifies two +route elements: ``{controller}`` and ``{id}``. The ``{controller}`` element +is a CakePHP default route element, so the router knows how to match and +identify controller names in URLs. The ``{id}`` element is a custom +route element, and must be further clarified by specifying a +matching regular expression in the third parameter of ``connect()``. + +CakePHP does not automatically produce lowercased and dashed URLs when using the +``{controller}`` parameter. If you need this, the above example could be +rewritten like so:: + + use Cake\Routing\Route\DashedRoute; + + // Create a builder with a different route class. + $routes->scope('/', function (RouteBuilder $routes) { + $routes->setRouteClass(DashedRoute::class); + $routes->connect('/{controller}/{id}', ['action' => 'view']) + ->setPatterns(['id' => '[0-9]+']); + + $routes->connect( + '/{controller}/{id}', + ['action' => 'view'], + ['id' => '[0-9]+'] + ); + }); + +The ``DashedRoute`` class will make sure that the ``{controller}`` and +``{plugin}`` parameters are correctly lowercased and dashed. + +.. note:: + + Patterns used for route elements must not contain any capturing + groups. If they do, Router will not function correctly. + +Once this route has been defined, requesting ``/apples/5`` would call the ``view()`` +method of the ApplesController. Inside the ``view()`` method, you would need to +access the passed ID at ``$this->request->getParam('id')``. + +If you have a single controller in your application and you do not want the +controller name to appear in the URL, you can map all URLs to actions in your +controller. For example, to map all URLs to actions of the ``home`` controller, +e.g have URLs like ``/demo`` instead of ``/home/demo``, you can do the +following:: + + $routes->connect('/{action}', ['controller' => 'Home']); + +If you would like to provide a case insensitive URL, you can use regular +expression inline modifiers:: + + $routes->connect( + '/{userShortcut}', + ['controller' => 'Teachers', 'action' => 'profile', 1], + )->setPatterns(['userShortcut' => '(?i:principal)']); + +One more example, and you'll be a routing pro:: + + $routes->connect( + '/{controller}/{year}/{month}/{day}', + ['action' => 'index'] + )->setPatterns([ + 'year' => '[12][0-9]{3}', + 'month' => '0[1-9]|1[012]', + 'day' => '0[1-9]|[12][0-9]|3[01]' + ]); + +This is rather involved, but shows how powerful routes can be. The URL supplied +has four route elements. The first is familiar to us: it's a default route +element that tells CakePHP to expect a controller name. + +Next, we specify some default values. Regardless of the controller, +we want the ``index()`` action to be called. + +Finally, we specify some regular expressions that will match years, +months and days in numerical form. Note that parenthesis (capturing groups) +are not supported in the regular expressions. You can still specify +alternates, as above, but not grouped with parenthesis. + +Once defined, this route will match ``/articles/2007/02/01``, +``/articles/2004/11/16``, handing the requests to +the ``index()`` actions of their respective controllers, with the date +parameters in ``$this->request->getParam()``. + +Reserved Route Elements +----------------------- + +There are several route elements that have special meaning in +CakePHP, and should not be used unless you want the special meaning + +* ``controller`` Used to name the controller for a route. +* ``action`` Used to name the controller action for a route. +* ``plugin`` Used to name the plugin a controller is located in. +* ``prefix`` Used for :ref:`prefix-routing` +* ``_ext`` Used for :ref:`File extentions routing `. +* ``_base`` Set to ``false`` to remove the base path from the generated URL. If + your application is not in the root directory, this can be used to generate + URLs that are 'cake relative'. +* ``_scheme`` Set to create links on different schemes like `webcal` or `ftp`. + Defaults to the current scheme. +* ``_host`` Set the host to use for the link. Defaults to the current host. +* ``_port`` Set the port if you need to create links on non-standard ports. +* ``_full`` If ``true`` the value of ``App.fullBaseUrl`` mentioned in + :ref:`general-configuration` will be prepended to generated URLs. +* ``#`` Allows you to set URL hash fragments. +* ``_https`` Set to ``true`` to convert the generated URL to https or ``false`` + to force http. Prior to 4.5.0 use ``_ssl``. +* ``_method`` Define the HTTP verb/method to use. Useful when working with + :ref:`resource-routes`. +* ``_name`` Name of route. If you have setup named routes, you can use this key + to specify it. + +.. _route-fluent-methods: + +Configuring Route Options +------------------------- + +There are a number of route options that can be set on each route. After +connecting a route you can use its fluent builder methods to further configure +the route. These methods replace many of the keys in the ``$options`` parameter +of ``connect()``:: + + $routes->connect( + '/{lang}/articles/{slug}', + ['controller' => 'Articles', 'action' => 'view'], + ) + // Allow GET and POST requests. + ->setMethods(['GET', 'POST']) + + // Only match on the blog subdomain. + ->setHost('blog.example.com') + + // Set the route elements that should be converted to passed arguments + ->setPass(['slug']) + + // Set the matching patterns for route elements + ->setPatterns([ + 'slug' => '[a-z0-9-_]+', + 'lang' => 'en|fr|es', + ]) + + // Also allow JSON file extensions + ->setExtensions(['json']) + + // Set lang to be a persistent parameter + ->setPersist(['lang']); + +Passing Parameters to Action +---------------------------- + +When connecting routes using :ref:`route-elements` you may want to have routed +elements be passed arguments instead. The ``pass`` option indicates which route +elements should also be made available as arguments passed into the controller +functions:: + + // src/Controller/BlogsController.php + public function view($articleId = null, $slug = null) + { + // Some code here... + } + + // routes.php + $routes->scope('/', function (RouteBuilder $routes) { + $routes->connect( + '/blog/{id}-{slug}', // For example, /blog/3-CakePHP_Rocks + ['controller' => 'Blogs', 'action' => 'view'] + ) + // Define the route elements in the route template + // to prepend as function arguments. Order matters as this + // will pass the `$id` and `$slug` elements as the first and + // second parameters. Any additional passed parameters in your + // route will be added after the setPass() arguments. + ->setPass(['id', 'slug']) + // Define a pattern that `id` must match. + ->setPatterns([ + 'id' => '[0-9]+', + ]); + }); + +Now thanks to the reverse routing capabilities, you can pass in the URL array +like below and CakePHP will know how to form the URL as defined in the routes:: + + // view.php + // This will return a link to /blog/3-CakePHP_Rocks + echo $this->Html->link('CakePHP Rocks', [ + 'controller' => 'Blog', + 'action' => 'view', + 'id' => 3, + 'slug' => 'CakePHP_Rocks' + ]); + + // You can also used numerically indexed parameters. + echo $this->Html->link('CakePHP Rocks', [ + 'controller' => 'Blog', + 'action' => 'view', + 3, + 'CakePHP_Rocks' + ]); + +.. _path-routing: + +Using Path Routing +------------------ + +We talked about string targets above. The same also works for URL generation using +``Router::pathUrl()``:: + + echo Router::pathUrl('Articles::index'); + // outputs: /articles + + echo Router::pathUrl('MyBackend.Admin/Articles::view', [3]); + // outputs: /admin/my-backend/articles/view/3 + +.. tip:: + + IDE support for Path Routing autocomplete can be enabled with `CakePHP IdeHelper Plugin `_. + .. _named-routes: Using Named Routes ------------------ -.. toctree:: - :glob: - :maxdepth: 1 +Sometimes you'll find typing out all the URL parameters for a route too verbose, +or you'd like to take advantage of the performance improvements that named +routes have. When connecting routes you can specify a ``_name`` option, this +option can be used in reverse routing to identify the route you want to use:: + + // Connect a route with a name. + $routes->connect( + '/login', + ['controller' => 'Users', 'action' => 'login'], + ['_name' => 'login'] + ); + + // Name a verb specific route + $routes->post( + '/logout', + ['controller' => 'Users', 'action' => 'logout'], + 'logout' + ); + + // Generate a URL using a named route. + $url = Router::url(['_name' => 'logout']); + + // Generate a URL using a named route, + // with some query string args. + $url = Router::url(['_name' => 'login', 'username' => 'jimmy']); + +If your route template contains any route elements like ``{controller}`` you'll +need to supply those as part of the options to ``Router::url()``. + +.. note:: + + Route names must be unique across your entire application. The same + ``_name`` cannot be used twice, even if the names occur inside a different + routing scope. + +When building named routes, you will probably want to stick to some conventions +for the route names. CakePHP makes building up route names easier by allowing +you to define name prefixes in each scope:: + + $routes->scope('/api', ['_namePrefix' => 'api:'], function (RouteBuilder $routes) { + // This route's name will be `api:ping` + $routes->get('/ping', ['controller' => 'Pings'], 'ping'); + }); + // Generate a URL for the ping route + Router::url(['_name' => 'api:ping']); + + // Use namePrefix with plugin() + $routes->plugin('Contacts', ['_namePrefix' => 'contacts:'], function (RouteBuilder $routes) { + // Connect routes. + }); + + // Or with prefix() + $routes->prefix('Admin', ['_namePrefix' => 'admin:'], function (RouteBuilder $routes) { + // Connect routes. + }); + +You can also use the ``_namePrefix`` option inside nested scopes and it works as +you'd expect:: + + $routes->plugin('Contacts', ['_namePrefix' => 'contacts:'], function (RouteBuilder $routes) { + $routes->scope('/api', ['_namePrefix' => 'api:'], function (RouteBuilder $routes) { + // This route's name will be `contacts:api:ping` + $routes->get('/ping', ['controller' => 'Pings'], 'ping'); + }); + }); + + // Generate a URL for the ping route + Router::url(['_name' => 'contacts:api:ping']); + +Routes connected in named scopes will only have names added if the route is also +named. Nameless routes will not have the ``_namePrefix`` applied to them. + +.. index:: admin routing, prefix routing +.. _prefix-routing: + +Prefix Routing +-------------- + +.. php:staticmethod:: prefix($name, $callback) + +Many applications require an administration section where +privileged users can make changes. This is often done through a +special URL such as ``/admin/users/edit/5``. In CakePHP, prefix routing +can be enabled by using the ``prefix`` scope method:: + + use Cake\Routing\Route\DashedRoute; + + $routes->prefix('Admin', function (RouteBuilder $routes) { + // All routes here will be prefixed with `/admin`, and + // have the `'prefix' => 'Admin'` route element added that + // will be required when generating URLs for these routes + $routes->fallbacks(DashedRoute::class); + }); + +Prefixes are mapped to sub-namespaces in your application's ``Controller`` +namespace. By having prefixes as separate controllers you can create smaller and +simpler controllers. Behavior that is common to the prefixed and non-prefixed +controllers can be encapsulated using inheritance, +:doc:`/controllers/components`, or traits. Using our users example, accessing +the URL ``/admin/users/edit/5`` would call the ``edit()`` method of our +**src/Controller/Admin/UsersController.php** passing 5 as the first parameter. +The view file used would be **templates/Admin/Users/edit.php** + +You can map the URL /admin to your ``index()`` action of pages controller using +following route:: + + $routes->prefix('Admin', function (RouteBuilder $routes) { + // Because you are in the admin scope, + // you do not need to include the /admin prefix + // or the Admin route element. + $routes->connect('/', ['controller' => 'Pages', 'action' => 'index']); + }); + +When creating prefix routes, you can set additional route parameters using +the ``$options`` argument:: + + $routes->prefix('Admin', ['param' => 'value'], function (RouteBuilder $routes) { + // Routes connected here are prefixed with '/admin' and + // have the 'param' routing key set. + $routes->connect('/{controller}'); + }); + +Multi word prefixes are by default converted using dasherize inflection, ie ``MyPrefix`` +would be mapped to ``my-prefix`` in the URL. Make sure to set a path for such prefixes +if you want to use a different format like for example underscoring:: + + $routes->prefix('MyPrefix', ['path' => '/my_prefix'], function (RouteBuilder $routes) { + // Routes connected here are prefixed with '/my_prefix' + $routes->connect('/{controller}'); + }); + +You can define prefixes inside plugin scopes as well:: + + $routes->plugin('DebugKit', function (RouteBuilder $routes) { + $routes->prefix('Admin', function (RouteBuilder $routes) { + $routes->connect('/{controller}'); + }); + }); + +The above would create a route template like ``/debug-kit/admin/{controller}``. +The connected route would have the ``plugin`` and ``prefix`` route elements set. + +When defining prefixes, you can nest multiple prefixes if necessary:: + + $routes->prefix('Manager', function (RouteBuilder $routes) { + $routes->prefix('Admin', function (RouteBuilder $routes) { + $routes->connect('/{controller}/{action}'); + }); + }); + +The above would create a route template like ``/manager/admin/{controller}/{action}``. +The connected route would have the ``prefix`` route element set to +``Manager/Admin``. + +The current prefix will be available from the controller methods through +``$this->request->getParam('prefix')`` + +When using prefix routes it's important to set the ``prefix`` option, and to +use the same CamelCased format that is used in the ``prefix()`` method. Here's +how to build this link using the HTML helper:: + + // Go into a prefixed route. + echo $this->Html->link( + 'Manage articles', + ['prefix' => 'Manager/Admin', 'controller' => 'Articles', 'action' => 'add'] + ); + + // Leave a prefix + echo $this->Html->link( + 'View Post', + ['prefix' => false, 'controller' => 'Articles', 'action' => 'view', 5] + ); + +.. index:: plugin routing + +Creating Links to Prefix Routes +------------------------------- + +You can create links that point to a prefix, by adding the prefix key to your +URL array:: + + echo $this->Html->link( + 'New admin todo', + ['prefix' => 'Admin', 'controller' => 'TodoItems', 'action' => 'create'] + ); + +When using nesting, you need to chain them together:: + + echo $this->Html->link( + 'New todo', + ['prefix' => 'Admin/MyPrefix', 'controller' => 'TodoItems', 'action' => 'create'] + ); + +This would link to a controller with the namespace ``App\\Controller\\Admin\\MyPrefix`` and the file path +``src/Controller/Admin/MyPrefix/TodoItemsController.php``. + +.. note:: + + The prefix is always CamelCased here, even if the routing result is dashed. + The route itself will do the inflection if necessary. + +Plugin Routing +-------------- + +.. php:staticmethod:: plugin($name, $options = [], $callback) + +Routes for :doc:`/plugins` should be created using the ``plugin()`` +method. This method creates a new routing scope for the plugin's routes:: + + $routes->plugin('DebugKit', function (RouteBuilder $routes) { + // Routes connected here are prefixed with '/debug-kit' and + // have the plugin route element set to 'DebugKit'. + $routes->connect('/{controller}'); + }); + +When creating plugin scopes, you can customize the path element used with the +``path`` option:: + + $routes->plugin('DebugKit', ['path' => '/debugger'], function (RouteBuilder $routes) { + // Routes connected here are prefixed with '/debugger' and + // have the plugin route element set to 'DebugKit'. + $routes->connect('/{controller}'); + }); + +When using scopes you can nest plugin scopes within prefix scopes:: + + $routes->prefix('Admin', function (RouteBuilder $routes) { + $routes->plugin('DebugKit', function (RouteBuilder $routes) { + $routes->connect('/{controller}'); + }); + }); + +The above would create a route that looks like ``/admin/debug-kit/{controller}``. +It would have the ``prefix``, and ``plugin`` route elements set. The +:ref:`plugin-routes` section has more information on building plugin routes. + +Creating Links to Plugin Routes +------------------------------- + +You can create links that point to a plugin, by adding the plugin key to your +URL array:: + + echo $this->Html->link( + 'New todo', + ['plugin' => 'Todo', 'controller' => 'TodoItems', 'action' => 'create'] + ); + +Conversely if the active request is a plugin request and you want to create +a link that has no plugin you can do the following:: + + echo $this->Html->link( + 'New todo', + ['plugin' => null, 'controller' => 'Users', 'action' => 'profile'] + ); + +By setting ``'plugin' => null`` you tell the Router that you want to +create a link that is not part of a plugin. + +SEO-Friendly Routing +-------------------- + +Some developers prefer to use dashes in URLs, as it's perceived to give +better search engine rankings. The ``DashedRoute`` class can be used in your +application with the ability to route plugin, controller, and camelized action +names to a dashed URL. + +For example, if we had a ``ToDo`` plugin, with a ``TodoItems`` controller, and a +``showItems()`` action, it could be accessed at ``/to-do/todo-items/show-items`` +with the following router connection:: + + use Cake\Routing\Route\DashedRoute; + + $routes->plugin('ToDo', ['path' => 'to-do'], function (RouteBuilder $routes) { + $routes->fallbacks(DashedRoute::class); + }); + +Matching Specific HTTP Methods +------------------------------ + +Routes can match specific HTTP methods using the HTTP verb helper methods:: + + $routes->scope('/', function (RouteBuilder $routes) { + // This route only matches on POST requests. + $routes->post( + '/reviews/start', + ['controller' => 'Reviews', 'action' => 'start'] + ); + + // Match multiple verbs + $routes->connect( + '/reviews/start', + [ + 'controller' => 'Reviews', + 'action' => 'start', + ] + )->setMethods(['POST', 'PUT']); + }); + +You can match multiple HTTP methods by using an array. Because the ``_method`` +parameter is a routing key, it participates in both URL parsing and URL +generation. To generate URLs for method specific routes you'll need to include +the ``_method`` key when generating the URL:: + + $url = Router::url([ + 'controller' => 'Reviews', + 'action' => 'start', + '_method' => 'POST', + ]); + +Matching Specific Hostnames +--------------------------- + +Routes can use the ``_host`` option to only match specific hosts. You can use +the ``*.`` wildcard to match any subdomain:: + + $routes->scope('/', function (RouteBuilder $routes) { + // This route only matches on http://images.example.com + $routes->connect( + '/images/default-logo.png', + ['controller' => 'Images', 'action' => 'default'] + )->setHost('images.example.com'); + + // This route only matches on http://*.example.com + $routes->connect( + '/images/old-log.png', + ['controller' => 'Images', 'action' => 'oldLogo'] + )->setHost('*.example.com'); + }); + +The ``_host`` option is also used in URL generation. If your ``_host`` option +specifies an exact domain, that domain will be included in the generated URL. +However, if you use a wildcard, then you will need to provide the ``_host`` +parameter when generating URLs:: + + // If you have this route + $routes->connect( + '/images/old-log.png', + ['controller' => 'Images', 'action' => 'oldLogo'] + )->setHost('images.example.com'); + + // You need this to generate a url + echo Router::url([ + 'controller' => 'Images', + 'action' => 'oldLogo', + '_host' => 'images.example.com', + ]); + +.. index:: file extensions +.. _file-extensions: + +Routing File Extensions +----------------------- + +.. php:staticmethod:: extensions(string|array|null $extensions, $merge = true) + +To handle different file extensions in your URLs, you can define the extensions +using the :php:meth:`Cake\\Routing\\RouteBuilder::setExtensions()` method:: + + $routes->scope('/', function (RouteBuilder $routes) { + $routes->setExtensions(['json', 'xml']); + }); + +This will enable the named extensions for all routes that are being connected in +that scope **after** the ``setExtensions()`` call, including those that are being +connected in nested scopes. + +.. note:: + + Setting the extensions should be the first thing you do in a scope, as the + extensions will only be applied to routes connected **after** the extensions + are set. + + Also be aware that re-opened scopes will **not** inherit extensions defined in + previously opened scopes. + +By using extensions, you tell the router to remove any matching file extensions +from the URL, and then parse what remains. If you want to create a URL such as +/page/title-of-page.html you would create your route using:: + + $routes->scope('/page', function (RouteBuilder $routes) { + $routes->setExtensions(['json', 'xml', 'html']); + $routes->connect( + '/{title}', + ['controller' => 'Pages', 'action' => 'view'] + )->setPass(['title']); + }); + +Then to create links which map back to the routes simply use:: + + $this->Html->link( + 'Link title', + ['controller' => 'Pages', 'action' => 'view', 'title' => 'super-article', '_ext' => 'html'] + ); + +.. _route-scoped-middleware: + +Route Scoped Middleware +======================= + +While Middleware can be applied to your entire application, applying middleware +to specific routing scopes offers more flexibility, as you can apply middleware +only where it is needed allowing your middleware to not concern itself with +how/where it is being applied. + +.. note:: + + Applied scoped middleware will be run by :ref:`RoutingMiddleware `, + normally at the end of your application's middleware queue. + +Before middleware can be applied to a scope, it needs to be +registered into the route collection:: + + // in config/routes.php + use Cake\Http\Middleware\CsrfProtectionMiddleware; + use Cake\Http\Middleware\EncryptedCookieMiddleware; + + $routes->registerMiddleware('csrf', new CsrfProtectionMiddleware()); + $routes->registerMiddleware('cookies', new EncryptedCookieMiddleware()); + +Once registered, scoped middleware can be applied to specific +scopes:: + + $routes->scope('/cms', function (RouteBuilder $routes) { + // Enable CSRF & cookies middleware + $routes->applyMiddleware('csrf', 'cookies'); + $routes->get('/articles/{action}/*', ['controller' => 'Articles']); + }); + +In situations where you have nested scopes, inner scopes will inherit the +middleware applied in the containing scope:: + + $routes->scope('/api', function (RouteBuilder $routes) { + $routes->applyMiddleware('ratelimit', 'auth.api'); + $routes->scope('/v1', function (RouteBuilder $routes) { + $routes->applyMiddleware('v1compat'); + // Define routes here. + }); + }); + +In the above example, the routes defined in ``/v1`` will have 'ratelimit', +'auth.api', and 'v1compat' middleware applied. If you re-open a scope, the +middleware applied to routes in each scope will be isolated:: + + $routes->scope('/blog', function (RouteBuilder $routes) { + $routes->applyMiddleware('auth'); + // Connect the authenticated actions for the blog here. + }); + $routes->scope('/blog', function (RouteBuilder $routes) { + // Connect the public actions for the blog here. + }); + +In the above example, the two uses of the ``/blog`` scope do not share +middleware. However, both of these scopes will inherit middleware defined in +their enclosing scopes. + +Grouping Middleware +------------------- + +To help keep your route code :abbr:`DRY (Do not Repeat Yourself)` middleware can +be combined into groups. Once combined groups can be applied like middleware +can:: + + $routes->registerMiddleware('cookie', new EncryptedCookieMiddleware()); + $routes->registerMiddleware('auth', new AuthenticationMiddleware()); + $routes->registerMiddleware('csrf', new CsrfProtectionMiddleware()); + $routes->middlewareGroup('web', ['cookie', 'auth', 'csrf']); + + // Apply the group + $routes->applyMiddleware('web'); + +.. _resource-routes: + +RESTful Routing +=============== + +Router helps generate RESTful routes for your controllers. RESTful routes are +helpful when you are creating API endpoints for your application. If we wanted +to allow REST access to a recipe controller, we'd do something like this:: + + // In config/routes.php... + + $routes->scope('/', function (RouteBuilder $routes) { + $routes->setExtensions(['json']); + $routes->resources('Recipes'); + }); + +The first line sets up a number of default routes for REST +access where method specifies the desired result format, for example, xml, +json and rss. These routes are HTTP Request Method sensitive. + +=========== ===================== ============================== +HTTP format URL.format Controller action invoked +=========== ===================== ============================== +GET /recipes.format RecipesController::index() +----------- --------------------- ------------------------------ +GET /recipes/123.format RecipesController::view(123) +----------- --------------------- ------------------------------ +POST /recipes.format RecipesController::add() +----------- --------------------- ------------------------------ +PUT /recipes/123.format RecipesController::edit(123) +----------- --------------------- ------------------------------ +PATCH /recipes/123.format RecipesController::edit(123) +----------- --------------------- ------------------------------ +DELETE /recipes/123.format RecipesController::delete(123) +=========== ===================== ============================== + +.. note:: + + The default for pattern for resource IDs only matches integers or UUIDs. + If your IDs are different you will have to supply a regular expression pattern + via the ``id`` option, for example, ``$builder->resources('Recipes', ['id' => '.*'])``. + +The HTTP method being used is detected from a few different sources. +The sources in order of preference are: + +#. The ``_method`` POST variable +#. The ``X_HTTP_METHOD_OVERRIDE`` header. +#. The ``REQUEST_METHOD`` header + +The ``_method`` POST variable is helpful in using a browser as a +REST client (or anything else that can do POST). Just set +the value of ``_method`` to the name of the HTTP request method you +wish to emulate. + +Creating Nested Resource Routes +------------------------------- + +Once you have connected resources in a scope, you can connect routes for +sub-resources as well. Sub-resource routes will be prepended by the original +resource name and a id parameter. For example:: + + $routes->scope('/api', function (RouteBuilder $routes) { + $routes->resources('Articles', function (RouteBuilder $routes) { + $routes->resources('Comments'); + }); + }); + +Will generate resource routes for both ``articles`` and ``comments``. The +comments routes will look like:: + + /api/articles/{article_id}/comments + /api/articles/{article_id}/comments/{id} + +You can get the ``article_id`` in ``CommentsController`` by:: + + $this->request->getParam('article_id'); + +By default resource routes map to the same prefix as the containing scope. If +you have both nested and non-nested resource controllers you can use a different +controller in each context by using prefixes:: + + $routes->scope('/api', function (RouteBuilder $routes) { + $routes->resources('Articles', function (RouteBuilder $routes) { + $routes->resources('Comments', ['prefix' => 'Articles']); + }); + }); + +The above would map the 'Comments' resource to the +``App\Controller\Articles\CommentsController``. Having separate controllers lets +you keep your controller logic simpler. The prefixes created this way are +compatible with :ref:`prefix-routing`. + +.. note:: + + While you can nest resources as deeply as you require, it is not recommended + to nest more than 2 resources together. + +Limiting the Routes Created +--------------------------- + +By default CakePHP will connect 6 routes for each resource. If you'd like to +only connect specific resource routes you can use the ``only`` option:: + + $routes->resources('Articles', [ + 'only' => ['index', 'view'] + ]); + +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 +------------------------------------ + +You may need to change the controller action names that are used when connecting +routes. For example, if your ``edit()`` action is called ``put()`` you can +use the ``actions`` key to rename the actions used:: + + $routes->resources('Articles', [ + 'actions' => ['update' => 'put', 'create' => 'add'] + ]); + +The above would use ``put()`` for the ``edit()`` action, and ``add()`` +instead of ``create()``. + +Mapping Additional Resource Routes +---------------------------------- + +You can map additional resource methods using the ``map`` option:: + + $routes->resources('Articles', [ + 'map' => [ + 'deleteAll' => [ + 'action' => 'deleteAll', + 'method' => 'DELETE' + ] + ] + ]); + // This would connect /articles/deleteAll + +In addition to the default routes, this would also connect a route for +`/articles/delete-all`. By default the path segment will match the key name. You +can use the 'path' key inside the resource definition to customize the path +name:: + + $routes->resources('Articles', [ + 'map' => [ + 'updateAll' => [ + 'action' => 'updateAll', + 'method' => 'PUT', + 'path' => '/update-many', + ], + ], + ]); + // This would connect /articles/update-many + +If you define 'only' and 'map', make sure that your mapped methods are also in +the 'only' list. + +Prefixed Resource Routing +------------------------- + +Resource routes can be connected to controllers in routing prefixes by +connecting routes within a prefixed scope or by using the ``prefix`` option:: + + $routes->resources('Articles', [ + 'prefix' => 'Api', + ]); + +.. _custom-rest-routing: + +Custom Route Classes for Resource Routes +---------------------------------------- + +You can provide ``connectOptions`` key in the ``$options`` array for +``resources()`` to provide custom setting used by ``connect()``:: + + $routes->scope('/', function (RouteBuilder $routes) { + $routes->resources('Books', [ + 'connectOptions' => [ + 'routeClass' => 'ApiRoute', + ] + ]; + }); + +URL Inflection for Resource Routes +---------------------------------- + +By default, multi-worded controllers' URL fragments are the dashed +form of the controller's name. For example, ``BlogPostsController``'s URL fragment +would be **/blog-posts**. + +You can specify an alternative inflection type using the ``inflect`` option:: + + $routes->scope('/', function (RouteBuilder $routes) { + $routes->resources('BlogPosts', [ + 'inflect' => 'underscore' // Will use ``Inflector::underscore()`` + ]); + }); + +The above will generate URLs styled like: **/blog_posts**. + +Changing the Path Element +------------------------- + +By default resource routes use an inflected form of the resource name for the +URL segment. You can set a custom URL segment with the ``path`` option:: + + $routes->scope('/', function (RouteBuilder $routes) { + $routes->resources('BlogPosts', ['path' => 'posts']); + }); + +.. index:: passed arguments +.. _passed-arguments: + +Passed Arguments +================ + +Passed arguments are additional arguments or path segments that are +used when making a request. They are often used to pass parameters +to your controller methods. :: + + http://localhost/calendars/view/recent/mark + +In the above example, both ``recent`` and ``mark`` are passed arguments to +``CalendarsController::view()``. Passed arguments are given to your controllers +in three ways. First as arguments to the action method called, and secondly they +are available in ``$this->request->getParam('pass')`` as a numerically indexed +array. When using custom routes you can force particular parameters to go into +the passed arguments as well. + +If you were to visit the previously mentioned URL, and you +had a controller action that looked like:: + + class CalendarsController extends AppController + { + public function view($arg1, $arg2) + { + debug(func_get_args()); + } + } + +You would get the following output:: + + Array + ( + [0] => recent + [1] => mark + ) + +This same data is also available at ``$this->request->getParam('pass')`` in your +controllers, views, and helpers. The values in the pass array are numerically +indexed based on the order they appear in the called URL:: + + debug($this->request->getParam('pass')); + +Either of the above would output:: + + Array + ( + [0] => recent + [1] => mark + ) + +When generating URLs, using a :term:`arreglo de enrutamiento` you add passed +arguments as values without string keys in the array:: + + ['controller' => 'Articles', 'action' => 'view', 5] + +Since ``5`` has a numeric key, it is treated as a passed argument. + +Generating URLs +=============== + +.. php:staticmethod:: url($url = null, $full = false) +.. php:staticmethod:: reverse($params, $full = false) + +Generating URLs or Reverse routing is a feature in CakePHP that is used to +allow you to change your URL structure without having to modify all your code. + +If you create URLs using strings like:: + + $this->Html->link('View', '/articles/view/' . $id); + +And then later decide that ``/articles`` should really be called +'posts' instead, you would have to go through your entire +application renaming URLs. However, if you defined your link like:: + + //`link()` uses Router::url() internally and accepts a routing array + + $this->Html->link( + 'View', + ['controller' => 'Articles', 'action' => 'view', $id] + ); + +or:: + + //'Router::reverse()' operates on the request parameters array + //and will produce a url string, valid input for `link()` + + $requestParams = Router::getRequest()->getAttribute('params'); + $this->Html->link('View', Router::reverse($requestParams)); + +Then when you decided to change your URLs, you could do so by defining a +route. This would change both the incoming URL mapping, as well as the +generated URLs. + +The choice of technique is determined by how well you can predict the routing +array elements. + +Using ``Router::url()`` +----------------------- + +``Router::url()`` allows you to use :term:`routing arrays ` in +situations where the array elements required are fixed or easily deduced. + +It will provide reverse routing when the destination url is well defined:: + + $this->Html->link( + 'View', + ['controller' => 'Articles', 'action' => 'view', $id] + ); + +It is also useful when the destination is unknown but follows a well +defined pattern:: + + $this->Html->link( + 'View', + ['controller' => $controller, 'action' => 'view', $id] + ); + +Elements with numeric keys are treated as :ref:`passed-arguments`. + +When using routing arrays, you can define both query string parameters and +document fragments using special keys:: + + $routes->url([ + 'controller' => 'Articles', + 'action' => 'index', + '?' => ['page' => 1], + '#' => 'top' + ]); + + // Will generate a URL like. + /articles/index?page=1#top + +You can also use any of the special route elements when generating URLs: + +* ``_ext`` Used for :ref:`file-extensions` routing. +* ``_base`` Set to ``false`` to remove the base path from the generated URL. If + your application is not in the root directory, this can be used to generate + URLs that are 'cake relative'. +* ``_scheme`` Set to create links on different schemes like ``webcal`` or + ``ftp``. Defaults to the current scheme. +* ``_host`` Set the host to use for the link. Defaults to the current host. +* ``_port`` Set the port if you need to create links on non-standard ports. +* ``_method`` Define the HTTP verb the URL is for. +* ``_full`` If ``true`` the value of ``App.fullBaseUrl`` mentioned in + :ref:`general-configuration` will be prepended to generated URLs. +* ``_https`` Set to ``true`` to convert the generated URL to https or ``false`` + to force http. Prior to 4.5.0 use ``_ssl`` +* ``_name`` Name of route. If you have setup named routes, you can use this key + to specify it. + +Using ``Router::reverse()`` +--------------------------- + +``Router::reverse()`` allows you to use the :ref:`request-parameters` in cases +where the current URL with some modification is the basis for the destination +and the elements of the current URL are unpredictable. + +As an example, imagine a blog that allowed users to create **Articles** and +**Comments**, and to mark both as either *published* or *draft*. Both the index +page URLs might include the user id. The **Comments** URL might also include +an article id to identify what article the comment refers to. + +Here are urls for this scenario:: + + /articles/index/42 + /comments/index/42/18 + +When the author uses these pages, it would be convenient to include links +that allow the page to be displayed with all results, published only, +or draft only. + +To keep the code DRY, it would be best to include the links through +an element:: + + // element/filter_published.php + + $params = $this->getRequest()->getAttribute('params'); + + /* prepare url for Draft */ + $params = Hash::insert($params, '?.published', 0); + echo $this->Html->link(__('Draft'), Router::reverse($params)); + + /* Prepare url for Published */ + $params = Hash::insert($params, '?.published', 1); + echo $this->Html->link(__('Published'), Router::reverse($params)); + + /* Prepare url for All */ + $params = Hash::remove($params, '?.published'); + echo $this->Html->link(__('All'), Router::reverse($params)); + +The links generated by these method calls would include one or two pass +parameters depending on the structure of the current URL. And the code +would work for any future URL, for example, if you started using +pathPrefixes or if you added more pass parameters. + +Routing Arrays vs Request Parameters +------------------------------------- + +The significant difference between the two arrays and their use in these +reverse routing methods is in the way they include pass parameters. + +Routing arrays include pass parameters as un-keyed values in the array:: + + $url = [ + 'controller' => 'Articles', + 'action' => 'View', + $id, //a pass parameter + 'page' => 3, //a query argument + ]; + +Request parameters include pass parameters on the 'pass' key of the array:: + + $url = [ + 'controller' => 'Articles', + 'action' => 'View', + 'pass' => [$id], //the pass parameters + '?' => ['page' => 3], //the query arguments + ]; + +So it is possible, if you wish, to convert the request parameters into +a routing array or vice versa. + +.. _asset-routing: + +Generating Asset URLs +===================== + +The ``Asset`` class provides methods for generating URLs to your application's +css, javascript, images and other static asset files:: + + use Cake\Routing\Asset; + + // Generate a URL to APP/webroot/js/app.js + $js = Asset::scriptUrl('app.js'); + + // Generate a URL to APP/webroot/css/app.css + $css = Asset::cssUrl('app.css'); + + // Generate a URL to APP/webroot/image/logo.png + $img = Asset::imageUrl('logo.png'); + + // Generate a URL to APP/webroot/files/upload/photo.png + $file = Asset::url('files/upload/photo.png'); + +The above methods also accept an array of options as their second parameter: + +* ``fullBase`` Append the full URL with domain name. +* ``pathPrefix`` Path prefix for relative URLs. +* ``plugin``` You can provide ``false``` to prevent paths from being treated as + a plugin asset. +* ``timestamp`` Overrides the value of ``Asset.timestamp`` in Configure. Set to + ``false`` to skip timestamp generation. Set to ``true`` to apply timestamps + when debug is true. Set to ``'force'`` to always enable timestamping + regardless of debug value. + +:: + + // Generates http://example.org/img/logo.png + $img = Asset::url('logo.png', ['fullBase' => true]); + + // Generates /img/logo.png?1568563625 + // Where the timestamp is the last modified time of the file. + $img = Asset::url('logo.png', ['timestamp' => true]); + +To generate asset URLs for files in plugins use :term:`Sintaxis de plugin`:: + + // Generates `/debug_kit/img/cake.png` + $img = Asset::imageUrl('DebugKit.cake.png'); + +.. _redirect-routing: + +Redirect Routing +================ + +Redirect routing allows you to issue HTTP status 30x redirects for +incoming routes, and point them at different URLs. This is useful +when you want to inform client applications that a resource has moved +and you don't want to expose two URLs for the same content. + +Redirection routes are different from normal routes as they perform an actual +header redirection if a match is found. The redirection can occur to +a destination within your application or an outside location:: + + $routes->scope('/', function (RouteBuilder $routes) { + $routes->redirect( + '/home/*', + ['controller' => 'Articles', 'action' => 'view'], + ['persist' => true] + // Or ['persist'=>['id']] for default routing where the + // view action expects $id as an argument. + ); + }) + +Redirects ``/home/*`` to ``/articles/view`` and passes the parameters to +``/articles/view``. Using an array as the redirect destination allows +you to use other routes to define where a URL string should be +redirected to. You can redirect to external locations using +string URLs as the destination:: + + $routes->scope('/', function (RouteBuilder $routes) { + $routes->redirect('/articles/*', 'http://google.com', ['status' => 302]); + }); + +This would redirect ``/articles/*`` to ``http://google.com`` with a +HTTP status of 302. + +.. _entity-routing: + +Entity Routing +============== + +Entity routing allows you to use an entity, an array or object implement +``ArrayAccess`` as the source of routing parameters. This allows you to refactor +routes more easily, and generate URLs with less code. For example, if you start +off with a route that looks like:: + + $routes->get( + '/view/{id}', + ['controller' => 'Articles', 'action' => 'view'], + 'articles:view' + ); + +You can generate URLs to this route using:: + + // $article is an entity in the local scope. + Router::url(['_name' => 'articles:view', 'id' => $article->id]); + +Later on, you may want to expose the article slug in the URL for SEO purposes. +In order to do this you would need to update everywhere you generate a URL to +the ``articles:view`` route, which could take some time. If we use entity routes +we pass the entire article entity into URL generation allowing us to skip any +rework when URLs require more parameters:: + + use Cake\Routing\Route\EntityRoute; + + // Create entity routes for the rest of this scope. + $routes->setRouteClass(EntityRoute::class); + + // Create the route just like before. + $routes->get( + '/view/{id}/{slug}', + ['controller' => 'Articles', 'action' => 'view'], + 'articles:view' + ); + +Now we can generate URLs using the ``_entity`` key:: + + Router::url(['_name' => 'articles:view', '_entity' => $article]); + +This will extract both the ``id`` property and the ``slug`` property out of the +provided entity. + +.. _custom-route-classes: + +Custom Route Classes +==================== + +Custom route classes allow you to extend and change how individual routes parse +requests and handle reverse routing. Route classes have a few conventions: + +* Route classes are expected to be found in the ``Routing\\Route`` namespace of + your application or plugin. +* Route classes should extend :php:class:`Cake\\Routing\\Route\\Route`. +* Route classes should implement one or both of ``match()`` and/or ``parse()``. + +The ``parse()`` method is used to parse an incoming URL. It should generate an +array of request parameters that can be resolved into a controller & action. +Return ``null`` from this method to indicate a match failure. + +The ``match()`` method is used to match an array of URL parameters and create a +string URL. If the URL parameters do not match the route ``false`` should be +returned. + +You can use a custom route class when making a route by using the ``routeClass`` +option:: + + $routes->connect( + '/{slug}', + ['controller' => 'Articles', 'action' => 'view'], + ['routeClass' => 'SlugRoute'] + ); + + // Or by setting the routeClass in your scope. + $routes->scope('/', function (RouteBuilder $routes) { + $routes->setRouteClass('SlugRoute'); + $routes->connect( + '/{slug}', + ['controller' => 'Articles', 'action' => 'view'] + ); + }); + +This route would create an instance of ``SlugRoute`` and allow you +to implement custom parameter handling. You can use plugin route classes using +standard :term:`Sintaxis de plugin`. + +Default Route Class +------------------- + +.. php:staticmethod:: setRouteClass($routeClass = null) + +If you want to use an alternate route class for your routes besides the +default ``Route``, you can do so by calling ``RouterBuilder::setRouteClass()`` +before setting up any routes and avoid having to specify the ``routeClass`` +option for each route. For example using:: + + use Cake\Routing\Route\DashedRoute; + + $routes->setRouteClass(DashedRoute::class); + +will cause all routes connected after this to use the ``DashedRoute`` route class. +Calling the method without an argument will return current default route class. + +Fallbacks Method +---------------- + +.. php:method:: fallbacks($routeClass = null) + +The fallbacks method is a simple shortcut for defining default routes. The +method uses the passed routing class for the defined rules or if no class is +provided the class returned by ``RouterBuilder::setRouteClass()`` is used. + +Calling fallbacks like so:: + + use Cake\Routing\Route\DashedRoute; + + $routes->fallbacks(DashedRoute::class); + +Is equivalent to the following explicit calls:: + + use Cake\Routing\Route\DashedRoute; + + $routes->connect('/{controller}', ['action' => 'index'], ['routeClass' => DashedRoute::class]); + $routes->connect('/{controller}/{action}/*', [], ['routeClass' => DashedRoute::class]); + +.. note:: + + Using the default route class (``Route``) with fallbacks, or any route + with ``{plugin}`` and/or ``{controller}`` route elements will result in + inconsistent URL case. + +.. warning:: + Fallback route templates are very generic and allow URLs to be generated + and parsed for controllers & actions that do not exist. Fallback URLs can + also introduce ambiguity and duplication in your URLs. + + As your application grows, it is recommended to move away from fallback URLs + and explicitly define the routes in your application. + +Creating Persistent URL Parameters +================================== + +You can hook into the URL generation process using URL filter functions. Filter +functions are called *before* the URLs are matched against the routes, this +allows you to prepare URLs before routing. + +Callback filter functions should expect the following parameters: + +- ``$params`` The URL parameter array being processed. +- ``$request`` The current request (``Cake\Http\ServerRequest`` instance). + +The URL filter function should *always* return the parameters even if unmodified. + +URL filters allow you to implement features like persistent parameters:: + + Router::addUrlFilter(function (array $params, ServerRequest $request) { + if ($request->getParam('lang') && !isset($params['lang'])) { + $params['lang'] = $request->getParam('lang'); + } + return $params; + }); + +Filter functions are applied in the order they are connected. + +Another use case is changing a certain route on runtime (plugin routes for +example):: + + Router::addUrlFilter(function (array $params, ServerRequest $request) { + if (empty($params['plugin']) || $params['plugin'] !== 'MyPlugin' || empty($params['controller'])) { + return $params; + } + if ($params['controller'] === 'Languages' && $params['action'] === 'view') { + $params['controller'] = 'Locations'; + $params['action'] = 'index'; + $params['language'] = $params[0]; + unset($params[0]); + } + return $params; + }); + +This will alter the following route:: + + Router::url(['plugin' => 'MyPlugin', 'controller' => 'Languages', 'action' => 'view', 'es']); + +into this:: + + Router::url(['plugin' => 'MyPlugin', 'controller' => 'Locations', 'action' => 'index', 'language' => 'es']); - /development/dispatch-filters +.. warning:: + If you are using the caching features of :ref:`routing-middleware` you must + define the URL filters in your application ``bootstrap()`` as filters are + not part of the cached data. .. meta:: - :title lang=es: Routing - :keywords lang=es: controller actions,default routes,mod rewrite,code index,string url,php class,incoming requests,dispatcher,url url,meth,maps,match,parameters,array,config,cakephp,apache,router + :title lang=es: Enrutamiento + :keywords lang=en: controller actions,default routes,mod rewrite,code index,string url,php class,incoming requests,dispatcher,url url,meth,maps,match,parameters,array,config,cakephp,apache,router diff --git a/es/epub-contents.rst b/es/epub-contents.rst index 24a55dcc12..3d175d17ee 100644 --- a/es/epub-contents.rst +++ b/es/epub-contents.rst @@ -1,14 +1,14 @@ :orphan: -Contents -######## +Contenidos +########## .. toctree:: :maxdepth: 3 intro quickstart - appendices/4-0-migration-guide + appendices/migration-guides tutorials-and-examples contributing @@ -20,10 +20,9 @@ Contents views orm - controllers/components/authentication - bake core-libraries/caching - console-and-shells + bake + console-commands development/debugging deployment core-libraries/email @@ -32,7 +31,7 @@ Contents core-libraries/internationalization-and-localization core-libraries/logging core-libraries/form - controllers/components/pagination + controllers/pagination plugins development/rest security @@ -42,7 +41,6 @@ Contents core-libraries/app core-libraries/collections - core-libraries/file-folder core-libraries/hash core-libraries/httpclient core-libraries/inflector @@ -53,12 +51,14 @@ Contents core-libraries/xml core-libraries/global-constants-and-functions + chronos debug-kit migrations + elasticsearch appendices .. todolist:: .. meta:: - :title lang=es: Contents - :keywords lang=es: core libraries,ref search,shells,deployment,appendices,glossary,models + :title lang=es: Contenidos + :keywords lang=en: core libraries,ref search,commands,deployment,appendices,glossary,models diff --git a/es/orm.rst b/es/orm.rst index 59c071311b..6ed39411a0 100644 --- a/es/orm.rst +++ b/es/orm.rst @@ -108,4 +108,4 @@ Más información orm/associations orm/behaviors orm/schema-system - console-and-shells/orm-cache + console-commands/schema-cache diff --git a/es/phinx.rst b/es/phinx.rst new file mode 100644 index 0000000000..53312b3a90 --- /dev/null +++ b/es/phinx.rst @@ -0,0 +1,4 @@ +Migraciones con Phinx +###################### + +Esta página ha sido `movida `__. diff --git a/es/release-policy.rst b/es/release-policy.rst new file mode 100644 index 0000000000..5be9e648f4 --- /dev/null +++ b/es/release-policy.rst @@ -0,0 +1,54 @@ +Política de Versiones +##################### + +CakePHP sigue la versión semántica para todas sus versiones. Esto sigue la convención de versionado de **importante.menor.parche**. + +El equipo de desarrollo intenta garantizar que cada versión siga las restricciones y garantías a continuación. + +Versiones Importantes +--------------------- + +Las versiones importantes generalmente no son retrocompatibles. Aunque CakePHP intenta no cambiar muchas características importantes en las versiones importantes, hay cambios en la API. + +Los cambios en las versiones importantes pueden incluir casi cualquier cosa, pero siempre se utilizan para eliminar características obsoletas y actualizar interfaces. + +Cualquier cambio de comportamiento que no sea retrocompatible se realiza en cambios importantes. + +Cada versión importante suele venir con una guía de actualización y muchas actualizaciones automáticas de código utilizando rector. + +Versiones Menores +----------------- + +Las versiones menores son generalmente retrocompatibles con la versión menor y el parche anterior. + +Las características pueden ser obsoletas, pero nunca se eliminan en una versión menor. + +Las interfaces no se cambian, pero se pueden agregar anotaciones para nuevos métodos expuestos en las implementaciones proporcionadas por CakePHP. + +Las nuevas características generalmente solo se agregan en versiones menores para que los usuarios puedan seguir las notas de migración. Las nuevas características también pueden incluir nuevas excepciones lanzadas cuando se corrige un comportamiento o se informan errores. + +Los cambios de comportamiento que requieren documentación se realizan en las versiones menores, pero generalmente son retrocompatibles. Se pueden hacer algunas excepciones si el problema es grave. + +.. nota:: + Las versiones menores también se conocen como versiones de puntos. + +Versiones de Parches +-------------------- + +Las versiones de parches siempre son retrocompatibles. Solo se realizan cambios que solucionan características rotas. + +Por lo general, los usuarios deberían poder confiar en que las versiones de parches no cambiarán el comportamiento, excepto para solucionar un problema. + +Los problemas que cambian un comportamiento de larga data generalmente no se encuentran en versiones de parches. Estos se consideran cambios de comportamiento y se incluirán en versiones menores o importantes para que los usuarios puedan migrar. + +.. nota:: + Las versiones de parches también se conocen como versiones de corrección de errores. + +Funciones Experimentales +------------------------ + +Cuando se agrega una nueva característica donde la API todavía está cambiando, puede marcarse como **experimental**. + +Las características experimentales deben seguir la misma convención de versiones menores y de corrección de errores. Sin embargo, los cambios en la API pueden ir en versiones menores, lo que podría cambiar significativamente el comportamiento. + +Los usuarios siempre deben esperar que la API cambie antes de que las características experimentales se lancen por completo. diff --git a/es/security.rst b/es/security.rst index 6a7ca602a1..e9791bb1b1 100644 --- a/es/security.rst +++ b/es/security.rst @@ -1,22 +1,20 @@ -Security -######## +Seguridad +########## -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +CakePHP provee algunas herramientas para hacer +que tu aplicación sea segura. Las siguientes secciones +cubren estas herramientas: .. toctree:: :maxdepth: 1 core-libraries/security - controllers/components/csrf - controllers/components/security + Form Protection Middleware + CSRF Protection + Content Security Policy + Security Headers + HTTPS Enforcer .. meta:: - :title lang=es: Security + :title lang=es: Seguridad :keywords lang=es: security, csrf, cross site request forgery component diff --git a/es/security/content-security-policy.rst b/es/security/content-security-policy.rst new file mode 100644 index 0000000000..6b797103d2 --- /dev/null +++ b/es/security/content-security-policy.rst @@ -0,0 +1,54 @@ +Content Security Policy Middleware +################################## + +The ``CspMiddleware`` makes it simpler to add Content-Security-Policy headers in +your application. Before using it you should install ``paragonie/csp-builder``: + +.. code-block:: bash + + composer require paragonie/csp-builder + +You can then configure the middleware using an array, or passing in a built +``CSPBuilder`` object:: + + use Cake\Http\Middleware\CspMiddleware; + + $csp = new CspMiddleware([ + 'script-src' => [ + 'allow' => [ + 'https://www.google-analytics.com', + ], + 'self' => true, + 'unsafe-inline' => false, + 'unsafe-eval' => false, + ], + ]); + + $middlewareQueue->add($csp); + +If you want to use a more strict CSP configuration, you can enable nonce based +CSP rules with the ``scriptNonce`` and ``styleNonce`` options. When enabled +these options will modify your CSP policy and set the ``cspScriptNonce`` and +``cspStyleNonce`` attributes in the request. These attributes are applied to +the ``nonce`` attribute of all script and CSS link elements created by +``HtmlHelper``. This simplifies the adoption of policies that use +a `nonce-base64 +`__ +and ``strict-dynamic`` for increased security and easier maintenance:: + + + $policy = [ + // Must exist even if empty to set nonce for for script-src + 'script-src' => [], + 'style-src' => [], + ]; + // Enable automatic nonce addition to script & CSS link tags. + $csp = new CspMiddleware($policy, [ + 'scriptNonce' => true, + 'styleNonce' => true, + ]); + $middlewareQueue->add($csp); + +.. meta:: + :title lang=en: Content Security Policy Middleware + :keywords lang=en: security, content security policy, csp, middleware, cross-site scripting diff --git a/es/security/csrf.rst b/es/security/csrf.rst new file mode 100644 index 0000000000..a191232e97 --- /dev/null +++ b/es/security/csrf.rst @@ -0,0 +1,174 @@ +Protección CSRF +############### + +Las Solicitudes CSRF son una clase de ataque donde se realizan comandos no autorizados en nombre de un usuario autenticado sin su conocimiento o consentimiento. + +CakePHP ofrece dos formas de protección CSRF: + +* ``SessionCsrfProtectionMiddleware`` almacena tokens CSRF en la sesión. Esto requiere que tu aplicación abra la sesión en cada solicitud. Los beneficios de los tokens CSRF basados en sesiones son que están vinculados a un usuario específico y sólo son válidos durante la duración de una sesión activa. +* ``CsrfProtectionMiddleware`` almacena tokens CSRF en una cookie. Usar una cookie permite realizar verificaciones CSRF sin ningún estado en el servidor. Los valores de las cookies se verifican en términos de autenticidad mediante una comprobación HMAC. Sin embargo, debido a su naturaleza sin estado, los tokens CSRF se pueden reutilizar entre usuarios y sesiones. + +.. nota:: + + No puedes usar ambos enfoques a la vez, debes elegir sólo uno. Si usas ambos, ocurrirá un error de incompatibilidad de tokens CSRF en cada solicitud `PUT` y `POST`. + +.. _csrf-middleware: + +Middleware CSRF +=============== + +La protección CSRF se puede aplicar a toda tu aplicación o a ámbitos de enrutamiento específicos. Al aplicar un middleware CSRF a tu cola de middlewares, proteges todas las acciones en la aplicación:: + + // En src/Application.php + // Para tokens CSRF basados en cookies. + use Cake\Http\Middleware\CsrfProtectionMiddleware; + + // Para tokens CSRF basados en sesiones. + use Cake\Http\Middleware\SessionCsrfProtectionMiddleware; + + public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue + { + $opciones = [ + // ... + ]; + $csrf = new CsrfProtectionMiddleware($opciones); + // o + $csrf = new SessionCsrfProtectionMiddleware($opciones); + + $middlewareQueue->add($csrf); + return $middlewareQueue; + } + +Al aplicar la protección CSRF a los ámbitos de enrutamiento, puedes aplicar condicionalmente CSRF a grupos específicos de rutas:: + + // en src/Application.php + use Cake\Http\Middleware\CsrfProtectionMiddleware; + + public function routes(RouteBuilder $routes) : void + { + $options = [ + // ... + ]; + $routes->registerMiddleware('csrf', new CsrfProtectionMiddleware($options)); + parent::routes($routes); + } + + // en config/routes.php + $routes->scope('/', function (RouteBuilder $routes) { + $routes->applyMiddleware('csrf'); + }); + +Opciones del middleware CSRF basado en cookies +----------------------------------------------- + +Las opciones de configuración disponibles son: + +- ``cookieName``: El nombre de la cookie que se enviará. Por defecto es ``csrfToken``. +- ``expiry``: Cuánto tiempo debe durar el token CSRF. Por defecto es por la sesión del navegador. +- ``secure``: Si la cookie se establecerá o no con la bandera Secure. Es decir, la cookie sólo se establecerá en una conexión HTTPS y cualquier intento sobre HTTP normal fallará. Por defecto es ``false``. +- ``httponly``: Si la cookie se establecerá o no con la bandera HttpOnly. Por defecto es ``false``. Antes de la versión 4.1.0, usa la opción ``httpOnly``. +- ``samesite``: Te permite declarar si tu cookie debe estar restringida a un contexto de primer partido o mismo sitio. Los valores posibles son ``Lax``, ``Strict`` y ``None``. Por defecto es ``null``. +- ``field``: El campo del formulario a comprobar. Por defecto es ``_csrfToken``. Cambiar esto también requerirá configurar FormHelper. + +Opciones del middleware CSRF basado en sesiones +----------------------------------------------- + +Las opciones de configuración disponibles son: + +- ``key``: La clave de sesión a utilizar. Por defecto es `csrfToken`. +- ``field``: El campo del formulario a comprobar. Cambiar esto también requerirá configurar FormHelper. + +Cuando está habilitado, puedes acceder al token CSRF actual en el objeto de Request:: + + $token = $this->request->getAttribute('csrfToken'); + +Si necesitas rotar o reemplazar el token CSRF de la sesión, puedes hacerlo con:: + + $this->request = SessionCsrfProtectionMiddleware::replaceToken($this->request); + +.. versionadded:: 4.3.0 + Se añadió el método ``replaceToken``. + +Omitir comprobaciones CSRF para acciones específicas +----------------------------------------------------- + +Ambas implementaciones de middleware CSRF te permiten usar la función ``skip check`` para un control más preciso sobre las URL para las cuales se debe hacer la comprobación de tokens CSRF:: + + // en src/Application.php + use Cake\Http\Middleware\CsrfProtectionMiddleware; + + public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue + { + $csrf = new CsrfProtectionMiddleware(); + + // La comprobación del token se omitirá cuando el callback devuelva `true`. + $csrf->skipCheckCallback(function ($request) { + // Omitir la comprobación del token para las URL de la API. + if ($request->getParam('prefix') === 'Api') { + return true; + } + }); + + // Asegúrate de que el middleware de enrutamiento se añada a la cola antes del middleware de protección CSRF. + $middlewareQueue->add($csrf); + + return $middlewareQueue; + } + +.. nota:: + + Debes aplicar el middleware de protección CSRF solo para rutas que manejen + solicitudes con estado que utilicen cookies/sesiones. Por ejemplo, al desarrollar una + API, las solicitudes sin estado que no usan cookies para la autenticación no se ven + afectadas por CSRF, por lo que el middleware no necesita aplicarse para esas rutas. + +Integración con FormHelper +-------------------------- + +El ``CsrfProtectionMiddleware`` se integra perfectamente con ``FormHelper``. Cada vez +que creas un formulario con ``FormHelper``, se insertará un campo oculto que contiene +el token CSRF. + +.. nota:: + + Cuando uses protección CSRF, siempre debes empezar tus formularios con + ``FormHelper``. Si no lo haces, deberás crear manualmente los campos ocultos en + cada uno de tus formularios. + +Protección CSRF y Solicitudes AJAX +----------------------------------- + +Además de los parámetros de datos de la solicitud, los tokens CSRF se pueden enviar a través +de un encabezado especial ``X-CSRF-Token``. Usar un encabezado a menudo facilita la +integración de un token CSRF con aplicaciones JavaScript, o `endpoints` de API +basados en XML/JSON. + +El Token CSRF se puede obtener en JavaScript a través de la Cookie ``csrfToken``, o en PHP +a través del atributo del objeto de Request llamado ``csrfToken``. Usar la cookie puede ser más fácil +cuando tu código JavaScript reside en archivos separados de las plantillas de vista de CakePHP, +y cuando ya tienes funcionalidad para analizar cookies mediante JavaScript. + +Si tienes archivos JavaScript separados pero no quieres ocuparte de manejar cookies, +podrías, por ejemplo, configurar el token en una variable global de JavaScript en tu diseño, mediante +la definición de un bloque de script como este:: + + echo $this->Html->scriptBlock(sprintf( + 'var csrfToken = %s;', + json_encode($this->request->getAttribute('csrfToken')) + )); + +Luego puedes acceder al token como ``csrfToken`` o ``window.csrfToken`` en cualquier archivo de script +que se cargue después de este bloque de script. + +Otra alternativa sería poner el token en una metaetiqueta personalizada como esta:: + + echo $this->Html->meta('csrfToken', $this->request->getAttribute('csrfToken')); + +que luego se podría acceder en tus scripts buscando el elemento ``meta`` con +el nombre ``csrfToken``, que podría ser tan simple como esto cuando se usa jQuery:: + + var csrfToken = $('meta[name="csrfToken"]').attr('content'); + +.. meta:: + :title lang=es: Protección CSRF + :keywords lang=es: seguridad, csrf, falsificación de solicitudes entre sitios, middleware, sesión diff --git a/es/security/https-enforcer.rst b/es/security/https-enforcer.rst new file mode 100644 index 0000000000..63e99beeea --- /dev/null +++ b/es/security/https-enforcer.rst @@ -0,0 +1,65 @@ +.. _https-enforcer-middleware: + +HTTPS Enforcer Middleware +######################### + +If you want your application to only be available via HTTPS connections you can +use the ``HttpsEnforcerMiddleware``:: + + use Cake\Http\Middleware\HttpsEnforcerMiddleware; + + // Always raise an exception and never redirect. + $https = new HttpsEnforcerMiddleware([ + 'redirect' => false, + ]); + + // Send a 302 status code when redirecting + $https = new HttpsEnforcerMiddleware([ + 'redirect' => true, + 'statusCode' => 302, + ]); + + // Send additional headers in the redirect response. + $https = new HttpsEnforcerMiddleware([ + 'headers' => ['X-Https-Upgrade' => 1], + ]); + + // Disable HTTPs enforcement when ``debug`` is on. + $https = new HttpsEnforcerMiddleware([ + 'disableOnDebug' => true, + ]); + + // Only trust HTTP_X_ headers from the listed servers. + $https = new HttpsEnforcerMiddleware([ + 'trustProxies' => ['192.168.1.1'], + ]); + +If a non-HTTP request is received that does not use GET a ``BadRequestException`` will be raised. + +NOTE: The Strict-Transport-Security header is ignored by the browser when your site has only been +accessed using HTTP. Once your site is accessed over HTTPS with no certificate errors, the browser +knows your site is HTTPS capable and will honor the Strict-Transport-Security header. + +Adding Strict-Transport-Security +================================ + +When your application requires SSL it is a good idea to set the +``Strict-Transport-Security`` header. This header value is cached in the +browser, and informs browsers that they should always connect with HTTPS connections. +You can configure this header with the ``hsts`` option:: + + $https = new HttpsEnforcerMiddleware([ + 'hsts' => [ + // How long the header value should be cached for. + 'maxAge' => 60 * 60 * 24 * 365, + // should this policy apply to subdomains? + 'includeSubDomains' => true, + // Should the header value be cacheable in google's HSTS preload + // service? While not part of the spec it is widely implemented. + 'preload' => true, + ], + ]); + +.. meta:: + :title lang=en: HTTPS Enforcer Middleware + :keywords lang=en: security, https, require https diff --git a/es/security/security-headers.rst b/es/security/security-headers.rst new file mode 100644 index 0000000000..f6d9901ca0 --- /dev/null +++ b/es/security/security-headers.rst @@ -0,0 +1,34 @@ +.. _security-header-middleware: + +Middleware SecurityHeader +######################### + +El ``SecurityHeaderMiddleware`` te permite agregar headers +relacionados con la seguridad a tu aplicación. Una vez configurado, el middleware +agregará los siguientes headers a las respuestas: + +* ``X-Content-Type-Options`` +* ``X-Download-Options`` +* ``X-Frame-Options`` +* ``Referrer-Policy`` + +Este middleware debe ser configurado antes de agregarlo a la cola de middlewares:: + + use Cake\Http\Middleware\SecurityHeadersMiddleware; + + $securityHeaders = new SecurityHeadersMiddleware(); + $securityHeaders + ->setReferrerPolicy() + ->setXFrameOptions() + ->noOpen() + ->noSniff(); + + $middlewareQueue->add($securityHeaders); + +Aqui está uina lista de `Headers HTTP comunes `__, +y la `configuración recomendada `__ de Mozzilla para +aplicaciones web seguras. + +.. meta:: + :title lang=en: Middleware SecurityHeader + :keywords lang=en: x-frame-options, cross-domain, referrer-policy, download-options, middleware, content-type-options diff --git a/es/standalone-packages.rst b/es/standalone-packages.rst new file mode 100644 index 0000000000..1d78dd3fa1 --- /dev/null +++ b/es/standalone-packages.rst @@ -0,0 +1,76 @@ +Paquetes Independientes +########################glo + +El núcleo de CakePHP está dividido en varios paquetes que pueden +ser usados de manera independiente. + +`ORM `_ +--------------------------------------- + +Un mapeador objeto-relacional flexible, ligero y poderoso para PHP. Ha +sido implementado usando el patrón `DataMapper`. + +`Database `_ +------------------------------------------------- + +Librería flexible de base de datos con un API similar a PDO. + +`Datasource `_ +----------------------------------------------------- + +Provee un manejo de conexiones y `traits` para entidades y `Queries` que +puede ser reusado por diferentes tipos de almacenamiento de datos. + +`HTTP `_ +----------------------------------------- + +Cliente HTTP y librerias compatibles con los estándares PSR-18 y PSR-15. + +`Console `_ +----------------------------------------------- + +Librería para crear aplicaciones de línea de comando. + +`Collection `_ +----------------------------------------------------- + +Librería que provee un conjunto de herramientas para manipular arreglos y objetos de tipo Traversable. + +`I18n `_ +----------------------------------------- + +Provee soporte para traducción y localización para fechas y números. + +`Cache `_ +------------------------------------------- + +Librería de caché que soporta distintos manejadores. Es compatible con PSR-16. + +`Log `_ +--------------------------------------- + +Librería para escribir registros (`logging`) con soporte para múltiples manejadores. Es compatible con PSR-3. + +`Event `_ +------------------------------------------- + +Librería de manejo de eventos. + +`Utility `_ +----------------------------------------------- + +Librería que incluye clases de utilidad como Inflexto, Tet, Hash, Security y Xml. + +`Validation `_ +----------------------------------------------------- + +Librería de validación de CakePHP. + +`Form `_ +----------------------------------------- + +Librería usada para crear formularios no enlazados con el ORM o algún otro almacenamiento de datos. + +.. meta:: + :title lang=en: Packages Independientes + :keywords lang=en: packages, cakephp, orm, database, http client, http server, utility, events, log, cache diff --git a/es/topics.rst b/es/topics.rst index 51e8f8c684..b02564f354 100644 --- a/es/topics.rst +++ b/es/topics.rst @@ -24,15 +24,14 @@ Introducción a las partes principales de CakePHP: * :doc:`/core-libraries/form` * :doc:`/development/sessions` * :doc:`/development/rest` -* :doc:`/controllers/components/authentication` -* :doc:`/controllers/components/pagination` -* :doc:`/controllers/components/csrf` +* :doc:`/controllers/pagination` +* :ref:`csrf-middleware` * :doc:`/core-libraries/email` * :doc:`/views/helpers/form` * :doc:`/views/helpers/html` * :doc:`/core-libraries/validation` * :doc:`/development/testing` * :doc:`/deployment` -* :doc:`/console-and-shells` +* :doc:`/console-commands` * :doc:`/contributing` * :doc:`/tutorials-and-examples` diff --git a/es/views/helpers.rst b/es/views/helpers.rst index 500f5e5813..e33bada0c5 100644 --- a/es/views/helpers.rst +++ b/es/views/helpers.rst @@ -1,14 +1,15 @@ Helpers ####### -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +Los Helpers son clases similares a componentes para la capa de presentación de tu aplicación. +Contienen lógica de presentación que se comparte entre muchas vistas, elementos o diseños. +Este capítulo te mostrará cómo configurar los helpers, cómo cargarlos y usarlos, y te guiará +en los simples pasos para crear tus propios helpers personalizados. - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +CakePHP incluye varios helpers que ayudan en la creación de vistas. Ayudan en la creación de +estructuras bien formadas (incluyendo formularios), ayudan en el formato de texto, horas y números, +e incluso pueden acelerar la funcionalidad AJAX. Para obtener más información sobre los helpers +incluidos en CakePHP, consulta el capítulo correspondiente para cada helper: .. toctree:: :maxdepth: 1 @@ -19,12 +20,332 @@ Helpers /views/helpers/html /views/helpers/number /views/helpers/paginator - /views/helpers/rss - /views/helpers/session /views/helpers/text /views/helpers/time /views/helpers/url +.. _configuring-helpers: + +Configurando Helpers +==================== + +Configuras los helpers en CakePHP declarándolos en una clase de vista. Cada aplicación +CakePHP incluye una clase ``AppView`` que es el lugar ideal para añadir helpers para su uso global:: + + class AppView extends View + { + public function initialize(): void + { + parent::initialize(); + $this->addHelper('Html'); + $this->addHelper('Form'); + $this->addHelper('Flash'); + } + } + +Para añadir helpers desde plugins, utiliza la :term:`Sintaxis de plugin` utilizada en otros lugares en CakePHP:: + + $this->addHelper('Blog.Comment'); + +No es necesario añadir explícitamente los Helpers que provienen de CakePHP o de tu aplicación. Estos helpers se pueden cargar de forma tardía (lazy loaded) cuando se utilizan por primera vez. Por ejemplo:: + + // Carga el FormHelper si aún no se ha añadido/cargado explícitamente. + $this->Form->create($article); + +Desde las vistas de un plugin, los helpers del plugin también se pueden cargar de forma tardía. Por ejemplo, las plantillas de vista en el plugin 'Blog' pueden cargar los helpers del mismo plugin. + +Carga Condicional de Helpers +---------------------------- + +Puedes utilizar el nombre de la acción actual para añadir helpers de forma condicional:: + + class AppView extends View + { + public function initialize(): void + { + parent::initialize(); + if ($this->request->getParam('action') === 'index') { + $this->addHelper('ListPage'); + } + } + } + +También puedes utilizar el método ``beforeRender`` de tu controlador para añadir helpers:: + + class ArticlesController extends AppController + { + public function beforeRender(EventInterface $event) + { + parent::beforeRender($event); + $this->viewBuilder()->addHelper('MyHelper'); + } + } + +Opciones de Configuración +------------------------- + +Puedes pasar opciones de configuración a los helpers. Estas opciones se pueden utilizar para establecer valores de atributos o modificar el comportamiento de un helper:: + + namespace App\View\Helper; + + use Cake\View\Helper; + use Cake\View\View; + + class AwesomeHelper extends Helper + { + public function initialize(array $config): void + { + debug($config); + } + } + +Por defecto, todas las opciones de configuración se fusionarán con la propiedad ``$_defaultConfig``. Esta propiedad debe definir los valores por defecto de cualquier configuración que tu helper requiera. Por ejemplo:: + + namespace App\View\Helper; + + use Cake\View\Helper; + use Cake\View\StringTemplateTrait; + + class AwesomeHelper extends Helper + { + use StringTemplateTrait; + + /** + * @var array + */ + protected $_defaultConfig = [ + 'errorClass' => 'error', + 'templates' => [ + 'label' => '', + ], + ]; + } + +Cualquier configuración proporcionada al constructor de tu helper se fusionará con los valores por defecto durante la construcción y los datos fusionados se establecerán en ``_config``. Puedes utilizar el método ``getConfig()`` para leer la configuración en tiempo de ejecución:: + + // Lee la opción de configuración errorClass. + $class = $this->Awesome->getConfig('errorClass'); + +Usar la configuración del helper te permite configurar declarativamente tus helpers y mantener la lógica de configuración fuera de las acciones de tu controlador. Si tienes opciones de configuración que no se pueden incluir como parte de una declaración de clase, puedes configurarlas en el callback ``beforeRender`` de tu controlador:: + + class PostsController extends AppController + { + public function beforeRender(EventInterface $event) + { + parent::beforeRender($event); + $builder = $this->viewBuilder(); + $builder->helpers([ + 'CustomStuff' => $this->_getCustomStuffConfig(), + ]); + } + } + +.. _aliasing-helpers: + +Alias de Helpers +---------------- + +Un ajuste común para usar es la opción ``className``, que te permite crear alias para los helpers en tus vistas. Esta característica es útil cuando quieres reemplazar ``$this->Html`` u otra referencia común de Helper con una implementación personalizada:: + + // src/View/AppView.php + class AppView extends View + { + public function initialize(): void + { + $this->addHelper('Html', [ + 'className' => 'MyHtml', + ]); + } + } + + // src/View/Helper/MyHtmlHelper.php + namespace App\View\Helper; + + use Cake\View\Helper\HtmlHelper; + + class MyHtmlHelper extends HtmlHelper + { + // Agrega tu código para sobrescribir el HtmlHelper principal + } + +Lo anterior haría que ``MyHtmlHelper`` se pudiera utilizar usando el *alias* ``$this->Html`` en tus vistas. + +.. note:: + + Hacer un alias de un helper reemplaza esa instancia en cualquier lugar donde se utilice ese helper, incluso dentro de otros Helpers. + +Usar Helpers +============= + +Una vez que hayas configurado qué helpers quieres usar en tu controlador, cada helper se expone como una propiedad pública en la vista. Por ejemplo, si estás utilizando el :php:class:`HtmlHelper`, podrías acceder a él haciendo lo siguiente:: + + echo $this->Html->css('styles'); + +Lo anterior llamaría al método ``css()`` en el HtmlHelper. Puedes acceder a cualquier helper cargado usando ``$this->{$nombreDelHelper}``. + +Cargar Helpers Dinámicamente +---------------------------- + +Puede haber situaciones en las que necesites cargar dinámicamente un helper desde dentro de una vista. Puedes usar el :php:class:`Cake\\View\\HelperRegistry` de la vista para hacer esto:: + + // Cualquiera de los dos funciona. + $mediaHelper = $this->loadHelper('Media', $mediaConfig); + $mediaHelper = $this->helpers()->load('Media', $mediaConfig); + +El HelperRegistry es un :doc:`registro ` y es compatible con la API de registro utilizada en otros lugares en CakePHP. + +Métodos de Eventos +================== + +Los helpers tienen varios métodos que se ejecutan con determinados eventos yque te permiten cambiar el proceso de renderización de la vista. Consulta el :ref:`helper-api` y la documentación de :doc:`/core-libraries/events` para obtener más información. + +Creación de Helpers +=================== + +Puedes crear clases de helper personalizadas para su uso en tu aplicación o plugins. Al igual que la mayoría de los componentes de CakePHP, las clases de helper tienen algunas convenciones: + +* Los archivos de clase del helper deben colocarse en **src/View/Helper**. Por ejemplo: + **src/View/Helper/LinkHelper.php** +* Los nombres de las clases de helper deben llevar el sufijo ``Helper``. Por ejemplo: ``LinkHelper``. +* Al hacer referencia a los nombres de los helper, debes omitir el sufijo ``Helper``. Por ejemplo: ``$this->addHelper('Link');`` o ``$this->loadHelper('Link');``. + +También querrás extender ``Helper`` para asegurarte de que todo funcione correctamente:: + + /* src/View/Helper/LinkHelper.php */ + namespace App\View\Helper; + + use Cake\View\Helper; + + class LinkHelper extends Helper + { + public function makeEdit($title, $url) + { + // Lógica para crear un enlace con formato especial va aquí... + } + } + +Inclusión de otros Helpers +-------------------------- + +Es posible que desees utilizar alguna funcionalidad ya existente en otro helper. Para hacerlo, puedes especificar los helpers que deseas utilizar con un array ``$helpers``, formateado de la misma manera que en un controlador:: + + /* src/View/Helper/LinkHelper.php (usando otros helpers) */ + + namespace App\View\Helper; + + use Cake\View\Helper; + + class LinkHelper extends Helper + { + protected $helpers = ['Html']; + + public function makeEdit($title, $url) + { + // Usa el helper HTML para generar + // Datos formateados: + + $link = $this->Html->link($title, $url, ['class' => 'edit']); + + return '
    ' . $link . '
    '; + } + } + +.. _using-helpers: + +Usando tu nuevo Helper +---------------------- + +Una vez que hayas creado tu helper y lo hayas colocado en **src/View/Helper/**, puedes cargarlo en tus vistas:: + + class AppView extends View + { + public function initialize(): void + { + parent::initialize(); + $this->addHelper('Link'); + } + } + +Una vez que se ha cargado tu helper, puedes usarlo en tus vistas accediendo a la propiedad de vista correspondiente:: + + + Link->makeEdit('Cambiar esta Receta', '/recipes/edit/5') ?> + +.. note:: + + El ``HelperRegistry`` intentará cargar de forma tardía cualquier helper que no esté + específicamente identificado en tu ``Controller``. + +Acceso a Variables de Vista dentro de tu Helper +----------------------------------------------- + +Si deseas acceder a una variable de vista dentro de un helper, puedes utilizar ``$this->getView()->get()`` como sigue:: + + class AwesomeHelper extends Helper + { + public $helpers = ['Html']; + + public function someMethod() + { + // establece la meta descripción + return $this->Html->meta( + 'description', $this->getView()->get('metaDescription'), ['block' => 'meta'] + ); + } + } + +Renderizar un Elemento de Vista dentro de tu Helper +---------------------------------------------------- + +Si deseas renderizar un elemento dentro de tu Helper, puedes usar ``$this->getView()->element()`` como sigue:: + + class AwesomeHelper extends Helper + { + public function someFunction() + { + return $this->getView()->element( + '/ruta/a/elemento', + ['foo'=>'bar','bar'=>'foo'] + ); + } + } + +.. _helper-api: + +Clase Helper +============ + +.. php:class:: Helper + +Métodos de Eventos +------------------- + +Implementando un método de evento en un helper, CakePHP suscribirá automáticamente tu helper al evento relevante. A diferencia de las versiones anteriores de CakePHP, *no* debes llamar a ``parent`` en tus métodos, ya que la clase base Helper no implementa ninguno de los métodos de evento. + +.. php:method:: beforeRenderFile(EventInterface $event, $viewFile) + + Se llama antes de renderizar cada archivo de vista. Esto incluye elementos, vistas, vistas principales y diseños (layouts). + +.. php:method:: afterRenderFile(EventInterface $event, $viewFile, $content) + + Se llama después de renderizar cada archivo de vista. Esto incluye elementos, vistas, vistas principales y diseños (layouts). Este evento puede modificar y devolver ``$content`` para cambiar cómo se mostrará el contenido renderizado en el navegador. + +.. php:method:: beforeRender(EventInterface $event, $viewFile) + + El método beforeRender se llama después del método beforeRender del controlador pero antes de que el controlador renderice la vista y el diseño (layout). Recibe el archivo que se está renderizando como argumento. + +.. php:method:: afterRender(EventInterface $event, $viewFile) + + Se llama después de que la vista ha sido renderizada pero antes de que comience el renderizado del diseño (layout). + +.. php:method:: beforeLayout(EventInterface $event, $layoutFile) + + Se llama antes de que comience el renderizado del diseño (layout). Recibe el nombre del archivo del diseño como argumento. + +.. php:method:: afterLayout(EventInterface $event, $layoutFile) + + Se llama después de que se haya completado el renderizado del diseño (layout). Recibe el nombre del archivo del diseño (layout) como argumento. + .. meta:: :title lang=es: Helpers - :keywords lang=es: php class,time function,presentation layer,processing power,ajax,markup,array,functionality,logic,syntax,elements,cakephp,plugins + :keywords lang=en: php class,time function,presentation layer,processing power,ajax,markup,array,functionality,logic,syntax,elements,cakephp,plugins diff --git a/es/views/helpers/rss.rst b/es/views/helpers/rss.rst deleted file mode 100644 index 4ed27df6a9..0000000000 --- a/es/views/helpers/rss.rst +++ /dev/null @@ -1,20 +0,0 @@ -RSS -### - -.. php:namespace:: Cake\View\Helper - -.. php:class:: RssHelper(View $view, array $config = []) - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: RssHelper - :description lang=es: The RSS helper makes generating XML for RSS feeds easy. - :keywords lang=es: rss helper,rss feed,isrss,rss item,channel data,document data,parse extensions,request handler diff --git a/es/views/helpers/session.rst b/es/views/helpers/session.rst deleted file mode 100644 index 189a8333e8..0000000000 --- a/es/views/helpers/session.rst +++ /dev/null @@ -1,20 +0,0 @@ -SessionHelper -############# - -.. php:namespace:: Cake\View\Helper - -.. php:class:: SessionHelper(View $view, array $config = []) - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: SessionHelper - :description lang=es: As a natural counterpart to the Session Component, the Session Helper replicates most of the component's functionality and makes it available in your view. - :keywords lang=es: session helper,flash messages,session flash,session read,session check From bd90117c0a581d6a4d21c660cd37520fc613e0c5 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Fri, 20 Oct 2023 18:18:29 +0200 Subject: [PATCH 070/337] working on breadcrumbs translation --- es/views/helpers/breadcrumbs.rst | 191 +++++++++++++++++++++++++++++-- 1 file changed, 182 insertions(+), 9 deletions(-) diff --git a/es/views/helpers/breadcrumbs.rst b/es/views/helpers/breadcrumbs.rst index 7795586ae5..7021c9b5d1 100644 --- a/es/views/helpers/breadcrumbs.rst +++ b/es/views/helpers/breadcrumbs.rst @@ -5,16 +5,189 @@ Breadcrumbs .. php:class:: BreadcrumbsHelper(View $view, array $config = []) -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +El Helper de Navegación por rastro proporciona una manera sencilla de gestionar la creación y representación de un rastro +de migas de pan para tu aplicación. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +Creando un Rastro de Migas de Pan +==================================== - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +Puedes agregar una miga a la lista utilizando el método "add()". Este método toma tres argumentos: + +- **title** Un texto que se mostrará como el título de la miga. +- **url** Un textto o un arreglo de parámetros que se proporcionarán a la + :doc:`/views/helpers/url` +- **options** Un arreglo de atributos para el ``item`` y ``itemWithoutLink`` + template. Ver la section acerca :ref:`definir atributos para el registro + ` para más información. + +Además de agregar al final del rastro, puedes realizar una variedad de operaciones:: + + // Añade una miga al final. + $this->Breadcrumbs->add( + 'Products', + ['controller' => 'products', 'action' => 'index'] + ); + + // Añade varias migas al final del rastro. + $this->Breadcrumbs->add([ + ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']], + ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]], + ]); + + // Añade una miga al principio. + $this->Breadcrumbs->prepend( + 'Products', + ['controller' => 'products', 'action' => 'index'] + ); + + // Añade múltiple migas al final, en el orden dado + $this->Breadcrumbs->prepend([ + ['title' => 'Products', 'url' => ['controller' => 'products', 'action' => 'index']], + ['title' => 'Product name', 'url' => ['controller' => 'products', 'action' => 'view', 1234]], + ]); + + // Inserta la miga en una posición específica. Si la posición está fuera de los + // límites, se generará una excepción. + $this->Breadcrumbs->insertAt( + 2, + 'Products', + ['controller' => 'products', 'action' => 'index'] + ); + + // Inserta la miga antes de una miga específica, basado en el título. + // Si no se puede encontrar el título de la miga nombrada, + // se generará una excepción. + $this->Breadcrumbs->insertBefore( + 'A product name', // el título de la miga para insertar antes + 'Products', + ['controller' => 'products', 'action' => 'index'] + ); + + // Inserta la miga despues de una miga específica, basado en el título. + // Si no se puede encontrar el título de la miga nombrada, + // se generará una excepción. + $this->Breadcrumbs->insertAfter( + 'A product name', // el título de la miga para insertar despues + 'Products', + ['controller' => 'products', 'action' => 'index'] + ); + + + +El uso de estos métodos te proporciona la capacidad de trabajar con el proceso de representación de dos pasos de CakePHP. +Dado que los ``templates`` y ``layouts`` se representan de adentro hacia afuera (es decir, los elementos incluidos se representan primero), +esto te permite definir con precisión dónde deseas agregar una miga de pan. + + +Renderización del Rastro de Migas de Pan +=========================================== + +Después de agregar migas al rastro, puedes representarlo fácilmente utilizando el método +``render()`` . Este método acepta dos argumentos en forma de arreglos: + +- ``$attributes`` : Un arreglo de atributos que se aplicarán a la plantilla "wrapper". + Esto te permite agregar atributos a la etiqueta HTML. Acepta la clave especial "templateVars" + para permitir la inserción de variables de plantilla personalizadas en el ``template``. +- ``$separator`` : Un arreglo de atributos para el ``separator`` template. + Las propiedades posibles son: + + - ``separator`` El texto que se mostrará como separador. + - ``innerAttrs`` Para proporcionar atributos en caso de que tu separador esté dividido en dos elementos. + - ``templateVars`` Permite la inserción de una variable de plantilla personalizada en el ``template``. + + Todas las demás propiedades se convertirán en atributos HTML y reemplazarán la clave "attrs" en la + plantilla. Si utilizas el valor predeterminado para esta opción ``(empty)``, + no se representará un separador. + +Aquí tienes un ejemplo de cómo representar un rastro:: + + echo $this->Breadcrumbs->render( + ['class' => 'breadcrumbs-trail'], + ['separator' => ''] + ); + +Personalizando el resultado +----------------------------- + +El ``BreadcrumbsHelper`` internamente usa el ``StringTemplateTrait``, lo que proporciona +la capacidad de personalizar fácilmente la salida de varias cadenas HTML. +Incluye cuatro plantillas, con la siguiente declaración predeterminada:: + + [ + 'wrapper' => '{{content}}', + 'item' => '{{title}}{{separator}}', + 'itemWithoutLink' => '{{title}}{{separator}}', + 'separator' => '{{separator}}' + ] + +Puedes personalizarlos fácilmente utilizando el método ``setTemplates()`` de +``StringTemplateTrait``:: + + $this->Breadcrumbs->setTemplates([ + 'wrapper' => '', + ]); + +Dado que tus ``templates`` serán renderizados, la opción ``templateVars`` +te permite agregar tu propio template de variables a los diferentes templates :: + + $this->Breadcrumbs->setTemplates([ + 'item' => '{{icon}}{{title}}{{separator}}' + ]); + +Para definir el parámetro ``{{icon}}``, simplemente especifícala al agregar la miga:: + + $this->Breadcrumbs->add( + 'Products', + ['controller' => 'products', 'action' => 'index'], + [ + 'templateVars' => [ + 'icon' => '', + ], + ] + ); + +.. _defining_attributes_item: + +Definiendo Atributos +-------------------------------- +Si deseas aplicar atributos HTML específicos tanto al elemento como a su subelemento, +puedes aprovechar la clave ``innerAttrs``, que proporciona el argumento ``$options``. +Todo excepto ``innerAttrs`` y ``templateVars`` se representará como atributos HTML.:: + + $this->Breadcrumbs->add( + 'Products', + ['controller' => 'products', 'action' => 'index'], + [ + 'class' => 'products-crumb', + 'data-foo' => 'bar', + 'innerAttrs' => [ + 'class' => 'inner-products-crumb', + 'id' => 'the-products-crumb', + ], + ] + ); + + // Según la plantilla predeterminada, esto representará el siguiente HTML: +
  • + Products +
    • + +Borrando las Migas de Pan +============================ + +Puedes borrar las migas de pan utilizando el método ``reset()``. +Esto puede ser útil cuando deseas transformar las migas y sobrescribir la lista:: + + $crumbs = $this->Breadcrumbs->getCrumbs(); + $crumbs = collection($crumbs)->map(function ($crumb) { + $crumb['options']['class'] = 'breadcrumb-item'; + return $crumb; + })->toArray(); + + $this->Breadcrumbs->reset()->add($crumbs); .. meta:: - :title lang=es: BreadcrumbsHelper - :description lang=es: The role of the BreadcrumbsHelper in CakePHP is provide a way to easily manage breadcrumbs. - :keywords lang=es: breadcrumbs helper,cakephp crumbs + :title lang=en: BreadcrumbsHelper + :description lang=en: The role of the BreadcrumbsHelper in CakePHP is provide a way to easily manage breadcrumbs. + :keywords lang=en: breadcrumbs helper,cakephp crumbs + From c2a3b688cfb33e533cd80e416dd4697c3cdaae27 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Sat, 21 Oct 2023 08:09:48 +0200 Subject: [PATCH 071/337] [es] Traslating flash.rst according to current version --- es/views/helpers/flash.rst | 66 +++++++++++++++++++++++++++++++++++--- 1 file changed, 61 insertions(+), 5 deletions(-) diff --git a/es/views/helpers/flash.rst b/es/views/helpers/flash.rst index 38b3de5e02..890079d981 100644 --- a/es/views/helpers/flash.rst +++ b/es/views/helpers/flash.rst @@ -5,11 +5,67 @@ FlashHelper .. php:class:: FlashHelper(View $view, array $config = []) +FlashHelper proporciona una forma de representar mensajes flash que se establecieron en +``$_SESSION`` a través de :doc:`FlashComponent     `. Tanto +:doc:`FlashComponent ` como FlashHelper +utilizan principalmente ``elements`` para renderizar mensajes flash. Flash elements se pueden encontrar en +el directorio **templates/element/flash**. Puedes notar CakePHP's App +template viene con tres elementos flash: **success.php**, **default.php**, and +**error.php**. + +Renderizando Mnesajes Flash +============================= + +Para renderizar un mensaje flash, puedes simplemente utilizar el método FlashHelper's ``render()`` +en tu template default ``templates/layout/default.php``:: + + Flash->render() ?> + +Por defecto, CakePHP utiliza un "flash" key para los mensajes flash messages en la sesión. Sin embargo, si +si has especificado un "key" al establecer el mensaje flash en +:doc:`FlashComponent `, puedes especificar cual "key" de flash renderizar:: + + Flash->render('other') ?> + +También puedes sobreescribir cualquiera de las opciones establecidas en FlashComponent:: + + // En el Controller + $this->Flash->set('The user has been saved.', [ + 'element' => 'success' + ]); + + // En el template: Utilizará great_success.php en vez de success.php + Flash->render('flash', [ + 'element' => 'great_success' + ]); + + // En el template: el elemento flashy del plugin "Company" + Flash->render('flash', [ + 'element' => 'Company.flashy' + ]); + .. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + Cuando construyas algun template personalizado para mensajes flash, asegúrate de + codificar (encode) correctamente en HTML cualquier dato del usuario. + CakePHP no escapará (escape) los parámetros de los mensajes flash por ti. + + +Para obtener más información sobre las opciones disponibles en el arreglo, consulta la sección +:doc:`FlashComponent ` + +Routing Prefix y Mensajes Flash +================================= + +If you have a Routing prefix configured, ahora puedes tener tus elementos Flash almacenados en +**templates/{Prefix}/element/flash**. De esta manera, puedes tener +mensajes específicos para cada parte de tu aplicación. Por ejemplo, puedes utilizar +diferentes "layoouts" para la sección de frontend y la sección de administración. + + +Mensajes Flash y Tema +========================= - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +El The FlashHelper utiliza ``elements`` normales para renderizar los mensajes y, por lo tanto, +respetará cualquier Tema que hayas especificado. Entonces, cuando tu Tema tiene un archivo +templates/element/flash/error.php, se utilizará, al igual que con cualquier otro ``Elements`` y ``Views``. From 7627a349be89c12f7a7513f70346f476c9612192 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Sat, 21 Oct 2023 08:21:02 +0200 Subject: [PATCH 072/337] [es] Traslating number.rst according to current version, meta data improvements --- es/views/helpers/breadcrumbs.rst | 6 +++--- es/views/helpers/number.rst | 26 ++++++++++++++++++-------- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/es/views/helpers/breadcrumbs.rst b/es/views/helpers/breadcrumbs.rst index 7021c9b5d1..e35e3eff81 100644 --- a/es/views/helpers/breadcrumbs.rst +++ b/es/views/helpers/breadcrumbs.rst @@ -187,7 +187,7 @@ Esto puede ser útil cuando deseas transformar las migas y sobrescribir la lista $this->Breadcrumbs->reset()->add($crumbs); .. meta:: - :title lang=en: BreadcrumbsHelper - :description lang=en: The role of the BreadcrumbsHelper in CakePHP is provide a way to easily manage breadcrumbs. - :keywords lang=en: breadcrumbs helper,cakephp crumbs + :title lang=es: BreadcrumbsHelper + :description lang=es: El papel del BreadcrumbsHelper en CakePHP es proporcionar una forma sencilla de gestionar las migas de pan. + :keywords lang=en: breadcrumbs helper,cakephp migas de pan, migas diff --git a/es/views/helpers/number.rst b/es/views/helpers/number.rst index b35eb70ae7..9c1ed033a6 100644 --- a/es/views/helpers/number.rst +++ b/es/views/helpers/number.rst @@ -5,16 +5,26 @@ NumberHelper .. php:class:: NumberHelper(View $view, array $config = []) -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +The NumberHelper contains convenient methods that enable display +numbers in common formats in your views. These methods include ways +to format currency, percentages, data sizes, format numbers to +specific precisions and also to give you more flexibility with +formatting numbers. - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. +El NumberHelper contiene métodos convenientes que permiten mostrar números +en formatos comunes en tus vistas. Estos métodos incluyen formas de formatear moneda, +porcentajes, tamaños de datos, formatear números con precisiones específicas y también +ofrecen mayor flexibilidad en la formateo de números. - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. +.. include:: /core-libraries/number.rst + :start-after: start-cakenumber + :end-before: end-cakenumber + +.. warning:: + + Todos los símbolos son UTF-8. .. meta:: :title lang=es: NumberHelper - :description lang=es: The Number Helper contains convenience methods that enable display numbers in common formats in your views. - :keywords lang=es: number helper,currency,number format,number precision,format file size,format numbers + :description lang=es: El NumberHelper contiene métodos convenientes que permiten mostrar números en formatos comunes en tus vistas. + :keywords lang=es: number helper, moneda, currency, number format,number precision, formato de número, precisión de número, format file size,format numbers, formatear el tamaño del archivo, formatear números From f82d8b6ae5d28187b464a3210e433f4af4913492 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Tue, 24 Oct 2023 18:04:56 +0200 Subject: [PATCH 073/337] [es] WIP logging translation --- es/core-libraries/logging.rst | 99 ++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 48 deletions(-) diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index e645f7ccee..5670cf5caa 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -1,36 +1,40 @@ Logging ####### -While CakePHP core Configure Class settings can really help you see -what's happening under the hood, there are certain times that -you'll need to log data to the disk in order to find out what's -going on. With technologies like SOAP, AJAX, and REST APIs, debugging can be -rather difficult. +Si bien la configuración de la clase Configure de CakePHP puede ayudarte a ver +lo que está sucediendo en el sistema, hay momentos en los que necesitarás registrar +datos en el disco para averiguar lo que está ocurriendo. Con tecnologías como SOAP, AJAX y APIs REST, +la depuración puede ser bastante difícil. -Logging can also be a way to find out what's been going on in your -application over time. What search terms are being used? What sorts -of errors are my users being shown? How often is a particular query -being executed? +Logging también puede ser una forma de averiguar lo que ha estado ocurriendo +en tu aplicación con el tiempo. ¿Qué términos de búsqueda se están utilizando? +¿Qué tipos de errores están viendo mis usuarios? ¿Con qué frecuencia se ejecuta +una consulta en particular? Logging data in CakePHP is done with the ``log()`` function. It is provided by the ``LogTrait``, which is the common ancestor for many CakePHP classes. If the context is a CakePHP class (Controller, Component, View,...), you can log your data. You can also use ``Log::write()`` directly. See :ref:`writing-to-logs`. +El registro de datos en CakePHP se realiza con la función "log()". Esta función es proporcionada por el +"LogTrait", que es el ancestro común de muchas clases de CakePHP. Si el contexto es una clase de CakePHP +(Controlador, Componente, Vista, etc.), puedes registrar tus datos. También puedes usar "Log::write()" +directamente. Consulta la sección :ref:`writing-to-logs` para obtener más información. + .. _log-configuration: Logging Configuration ===================== -Configuring ``Log`` should be done during your application's bootstrap phase. -The **config/app.php** file is intended for just this. You can define -as many or as few loggers as your application needs. Loggers should be -configured using :php:class:`Cake\\Log\\Log`. An example would be:: +La configuración de "Log" debe realizarse durante la fase de arranque de tu aplicación. +El archivo **config/app.php** está diseñado precisamente para esto. Puedes definir tantos +``loggers`` como necesite tu aplicación. Los ``loggers`` deben configurarse utilizando la clase +:php:class:`Cake\\Log\\Log`. Un ejemplo sería:: use Cake\Log\Engine\FileLog; use Cake\Log\Log; - // Classname using logger 'class' constant + // Nombre de la clase utilizando la constante 'class' del logger. Log::setConfig('info', [ 'className' => FileLog::class, 'path' => LOGS, @@ -38,7 +42,7 @@ configured using :php:class:`Cake\\Log\\Log`. An example would be:: 'file' => 'info', ]); - // Short classname + // Nombre de clase corto Log::setConfig('debug', [ 'className' => 'File', 'path' => LOGS, @@ -54,64 +58,63 @@ configured using :php:class:`Cake\\Log\\Log`. An example would be:: 'file' => 'error', ]); -The above creates three loggers, named ``info``, ``debug`` and ``error``. -Each is configured to handle different levels of messages. They also store their -log messages in separate files, so we can separate debug/notice/info logs -from more serious errors. See the section on :ref:`logging-levels` for more -information on the different levels and what they mean. +Lo anterior crea tres loggers, llamados ``info``, ``debug`` and ``error``. +Cada uno está configurado para manejar diferentes niveles de mensajes. +También almacenan sus mensajes de registro en archivos separados, de esta manera, +podemos separar los registros de depuración/aviso/información de los errores más graves. +Consulta la sección sobr :ref:`logging-levels` para obtener más información sobre +los diferentes niveles y lo que significan. -Once a configuration is created you cannot change it. Instead you should drop -the configuration and re-create it using :php:meth:`Cake\\Log\\Log::drop()` and +Una vez que se crea una configuración, no se puede cambiar. En su lugar, debes eliminar +la configuración y volver a crearla utilizando :php:meth:`Cake\\Log\\Log::drop()` y :php:meth:`Cake\\Log\\Log::setConfig()`. -It is also possible to create loggers by providing a closure. This is useful -when you need full control over how the logger object is built. The closure -has to return the constructed logger instance. For example:: +ambién es posible crear loggers proporcionando un cierre (closure). Esto es útil +cuando necesitas un control completo sobre cómo se construye el objeto del logger. El cierre +debe devolver la instancia del logger. Por ejemplo:: Log::setConfig('special', function () { return new \Cake\Log\Engine\FileLog(['path' => LOGS, 'file' => 'log']); }); -Configuration options can also be provided as a :term:`DSN` string. This is -useful when working with environment variables or :term:`PaaS` providers:: + +Las opciones de configuración también se pueden proporcionar como una cadena :term:`DSN`. Esto es +útil cuando se trabaja con variables de entorno o proveedores :term:`PaaS`:: Log::setConfig('error', [ 'url' => 'file:///full/path/to/logs/?levels[]=warning&levels[]=error&file=error', ]); .. warning:: - If you do not configure logging engines, log messages will not be stored. + Si no configuras motores de registro (logging), los mensajes de log no se almacenarán. -Error and Exception Logging -=========================== +Registro de Errores y Excepciones +================================= -Errors and Exceptions can also be logged. By configuring the corresponding -values in your **config/app.php** file. Errors will be displayed when debug is -``true`` and logged when debug is ``false``. To log uncaught exceptions, set the -``log`` option to ``true``. See :doc:`/development/configuration` for more -information. +Los errores y excepciones también pueden registrarse configurando los valores correspondientes en tu archivo **config/app.php**. +Los errores se mostrarán cuando el modo de depuración esté en ``true`` y se registrarán en los archivos de log cuando el modo de depuración esté en ``false``. +Para registrar excepciones no capturadas, configura la opción ``log`` como ``true``. +Consulta ::doc:`/development/configuration` para obtener más información. .. _writing-to-logs: -Writing to Logs -=============== +Escribiendo en los archivos de Log +=================================== -Writing to the log files can be done in two different ways. The first -is to use the static :php:meth:`Cake\\Log\\Log::write()` method:: +Escribir en los archivos de registro se puede hacer de dos maneras diferentes. La primera es +utilizando el método estático ::php:meth:`Cake\\Log\\Log::write()`:: Log::write('debug', 'Something did not work'); -The second is to use the ``log()`` shortcut function available on any -class using the ``LogTrait``. Calling ``log()`` will internally call -``Log::write()``:: +La segunda opción es utilizar la función de acceso directo ``log()`` disponible en cualquier clase +que utilice el ``LogTrait``. Llamar a``log()`` llamará internamente a``Log::write()``:: - // Executing this inside a class using LogTrait + // Ejecutando esto dentro de una clase que utiliza LogTrait $this->log('Something did not work!', 'debug'); -All configured log streams are written to sequentially each time -:php:meth:`Cake\\Log\\Log::write()` is called. If you have not configured any -logging engines ``log()`` will return ``false`` and no log messages will be -written. +Todos los log configurados se escriben secuencialmente cada vez que se llama a +:php:meth:`Cake\\Log\\Log::write()`. Si no has configurado ningún motor de registro, +``log()`` devolverá "false" y no se escribirán mensajes de registro. Using Placeholders in Messages ------------------------------ @@ -495,6 +498,6 @@ Use similar methods if you want to configure a different logger for your console your application logger. This will prevent duplicate log entries. .. meta:: - :title lang=es: Registro (Logging) + :title lang=en: Logging :description lang=en: Log CakePHP data to the disk to help debug your application over longer periods of time. :keywords lang=en: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs From 26a2201efc889724646670146282be7b321394c0 Mon Sep 17 00:00:00 2001 From: Alejandro Ibarra Date: Wed, 25 Oct 2023 05:23:05 +0200 Subject: [PATCH 074/337] Fix Number --- es/core-libraries/number.rst | 356 +++++++++++++++++++++++++++++++++-- es/views/helpers/number.rst | 14 +- 2 files changed, 349 insertions(+), 21 deletions(-) diff --git a/es/core-libraries/number.rst b/es/core-libraries/number.rst index e28d122311..bffb7261d3 100644 --- a/es/core-libraries/number.rst +++ b/es/core-libraries/number.rst @@ -1,20 +1,354 @@ -Number -###### +Clase Number +############ .. php:namespace:: Cake\I18n .. php:class:: Number -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. +Si necesitas las funcionalidades de :php:class:`NumberHelper` fuera de una vista, utiliza la clase ``Number``:: - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + namespace App\Controller; + + use Cake\I18n\Number; + + class UsersController extends AppController + { + public function initialize(): void + { + parent::initialize(); + $this->loadComponent('Authentication.Authentication'); + } + + public function afterLogin() + { + $identity = $this->Authentication->getIdentity(); + $storageUsed = $identity->storage_used; + if ($storageUsed > 5000000) { + // Notificar a los usuarios de su cuota + $this->Flash->success(__('Estás usando {0} de almacenamiento', Number::toReadableSize($storageUsed))); + } + } + } + +.. start-cakenumber + +Todas estas funciones devuelven el número formateado; no imprimen automáticamente la salida en la vista. + +Formato de Valores Monetarios +============================= + +.. php:method:: currency(mixed $value, string $currency = null, array $options = []) + +Este método se utiliza para mostrar un número en formatos de moneda comunes (EUR, GBP, USD), basándose en el código de moneda de tres letras ISO 4217. Su uso en una vista se ve así:: + + // Llamado como NumberHelper + echo $this->Number->currency($value, $currency); + + // Llamado como Number + echo Number::currency($value, $currency); + +El primer parámetro, ``$value``, debería ser un número de punto flotante que representa la cantidad de dinero que estás expresando. El segundo parámetro es una cadena utilizada para elegir un esquema de formato de moneda predefinido: + ++---------------------+----------------------------------------------------+ +| $currency | 1234,56, formateado por tipo de moneda | ++=====================+====================================================+ +| EUR | €1.234,56 | ++---------------------+----------------------------------------------------+ +| GBP | £1.234,56 | ++---------------------+----------------------------------------------------+ +| USD | $1.234,56 | ++---------------------+----------------------------------------------------+ + +El tercer parámetro es un arreglo de opciones para definir aún más la salida. Las siguientes opciones están disponibles: + ++---------------------+----------------------------------------------------+ +| Opción | Descripción | ++=====================+====================================================+ +| before | Texto para mostrar antes del número formateado. | ++---------------------+----------------------------------------------------+ +| after | Texto para mostrar después del número formateado. | ++---------------------+----------------------------------------------------+ +| zero | El texto a usar para los valores cero; puede ser | +| | una cadena o un número, por ejemplo, 0, '¡Gratis!'.| ++---------------------+----------------------------------------------------+ +| places | Número de lugares decimales a usar, por ejemplo, 2 | ++---------------------+----------------------------------------------------+ +| precision | Número máximo de lugares decimales a usar, | +| | por ejemplo, 2. | ++---------------------+----------------------------------------------------+ +| locale | El nombre de la localidad a usar para formatear | +| | el número, por ejemplo, "es_ES". | ++---------------------+----------------------------------------------------+ +| fractionSymbol | Cadena a usar para números fraccionarios, por | +| | ejemplo, 'centavos'. | ++---------------------+----------------------------------------------------+ +| fractionPosition | Ya sea 'antes' o 'después' para colocar el símbolo | +| | fraccionario. | ++---------------------+----------------------------------------------------+ +| pattern | Un patrón de número ICU para usar para formatear el| +| | número, por ejemplo, #,###.00. | ++---------------------+----------------------------------------------------+ +| useIntlCode | Establecer en ``true`` para reemplazar el símbolo | +| | de moneda con el código de moneda internacional. | ++---------------------+----------------------------------------------------+ + +Si el valor de ``$currency`` es ``null``, la moneda predeterminada se recuperará de +:php:meth:`Cake\\I18n\\Number::defaultCurrency()`. Para formatear monedas en un +formato de contabilidad, debes establecer el formato de la moneda:: + + Number::setDefaultCurrencyFormat(Number::FORMAT_CURRENCY_ACCOUNTING); + +Configurar la Moneda Predeterminada +=================================== + +.. php:method:: setDefaultCurrency($currency) + +Configura la moneda predeterminada. Esto evita la necesidad de pasar siempre la +moneda a :php:meth:`Cake\\I18n\\Number::currency()` y cambiar todas las +salidas de moneda configurando otro valor predeterminado. Si ``$currency`` se establece en ``null``, +se eliminará el valor almacenado actualmente. + +Obtener la Moneda Predeterminada +================================ + +.. php:method:: getDefaultCurrency() + +Obtén la moneda predeterminada. Si la moneda predeterminada se configuró anteriormente utilizando +``setDefaultCurrency()``, se devolverá ese valor. De forma predeterminada, recuperará el valor de la ini de ``intl.default_locale`` si está configurado y ``'en_US'`` si no lo está. + +Formato de Números de Punto Flotante +==================================== + +.. php:method:: precision(float $value, int $precision = 3, array $options = []) + +Este método muestra un número con la cantidad especificada de precisión (lugares decimales). Se redondeará para mantener el +nivel de precisión definido. :: + + // Llamado como NumberHelper + echo $this->Number->precision(456.91873645, 2); + + // Salida + 456.92 + + // Llamado como Number + echo Number::precision(456.91873645, 2); + +Formato de Porcentajes +====================== + +.. php:method:: toPercentage(mixed $value, int $precision = 2, array $options = []) + ++---------------------+----------------------------------------------------+ +| Opción | Descripción | ++=====================+====================================================+ +| multiply | Booleano para indicar si el valor debe ser | +| | multiplicado por 100. Útil para porcentajes | +| | decimales. | ++---------------------+----------------------------------------------------+ + +Al igual que :php:meth:`Cake\\I18n\\Number::precision()`, este método formatea un número +según la precisión proporcionada (donde los números se redondean para cumplir con la +precisión dada). Este método también expresa el número como un porcentaje +y agrega la salida con un signo de porcentaje. :: + + // Llamado como NumberHelper. Salida: 45.69% + echo $this->Number->toPercentage(45.691873645); + + // Llamado como Number. Salida: 45.69% + echo Number::toPercentage(45.691873645); + + // Llamado con multiplicar. Salida: 45.7% + echo Number::toPercentage(0.45691, 1, [ + 'multiply' => true + ]); + +Interactuar con Valores Legibles para Humanos +============================================= + +.. php:method:: toReadableSize(string $size) + +Este método formatea tamaños de datos en formas legibles para humanos. Proporciona +una forma abreviada de convertir bytes a KB, MB, GB y TB. El tamaño se +muestra con un nivel de precisión de dos dígitos, de acuerdo con el tamaño +de los datos suministrados (es decir, los tamaños más altos se expresan en términos más grandes):: + + // Llamado como NumberHelper + echo $this->Number->toReadableSize(0); // 0 Byte + echo $this->Number->toReadableSize(1024); // 1 KB + echo $this->Number->toReadableSize(1321205.76); // 1.26 MB + echo $this->Number->toReadableSize(5368709120); // 5 GB + + // Llamado como Number + echo Number::toReadableSize(0); // 0 Byte + echo Number::toReadableSize(1024); // 1 KB + echo Number::toReadableSize(1321205.76); // 1.26 MB + echo Number::toReadableSize(5368709120); // 5 GB + +Formato de Números +================== + +.. php:method:: format(mixed $value, array $options = []) + +Este método te brinda mucho más control sobre el formato de +números para usar en tus vistas (y se utiliza como el método principal por +la mayoría de los otros métodos de NumberHelper). Usar este método puede +verse así:: + + // Llamado como NumberHelper + $this->Number->format($value, $options); + + // Llamado como Number + Number::format($value, $options); + +El parámetro ``$value`` es el número que estás planeando +formatear para la salida. Sin opciones proporcionadas, el número +1236.334 se mostraría como 1,236. Ten en cuenta que la precisión predeterminada es +cero decimales. + +El parámetro ``$options`` es donde reside la verdadera magia para este método. + +- Si pasas un entero, este se convierte en la cantidad de precisión + o lugares para la función. +- Si pasas un arreglo asociado, puedes usar las siguientes claves: + ++---------------------+----------------------------------------------------+ +| Opción | Descripción | ++=====================+====================================================+ +| places | Número de lugares decimales a usar, por ejemplo, 2 | ++---------------------+----------------------------------------------------+ +| precision | Número máximo de lugares decimales a usar, por | +| | ejemplo, 2. | ++---------------------+----------------------------------------------------+ +| pattern | Un patrón de número ICU para usar para formatear el| +| | número, por ejemplo, #,###.00. | ++---------------------+----------------------------------------------------+ +| locale | El nombre de la localidad a usar para formatear el | +| | número, por ejemplo, "es_ES". | ++---------------------+----------------------------------------------------+ +| before | Texto para mostrar antes del número formateado. | ++---------------------+----------------------------------------------------+ +| after | Texto para mostrar después del número formateado. | ++---------------------+----------------------------------------------------+ + +Ejemplo:: + + // Llamado como NumberHelper + echo $this->Number->format('123456.7890', [ + 'places' => 2, + 'before' => '¥ ', + 'after' => ' !' + ]); + // Salida '¥ 123,456.79 !' + + echo $this->Number->format('123456.7890', [ + 'locale' => 'fr_FR' + ]); + // Salida '123 456,79 !' + + // Llamado como Number + echo Number::format('123456.7890', [ + 'places' => 2, + 'before' => '¥ ', + 'after' => ' !' + ]); + // Salida '¥ 123,456.79 !' + + echo Number::format('123456.7890', [ + 'locale' => 'fr_FR' + ]); + // Salida '123 456,79 !' + +.. php:method:: ordinal(mixed $value, array $options = []) + +Este método mostrará un número ordinal. + +Ejemplos:: + + echo Number::ordinal(1); + // Salida '1st' + + echo Number::ordinal(2); + // Salida '2nd' + + echo Number::ordinal(2, [ + 'locale' => 'fr_FR' + ]); + // Salida '2e' + + echo Number::ordinal(410); + // Salida '410th' + +Diferencias en el Formato +========================= + +.. php:method:: formatDelta(mixed $value, array $options = []) + +Este método muestra diferencias en el valor como un número con signo:: + + // Llamado como NumberHelper + $this->Number->formatDelta($value, $options); + + // Llamado como Number + Number::formatDelta($value, $options); + +El parámetro ``$value`` es el número que estás planeando +formatear para la salida. Sin opciones proporcionadas, el número +1236.334 se mostraría como 1,236. Ten en cuenta que la precisión predeterminada es +cero decimales. + +El parámetro ``$options`` toma las mismas claves que :php:meth:`Number::format()` en sí: + ++---------------------+----------------------------------------------------+ +| Opción | Descripción | ++=====================+====================================================+ +| places | Número de lugares decimales a usar, por ejemplo, 2 | ++---------------------+----------------------------------------------------+ +| precision | Número máximo de lugares decimales a usar, por | +| | ejemplo, 2. | ++---------------------+----------------------------------------------------+ +| locale | El nombre de la localidad a usar para formatear el | +| | número, por ejemplo, "es_ES". | ++---------------------+----------------------------------------------------+ +| before | Texto para mostrar antes del número formateado. | ++---------------------+----------------------------------------------------+ +| after | Texto para mostrar después del número formateado. | ++---------------------+----------------------------------------------------+ + +Ejemplo:: + + // Llamado como NumberHelper + echo $this->Number->formatDelta('123456.7890', [ + 'places' => 2, + 'before' => '[', + 'after' => ']' + ]); + // Salida '[+123,456.79]' + + // Llamado como Number + echo Number::formatDelta('123456.7890', [ + 'places' => 2, + 'before' => '[', + 'after' => ']' + ]); + // Salida '[+123,456.79]' + +.. end-cakenumber + +Configurar Formateadores +======================== + +.. php:method:: config(string $locale, int $type = NumberFormatter::DECIMAL, array $options = []) + +Este método te permite configurar valores predeterminados del formateador que persisten en llamadas +a varios métodos. + +Ejemplo:: + + Number::config('es_ES', \NumberFormatter::CURRENCY, [ + 'pattern' => '#,##,##0' + ]); - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. .. meta:: - :title lang=es: NumberHelper - :description lang=es: The Number Helper contains convenience methods that enable display numbers in common formats in your views. - :keywords lang=es: number helper,currency,number format,number precision,format file size,format numbers + :title lang=es: Clase Number + :keywords lang=es: number,currency,number format,number precision,format file size,format numbers diff --git a/es/views/helpers/number.rst b/es/views/helpers/number.rst index 9c1ed033a6..1071e9dd3e 100644 --- a/es/views/helpers/number.rst +++ b/es/views/helpers/number.rst @@ -1,20 +1,14 @@ -NumberHelper -############ +Helper Number +############# .. php:namespace:: Cake\View\Helper .. php:class:: NumberHelper(View $view, array $config = []) -The NumberHelper contains convenient methods that enable display -numbers in common formats in your views. These methods include ways -to format currency, percentages, data sizes, format numbers to -specific precisions and also to give you more flexibility with -formatting numbers. - El NumberHelper contiene métodos convenientes que permiten mostrar números en formatos comunes en tus vistas. Estos métodos incluyen formas de formatear moneda, -porcentajes, tamaños de datos, formatear números con precisiones específicas y también -ofrecen mayor flexibilidad en la formateo de números. +porcentajes, tamaños de datos, precisiones específicas y también +ofrecen mayor flexibilidad en el formato de números. .. include:: /core-libraries/number.rst :start-after: start-cakenumber From 77d8c621cf63fd5ec87244085e6377440c81dde7 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Wed, 25 Oct 2023 17:32:14 +0200 Subject: [PATCH 075/337] [es] WIP logging translation --- es/core-libraries/logging.rst | 95 ++++++++++++++++++----------------- 1 file changed, 48 insertions(+), 47 deletions(-) diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index 5670cf5caa..66081f5d77 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -112,28 +112,30 @@ que utilice el ``LogTrait``. Llamar a``log()`` llamará internamente a``Log::wri // Ejecutando esto dentro de una clase que utiliza LogTrait $this->log('Something did not work!', 'debug'); -Todos los log configurados se escriben secuencialmente cada vez que se llama a +Todos los ``log`` configurados se escriben secuencialmente cada vez que se llama a :php:meth:`Cake\\Log\\Log::write()`. Si no has configurado ningún motor de registro, ``log()`` devolverá "false" y no se escribirán mensajes de registro. -Using Placeholders in Messages ------------------------------- +Usando marcadores de posición (placeholders) en mensajes +----------------------------------------------- -If you need to log dynamically defined data, you can use placeholders in your -log messages and provide an array of key/value pairs in the ``$context`` -parameter:: +Si necesitas registrar datos definidos dinámicamente, puedes utilizar marcadores de posición en tus +mensajes de registro y proporcionar un array de pares clave/valor en el parámetro ``$context`` +como sigue:: - // Will log `Could not process for userid=1` - Log::write('error', 'Could not process for userid={user}', ['user' => $user->id]); -Placeholders that do not have keys defined will not be replaced. If you need to -use a literal braced word, you must escape the placeholder:: + // Se registrará `No se pudo procesar para el usuario id = 1` + Log::write('error', 'No se pudo procesar para el usuario id ={user}', ['user' => $user->id]); - // Will log `No {replace}` +Los marcadores (placeholders) que no tienen claves definidas no serán reemplazados. +Si necesitas utilizar una palabra entre llaves de forma literal, debes escapar el marcador:: + + + // Se registrará `No {replace}` Log::write('error', 'No \\{replace}', ['replace' => 'no']); -If you include objects in your logging placeholders those objects must implement -one of the following methods: +Si incluyes objetos en los marcadores, esos objetos deben implementar +uno de los siguientes métodos: * ``__toString()`` * ``toArray()`` @@ -141,49 +143,48 @@ one of the following methods: .. _logging-levels: -Using Levels ------------- +Usando Niveles +--------------- -CakePHP supports the standard POSIX set of logging levels. Each level represents -an increasing level of severity: +CakePHP admite el conjunto estándar de niveles de registro POSIX. Cada nivel representa un aumento +en el nivel de gravedad: -* Emergency: system is unusable -* Alert: action must be taken immediately -* Critical: critical conditions -* Error: error conditions -* Warning: warning conditions -* Notice: normal but significant condition -* Info: informational messages -* Debug: debug-level messages +* Emergency: el sistema no es utilizable +* Alert: se debe tomar una acción inmediata +* Critical: condiciones críticas +* Error: condiciones de error +* Warning: condiciones de advertencia +* Notice: condiciones normales pero significativas +* Info: mensajes informativos +* Debug: mensajes de depuración -You can refer to these levels by name when configuring loggers, and when writing -log messages. Alternatively, you can use convenience methods like -:php:meth:`Cake\\Log\\Log::error()` to clearly indicate the logging -level. Using a level that is not in the above levels will result in an -exception. +Puedes hacer referencia a estos niveles por nombre al configurar lo ``loggers`` y al escribir +mensajes de registro. Alternativamente, puedes utilizar métodos de conveniencia como : +:php:meth:`Cake\\Log\\Log::error()` para indicar claramente el nivel de registro. +Utilizar un nivel que no esté en la lista de niveles anteriores resultará en una excepción. .. note:: - When ``levels`` is set to an empty value in a logger's configuration, it - will take messages of any level. + Cuando ``levels`` se establece en un valor vacío en la configuración de un ``logger``, + aceptará mensajes de cualquier nivel. .. _logging-scopes: -Logging Scopes --------------- +Ámbitos de Registro (scope) +---------------------------- -Often times you'll want to configure different logging behavior for different -subsystems or parts of your application. Take for example an e-commerce shop. -You'll probably want to handle logging for orders and payments differently than -you do other less critical logs. +En muchas ocasiones, querrás configurar diferentes comportamientos de registro para diferentes +subsistemas o partes de tu aplicación. Tomemos como ejemplo una tienda en línea. +Probablemente quieras manejar el registro de pedidos y pagos de manera diferente a como lo haces +con otros registros menos críticos. -CakePHP exposes this concept as logging scopes. When log messages are written -you can include a scope name. If there is a configured logger for that scope, -the log messages will be directed to those loggers. For example:: +CakePHP expone este concepto como ámbitos de registro. Cuando se escriben mensajes de registro, +puedes incluir un nombre de ámbito ``scope``. Si hay un registrador configurado para ese ámbito, +los mensajes de registro se dirigirán a esos ``loggers``. Por ejemplo:: use Cake\Log\Engine\FileLog; - // Configure logs/shops.log to receive all levels, but only - // those with `orders` and `payments` scope. + // Configura logs/shops.log para recibir todos los niveles, pero solo aquellos con ``scope`` + // `orders` y `payments`. Log::setConfig('shops', [ 'className' => FileLog::class, 'path' => LOGS, @@ -192,8 +193,8 @@ the log messages will be directed to those loggers. For example:: 'file' => 'shops.log', ]); - // Configure logs/payments.log to receive all levels, but only - // those with `payments` scope. + // Configura logs/payments.log para recibir todos los niveles, pero solo aquellos con ``scope`` + // `payments`. Log::setConfig('payments', [ 'className' => FileLog::class, 'path' => LOGS, @@ -205,8 +206,8 @@ the log messages will be directed to those loggers. For example:: Log::warning('this gets written only to shops.log', ['scope' => ['orders']]); Log::warning('this gets written to both shops.log and payments.log', ['scope' => ['payments']]); -Scopes can also be passed as a single string or a numerically indexed array. -Note that using this form will limit the ability to pass more data as context:: +Los ``scopes`` también se pueden pasar como una cadena única o como una matriz indexada numéricamente. +Ten en cuenta que al usar esta forma, se limitará la capacidad de pasar más datos como contexto:: Log::warning('This is a warning', ['orders']); Log::warning('This is a warning', 'payments'); From 07020d08f6fd9304af1612d10bfadaa6c1d5a81a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Gonz=C3=A1lez?= Date: Mon, 23 Oct 2023 08:36:04 +0100 Subject: [PATCH 076/337] update installation page --- .../cms/installation.rst | 41 ++++++++++--------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/es/tutorials-and-examples/cms/installation.rst b/es/tutorials-and-examples/cms/installation.rst index e26705bc33..6df766aa26 100644 --- a/es/tutorials-and-examples/cms/installation.rst +++ b/es/tutorials-and-examples/cms/installation.rst @@ -46,7 +46,7 @@ en la carpeta **cms** del directorio de trabajo actual: .. code-block:: console - php composer.phar create-project --prefer-dist cakephp/app:4.* cms + php composer.phar create-project --prefer-dist cakephp/app:5.* cms Si ha descargado y ejecutado el `Instalador de Composer de Windows `_, entonces, escriba la siguiente línea en el @@ -55,7 +55,7 @@ C:\\wamp\\www\\dev): .. code-block:: console - composer self-update && composer create-project --prefer-dist cakephp/app:4.* cms + composer self-update && composer create-project --prefer-dist cakephp/app:5.* cms La ventaja de usar Composer es que completará automáticamente algunas tareas de configuración importantes, como establecer los permisos de archivo correctos y @@ -67,24 +67,25 @@ Composer, consulte la sección :doc:`/installation`. Independientemente de cómo haya descargado e instalado CakePHP, una vez que la configuración es completada, la disposición de su directorio debería ser similar a la siguiente:: - /cms - /bin - /config - /logs - /plugins - /src - /tests - /tmp - /vendor - /webroot - .editorconfig - .gitignore - .htaccess - .travis.yml - .composer.json - index.php - phpunit.xml.dist - README.md + cms/ + bin/ + config/ + logs/ + plugins/ + resources/ + src/ + templates/ + tests/ + tmp/ + vendor/ + webroot/ + .editorconfig + .gitignore + .htaccess + composer.json + index.php + phpunit.xml.dist + README.md Ahora podría ser un buen momento para aprender un poco sobre cómo funciona la estructura de directorios de CakePHP: consulte la sección :doc:`/intro/cakephp-folder-structure`. From a514288c3b2ed9146cbd6119236687d07b8902f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Gonz=C3=A1lez?= Date: Mon, 23 Oct 2023 09:03:52 +0100 Subject: [PATCH 077/337] update database.rst content of default files and remove * entity accessible --- en/tutorials-and-examples/cms/database.rst | 32 ++++++++++---------- es/tutorials-and-examples/cms/database.rst | 35 +++++++++++----------- 2 files changed, 32 insertions(+), 35 deletions(-) diff --git a/en/tutorials-and-examples/cms/database.rst b/en/tutorials-and-examples/cms/database.rst index e97c7fd7a9..da063be179 100644 --- a/en/tutorials-and-examples/cms/database.rst +++ b/en/tutorials-and-examples/cms/database.rst @@ -131,33 +131,26 @@ might look something like the following:: [ 'default' => [ - 'className' => 'Cake\Database\Connection', - // Replace Mysql with Postgres if you are using PostgreSQL - 'driver' => 'Cake\Database\Driver\Mysql', - 'persistent' => false, 'host' => 'localhost', 'username' => 'cakephp', 'password' => 'AngelF00dC4k3~', 'database' => 'cake_cms', - // Comment out the line below if you are using PostgreSQL - 'encoding' => 'utf8mb4', - 'timezone' => 'UTC', - 'cacheMetadata' => true, + 'url' => env('DATABASE_URL', null), ], ], - // More configuration below. + // Más configuración abajo. ]; -Once you've saved your **config/app.php** file, you should see that the 'CakePHP is +Once you've saved your **config/app_local.php** file, you should see that the 'CakePHP is able to connect to the database' section has a green chef hat. .. note:: - If you have **config/app_local.php** in your app folder, you need to - configure your database connection in that file instead. + The file **config/app_local.php** in your is a local override of the file **config/app_local.php** + used to configure your development environment quickly. Creating our First Model ======================== @@ -174,7 +167,8 @@ to **src/Model/Table/ArticlesTable.php**. The completed file should look like this:: addBehavior('Timestamp'); } } @@ -215,9 +210,12 @@ look like this:: class Article extends Entity { protected array $_accessible = [ - '*' => true, - 'id' => false, - 'slug' => false, + 'title' => true, + 'body' => true, + 'published' => true, + 'created' => true, + 'modified' => true, + 'users' => true, ]; } diff --git a/es/tutorials-and-examples/cms/database.rst b/es/tutorials-and-examples/cms/database.rst index ce208c8011..34131e89fb 100644 --- a/es/tutorials-and-examples/cms/database.rst +++ b/es/tutorials-and-examples/cms/database.rst @@ -122,7 +122,7 @@ Configuración de la base de datos ================================= A continuación, digamos a CakePHP dónde está nuestra base de datos y cómo conectarse a ella. Reemplace -los valores en el arreglo ``Datasources.default`` en su archivo **config/app.php** con los que aplican +los valores en el arreglo ``Datasources.default`` en su archivo **config/app_local.php** con los que aplican a su configuración. Una arreglo de configuración completo de muestra podría tener el siguiente aspecto:: [ 'default' => [ - 'className' => 'Cake\Database\Connection', - // Replace Mysql with Postgres if you are using PostgreSQL - 'driver' => 'Cake\Database\Driver\Mysql', - 'persistent' => false, 'host' => 'localhost', 'username' => 'cakephp', 'password' => 'AngelF00dC4k3~', 'database' => 'cake_cms', - // Comment out the line below if you are using PostgreSQL - 'encoding' => 'utf8mb4', - 'timezone' => 'UTC', - 'cacheMetadata' => true, + 'url' => env('DATABASE_URL', null), ], ], // Más configuración abajo. ]; -Una vez que haya guardado su archivo **config/app.php**, debería ver que la sección +Una vez que haya guardado su archivo **config/app_local.php**, debería ver que la sección 'CakePHP is able to connect to the database' tiene un gorro de cocinero verde. .. note:: - Si tiene **config/app_local.php** en la carpeta de su aplicación, - este anula la configuración de app.php. + El fichero **config/app_local.php** se utiliza para sobreescribir los valores por defecto de la + configuración en **config/app.php**. Esto facilita la configuración en los entornos de desarrollo. Creando nuestro primer modelo ============================= @@ -169,7 +162,8 @@ en **src/Model/Table**. El archivo que crearemos se guardará en **src/Model/Tab El archivo completo debería verse así:: addBehavior('Timestamp'); } } -Hemos agregado el comportamiento :doc:`/orm/behaviors/timestamp` que automáticamente +Hemos agregado el comportamiento :doc:`/orm/behaviors/timestamp` que automáticamente llenará las columnas ``created`` y ``modified`` de nuestra tabla. Al nombrar nuestro objeto ``Table`` ``ArticlesTable``, CakePHP puede usar convenciones de nomenclatura para saber que nuestro modelo usa la tabla `articles`` de la base de datos. CakePHP @@ -202,7 +197,8 @@ nuestros datos. Nuestra ``Entity`` se guardará en **src/Model/Entity/Article.ph archivo completo debería verse así:: true, - 'id' => false, - 'slug' => false, + 'title' => true, + 'body' => true, + 'published' => true, + 'created' => true, + 'modified' => true, + 'users' => true, ]; } From 9d2ba70f37add0f3755d8bbd937c2c3b54726d87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20Gonz=C3=A1lez?= Date: Fri, 27 Oct 2023 11:09:30 +0100 Subject: [PATCH 078/337] fix file comments and typo --- en/tutorials-and-examples/cms/database.rst | 8 ++++++-- es/tutorials-and-examples/cms/database.rst | 3 +++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/en/tutorials-and-examples/cms/database.rst b/en/tutorials-and-examples/cms/database.rst index da063be179..9bfc2c8dde 100644 --- a/en/tutorials-and-examples/cms/database.rst +++ b/en/tutorials-and-examples/cms/database.rst @@ -130,8 +130,9 @@ with those that apply to your setup. A sample completed configuration array might look something like the following:: [ 'default' => [ 'host' => 'localhost', @@ -141,7 +142,7 @@ might look something like the following:: 'url' => env('DATABASE_URL', null), ], ], - // Más configuración abajo. + // More configuration below. ]; Once you've saved your **config/app_local.php** file, you should see that the 'CakePHP is @@ -167,6 +168,7 @@ to **src/Model/Table/ArticlesTable.php**. The completed file should look like this:: [ @@ -162,6 +163,7 @@ en **src/Model/Table**. El archivo que crearemos se guardará en **src/Model/Tab El archivo completo debería verse así:: Date: Sat, 28 Oct 2023 12:05:27 +0100 Subject: [PATCH 079/337] Removed deprecated files --- es/controllers/components/authentication.rst | 15 - es/controllers/components/pagination.rst | 324 ------------- .../components/request-handling.rst | 15 - es/controllers/components/security.rst | 191 -------- es/tutorials-and-examples/bookmarks/intro.rst | 393 --------------- .../bookmarks/part-two.rst | 455 ------------------ 6 files changed, 1393 deletions(-) delete mode 100644 es/controllers/components/authentication.rst delete mode 100644 es/controllers/components/pagination.rst delete mode 100644 es/controllers/components/request-handling.rst delete mode 100644 es/controllers/components/security.rst delete mode 100644 es/tutorials-and-examples/bookmarks/intro.rst delete mode 100644 es/tutorials-and-examples/bookmarks/part-two.rst diff --git a/es/controllers/components/authentication.rst b/es/controllers/components/authentication.rst deleted file mode 100644 index 552273efa1..0000000000 --- a/es/controllers/components/authentication.rst +++ /dev/null @@ -1,15 +0,0 @@ -Authentication -############## - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Authentication - :keywords lang=es: authentication handlers,array php,basic authentication,web application,different ways,credentials,exceptions,cakephp,logging diff --git a/es/controllers/components/pagination.rst b/es/controllers/components/pagination.rst deleted file mode 100644 index 138fccaaa0..0000000000 --- a/es/controllers/components/pagination.rst +++ /dev/null @@ -1,324 +0,0 @@ -Paginación -########## - -.. php:namespace:: Cake\Controller\Component - -.. php:class:: PaginatorComponent - -Uno de los mayores obstaculos para crear aplicaciones web flexibles y -amigables para el usuario es diseñar una interfaz de usuario intuitiva. -Muchas aplicaciones tienen a crecer en tamaño y complejidad rapidamente, -y los diseñadores y programadores por igual no pueden hacer frente -a la visualización de cientos o miles de registros. Refactorizar lleva -tiempo, y el rendimiento y la satisfación del usuario pueden verse afectados. - -Mostrar un número razonable de registros por página siempre ha sido una parte crítica -para cada aplicación y suele causar muchos dolores de cabeza a los desarrolladores. -CakePHP alivia la carga del desarrollador al proporcionar una manera rapida y fácil -de paginar datos. - -La paginación en CakePHP es ofrecida por un componente de un controlador. Puedes utilizar -:php:class:`~Cake\\View\\Helper\\PaginatorHelper` en la vista de tu plantilla para generar -los controles de paginación. - -Uso Básico -========== - -Para paginar una consulta primero debemos cargar el ``PaginatorComponent``:: - - class ArticlesController extends AppController - { - public function initialize(): void - { - parent::initialize(); - $this->loadComponent('Paginator'); - } - } - -Una vez cargado podemos paginar una tabla de clase ORM o un objeto ``Query``:: - - public function index() - { - // Paginate the ORM table. - $this->set('articles', $this->paginate($this->Articles)); - - // Paginate a partially completed query - $query = $this->Articles->find('published'); - $this->set('articles', $this->paginate($query)); - } - -Uso Avanzado -============ - -El componente ``PaginatorComponent`` admite casos de uso más complejos mediante la -configuración de la propiedad del controlador ``$paginate`` o como el argumento ``$settings`` -para ``paginate()``. Estas condiciones sirven como base para tus consultas de paginación. -Son aumentados por los parametros ``sort``, ``direction``, ``limit``, y ``page`` pasados -dentro de la URL:: - - class ArticlesController extends AppController - { - public $paginate = [ - 'limit' => 25, - 'order' => [ - 'Articles.title' => 'asc' - ] - ]; - } - -.. tip:: - Las opciones predeterminadas de ``order`` deben definirse como un array. - -Si bien puedes incluir cualquiera de las opciones soportadas por :php:meth:`~Cake\\ORM\\Table::find()` -como ``fields`` en tus ajustes de paginación. Es más limpio y sencillo agrupar tus opciones de -paginación dentro de :ref:`custom-find-methods`. Puedes usar tu buscador en la paginación utilizando la -opción ``finder`` :: - - class ArticlesController extends AppController - { - public $paginate = [ - 'finder' => 'published', - ]; - } - -Si tu metodo de busqueda requiere opciones adicionales, puedes pasarlas como como valores -para el buscador:: - - class ArticlesController extends AppController - { - // find articles by tag - public function tags() - { - $tags = $this->request->getParam('pass'); - - $customFinderOptions = [ - 'tags' => $tags - ]; - // Estamos utilizando el argumento $settings para paginate() aqui. - // Pero la misma estructura puede ser utilizada para $this->paginate - // - // Nuestro buscador personalizado se llama findTagged dentro ArticlesTable.php - // por eso estamos usando `tagged` como clave. - // Nuestro buscador deberia verse como: - // public function findTagged(Query $query, array $options) { - $settings = [ - 'finder' => [ - 'tagged' => $customFinderOptions - ] - ]; - $articles = $this->paginate($this->Articles, $settings); - $this->set(compact('articles', 'tags')); - } - } - -Además de definir valores generales de paginación, puedes definir mas de un conjunto de -valores predeterminados para la paginación en el controlador. El nombre de cada modelo -puede ser usado como clave en la propiedad ``$paginate``:: - - class ArticlesController extends AppController - { - public $paginate = [ - 'Articles' => [], - 'Authors' => [], - ]; - } - -Los valores de las claves de ``Articles`` y ``Authors`` podrían contener todas las -propiedades que tendría una matriz básica ``$paginate``. - -Una vez que hayas utilizado ``paginate()`` para crear resultados. La solicitud del -controlador se actualizará con los parámetros de paginación. Puedes acceder a los -metadatos de paginación en ``$this->request->getParam('paging')``. - -Paginación Simple -================= - -Por defecto, la paginación utiliza una consulta ``count()`` para calcular el tamaño -del conjunto de resultados para que puedan ser renderizados los enlaces de número de -página. En conjuntos de datos muy grandes, esta consulta de conteo puede ser muy costosa. -En situaciones donde solo quieres mostrar los enlaces "Siguiente" y "Anterior" puedes -utilizar el paginador 'simple' que realiza una consulta de conteo:: - - public function initialize(): void - { - parent::initialize(); - - // Load the paginator component with the simple paginator strategy. - $this->loadComponent('Paginator', [ - 'paginator' => new \Cake\Datasource\SimplePaginator(), - ]); - } - -Cuando se utilice el ``SimplePaginator`` no se podra generar los números de pagina, -datos de contador, enlaces a la ultima pagina, o controles de recuento total de registros. - -Utilizando Directamente PaginatorComponent -========================================== - -Si necesitas paginar datos de otro componente, puedes utilizar el ``PaginatorComponent`` directamente. -Cuenta con una API similar al método controlador:: - - $articles = $this->Paginator->paginate($articleTable->find(), $config); - - // Or - $articles = $this->Paginator->paginate($articleTable, $config); - -El primer parámetro debe ser el objeto de consulta a encontrar en la tabla de objetos de la que se -desea paginar los resultados. Opcionalmente, puedes pasar el tabla de objetos y dejar la consulta -se construirá para usted. El segundo parametro deberia ser el array de los ajustes para usar en la -paginación. Este array deberia tener la misma estructura que la propiedad ``$paginate`` en el -controlador. Al paginar un objeto ``Query``, la opción ``finder`` sera ignorada. Se da por asumido -que se esta pasando la consulta que desas que sea paginada. - -.. _paginating-multiple-queries: - -Paginando Multiples Consultas -============================= - -Puedes paginar multiples modelos en una sola accion del controlador, usando la opción ``scope`` -tanto en la propiedad ``$paginate`` del controlador y en la llamada al metodo ``paginate()``:: - - // Propiedad paginado - public $paginate = [ - 'Articles' => ['scope' => 'article'], - 'Tags' => ['scope' => 'tag'] - ]; - - // En una acción del controlador - $articles = $this->paginate($this->Articles, ['scope' => 'article']); - $tags = $this->paginate($this->Tags, ['scope' => 'tag']); - $this->set(compact('articles', 'tags')); - -La opción ``scope`` dará como resultado el aspecto de ``PaginatorComponent`` en parámetros de cadena -de consulta con ámbito. Por ejemplo, el siguiente URL podría ser utilizado para paginar tags y articles -al mismo tiempo:: - - /dashboard?article[page]=1&tag[page]=3 - -Consulte la sección `paginator-helper-multiple` para saber como generar elementos HTML con ambito -y URLs para paginación. - -Paginar el Mismo Modelo Varias Veces ------------------------------------- - -Para paginar el mismo modelo multiples veces dentro de una sola acción del controlador necesitas definir -un alias para el modelo. Consulte `table-registry-usage` para detalles adicionales sobre como -utilizar la tabla de registros:: - - // En una acción del controlador - $this->paginate = [ - 'ArticlesTable' => [ - 'scope' => 'published_articles', - 'limit' => 10, - 'order' => [ - 'id' => 'desc', - ], - ], - 'UnpublishedArticlesTable' => [ - 'scope' => 'unpublished_articles', - 'limit' => 10, - 'order' => [ - 'id' => 'desc', - ], - ], - ]; - - // Registrar una tabla de objetos adicional para permitir la diferenciación en el componente de paginación - TableRegistry::getTableLocator()->setConfig('UnpublishedArticles', [ - 'className' => 'App\Model\Table\ArticlesTable', - 'table' => 'articles', - 'entityClass' => 'App\Model\Entity\Article', - ]); - - $publishedArticles = $this->paginate( - $this->Articles->find('all', [ - 'scope' => 'published_articles' - ])->where(['published' => true]) - ); - - $unpublishedArticles = $this->paginate( - TableRegistry::getTableLocator()->get('UnpublishedArticles')->find('all', [ - 'scope' => 'unpublished_articles' - ])->where(['published' => false]) - ); - -.. _control-which-fields-used-for-ordering: - -Controlar que Campos se utilizan para Ordenar -============================================= - -Por defecto, el ordenamiento se puede realizar en cualquier columna no virtual que la tabla tenga. -Esto es, a veces no deseable ya que permite a los usuarios ordenar por columnas no indexadas que pueden -provocar gran trabajo para ser ordenadas. Puedes establecer una lista blanca de campos que se pueden -ordenar utilando la opción ``sortWhitelist``. Esta opción es necesaria cuando quieres ordenar datos asociados -o campos calculados que pueden formar parte de la consulta de paginación:: - - public $paginate = [ - 'sortWhitelist' => [ - 'id', 'title', 'Users.username', 'created' - ] - ]; - -Cualquier solicitud que intente ordenar campos que no se encuentren en el lista blanca será ignorada. - -Limitar el Número Máximo de Filas por Página -============================================ - -El número de resultados que se obtienen por página se expone al usuario como el parametro ``limit``. -Generalmente no es deseable permitir que los usuarios obtengan todas las filas en un conjunto paginado. -La opción ``maxLimit`` establece que nadie puede configurar este límite demasiado alto desde afuera. -Por defecto, CakePHP limita el número maximo de filas que pueden ser obtenidas a 100. Si este limite por -defecto no es apropiado para tu aplicación, puedes ajustarlo en las opciones de paginación, por ejemplo, -reduciendolo a ``10``:: - - public $paginate = [ - // Other keys here. - 'maxLimit' => 10 - ]; - -Si el parametro de la solictud es mayor a este valor, se reducirá al valor de ``maxLimit``. - -Uniendo Asociaciones Adicionales -================================ - -Se pueden cargar asociaciones adicionales en la tabla paginada utilizando el parametro ``contain``:: - - public function index() - { - $this->paginate = [ - 'contain' => ['Authors', 'Comments'] - ]; - - $this->set('articles', $this->paginate($this->Articles)); - } - -Solicitudes de Página Fuera de Rango -==================================== - -El PaginatorComponent lanzará un ``NotFoundException`` cuando trate de acceder a una página no existente, -es decir, cuando el número de página solicitado sea mayor al número de páginas. - -Por lo tanto, puedes dejar que se muestre la página de error normal o utilizar un bloque try catch y -tomar las medidas apropiadas cuando se detecta un ``NotFoundException``:: - - use Cake\Http\Exception\NotFoundException; - - public function index() - { - try { - $this->paginate(); - } catch (NotFoundException $e) { - // Has algo aquí como redirigir a la primera página o a la ultima página. - // $this->request->getAttribute('paging') te dara la información requerida. - } - } - -Paginación en la Vista -====================== - -Consulte la documentación :php:class:`~Cake\\View\\Helper\\PaginatorHelper` para saber como crear -enlaces para la navegación de paginación. - -.. meta:: - :title lang=es: Paginación - :keywords lang=es: array ordenado,condiciones de consulta,clase php,aplicaciones web,dolores de cabeza,obstaculos,complejidad,programadores,parametros,paginado,diseñadores,cakephp,satisfacción,desarrolladores diff --git a/es/controllers/components/request-handling.rst b/es/controllers/components/request-handling.rst deleted file mode 100644 index c219ab6f61..0000000000 --- a/es/controllers/components/request-handling.rst +++ /dev/null @@ -1,15 +0,0 @@ -Request Handling -################ - -.. note:: - La documentación no es compatible actualmente con el idioma español en esta página. - - Por favor, siéntase libre de enviarnos un pull request en - `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. - - Usted puede hacer referencia a la versión en Inglés en el menú de selección superior - para obtener información sobre el tema de esta página. - -.. meta:: - :title lang=es: Request Handling - :keywords lang=es: handler component,javascript libraries,public components,null returns,model data,request data,content types,file extensions,ajax,meth,content type,array,conjunction,cakephp,insight,php diff --git a/es/controllers/components/security.rst b/es/controllers/components/security.rst deleted file mode 100644 index 261c8bd3d4..0000000000 --- a/es/controllers/components/security.rst +++ /dev/null @@ -1,191 +0,0 @@ -Seguridad -######### - -.. php:class:: SecurityComponent(ComponentCollection $collection, array $config = []) - -El componente de seguridad crea una forma de integrar seguridad de forma más estricta -en tu aplicación. Proporciona métodos para diversas tareas como: - -* Restringir qué métodos HTTP acepta tu aplicación. -* Protección contra manipulación de formularios. -* Requerir que se utilice SSL. -* Limitación de la comunicación entre controladores. - -Como todos los componentes, se configura a través de varios parámetros configurables. -Todas estas propiedades se pueden establecer directamente o a través de métodos setter -del mismo nombre en ``beforeFilter()`` de tu controlador. - -Al usar el componente de seguridad, obtienes automáticamente protección contra la -manipulación de formularios. Los campos token ocultos se insertarán automáticamente -en los formularios y serán verificados por el componente de seguridad. - -Si estas utilizando las funciones de protección de formularios del componente de -seguridad y otros componentes que procesan datos de formularios en tus devoluciones -de llamada ``startup()``, asegúrate de colocar el componente de seguridad antes de -esos componentes en tu método ``initialize()``. - -.. note:: - - Al usar el componente de seguridad, **debes** usar FormHelper para crear tus - formularios. Además, **no** debes reescribir ninguno de los "nombres" de los - campos. El componente de seguridad busca ciertos indicadores que son creados - y manejados por FormHelper (especialmente esos creados en - :php:meth:`~Cake\\View\\Helper\\FormHelper::create()` y - :php:meth:`~Cake\\View\\Helper\\FormHelper::end()`). Es probable que la modificación - dinámica de los campos que se envían en una solicitud POST, como deshabilitar, - borrar o crear nuevos campos a través de JavaScript, haga que la solicitud se - envíe a la devolución de llamada de blackhole. - - Siempre debes verificar el método HTTP que se utiliza antes de ejecutarlo para - evitar efectos secundarios. Debes verificar el método HTTP - o usar :php:meth:`Cake\\Http\\ServerRequest::allowMethod()` para asegurarte - de que se utiliza el método HTTP correcto. - -Manejo de devoluciones de llamada blackhole -=========================================== - -.. php:method:: blackHole(Controller $controller, string $error = '', ?SecurityException $exception = null) - -Si una acción está restringida por el componente de seguridad, es 'black-holed' -como una solicitud no válida que dará como resultado un error 400 por defecto. -Puedes configurar este comportamiento seteando la opción de configuración -``blackHoleCallback`` para una función de devolución de llamada en el controlador. - -Al configurar un método de devolución de llamada, puedes personalizar como el -proceso blackhole funciona:: - - public function beforeFilter(EventInterface $event) - { - parent::beforeFilter($event); - - $this->Security->setConfig('blackHoleCallback', 'blackhole'); - } - - public function blackhole($type, SecurityException $exception) - { - if ($exception->getMessage() === 'Request is not SSL and the action is required to be secure') { - // Reformule el mensaje de excepción con un string traducible. - $exception->setMessage(__('Please access the requested page through HTTPS')); - } - - // Vuelve a lanzar la excepción reformulada condicionalmente. - throw $exception; - - // Alternativamente, maneja el error. Por ejemplo, configura un mensaje flash & - // redirige a la versión HTTPS de la página solicitada. - } - -El parámetro ``$type`` puede tener los siguientes valores: - -* 'auth' Indica un error de validación de formulario o un error de discrepancia - entre controlador y acción. -* 'secure' Indica un error de restricción del método SSL. - -Prevención de manipulación de formularios -========================================= - -Por defecto, ``SecurityComponent`` evita que los usuarios alteren los formularios -de formas específicas. El ``SecurityComponent`` evitará las siguientes cosas: - -* Los campos desconocidos no podrán ser agregados al formulario. -* Los campos no pueden ser eliminados del formulario. -* Los valores en las entradas ocultas no podrán ser modificadas. - -La prevención de este tipo de manipulación se logra trabajando con ``FormHelper`` -y rastreando qué campos hay en un formulario. También se realiza un seguimiento -de los valores de los campos ocultos. Todos estos datos se combinan y se convierten -en un hash. Cuando un formulario es enviado, ``SecurityComponent`` usará los datos -POST para construir la misma estructura y comparar el hash. - -.. note:: - - SecurityComponent **no** evitará que se agreguen/cambien opciones seleccionadas. - Tampoco impedirá que se agreguen/cambien opciones de radio. - -unlockedFields - Establecer en una lista de campos de formulario para excluir de la validación - POST. Los campos se pueden desbloquear en el componente o con :php:meth:`FormHelper::unlockField()`. - Los campos que han sido desbloqueados no están obligados a ser parte del POST - y los campos desbloqueados ocultos no tienen su valores verificados. - -validatePost - Establece en ``false`` para omitir por completo la validación de las solicitudes - POST, esencialmente desactivando las validaciones de los formularios. - -Uso -=== - -La configuración del componente de seguridad generalmente se realiza en las -devoluciones de llamada ``initialize`` o ``beforeFilter()`` del controlador:: - - namespace App\Controller; - - use App\Controller\AppController; - use Cake\Event\EventInterface; - - class WidgetsController extends AppController - { - public function initialize(): void - { - parent::initialize(); - $this->loadComponent('Security'); - } - - public function beforeFilter(EventInterface $event) - { - parent::beforeFilter($event); - - if ($this->request->getParam('prefix') === 'Admin') { - $this->Security->setConfig('validatePost', false); - } - } - } - -El ejemplo anterior deshabilitaría la prevención de manipulación de formularios -para rutas con prefijo de administrador. - -.. _security-csrf: - -Protección CSRF -=============== - -CSRF o Cross Site Request Forgery es una vulnerabilidad común en las aplicaciones -web. Permite a un atacante capturar y reproducir una solicitud anterior, y a veces, -enviar solicitudes de datos utilizando etiquetas de imagen o recursos en otros -dominios. Para habilitar las funciones de protección CSRF. - -Deshabilitar la manipulación de formularios para acciones específicas -===================================================================== - -Hay muchos casos en los que querrías deshabilitar la prevención de manipulación -de formularios para una acción (por ejemplo, solicitudes AJAX). Puedes "desbloquear" -estas acciones enumerándolas en ``$this->Security->unlockedActions`` en tu -``beforeFilter()``:: - - namespace App\Controller; - - use App\Controller\AppController; - use Cake\Event\EventInterface; - - class WidgetController extends AppController - { - public function initialize(): void - { - parent::initialize(); - $this->loadComponent('Security'); - } - - public function beforeFilter(EventInterface $event) - { - parent::beforeFilter($event); - - $this->Security->setConfig('unlockedActions', ['edit']); - } - } - -Este ejemplo deshabilitaría todas las comprobaciones de seguridad para las acciones -de edición. - -.. meta:: - :title lang=es: Seguridad - :keywords lang=es: parámetros configurables, componente de seguridad, parámetros de configuración, solicitud no válida, funciones de protección, seguridad más estricta, holing, clase php, meth, error 404, período de inactividad, csrf, array, envío, clase de seguridad, deshabilitar seguridad, desbloquear acciones diff --git a/es/tutorials-and-examples/bookmarks/intro.rst b/es/tutorials-and-examples/bookmarks/intro.rst deleted file mode 100644 index 12c308a159..0000000000 --- a/es/tutorials-and-examples/bookmarks/intro.rst +++ /dev/null @@ -1,393 +0,0 @@ -Tutorial Bookmarker (Favoritos) -############################### - -Este tutorial te guiará en la creación de una aplicación sencilla para el guardado de favoritos (Bookmaker). - -Para comenzar instalaremos CakePHP creando nuestra base de datos y utilizaremos las herramientas que CakePHP provee para realizar nuestra aplicación rápidamente. - -Esto es lo que necesitarás: - -#. Un servidor de base de datos. Nosotros utilizaremos MySQL en este tutorial. Necesitarás tener los conocimientos suficientes de SQL para crear una base de datos; CakePHP tomará las riendas desde ahí. Al utilizar MySQL asegúrate de que tienes habilitado ``pdo_mysql`` en PHP. -#. Conocimientos básicos de PHP. - -Antes de empezar deberías de asegurarte de que tienes actualizada la versión de PHP: - -.. code-block:: console - - php -v - -Deberías tener instalado PHP |minphpversion| (CLI) o superior. La versión PHP de tu servidor web deberá ser |minphpversion| o superior y lo ideal es que coincida con la versión de la interfaz de línea de comandos (CLI) de PHP. Si quieres ver la aplicación ya finalizada puedes consultar `cakephp/bookmarker `__. - -Empecemos! - -Instalar CakePHP -================ - -La forma más sencilla de instalar CakePHP es utilizando Composer, una manera sencilla de instalar CakePHP desde tu terminal o prompt de línea de comandos. - -Primero necesitarás descargar e instalar Composer si aún no lo tienes. Si ya tienes instalado cURL es tan sencillo como ejecutar:: - - curl -s https://getcomposer.org/installer | php - -O puedes descargar ``composer.phar`` desde la `Página web de Composer `_. - -Después sencillamente escribe la siguiente línea en tu terminal desde tu directorio de instalación para instalar el esqueleto de la aplicación CakePHP en el directorio **bookmarker**:: - - php composer.phar create-project --prefer-dist cakephp/app:4.* bookmarker - -Si descargaste y ejecutaste el `Instalador Windows de Composer `_, entonces escribe la siguiente línea en tu terminal desde tu directorio de instalación (ie. C:\\wamp\\www\\dev\\cakephp3):: - - composer self-update && composer create-project --prefer-dist cakephp/app:4.* bookmarker - -La ventaja de utilizar Composer es que automáticamente realizará algunas tareas importantes como configurar correctamente el archivo de permisos y crear tu archivo **config/app.php**. - -Hay otras formas de instalar CakePHP. Si no puedes o no quieres utilizar Composer comprueba la sección :doc:`/installation`. - -Sin importar como hayas descargado e instalado CakePHP, una vez hayas finalizado, tu directorio de instalación debería ser algo como:: - - /bookmarker - /bin - /config - /logs - /plugins - /src - /tests - /tmp - /vendor - /webroot - .editorconfig - .gitignore - .htaccess - .travis.yml - composer.json - index.php - phpunit.xml.dist - README.md - -Ahora podría ser un buen momento para que aprendas un poco sobre como funciona la estructura de directorios de CakePHP: :doc:`/intro/cakephp-folder-structure`. - -Comprobar la instalación -======================== - -Podemos comprobar rápidamente que nuestra instalación ha sido correcta accediendo a la página principal que se crea por defecto. - -Pero antes necesitarás inicializar el servidor de desarrollo:: - - bin/cake server - -.. note:: - - Para Windows introduce el comando ``bin\cake server`` (fíjate en la \\ ). - -Esto arrancará el servidor integrado en el puerto 8765. Accede a **http://localhost:8765** a través de tu navegador para ver la página de bienvenida. Todos los items deberán estar marcados como correctos para que CakePHP pueda conectarse a tu base de datos. Si no, puede que necesites instalar extensiones adicionales de PHP, o dar permisos de directorio. - -Crear la base de datos -====================== - -Continuamos, creemos ahora la base de datos para nuestra aplicación de favoritos. - -Si aún no lo has hecho, crea una base de datos vacía para usar en este tutorial con el nombre que tu quieras, e.g. ``cake_bookmarks``. - -Puedes ejecutar la siguiente sentencia SQL para crear las tablas necesarias: - -.. code-block:: mysql - - CREATE TABLE users ( - id INT AUTO_INCREMENT PRIMARY KEY, - email VARCHAR(255) NOT NULL, - password VARCHAR(255) NOT NULL, - created DATETIME, - modified DATETIME - ); - - CREATE TABLE bookmarks ( - id INT AUTO_INCREMENT PRIMARY KEY, - user_id INT NOT NULL, - title VARCHAR(50), - description TEXT, - url TEXT, - created DATETIME, - modified DATETIME, - FOREIGN KEY user_key (user_id) REFERENCES users(id) - ); - - CREATE TABLE tags ( - id INT AUTO_INCREMENT PRIMARY KEY, - title VARCHAR(255), - created DATETIME, - modified DATETIME, - UNIQUE KEY (title) - ); - - CREATE TABLE bookmarks_tags ( - bookmark_id INT NOT NULL, - tag_id INT NOT NULL, - PRIMARY KEY (bookmark_id, tag_id), - FOREIGN KEY tag_key(tag_id) REFERENCES tags(id), - FOREIGN KEY bookmark_key(bookmark_id) REFERENCES bookmarks(id) - ); - -Puedes ver que la tabla ``bookmarks_tags`` utiliza una clave primaria compuesta. CakePHP soporta claves primarias compuestas en casi cualquier lado, haciendo más fácil construir aplicaciones multi-anidadas. - -Los nombres de las tablas y columnas que hemos utilizado no son aleatorios. Utilizando las :doc:`convenciones de nombres ` podemos hacer mejor uso de CakePHP y evitar tener que configurar el framework. - -CakePHP es lo suficientemente flexible para acomodarse incluso a esquemas inconsistentes de bases de datos heredados, pero siguiendo las convenciones ahorrarás tiempo. - -Configuración de la base de datos -================================= - -Siguiente, indiquémosle a CakePHP donde está nuestra base de datos y como conectarse a ella. Para la mayoría de las veces esta será la primera y última vez que necesitarás configurar algo. - -La configuración debería ser bastante sencilla: sólo cambia los valores del array ``Datasources.default`` en el archivo **config/app.php** por aquellos que apliquen a tu instalación. Un ejemplo de array de configuración completado puede lucir así:: - - return [ - // More configuration above. - 'Datasources' => [ - 'default' => [ - 'className' => 'Cake\Database\Connection', - 'driver' => 'Cake\Database\Driver\Mysql', - 'persistent' => false, - 'host' => 'localhost', - 'username' => 'cakephp', - 'password' => 'AngelF00dC4k3~', - 'database' => 'cake_bookmarks', - 'encoding' => 'utf8', - 'timezone' => 'UTC', - 'cacheMetadata' => true, - ], - ], - // More configuration below. - ]; - -Una vez hayas guardado tu archivo **config/app.php** deberías ver que la sección 'CakePHP is -able to connect to the database' tiene un chechmark de correcto. - -.. note:: - - Puedes encontrar una copia de la configuración por defecto de CakePHP en **config/app.default.php**. - -Crear el esqueleto del código -============================== - -Gracias a que nuestra base de datos sigue las convenciones de CakePHP podemos utilizar la :doc:`consola de bake ` de la aplicación para crear rápidamente una aplicación básica. - -En tu línea de comandos ejecuta las siguientes instrucciones:: - - // En Windows necesitarás utilizar bin\cake. - bin/cake bake all users - bin/cake bake all bookmarks - bin/cake bake all tags - -Esto creará los controladores, modelos, vistas, sus correspondientes casos de prueba y accesorios para nuestros recursos de users, bookmarks y tags. - -Si detuviste tu servidor reinícialo. - -Vete a **http://localhost:8765/bookmarks**, deberías poder ver una básica pero funcional aplicación provista de acceso a las tablas de tu base de datos. - -Una vez estés en la lista de bookmarks añade unos cuantos usuarios (users), favoritos (bookmarks) y etiquetas (tags) - -.. note:: - - Si ves una página de error Not Found (404) comprueba que el módulo de Apache mod_rewrite está cargado. - -Añadir encriptación (hashing) a la contraseña -============================================== - -Cuando creaste tus usuarios (visitando **http://localhost:8765/users**) probablemente te darías cuenta de que las contraseñas (password) se almacenaron en texto plano. Algo muy malo desde un punto de vista de seguridad, así que arreglémoslo. - -Éste es también un buen momento para hablar de la capa de modelo en CakePHP. - -En CakePHP separamos los métodos que operan con una colección de objetos y los que lo hacen con un único objeto en diferentes clases. - -Los métodos que operan con una coleccion de entidades van en la clase ``Table``, mientras que los que lo hacen con una sola van en la clase ``Entity``. - -Por ejemplo: el encriptado de una contraseña se hace en un registro individual, por lo que implementaremos este comportamiento en el objeto Entity. - -Ya que lo que queremos es encriptar la contraseña cada vez que la introduzcamos en la base de datos utilizaremos un método mutador/setter. - -CakePHP utilizará la convención para métodos setter cada vez que una propiedad se introducida en una de tus entidades. - -Añadamos un setter para la contraseña añadiendo el siguiente código en **src/Model/Entity/User.php**:: - - namespace App\Model\Entity; - - use Cake\Auth\DefaultPasswordHasher; //include this line - use Cake\ORM\Entity; - - class User extends Entity - { - - // Code from bake. - - protected function _setPassword($value) - { - $hasher = new DefaultPasswordHasher(); - return $hasher->hash($value); - } - } - -Ahora actualiza uno de los usuarios que creaste antes, si cambias su contraseña deberías ver una contraseña encriptada en vez del valor original en la lista de usuarios o en su página de View. - -CakePHP encripta contraseñas con `bcrypt -`_ por defecto. Puedes usar también sha1 o md5 si estás trabajando con bases de datos ya existentes. - -.. note:: - - Si la contraseña no se ha encriptado asegúrate de que has usado el mismo estilo de escritura que el del atributo password de la clase cuando nombraste la función setter. - -Obtener bookmarks con un tag específico -======================================== - -Ahora que estamos almacenando contraseñas con seguridad podemos añadir alguna funcionalidad interesante a nuestra aplicación. - -Cuando acumulas una colección de favoritos es útil poder buscarlos a través de etiquetas. - -Implementemos una ruta, una acción de controlador y un método finder para buscar bookmarks mediante etiquetas. - -Idealmente tendríamos una URL como **http://localhost:8765/bookmarks/tagged/funny/cat/gifs** que nos permitiría encontrar todos los bookmarks que tienen las etiquetas 'funny', 'cat' o 'gifs'. - -Antes de que podamos implementarlo añadiremos una nueva ruta. - -Modifica tu **config/routes.php** para que se vea como ésto:: - - 'Bookmarks'], - function ($routes) { - $routes->connect('/tagged/*', ['action' => 'tags']); - } - ); - - Router::scope('/', function ($routes) { - // Connect the default home and /pages/* routes. - $routes->connect('/', [ - 'controller' => 'Pages', - 'action' => 'display', 'home' - ]); - $routes->connect('/pages/*', [ - 'controller' => 'Pages', - 'action' => 'display' - ]); - - // Connect the conventions based default routes. - $routes->fallbacks(); - }); - -Lo cual define una nueva 'ruta' que conecta el path **/bookmarks/tagged/** a ``BookmarksController::tags()``. - -Con la definición de rutas puedes separar como se ven tus URLs de como se implementan. Si visitamos **http://localhost:8765/bookmarks/tagged**, podremos ver una página de error bastante útil de CakePHP informando que no existe la acción del controlador. - -Implementemos ahora ese método. - -En **src/Controller/BookmarksController.php** añade:: - - public function tags() - { - // The 'pass' key is provided by CakePHP and contains all - // the passed URL path segments in the request. - $tags = $this->request->getParam('pass'); - - // Use the BookmarksTable to find tagged bookmarks. - $bookmarks = $this->Bookmarks->find('tagged', [ - 'tags' => $tags - ]); - - // Pass variables into the view template context. - $this->set([ - 'bookmarks' => $bookmarks, - 'tags' => $tags - ]); - } - -Para acceder a otras partes del request consulta :ref:`cake-request`. - -Crear el método finder ----------------------- - -En CakePHP nos gusta mantener las acciones de los controladores sencillas y poner la mayoría de la lógica de la aplicación en los modelos. Si visitas ahora la URL **/bookmarks/tagged** verás un error de que el método ``findTagged()`` no ha sido implementado todavía, asi que hagámoslo. - -En **src/Model/Table/BookmarksTable.php** añade lo siguiente:: - - // El argumento $query es una instancia de query. - // El array $options contendrá las opciones de 'tags' que pasemos - // para encontrar'tagged') en nuestra acción del controlador. - public function findTagged(Query $query, array $options) - { - $bookmarks = $this->find() - ->select(['id', 'url', 'title', 'description']); - - if (empty($options['tags'])) { - $bookmarks - ->leftJoinWith('Tags') - ->where(['Tags.title IS' => null]); - } else { - $bookmarks - ->innerJoinWith('Tags') - ->where(['Tags.title IN ' => $options['tags']]); - } - - return $bookmarks->group(['Bookmarks.id']); - } - -Acabamos de implementar un :ref:`método finder personalizado `. - -Esto es un concepto muy poderoso en CakePHP que te permite empaquetar queries re-utilizables. - -Los métodos finder siempre reciben un objeto :doc:`/orm/query-builder` y un array de opciones como parámetros. Estos métodos pueden manipular la query y añadir cualquier condición o criterio requerido; cuando se completan devuelven un objeto query modificado. - -En nuestro método finder sacamos provecho de los métodos ``distinct()`` y ``matching()`` que nos permiten encontrar distintos ('distincts') bookmarks que tienen un tag coincidente (matching). El método ``matching()`` acepta una `función anónima `_ que recibe un generador de consultas. Dentro del callback usaremos este generador para definir las condiciones que filtrarán bookmarks que tienen las etiquetas (tags) especificadas. - -Crear la vista --------------- - -Ahora si visitas la URL **/bookmarks/tagged**, CakePHP mostrará un error advirtiéndote de que no has creado un archivo de vista. - -Siguiente paso, creemos un archivo de vista para nuestro método ``tags()``. - -En **templates/Bookmarks/tags.php** añade el siguiente código:: - -

    - Bookmarks tagged with - Text->toList(h($tags)) ?> -

    - -
    - -
    - -

    Html->link($bookmark->title, $bookmark->url) ?>

    - url) ?> - - - Text->autoParagraph(h($bookmark->description)) ?> -
    - -
    - -En el código de arriba utilizamos los helpers :doc:`/views/helpers/html` y :doc:`/views/helpers/text` para que asistan en la generación de nuestra salida de la vista. - -También utilizamos la función de atajo ``h()`` para salidas de código HTML. Deberías acordarte siempre de utilizar ``h()`` cuando muestres datos del usuario para evitar problemas de inyección HTML. - -El archivo **tags.php** que acabamos de crear sigue las convenciones de CakePHP para archivos de vistas. La convención es que el nombre del archivo sea una versión en minúsculas y subrayados del nombre de la acción del controlador. - -Puedes observar que hemos podido usar las variables ``$tags`` y ``$bookmarks`` en nuestra vista. - -Cuando utilizamos el método ``set()`` en nuestro controlador especificamos variables para enviarlas a la vista. Ésta hará disponibles todas las variables que se le pasen como variables locales. - -Ahora deberías poder visitar la URL **/bookmarks/tagged/funny** y ver todos los favoritos etiquetados con 'funny'. - -Hasta aquí hemos creado una aplicación básica para manejar favoritos (bookmarks), etiquetas (tags) y usuarios (users). Sin embargo todo el mundo puede ver las etiquetas de los demás. En el siguiente capítulo implementaremos autenticación y restringiremos el uso de etiquetas únicamente a aquellas que pertenezcan al usuario actual. - -Ahora ve a :doc:`/tutorials-and-examples/bookmarks/part-two` para continuar construyendo tu apliación o :doc:`sumérgete en la documentación ` para aprender más sobre que puede hacer CakePHP por ti. - -.. meta:: - :title lang=es: Tutorial Bookmarker (Favoritos) diff --git a/es/tutorials-and-examples/bookmarks/part-two.rst b/es/tutorials-and-examples/bookmarks/part-two.rst deleted file mode 100644 index 900acd1c6f..0000000000 --- a/es/tutorials-and-examples/bookmarks/part-two.rst +++ /dev/null @@ -1,455 +0,0 @@ -Tutorial Bookmarker (Favoritos) - Parte 2 -######################################### - -Tras realizar :doc:`la primera parte de este tutorial ` -deberías tener una aplicación muy básica para guardar favoritos. - -En este capítulo añadiremos la autenticación y restringiremos los favoritos -(bookmarks) para que cada usuario pueda consultar o modificar solamente los suyos. - -Añadir login -============ - -En CakePHP, la autenticación se maneja mediante :doc:`/controllers/components`. - -Los componentes pueden verse como una forma de crear trozos reutilizables de -código de controlador para una finalidad o idea. Además pueden engancharse al -evento de ciclo de vida de los controladores e interactuar con tu aplicación -de ese modo. - -Para empezar añadiremos el componente :doc:`AuthComponent ` -a nuestra aplicación. - -Como queremos que todos nuestros métodos requieran de autenticación añadimos -*AuthComponent* en *AppController* del siguiente modo:: - - // En src/Controller/AppController.php - namespace App\Controller; - - use Cake\Controller\Controller; - - class AppController extends Controller - { - public function initialize() - { - $this->loadComponent('Flash'); - $this->loadComponent('Auth', [ - 'authenticate' => [ - 'Form' => [ - 'fields' => [ - 'username' => 'email', - 'password' => 'password' - ] - ] - ], - 'loginAction' => [ - 'controller' => 'Users', - 'action' => 'login' - ], - 'unauthorizedRedirect' => $this->referer() // Si no está autorizado, - //el usuario regresa a la página que estaba - ]); - - // Permite ejecutar la acción display para que nuestros controladores de páginas - // sigan funcionando. - $this->Auth->allow(['display']); - } - } - -Acabamos de decirle a CakePHP que queremos cargar los compomentes ``Flash`` y -``Auth``. Además hemos personalizado la configuración de *AuthComponent* indicando -que utilice como *username* el campo *email* de la tabla *Users* de la base de datos. - -Ahora si vas a cualquier *URL* serás enviado a **/users/login**, que mostrará una -página de error ya que no hemos escrito el código de la función *login* todavía, -así que hagámoslo ahora:: - - // En src/Controller/UsersController.php - public function login() - { - if ($this->request->is('post')) { - $user = $this->Auth->identify(); - if ($user) { - $this->Auth->setUser($user); - return $this->redirect($this->Auth->redirectUrl()); - } - $this->Flash->error('Tu usuario o contraseña es incorrecta.'); - } - } - -Y en **templates/Users/login.php** añade lo siguiente:: - -

    Login

    - Form->create() ?> - Form->input('email') ?> - Form->input('password') ?> - Form->button('Login') ?> - Form->end() ?> - -Ahora que tenemos un formulario de *login* sencillo deberíamos poder loguearnos -con algún usuario que tenga contraseña encriptada. - -.. note:: - - Si ninguno de tus usuarios tiene contraseña encriptada comenta la línea - ``loadComponent('Auth')``, a continuación edita un usuario y modifica - la contraseña. - -Ahora deberías poder loguearte, si no es así asegúrate de que estás utilizando -un usuario con contraseña encriptada. - -Añadir *logout* -=============== - -Ahora que la gente puede loguearse probablemente quieras añadir una forma de -desloguearse también. - -Otra vez en ``UsersController``, añade el siguiente código:: - - public function initialize() - { - parent::initialize(); - $this->Auth->allow(['logout']); - } - - public function logout() - { - $this->Flash->success('Ahora estás deslogueado.'); - return $this->redirect($this->Auth->logout()); - } - -Este código añade la acción ``logout`` como una acción pública e implementa -la función. - -Ahora puedes visitar ``/users/logout`` para desloguearte, deberías ser enviado -a la página de inicio. - -Habilitar registros -=================== - -Si no estás logueado e intentas acceder a **/users/add** eres reenviado a la -página de login. Deberíamos arreglar esto si queremos permitir que la gente se -pueda registrar en nuestra aplicación. - -En el controlador ``UsersController`` añade lo siguiente:: - - public function initialize() - { - parent::initialize(); - // Añade logout a la lista de actiones permitidas. - $this->Auth->allow(['logout', 'add']); - } - -El código anterior le dice a ``AuthComponent`` que la acción ``add()`` no -necesita autenticación ni autorización. - -Tal vez quieras tomarte un tiempo para limpiar **Users/add.php** y eliminar los -enlaces erróneos o continuar con el siguiente apartado. No vamos a crear la -edición de usuarios, consulta o listado en este tutorial así que no funcionará -el control de ``AuthComponent`` para el acceso a esas acciones del controlador. - -Restringiendo el acceso a favoritos -=================================== - -Ahora que los usuarios pueden loguearse queremos restringir los favoritos que -uno puede ver a los que creó. Esto lo haremos usando un adaptador de -'authorization'. - -Ya que nuestro requisito es muy sencillo podremos escribir un código también muy -sencillo en nuestro ``BookmarksController``. - -Pero antes necesitamos decirle al componente *AuthComponent* cómo va a autorizar -acciones nuestra aplicación. Para ello añade en ``AppController``:: - - public function isAuthorized($user) - { - return false; - } - -Además añade la siguiente línea a la configuración de ``Auth`` en tu ``AppController``:: - - 'authorize' => 'Controller', - -Tú método ``initialize()`` debería verse así:: - - public function initialize() - { - $this->loadComponent('Flash'); - $this->loadComponent('Auth', [ - 'authorize'=> 'Controller',// línea añadida - 'authenticate' => [ - 'Form' => [ - 'fields' => [ - 'username' => 'email', - 'password' => 'password' - ] - ] - ], - 'loginAction' => [ - 'controller' => 'Users', - 'action' => 'login' - ], - 'unauthorizedRedirect' => $this->referer() - ]); - - // Permite ejecutar la acción display para que nuestros controladores - // de páginas sigan funcionando. - $this->Auth->allow(['display']); - } - -Por defecto denegaremos el acceso siempre y concederemos los accesos donde tenga -sentido. - -Primero añadiremos la lógica de autorización para favoritos. - -En tu ``BookmarksController`` añade lo siguiente:: - - public function isAuthorized($user) - { - $action = $this->request->getParam('action'); - - // Las acciones add e index están siempre permitidas. - if (in_array($action, ['index', 'add', 'tags'])) { - return true; - } - // El resto de acciones requieren un id. - if (!$this->request->getParam('pass.0')) { - return false; - } - - // Comprueba que el favorito pertenezca al usuario actual. - $id = $this->request->getParam('pass.0'); - $bookmark = $this->Bookmarks->get($id); - if ($bookmark->user_id == $user['id']) { - return true; - } - return parent::isAuthorized($user); - } - -Ahora si intentas consultar, editar o borrar un favorito que no te pertenece -deberías ser redirigido a la página desde la que accediste. - -Si no se muestra ningún mensaje de error añade lo siguiente a tu layout:: - - // En templates/layout/default.php - Flash->render() ?> - -Deberías poder ver ahora los mensajes de error de autorización. - -Arreglar lista de consulta y formularios -======================================== - -Mientras que *view* y *delete* están funcionando, *edit*, *add* e *index* presentan un -par de problemas: - -#. Cuando añades un favorito puedes elegir el usuario. -#. Cuando editas un favorito puedes elegir un usuario. -#. La página con el listado muestra favoritos de otros usuarios. - -Abordemos el formulario de añadir favorito primero. - -Para empezar elimina ``input('user_id')`` de **templates/Bookmarks/add.php**. - -Con esa parte eliminada actualizaremos la acción ``add()`` de -**src/Controller/BookmarksController.php** para que luzca así:: - - public function add() - { - $bookmark = $this->Bookmarks->newEntity(); - if ($this->request->is('post')) { - $bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->getData()); - $bookmark->user_id = $this->Auth->user('id'); - if ($this->Bookmarks->save($bookmark)) { - $this->Flash->success('El favorito se ha guardado.'); - return $this->redirect(['action' => 'index']); - } - $this->Flash->error('El favorito podría no haberse guardado. Por favor, inténtalo de nuevo.'); - } - $tags = $this->Bookmarks->Tags->find('list'); - $this->set(compact('bookmark', 'tags')); - $this->set('_serialize', ['bookmark']); - } - -Completando la propiedad de la entidad con datos de la sesión eliminaremos -cualquier posibilidad de que el usuario modifique el usuario al que pertenece -el favorito. Haremos lo mismo para el formulario de edición. - -Tu acción ``edit()`` de **src/Controller/BookmarksController.php** debería ser -así:: - - public function edit($id = null) - { - $bookmark = $this->Bookmarks->get($id, [ - 'contain' => ['Tags'] - ]); - if ($this->request->is(['patch', 'post', 'put'])) { - $bookmark = $this->Bookmarks->patchEntity($bookmark, $this->request->getData()); - $bookmark->user_id = $this->Auth->user('id'); - if ($this->Bookmarks->save($bookmark)) { - $this->Flash->success('El favorito se ha guardado.'); - return $this->redirect(['action' => 'index']); - } - $this->Flash->error('El favorito podría no haberse guardado. Por favor, inténtalo de nuevo.'); - } - $tags = $this->Bookmarks->Tags->find('list'); - $this->set(compact('bookmark', 'tags')); - $this->set('_serialize', ['bookmark']); - } - -Listado consulta ----------------- - -Ahora solo necesitamos mostrar los favoritos del usuario actualmente logueado. - -Podemos hacer eso actualizando la llamada a ``paginate()``. Haz que tu método -``index()`` de **src/Controller/BookmarksController.php** se vea así:: - - public function index() - { - $this->paginate = [ - 'conditions' => [ - 'Bookmarks.user_id' => $this->Auth->user('id'), - ] - ]; - $this->set('bookmarks', $this->paginate($this->Bookmarks)); - $this->set('_serialize', ['bookmarks']); - } - -Deberíamos actualizar también el método ``tags()`` y el método finder relacionado, -pero lo dejaremos como un ejercicio para que lo hagas por tu cuenta. - -Mejorar la experiencia de etiquetado -==================================== - -Ahora mismo añadir nuevos tags es un proceso complicado desde que -``TagsController`` desautorizó todos los accesos. - -En vez de permitirlos podemos mejorar la *UI* para la selección de tags -utilizando un campo de texto separado por comas. Esto proporcionará una mejor -experiencia para nuestros usuarios y usa algunas de las mejores características de *ORM*. - -Añadir un campo calculado -------------------------- - -Para acceder de forma sencilla a las etiquetas formateadas podemos añadir un -campo virtual/calculado a la entidad. - -En **src/Model/Entity/Bookmark.php** añade lo siguiente:: - - use Cake\Collection\Collection; - - protected function _getTagString() - { - if (isset($this->_fields['tag_string'])) { - return $this->_fields['tag_string']; - } - if (empty($this->tags)) { - return ''; - } - $tags = new Collection($this->tags); - $str = $tags->reduce(function ($string, $tag) { - return $string . $tag->title . ', '; - }, ''); - return trim($str, ', '); - } - -Esto nos dará acceso a la propiedad calculada ``$bookmark->tag_string`` que -utilizaremos más adelante. - -Recuerda añadir la propiedad ``tag_string`` a la lista ``_accessible`` en tu -entidad para poder 'guardarla' más adelante. - -En **src/Model/Entity/Bookmark.php** añade ``tag_string`` a ``$_accessible`` de -este modo:: - - protected array $_accessible = [ - 'user_id' => true, - 'title' => true, - 'description' => true, - 'url' => true, - 'user' => true, - 'tags' => true, - 'tag_string' => true, - ]; - -Actualizar las vistas ---------------------- - -Con la entidad actualizada podemos añadir un nuevo campo de entrada para nuestros -tags. En **templates/Bookmarks/add.php** y **templates/Bookmarks/edit.php**, -cambia el campo ``tags._ids`` por el siguiente:: - - echo $this->Form->input('tag_string', ['type' => 'text']); - -Guardar el string de tags -------------------------- - -Ahora que podemos ver los tags existentes como un string querremos guardar -también esa información. - -Al haber marcado ``tag_string`` como accesible el ORM copiará esa información -del request a nuestra entidad. Podemos usar un método de gancho ``beforeSave()`` -para parsear el *string* de etiquetas y encontrar/crear las entidades relacionadas. - -Añade el siguiente código a **src/Model/Table/BookmarksTable.php**:: - - public function beforeSave($event, $entity, $options) - { - if ($entity->tag_string) { - $entity->tags = $this->_buildTags($entity->tag_string); - } - } - - protected function _buildTags($tagString) - { - // Hace trim a las etiquetas - $newTags = array_map('trim', explode(',', $tagString)); - // Elimina las etiquetas vacías - $newTags = array_filter($newTags); - // Elimina las etiquetas duplicadas - $newTags = array_unique($newTags); - - $out = []; - $query = $this->Tags->find() - ->where(['Tags.title IN' => $newTags]); - - // Elimina las etiquetas existentes de la lista de nuevas etiquetas. - foreach ($query->extract('title') as $existing) { - $index = array_search($existing, $newTags); - if ($index !== false) { - unset($newTags[$index]); - } - } - // Añade las etiquetas existentes. - foreach ($query as $tag) { - $out[] = $tag; - } - // Añade las etiquetas nuevas. - foreach ($newTags as $tag) { - $out[] = $this->Tags->newEntity(['title' => $tag]); - } - return $out; - } - -Aunque este código sea algo más complicado de lo que hemos hecho hasta ahora, nos -ayudará a ver lo potente que es el *ORM* en CakePHP. - -Puedes manipular los resultados de la consulta usando los métodos -:doc:`/core-libraries/collections` y manejar escenearios en los que estás -creando entidades *on the fly* con facilidad. - -Para finalizar -============== - -Hemos mejorado nuestra aplicación de favoritos para manejar escenarios de -autenticación y de autorización/control de acceso básicos. - -Además hemos añadido algunas mejoras interesantes de experiencia de usuario -sacándole provecho a *FormHelper* y al potencial de *ORM*. - -Gracias por tomarte tu tiempo para explorar CakePHP. Ahora puedes realizar -el tutorial :doc:`/tutorials-and-examples/blog/blog`, aprender más sobre :doc:`/orm`, -o puedes leer detenidamente los :doc:`/topics`. - -.. meta:: - :title lang=es: Tutorial Bookmarker (Favoritos) - Parte 2 From d2f1fb704c3806fec83572d5a0b2c1c4502e63f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 30 Oct 2023 10:30:37 +0000 Subject: [PATCH 080/337] Update /controllers/components.rst page in EN and ES --- en/controllers/components.rst | 13 +++--- es/controllers/components.rst | 83 +++++++++++++++++------------------ es/intro.rst | 4 +- 3 files changed, 49 insertions(+), 51 deletions(-) diff --git a/en/controllers/components.rst b/en/controllers/components.rst index fb0b6ea190..f428bb9778 100644 --- a/en/controllers/components.rst +++ b/en/controllers/components.rst @@ -25,7 +25,7 @@ Configuring Components ====================== Many of the core components require configuration. One example would be -the :doc:`/controllers/components/form-protection`. Configuration for these components, +the :doc:`/controllers/components/form-protection`. Configuration for these components, and for components in general, is usually done via ``loadComponent()`` in your Controller's ``initialize()`` method or via the ``$components`` array:: @@ -37,9 +37,8 @@ Controller's ``initialize()`` method or via the ``$components`` array:: $this->loadComponent('FormProtection', [ 'unlockedActions' => ['index'], ]); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); } - } You can configure components at runtime using the ``setConfig()`` method. Often, @@ -58,7 +57,7 @@ to read and write configuration data:: $this->FormProtection->getConfig('unlockedActions'); // Set config - $this->Csrf->setConfig('cookieName', 'token'); + $this->Flash->setConfig('key', 'myFlash'); As with helpers, components will automatically merge their ``$_defaultConfig`` property with constructor configuration to create the ``$_config`` property @@ -193,12 +192,12 @@ component, through which we can access an instance of it:: // In a controller // Make the new component available at $this->Math, - // as well as the standard $this->Csrf + // as well as the standard $this->Flash public function initialize(): void { parent::initialize(); $this->loadComponent('Math'); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); } When including Components in a Controller you can also declare a @@ -214,7 +213,7 @@ the Component:: 'precision' => 2, 'randomGenerator' => 'srand', ]); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); } The above would pass the array containing precision and randomGenerator to diff --git a/es/controllers/components.rst b/es/controllers/components.rst index 6f3a53ada1..c4af604468 100644 --- a/es/controllers/components.rst +++ b/es/controllers/components.rst @@ -2,24 +2,20 @@ Componentes ########### Los componentes son paquetes de lógica que se comparten entre los controladores. -CakePHP viene un con fantástico conjunto de componentes básicos que puedes usar +CakePHP viene un con fantástico conjunto de componentes básicos que puedes usar para ayudar en varias tareas comunes. También puedes crear tus propios componentes. Si te encuentras queriendo copiar y pegar cosas entre componentes, deberías considerar crear tu propio componente que contenga la funcionalidad. Crear componentes mantiene el código del controlador limpio y te permite rehusar código entre los diferentes controladores. -Para más información sobre componentes incluidos en CakePHP, consulte el capítulo +Para más información sobre componentes incluidos en CakePHP, consulte el capítulo de cada componente: .. toctree:: :maxdepth: 1 - /controllers/components/authentication /controllers/components/flash - /controllers/components/security - /controllers/components/pagination - /controllers/components/request-handling /controllers/components/form-protection /controllers/components/check-http-cache @@ -28,9 +24,8 @@ de cada componente: Configurando componentes ======================== -Muchos de los componentes principales requieren configuración. Algunos ejemplos -de componentes que requieren configuración son :doc:`/controllers/components/security` -y :doc:`/controllers/components/form-protection`. La configuración para estos +Muchos de los componentes principales requieren configuración. Un ejemplo sería +:doc:`/controllers/components/form-protection`. La configuración para estos componentes, y para los componentes en general, es usualmente hecho a través ``loadComponent()`` en el método ``initialize()`` del controlador o a través del array ``$components``:: @@ -42,9 +37,8 @@ en el método ``initialize()`` del controlador o a través del array ``$componen $this->loadComponent('FormProtection', [ 'unlockedActions' => ['index'], ]); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); } - } También puedes configurar los componentes en tiempo de ejecución usando el método @@ -56,14 +50,14 @@ Lo anterior podría ser también expresado como:: $this->FormProtection->setConfig('unlockedActions', ['index']); } -Al igual que los helpers, componentes implementan los métodos ``getConfig()`` y +Al igual que los helpers, los componentes implementan los métodos ``getConfig()`` y ``setConfig()`` para leer y escribir los datos de configuración:: // Lee los datos de configuración. $this->FormProtection->getConfig('unlockedActions'); // Escribe los datos de configuración - $this->Csrf->setConfig('cookieName', 'token'); + $this->Flash->setConfig('key', 'myFlash'); Al igual que con los helpers, los componentes fusionarán automáticamente su propiedad ``$_defaultConfig`` con la configuración del controlador para crear la propiedad ``$_config`` que es @@ -73,7 +67,7 @@ Componentes de alias -------------------- Una configuración común para usar es la opción ``className``, que te permite utilizar -componentes de alias. Esta característica es útil cuando quieres reemplazar ``$this->Auth`` +componentes de alias. Esta característica es útil cuando quieres reemplazar ``$this->Flash`` u otra referencia común de componente con una implementación personalizada:: // src/Controller/PostsController.php @@ -81,21 +75,21 @@ u otra referencia común de componente con una implementación personalizada:: { public function initialize(): void { - $this->loadComponent('Auth', [ - 'className' => 'MyAuth' + $this->loadComponent('Flash', [ + 'className' => 'MyFlash' ]); } } - // src/Controller/Component/MyAuthComponent.php - use Cake\Controller\Component\AuthComponent; + // src/Controller/Component/MyFlashComponent.php + use Cake\Controller\Component\FlashComponent; - class MyAuthComponent extends AuthComponent + class MyFlashComponent extends FlashComponent { - // Agrega tu código para sobreescribir el AuthComponent principal + // Agrega tu código para sobreescribir el FlashComponent principal } -Lo de arriba haría *alias* ``MyAuthComponent`` a ``$this->Auth`` en tus controladores. +Lo de arriba haría *alias* ``MyFlashComponent`` a ``$this->Flash`` en tus controladores. .. note:: El alias de un componente reemplaza esa instancia en cualquier lugar donde se @@ -105,7 +99,7 @@ Carga de componentes sobre la marcha ------------------------------------ Es posible que no necesites todos tus componentes disponibles en cada acción del -controlador. En situaciones como estas, puedes cargar un componente en tiempo de +controlador. En situaciones como estas, puedes cargar un componente en tiempo de ejecución usando el método ``loadComponent()`` en tu controlador:: // En una acción del controlador @@ -115,7 +109,7 @@ ejecución usando el método ``loadComponent()`` en tu controlador:: .. note:: Ten en cuenta que los componentes cargados sobre la marcha no perderán devoluciones - de llamadas. Si te basas en que las devoluciones de llamada ``beforeFilter`` o + de llamadas. Si te basas en que las devoluciones de llamada ``beforeFilter`` o ``startup`` serán llamadas, necesitarás llamarlas manualmente dependiendo de cuándo cargas tu componente. @@ -123,7 +117,7 @@ Uso de componentes ================== Una vez que hayas incluido algunos componentes a tu controlador, usarlos es bastante -simple. Cada componente que uses se exponen como una propiedad en tu controlador. +simple. Cada componente que uses se exponen como una propiedad en tu controlador. Si cargaste el :php:class:`Cake\\Controller\\Component\\FlashComponent` en tu controlador, puedes acceder a él de esta forma:: @@ -150,6 +144,12 @@ puedes acceder a él de esta forma:: como propiedades, comparten el mismo 'espacio de nombres'. Asegúrate de no dar a un componente y un modelo el mismo nombre. +.. warning:: + + Los métodos de un componente **no** tienen acceso a :doc:`/development/dependency-injection` + como lo tienen los controladores. Usa una clase de servicio dentro de las acciones de tu controlador + en lugar de en el componente si necesitas ésta funcionalidad. + .. _creating-a-component: Creando un componente @@ -159,7 +159,7 @@ Supongamos que nuestra aplicación necesita realizar una operación matemática en muchas partes diferentes de la aplicación. Podríamos crear un componente para albergar esta lógica compartida para su uso en muchos controladores diferentes. -El primer paso es crear un nuevo archivo de componente y clase. Crea el archivo en +El primer paso es crear un nuevo archivo de componente y clase. Crea el archivo en **src/Controller/Component/MathComponent.php**. La estructura básica para el componente debería verse algo como esto:: @@ -184,21 +184,21 @@ Incluyendo tu componente en tus controladores --------------------------------------------- Una vez que nuestro componente está terminado, podemos usarlo en los controladores -de la aplicación cargándolo durante el método ``initialize()`` del controlador. -Una vez cargado, el controlador recibirá un nuevo atributo con el nombre del +de la aplicación cargándolo durante el método ``initialize()`` del controlador. +Una vez cargado, el controlador recibirá un nuevo atributo con el nombre del componente, a través del cual podemos acceder a una instancia del mismo:: // En un controlador // Haz que el nuevo componente esté disponible en $this->Math, - // así como el estándar $this->Csrf + // así como el estándar $this->Flash public function initialize(): void { parent::initialize(); $this->loadComponent('Math'); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); } -Al incluir componentes en un controlador, también puedes declarar un conjunto de +Al incluir componentes en un controlador, también puedes declarar un conjunto de parámetros que se pasarán al constructor del componente. Estos parámetros pueden ser manejados por el componente:: @@ -210,10 +210,10 @@ ser manejados por el componente:: 'precision' => 2, 'randomGenerator' => 'srand' ]); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); } -Lo anterior pasaría el array que contiene precision y randomGenerator a ``MathComponent::initialize()`` +Lo anterior pasaría el array que contiene precision y randomGenerator a ``MathComponent::initialize()`` en el parámetro ``$config``. Usando otros componentes en tu componente @@ -259,13 +259,13 @@ componentes agregándolos a la propiedad `$components`:: .. note:: - A diferencia de un componente incluido en un controlador, no se activarán + A diferencia de un componente incluido en un controlador, no se activarán devoluciones de llamada en el componente de un componente. Accediendo al controlador de un componente ------------------------------------------ -Desde dentro de un componente, puedes acceder al controlador actual a través del +Desde dentro de un componente, puedes acceder al controlador actual a través del registro:: $controller = $this->getController(); @@ -278,22 +278,22 @@ de las solicitudes que les permiten aumentar el ciclo de solicitud. .. php:method:: beforeFilter(EventInterface $event) - Es llamado antes que el método beforeFilter del controlador, pero *después* + Es llamado antes que el método beforeFilter() del controlador, pero *después* del método initialize() del controlador. .. php:method:: startup(EventInterface $event) - Es llamado después del método beforeFilter del controlador, pero antes de que - el controlador ejecute la acción actual del manejador. + Es llamado después del método beforeFilter() del controlador, pero antes de que + el controlador ejecute el "handler" de la acción actual .. php:method:: beforeRender(EventInterface $event) - Es llamado después de que el controlador ejecute la lógica de la acción + Es llamado después de que el controlador ejecute la lógica de la acción solicitada, pero antes de que el controlador renderize las vistas y el diseño. -.. php:method:: shutdown(EventInterface $event) +.. php:method:: afterFilter(EventInterface $event) - Es llamado antes de enviar la salida al navegador. + Es llamado durante el evento ``Controller.shutdown``, antes de enviar la salida al navegador. .. php:method:: beforeRedirect(EventInterface $event, $url, Response $response) @@ -341,5 +341,4 @@ actual. Al generar una ``RedirectException`` puedes incluir encabezados adiciona .. meta:: :title lang=es: Componentes - :keywords lang=es: array controller,core libraries,authentication request,array name,access control lists,public components,controller code,core components,cookiemonster,login cookie,configuration settings,functionality,logic,sessions,cakephp,doc - + :keywords lang=en: array controller,core libraries,array name,access control lists,public components,controller code,core components,cookiemonster,login cookie,configuration settings,functionality,logic,sessions,cakephp,doc diff --git a/es/intro.rst b/es/intro.rst index f1aea892ef..426d7f5a5f 100644 --- a/es/intro.rst +++ b/es/intro.rst @@ -9,7 +9,7 @@ manera conjunta o separada. El objetivo de este artículo es introducirte en los conceptos generales de CakePHP y darte un rápido vistazo sobre como esos conceptos están implementados en CakePHP. Si estás deseando comenzar un proyecto puedes :doc:`empezar con el tutorial -`, o :doc:`profundizar en la documentación +`, o :doc:`profundizar en la documentación `. Convenciones sobre configuración @@ -155,7 +155,7 @@ geniales de CakePHP son: * :doc:`Framework para la ejecución de pruebas integrado ` para que puedas asegurarte de que tu código funciona perfectamente. Los siguientes pasos obvios son :doc:`descargar CakePHP ` -y leer el :doc:`tutorial y crear algo asombroso `. +y leer el :doc:`tutorial y crear algo asombroso `. Lecturas complementarias ======================== From 09888014386e4fdf6d5af9aa8aa86639efd170af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 30 Oct 2023 10:52:48 +0000 Subject: [PATCH 081/337] Added references tutorial pages with the Note that the translation is missing to avoid file referencing errors --- es/quickstart.rst | 7 ++++--- es/tutorials-and-examples.rst | 6 ++++-- es/tutorials-and-examples/cms/articles-controller.rst | 11 +++++++++++ es/tutorials-and-examples/cms/authentication.rst | 11 +++++++++++ es/tutorials-and-examples/cms/authorization.rst | 11 +++++++++++ es/tutorials-and-examples/cms/tags-and-users.rst | 11 +++++++++++ 6 files changed, 52 insertions(+), 5 deletions(-) create mode 100644 es/tutorials-and-examples/cms/articles-controller.rst create mode 100644 es/tutorials-and-examples/cms/authentication.rst create mode 100644 es/tutorials-and-examples/cms/authorization.rst create mode 100644 es/tutorials-and-examples/cms/tags-and-users.rst diff --git a/es/quickstart.rst b/es/quickstart.rst index 75d26113c6..6fe7cb28fe 100644 --- a/es/quickstart.rst +++ b/es/quickstart.rst @@ -5,9 +5,10 @@ La mejor forma de experimentar y aprender CakePHP es sentarse y construir algo. Para empezar crearemos una sencilla aplicación para guardar favoritos. -.. include:: /tutorials-and-examples/bookmarks/intro.rst -.. include:: /tutorials-and-examples/bookmarks/part-two.rst +.. include:: /tutorials-and-examples/cms/installation.rst +.. include:: /tutorials-and-examples/cms/database.rst +.. include:: /tutorials-and-examples/cms/articles-controller.rst .. meta:: :title lang=es: Primeros pasos - :keywords lang=es: estructura de archivos, tabla de nombres, petición inicial, tabla base de datos, estructura organizativa, rst, nomes de archivos, convenciones, mvc, página web, sit + :keywords lang=es: estructura de archivos, tabla de nombres, petición inicial, tabla base de datos, estructura organizativa, rst, nombres de archivos, convenciones, mvc, página web, sit diff --git a/es/tutorials-and-examples.rst b/es/tutorials-and-examples.rst index da09e37e13..05673b4b66 100644 --- a/es/tutorials-and-examples.rst +++ b/es/tutorials-and-examples.rst @@ -15,12 +15,14 @@ para usar. tutorials-and-examples/cms/installation tutorials-and-examples/cms/database + tutorials-and-examples/cms/articles-controller + tutorials-and-examples/cms/tags-and-users + tutorials-and-examples/cms/authentication + tutorials-and-examples/cms/authorization .. toctree:: :maxdepth: 1 - tutorials-and-examples/bookmarks/intro - tutorials-and-examples/bookmarks/part-two tutorials-and-examples/blog/blog tutorials-and-examples/blog/part-two tutorials-and-examples/blog/part-three diff --git a/es/tutorials-and-examples/cms/articles-controller.rst b/es/tutorials-and-examples/cms/articles-controller.rst new file mode 100644 index 0000000000..7fb7106824 --- /dev/null +++ b/es/tutorials-and-examples/cms/articles-controller.rst @@ -0,0 +1,11 @@ +CMS Tutorial - Creating the Articles Controller +======= + +.. note:: + La documentación no es compatible actualmente con el idioma español en esta página. + + Por favor, siéntase libre de enviarnos un pull request en + `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + + Usted puede hacer referencia a la versión en Inglés en el menú de selección superior + para obtener información sobre el tema de esta página. diff --git a/es/tutorials-and-examples/cms/authentication.rst b/es/tutorials-and-examples/cms/authentication.rst new file mode 100644 index 0000000000..575e244a44 --- /dev/null +++ b/es/tutorials-and-examples/cms/authentication.rst @@ -0,0 +1,11 @@ +CMS Tutorial - Authentication +======= + +.. note:: + La documentación no es compatible actualmente con el idioma español en esta página. + + Por favor, siéntase libre de enviarnos un pull request en + `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + + Usted puede hacer referencia a la versión en Inglés en el menú de selección superior + para obtener información sobre el tema de esta página. diff --git a/es/tutorials-and-examples/cms/authorization.rst b/es/tutorials-and-examples/cms/authorization.rst new file mode 100644 index 0000000000..9771257ff8 --- /dev/null +++ b/es/tutorials-and-examples/cms/authorization.rst @@ -0,0 +1,11 @@ +CMS Tutorial - Authorization +======= + +.. note:: + La documentación no es compatible actualmente con el idioma español en esta página. + + Por favor, siéntase libre de enviarnos un pull request en + `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + + Usted puede hacer referencia a la versión en Inglés en el menú de selección superior + para obtener información sobre el tema de esta página. diff --git a/es/tutorials-and-examples/cms/tags-and-users.rst b/es/tutorials-and-examples/cms/tags-and-users.rst new file mode 100644 index 0000000000..0bb5eee32a --- /dev/null +++ b/es/tutorials-and-examples/cms/tags-and-users.rst @@ -0,0 +1,11 @@ +CMS Tutorial - Tags and Users +======= + +.. note:: + La documentación no es compatible actualmente con el idioma español en esta página. + + Por favor, siéntase libre de enviarnos un pull request en + `Github `_ o utilizar el botón **Improve this Doc** para proponer directamente los cambios. + + Usted puede hacer referencia a la versión en Inglés en el menú de selección superior + para obtener información sobre el tema de esta página. From d0d175e57b867b644f80f51ba169f86cf563102a Mon Sep 17 00:00:00 2001 From: Antonio Reveron Date: Mon, 30 Oct 2023 11:17:11 +0000 Subject: [PATCH 082/337] finalizado de traducir la pagina 5-0-migration-guide --- es/appendices/5-0-migration-guide.rst | 261 +++++++++++++------------- 1 file changed, 128 insertions(+), 133 deletions(-) diff --git a/es/appendices/5-0-migration-guide.rst b/es/appendices/5-0-migration-guide.rst index bbc8b4f6d2..5164dfa44b 100644 --- a/es/appendices/5-0-migration-guide.rst +++ b/es/appendices/5-0-migration-guide.rst @@ -70,7 +70,7 @@ Consola Connection ---------- -- Se ha elimiando ``Connection::prepare()``. En su lugar, puede utilizar ``Connection::execute()`` +- Se ha eliminado ``Connection::prepare()``. En su lugar, puede utilizar ``Connection::execute()`` para ejecutar una consulta SQL especificando en la cadena SQL los parámetros y los tipos en una sola llamada. - Se ha eliminado ``Connection::enableQueryLogging()``. Si no ha habilitado el registro a través de la configuración de conexión, puedes configurar más adelante la instancia del registrador para que @@ -126,10 +126,8 @@ Base de datos - ``SqlDialectTrait`` se ha eliminado y toda su funcionalidad se ha movido a la propia clase ``Driver``. - ``CaseExpression`` ha sido eliminado y debe ser reemplazado por ``QueryExpression::case()`` o ``CaseStatementExpression`` -- ``Connection::connect()`` ha sido eliminado. Usa - ``$connection->getDriver()->connect()`` en su lugar. -- ``Connection::disconnect()`` ha sido eliminado. Usa - ``$connection->getDriver()->disconnect()`` en su lugar. +- ``Connection::connect()`` ha sido eliminado. Usar ``$connection->getDriver()->connect()`` en su lugar. +- ``Connection::disconnect()`` ha sido eliminado. Usar ``$connection->getDriver()->disconnect()`` en su lugar. - ``cake.database.queries`` ha sido añadido como alternativa al scope ``queriesLog``. Datasource @@ -140,7 +138,7 @@ Datasource - El método ``aliasField()`` ha sido añadido a ``RepositoryInterface``. Las implementaciones que no son ORM tienen que implementar este método ahora. -Event +Eventos ----- - Las cargas útiles de eventos deben ser un array. Otros objetos como ``ArrayAccess`` ya no se convierten en array y ahora lanzarán un ``TypeError``. @@ -157,7 +155,7 @@ Error Filesystem ---------- -- El paquete de Filesystem ha eliminado, y la clase ``Filesystem`` se ha movido al paquete de Utility. +- El paquete de Filesystem se ha eliminado, y la clase ``Filesystem`` se ha movido al paquete de Utility. Http ---- @@ -169,174 +167,171 @@ Http I18n ---- -- ``FrozenDate`` was renamed to `Date` and ``FrozenTime`` was renamed to `DateTime`. -- ``Time`` now extends ``Cake\Chronos\ChronosTime`` and is therefore immutable. -- ``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``). +- Se cambió el nombre de ``FrozenDate`` a `Date` y el de ``FrozenTime`` a `DateTime`. +- ``Time`` ahora extiende de ``Cake\Chronos\ChronosTime`` y por lo tanto es inmutable. +- ``Date::parseDateTime()`` ha sido eliminado. +- ``Date::parseTime()`` ha sido eliminado. +- ``Date::setToStringFormat()`` y ``Date::setJsonEncodeFormat()`` ya no aceptan un array. +- ``Date::i18nFormat()`` y ``Date::nice()`` ya no aceptan un parámetro de zona horaria. +- Los archivos de traducción en la carpeta de vendor con prefijo como (``FooBar/Awesome``) ahora tendrán + ese prefijo en el nombre del archivo de traducción, por ejemplo, ``foo_bar_awesome.po`` para evitar colisiones + con otro fichero ``awesome.po`` correspondiente con el 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. +- La configuración del motor de registros ahora utiliza ``null`` en lugar de ``false`` para desactivar los scopes. + Así que en lugar de ``'scopes' => false`` necesitas usar ``'scopes' => null`` en la configuración de tu log. Mailer ------ -- ``Email`` has been removed. Use `Mailer `__ instead. -- ``cake.mailer`` has been added as an alternative to the ``email`` scope +- Se ha eliminado ``Email``. Usar `Mailer `__ en su lugar. +- ``cake.mailer`` se ha añadido como alternativa al scope ``email``. 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 +- ``EntityTrait::has()`` ahora devuelve ``true`` cuando existe un atributo y se estable + en ``null``. En versiones anteriores de CakePHP esto devolvía ``false``. + Consulte las notas de la version 4.5.0 para saber como adoptar este comportamiento en 4.x. +- ``EntityTrait::extractOriginal()`` ahora devuelve solo los campos existentes, similar a ``extractOriginalChanged()``. +- Ahora se requiere que los argumentos de un `Finder` sean arrays asociativos, como siempre se esperó que fueran. +- ``TranslateBehavior`` ahora tiene como valor predeterminado la estrategia ``ShadowTable``. Si está + utilizando la estrategia ``Eav`` deberá actualizar la configuración de tu behavior para conservar + el comportamiento anterior. +- La opción ``allowMultipleNulls`` para la regla ``isUnique`` ahora es true de forma predeterminada, + coincidiendo con el comportamiento original de 3.x. +- ``Table::query()`` se ha eliminado en favor de funciones específicas de tipo de consulta. +- ``Table::updateQuery()``, ``Table::selectQuery()``, ``Table::insertQuery()``, y + ``Table::deleteQuery()`` se añadieron y ahora devuelven los nuevos objetos de consulta de tipo especifico. +- Se añadieron ``SelectQuery``, ``InsertQuery``, ``UpdateQuery`` y ``DeleteQuery`` que representan + solo un tipo de consulta y no permiten cambiar entre tipos de consulta, sin llamar a funciones no relacionadas + con el tipo de consulta especifico. +- ``Table::_initializeSchema()`` ha sido eliminado y debe ser reemplazado llamando a + ``$this->getSchema()`` dentro del método ``initialize()``. +- ``SaveOptionsBuilder`` ha sido eliminado. En su lugar, utilice un array normal para las opciones. + +Enrutamiento ------- -- 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. +- Los métodos estáticos ``connect()``, ``prefix()``, ``scope()`` y ``plugin()`` del ``Router`` han sido eliminados y + deben ser reemplazados llamando a sus variantes de método no estáticos a través de la instancia ``RouteBuilder``. +- ``RedirectException`` ha sido eliminado. Usar ``\Cake\Http\Exception\RedirectException`` en su lugar. 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. +- ``TestSuite`` fue eliminado. En su lugar, los usuarios deben usar variables de entorno + para personalizar la configuración de las pruebas unitarias. +- ``TestListenerTrait`` fue eliminado. PHPUnit dejó de dar soporte a estos listeners. + Ver documentación :doc:`/appendices/phpunit10` +- ``IntegrationTestTrait::configRequest()`` ahora fusiona la configuración cuando se llama varias + veces en lugar de reemplazar la configuración actualmente presente. -Validation +Validaciones ---------- -- ``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\```. +- ``Validation::isEmpty()`` ya no es compatible con la subida de ficheros en forma + arrays. El soporte para la subida de ficheros en forma de array también se ha eliminado de + ``ServerRequest`` por lo que no debería ver esto como un problema fuera de las pruebas. +- Anteriormente, la mayoría de los mensajes de error de validacion de datos eran simplemente ``El valor proporcionado no es válido``. + Ahora, los mensajes de error de validación de datos están redactados con mayor precisión. + Por ejemplo, ``El valor proporcionado debe ser mayor o igual que \`5\```. -View +Vistas ---- -- ``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 +- Las opciones de ``ViewBuilder`` ahora son verdaderamente asociativas (string keys). +- ``NumberHelper`` y ``TextHelper`` ya no aceptan la configuración de ``engine``. +- ``ViewBuilder::setHelpers()`` el parámetro ``$merge`` fue eliminado. Usar ``ViewBuilder::addHelpers()`` en su lugar. +- Dentro ``View::initialize()``, preferentemente usar ``addHelper()`` en lugar de ``loadHelper()``. + De todas formas, todas las configuraciones de helpers se cargarán después. +- ``View\Widget\FileWidget`` ya no es compatible con la subida de ficheros en forma + arrays. Esto esta alineado con los cambios en ``ServerRequest`` y ``Validation``. +- ``FormHelper`` ya no estable ``autocomplete=off`` en los campos de token CSRF. Esto + fue una solución para un error de Safari que no es relevante. + +Obsolescencias ============ -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. +A continuación se muestra una lista de métodos, propiedades y comportamientos en desuso. Estas +características seguirán funcionando en la versión 5.x y se eliminarán en la versión 6.0. -Database +Base de datos -------- -- ``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. +- ``Query::order()`` ha quedado obsoleto. Utiliza ``Query::orderBy()`` en su lugar + ahora que los métodos ``Connection`` ya no son proxy. Esto alinea el nombre de la función + con la instrucción SQL. +- ``Query::group()`` ha quedado obsoleto. Utiliza ``Query::groupBy()`` en su lugar + ahora que los métodos ``Connection`` ya no son proxy. Esto alinea el nombre de la función + con la instrucción SQL. 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)``. +- Llamar a ``Table::find()`` con opciones de array esta obsoleto. Utiliza `named arguments `__ + en su lugar. Por ejemplo, en lugar de ``find('all', ['conditions' => $array])`` usar + ``find('all', conditions: $array)``. De manera similar, para las opciones de finders personalizados, en lugar + de ``find('list', ['valueField' => 'name'])`` usar ``find('list', valueField: 'name')`` + o varios argumentos como ``find(type: 'list', valueField: 'name', conditions: $array)``. -New Features +Nuevas características ============ -Improved type checking +Comprobación de tipos mejorada ----------------------- -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. +CakePHP 5 aprovecha la función de sistema de tipos expandidos disponible en PHP 8.1+. +CakePHP también usa ``assert()`` para proporcionar mensajes de error mejorados y una solidez de tipo adicional. +En el modo de producción, puede configurar PHP para que no genere código para ``assert()`` lo que mejora el rendimiento de la aplicación. +Consulte :ref:`symlink-assets` para saber cómo hacerlo. -Collection +Colecciones ---------- -- 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()`` +- Se añadió ``unique()`` que filtra el valor duplicado especificado por la devolución de llamada proporcionada. +- ``reject()`` ahora soporta una devolución de llamada predeterminada que filtra los valores verdaderos, + que es el inverso del comportamiento predeterminado de ``filter()`` Core ---- -- The ``services()`` method was added to ``PluginInterface``. -- ``PluginCollection::addFromConfig()`` has been added to :ref:`simplify plugin loading `. +- El método ``services()`` se añadió a ``PluginInterface``. +- ``PluginCollection::addFromConfig()`` se ha añadido a :ref:`simplify plugin loading `. -Database +Base de datos -------- -- ``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. +- ``ConnectionManager`` ahora soporta roles de conexión de lectura y escritura. Los roles se pueden configurar + con claves de ``read`` y ``write`` en la configuración de conexión que anulan la configuración compartida. +- Se añadió ``Query::all()`` que ejecuta devoluciones de llamada del decorador de resultados y devuelve un conjunto de resultados para consultas seleccionadas. +- Se añadió ``Query::comment()`` para agregar un comentario SQL a la consulta ejecutada. Esto facilita la depuración de consultas. +- ``EnumType`` fue añadido para permitir el mapeo entre enumeraciones respaldadas por PHP y una cadena o columna entera. +- ``getMaxAliasLength()`` y ``getConnectionRetries()`` se añadieron a ``DriverInterface``. +- Los drivers compatibles ahora agregan automáticamente el incremento automático solo a las claves primarias enteras denominadas "id" + en lugar de a todas las claves primarias enteras. Si se establece 'autoIncrement' en false, siempre se deshabilita en todos los drivers compatibles. 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. +- Se ha añadido soporte para 'factories interface' `PSR-17 `__. + Esto permite ``cakephp/http`` proporcionar una implementación de cliente a + bibliotecas que permiten la resolución automática de interfaces como php-http. +- Se añadieron ``CookieCollection::__get()`` y ``CookieCollection::__isset()`` para añadir + formas ergonómicas de acceder a las cookies sin excepciones. ORM --- -Required Entity Fields +Campos de entidad obligatorios ---------------------- -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:: +Las entidades tienen una nueva funcionalidad de opt-in que permite hacer que las entidades manejen +propiedades de manera más estricta. El nuevo comportamiento se denomina 'required fields'. Cuando +es habilitado, el acceso a las propiedades que no están definidas en la entidad generará +excepciones. Esto afecta a los siguientes usos:: $entity->get(); $entity->has(); @@ -344,17 +339,17 @@ exceptions. This impacts the following usage:: 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. +Los campos se consideran definidos si pasan ``array_key_exists``. Esto incluye +valores nulos. Debido a que esta puede ser una característica tediosa de habilitar, se aplazó a +5.0. Nos gustaría recibir cualquier comentario que tenga sobre esta función, +ya que estamos considerando hacer que este sea el comportamiento predeterminado en el futuro. 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:: +Los finders de las tablas ahora pueden tener argumentos escritos según sea necesario en lugar de un array de opciones. +Por ejemplo, un finder para obtener publicaciones por categoría o usuario:: public function findByCategoryOrUser(SelectQuery $query, array $options) { @@ -368,7 +363,7 @@ For e.g. a finder for fetching posts by category or user:: return $query; } -can now be written as:: +ahora se pueden escribir como:: public function findByCategoryOrUser(SelectQuery $query, ?int $categoryId = null, ?int $userId = null) { @@ -382,11 +377,11 @@ can now be written as:: 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. +El finder puede ser llamado como ``find('byCategoryOrUser', userId: $somevar)``. +Incluso puedes incluir los argumentos con nombre especial para establecer cláusulas de consulta. ``find('byCategoryOrUser', userId: $somevar, conditions: ['enabled' => true])``. -A similar change has been applied to the ``RepositoryInterface::get()`` method:: +Un cambio similar se ha aplicado al método ``RepositoryInterface::get()``:: public function view(int $id) { @@ -396,7 +391,7 @@ A similar change has been applied to the ``RepositoryInterface::get()`` method:: ]); } -can now be written as:: +ahora se pueden escribir como:: public function view(int $id) { @@ -406,13 +401,13 @@ can now be written as:: TestSuite --------- -- ``IntegrationTestTrait::requestAsJson()`` has been added to set JSON headers for the next request. +- Se ha añadido ``IntegrationTestTrait::requestAsJson()`` para establecer encabezados JSON para la siguiente solicitud. -Plugin Installer +Instalador de plugins ---------------- -- 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``. +- El instalador de plugins se ha actualizado para manejar automáticamente la carga automática de clases para los plugins + de tu aplicación. Por lo tanto, puede eliminar el espacio de nombres para las asignaciones de rutas para + tus plugins de tu ``composer.json`` y simplemente ejecutar ``composer dumpautoload``. .. meta:: :title lang=es: 5.0 Guía de migración From 6f8f062189a154cc6d095881b9f34da40ab5678e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 30 Oct 2023 11:51:38 +0000 Subject: [PATCH 083/337] Update /controllers.rst page in EN and ES --- en/controllers.rst | 10 +-- es/controllers.rst | 169 +++++++++++++++++++++++++++------------------ 2 files changed, 107 insertions(+), 72 deletions(-) diff --git a/en/controllers.rst b/en/controllers.rst index e23efdff7d..7061c7502b 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -68,8 +68,8 @@ is invoked at the end of a Controller's constructor for this kind of use:: { public function initialize(): void { - // Always enable the CSRF component. - $this->loadComponent('Csrf'); + // Always enable the FormProtection component. + $this->loadComponent('FormProtection'); } } @@ -320,8 +320,8 @@ actions, you can define that logic within ``viewClasses()``:: return [JsonView::class]; } -If within your controller actions you need to process request or load data -differently based on the controller action you can use +If within your controller actions you need to process the request or load data +differently based on the content type you can use :ref:`check-the-request`:: // In a controller action @@ -492,7 +492,7 @@ want loaded, and any configuration data for them:: public function initialize(): void { parent::initialize(); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); $this->loadComponent('Comments', Configure::read('Comments')); } diff --git a/es/controllers.rst b/es/controllers.rst index 0e993037f2..3e0d8b6e80 100644 --- a/es/controllers.rst +++ b/es/controllers.rst @@ -5,38 +5,38 @@ Controladores .. php:class:: Controller -Los controladores son la 'C' en MVC. Después de aplicar el enrutamiento y +Los controladores son la 'C' en MVC. Después de aplicar el enrutamiento y que el controlador ha sido encontrado, la acción de tu controlador es llamado. Tu controlador -debe manejar la interpretación de los datos de la solicitud, +debe manejar la interpretación de los datos de la solicitud, asegurándose de que se llamen -a los modelos correctos y se muestre la respuesta o vista correcta. +a los modelos correctos y se muestre la respuesta o vista correcta. Los controladores se pueden considerar como una capa intermedia entre el Modelo y la Vista. Quieres mantener -tus controladores delgados, y tus modelos gruesos. +tus controladores delgados, y tus modelos gruesos. Esto te ayudará a reutilizar tu código y lo hará mas fácil de probar. -Comúnmente, un controlador se usa para administrar la lógica en torno +Comúnmente, un controlador se usa para administrar la lógica en torno a un solo modelo. Por -ejemplo, si estuvieras construyendo un sitio online para una panadería, +ejemplo, si estuvieras construyendo un sitio online para una panadería, podrías tener un -RecipesController que gestiona tus recetas y un IngredientsController +RecipesController que gestiona tus recetas y un IngredientsController que gestiona tus -ingredientes. Sin embargo, es posible hacer que los controladores trabajen -con más de +ingredientes. Sin embargo, es posible hacer que los controladores trabajen +con más de un modelo. En CakePHP, un controlador es nombrado a raíz del modelo que maneja. Los controladores de tu aplicación extienden de la clase ``AppController``, que a su vez extiende de la clase principal :php:class:`Controller`. La clase ``AppController`` puede ser definida en **src/Controller/AppController.php** -y debería contener los métodos que se comparten entre todos los controladores +y debería contener los métodos que se comparten entre todos los controladores de tu aplicación. Los controladores proveen una serie de métodos que manejan las peticiones. Estos son llamadas *acciones*. Por defecto, cada método público en un controlador es -una acción, y es accesible mediante una URL. Una acción es responsable de +una acción, y es accesible mediante una URL. Una acción es responsable de interpretar la petición y crear la respuesta. Por lo general, las respuestas -son de la forma de una vista renderizada, pero también, hay otras maneras de crear +son de la forma de una vista renderizada, pero también, hay otras maneras de crear respuestas. .. _app-controller: @@ -44,10 +44,10 @@ respuestas. El App Controller ================== -Como se indicó en la introducción, la clase ``AppController`` es clase padre de +Como se indicó en la introducción, la clase ``AppController`` es clase padre de todos los controladores de tu aplicación. ``AppController`` extiende de la clase :php:class:`Cake\\Controller\\Controller` que está incluida en CakePHP. -``AppController`` se define en **src/Controller/AppController.php** como se +``AppController`` se define en **src/Controller/AppController.php** como se muestra a continuación:: namespace App\Controller; @@ -58,7 +58,7 @@ muestra a continuación:: { } -Los atributos y métodos del controlador creados en tu ``AppController`` van a +Los atributos y métodos del controlador creados en tu ``AppController`` van a estar disponibles en todos los controladores que extiendan de este. Los componentes (que aprenderás más adelante) son mejor usados para código que se encuentra en muchos (pero no necesariamente en todos) los componentes. @@ -66,7 +66,7 @@ encuentra en muchos (pero no necesariamente en todos) los componentes. Puedes usar tu ``AppController`` para cargar componentes que van a ser utilizados en cada controlador de tu aplicación. CakePHP proporciona un método ``initialize()`` que es llamado al final del constructor de un controlador para este tipo de uso:: - + namespace App\Controller; use Cake\Controller\Controller; @@ -75,19 +75,20 @@ que es llamado al final del constructor de un controlador para este tipo de uso: { public function initialize(): void { - // Siempre habilita el componente CSRF. - $this->loadComponent('Csrf'); + // Always enable the FormProtection component. + $this->loadComponent('FormProtection'); } } + Flujo de solicitud ================== -Cuando se realiza una solicitud a una aplicación CakePHP, las clases CakePHP +Cuando se realiza una solicitud a una aplicación CakePHP, las clases CakePHP :php:class:`Cake\\Routing\\Router` y :php:class:`Cake\\Routing\\Dispatcher` -usan :ref:`routes-configuration` para encontrar y crear la instancia correcta -del controlador. Los datos de la solicitud son encapsulados en un objeto de -solicitud. CakePHP pone toda la información importante de la solicitud en la +usan :ref:`routes-configuration` para encontrar y crear la instancia correcta +del controlador. Los datos de la solicitud son encapsulados en un objeto de +solicitud. CakePHP pone toda la información importante de la solicitud en la propiedad ``$this->request``. Consulta la sección sobre :ref:`cake-request` para obtener más información sobre el objeto de solicitud de CakePHP. @@ -95,14 +96,14 @@ Acciones del controlador ======================== Las acciones del controlador son las responsables de convertir los parámetros -de la solicitud en una respuesta para el navegador/usuario que realiza la +de la solicitud en una respuesta para el navegador/usuario que realiza la petición. CakePHP usa convenciones para automatizar este proceso y eliminar algunos códigos repetitivos que de otro modo se necesitaría escribir. -Por convención, CakePHP renderiza una vista con una versión en infinitivo del nombre -de la acción. Volviendo a nuestro ejemplo de la panadería online, nuestro -RecipesController podría contener las acciones ``view()``, ``share()``, y -``search()``. El controlador sería encontrado en +Por convención, CakePHP renderiza una vista con una versión en infinitivo del nombre +de la acción. Volviendo a nuestro ejemplo de la panadería online, nuestro +RecipesController podría contener las acciones ``view()``, ``share()``, y +``search()``. El controlador sería encontrado en **src/Controller/RecipesController.php** y contiene:: // src/Controller/RecipesController.php @@ -139,7 +140,7 @@ CakePHP se encargará de renderizar y entregar la vista. Si por algún motivo deseas omitir el comportamiento predeterminado, puedes retornar un objeto :php:class:`Cake\\Http\\Response` de la acción con la respuesta creada. -Para que puedas usar un controlador de manera efectiva en tu aplicación, +Para que puedas usar un controlador de manera efectiva en tu aplicación, cubriremos algunos de los atributos y métodos principales proporcionados por los controladores de CakePHP. @@ -148,7 +149,7 @@ Interactuando con vistas Los controladores interactúan con las vistas de muchas maneras. Primero, los controladores son capaces de pasar información a las vistas, usando ``Controller::set()``. -También puedes decidir qué clase de vista usar, y qué archivo de vista debería +También puedes decidir qué clase de vista usar, y qué archivo de vista debería ser renderizado desde el controlador. .. _setting-view_variables: @@ -158,7 +159,7 @@ Configuración de variables de vista .. php:method:: set(string $var, mixed $value) -El método ``Controller::set()`` es la manera principal de mandar información +El método ``Controller::set()`` es la manera principal de mandar información desde el controlador a la vista. Una vez que hayas utilizado ``Controller::set()``, la variable puede ser accedida en tu vista:: @@ -172,13 +173,13 @@ la variable puede ser accedida en tu vista:: Has seleccionado cubierta para la tarta. El método ``Controller::set()`` también toma un array asociativo como su primer -parámetro. A menudo, esto puede ser una forma rápida de asignar un conjunto de +parámetro. A menudo, esto puede ser una forma rápida de asignar un conjunto de información a la vista:: $data = [ 'color' => 'pink', 'type' => 'sugar', - 'base_price' => 23.95 + 'base_price' => 23.95, ]; // Hace $color, $type, y $base_price @@ -218,7 +219,7 @@ coloca la vista dentro de su ``View::$layout``, y lo devuelve al usuario final. El archivo de vista por defecto utilizado para el renderizado es definido por convención. -Si la acción ``search()`` de RecipesController es solicitada, el archivo vista en +Si la acción ``search()`` de RecipesController es solicitada, el archivo vista en **templates/Recipes/search.php** será renderizado:: namespace App\Controller; @@ -234,8 +235,8 @@ Si la acción ``search()`` de RecipesController es solicitada, el archivo vista // ... } -Aunque CakePHP va a llamarlo automáticamente después de cada acción de lógica -(a menos que llames a ``$this->disableAutoRender()``), puedes usarlo para +Aunque CakePHP va a llamarlo automáticamente después de cada acción de lógica +(a menos que llames a ``$this->disableAutoRender()``), puedes usarlo para especificar un archivo de vista alternativo especificando el nombre de este como primer argumento del método ``Controller::render()``. @@ -254,7 +255,7 @@ Renderizando una plantilla específica En tu controlador, puede que quieras renderizar una vista diferente a la que es convencional. Puedes hacer esto llamando a ``Controller::render()`` directamente. -Una vez que hayas llamado a ``Controller::render()``, CakePHP no tratará de +Una vez que hayas llamado a ``Controller::render()``, CakePHP no tratará de re-renderizar la vista:: namespace App\Controller; @@ -267,7 +268,7 @@ re-renderizar la vista:: } } -Esto renderizará **templates/Posts/custom_file.php** en vez de +Esto renderizará **templates/Posts/custom_file.php** en vez de **templates/Posts/my_action.php**. También puedes renderizar vistas dentro de plugins usando la siguiente sintaxis: @@ -292,10 +293,10 @@ Negociación del tipo de contenido .. php:method:: viewClasses() -Los controladores pueden definir una lista de clases de vistas que soportan. -Después de que la acción del controlador este completa, CakePHP usará la lista de +Los controladores pueden definir una lista de clases de vistas que soportan. +Después de que la acción del controlador este completa, CakePHP usará la lista de vista para realizar negociación del tipo de contenido. Esto permite a tu aplicación -rehusar la misma acción del controlador para renderizar una vista HTML o +rehusar la misma acción del controlador para renderizar una vista HTML o renderizar una respuesta JSON o XML. Para definir la lista de clases de vista que soporta un controlador se utiliza el método ``viewClasses()``:: @@ -314,9 +315,33 @@ soporta un controlador se utiliza el método ``viewClasses()``:: La clase ``View`` de la aplicación se usa automáticamente como respaldo cuando no se puede seleccionar otra vista en función del encabezado de la petición ``Accept`` -o de la extensión del enrutamiento. Si tu aplicación necesita realizar una lógica -diferente para diferente formatos de respuesta puedes usar ``$this->request->is()`` -para construir la lógica condicional requerida. +o de la extensión del enrutamiento. Si tu aplicación sólo soporta tipos de contenido +para una acción específica, puedes definir esa lógica dentro de ``viewClasses()``:: + + public function viewClasses(): array + { + if ($this->request->getParam('action') === 'export') { + // Usa una vista CSV personalizada para exportación de datos + return [CsvView::class]; + } + + return [JsonView::class]; + } + +Si dentro de las acciones de tu controlador necesitas procesar la petición o cargar datos +de forma diferente dependiendo del tipo de contenido puedes usar +:ref:`check-the-request`:: + + // En la acción de un controlador + + // Carga información adicional cuando se preparan respuestas JSON + if ($this->request->is('json')) { + $query->contain('Authors'); + } + +También puedes definir las clases View soportadas por tu controlador usando +el método ``addViewClasses()`` que unirá la vista proporcionada con +aquellas que están actualmente en la propiedad ``viewClasses``. .. note:: Las clases de vista deben implementar el método estático ``contentType()`` @@ -352,12 +377,9 @@ de vista alternativa:: } -Es importante recordar que las vistas coincidentes se aplican sólo *después* de +Es importante recordar que las vistas coincidentes se aplican sólo *después* de intentar la negociación del tipo de contenido. -.. versionadded:: 4.4.0 - Anterior a 4.4 debes usar :doc:`/controllers/components/request-handling` - en vez de ``viewClasses()``. Redirigiendo a otras páginas ============================ @@ -416,16 +438,30 @@ nombrada acción:: Cargando modelos adicionales ============================ +.. php:method:: fetchModel(string $alias, array $config = []) + +La función ``fetchModel()`` es útil cuando se necesita cargar un modelo o tabla del ORM que +no es la predeterminada por el controlador. Modelos obtenidos de ésta manera no serán seteados +como propiedades en el controlador:: + + // Obtiene un modelo de ElasticSearch + $articles = $this->fetchModel('Articles', 'Elastic'); + + // Obtiene un modelo de webservice + $github = $this->fetchModel('GitHub', 'Webservice'); + +.. versionadded:: 4.5.0 + .. php:method:: fetchTable(string $alias, array $config = []) -La función ``fetchTable()`` es útil cuando se necesita usar una tabla que no es +La función ``fetchTable()`` es útil cuando se necesita usar una tabla del ORM que no es la predeterminada por el controlador:: // En un método del controlador. - $recentArticles = $this->fetchTable('Articles')->find('all', [ - 'limit' => 5, - 'order' => 'Articles.created DESC' - ]) + $recentArticles = $this->fetchTable('Articles')->find('all', + limit: 5, + order: 'Articles.created DESC' + ) ->all(); .. versionadded:: 4.3.0 @@ -438,16 +474,18 @@ Paginación de un modelo Este método se utiliza para paginar los resultados obtenidos por tus modelos. Puedes especificar tamaño de páginas, condiciones de búsqueda del modelo y más. +Ve a la sección :doc:`pagination ` para más detalles +sobre como usar ``paginate()``. -El atributo ``$paginate`` te da una manera de personalizar cómo ``paginate()`` +El atributo ``$paginate`` te da una manera de personalizar cómo ``paginate()`` se comporta:: class ArticlesController extends AppController { - public $paginate = [ + protected array $paginate = [ 'Articles' => [ - 'conditions' => ['published' => 1] - ] + 'conditions' => ['published' => 1], + ], ]; } @@ -462,7 +500,7 @@ que deseas cargar, y cualquier dato de configuración para ellos:: public function initialize(): void { parent::initialize(); - $this->loadComponent('Csrf'); + $this->loadComponent('Flash'); $this->loadComponent('Comments', Configure::read('Comments')); } @@ -486,24 +524,24 @@ Lista de eventos Métodos de callback del controlador ================================================ -Por defecto, los siguientes métodos de callback están conectados a +Por defecto, los siguientes métodos de callback están conectados a eventos relacionados si los métodos son implementados por tus controladores. .. php:method:: beforeFilter(EventInterface $event) Llamado durante el evento ``Controller.initialize`` que ocurre antes de cada - acción en el controlador. Es un lugar útil para comprobar si hay una sesión + acción en el controlador. Es un lugar útil para comprobar si hay una sesión activa o inspeccionar los permisos del usuario. .. note:: El método beforeFilter() será llamado por acciones faltantes. - + Devolver una respuesta del método ``beforeFilter`` no evitará que otros oyentes del mismo evento sean llamados. Debes explícitamente parar el evento. .. php:method:: beforeRender(EventInterface $event) - Llamado durante el evento ``Controller.beforeRender`` que ocurre después + Llamado durante el evento ``Controller.beforeRender`` que ocurre después de la lógica de acción del controlador, pero antes de que la vista sea renderizada. Este callback no se usa con frecuencia, pero puede ser necesaria si estas llamando :php:meth:`~Cake\\Controller\\Controller::render()` de forma @@ -515,7 +553,7 @@ eventos relacionados si los métodos son implementados por tus controladores. de cada acción del controlador, y después de que se complete el renderizado. Este es el último método del controlador para ejecutar. -Además de las devoluciones de llamada del ciclo de vida del controlador, +Además de las devoluciones de llamada del ciclo de vida del controlador, :doc:`/controllers/components` también proporciona un conjunto similar de devoluciones de llamada. @@ -535,9 +573,9 @@ Middleware del controlador .. php:method:: middleware($middleware, array $options = []) -:doc:`Middleware ` puede ser definido globalmente, en +:doc:`Middleware ` puede ser definido globalmente, en un ámbito de enrutamiento o dentro de un controlador. Para definir el middleware -para un controlador en específico usa el método ``middleware()`` de tu método +para un controlador en específico usa el método ``middleware()`` de tu método ``initialize()`` del controlador:: public function initialize(): void @@ -555,9 +593,6 @@ para un controlador en específico usa el método ``middleware()`` de tu métod El middleware definido por un controlador será llamado **antes** ``beforeFilter()`` y se llamarán a los métodos de acción. -.. versionadded:: 4.3.0 - ``Controller::middleware()`` fue agregado. - Más sobre controladores ======================= From f7f520ff6deb709d6b2ebfb820632fbe58189c28 Mon Sep 17 00:00:00 2001 From: Antonio Reveron Date: Mon, 30 Oct 2023 12:59:02 +0000 Subject: [PATCH 084/337] fix multiple warnings Title underline too short --- es/appendices/5-0-migration-guide.rst | 32 +++++++++++++-------------- es/appendices/5-0-upgrade-guide.rst | 12 +++++----- es/appendices/migration-guides.rst | 2 +- es/appendices/phpunit10.rst | 10 ++++----- 4 files changed, 28 insertions(+), 28 deletions(-) diff --git a/es/appendices/5-0-migration-guide.rst b/es/appendices/5-0-migration-guide.rst index 5164dfa44b..fd91c2fb5e 100644 --- a/es/appendices/5-0-migration-guide.rst +++ b/es/appendices/5-0-migration-guide.rst @@ -1,5 +1,5 @@ 5.0 Guía de migración -################### +##################### CakePHP 5.0 contiene cambios importantes, y no es compatible con versiones anteriores de 4.x. Antes de intentar actualizar a la version 5.0, primero actualice a la version 4.5 y resuelva @@ -9,13 +9,13 @@ Consulte :doc:`/appendices/5-0-upgrade-guide` para obtener instrucciones paso a como actualizar a la versión 5.0. Características obsoletas eliminadas -=========================== +==================================== Todos los métodos, propiedades y funcionalidades que emitían advertencias de obsolencias a partir de la versión 4.5 se han eliminado. Cambios importantes -================ +=================== Además de la eliminación de características obsoletas, se han realizado cambios importantes: @@ -110,7 +110,7 @@ Core - ``ClassLoader`` ha sido eliminado. En su lugar, utiliza composer para generar archivos de carga automática. Base de datos --------- +------------- - ``DateTimeType`` y ``DateType`` ahora siempre devuelven objetos inmutables. Además, la interfaz para los objetos ``Date`` refleja la interfaz ``ChronosDate`` @@ -139,7 +139,7 @@ Datasource tienen que implementar este método ahora. Eventos ------ +------- - Las cargas útiles de eventos deben ser un array. Otros objetos como ``ArrayAccess`` ya no se convierten en array y ahora lanzarán un ``TypeError``. - Se recomienda ajustar los handlers de eventos para que sean métodos void y usar ``$event->setResult()`` en lugar de devolver el resultado. @@ -213,7 +213,7 @@ ORM - ``SaveOptionsBuilder`` ha sido eliminado. En su lugar, utilice un array normal para las opciones. Enrutamiento -------- +------------ - Los métodos estáticos ``connect()``, ``prefix()``, ``scope()`` y ``plugin()`` del ``Router`` han sido eliminados y deben ser reemplazados llamando a sus variantes de método no estáticos a través de la instancia ``RouteBuilder``. @@ -230,7 +230,7 @@ TestSuite veces en lugar de reemplazar la configuración actualmente presente. Validaciones ----------- +------------ - ``Validation::isEmpty()`` ya no es compatible con la subida de ficheros en forma arrays. El soporte para la subida de ficheros en forma de array también se ha eliminado de @@ -240,7 +240,7 @@ Validaciones Por ejemplo, ``El valor proporcionado debe ser mayor o igual que \`5\```. Vistas ----- +------ - Las opciones de ``ViewBuilder`` ahora son verdaderamente asociativas (string keys). - ``NumberHelper`` y ``TextHelper`` ya no aceptan la configuración de ``engine``. @@ -253,13 +253,13 @@ Vistas fue una solución para un error de Safari que no es relevante. Obsolescencias -============ +============== A continuación se muestra una lista de métodos, propiedades y comportamientos en desuso. Estas características seguirán funcionando en la versión 5.x y se eliminarán en la versión 6.0. Base de datos --------- +------------- - ``Query::order()`` ha quedado obsoleto. Utiliza ``Query::orderBy()`` en su lugar ahora que los métodos ``Connection`` ya no son proxy. Esto alinea el nombre de la función @@ -278,10 +278,10 @@ ORM o varios argumentos como ``find(type: 'list', valueField: 'name', conditions: $array)``. Nuevas características -============ +====================== Comprobación de tipos mejorada ------------------------ +------------------------------ CakePHP 5 aprovecha la función de sistema de tipos expandidos disponible en PHP 8.1+. CakePHP también usa ``assert()`` para proporcionar mensajes de error mejorados y una solidez de tipo adicional. @@ -289,7 +289,7 @@ En el modo de producción, puede configurar PHP para que no genere código para Consulte :ref:`symlink-assets` para saber cómo hacerlo. Colecciones ----------- +----------- - Se añadió ``unique()`` que filtra el valor duplicado especificado por la devolución de llamada proporcionada. - ``reject()`` ahora soporta una devolución de llamada predeterminada que filtra los valores verdaderos, @@ -302,7 +302,7 @@ Core - ``PluginCollection::addFromConfig()`` se ha añadido a :ref:`simplify plugin loading `. Base de datos --------- +------------- - ``ConnectionManager`` ahora soporta roles de conexión de lectura y escritura. Los roles se pueden configurar con claves de ``read`` y ``write`` en la configuración de conexión que anulan la configuración compartida. @@ -326,7 +326,7 @@ ORM --- Campos de entidad obligatorios ----------------------- +------------------------------ Las entidades tienen una nueva funcionalidad de opt-in que permite hacer que las entidades manejen propiedades de manera más estricta. El nuevo comportamiento se denomina 'required fields'. Cuando @@ -404,7 +404,7 @@ TestSuite - Se ha añadido ``IntegrationTestTrait::requestAsJson()`` para establecer encabezados JSON para la siguiente solicitud. Instalador de plugins ----------------- +--------------------- - El instalador de plugins se ha actualizado para manejar automáticamente la carga automática de clases para los plugins de tu aplicación. Por lo tanto, puede eliminar el espacio de nombres para las asignaciones de rutas para tus plugins de tu ``composer.json`` y simplemente ejecutar ``composer dumpautoload``. diff --git a/es/appendices/5-0-upgrade-guide.rst b/es/appendices/5-0-upgrade-guide.rst index 44e75c798d..f6e444e81d 100644 --- a/es/appendices/5-0-upgrade-guide.rst +++ b/es/appendices/5-0-upgrade-guide.rst @@ -1,10 +1,10 @@ 5.0 Guía de actualización -################# +######################### En primer lugar, compruebe que su aplicación se está ejecutando en la última versión de CakePHP 4.x. Arreglar avisos de obsolescencia -======================== +================================ Una vez que su aplicación se ejecuta en la última version de CakePHP 4.x, activar advertencias de obsoletos en **config/app.php**:: @@ -21,7 +21,7 @@ son: ``updateQuery()``, ``insertQuery()`` and ``deleteQuery()`` instead. Actualiza a PHP 8.1 -================== +=================== Si no estas ejecutando en **PHP 8.1 o superior**, tendrás que actualizar PHP antes de actualizar CakePHP. @@ -31,7 +31,7 @@ Si no estas ejecutando en **PHP 8.1 o superior**, tendrás que actualizar PHP an .. _upgrade-tool-use: Usar la herramienta de actualización -==================== +==================================== .. note:: La herramienta de actualización sólo funciona en aplicaciones que se ejecutan en cakePHP 4.x. No puedes ejecutar la herramienta de actualización después de actualizar a CakePHP 5.0. @@ -55,7 +55,7 @@ plugin:: bin/cake upgrade rector --rules chronos3 Actualizar dependencias de CakePHP -========================= +================================== Después de aplicar las refactorizaciones de rector necesitas actualizar CakePHP, sus plugins, PHPUnit y tal vez otras dependencias en tu ``composer.json``. @@ -67,7 +67,7 @@ After the version strings are adjusted in your ``composer.json`` execute ``composer update -W`` and check its output. Actualiza los archivos de la aplicación basándose en las últimas plantillas -=============================================== +=========================================================================== A continuación, asegurate de que el resto de tu aplicación este actualizado basándose en la ultima version de `cakephp/app `__. diff --git a/es/appendices/migration-guides.rst b/es/appendices/migration-guides.rst index f5d9f1e9db..ed157548e7 100644 --- a/es/appendices/migration-guides.rst +++ b/es/appendices/migration-guides.rst @@ -1,5 +1,5 @@ Guías de migración -################ +################## Las guías de migración contienen información relativa a las nuevas funcionalidades introducidas en cada versión y la manera de migrar entre 4.x y 5.x diff --git a/es/appendices/phpunit10.rst b/es/appendices/phpunit10.rst index 1354c567b0..59761f3911 100644 --- a/es/appendices/phpunit10.rst +++ b/es/appendices/phpunit10.rst @@ -1,11 +1,11 @@ Actualización a PHPUnit 10 -################## +########################## Con CakePHP 5 la version mínima de PHPUnit ha cambiado de ``^8.5 || ^9.3`` a ``^10.1``. Esto introduce algunos cambios importantes tanto por parte de PHPUnit como por parte de CakePHP. Ajustes de phpunit.xml -======================= +====================== Se recomienda dejar que PHPUnit actualice su archivo de configuración a través del siguiente comando:: @@ -18,7 +18,7 @@ Se recomienda dejar que PHPUnit actualice su archivo de configuración a través Con este comando ejecutado, tu ``phpunit.xml`` ya tiene la mayoría de los cambios recomendados presentes. Nuevo sistema de eventos ----------------- +------------------------ PHPUnit 10 eliminó el antiguo sistema de hook e introdujo un nuevo `Sistema de eventos `_ @@ -35,7 +35,7 @@ a:: ``->withConsecutive()`` ha sido eliminado -======================================== +========================================= Puedes convertir el metodo ``->withConsecutive()`` eliminado en una solución provisional que funcione como puede ver aquí:: @@ -52,7 +52,7 @@ se ha añadido el método estático ``self::withConsecutive()`` a través del m a la clase base ``Cake\TestSuite\TestCase`` para que no tenga que agregar manualmente este trait a tus clases de TestCase. los proveedores de datos tienen que ser estáticos -================================ +================================================= Si tus testcases aprovechan la función de proveedor de datos de PHPUnit entonces tienes que ajustar tus proveedores de datos para que sean estáticos:: From cd7bbafd7838deb4bfe03924680d18cd32ca5afe Mon Sep 17 00:00:00 2001 From: Antonio Reveron Date: Mon, 30 Oct 2023 13:05:36 +0000 Subject: [PATCH 085/337] fix warning title underline too short --- es/appendices/5-0-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/es/appendices/5-0-migration-guide.rst b/es/appendices/5-0-migration-guide.rst index fd91c2fb5e..887195b9af 100644 --- a/es/appendices/5-0-migration-guide.rst +++ b/es/appendices/5-0-migration-guide.rst @@ -77,7 +77,7 @@ Connection el controlador habilite el registro de consultas ``$connection->getDriver()->setLogger()``. Controlador ----------- +----------- - La firma del método para ``Controller::__construct()`` ha cambiado. Por lo tanto, tienes que ajustar el código en consecuencia si estás sobreescribiendo el constructor. From 9d69ba5a8c3e06c116dfd3f691c7ff2664728b2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 30 Oct 2023 13:35:21 +0000 Subject: [PATCH 086/337] Updated file tutorials-and-examples/blog-auth-example/auth.rst in ES --- .../blog-auth-example/auth.rst | 417 +++++++++--------- 1 file changed, 220 insertions(+), 197 deletions(-) diff --git a/es/tutorials-and-examples/blog-auth-example/auth.rst b/es/tutorials-and-examples/blog-auth-example/auth.rst index cb107e286a..30d5c44a8b 100644 --- a/es/tutorials-and-examples/blog-auth-example/auth.rst +++ b/es/tutorials-and-examples/blog-auth-example/auth.rst @@ -1,13 +1,16 @@ Tutorial Blog - Autenticación y Autorización ############################################ -Siguiendo con nuestro ejemplo de aplicacion :doc:`/tutorials-and-examples/blog/blog`, imaginá que necesitamos proteger ciertas URLs, dependiendo del usuario logeado. También tenemos otro requisito, permitir que nuestro blog tenga varios autores, cada uno habilitado para crear sus posts, editar y borrarlos a voluntad, evitando que otros autores puedan cambiarlos. +Siguiendo con nuestro ejemplo de aplicación :doc:`/tutorials-and-examples/blog/blog`, imaginá que +necesitamos no permitir que usuarios no autenticados puedan crear artículos. -Creando el codigo para usuarios -=============================== +Creando la tabla users y el Controlador +======================================= Primero, vamos a crear una tabla en nuestra base de datos para guardar los datos de usuarios:: +.. code-block:: mysql + CREATE TABLE users ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, email VARCHAR(255), @@ -17,9 +20,26 @@ Primero, vamos a crear una tabla en nuestra base de datos para guardar los datos modified DATETIME DEFAULT NULL ); -Siguimos las convenciones de CakePHP para nombrar tablas pero también estamos aprovechando otra convencion: al usar los campos email y password en nuestra tabla CakePHP configurará automáticamente la mayoria de las cosas al momento de implementar el login. +Si estás usando PostgreSQL, conecta a la base de datos cake_blog y ejecuta el siguiente SQL en su lugar: -El siguiente paso es crear Users table, responsable de buscar, guardar y validar los datos de usuario:: +.. code-block:: SQL + + CREATE TABLE users ( + id SERIAL PRIMARY KEY, + email VARCHAR(255), + password VARCHAR(255), + role VARCHAR(20), + created TIMESTAMP DEFAULT NULL, + modified TIMESTAMP DEFAULT NULL + ); + +Seguimos las convenciones de CakePHP para nombrar tablas, pero también +estamos aprovechando otra convención: al usar los campos email y password +en nuestra tabla users, CakePHP configurará automáticamente la mayoría de las cosas +al momento de implementar el login. + +El siguiente paso es crear nuestra clase ``UsersTable``, responsable de buscar, guardar +y validar los datos de usuario:: // src/Model/Table/UsersTable.php namespace App\Model\Table; @@ -29,11 +49,10 @@ El siguiente paso es crear Users table, responsable de buscar, guardar y validar class UsersTable extends Table { - - public function validationDefault(Validator $validator) + public function validationDefault(Validator $validator): Validator { return $validator - ->notEmpty('email', 'A email is required') + ->notEmpty('email', 'An email is required') ->email('email') ->notEmpty('password', 'A password is required') ->notEmpty('role', 'A role is required') @@ -45,44 +64,33 @@ El siguiente paso es crear Users table, responsable de buscar, guardar y validar } -También vamos a crear UsersController; el siguiente contenido fue generado usando baked UsersController con el generador de código incluído con CakePHP:: +También vamos a crear nuestro ``UsersController``. El siguiente contenido se corresponde +con una clase ``UsersController`` básica "baked" usando las utilidades de generación +de código que están incluidas en CakePHP:: // src/Controller/UsersController.php namespace App\Controller; use App\Controller\AppController; - use Cake\Event\Event; - // Prior to 3.6 use Cake\Network\Exception\NotFoundException - use Cake\Http\Exception\NotFoundException; + use Cake\Event\EventInterface; class UsersController extends AppController { - - public function beforeFilter(Event $event) + public function index() { - parent::beforeFilter($event); - $this->Auth->allow('add'); - } - - public function index() - { - $this->set('users', $this->Users->find('all')); + $this->set('users', $this->Users->find()->all()); } public function view($id) { - if (!$id) { - throw new NotFoundException(__('Invalid user')); - } - $user = $this->Users->get($id); $this->set(compact('user')); } public function add() { - $user = $this->Users->newEntity(); + $user = $this->Users->newEmptyEntity(); if ($this->request->is('post')) { $user = $this->Users->patchEntity($user, $this->request->getData()); if ($this->Users->save($user)) { @@ -93,10 +101,11 @@ También vamos a crear UsersController; el siguiente contenido fue generado usan } $this->set('user', $user); } - } -De la misma forma que creamos las vistas para los posts del blog o usando la herramienta de generación de código, creamos las vistas. Para los objetivos de este tutorial, mostraremos solamente add.php: +Creamos las vistas para nuestros artículos de la misma forma que el controlador, usando +las herramientas de generación de código 'bake', lo que nos permite implementar las vistas +de los usuarios. Para el propósito de este tutorial, mostraremos solamente **add.php**:: .. code-block:: php @@ -106,9 +115,9 @@ De la misma forma que creamos las vistas para los posts del blog o usando la her Form->create($user) ?>
    - Form->input('email') ?> - Form->input('password') ?> - Form->input('role', [ + Form->control('email') ?> + Form->control('password') ?> + Form->control('role', [ 'options' => ['admin' => 'Admin', 'author' => 'Author'] ]) ?>
    @@ -116,84 +125,27 @@ De la misma forma que creamos las vistas para los posts del blog o usando la her Form->end() ?> -Autenticación (login y logout) -============================== - -Ya estamos listos para agregar nuestra autenticación. En CakePHP esto es manejado por :php:class:`Cake\\Controller\\Component\\AuthComponent`, responsable de requerir login para ciertas acciones, de manejar el sign-in y el sign-out y también de autorizar usuarios logeados a ciertas acciones que estan autorizados a utilizar. - -Para agregar este componente a tú aplicación abre el archivo **src/Controller/AppController.php** y agrega las siguientes lineas:: +Añadiendo Autenticación +======================= - // src/Controller/AppController.php +Ya estamos listos para agregar nuestra autenticación. En CakePHP esto es manejado +por el plugin ``authentication``. Empezaremos instalándolo. Usa composer para +instalar el plugin: - namespace App\Controller; +.. code-block:: console - use Cake\Controller\Controller; - use Cake\Event\Event; + composer require "cakephp/authentication:^2.0" - class AppController extends Controller - { - //... +Luego añade la siguiente línea en la función ``bootstrap()`` del archivo ``Application.php``:: - public function initialize() - { - $this->loadComponent('Flash'); - $this->loadComponent('Auth', [ - 'loginRedirect' => [ - 'controller' => 'Articles', - 'action' => 'index' - ], - 'logoutRedirect' => [ - 'controller' => 'Pages', - 'action' => 'display', - 'home' - ] - ]); - } + // in src/Application.php in the bootstrap() method. + $this->addPlugin('Authentication'); - public function beforeFilter(Event $event) - { - $this->Auth->allow(['index', 'view', 'display']); - } - //... - } - -No hay mucho que configurar, al haber utilizado convenciones para la tabla de usuarios. Simplemente asignamos las URLs que serán cargadas despues del login y del logout, en nuestro caso ``/articles/`` y ``/`` respectivamente. - -Lo que hicimos en ``beforeFilter()`` fue decirle al AuthComponent que no requiera login para las acciones index y view en cada controlador. -Queremos que nuestros visitantes puedan leer y listar las entradas sin registrarse. - -Ahora necesitamos poder registrar nuevos usuarios, guardar el nombre de usuario y contraseña, y hashear su contraseña para que no sea guardada como texto plano. Vamos a decirle al AuthComponent que deje usuarios sin autenticar acceder a la funcion add del controlador users e implementemos las acciones de login y logout:: - - // src/Controller/UsersController.php - - public function beforeFilter(Event $event) - { - parent::beforeFilter($event); - // Allow users to register and logout. - // You should not add the "login" action to allow list. Doing so would - // cause problems with normal functioning of AuthComponent. - $this->Auth->allow(['add', 'logout']); - } - - public function login() - { - if ($this->request->is('post')) { - $user = $this->Auth->identify(); - if ($user) { - $this->Auth->setUser($user); - return $this->redirect($this->Auth->redirectUrl()); - } - $this->Flash->error(__('Invalid email or password, try again')); - } - } - - public function logout() - { - return $this->redirect($this->Auth->logout()); - } +Añadiendo hashing de contraseña +=============================== -El hasheo del password aún no está hecho, necesitamos una clase Entity para nuestra clase User para así manejar esta lógica específica. -Crea el archivo **src/Model/Entity/User.php** y agrega las siguientes lineas:: +Lo siguiente, creamos la entidad ``User`` y añadimos el hashing del password. Crear el +archivo de la entidad **src/Model/Entity/User.php** y añade lo siguiente:: // src/Model/Entity/User.php namespace App\Model\Entity; @@ -203,9 +155,11 @@ Crea el archivo **src/Model/Entity/User.php** y agrega las siguientes lineas:: class User extends Entity { - - // Make all fields mass assignable for now. - protected array $_accessible = ['*' => true]; + // Make all fields mass assignable except for primary key field "id". + protected array $_accessible = [ + '*' => true, + 'id' => false + ]; // ... @@ -219,141 +173,210 @@ Crea el archivo **src/Model/Entity/User.php** y agrega las siguientes lineas:: // ... } -Ahora cada vez que la propiedad password sea asignada a un usuario, será hasheada usando la clase ``DefaultPasswordHasher``. -Solamente nos falta un archivo para la vista de la acción login. Abre tu archivo **templates/Users/login.php** y agrega las siguientes -lineas: +Ahora, siempre que la propiedad ``password`` es asignada a la entidad User, se +le aplicara el Hash usando la clase ``DefaultPasswordHasher``. -.. code-block:: php - - +Configurando Autenticación +========================== -
    - Flash->render('auth') ?> - Form->create() ?> -
    - - Form->input('email') ?> - Form->input('password') ?> -
    - Form->button(__('Login')); ?> - Form->end() ?> -
    +Ahora es el momento de configurar el plugin Authentication. +El plugin gestionará el proceso de autenticación usando 3 clases diferentes: -Ya podés registrar un nuevo usuario accediendo a ``/users/add`` e iniciar sesión con las nuevas credenciales ingresando a ``/users/login``. También al intentar acceder a alguna otra URL que no fue explicitamente autorizada, por ejemplo ``/articles/add``, la aplicación te redireccionará automaticamente al la pagina de login. +* ``Application`` usara el Authentication Middleware y proporciona un + AuthenticationService, teniendo todas las configuraciones que queramos para definir + como se van a comprobar las credenciales y donde encontrarlas. +* ``AuthenticationService`` es una clase de utilidad que te permite configurar el + proceso de autenticación. +* ``AuthenticationMiddleware`` será ejecutado como parte de la cola de middleware, + esto será antes de que tu controlador sea procesado por el framework, recogerá + las credenciales y las procesará para comprobar si el usuario está autenticado. -Y eso es todo! Se ve demasiado simple para ser verdad. Volvamos un poco para explicar que pasa. La función ``beforeFilter()`` le dice al AuthComponent que no requiera login para la acción ``add()`` asi como para ``index()`` y ``view()``, autorizadas en el ``beforeFilter()`` del AppController. +La lógica de autenticación es dividida en clases específicas y el proceso +se realiza antes de la capa del controlador. Primero, se comprueba si el +usuario está autenticado (basado en la configuración proporcionada) e inyecta +el usuario y el resultado de la autenticación en la petición para futura referencia. -La función ``login()`` llama a ``$this->Auth->identify()`` del AuthComponent, y funciona sin ninguna otra configuración ya que seguimos la convención. Es decir, tener un modelo llamado User con los campos email y password, y usar un formulario que hace post a un controlador con los datos del usuario. Esta función devuelve si el login fue exitoso o no, y en caso de que tenga exito redirige a la URL puesta en AppController, dentro de la configuracion del AuthComponent. +En **src/Application.php**, añade los siguientes imports:: -El logout funciona simplemente al acceder a ``/users/logout`` y redirecciona al usuario a la URL configurada. + // In src/Application.php add the following imports + use Authentication\AuthenticationService; + use Authentication\AuthenticationServiceInterface; + use Authentication\AuthenticationServiceProviderInterface; + use Authentication\Middleware\AuthenticationMiddleware; + use Psr\Http\Message\ServerRequestInterface; -Autorización (quién está autorizado a acceder qué) -================================================== +Luego implementa el interfaz de autenticación en tu clase Application:: -Como mencionamos antes, estamos convirtiendo este blog en una herramienta de autoría multiusuario, y para hacer esto necesitamos modificar la tabla de posts para agregar referencia al modelo User:: + // in src/Application.php + class Application extends BaseApplication + implements AuthenticationServiceProviderInterface + { - ALTER TABLE articles ADD COLUMN user_id INT(11); +Después añade lo siguiente:: -También, un pequeño cambio en ArticlesController es necesario para guardar el usuario logeado como referencia en los artículos creados:: + // src/Application.php + public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue + { + $middlewareQueue + // ... other middleware added before + ->add(new RoutingMiddleware($this)) + // add Authentication after RoutingMiddleware + ->add(new AuthenticationMiddleware($this)); - // src/Controller/ArticlesController.php + return $middlewareQueue; + } - public function add() + public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface { - $article = $this->Articles->newEmptyEntity(); - if ($this->request->is('post')) { - $article = $this->Articles->patchEntity($article, $this->request->getData()); - // Added this line - $article->user_id = $this->Auth->user('id'); - // You could also do the following - //$newData = ['user_id' => $this->Auth->user('id')]; - //$article = $this->Articles->patchEntity($article, $newData); - if ($this->Articles->save($article)) { - $this->Flash->success(__('Your article has been saved.')); - return $this->redirect(['action' => 'index']); - } - $this->Flash->error(__('Unable to add your article.')); - } - $this->set('article', $article); - } + $authenticationService = new AuthenticationService([ + 'unauthenticatedRedirect' => '/users/login', + 'queryParam' => 'redirect', + ]); + + // Carga los identificadores, asegurando que se comprueban los campos email y password + $authenticationService->loadIdentifier('Authentication.Password', [ + 'fields' => [ + 'username' => 'email', + 'password' => 'password', + ], + ]); -La función ``user()`` del AuthComponent devuelve datos del usuario actualmente logeado. Usamos este método para agregar datos a la información que será guardada. + // Carga los authenticators, quieres que la sesión comprueba primero + $authenticationService->loadAuthenticator('Authentication.Session'); + // Configure form data check to pick email and password + $authenticationService->loadAuthenticator('Authentication.Form', [ + 'fields' => [ + 'username' => 'email', + 'password' => 'password', + ], + 'loginUrl' => '/users/login', + ]); + + return $authenticationService; + } -Vamos a prevenir que autores puedan editar o eliminar los artículos de otros autores. La regla básica para nuestra aplicación es que los usuarios admin pueden acceder todas las URL, mientras que los usuarios normales (autores) solamente pueden acceder las acciones permitidas. Abre nuevamente AppController y agregá las siguientes opciones en la configuración del Auth:: +En tu clase ``AppController`` añade el siguiente código:: // src/Controller/AppController.php - - public function initialize() + public function initialize(): void { + parent::initialize(); $this->loadComponent('Flash'); - $this->loadComponent('Auth', [ - 'authorize' => ['Controller'], // Added this line - 'loginRedirect' => [ - 'controller' => 'Articles', - 'action' => 'index' - ], - 'logoutRedirect' => [ - 'controller' => 'Pages', - 'action' => 'display', - 'home' - ] - ]); + + // Añade ésta línea para comprobar la autenticación y asegurar tu aplicación + $this->loadComponent('Authentication.Authentication'); + +Ahora, en cada petición, el ``AuthenticationMiddleware`` inspeccionará la sesión +para comprobar si existe un usuario autenticado. Si estamos cargando la página +``/users/login``, también inspeccionará los datos del formulario enviado en "post" +(si hay alguno) para extraer las credenciales. Por defecto las credenciales se +extraerán de los campos ``email`` y ``password`` de la información del request. +El resultado de la autenticación será inyectado in un atributo de la petición +llamado ``authentication``. Puedes inspeccionar el resultado en cualquier momento +usando ``$this->request->getAttribute('authentication')`` desde la acción de un +controlador. +Todas tus páginas serán restringidas ya que ``AuthenticationComponent`` está +comprobando el resultado en cada petición. Cuando falla al buscar un usuario +autenticado, redirigirá al usuario a la página ``/users/login``. +Te en cuenta que en éste punto del tutorial, la aplicación no funcionará ya que +aún no tenemos la página de login. Si visitas tu aplicación, obtendrás un bucle +infinito de redirección, asi que, vamos a arreglarlo! + +En tu ``UsersController``, añade el siguiente código:: + + public function beforeFilter(\Cake\Event\EventInterface $event) + { + parent::beforeFilter($event); + // Configura la acción de login para no requerir autenticación, para + // prevenir el bucle infinito de redirección + $this->Authentication->addUnauthenticatedActions(['login']); } - public function isAuthorized($user) + public function login() { - // Admin can access every action - if (isset($user['role']) && $user['role'] === 'admin') { - return true; - } + $this->request->allowMethod(['get', 'post']); + $result = $this->Authentication->getResult(); + // sin importar si es POST o GET, redirige si el usuario esta autenticado + if ($result->isValid()) { + // redirige a /articles después de iniciar sesión correctamente + $redirect = $this->request->getQuery('redirect', [ + 'controller' => 'Articles', + 'action' => 'index', + ]); - // Default deny - return false; + return $this->redirect($redirect); + } + // muestra los errors si el usuario envió el formulario y fallo la autenticación + if ($this->request->is('post') && !$result->isValid()) { + $this->Flash->error(__('Invalid email or password')); + } } -Hemos creado un mecanismo de autorización muy simple. En este caso, los usuarios con el rol ``admin`` podrán acceder a cualquier URL del sitio cuando esten logeados, pero el resto de los usuarios no podrán hacer más que los usuarios no logeados. +Añade la lógica de la vista para la acción de login:: -Esto no es exactamente lo que queriamos, por lo que tendremos que agregar mas reglas a nuestro método ``isAuthorized()``. Pero en lugar de hacerlo en AppController, vamos a delegar a cada controlador. Las reglas que vamos a agregar a ArticlesController deberian permitirle a los autores crear artículos, pero prevenir que editen artículos que no le pertenezcan. Abre el archivo ArticlesController.php y agregá las siguientes lineas:: + +
    + Flash->render() ?> +

    Login

    + Form->create() ?> +
    + + Form->control('email', ['required' => true]) ?> + Form->control('password', ['required' => true]) ?> +
    + Form->submit(__('Login')); ?> + Form->end() ?> - // src/Controller/ArticlesController.php + Html->link("Add User", ['action' => 'add']) ?> +
    - public function isAuthorized($user) - { - // All registered users can add articles - if ($this->request->getParam('action') === 'add') { - return true; - } +Ahora la página de login nos permitirá iniciar sesión en la aplicación. +Compruébalo haciendo una petición a cualquier página de tu aplicación. +Después de haber sido redirigido a la página ``/users/login``, introduce +el email y password que usaste previamente para crear el usuario. +Deberías ser redirigido correctamente después de iniciar sesión. - // The owner of an article can edit and delete it - if (in_array($this->request->getParam('action'), ['edit', 'delete'])) { - $articleId = (int)$this->request->getParam('pass.0'); - if ($this->Articles->isOwnedBy($articleId, $user['id'])) { - return true; - } - } +Necesitamos añadir un par de detalles más para configurar nuestra aplicación. +Queremos que todas las páginas ``view`` e ``index`` sean accesible sin necesitar +iniciar sesión, así que añadiremos ésta configuración específica en ``AppController``:: - return parent::isAuthorized($user); + // en src/Controller/AppController.php + public function beforeFilter(\Cake\Event\EventInterface $event) + { + parent::beforeFilter($event); + // para todos los controladores de nuestra aplicación, hacer el index y view + // acciones públicas, saltándonos la autenticación + $this->Authentication->addUnauthenticatedActions(['index', 'view']); } -Estamos sobreescribiendo el método ``isAuthorized()`` de AppController y comprobando si la clase padre autoriza al usuario. Si no lo hace entonces solamente autorizarlo a acceder a la acción add y condicionalmente acceder a edit y delete. Una última cosa por implementar, decidir si el usuario está autorizador a editar el post o no, estamos llamando la función ``isOwnedBy()`` del modelo Articles. Es en general una buena practica mover la mayor parte de la logica posible hacia los modelos:: +Terminar sesión +=============== - // src/Model/Table/ArticlesTable.php +Añade la acción ``logout`` a la clase ``UsersController``:: - public function isOwnedBy($articleId, $userId) + // en src/Controller/UsersController.php + public function logout() { - return $this->exists(['id' => $articleId, 'user_id' => $userId]); + $result = $this->Authentication->getResult(); + // sin importar si es POST o GET, redirige si el usuario esta autenticado + if ($result->isValid()) { + $this->Authentication->logout(); + return $this->redirect(['controller' => 'Users', 'action' => 'login']); + } } -Esto concluye nuestro simple tutorial de autenticación y autorización. Para proteger el UsersController se puede seguir la misma técnica utilizada para ArticlesController. También es posible implementar una solución mas general en AppController, de acuerdo a tus reglas. +Ahora puedes visitar ``/users/logout`` para terminar la sesión. Luego serás +redirigido a la página de login. Si has llegado tan lejos, felicidades, ahora +tienes un blog simple que: -En caso de necesitar más control, sugerimos leer la guia completa sobre Auth en -:doc:`/controllers/components/authentication`, donde encontrarás mas información para configurar el componente y crear clases de autorizacion a tú medida. +* Permite usuarios autenticados crear y editar artículos. +* Permite usuarios no autenticados ver artículos y etiquetas. Lectura sugerida ---------------- #. :doc:`/bake/usage` Generar código CRUD básico -#. :doc:`/controllers/components/authentication`: Registro y login de usuarios +#. `Authentication Plugin `__ documentación. .. meta:: :title lang=es: Tutorial Blog - Autenticación y Autorización From 1786502e9eeb8e7af772c9769df766dd2aec1a56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 30 Oct 2023 13:57:28 +0000 Subject: [PATCH 087/337] Update the page /views/json-and-xml-views.rst in EN and ES --- en/views/json-and-xml-views.rst | 7 ++- es/views/json-and-xml-views.rst | 82 ++++++++++++++++----------------- 2 files changed, 46 insertions(+), 43 deletions(-) diff --git a/en/views/json-and-xml-views.rst b/en/views/json-and-xml-views.rst index 4f37ade368..04d7005bcc 100644 --- a/en/views/json-and-xml-views.rst +++ b/en/views/json-and-xml-views.rst @@ -60,7 +60,7 @@ serialize:: public function index() { - // Set the view vars that have to be serialized. + // Set the view vars $this->set('articles', $this->paginate()); // Specify which view vars JsonView should serialize. $this->viewBuilder()->setOption('serialize', 'articles'); @@ -84,7 +84,7 @@ You can also define ``serialize`` as an array of view variables to combine:: { // Some code that created $articles and $comments - // Set the view vars that have to be serialized. + // Set the view vars $this->set(compact('articles', 'comments')); // Specify which view vars JsonView should serialize. @@ -238,3 +238,6 @@ total control over view class selection you can directly choose the view class:: } } +.. meta:: + :title lang=en: JSON and XML views + :keywords lang=en: json,xml,presentation layer,view,ajax,logic,syntax,templates,cakephp diff --git a/es/views/json-and-xml-views.rst b/es/views/json-and-xml-views.rst index 3e7e3e86f8..eef756f76d 100644 --- a/es/views/json-and-xml-views.rst +++ b/es/views/json-and-xml-views.rst @@ -1,35 +1,30 @@ Vistas JSON y XML ################# -JsonView y XmlView le permiten crear respuestas JSON y XML, e integrarse con el -:php:class:`Cake\\Controller\\Component\\RequestHandlerComponent`. +La integración de ``JsonView`` y ``XmlView`` con las funcionalidades de :ref:`controller-viewclasses` +de CakePHP y te permite crear respuestas JSON y XML. -Al habilitar ``RequestHandlerComponent`` en su aplicación y habilitar la -compatibilidad con las extensiones ``json`` y/o ``xml``, puede aprovechar -automáticamente las nuevas clases de vista. ``JsonView`` y ``XmlView`` se -denominarán vistas de datos para el resto de esta página. +Éstas clases View son usadas de forma mas común junto con :php:meth:`\Cake\Controller\Controller::viewClasses()`. Hay dos formas de generar vistas de datos. La primera es mediante el uso de la opción ``serialize`` y la segunda es mediante la creación de archivos de plantilla normales. -Habilitación de vistas de datos en su aplicación -================================================ +Definiendo clases View pata Negociar +==================================== -Antes de poder usar las clases de vista de datos, primero deberá cargar el -:php:class:`Cake\\Controller\\Component\\RequestHandlerComponent` en su -controlador:: +En tu ``AppController`` o en un controlador individual puedes implementar la +función ``viewClasses()`` y proporcionarle todas las clases View que +quieras soportar:: - public function initialize(): void + use Cake\View\JsonView; + use Cake\View\XmlView; + + public function viewClasses(): array { - ... - $this->loadComponent('RequestHandler'); + return [JsonView::class, XmlView::class]; } -Esto se puede hacer en su ``AppController`` y habilitará el cambio automático de -clase de vista en los tipos de contenido. También puede configurar el componente -con la configuración ``viewClassMap``, para asignar tipos a sus clases -personalizadas y/o asignar otros tipos de datos. Opcionalmente, puede habilitar las extensiones json y/o xml con `file-extensions`. Esto le permitirá acceder a ``JSON``, ``XML`` o cualquier @@ -57,19 +52,20 @@ serializar:: namespace App\Controller; + use Cake\View\JsonView; + class ArticlesController extends AppController { - public function initialize(): void + public function viewClasses(): array { - parent::initialize(); - $this->loadComponent('RequestHandler'); + return [JsonView::class]; } public function index() { - // Set the view vars that have to be serialized. + // Asigna las variables a la vista $this->set('articles', $this->paginate()); - // Specify which view vars JsonView should serialize. + // Especifica las variables de vista que JsonView deberá serializar $this->viewBuilder()->setOption('serialize', 'articles'); } } @@ -79,19 +75,20 @@ combinar:: namespace App\Controller; + use Cake\View\JsonView; + class ArticlesController extends AppController { - public function initialize(): void + public function viewClasses(): array { - parent::initialize(); - $this->loadComponent('RequestHandler'); + return [JsonView::class]; } public function index() { - // Some code that created $articles and $comments + // Código que crear las variables $articles y $comments - // Set the view vars that have to be serialized. + // Asigna las variables a la vista $this->set(compact('articles', 'comments')); // Specify which view vars JsonView should serialize. @@ -108,9 +105,9 @@ Sin un solo elemento de nivel superior, el Xml no podrá generarse. Uso de una vista de datos con archivos de plantilla =================================================== -Debe usar archivos de plantilla si necesita realizar alguna manipulación del +Debe usar archivos de plantilla si necesita manipular el contenido de la vista antes de crear el resultado final. Por ejemplo, si tuviéramos -artículos que tuvieran un campo que contuviera HTML generado, probablemente +artículos con un campo que contuviera HTML generado, probablemente querríamos omitirlo de una respuesta JSON. Esta es una situación en la que un archivo de vista sería útil:: @@ -125,7 +122,7 @@ de vista sería útil:: } // View code - templates/Articles/json/index.php - foreach ($articles as &$article) { + foreach ($articles as $article) { unset($article->generated_html); } echo json_encode(compact('articles')); @@ -162,7 +159,7 @@ mediante el prefijo ``@``:: 'loc' => Router::url(['controller' => 'Pages', 'action' => 'view', $page->slug, '_full' => true]), 'lastmod' => $page->modified->format('Y-m-d'), 'changefreq' => 'daily', - 'priority' => '0.5' + 'priority' => '0.5', ]; } @@ -173,7 +170,7 @@ mediante el prefijo ``@``:: $this->set([ // Define an attribute on the root node. '@xmlns' => 'http://www.sitemaps.org/schemas/sitemap/0.9', - 'url' => $urls + 'url' => $urls, ]); } @@ -199,21 +196,20 @@ CakePHP en una forma coherente de JSON:: Respuestas JSONP ---------------- -Al utilizar ``JsonView``, puede utilizar la variable de vista especial ``_jsonp`` +Al utilizar ``JsonView``, puede utilizar la variable de vista especial ``jsonp`` para habilitar la devolución de una respuesta JSONP. Si se establece en ``true`` la clase de vista comprueba si se establece el parámetro de string de consulta denominado "callback" y, de ser así, envuelve la respuesta json en el nombre de función proporcionado. Si desea utilizar un nombre de parámetro de string de consulta -personalizado en lugar de "callback", establezca ``_jsonp`` al nombre requerido en +personalizado en lugar de "callback", establezca ``jsonp`` al nombre requerido en lugar de ``true.``. -Ejemplo de uso -============== +Eligiendo una clase View +======================== -Si bien el :doc:`RequestHandlerComponent -` puede establecer automáticamente la -vista en función del tipo de contenido o la extensión de la solicitud, también puede -controlar las asignaciones de vistas en el controlador:: +Aunque puedes usar la función ``viewClasses`` la mayoría de las veces, si quieres +un control total sobre la selección de la clase de vista, puedes elegir directamente +la clase:: // src/Controller/VideosController.php namespace App\Controller; @@ -252,3 +248,7 @@ controlar las asignaciones de vistas en el controlador:: return $this->response->withDownload('report-' . date('YmdHis') . '.' . $format); } } + +.. meta:: + :title lang=es: Vistas JSON y XML + :keywords lang=es: json,xml,presentation layer,view,ajax,logic,syntax,templates,cakephp From 5e6680b4d7fb49a46b71de224418fa04a4ab59b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20P=C3=A9rez?= Date: Mon, 30 Oct 2023 15:12:46 +0000 Subject: [PATCH 088/337] Fix build issues --- es/tutorials-and-examples/blog-auth-example/auth.rst | 4 ++-- es/tutorials-and-examples/cms/articles-controller.rst | 2 +- es/tutorials-and-examples/cms/authentication.rst | 2 +- es/tutorials-and-examples/cms/authorization.rst | 2 +- es/tutorials-and-examples/cms/tags-and-users.rst | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/es/tutorials-and-examples/blog-auth-example/auth.rst b/es/tutorials-and-examples/blog-auth-example/auth.rst index 30d5c44a8b..5920a6043e 100644 --- a/es/tutorials-and-examples/blog-auth-example/auth.rst +++ b/es/tutorials-and-examples/blog-auth-example/auth.rst @@ -7,7 +7,7 @@ necesitamos no permitir que usuarios no autenticados puedan crear artículos. Creando la tabla users y el Controlador ======================================= -Primero, vamos a crear una tabla en nuestra base de datos para guardar los datos de usuarios:: +Primero, vamos a crear una tabla en nuestra base de datos para guardar los datos de usuarios: .. code-block:: mysql @@ -105,7 +105,7 @@ de código que están incluidas en CakePHP:: Creamos las vistas para nuestros artículos de la misma forma que el controlador, usando las herramientas de generación de código 'bake', lo que nos permite implementar las vistas -de los usuarios. Para el propósito de este tutorial, mostraremos solamente **add.php**:: +de los usuarios. Para el propósito de este tutorial, mostraremos solamente **add.php**: .. code-block:: php diff --git a/es/tutorials-and-examples/cms/articles-controller.rst b/es/tutorials-and-examples/cms/articles-controller.rst index 7fb7106824..15e9db6600 100644 --- a/es/tutorials-and-examples/cms/articles-controller.rst +++ b/es/tutorials-and-examples/cms/articles-controller.rst @@ -1,5 +1,5 @@ CMS Tutorial - Creating the Articles Controller -======= +=============================================== .. note:: La documentación no es compatible actualmente con el idioma español en esta página. diff --git a/es/tutorials-and-examples/cms/authentication.rst b/es/tutorials-and-examples/cms/authentication.rst index 575e244a44..4fc26cdd4f 100644 --- a/es/tutorials-and-examples/cms/authentication.rst +++ b/es/tutorials-and-examples/cms/authentication.rst @@ -1,5 +1,5 @@ CMS Tutorial - Authentication -======= +============================= .. note:: La documentación no es compatible actualmente con el idioma español en esta página. diff --git a/es/tutorials-and-examples/cms/authorization.rst b/es/tutorials-and-examples/cms/authorization.rst index 9771257ff8..d2e7c224ae 100644 --- a/es/tutorials-and-examples/cms/authorization.rst +++ b/es/tutorials-and-examples/cms/authorization.rst @@ -1,5 +1,5 @@ CMS Tutorial - Authorization -======= +============================ .. note:: La documentación no es compatible actualmente con el idioma español en esta página. diff --git a/es/tutorials-and-examples/cms/tags-and-users.rst b/es/tutorials-and-examples/cms/tags-and-users.rst index 0bb5eee32a..e6424af39c 100644 --- a/es/tutorials-and-examples/cms/tags-and-users.rst +++ b/es/tutorials-and-examples/cms/tags-and-users.rst @@ -1,5 +1,5 @@ CMS Tutorial - Tags and Users -======= +============================= .. note:: La documentación no es compatible actualmente con el idioma español en esta página. From a26b0a720938037c977d66d4cecf51cd9c528603 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Mon, 30 Oct 2023 20:39:46 +0100 Subject: [PATCH 089/337] [es] logging translation --- es/core-libraries/logging.rst | 253 +++++++++++++++++----------------- 1 file changed, 124 insertions(+), 129 deletions(-) diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index 66081f5d77..639d42a61c 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -26,7 +26,7 @@ directamente. Consulta la sección :ref:`writing-to-logs` para obtener más info Logging Configuration ===================== -La configuración de "Log" debe realizarse durante la fase de arranque de tu aplicación. +La configuración de ``Log`` debe realizarse durante la fase de arranque de tu aplicación. El archivo **config/app.php** está diseñado precisamente para esto. Puedes definir tantos ``loggers`` como necesite tu aplicación. Los ``loggers`` deben configurarse utilizando la clase :php:class:`Cake\\Log\\Log`. Un ejemplo sería:: @@ -117,7 +117,7 @@ Todos los ``log`` configurados se escriben secuencialmente cada vez que se llama ``log()`` devolverá "false" y no se escribirán mensajes de registro. Usando marcadores de posición (placeholders) en mensajes ------------------------------------------------ +--------------------------------------------------------- Si necesitas registrar datos definidos dinámicamente, puedes utilizar marcadores de posición en tus mensajes de registro y proporcionar un array de pares clave/valor en el parámetro ``$context`` @@ -213,119 +213,113 @@ Ten en cuenta que al usar esta forma, se limitará la capacidad de pasar más da Log::warning('This is a warning', 'payments'); .. note:: - When ``scopes`` is set to an empty array or ``null`` in a logger's - configuration, it will take messages of any scope. Setting it to ``false`` - will only match messages without scope. + Cuando ``scopes`` se establece como un arreglo vacío o null en la configuración de un ``logger``, + aceptará mensajes de cualquier ``scope``. Establecerlo como false solo coincidirá con mensajes sin ``scope``. .. _file-log: -Logging to Files -================ +Guardando logs en Archivos +=========================== -As its name implies ``FileLog`` writes log messages to files. The level of log -message being written determines the name of the file the message is stored in. -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**:: +Como su nombre indica, ``FileLog`` escribe mensajes de registro en archivos. El nivel del mensaje +de registro que se está escribiendo determina el nombre del archivo en el que se almacena el mensaje. +Si no se proporciona un nivel, se utiliza :php:const:`LOG_ERR`, que escribe en el registro de errores. +La ubicación de registro predeterminada es **logs/$level.log**:: - // Executing this inside a CakePHP class + // Es ejecutado asi dentro de una clase CakePHP $this->log("Something didn't work!"); - // Results in this being appended to logs/error.log + // Se añadirá lo siguiente al archivo logs/error.log. // 2007-11-02 10:22:02 Error: Something didn't work! -The configured directory must be writable by the web server user in -order for logging to work correctly. +El directorio configurado debe tener permisos de escritura por el usuario del servidor web para +que el registro funcione correctamente. -You can configure additional/alternate FileLog locations when configuring -a logger. FileLog accepts a ``path`` which allows for -custom paths to be used:: +Puedes configurar ubicaciones adicionales o alternativas para FileLog al configurar un registrador. +FileLog acepta un "path" que permite utilizar rutas personalizadas:: Log::setConfig('custom_path', [ 'className' => 'File', 'path' => '/path/to/custom/place/' ]); -``FileLog`` engine takes the following options: +El motor de ``FileLog`` toma las siguientes opciones: -* ``size`` Used to implement basic log file rotation. If log file size - reaches specified size the existing file is renamed by appending timestamp - to filename and new log file is created. Can be integer bytes value or - human readable string values like '10MB', '100KB' etc. Defaults to 10MB. -* ``rotate`` Log files are rotated specified times before being removed. - If value is 0, old versions are removed rather then rotated. Defaults to 10. -* ``mask`` Set the file permissions for created files. If left empty the default - permissions are used. +* ``size`` Se utiliza para implementar una rotación básica de archivos de registro. Si el tamaño + del archivo de registro alcanza el tamaño especificado, el archivo existente se renombra agregando + una marca de tiempo al nombre de archivo y se crea un nuevo archivo de registro. Puede ser un valor + entero en bytes o valores como '10MB', '100KB', etc. El valor predeterminado es 10MB. +* ``rotate`` Los archivos de registro se rotan un número especificado de veces antes de ser eliminados. + Si el valor es 0, se eliminan las versiones antiguas en lugar de rotarlas. El valor predeterminado es 10. +* ``mask`` Establece los permisos de archivo para los archivos creados. Si se deja vacío, se utilizan + los permisos predeterminados. .. note:: - Missing directories will be automatically created to avoid - unnecessary errors thrown when using the FileEngine. + Los directorios faltantes se crearán automáticamente para evitar errores innecesarios + cuando se utiliza FileEngine. .. _syslog-log: -Logging to Syslog -================= +Guardando logs en Syslog +========================= -In production environments it is highly recommended that you setup your system to -use syslog instead of the file logger. This will perform much better as any -writes will be done in a (almost) non-blocking fashion and your operating system -logger can be configured separately to rotate files, pre-process writes or use -a completely different storage for your logs. +En entornos de producción, se recomienda encarecidamente configurar tu sistema para utilizar el +syslog en lugar del guardar los logs en archivos. Esto mejorará el rendimiento, ya que cualquier +escritura se realizará de manera (casi) no bloqueante y el ``logger`` del sistema operativo se +puede configurar de forma independiente para rotar archivos, preprocesar escrituras o +utilizar un almacenamiento completamente diferente para tus registros. -Using syslog is pretty much like using the default FileLog engine, you just need -to specify ``Syslog`` as the engine to be used for logging. The following -configuration snippet will replace the default logger with syslog, this should -be done in the **config/bootstrap.php** file:: +Usar syslog es prácticamente como usar el motor de registro de archivos predeterminado, simplemente +necesitas especificar ``Syslog`` como el motor a utilizar para el registro de logs. El siguiente +fragmento de configuración reemplazará el ``logger`` predeterminado con syslog, esto se debe hacer +en el archivo **config/bootstrap.php**":: Log::setConfig('default', [ 'engine' => 'Syslog' ]); -The configuration array accepted for the Syslog logging engine understands the -following keys: - -* ``format``: An sprintf template string with two placeholders, the first one - for the error level, and the second for the message itself. This key is - useful to add additional information about the server or process in the - logged message. For example: ``%s - Web Server 1 - %s`` will look like - ``error - Web Server 1 - An error occurred in this request`` after - replacing the placeholders. This option is deprecated. You should use - :ref:`logging-formatters` instead. -* ``prefix``: An string that will be prefixed to every logged message. -* ``flag``: An integer flag to be used for opening the connection to the - logger, by default ``LOG_ODELAY`` will be used. See ``openlog`` documentation - for more options -* ``facility``: The logging slot to use in syslog. By default ``LOG_USER`` is - used. See ``syslog`` documentation for more options - -Creating Log Engines -===================== +El arreglo de configuración aceptado para el motor de registro Syslog comprende +las siguientes claves: +* ``format``: Una cadena de plantilla sprintf con dos marcadores de posición (placeholdes), + el primero para el nivel de error y el segundo para el mensaje en sí. Esta clave es + útil para agregar información adicional sobre el servidor o el proceso en el mensaje + registrado. Por ejemplo: ``%s -Servidor web 1 - %s`` se verá como + ``error - Servidor web 1 - Ocurrió un error en esta solicitud`` después de reemplazar + los placeholders. Esta opción está obsoleta. Deberías usar :ref:`logging-formatters` en su lugar. +* ``prefix``: Una cadena que se utilizará como prefijo para cada mensaje registrado. +* ``flag``: Una bandera tipo ``int`` que se usará para abrir la conexión al registro, + por defecto se usará ``LOG_ODELAY```. Consulta la documentación de ``openlog`` para ver más opciones. +* ``facility``: El espacio de registro a utilizar en syslog. Por defecto se utiliza ``LOG_USER``. + Consulta la documentación de ``syslog`` para ver más opciones. + +Creación de Motores de Logs +================================= -Log engines can be part of your application, or part of -plugins. If for example you had a database logger called -``DatabaseLog``. As part of your application it would be placed in -**src/Log/Engine/DatabaseLog.php**. As part of a plugin it would be placed in -**plugins/LoggingPack/src/Log/Engine/DatabaseLog.php**. To configure log -engine you should use :php:meth:`Cake\\Log\\Log::setConfig()`. For example -configuring our DatabaseLog would look like:: +Los motores de registro pueden formar parte de tu aplicación o de plugins. Por ejemplo, +si tuvieras un registro en base de datos llamado ``DatabaseLog``, como parte de tu aplicación +se colocaría en **src/Log/Engine/DatabaseLog.php**. Como parte de un plugin se colocaría en +**plugins/LoggingPack/src/Log/Engine/DatabaseLog.php**. Para configurar el motor de registro, +debes usar :php:meth:`Cake\\Log\\Log::setConfig()`. Por ejemplo, la configuración de nuestro +DatabaseLog se vería así:: - // For src/Log + // Para src/Log Log::setConfig('otherFile', [ 'className' => 'Database', 'model' => 'LogEntry', // ... ]); - // For plugin called LoggingPack + // Para el plugin llamado LoggingPack Log::setConfig('otherFile', [ 'className' => 'LoggingPack.Database', 'model' => 'LogEntry', // ... ]); -When configuring a log engine the ``className`` parameter is used to -locate and load the log handler. All of the other configuration -properties are passed to the log engine's constructor as an array. :: +Al configurar un motor de registro, el parámetro ``className`` se utiliza para localizar +y cargar el controlador de registro. Todas las demás propiedades de configuración se pasan +al constructor del motor de registro como un array.:: namespace App\Log\Engine; use Cake\Log\Engine\BaseLog; @@ -344,31 +338,31 @@ properties are passed to the log engine's constructor as an array. :: } } -CakePHP requires that all logging engine implement ``Psr\Log\LoggerInterface``. -The class :php:class:`Cake\Log\Engine\BaseLog` is an easy way to satisfy the -interface as it only requires you to implement the ``log()`` method. +CakePHP requiere que todos los motores de registro implementen Psr\Log\LoggerInterface. +La clase :php:class:`Cake\Log\Engine\BaseLog` es una forma sencilla de cumplir con la interfaz, +ya que solo requiere que implementes el método log(). .. _logging-formatters: -Logging Formatters ------------------- -Logging formatters allow you to control how log messages are formatted -independent of the storage engine. Each core provided logging engine comes with -a formatter configured to maintain backwards compatible output. However, you can -adjust the formatters to fit your requirements. Formatters are configured -alongside the logging engine:: +Formateadores de Logs +--------------------------- +Los formateadores de registro te permiten controlar cómo se formatean los mensajes de registro +de forma independiente al motor de almacenamiento. Cada motor de registro proporcionado por +defecto viene con un formateador configurado para mantener una salida compatible con versiones +anteriores. Sin embargo, puedes ajustar los formateadores para satisfacer tus requisitos. +Los formateadores se configuran junto al motor de registro:: use Cake\Log\Engine\SyslogLog; use App\Log\Formatter\CustomFormatter; - // Simple formatting configuration with no options. + // Configuración de formato simple sin opciones. Log::setConfig('error', [ 'className' => SyslogLog::class, 'formatter' => CustomFormatter::class, ]); - // Configure a formatter with additional options. + // Configurar un formateador con algunas opciones. Log::setConfig('error', [ 'className' => SyslogLog::class, 'formatter' => [ @@ -377,10 +371,12 @@ alongside the logging engine:: ], ]); -To implement your own logging formatter you need to extend -``Cake\Log\Format\AbstractFormatter`` or one of its subclasses. The primary -method you need to implement is ``format($level, $message, $context)`` which is -responsible for formatting log messages. + +Para implementar tu propio formateador de registro, necesitas extender +``Cake\Log\Format\AbstractFormatter`` o una de sus subclases. El método principal que +debes implementar es ``format($level, $message, $context)`` que es responsable de +formatear los mensajes de log. + Log API ======= @@ -389,46 +385,45 @@ Log API .. php:class:: Log - A simple class for writing to logs. +Una clase sencilla para escribir logs. .. php:staticmethod:: setConfig($key, $config) - :param string $name: Name for the logger being connected, used - to drop a logger later on. - :param array $config: Array of configuration information and - constructor arguments for the logger. + :param string $name: Nombre para el registro al que se está conectando, utilizado para + eliminar un registro más adelante. + :param array $config: Arreglo de configuración y argumentos del constructor para el ``logger``. - Get or set the configuration for a Logger. See :ref:`log-configuration` for - more information. + Devuelve o establece la configuración de un ``logger``. Para mas información ver :ref:`log-configuration`. .. php:staticmethod:: configured() - :returns: An array of configured loggers. + :returns: Arreglo de los ``loggers`` configurados - Get the names of the configured loggers. + Devuelve los nombres de los ``loggers`` configurados. .. php:staticmethod:: drop($name) - :param string $name: Name of the logger you wish to no longer receive - messages. + :param string $name: Nombre del ``logger`` del que ya no deseas recibir mensajes. .. php:staticmethod:: write($level, $message, $scope = []) - Write a message into all the configured loggers. - ``$level`` indicates the level of log message being created. - ``$message`` is the message of the log entry being written to. - ``$scope`` is the scope(s) a log message is being created in. + Escribe un mensaje en todos los ``loggers`` configurados + ``$level`` indica el nivel del mensaje de registro que se está creando. + ``$message`` es el mensaje de la entrada del registro que se está escribiendo. + ``$scope`` es el(los) ámbito(s) en el que se está creando un mensaje de registro. .. php:staticmethod:: levels() -Call this method without arguments, eg: `Log::levels()` to obtain current -level configuration. -Convenience Methods -------------------- +Llama a este método sin argumentos, por ejemplo: `Log::levels()` para obtener +la configuración actual del nivel. -The following convenience methods were added to log `$message` with the -appropriate log level. + +Métodos de conveniencia +------------------------ + +Se agregaron los siguientes métodos útiles para registrar `$message` con el nivel +de registro apropiado. .. php:staticmethod:: emergency($message, $scope = []) .. php:staticmethod:: alert($message, $scope = []) @@ -440,26 +435,26 @@ appropriate log level. .. php:staticmethod:: debug($message, $scope = []) Logging Trait -============= +============== .. php:trait:: LogTrait - A trait that provides shortcut methods for logging + Un ``trait`` que proporciona métodos abreviados para el registro de mensajes. .. php:method:: log($msg, $level = LOG_ERR) - Log a message to the logs. By default messages are logged as - ERROR messages. + Agregar un mensaje al log. De forma predeterminada, los mensajes se registran + como mensajes de ERROR. -Using Monolog -============= -Monolog is a popular logger for PHP. Since it implements the same interfaces as -the CakePHP loggers, you can use them in your application as the default -logger. +Usando Monolog +================ + +Monolog es una librería de logging popular en PHP. Dado que implementa las mismas interfaces +que los ``loggers`` de CakePHP, puedes usarlos en tu aplicación como el ``logger`` predeterminado. -After installing Monolog using composer, configure the logger using the -``Log::setConfig()`` method:: +Una vez instalado Monolog utilizando composer, configura el ``logger`` usando el método +``Log::setConfig()``:: // config/bootstrap.php @@ -468,15 +463,15 @@ After installing Monolog using composer, configure the logger using the Log::setConfig('default', function () { $log = new Logger('app'); - $log->pushHandler(new StreamHandler('path/to/your/combined.log')); + $log->pushHandler(new StreamHandler('ruta/a/tu/combined.log')); return $log; }); - // Optionally stop using the now redundant default loggers + // Opcionalmente deja de usar los ``loggers`` predeterminados que ahora son redundantes. Log::drop('debug'); Log::drop('error'); -Use similar methods if you want to configure a different logger for your console:: +Utiliza métodos similares si deseas configurar un ``logger`` diferente para tu consola:: // config/bootstrap_cli.php @@ -485,20 +480,20 @@ Use similar methods if you want to configure a different logger for your console Log::setConfig('default', function () { $log = new Logger('cli'); - $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log')); + $log->pushHandler(new StreamHandler('ruta/a/tu/combined-cli.log')); return $log; }); - // Optionally stop using the now redundant default CLI loggers + // Opcionalmente deja de usar los ``logger`` predeterminados redundantes para la línea de comando. Configure::delete('Log.debug'); Configure::delete('Log.error'); .. note:: - When using a console specific logger, make sure to conditionally configure - your application logger. This will prevent duplicate log entries. + Cuando uses un ``logger`` específico para la consola, asegúrate de configurar condicionalmente tu ``logger`` de aplicación. + Esto evitará entradas de registro duplicadas. .. meta:: - :title lang=en: Logging - :description lang=en: Log CakePHP data to the disk to help debug your application over longer periods of time. - :keywords lang=en: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs + :title lang=es: Logging + :description lang=en: Registra datos de CakePHP a disco para ayudar a depurar la aplicación a lo largo de largos períodos de tiempo + :keywords lang=en: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs, bitácora de eventos, registro de datos, registro, depuración From 227bbe2ed21441acdc1e2edd7e370a302dcc5347 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Tue, 24 Oct 2023 18:04:56 +0200 Subject: [PATCH 090/337] [es] WIP logging translation --- es/core-libraries/logging.rst | 99 ++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 48 deletions(-) diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index e645f7ccee..5670cf5caa 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -1,36 +1,40 @@ Logging ####### -While CakePHP core Configure Class settings can really help you see -what's happening under the hood, there are certain times that -you'll need to log data to the disk in order to find out what's -going on. With technologies like SOAP, AJAX, and REST APIs, debugging can be -rather difficult. +Si bien la configuración de la clase Configure de CakePHP puede ayudarte a ver +lo que está sucediendo en el sistema, hay momentos en los que necesitarás registrar +datos en el disco para averiguar lo que está ocurriendo. Con tecnologías como SOAP, AJAX y APIs REST, +la depuración puede ser bastante difícil. -Logging can also be a way to find out what's been going on in your -application over time. What search terms are being used? What sorts -of errors are my users being shown? How often is a particular query -being executed? +Logging también puede ser una forma de averiguar lo que ha estado ocurriendo +en tu aplicación con el tiempo. ¿Qué términos de búsqueda se están utilizando? +¿Qué tipos de errores están viendo mis usuarios? ¿Con qué frecuencia se ejecuta +una consulta en particular? Logging data in CakePHP is done with the ``log()`` function. It is provided by the ``LogTrait``, which is the common ancestor for many CakePHP classes. If the context is a CakePHP class (Controller, Component, View,...), you can log your data. You can also use ``Log::write()`` directly. See :ref:`writing-to-logs`. +El registro de datos en CakePHP se realiza con la función "log()". Esta función es proporcionada por el +"LogTrait", que es el ancestro común de muchas clases de CakePHP. Si el contexto es una clase de CakePHP +(Controlador, Componente, Vista, etc.), puedes registrar tus datos. También puedes usar "Log::write()" +directamente. Consulta la sección :ref:`writing-to-logs` para obtener más información. + .. _log-configuration: Logging Configuration ===================== -Configuring ``Log`` should be done during your application's bootstrap phase. -The **config/app.php** file is intended for just this. You can define -as many or as few loggers as your application needs. Loggers should be -configured using :php:class:`Cake\\Log\\Log`. An example would be:: +La configuración de "Log" debe realizarse durante la fase de arranque de tu aplicación. +El archivo **config/app.php** está diseñado precisamente para esto. Puedes definir tantos +``loggers`` como necesite tu aplicación. Los ``loggers`` deben configurarse utilizando la clase +:php:class:`Cake\\Log\\Log`. Un ejemplo sería:: use Cake\Log\Engine\FileLog; use Cake\Log\Log; - // Classname using logger 'class' constant + // Nombre de la clase utilizando la constante 'class' del logger. Log::setConfig('info', [ 'className' => FileLog::class, 'path' => LOGS, @@ -38,7 +42,7 @@ configured using :php:class:`Cake\\Log\\Log`. An example would be:: 'file' => 'info', ]); - // Short classname + // Nombre de clase corto Log::setConfig('debug', [ 'className' => 'File', 'path' => LOGS, @@ -54,64 +58,63 @@ configured using :php:class:`Cake\\Log\\Log`. An example would be:: 'file' => 'error', ]); -The above creates three loggers, named ``info``, ``debug`` and ``error``. -Each is configured to handle different levels of messages. They also store their -log messages in separate files, so we can separate debug/notice/info logs -from more serious errors. See the section on :ref:`logging-levels` for more -information on the different levels and what they mean. +Lo anterior crea tres loggers, llamados ``info``, ``debug`` and ``error``. +Cada uno está configurado para manejar diferentes niveles de mensajes. +También almacenan sus mensajes de registro en archivos separados, de esta manera, +podemos separar los registros de depuración/aviso/información de los errores más graves. +Consulta la sección sobr :ref:`logging-levels` para obtener más información sobre +los diferentes niveles y lo que significan. -Once a configuration is created you cannot change it. Instead you should drop -the configuration and re-create it using :php:meth:`Cake\\Log\\Log::drop()` and +Una vez que se crea una configuración, no se puede cambiar. En su lugar, debes eliminar +la configuración y volver a crearla utilizando :php:meth:`Cake\\Log\\Log::drop()` y :php:meth:`Cake\\Log\\Log::setConfig()`. -It is also possible to create loggers by providing a closure. This is useful -when you need full control over how the logger object is built. The closure -has to return the constructed logger instance. For example:: +ambién es posible crear loggers proporcionando un cierre (closure). Esto es útil +cuando necesitas un control completo sobre cómo se construye el objeto del logger. El cierre +debe devolver la instancia del logger. Por ejemplo:: Log::setConfig('special', function () { return new \Cake\Log\Engine\FileLog(['path' => LOGS, 'file' => 'log']); }); -Configuration options can also be provided as a :term:`DSN` string. This is -useful when working with environment variables or :term:`PaaS` providers:: + +Las opciones de configuración también se pueden proporcionar como una cadena :term:`DSN`. Esto es +útil cuando se trabaja con variables de entorno o proveedores :term:`PaaS`:: Log::setConfig('error', [ 'url' => 'file:///full/path/to/logs/?levels[]=warning&levels[]=error&file=error', ]); .. warning:: - If you do not configure logging engines, log messages will not be stored. + Si no configuras motores de registro (logging), los mensajes de log no se almacenarán. -Error and Exception Logging -=========================== +Registro de Errores y Excepciones +================================= -Errors and Exceptions can also be logged. By configuring the corresponding -values in your **config/app.php** file. Errors will be displayed when debug is -``true`` and logged when debug is ``false``. To log uncaught exceptions, set the -``log`` option to ``true``. See :doc:`/development/configuration` for more -information. +Los errores y excepciones también pueden registrarse configurando los valores correspondientes en tu archivo **config/app.php**. +Los errores se mostrarán cuando el modo de depuración esté en ``true`` y se registrarán en los archivos de log cuando el modo de depuración esté en ``false``. +Para registrar excepciones no capturadas, configura la opción ``log`` como ``true``. +Consulta ::doc:`/development/configuration` para obtener más información. .. _writing-to-logs: -Writing to Logs -=============== +Escribiendo en los archivos de Log +=================================== -Writing to the log files can be done in two different ways. The first -is to use the static :php:meth:`Cake\\Log\\Log::write()` method:: +Escribir en los archivos de registro se puede hacer de dos maneras diferentes. La primera es +utilizando el método estático ::php:meth:`Cake\\Log\\Log::write()`:: Log::write('debug', 'Something did not work'); -The second is to use the ``log()`` shortcut function available on any -class using the ``LogTrait``. Calling ``log()`` will internally call -``Log::write()``:: +La segunda opción es utilizar la función de acceso directo ``log()`` disponible en cualquier clase +que utilice el ``LogTrait``. Llamar a``log()`` llamará internamente a``Log::write()``:: - // Executing this inside a class using LogTrait + // Ejecutando esto dentro de una clase que utiliza LogTrait $this->log('Something did not work!', 'debug'); -All configured log streams are written to sequentially each time -:php:meth:`Cake\\Log\\Log::write()` is called. If you have not configured any -logging engines ``log()`` will return ``false`` and no log messages will be -written. +Todos los log configurados se escriben secuencialmente cada vez que se llama a +:php:meth:`Cake\\Log\\Log::write()`. Si no has configurado ningún motor de registro, +``log()`` devolverá "false" y no se escribirán mensajes de registro. Using Placeholders in Messages ------------------------------ @@ -495,6 +498,6 @@ Use similar methods if you want to configure a different logger for your console your application logger. This will prevent duplicate log entries. .. meta:: - :title lang=es: Registro (Logging) + :title lang=en: Logging :description lang=en: Log CakePHP data to the disk to help debug your application over longer periods of time. :keywords lang=en: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs From 285ff797016757a0ce8fa402bee2f8e5a17632e8 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Wed, 25 Oct 2023 17:32:14 +0200 Subject: [PATCH 091/337] [es] WIP logging translation --- es/core-libraries/logging.rst | 95 ++++++++++++++++++----------------- 1 file changed, 48 insertions(+), 47 deletions(-) diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index 5670cf5caa..66081f5d77 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -112,28 +112,30 @@ que utilice el ``LogTrait``. Llamar a``log()`` llamará internamente a``Log::wri // Ejecutando esto dentro de una clase que utiliza LogTrait $this->log('Something did not work!', 'debug'); -Todos los log configurados se escriben secuencialmente cada vez que se llama a +Todos los ``log`` configurados se escriben secuencialmente cada vez que se llama a :php:meth:`Cake\\Log\\Log::write()`. Si no has configurado ningún motor de registro, ``log()`` devolverá "false" y no se escribirán mensajes de registro. -Using Placeholders in Messages ------------------------------- +Usando marcadores de posición (placeholders) en mensajes +----------------------------------------------- -If you need to log dynamically defined data, you can use placeholders in your -log messages and provide an array of key/value pairs in the ``$context`` -parameter:: +Si necesitas registrar datos definidos dinámicamente, puedes utilizar marcadores de posición en tus +mensajes de registro y proporcionar un array de pares clave/valor en el parámetro ``$context`` +como sigue:: - // Will log `Could not process for userid=1` - Log::write('error', 'Could not process for userid={user}', ['user' => $user->id]); -Placeholders that do not have keys defined will not be replaced. If you need to -use a literal braced word, you must escape the placeholder:: + // Se registrará `No se pudo procesar para el usuario id = 1` + Log::write('error', 'No se pudo procesar para el usuario id ={user}', ['user' => $user->id]); - // Will log `No {replace}` +Los marcadores (placeholders) que no tienen claves definidas no serán reemplazados. +Si necesitas utilizar una palabra entre llaves de forma literal, debes escapar el marcador:: + + + // Se registrará `No {replace}` Log::write('error', 'No \\{replace}', ['replace' => 'no']); -If you include objects in your logging placeholders those objects must implement -one of the following methods: +Si incluyes objetos en los marcadores, esos objetos deben implementar +uno de los siguientes métodos: * ``__toString()`` * ``toArray()`` @@ -141,49 +143,48 @@ one of the following methods: .. _logging-levels: -Using Levels ------------- +Usando Niveles +--------------- -CakePHP supports the standard POSIX set of logging levels. Each level represents -an increasing level of severity: +CakePHP admite el conjunto estándar de niveles de registro POSIX. Cada nivel representa un aumento +en el nivel de gravedad: -* Emergency: system is unusable -* Alert: action must be taken immediately -* Critical: critical conditions -* Error: error conditions -* Warning: warning conditions -* Notice: normal but significant condition -* Info: informational messages -* Debug: debug-level messages +* Emergency: el sistema no es utilizable +* Alert: se debe tomar una acción inmediata +* Critical: condiciones críticas +* Error: condiciones de error +* Warning: condiciones de advertencia +* Notice: condiciones normales pero significativas +* Info: mensajes informativos +* Debug: mensajes de depuración -You can refer to these levels by name when configuring loggers, and when writing -log messages. Alternatively, you can use convenience methods like -:php:meth:`Cake\\Log\\Log::error()` to clearly indicate the logging -level. Using a level that is not in the above levels will result in an -exception. +Puedes hacer referencia a estos niveles por nombre al configurar lo ``loggers`` y al escribir +mensajes de registro. Alternativamente, puedes utilizar métodos de conveniencia como : +:php:meth:`Cake\\Log\\Log::error()` para indicar claramente el nivel de registro. +Utilizar un nivel que no esté en la lista de niveles anteriores resultará en una excepción. .. note:: - When ``levels`` is set to an empty value in a logger's configuration, it - will take messages of any level. + Cuando ``levels`` se establece en un valor vacío en la configuración de un ``logger``, + aceptará mensajes de cualquier nivel. .. _logging-scopes: -Logging Scopes --------------- +Ámbitos de Registro (scope) +---------------------------- -Often times you'll want to configure different logging behavior for different -subsystems or parts of your application. Take for example an e-commerce shop. -You'll probably want to handle logging for orders and payments differently than -you do other less critical logs. +En muchas ocasiones, querrás configurar diferentes comportamientos de registro para diferentes +subsistemas o partes de tu aplicación. Tomemos como ejemplo una tienda en línea. +Probablemente quieras manejar el registro de pedidos y pagos de manera diferente a como lo haces +con otros registros menos críticos. -CakePHP exposes this concept as logging scopes. When log messages are written -you can include a scope name. If there is a configured logger for that scope, -the log messages will be directed to those loggers. For example:: +CakePHP expone este concepto como ámbitos de registro. Cuando se escriben mensajes de registro, +puedes incluir un nombre de ámbito ``scope``. Si hay un registrador configurado para ese ámbito, +los mensajes de registro se dirigirán a esos ``loggers``. Por ejemplo:: use Cake\Log\Engine\FileLog; - // Configure logs/shops.log to receive all levels, but only - // those with `orders` and `payments` scope. + // Configura logs/shops.log para recibir todos los niveles, pero solo aquellos con ``scope`` + // `orders` y `payments`. Log::setConfig('shops', [ 'className' => FileLog::class, 'path' => LOGS, @@ -192,8 +193,8 @@ the log messages will be directed to those loggers. For example:: 'file' => 'shops.log', ]); - // Configure logs/payments.log to receive all levels, but only - // those with `payments` scope. + // Configura logs/payments.log para recibir todos los niveles, pero solo aquellos con ``scope`` + // `payments`. Log::setConfig('payments', [ 'className' => FileLog::class, 'path' => LOGS, @@ -205,8 +206,8 @@ the log messages will be directed to those loggers. For example:: Log::warning('this gets written only to shops.log', ['scope' => ['orders']]); Log::warning('this gets written to both shops.log and payments.log', ['scope' => ['payments']]); -Scopes can also be passed as a single string or a numerically indexed array. -Note that using this form will limit the ability to pass more data as context:: +Los ``scopes`` también se pueden pasar como una cadena única o como una matriz indexada numéricamente. +Ten en cuenta que al usar esta forma, se limitará la capacidad de pasar más datos como contexto:: Log::warning('This is a warning', ['orders']); Log::warning('This is a warning', 'payments'); From 6567e54ce3abd49a53d1cfd6eacba7705012d1c5 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Mon, 30 Oct 2023 20:39:46 +0100 Subject: [PATCH 092/337] [es] logging translation --- es/core-libraries/logging.rst | 253 +++++++++++++++++----------------- 1 file changed, 124 insertions(+), 129 deletions(-) diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index 66081f5d77..639d42a61c 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -26,7 +26,7 @@ directamente. Consulta la sección :ref:`writing-to-logs` para obtener más info Logging Configuration ===================== -La configuración de "Log" debe realizarse durante la fase de arranque de tu aplicación. +La configuración de ``Log`` debe realizarse durante la fase de arranque de tu aplicación. El archivo **config/app.php** está diseñado precisamente para esto. Puedes definir tantos ``loggers`` como necesite tu aplicación. Los ``loggers`` deben configurarse utilizando la clase :php:class:`Cake\\Log\\Log`. Un ejemplo sería:: @@ -117,7 +117,7 @@ Todos los ``log`` configurados se escriben secuencialmente cada vez que se llama ``log()`` devolverá "false" y no se escribirán mensajes de registro. Usando marcadores de posición (placeholders) en mensajes ------------------------------------------------ +--------------------------------------------------------- Si necesitas registrar datos definidos dinámicamente, puedes utilizar marcadores de posición en tus mensajes de registro y proporcionar un array de pares clave/valor en el parámetro ``$context`` @@ -213,119 +213,113 @@ Ten en cuenta que al usar esta forma, se limitará la capacidad de pasar más da Log::warning('This is a warning', 'payments'); .. note:: - When ``scopes`` is set to an empty array or ``null`` in a logger's - configuration, it will take messages of any scope. Setting it to ``false`` - will only match messages without scope. + Cuando ``scopes`` se establece como un arreglo vacío o null en la configuración de un ``logger``, + aceptará mensajes de cualquier ``scope``. Establecerlo como false solo coincidirá con mensajes sin ``scope``. .. _file-log: -Logging to Files -================ +Guardando logs en Archivos +=========================== -As its name implies ``FileLog`` writes log messages to files. The level of log -message being written determines the name of the file the message is stored in. -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**:: +Como su nombre indica, ``FileLog`` escribe mensajes de registro en archivos. El nivel del mensaje +de registro que se está escribiendo determina el nombre del archivo en el que se almacena el mensaje. +Si no se proporciona un nivel, se utiliza :php:const:`LOG_ERR`, que escribe en el registro de errores. +La ubicación de registro predeterminada es **logs/$level.log**:: - // Executing this inside a CakePHP class + // Es ejecutado asi dentro de una clase CakePHP $this->log("Something didn't work!"); - // Results in this being appended to logs/error.log + // Se añadirá lo siguiente al archivo logs/error.log. // 2007-11-02 10:22:02 Error: Something didn't work! -The configured directory must be writable by the web server user in -order for logging to work correctly. +El directorio configurado debe tener permisos de escritura por el usuario del servidor web para +que el registro funcione correctamente. -You can configure additional/alternate FileLog locations when configuring -a logger. FileLog accepts a ``path`` which allows for -custom paths to be used:: +Puedes configurar ubicaciones adicionales o alternativas para FileLog al configurar un registrador. +FileLog acepta un "path" que permite utilizar rutas personalizadas:: Log::setConfig('custom_path', [ 'className' => 'File', 'path' => '/path/to/custom/place/' ]); -``FileLog`` engine takes the following options: +El motor de ``FileLog`` toma las siguientes opciones: -* ``size`` Used to implement basic log file rotation. If log file size - reaches specified size the existing file is renamed by appending timestamp - to filename and new log file is created. Can be integer bytes value or - human readable string values like '10MB', '100KB' etc. Defaults to 10MB. -* ``rotate`` Log files are rotated specified times before being removed. - If value is 0, old versions are removed rather then rotated. Defaults to 10. -* ``mask`` Set the file permissions for created files. If left empty the default - permissions are used. +* ``size`` Se utiliza para implementar una rotación básica de archivos de registro. Si el tamaño + del archivo de registro alcanza el tamaño especificado, el archivo existente se renombra agregando + una marca de tiempo al nombre de archivo y se crea un nuevo archivo de registro. Puede ser un valor + entero en bytes o valores como '10MB', '100KB', etc. El valor predeterminado es 10MB. +* ``rotate`` Los archivos de registro se rotan un número especificado de veces antes de ser eliminados. + Si el valor es 0, se eliminan las versiones antiguas en lugar de rotarlas. El valor predeterminado es 10. +* ``mask`` Establece los permisos de archivo para los archivos creados. Si se deja vacío, se utilizan + los permisos predeterminados. .. note:: - Missing directories will be automatically created to avoid - unnecessary errors thrown when using the FileEngine. + Los directorios faltantes se crearán automáticamente para evitar errores innecesarios + cuando se utiliza FileEngine. .. _syslog-log: -Logging to Syslog -================= +Guardando logs en Syslog +========================= -In production environments it is highly recommended that you setup your system to -use syslog instead of the file logger. This will perform much better as any -writes will be done in a (almost) non-blocking fashion and your operating system -logger can be configured separately to rotate files, pre-process writes or use -a completely different storage for your logs. +En entornos de producción, se recomienda encarecidamente configurar tu sistema para utilizar el +syslog en lugar del guardar los logs en archivos. Esto mejorará el rendimiento, ya que cualquier +escritura se realizará de manera (casi) no bloqueante y el ``logger`` del sistema operativo se +puede configurar de forma independiente para rotar archivos, preprocesar escrituras o +utilizar un almacenamiento completamente diferente para tus registros. -Using syslog is pretty much like using the default FileLog engine, you just need -to specify ``Syslog`` as the engine to be used for logging. The following -configuration snippet will replace the default logger with syslog, this should -be done in the **config/bootstrap.php** file:: +Usar syslog es prácticamente como usar el motor de registro de archivos predeterminado, simplemente +necesitas especificar ``Syslog`` como el motor a utilizar para el registro de logs. El siguiente +fragmento de configuración reemplazará el ``logger`` predeterminado con syslog, esto se debe hacer +en el archivo **config/bootstrap.php**":: Log::setConfig('default', [ 'engine' => 'Syslog' ]); -The configuration array accepted for the Syslog logging engine understands the -following keys: - -* ``format``: An sprintf template string with two placeholders, the first one - for the error level, and the second for the message itself. This key is - useful to add additional information about the server or process in the - logged message. For example: ``%s - Web Server 1 - %s`` will look like - ``error - Web Server 1 - An error occurred in this request`` after - replacing the placeholders. This option is deprecated. You should use - :ref:`logging-formatters` instead. -* ``prefix``: An string that will be prefixed to every logged message. -* ``flag``: An integer flag to be used for opening the connection to the - logger, by default ``LOG_ODELAY`` will be used. See ``openlog`` documentation - for more options -* ``facility``: The logging slot to use in syslog. By default ``LOG_USER`` is - used. See ``syslog`` documentation for more options - -Creating Log Engines -===================== +El arreglo de configuración aceptado para el motor de registro Syslog comprende +las siguientes claves: +* ``format``: Una cadena de plantilla sprintf con dos marcadores de posición (placeholdes), + el primero para el nivel de error y el segundo para el mensaje en sí. Esta clave es + útil para agregar información adicional sobre el servidor o el proceso en el mensaje + registrado. Por ejemplo: ``%s -Servidor web 1 - %s`` se verá como + ``error - Servidor web 1 - Ocurrió un error en esta solicitud`` después de reemplazar + los placeholders. Esta opción está obsoleta. Deberías usar :ref:`logging-formatters` en su lugar. +* ``prefix``: Una cadena que se utilizará como prefijo para cada mensaje registrado. +* ``flag``: Una bandera tipo ``int`` que se usará para abrir la conexión al registro, + por defecto se usará ``LOG_ODELAY```. Consulta la documentación de ``openlog`` para ver más opciones. +* ``facility``: El espacio de registro a utilizar en syslog. Por defecto se utiliza ``LOG_USER``. + Consulta la documentación de ``syslog`` para ver más opciones. + +Creación de Motores de Logs +================================= -Log engines can be part of your application, or part of -plugins. If for example you had a database logger called -``DatabaseLog``. As part of your application it would be placed in -**src/Log/Engine/DatabaseLog.php**. As part of a plugin it would be placed in -**plugins/LoggingPack/src/Log/Engine/DatabaseLog.php**. To configure log -engine you should use :php:meth:`Cake\\Log\\Log::setConfig()`. For example -configuring our DatabaseLog would look like:: +Los motores de registro pueden formar parte de tu aplicación o de plugins. Por ejemplo, +si tuvieras un registro en base de datos llamado ``DatabaseLog``, como parte de tu aplicación +se colocaría en **src/Log/Engine/DatabaseLog.php**. Como parte de un plugin se colocaría en +**plugins/LoggingPack/src/Log/Engine/DatabaseLog.php**. Para configurar el motor de registro, +debes usar :php:meth:`Cake\\Log\\Log::setConfig()`. Por ejemplo, la configuración de nuestro +DatabaseLog se vería así:: - // For src/Log + // Para src/Log Log::setConfig('otherFile', [ 'className' => 'Database', 'model' => 'LogEntry', // ... ]); - // For plugin called LoggingPack + // Para el plugin llamado LoggingPack Log::setConfig('otherFile', [ 'className' => 'LoggingPack.Database', 'model' => 'LogEntry', // ... ]); -When configuring a log engine the ``className`` parameter is used to -locate and load the log handler. All of the other configuration -properties are passed to the log engine's constructor as an array. :: +Al configurar un motor de registro, el parámetro ``className`` se utiliza para localizar +y cargar el controlador de registro. Todas las demás propiedades de configuración se pasan +al constructor del motor de registro como un array.:: namespace App\Log\Engine; use Cake\Log\Engine\BaseLog; @@ -344,31 +338,31 @@ properties are passed to the log engine's constructor as an array. :: } } -CakePHP requires that all logging engine implement ``Psr\Log\LoggerInterface``. -The class :php:class:`Cake\Log\Engine\BaseLog` is an easy way to satisfy the -interface as it only requires you to implement the ``log()`` method. +CakePHP requiere que todos los motores de registro implementen Psr\Log\LoggerInterface. +La clase :php:class:`Cake\Log\Engine\BaseLog` es una forma sencilla de cumplir con la interfaz, +ya que solo requiere que implementes el método log(). .. _logging-formatters: -Logging Formatters ------------------- -Logging formatters allow you to control how log messages are formatted -independent of the storage engine. Each core provided logging engine comes with -a formatter configured to maintain backwards compatible output. However, you can -adjust the formatters to fit your requirements. Formatters are configured -alongside the logging engine:: +Formateadores de Logs +--------------------------- +Los formateadores de registro te permiten controlar cómo se formatean los mensajes de registro +de forma independiente al motor de almacenamiento. Cada motor de registro proporcionado por +defecto viene con un formateador configurado para mantener una salida compatible con versiones +anteriores. Sin embargo, puedes ajustar los formateadores para satisfacer tus requisitos. +Los formateadores se configuran junto al motor de registro:: use Cake\Log\Engine\SyslogLog; use App\Log\Formatter\CustomFormatter; - // Simple formatting configuration with no options. + // Configuración de formato simple sin opciones. Log::setConfig('error', [ 'className' => SyslogLog::class, 'formatter' => CustomFormatter::class, ]); - // Configure a formatter with additional options. + // Configurar un formateador con algunas opciones. Log::setConfig('error', [ 'className' => SyslogLog::class, 'formatter' => [ @@ -377,10 +371,12 @@ alongside the logging engine:: ], ]); -To implement your own logging formatter you need to extend -``Cake\Log\Format\AbstractFormatter`` or one of its subclasses. The primary -method you need to implement is ``format($level, $message, $context)`` which is -responsible for formatting log messages. + +Para implementar tu propio formateador de registro, necesitas extender +``Cake\Log\Format\AbstractFormatter`` o una de sus subclases. El método principal que +debes implementar es ``format($level, $message, $context)`` que es responsable de +formatear los mensajes de log. + Log API ======= @@ -389,46 +385,45 @@ Log API .. php:class:: Log - A simple class for writing to logs. +Una clase sencilla para escribir logs. .. php:staticmethod:: setConfig($key, $config) - :param string $name: Name for the logger being connected, used - to drop a logger later on. - :param array $config: Array of configuration information and - constructor arguments for the logger. + :param string $name: Nombre para el registro al que se está conectando, utilizado para + eliminar un registro más adelante. + :param array $config: Arreglo de configuración y argumentos del constructor para el ``logger``. - Get or set the configuration for a Logger. See :ref:`log-configuration` for - more information. + Devuelve o establece la configuración de un ``logger``. Para mas información ver :ref:`log-configuration`. .. php:staticmethod:: configured() - :returns: An array of configured loggers. + :returns: Arreglo de los ``loggers`` configurados - Get the names of the configured loggers. + Devuelve los nombres de los ``loggers`` configurados. .. php:staticmethod:: drop($name) - :param string $name: Name of the logger you wish to no longer receive - messages. + :param string $name: Nombre del ``logger`` del que ya no deseas recibir mensajes. .. php:staticmethod:: write($level, $message, $scope = []) - Write a message into all the configured loggers. - ``$level`` indicates the level of log message being created. - ``$message`` is the message of the log entry being written to. - ``$scope`` is the scope(s) a log message is being created in. + Escribe un mensaje en todos los ``loggers`` configurados + ``$level`` indica el nivel del mensaje de registro que se está creando. + ``$message`` es el mensaje de la entrada del registro que se está escribiendo. + ``$scope`` es el(los) ámbito(s) en el que se está creando un mensaje de registro. .. php:staticmethod:: levels() -Call this method without arguments, eg: `Log::levels()` to obtain current -level configuration. -Convenience Methods -------------------- +Llama a este método sin argumentos, por ejemplo: `Log::levels()` para obtener +la configuración actual del nivel. -The following convenience methods were added to log `$message` with the -appropriate log level. + +Métodos de conveniencia +------------------------ + +Se agregaron los siguientes métodos útiles para registrar `$message` con el nivel +de registro apropiado. .. php:staticmethod:: emergency($message, $scope = []) .. php:staticmethod:: alert($message, $scope = []) @@ -440,26 +435,26 @@ appropriate log level. .. php:staticmethod:: debug($message, $scope = []) Logging Trait -============= +============== .. php:trait:: LogTrait - A trait that provides shortcut methods for logging + Un ``trait`` que proporciona métodos abreviados para el registro de mensajes. .. php:method:: log($msg, $level = LOG_ERR) - Log a message to the logs. By default messages are logged as - ERROR messages. + Agregar un mensaje al log. De forma predeterminada, los mensajes se registran + como mensajes de ERROR. -Using Monolog -============= -Monolog is a popular logger for PHP. Since it implements the same interfaces as -the CakePHP loggers, you can use them in your application as the default -logger. +Usando Monolog +================ + +Monolog es una librería de logging popular en PHP. Dado que implementa las mismas interfaces +que los ``loggers`` de CakePHP, puedes usarlos en tu aplicación como el ``logger`` predeterminado. -After installing Monolog using composer, configure the logger using the -``Log::setConfig()`` method:: +Una vez instalado Monolog utilizando composer, configura el ``logger`` usando el método +``Log::setConfig()``:: // config/bootstrap.php @@ -468,15 +463,15 @@ After installing Monolog using composer, configure the logger using the Log::setConfig('default', function () { $log = new Logger('app'); - $log->pushHandler(new StreamHandler('path/to/your/combined.log')); + $log->pushHandler(new StreamHandler('ruta/a/tu/combined.log')); return $log; }); - // Optionally stop using the now redundant default loggers + // Opcionalmente deja de usar los ``loggers`` predeterminados que ahora son redundantes. Log::drop('debug'); Log::drop('error'); -Use similar methods if you want to configure a different logger for your console:: +Utiliza métodos similares si deseas configurar un ``logger`` diferente para tu consola:: // config/bootstrap_cli.php @@ -485,20 +480,20 @@ Use similar methods if you want to configure a different logger for your console Log::setConfig('default', function () { $log = new Logger('cli'); - $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log')); + $log->pushHandler(new StreamHandler('ruta/a/tu/combined-cli.log')); return $log; }); - // Optionally stop using the now redundant default CLI loggers + // Opcionalmente deja de usar los ``logger`` predeterminados redundantes para la línea de comando. Configure::delete('Log.debug'); Configure::delete('Log.error'); .. note:: - When using a console specific logger, make sure to conditionally configure - your application logger. This will prevent duplicate log entries. + Cuando uses un ``logger`` específico para la consola, asegúrate de configurar condicionalmente tu ``logger`` de aplicación. + Esto evitará entradas de registro duplicadas. .. meta:: - :title lang=en: Logging - :description lang=en: Log CakePHP data to the disk to help debug your application over longer periods of time. - :keywords lang=en: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs + :title lang=es: Logging + :description lang=en: Registra datos de CakePHP a disco para ayudar a depurar la aplicación a lo largo de largos períodos de tiempo + :keywords lang=en: cakephp logging,log errors,debug,logging data,cakelog class,ajax logging,soap logging,debugging,logs, bitácora de eventos, registro de datos, registro, depuración From 98a6d25cb178a7f76258d94bc4817f2c410b7055 Mon Sep 17 00:00:00 2001 From: Yelitza Parra Date: Mon, 30 Oct 2023 20:50:32 +0100 Subject: [PATCH 093/337] fixing identation --- es/core-libraries/logging.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index 639d42a61c..bd497c38f7 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -281,6 +281,7 @@ en el archivo **config/bootstrap.php**":: El arreglo de configuración aceptado para el motor de registro Syslog comprende las siguientes claves: + * ``format``: Una cadena de plantilla sprintf con dos marcadores de posición (placeholdes), el primero para el nivel de error y el segundo para el mensaje en sí. Esta clave es útil para agregar información adicional sobre el servidor o el proceso en el mensaje From 4e6de8c402586189714da9692be4a8e30cb26ecd Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 2 Nov 2023 03:52:09 +0100 Subject: [PATCH 094/337] Fix rendering --- en/plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/plugins.rst b/en/plugins.rst index 428b6f65a1..51fa7c79ae 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -295,7 +295,7 @@ Plugin Objects Plugin Objects allow a plugin author to define set-up logic, define default hooks, load routes, middleware and console commands. Plugin objects live in -**src/Plugin.php**. For our ContactManager plugin, our plugin class could look +**src/{PluginName}Plugin.php**. For our ContactManager plugin, our plugin class could look like:: namespace ContactManager; From 38c638f9afee4c8cb1dc67c133b75a4560588674 Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 2 Nov 2023 03:58:03 +0100 Subject: [PATCH 095/337] Fix docs about plugin class name --- en/plugins.rst | 8 ++++---- fr/plugins.rst | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/en/plugins.rst b/en/plugins.rst index 51fa7c79ae..31cbbacb52 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -176,7 +176,7 @@ classes:: $plugin->enable('routes'); $this->addPlugin($plugin); -Plugin objects also know their names and path information:: +Plugin classes also know their names and path information:: $plugin = new ContactManagerPlugin(); @@ -290,11 +290,11 @@ autoloader once you've created your plugin: .. _plugin-objects: -Plugin Objects +Plugin Classes ============== -Plugin Objects allow a plugin author to define set-up logic, define default -hooks, load routes, middleware and console commands. Plugin objects live in +Plugin classes allow a plugin author to define set-up logic, define default +hooks, load routes, middleware and console commands. Plugin classes live in **src/{PluginName}Plugin.php**. For our ContactManager plugin, our plugin class could look like:: diff --git a/fr/plugins.rst b/fr/plugins.rst index 47463e9e1e..6d186947a2 100644 --- a/fr/plugins.rst +++ b/fr/plugins.rst @@ -142,7 +142,7 @@ Configuration du Plugin Les plugins proposent plusieurs *hooks* permettant à un plugin de s'injecter lui-même aux endroits appropriés de votre application. Les *hooks* sont: - + * ``bootstrap`` Utilisé pour charger les fichiers de configuration par défaut d'un plugin, définir des constantes et d'autres fonctions globales. * ``routes`` Utilisé pour charger les routes pour un plugin. Il est déclenché @@ -293,7 +293,7 @@ re-générer votre autoloader après avoir créé votre plugin: .. _plugin-objects: -Plugin Objects +Plugin Classes ============== Les Objets Plugin permettent à un auteur de plugin de spécifier une logique de From 8fb81d3b896b9f96a0f2818f51717bf839308dff Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 2 Nov 2023 04:03:02 +0100 Subject: [PATCH 096/337] Simplify paths --- en/development/testing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index a0a20503c0..fe5c74db33 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -324,12 +324,12 @@ file: - ./tests/TestCase/ + tests/TestCase/ - ./plugins/Forum/tests/TestCase/ + plugins/Forum/tests/TestCase/ From 04d6e0e0bf8fb13b6c1fb69773b5577d41e3d1ac Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 2 Nov 2023 04:08:45 +0100 Subject: [PATCH 097/337] FIx CS. --- en/plugins.rst | 1 - en/views/helpers/form.rst | 1 - fr/views/helpers/form.rst | 1 - 3 files changed, 3 deletions(-) diff --git a/en/plugins.rst b/en/plugins.rst index 51fa7c79ae..0177890102 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -309,7 +309,6 @@ like:: class ContactManagerPlugin extends BasePlugin { - /** * @inheritDoc */ diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index f319100f62..5742a08682 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -2478,7 +2478,6 @@ could do the following:: class AutocompleteWidget implements WidgetInterface { - /** * StringTemplate instance. * diff --git a/fr/views/helpers/form.rst b/fr/views/helpers/form.rst index 8a146aa7f9..f9f0250ed4 100644 --- a/fr/views/helpers/form.rst +++ b/fr/views/helpers/form.rst @@ -2512,7 +2512,6 @@ vouliez construire un widget Autocomplete, vous pourriez le faire comme ceci:: class AutocompleteWidget implements WidgetInterface { - /** * StringTemplate instance. * From 714bbe248013f603bfe854e138d04b90b18498d0 Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 9 Nov 2023 15:59:32 +0100 Subject: [PATCH 098/337] Fix up migrator doc --- en/development/testing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index fe5c74db33..8631555d03 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -412,7 +412,7 @@ contains the fixture extension: - + The extension is included in your application and plugins generated by ``bake`` @@ -442,7 +442,7 @@ database schema as well:: // Simple setup for with no plugins $migrator->run(); - // Run migrations for multiple plugins + // Run migrations for a plugin $migrator->run(['plugin' => 'Contacts']); // Run the Documents migrations on the test_docs connection. From 816315c0807d52f63cd46e4726d23ec6a5c14b5a Mon Sep 17 00:00:00 2001 From: Tim Bischoff Date: Fri, 10 Nov 2023 14:57:48 +0100 Subject: [PATCH 099/337] Set union types to class properties in the helpers and components examples (#7763) * Update components.rst Set union types to class properties in the component example * Update helpers.rst Set union types to class properties in the helpers examples --- en/controllers/components.rst | 2 +- en/views/helpers.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/en/controllers/components.rst b/en/controllers/components.rst index fb0b6ea190..774fa65fec 100644 --- a/en/controllers/components.rst +++ b/en/controllers/components.rst @@ -234,7 +234,7 @@ You can load other components by adding them to the `$components` property:: class CustomComponent extends Component { // The other component your component uses - protected $components = ['Existing']; + protected array $components = ['Existing']; // Execute any other additional setup for your component. public function initialize(array $config): void diff --git a/en/views/helpers.rst b/en/views/helpers.rst index 5c603d7789..f393807058 100644 --- a/en/views/helpers.rst +++ b/en/views/helpers.rst @@ -122,7 +122,7 @@ your helper requires. For example:: /** * @var array */ - protected $_defaultConfig = [ + protected array $_defaultConfig = [ 'errorClass' => 'error', 'templates' => [ 'label' => '', @@ -268,7 +268,7 @@ just as you would in a controller:: class LinkHelper extends Helper { - protected $helpers = ['Html']; + protected array $helpers = ['Html']; public function makeEdit($title, $url) { @@ -317,7 +317,7 @@ If you would like to access a View variable inside a helper, you can use class AwesomeHelper extends Helper { - public $helpers = ['Html']; + public array $helpers = ['Html']; public function someMethod() { From 3a4953ba9afe858c7a6feb6423bedbe0e4a3fc4b Mon Sep 17 00:00:00 2001 From: Liqueur de Toile Date: Fri, 10 Nov 2023 18:44:31 +0100 Subject: [PATCH 100/337] Update 5-0-migration-guide.rst Related to https://github.com/cakephp/app/issues/979 --- en/appendices/5-0-migration-guide.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 2ae9e29800..bd825d9f3d 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -28,9 +28,6 @@ Global - 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. -- Global functions are now opt-in. If your application uses global function - aliases be sure to add ``require CAKE . 'functions.php'`` to you application's - ``config/bootstrap.php``. - Use of ``#[\AllowDynamicProperties]`` removed everywhere. It was used for the following classes: - ``Command/Command`` - ``Console/Shell`` From 12d36a20364a15944b58c672242334d5929f4cfe Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 12 Nov 2023 22:47:38 -0500 Subject: [PATCH 101/337] Update docs for requesthandler replacement. I'll backport this to 4.x so that the 5.x migration guide docs provide the solution discussed as part of cakephp/cakephp#17415 --- en/controllers.rst | 16 ++++++++++++++++ en/views.rst | 6 +++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/en/controllers.rst b/en/controllers.rst index 6f6e2810fa..e07343b684 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -374,6 +374,22 @@ view logic:: It is important to remember that match-all views are applied only *after* content-type negotiation is attempted. +Using AjaxView +============== + +In applications that use hypermedia or AJAX clients, you often need to render +view contents without the wrapping layout. You can use the ``AjaxView`` that +is bundled with the application skeleton:: + + // In a controller action, or in beforeRender. + if ($this->request->is('ajax')) { + $this->viewBuilder()->setClassName('Ajax'); + } + +``AjaxView`` will respond as ``text/html`` and use the ``ajax`` layout. +Generally this layout is minimal or contains client specific markup. This +replaces usage of ``RequestHandlerComponent`` automatically using the +``AjaxView`` in 4.x. Redirecting to Other Pages ========================== diff --git a/en/views.rst b/en/views.rst index cfeb8fff7b..2f8f2ddcb5 100644 --- a/en/views.rst +++ b/en/views.rst @@ -117,9 +117,9 @@ Another example, using if/elseif/else. Notice the colons:

    Hi unknown user

    -If you'd prefer using a templating language like -`Twig `_, a subclass of View will bridge your -templating language and CakePHP. +If you'd prefer to use a templating language like +`Twig `_, checkout the `CakePHP Twig Plugin +`__ Template files are stored in **templates/**, in a folder named after the controller that uses the files, and named after the action it corresponds to. From 1d1fcdea81470921b690ac62903b8524f2ca7435 Mon Sep 17 00:00:00 2001 From: Oliver Nowak Date: Mon, 13 Nov 2023 19:57:19 +0100 Subject: [PATCH 102/337] Fix content type negotiation header name. --- en/controllers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/controllers.rst b/en/controllers.rst index e07343b684..831593d0ba 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -286,7 +286,7 @@ Content Type Negotiation Controllers can define a list of view classes they support. After the controller's action is complete CakePHP will use the view list to perform -content-type negotiation with either :ref:`file-extensions` or ``Content-Type`` +content-type negotiation with either :ref:`file-extensions` or ``Accept`` headers. This enables your application to re-use the same controller action to render an HTML view or render a JSON or XML response. To define the list of supported view classes for a controller is done with the ``addViewClasses()`` From 46fcecbed64b609de6b455b08551f3bd23bba8b8 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 16 Nov 2023 10:18:42 -0500 Subject: [PATCH 103/337] Write docs for cakephp/cakephp#17416 --- en/appendices/5-1-upgrade-guide.rst | 3 +++ en/core-libraries/httpclient.rst | 11 +++++++++++ 2 files changed, 14 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 1dd32a3942..b70348b34d 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -14,6 +14,9 @@ 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. Validation ---------- diff --git a/en/core-libraries/httpclient.rst b/en/core-libraries/httpclient.rst index cdb11bcc3b..514568a4be 100644 --- a/en/core-libraries/httpclient.rst +++ b/en/core-libraries/httpclient.rst @@ -358,6 +358,17 @@ method:: ]); $http->addCookie(new Cookie('session', 'abc123')); +Client Events +============= + +``Client`` will emit events when requests are sent. The +``HttpClient.beforeSend`` event is fired before a request is sent, and +``HttpClient.afterSend`` is fired after a request is sent. You can modify the +request, or set a response in a ``beforeSend`` listener. The ``afterSend`` event +is triggered for all requests, even those that have their responses set by +a ``beforeSend`` event. + + .. _httpclient-response-objects: Response Objects From c48f5fa05644f6bb687423f126cce26f6c23b538 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Fri, 17 Nov 2023 09:04:50 +0100 Subject: [PATCH 104/337] replace _cake_core_ with _cake_translations_ cache config --- en/appendices/5-1-upgrade-guide.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index b70348b34d..13ae586242 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -6,6 +6,15 @@ and introduces new deprecations. Any functionality deprecated in 5.x will be removed in 6.0.0. +Deprecations +============ + +I18n +---- + +- The ``_cake_core_`` cache config key has been renamed to ``_cake_translations_``. + + New Features ============ From f7018917347c6cba7d378fbe964c859524f7e994 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sat, 18 Nov 2023 19:01:48 +0530 Subject: [PATCH 105/337] Add info about HTTP client events. Refs cakephp/cakephp#17416 --- en/core-libraries/httpclient.rst | 53 ++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/en/core-libraries/httpclient.rst b/en/core-libraries/httpclient.rst index 514568a4be..8c66cc20fa 100644 --- a/en/core-libraries/httpclient.rst +++ b/en/core-libraries/httpclient.rst @@ -479,6 +479,59 @@ instead. You can force select a transport adapter using a constructor option:: $client = new Client(['adapter' => Stream::class]); +Events +====== + +The HTTP client triggers couple of events before and after sending a request +which allows you to modify either the request or response or do other tasks like +caching, logging etc. + +HttpClient.beforeSend +--------------------- + + // Somewhere before calling one of the HTTP client's methods which makes a request + $http->getEventManager()->on( + 'HttpClient.beforeSend', + function ( + \Cake\Http\Client\ClientEvent $event, + \Cake\Http\Client\Request $request, + array $adapterOptions, + int $redirects + ) { + // Modify the request + $event->setRequest(....); + // Modify the adapter options + $event->setAdapterOptions(....); + + // Skip making the actual request by returning a response. + // You can use $event->setResult($response) to achieve the same. + return new \Cake\Http\Client\Response(body: 'something'); + } + ); + +HttpClient.afterSend +--------------------- + + // Somewhere before calling one of the HTTP client's methods which makes a request + $http->getEventManager()->on( + 'HttpClient.afterSend', + function ( + \Cake\Http\Client\ClientEvent $event, + \Cake\Http\Client\Request $request, + array $adapterOptions, + int $redirects, + bool $requestSent // Indicates whether the request was actually sent + // or response returned from ``beforeSend`` event + ) { + // Get the response + $response = $event->getResponse(); + + // Return a new/modified response. + // You can use $event->setResult($response) to achieve the same. + return new \Cake\Http\Client\Response(body: 'something'); + } + ); + .. _httpclient-testing: Testing From 35ab8b6ece004705258f6fa8c5e96dd13519f0fe Mon Sep 17 00:00:00 2001 From: Alberto Rodriguez Date: Sat, 18 Nov 2023 15:41:14 -0400 Subject: [PATCH 106/337] docs: es/controllers/request-response.rst --- es/controllers/request-response.rst | 976 +++++++++++++--------------- 1 file changed, 449 insertions(+), 527 deletions(-) diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index 280d8cc7a4..5eff5f62e5 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -1,151 +1,134 @@ -Request & Response Objects -########################## +Objetos de Solicitud y Respuesta +################################ .. php:namespace:: Cake\Http -The request and response objects provide an abstraction around HTTP requests and -responses. The request object in CakePHP allows you to introspect an incoming -request, while the response object allows you to effortlessly create HTTP -responses from your controllers. +Los objetos de solicitud y respuesta proporcionan una abstracción en torno a las solicitudes y respuestas HTTP. El objeto +de solicitud en CakePHP le permite realizar una introspección de una solicitud entrante, mientras que el objeto de +respuesta le permite crear respuestas HTTP sin esfuerzo desde sus controladores. .. index:: $this->request .. _cake-request: -Request -======= +Petición +======== .. php:class:: ServerRequest -``ServerRequest`` is the default request object used in CakePHP. It centralizes a -number of features for interrogating and interacting with request data. -On each request one Request is created and then passed by reference to the -various layers of an application that use request data. By default the request -is assigned to ``$this->request``, and is available in Controllers, Cells, Views -and Helpers. You can also access it in Components using the controller -reference. - -.. versionchanged:: 4.4.0 - The ``ServerRequest`` is available via DI. - So you can get it from container or use it as a dependency for your service. +``ServerRequest`` es el objeto de solicitud predeterminado utilizado en CakePHP. Centraliza una serie de funciones para +interrogar e interactuar con los datos de la solicitud. En cada solicitud, se crea un Request y luego se pasa por +referencia a las distintas capas de una aplicación que utiliza datos de solicitud. De forma predeterminada, la solicitud +se asigna a ``$this->request`` y está disponible en Controladores, Celdas, Vistas y Ayudantes. También puede acceder a él +en Componentes usando la referencia del controlador. -Some of the duties ``ServerRequest`` performs include: +Algunas de las tareas que realiza ``ServerRequest`` incluyen: -* Processing the GET, POST, and FILES arrays into the data structures you are - familiar with. -* Providing environment introspection pertaining to the request. Information - like the headers sent, the client's IP address, and the subdomain/domain - names the server your application is running on. -* Providing access to request parameters both as array indexes and object - properties. +* Procesar los arreglos GET, POST y FILES en las estructuras de datos con las que está familiarizado. +* Proporcionar una introspección del entorno correspondiente a la solicitud. Información como los encabezados enviados, + la dirección IP del cliente y los nombres de subdominio/dominio en el servidor en el que se ejecuta su aplicación. +* Proporcionar acceso a los parámetros de solicitud tanto como índices de matriz como propiedades de objetos. -CakePHP's request object implements the `PSR-7 -ServerRequestInterface `_ making it easier to -use libraries from outside of CakePHP. +El objeto de petición de CakePHP implementa `PSR-7 ServerRequestInterface `_, lo que +facilita el uso de bibliotecas desde fuera de CakePHP. .. _request-parameters: -Request Parameters ------------------- +Parámetros de petición +---------------------- -The request exposes routing parameters through the ``getParam()`` method:: +La solicitud expone los parámetros de enrutamiento a través del método ``getParam()``:: $controllerName = $this->request->getParam('controller'); -To get all routing parameters as an array use ``getAttribute()``:: +Para obtener todos los parámetros de enrutamiento como una matriz, use ``getAttribute()``:: $parameters = $this->request->getAttribute('params'); -All :ref:`route-elements` are accessed through this interface. +Se accede a todos los :ref:`route-elements` a través de esta interfaz. -In addition to :ref:`route-elements`, you also often need access to -:ref:`passed-arguments`. These are both available on the request object as -well:: +Además de :ref:`elementos-de-ruta`, a menudo también necesita acceso a :ref:`argumentos-pasados`. Ambos también están +disponibles en el objeto de solicitud: - // Passed arguments + // Argumentos pasados $passedArgs = $this->request->getParam('pass'); -Will all provide you access to the passed arguments. There -are several important/useful parameters that CakePHP uses internally, these -are also all found in the routing parameters: +Todos le proporcionarán acceso a los argumentos pasados. Hay varios parámetros importantes/útiles que CakePHP usa +internamente, y todos ellos también se encuentran en los parámetros de enrutamiento: -* ``plugin`` The plugin handling the request. Will be null when there is no - plugin. -* ``controller`` The controller handling the current request. -* ``action`` The action handling the current request. -* ``prefix`` The prefix for the current action. See :ref:`prefix-routing` for - more information. +* ``plugin`` El complemento que maneja la solicitud. Será nulo cuando no haya ningún complemento. +* ``controller`` El controlador que maneja la solicitud actual. +* ``action`` La acción que maneja la solicitud actual. +* ``prefix`` El prefijo de la acción actual. Consulte :ref:`prefix-routing` para obtener más información. -Query String Parameters ------------------------ +Parámetros de cadena de consulta +-------------------------------- .. php:method:: getQuery($name, $default = null) -Query string parameters can be read using the ``getQuery()`` method:: +Los parámetros de la cadena de consulta se pueden leer usando el método ``getQuery()``:: - // URL is /posts/index?page=1&sort=title + // URL es /posts/index?page=1&sort=title $page = $this->request->getQuery('page'); -You can either directly access the query property, or you can use -``getQuery()`` method to read the URL query array in an error-free manner. -Any keys that do not exist will return ``null``:: +Puede acceder directamente a la propiedad de consulta o puede utilizar el método ``getQuery()`` para leer la matriz de +consulta de URL sin errores. Cualquier clave que no exista devolverá ``null``:: $foo = $this->request->getQuery('value_that_does_not_exist'); // $foo === null - // You can also provide default values + // También puede proporcionar valores predeterminados $foo = $this->request->getQuery('does_not_exist', 'default val'); -If you want to access all the query parameters you can use -``getQueryParams()``:: +Si desea acceder a todos los parámetros de consulta, puede utilizar ``getQueryParams()``: $query = $this->request->getQueryParams(); -Request Body Data ------------------ +Datos del cuerpo de la petición +------------------------------- .. php:method:: getData($name, $default = null) -All POST data normally available through PHP's ``$_POST`` global variable can be -accessed using :php:meth:`Cake\\Http\\ServerRequest::getData()`. For example:: +Se puede acceder a todos los datos POST normalmente disponibles a través de la variable global ``$_POST`` de PHP usando +:php:meth:`Cake\\Http\\ServerRequest::getData()`. Por ejemplo:: - // An input with a name attribute equal to 'title' is accessible at + // Se puede acceder a una entrada con un atributo de nombre 'título' $title = $this->request->getData('title'); -You can use a dot separated names to access nested data. For example:: +Puede utilizar nombres separados por puntos para acceder a datos anidados. Por ejemplo:: $value = $this->request->getData('address.street_name'); -For non-existent names the ``$default`` value will be returned:: +Para nombres inexistentes se devolverá el valor ``$default``:: $foo = $this->request->getData('value.that.does.not.exist'); // $foo == null -You can also use :ref:`body-parser-middleware` to parse request body of different -content types into an array, so that it's accessible through ``ServerRequest::getData()``. +También puede utilizar :ref:`body-parser-middleware` para analizar el cuerpo de la solicitud de diferentes tipos de +contenido en una matriz, de modo que sea accesible a través de ``ServerRequest::getData()``. -If you want to access all the data parameters you can use +Si desea acceder a todos los parámetros de datos, puede utilizar ``getParsedBody()``:: $data = $this->request->getParsedBody(); .. _request-file-uploads: -File Uploads ------------- +Cargas de archivos +------------------ -Uploaded files can be accessed through the request body data, using the :php:meth:`Cake\\Http\\ServerRequest::getData()` -method described above. For example, a file from an input element with a name attribute of ``attachment``, can -be accessed like this:: +Se puede acceder a los archivos cargados a través de los datos del cuerpo de la solicitud, utilizando el método +:php:meth:`Cake\\Http\\ServerRequest::getData()` descrito anteriormente. Por ejemplo, se puede acceder a un archivo desde +un elemento de entrada con un atributo de nombre ``attachment`` de esta manera:: $attachment = $this->request->getData('attachment'); -By default file uploads are represented in the request data as objects that implement -`\\Psr\\Http\\Message\\UploadedFileInterface `__. In the current -implementation, the ``$attachment`` variable in the above example would by default hold an instance of -``\Laminas\Diactoros\UploadedFile``. +De forma predeterminada, las cargas de archivos se representan en los datos de la solicitud como objetos que implementan +`\\Psr\\Http\\Message\\UploadedFileInterface `__. En la +implementación actual, la variable ``$attachment`` en el ejemplo anterior contendría de forma predeterminada una +instancia de ``\Laminas\Diactoros\UploadedFile``. -Accessing the uploaded file details is fairly simple, here's how you can obtain the same data as provided by the old -style file upload array:: +Acceder a los detalles del archivo cargado es bastante simple, así es como puede obtener los mismos datos que proporciona +la matriz de carga de archivos de estilo antiguo: $name = $attachment->getClientFilename(); $type = $attachment->getClientMediaType(); @@ -153,33 +136,32 @@ style file upload array:: $tmpName = $attachment->getStream()->getMetadata('uri'); $error = $attachment->getError(); -Moving the uploaded file from its temporary location to the desired target -location, doesn't require manually accessing the temporary file, instead it can -be easily done by using the objects ``moveTo()`` method:: +Mover el archivo cargado desde su ubicación temporal a la ubicación de destino deseada no requiere acceder manualmente al +archivo temporal, sino que se puede hacer fácilmente usando el método ``moveTo()`` del objeto:: $attachment->moveTo($targetPath); -In an HTTP environment, the ``moveTo()`` method will automatically validate -whether the file is an actual uploaded file, and throw an exception in case -necessary. In an CLI environment, where the concept of uploading files doesn't -exist, it will allow to move the file that you've referenced irrespective of its -origins, which makes testing file uploads possible. +En un entorno HTTP, el método ``moveTo()`` validará automáticamente si el archivo es un archivo cargado real y generará +una excepción en caso de que sea necesario. En un entorno CLI, donde no existe el concepto de cargar archivos, permitirá +mover el archivo al que ha hecho referencia independientemente de sus orígenes, lo que hace posible probar la carga de +archivos. .. php:method:: getUploadedFile($path) -Returns the uploaded file at a specific path. The path uses the same dot syntax as the -:php:meth:`Cake\\Http\\ServerRequest::getData()` method:: +Devuelve el archivo cargado en una ruta específica. La ruta utiliza la misma sintaxis de puntos que el método +:php:meth:`Cake\\Http\\ServerRequest::getData()`:: $attachment = $this->request->getUploadedFile('attachment'); -Unlike :php:meth:`Cake\\Http\\ServerRequest::getData()`, :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` would -only return data when an actual file upload exists for the given path, if there is regular, non-file request body data -present at the given path, then this method will return ``null``, just like it would for any non-existent path. +A diferencia de :php:meth:`Cake\\Http\\ServerRequest::getData()`, :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` +solo devolvería datos cuando exista una carga de archivo real para la ruta dada, si hay datos regulares del cuerpo de la +solicitud que no son archivos presentes en la ruta dada, entonces este método devolverá "nulo", tal como lo haría para +cualquier ruta inexistente. .. php:method:: getUploadedFiles() -Returns all uploaded files in a normalized array structure. For the above example with the file input name of -``attachment``, the structure would look like:: +Devuelve todos los archivos cargados en una estructura de matriz normalizada. Para el ejemplo anterior con el nombre de +entrada del archivo ``attachment``, la estructura se vería así:: [ 'attachment' => object(Laminas\Diactoros\UploadedFile) { @@ -189,9 +171,9 @@ Returns all uploaded files in a normalized array structure. For the above exampl .. php:method:: withUploadedFiles(array $files) -This method sets the uploaded files of the request object, it accepts an array of objects that implement -`\\Psr\\Http\\Message\\UploadedFileInterface `__. It will -replace all possibly existing uploaded files:: +Este método establece los archivos cargados del objeto de solicitud, acepta una matriz de objetos que implementan +`\\Psr\\Http\\Message\\UploadedFileInterface `__. Reemplazará +todos los archivos cargados posiblemente existentes:: $files = [ 'MyModel' => [ @@ -216,146 +198,139 @@ replace all possibly existing uploaded files:: .. note:: - Uploaded files that have been added to the request via this method, will *not* be available in the request body - data, ie you cannot retrieve them via :php:meth:`Cake\\Http\\ServerRequest::getData()`! If you need them in the - request data (too), then you have to set them via :php:meth:`Cake\\Http\\ServerRequest::withData()` or - :php:meth:`Cake\\Http\\ServerRequest::withParsedBody()`. + Los archivos cargados que se agregaron a la solicitud a través de este método *no* estarán disponibles en los datos + del cuerpo de la solicitud, es decir, no puede recuperarlos a través de + :php:meth:`Cake\\Http\\ServerRequest::getData()` ! Si los necesita en los datos de la solicitud (también), entonces + debe configurarlos mediante :php:meth:`Cake\\Http\\ServerRequest::withData()` o + :php:meth:`Cake\\Http\ \ServerRequest::withParsedBody()`. -PUT, PATCH or DELETE Data +PUT, PATCH o DELETE Datos ------------------------- .. php:method:: input($callback, [$options]) -When building REST services, you often accept request data on ``PUT`` and -``DELETE`` requests. Any ``application/x-www-form-urlencoded`` request body data -will automatically be parsed and set to ``$this->data`` for ``PUT`` and -``DELETE`` requests. If you are accepting JSON or XML data, see below for how -you can access those request bodies. +Al crear servicios REST, a menudo se aceptan datos de solicitud en solicitudes ``PUT`` y ``DELETE``. Cualquier dato del +cuerpo de solicitud ``application/x-www-form-urlencoded`` se analizará automáticamente y se establecerá en +``$this->data`` para las solicitudes ``PUT`` y ``DELETE``. Si acepta datos JSON o XML, consulte a continuación cómo puede +acceder a esos cuerpos de solicitud. -When accessing the input data, you can decode it with an optional function. -This is useful when interacting with XML or JSON request body content. -Additional parameters for the decoding function can be passed as arguments to -``input()``:: +Al acceder a los datos de entrada, puede decodificarlos con una función opcional. Esto resulta útil al interactuar con el +contenido del cuerpo de la solicitud XML o JSON. Se pueden pasar parámetros adicionales para la función de decodificación +como argumentos a ``input()``:: $jsonData = $this->request->input('json_decode'); -Environment Variables (from $_SERVER and $_ENV) ------------------------------------------------ +Variables de entorno (de $_SERVER y $_ENV) +------------------------------------------ .. php:method:: putenv($key, $value = null) -``ServerRequest::getEnv()`` is a wrapper for ``getenv()`` global function and acts as -a getter/setter for environment variables without having to modify globals -``$_SERVER`` and ``$_ENV``:: +``ServerRequest::getEnv()`` es un contenedor para la función global ``getenv()`` y actúa como un captador/establecedor de +variables de entorno sin tener que modificar los globales ``$_SERVER`` y ``$_ENV` `:: - // Get the host + // Obtener el host $host = $this->request->getEnv('HTTP_HOST'); - // Set a value, generally helpful in testing. + // Establecer un valor, generalmente útil en las pruebas. $this->request->withEnv('REQUEST_METHOD', 'POST'); -To access all the environment variables in a request use ``getServerParams()``:: +Para acceder a todas las variables de entorno en una solicitud utilice ``getServerParams()``:: $env = $this->request->getServerParams(); -XML or JSON Data +Datos XML o JSON ---------------- -Applications employing :doc:`/development/rest` often exchange data in -non-URL-encoded post bodies. You can read input data in any format using -:php:meth:`~Cake\\Http\\ServerRequest::input()`. By providing a decoding function, -you can receive the content in a deserialized format:: +Las aplicaciones que emplean :doc:`/development/rest` a menudo intercambian datos en cuerpos de publicaciones sin +codificación URL. Puede leer datos de entrada en cualquier formato usando :php:meth:`~Cake\\Http\\ServerRequest::input()`. +Al proporcionar una función de decodificación, puede recibir el contenido en un formato deserializado:: - // Get JSON encoded data submitted to a PUT/POST action + // Obtenga datos codificados en JSON enviados a una acción PUT/POST $jsonData = $this->request->input('json_decode'); -Some deserializing methods require additional parameters when called, such as -the 'as array' parameter on ``json_decode``. If you want XML converted into a -DOMDocument object, :php:meth:`~Cake\\Http\\ServerRequest::input()` supports -passing in additional parameters as well:: +Algunos métodos de deserialización requieren parámetros adicionales cuando se llaman, como el parámetro 'as array' en +``json_decode``. Si desea convertir XML en un objeto DOMDocument, :php:meth:`~Cake\\Http\\ServerRequest::input()` también +admite el paso de parámetros adicionales:: - // Get XML encoded data submitted to a PUT/POST action + // Obtener datos codificados en XML enviados a una acción PUT/POST $data = $this->request->input('Cake\Utility\Xml::build', ['return' => 'domdocument']); -Path Information ----------------- +Información de ruta +------------------- -The request object also provides useful information about the paths in your -application. The ``base`` and ``webroot`` attributes are useful for -generating URLs, and determining whether or not your application is in a -subdirectory. The attributes you can use are:: +El objeto de solicitud también proporciona información útil sobre las rutas de su aplicación. Los atributos ``base`` y +``webroot`` son útiles para generar URL y determinar si su aplicación está o no en un subdirectorio. Los atributos que +puedes utilizar son: - // Assume the current request URL is /subdir/articles/edit/1?page=1 + // Supongamos que la URL de solicitud actual es /subdir/articles/edit/1?page=1 - // Holds /subdir/articles/edit/1?page=1 + // Contiene /subdir/articles/edit/1?page=1 $here = $request->getRequestTarget(); - // Holds /subdir + // Contiene /subdir $base = $request->getAttribute('base'); - // Holds /subdir/ + // Contiene /subdir/ $base = $request->getAttribute('webroot'); .. _check-the-request: -Checking Request Conditions ---------------------------- +Comprobación de las condiciones de la solicitud +----------------------------------------------- .. php:method:: is($type, $args...) -The request object provides a way to inspect certain conditions in a given -request. By using the ``is()`` method you can check a number of common -conditions, as well as inspect other application specific request criteria:: +El objeto de solicitud proporciona una forma de inspeccionar ciertas condiciones en una solicitud determinada. Al +utilizar el método ``is()``, puede comprobar una serie de condiciones comunes, así como inspeccionar otros criterios de +solicitud específicos de la aplicación: $isPost = $this->request->is('post'); -You can also extend the request detectors that are available, by using -:php:meth:`Cake\\Http\\ServerRequest::addDetector()` to create new kinds of -detectors. There are different types of detectors that you can create: - -* Environment value comparison - Compares a value fetched from :php:func:`env()` - for equality with the provided value. -* Header value comparison - If the specified header exists with the specified - value, or if the callable returns true. -* Pattern value comparison - Pattern value comparison allows you to compare a - value fetched from :php:func:`env()` to a regular expression. -* Option based comparison - Option based comparisons use a list of options to - create a regular expression. Subsequent calls to add an already defined - options detector will merge the options. -* Callback detectors - Callback detectors allow you to provide a 'callback' type - to handle the check. The callback will receive the request object as its only - parameter. +También puede ampliar los detectores de solicitudes que están disponibles, utilizando +:php:meth:`Cake\\Http\\ServerRequest::addDetector()` para crear nuevos tipos de detectores. Hay diferentes tipos de +detectores que puedes crear: + +* Comparación de valores del entorno: compara un valor obtenido de :php:func:`env()` para determinar su igualdad con el + valor proporcionado. +* Comparación del valor del encabezado: si el encabezado especificado existe con el valor especificado o si el invocable + devuelve verdadero. +* Comparación de valores de patrón: la comparación de valores de patrón le permite comparar un valor obtenido de + :php:func:`env()` con una expresión regular. +* Comparación basada en opciones: las comparaciones basadas en opciones utilizan una lista de opciones para crear una + expresión regular. Las llamadas posteriores para agregar un detector de opciones ya definido fusionarán las opciones. +* Detectores de devolución de llamada: los detectores de devolución de llamada le permiten proporcionar un tipo de + "callback" para manejar la verificación. La devolución de llamada recibirá el objeto de solicitud como único parámetro. .. php:method:: addDetector($name, $options) -Some examples would be:: +Algunos ejemplos serían:: - // Add an environment detector. + // Agregue un detector de entorno. $this->request->addDetector( 'post', ['env' => 'REQUEST_METHOD', 'value' => 'POST'] ); - // Add a pattern value detector. + // Agregue un detector de valor de patrón. $this->request->addDetector( 'iphone', ['env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i'] ); - // Add an option detector + // Agregar un detector de opciones $this->request->addDetector('internalIp', [ 'env' => 'CLIENT_IP', 'options' => ['192.168.0.101', '192.168.0.100'] ]); - // Add a header detector with value comparison + // Agregue un detector de encabezado con comparación de valores $this->request->addDetector('fancy', [ 'env' => 'CLIENT_IP', 'header' => ['X-Fancy' => 1] ]); - // Add a header detector with callable comparison + // Agregue un detector de encabezado con comparación invocable $this->request->addDetector('fancy', [ 'env' => 'CLIENT_IP', 'header' => ['X-Fancy' => function ($value, $header) { @@ -363,7 +338,7 @@ Some examples would be:: }] ]); - // Add a callback detector. Must be a valid callable. + // Agregue un detector de devolución de llamada. Debe ser un invocable válido. $this->request->addDetector( 'awesome', function ($request) { @@ -371,7 +346,7 @@ Some examples would be:: } ); - // Add a detector that uses additional arguments. + // Agregue un detector que use argumentos adicionales. $this->request->addDetector( 'csv', [ @@ -381,227 +356,213 @@ Some examples would be:: ] ); -There are several built-in detectors that you can use: - -* ``is('get')`` Check to see whether the current request is a GET. -* ``is('put')`` Check to see whether the current request is a PUT. -* ``is('patch')`` Check to see whether the current request is a PATCH. -* ``is('post')`` Check to see whether the current request is a POST. -* ``is('delete')`` Check to see whether the current request is a DELETE. -* ``is('head')`` Check to see whether the current request is HEAD. -* ``is('options')`` Check to see whether the current request is OPTIONS. -* ``is('ajax')`` Check to see whether the current request came with - X-Requested-With = XMLHttpRequest. -* ``is('ssl')`` Check to see whether the request is via SSL. -* ``is('flash')`` Check to see whether the request has a User-Agent of Flash. -* ``is('json')`` Check to see whether the request has 'json' extension and - accept 'application/json' mimetype. -* ``is('xml')`` Check to see whether the request has 'xml' extension and accept - 'application/xml' or 'text/xml' mimetype. - -``ServerRequest`` also includes methods like -:php:meth:`Cake\\Http\\ServerRequest::domain()`, -:php:meth:`Cake\\Http\\ServerRequest::subdomains()` and -:php:meth:`Cake\\Http\\ServerRequest::host()` to make applications that use -subdomains simpler. - -Session Data ------------- - -To access the session for a given request use the ``getSession()`` method or use the ``session`` attribute:: +Hay varios detectores integrados que puedes utilizar: + +* ``is('get')`` Verifique si la solicitud actual es un GET. +* ``is('put')`` Verifique si la solicitud actual es un PUT. +* ``is('patch')`` Verifique si la solicitud actual es un PATCH. +* ``is('post')`` Verifique si la solicitud actual es una POST. +* ``is('delete')`` Verifique si la solicitud actual es DELETE. +* ``is('head')`` Verifique si la solicitud actual es HEAD. +* ``is('options')`` Verifique si la solicitud actual es OPTIONS. +* ``is('ajax')`` Verifique si la solicitud actual vino con X-Requested-With = XMLHttpRequest. +* ``is('ssl')`` Compruebe si la solicitud se realiza a través de SSL. +* ``is('flash')`` Verifique si la solicitud tiene un User-Agent de Flash. +* ``is('json')`` Verifique si la solicitud tiene la extensión 'json' y acepte el tipo mime 'application/json'. +* ``is('xml')`` Verifique si la solicitud tiene la extensión 'xml' y acepte el tipo mime 'application/xml' o 'text/xml'. + +``ServerRequest`` También incluye métodos como :php:meth:`Cake\\Http\\ServerRequest::domain()`, +:php:meth:`Cake\\Http\\ServerRequest::subdomains()` y :php:meth:`Cake\\Http\\ServerRequest::host()` para simplificar las +aplicaciones que utilizan subdominios. + +Datos de sesión +--------------- + +Para acceder a la sesión para una solicitud determinada utilice el método ``getSession()`` o utilice el atributo +``session``:: $session = $this->request->getSession(); $session = $this->request->getAttribute('session'); $data = $session->read('sessionKey'); -For more information, see the :doc:`/development/sessions` documentation for how -to use the session object. +Para obtener más información, consulte la documentación :doc:`/development/sessions` sobre cómo utilizar el objeto de +sesión. -Host and Domain Name --------------------- +Host y nombre de dominio +------------------------ .. php:method:: domain($tldLength = 1) -Returns the domain name your application is running on:: +Devuelve el nombre de dominio en el que se ejecuta su aplicación:: - // Prints 'example.org' + // Muestra 'example.org' echo $request->domain(); .. php:method:: subdomains($tldLength = 1) -Returns the subdomains your application is running on as an array:: +Devuelve los subdominios en los que se ejecuta su aplicación como una matriz:: - // Returns ['my', 'dev'] for 'my.dev.example.org' + // Regresa ['my', 'dev'] de 'my.dev.example.org' $subdomains = $request->subdomains(); .. php:method:: host() -Returns the host your application is on:: +Devuelve el host en el que se encuentra su aplicación:: - // Prints 'my.dev.example.org' + // Muestra 'my.dev.example.org' echo $request->host(); -Reading the HTTP Method ------------------------ +Leyendo el método HTTP +---------------------- .. php:method:: getMethod() -Returns the HTTP method the request was made with:: +Devuelve el método HTTP con el que se realizó la solicitud:: - // Output POST + // Salida POST echo $request->getMethod(); -Restricting Which HTTP method an Action Accepts ------------------------------------------------ +Restringir qué método HTTP acepta una acción +-------------------------------------------- .. php:method:: allowMethod($methods) -Set allowed HTTP methods. If not matched, will throw -``MethodNotAllowedException``. The 405 response will include the required -``Allow`` header with the passed methods:: +Establecer métodos HTTP permitidos. Si no coincide, arrojará ``MethodNotAllowedException``. La respuesta 405 incluirá el +encabezado ``Allow`` requerido con los métodos pasados:: public function delete() { - // Only accept POST and DELETE requests + // Solo acepte solicitudes POST y DELETE $this->request->allowMethod(['post', 'delete']); ... } -Reading HTTP Headers --------------------- +Lectura de encabezados HTTP +--------------------------- -Allows you to access any of the ``HTTP_*`` headers that were used -for the request. For example:: +Le permite acceder a cualquiera de los encabezados ``HTTP_*`` que se utilizaron para la solicitud. Por ejemplo:: - // Get the header as a string + // Obtener el encabezado como una cadena $userAgent = $this->request->getHeaderLine('User-Agent'); - // Get an array of all values. + // Obtenga una matriz de todos los valores. $acceptHeader = $this->request->getHeader('Accept'); - // Check if a header exists + // Comprobar si existe un encabezado $hasAcceptHeader = $this->request->hasHeader('Accept'); -While some apache installs don't make the ``Authorization`` header accessible, -CakePHP will make it available through apache specific methods as required. +Si bien algunas instalaciones de Apache no hacen que el encabezado ``Authorization`` sea accesible, CakePHP lo hará +disponible a través de métodos específicos de Apache según sea necesario. .. php:method:: referer($local = true) -Returns the referring address for the request. +Devuelve la dirección de referencia de la solicitud. .. php:method:: clientIp() -Returns the current visitor's IP address. +Devuelve la dirección IP del visitante actual. -Trusting Proxy Headers ----------------------- +Confiar en los encabezados de proxy +----------------------------------- -If your application is behind a load balancer or running on a cloud service, you -will often get the load balancer host, port and scheme in your requests. Often -load balancers will also send ``HTTP-X-Forwarded-*`` headers with the original -values. The forwarded headers will not be used by CakePHP out of the box. To -have the request object use these headers set the ``trustProxy`` property to -``true``:: +Si su aplicación está detrás de un balanceador de carga o se ejecuta en un servicio en la nube, a menudo obtendrá el +host, el puerto y el esquema del balanceador de carga en sus solicitudes. A menudo, los balanceadores de carga también +enviarán encabezados ``HTTP-X-Forwarded-*`` con los valores originales. CakePHP no utilizará los encabezados reenviados +de fábrica. Para que el objeto de solicitud utilice estos encabezados, establezca la propiedad ``trustProxy`` en ``true``:: $this->request->trustProxy = true; - // These methods will now use the proxied headers. + // Estos métodos ahora utilizarán los encabezados proxy. $port = $this->request->port(); $host = $this->request->host(); $scheme = $this->request->scheme(); $clientIp = $this->request->clientIp(); -Once proxies are trusted the ``clientIp()`` method will use the *last* IP -address in the ``X-Forwarded-For`` header. If your application is behind -multiple proxies, you can use ``setTrustedProxies()`` to define the IP addresses -of proxies in your control:: +Una vez que se confía en los servidores proxy, el método ``clientIp()`` utilizará la *última* dirección IP en el +encabezado ``X-Forwarded-For``. Si su aplicación está detrás de varios servidores proxy, puede usar +``setTrustedProxies()`` para definir las direcciones IP de los servidores proxy bajo su control:: $request->setTrustedProxies(['127.1.1.1', '127.8.1.3']); -After proxies are trusted ``clientIp()`` will use the first IP address in the -``X-Forwarded-For`` header providing it is the only value that isn't from a trusted -proxy. +Después de que los servidores proxy sean confiables, ``clientIp()`` usará la primera dirección IP en el encabezado +``X-Forwarded-For`` siempre que sea el único valor que no provenga de un proxy confiable. -Checking Accept Headers ------------------------ +Comprobando encabezados aceptados +--------------------------------- .. php:method:: accepts($type = null) -Find out which content types the client accepts, or check whether it accepts a -particular type of content. +Descubra qué tipos de contenido acepta el cliente o compruebe si acepta un tipo de contenido en particular. -Get all types:: +Consigue todos los tipos:: $accepts = $this->request->accepts(); -Check for a single type:: +Consulta por un solo tipo:: $acceptsJson = $this->request->accepts('application/json'); .. php:method:: acceptLanguage($language = null) -Get all the languages accepted by the client, -or check whether a specific language is accepted. +Obtenga todos los idiomas aceptados por el cliente o verifique si se acepta un idioma específico. -Get the list of accepted languages:: +Obtenga la lista de idiomas aceptados:: $acceptsLanguages = $this->request->acceptLanguage(); -Check whether a specific language is accepted:: +Compruebe si se acepta un idioma específico:: $acceptsSpanish = $this->request->acceptLanguage('es-es'); .. _request-cookies: -Reading Cookies +Leyendo Cookies --------------- -Request cookies can be read through a number of methods:: +Las cookies de solicitud se pueden leer a través de varios métodos: - // Get the cookie value, or null if the cookie is missing. + // Obtenga el valor de la cookie, o nulo si falta la cookie. $rememberMe = $this->request->getCookie('remember_me'); - // Read the value, or get the default of 0 + // Lea el valor u obtenga el valor predeterminado de 0 $rememberMe = $this->request->getCookie('remember_me', 0); - // Get all cookies as an hash + // Obtener todas las cookies como hash $cookies = $this->request->getCookieParams(); - // Get a CookieCollection instance + // Obtener una instancia de CookieCollection $cookies = $this->request->getCookieCollection() -See the :php:class:`Cake\\Http\\Cookie\\CookieCollection` documentation for how -to work with cookie collection. - +Consulte la documentación :php:class:`Cake\\Http\\Cookie\\CookieCollection` para saber cómo trabajar con la recopilación +de cookies. -Uploaded Files --------------- +Archivos cargados +----------------- -Requests expose the uploaded file data in ``getData()`` or -``getUploadedFiles()`` as ``UploadedFileInterface`` objects:: +Las solicitudes exponen los datos del archivo cargado en ``getData()`` o ``getUploadedFiles()`` como objetos +``UploadedFileInterface``:: - // Get a list of UploadedFile objects + // Obtener una lista de objetos UploadedFile $files = $request->getUploadedFiles(); - // Read the file data. + // Lea los datos del archivo. $files[0]->getStream(); $files[0]->getSize(); $files[0]->getClientFileName(); - // Move the file. + // Mover el archivo $files[0]->moveTo($targetPath); -Manipulating URIs +Manipulación de URI ----------------- -Requests contain a URI object, which contains methods for interacting with the -requested URI:: +Las solicitudes contienen un objeto URI, que contiene métodos para interactuar con el URI solicitado:: - // Get the URI + // Obtener la URI $uri = $request->getUri(); - // Read data out of the URI. + // Leer datos de la URI. $path = $uri->getPath(); $query = $uri->getQuery(); $host = $uri->getHost(); @@ -609,177 +570,166 @@ requested URI:: .. index:: $this->response -Response -======== +Respueta (Response) +=================== .. php:class:: Response -:php:class:`Cake\\Http\\Response` is the default response class in CakePHP. -It encapsulates a number of features and functionality for generating HTTP -responses in your application. It also assists in testing, as it can be -mocked/stubbed allowing you to inspect headers that will be sent. +:php:class:`Cake\\Http\\Response` es la clase de respuesta predeterminada en CakePHP. Encapsula una serie de +características y funcionalidades para generar respuestas HTTP en su aplicación. También ayuda en las pruebas, ya que se +puede simular o eliminar, lo que le permite inspeccionar los encabezados que se enviarán. -``Response`` provides an interface to wrap the common response-related -tasks such as: +``Response`` proporciona una interfaz para envolver las tareas comunes relacionadas con la respuesta, como por ejemplo: -* Sending headers for redirects. -* Sending content type headers. -* Sending any header. -* Sending the response body. +* Envío de encabezados para redireccionamientos. +* Envío de encabezados de tipo de contenido. +* Envío de cualquier encabezado. +* Envío del cuerpo de la respuesta. -Dealing with Content Types --------------------------- +Tratar con tipos de contenido +----------------------------- .. php:method:: withType($contentType = null) -You can control the Content-Type of your application's responses with -:php:meth:`Cake\\Http\\Response::withType()`. If your application needs to deal -with content types that are not built into Response, you can map them with -``setTypeMap()`` as well:: +Puede controlar el tipo de contenido de las respuestas de su aplicación con :php:meth:`Cake\\Http\\Response::withType()`. +Si su aplicación necesita manejar tipos de contenido que no están integrados en Response, también puede asignarlos con +``setTypeMap()``:: - // Add a vCard type + // Agregar un tipo de vCard $this->response->setTypeMap('vcf', ['text/v-card']); - // Set the response Content-Type to vcard. + // Establezca el tipo de contenido de respuesta en vcard $this->response = $this->response->withType('vcf'); -Usually, you'll want to map additional content types in your controller's -:php:meth:`~Controller::beforeFilter()` callback, so you can leverage the -automatic view switching features of :php:class:`RequestHandlerComponent` if you -are using it. +Por lo general, querrás asignar tipos de contenido adicionales en la devolución de llamada de tu controlador +:php:meth:`~Controller::beforeFilter()`, para poder aprovechar las funciones de cambio automático de vista de +:php:class:`RequestHandlerComponent` si lo están usando. .. _cake-response-file: -Sending Files -------------- +Enviando arhivos +---------------- .. php:method:: withFile(string $path, array $options = []) -There are times when you want to send files as responses for your requests. -You can accomplish that by using :php:meth:`Cake\\Http\\Response::withFile()`:: +Hay ocasiones en las que desea enviar archivos como respuesta a sus solicitudes. Puedes lograrlo usando +:php:meth:`Cake\\Http\\Response::withFile()`:: public function sendFile($id) { $file = $this->Attachments->getFile($id); $response = $this->response->withFile($file['path']); - // Return the response to prevent controller from trying to render - // a view. + // Devuelve la respuesta para evitar que el controlador intente representar una vista. return $response; } -As shown in the above example, you must pass the file path to the method. -CakePHP will send a proper content type header if it's a known file type listed -in `Cake\\Http\\Response::$_mimeTypes`. You can add new types prior to calling -:php:meth:`Cake\\Http\\Response::withFile()` by using the -:php:meth:`Cake\\Http\\Response::withType()` method. +Como se muestra en el ejemplo anterior, debe pasar la ruta del archivo al método. CakePHP enviará un encabezado de tipo +de contenido adecuado si es un tipo de archivo conocido que figura en `Cake\\Http\\Response::$_mimeTypes`. Puede agregar +nuevos tipos antes de llamar a :php:meth:`Cake\\Http\\Response::withFile()` usando el método +:php:meth:`Cake\\Http\\Response::withType()` . -If you want, you can also force a file to be downloaded instead of displayed in -the browser by specifying the options:: +Si lo desea, también puede forzar la descarga de un archivo en lugar de mostrarlo en el navegador especificando las +opciones:: $response = $this->response->withFile( $file['path'], ['download' => true, 'name' => 'foo'] ); -The supported options are: +Las opciones admitidas son: name - The name allows you to specify an alternate file name to be sent to - the user. + El nombre le permite especificar un nombre de archivo alternativo para enviarlo al usuario. download - A boolean value indicating whether headers should be set to force - download. + Un valor booleano que indica si los encabezados deben configurarse para forzar la descarga. -Sending a String as File ------------------------- +Enviar una cadena como archivo +------------------------------ -You can respond with a file that does not exist on the disk, such as a pdf or an -ics generated on the fly from a string:: +Puedes responder con un archivo que no existe en el disco, como un pdf o un ics generado sobre la marcha a partir de una +cadena:: public function sendIcs() { $icsString = $this->Calendars->generateIcs(); $response = $this->response; - // Inject string content into response body + // Inyectar contenido de cadena en el cuerpo de la respuesta $response = $response->withStringBody($icsString); $response = $response->withType('ics'); - // Optionally force file download + // Opcionalmente forzar la descarga de archivos $response = $response->withDownload('filename_for_download.ics'); - // Return response object to prevent controller from trying to render - // a view. + // Devuelve un objeto de respuesta para evitar que el controlador intente representar una vista. return $response; } -Setting Headers ---------------- +Configuración de encabezados +---------------------------- .. php:method:: withHeader($header, $value) -Setting headers is done with the :php:meth:`Cake\\Http\\Response::withHeader()` -method. Like all of the PSR-7 interface methods, this method returns a *new* -instance with the new header:: +La configuración de los encabezados se realiza con el método :php:meth:`Cake\\Http\\Response::withHeader()`. Como todos +los métodos de la interfaz PSR-7, este método devuelve una instancia *nueva* con el nuevo encabezado:: - // Add/replace a header + // Agregar/reemplazar un encabezado $response = $response->withHeader('X-Extra', 'My header'); - // Set multiple headers + // Establecer múltiples encabezados $response = $response->withHeader('X-Extra', 'My header') ->withHeader('Location', 'http://example.com'); - // Append a value to an existing header + // Agregar un valor a un encabezado existente $response = $response->withAddedHeader('Set-Cookie', 'remember_me=1'); -Headers are not sent when set. Instead, they are held until the response is -emitted by ``Cake\Http\Server``. +Los encabezados no se envían cuando se configuran. En cambio, se retienen hasta que ``Cake\Http\Server`` emite la +respuesta. -You can now use the convenience method -:php:meth:`Cake\\Http\\Response::withLocation()` to directly set or get the -redirect location header. +Ahora puede utilizar el método conveniente :php:meth:`Cake\\Http\\Response::withLocation()` para configurar u obtener +directamente el encabezado de ubicación de redireccionamiento. -Setting the Body ----------------- +Configurando el cuerpo +---------------------- .. php:method:: withStringBody($string) -To set a string as the response body, do the following:: +Para establecer una cadena como cuerpo de respuesta, haga lo siguiente: - // Set a string into the body + // Coloca una cadena en el cuerpo. $response = $response->withStringBody('My Body'); - // If you want a json response - $response = $response->withType('application/json') + // Si quieres una respuesta json + $response = $response + ->withType('application/json') ->withStringBody(json_encode(['Foo' => 'bar'])); .. php:method:: withBody($body) -To set the response body, use the ``withBody()`` method, which is provided by the +Para configurar el cuerpo de la respuesta, use el método ``withBody()``, que es proporcionado por :php:class:`Laminas\\Diactoros\\MessageTrait`:: $response = $response->withBody($stream); -Be sure that ``$stream`` is a :php:class:`Psr\\Http\\Message\\StreamInterface` object. -See below on how to create a new stream. +Asegúrese de que ``$stream`` sea un objeto :php:class:`Psr\\Http\\Message\\StreamInterface`. Vea a continuación cómo +crear un nuevo stream. -You can also stream responses from files using :php:class:`Laminas\\Diactoros\\Stream` streams:: +También puedes transmitir respuestas desde archivos usando :php:class:`Laminas\\Diactoros\\Stream` streams:: - // To stream from a file + // Para transmitir desde un archivo use Laminas\Diactoros\Stream; $stream = new Stream('/path/to/file', 'rb'); $response = $response->withBody($stream); -You can also stream responses from a callback using the ``CallbackStream``. This -is useful when you have resources like images, CSV files or PDFs you need to -stream to the client:: +También puedes transmitir respuestas desde una devolución de llamada usando ``CallbackStream``. Esto es útil cuando tiene +recursos como imágenes, archivos CSV o PDF que necesita transmitir al cliente:: - // Streaming from a callback + // Transmisión desde una devolución de llamada use Cake\Http\CallbackStream; - // Create an image. + // Crea una imagen. $img = imagecreate(100, 100); // ... @@ -788,154 +738,139 @@ stream to the client:: }); $response = $response->withBody($stream); -Setting the Character Set -------------------------- +Configuración del juego de caracteres +------------------------------------- .. php:method:: withCharset($charset) -Sets the charset that will be used in the response:: +Establece el juego de caracteres que se utilizará en la respuesta:: $this->response = $this->response->withCharset('UTF-8'); -Interacting with Browser Caching --------------------------------- +Interactuar con el almacenamiento en caché del navegador +-------------------------------------------------------- .. php:method:: withDisabledCache() -You sometimes need to force browsers not to cache the results of a controller -action. :php:meth:`Cake\\Http\\Response::withDisabledCache()` is intended for just -that:: +A veces es necesario obligar a los navegadores a no almacenar en caché los resultados de una acción del controlador. +:php:meth:`Cake\\Http\\Response::withDisabledCache()` está destinado precisamente a eso:: public function index() { - // Disable caching + // Deshabilitar el almacenamiento en caché $this->response = $this->response->withDisabledCache(); } .. warning:: - Disabling caching from SSL domains while trying to send - files to Internet Explorer can result in errors. + Deshabilitar el almacenamiento en caché de dominios SSL al intentar enviar archivos a Internet Explorer puede + generar errores. .. php:method:: withCache($since, $time = '+1 day') -You can also tell clients that you want them to cache responses. By using +También puede decirles a los clientes que desea que almacenen en caché las respuestas. Usando :php:meth:`Cake\\Http\\Response::withCache()`:: public function index() { - // Enable caching + // Habilitar el almacenamiento en caché $this->response = $this->response->withCache('-1 minute', '+5 days'); } -The above would tell clients to cache the resulting response for 5 days, -hopefully speeding up your visitors' experience. -The ``withCache()`` method sets the ``Last-Modified`` value to the first -argument. ``Expires`` header and the ``max-age`` directive are set based on the -second parameter. Cache-Control's ``public`` directive is set as well. +Lo anterior les indicaría a los clientes que guarden en caché la respuesta resultante durante 5 días, con la esperanza +de acelerar la experiencia de sus visitantes. El método ``withCache()`` establece el valor ``Última modificación`` en el +primer argumento. El encabezado ``Expires`` y la directiva ``max-age`` se establecen en función del segundo parámetro. +La directiva "pública" de Cache-Control también está configurada. .. _cake-response-caching: -Fine Tuning HTTP Cache ----------------------- +Ajuste fino de la caché HTTP +---------------------------- -One of the best and easiest ways of speeding up your application is to use HTTP -cache. Under this caching model, you are only required to help clients decide if -they should use a cached copy of the response by setting a few headers such as -modified time and response entity tag. +Una de las mejores y más sencillas formas de acelerar su aplicación es utilizar la caché HTTP. Según este modelo de +almacenamiento en caché, solo debe ayudar a los clientes a decidir si deben usar una copia en caché de la respuesta +configurando algunos encabezados, como la hora de modificación y la etiqueta de entidad de respuesta. -Rather than forcing you to code the logic for caching and for invalidating -(refreshing) it once the data has changed, HTTP uses two models, expiration and -validation, which usually are much simpler to use. +En lugar de obligarlo a codificar la lógica para el almacenamiento en caché y para invalidarla (actualizarla) una vez que +los datos han cambiado, HTTP utiliza dos modelos, caducidad y validación, que generalmente son mucho más simples de usar. -Apart from using :php:meth:`Cake\\Http\\Response::withCache()`, you can also use -many other methods to fine-tune HTTP cache headers to take advantage of browser -or reverse proxy caching. +Además de usar :php:meth:`Cake\\Http\\Response::withCache()`, también puedes usar muchos otros métodos para ajustar los +encabezados de caché HTTP para aprovechar el almacenamiento en caché del navegador o del proxy inverso. -The Cache Control Header -~~~~~~~~~~~~~~~~~~~~~~~~ +El encabezado de control de caché +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. php:method:: withSharable($public, $time = null) -Used under the expiration model, this header contains multiple indicators that -can change the way browsers or proxies use the cached content. A -``Cache-Control`` header can look like this:: +Utilizado bajo el modelo de vencimiento, este encabezado contiene múltiples indicadores que pueden cambiar la forma en +que los navegadores o servidores proxy usan el contenido almacenado en caché. Un encabezado ``Cache-Control`` puede +verse así:: Cache-Control: private, max-age=3600, must-revalidate -``Response`` class helps you set this header with some utility methods that will -produce a final valid ``Cache-Control`` header. The first is the -``withSharable()`` method, which indicates whether a response is to be -considered sharable across different users or clients. This method actually -controls the ``public`` or ``private`` part of this header. Setting a response -as private indicates that all or part of it is intended for a single user. To -take advantage of shared caches, the control directive must be set as public. +La clase ``Response`` le ayuda a configurar este encabezado con algunos métodos de utilidad que producirán un encabezado +``Cache-Control`` final válido. El primero es el método ``withSharable()``, que indica si una respuesta debe considerarse +compartible entre diferentes usuarios o clientes. Este método en realidad controla la parte "pública" o "privada" de este +encabezado. Establecer una respuesta como privada indica que toda o parte de ella está destinada a un solo usuario. Para +aprovechar las cachés compartidas, la directiva de control debe configurarse como pública. -The second parameter of this method is used to specify a ``max-age`` for the -cache, which is the number of seconds after which the response is no longer -considered fresh:: +El segundo parámetro de este método se utiliza para especificar una ``max-age`` para el caché, que es el número de +segundos después de los cuales la respuesta ya no se considera nueva: public function view() { // ... - // Set the Cache-Control as public for 3600 seconds + // Configure Cache-Control como público durante 3600 segundos $this->response = $this->response->withSharable(true, 3600); } public function my_data() { // ... - // Set the Cache-Control as private for 3600 seconds + // Configure Cache-Control como privado durante 3600 segundos $this->response = $this->response->withSharable(false, 3600); } -``Response`` exposes separate methods for setting each of the directives in -the ``Cache-Control`` header. +``Response`` expone métodos separados para configurar cada una de las directivas en el encabezado ``Cache-Control``. -The Expiration Header -~~~~~~~~~~~~~~~~~~~~~ +El encabezado de vencimiento +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. php:method:: withExpires($time) -You can set the ``Expires`` header to a date and time after which the response -is no longer considered fresh. This header can be set using the -``withExpires()`` method:: +Puede configurar el encabezado ``Expires`` en una fecha y hora después de la cual la respuesta ya no se considera nueva. +Este encabezado se puede configurar usando el método ``withExpires()``:: public function view() { $this->response = $this->response->withExpires('+5 days'); } -This method also accepts a :php:class:`DateTime` instance or any string that can -be parsed by the :php:class:`DateTime` class. +Este método también acepta una instancia :php:class:`DateTime` o cualquier cadena que pueda ser analizada por la clase +:php:class:`DateTime`. -The Etag Header -~~~~~~~~~~~~~~~ +El encabezado de la etiqueta electrónica +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. php:method:: withEtag($tag, $weak = false) -Cache validation in HTTP is often used when content is constantly changing, and -asks the application to only generate the response contents if the cache is no -longer fresh. Under this model, the client continues to store pages in the -cache, but it asks the application every time -whether the resource has changed, instead of using it directly. -This is commonly used with static resources such as images and other assets. +La validación de caché en HTTP se usa a menudo cuando el contenido cambia constantemente y le pide a la aplicación que +solo genere el contenido de la respuesta si el caché ya no está actualizado. Bajo este modelo, el cliente continúa +almacenando páginas en el caché, pero pregunta a la aplicación cada vez si el recurso ha cambiado, en lugar de usarlo +directamente. Esto se usa comúnmente con recursos estáticos como imágenes y otros activos. -The ``withEtag()`` method (called entity tag) is a string -that uniquely identifies the requested resource, as a checksum does for a file, -in order to determine whether it matches a cached resource. +El método ``withEtag()`` (llamado etiqueta de entidad) es una cadena que identifica de forma única el recurso solicitado, +como lo hace una suma de comprobación para un archivo, para determinar si coincide con un recurso almacenado en caché. -To take advantage of this header, you must either call the -``checkNotModified()`` method manually or include the -:doc:`/controllers/components/check-http-cache` in your controller:: +Para aprovechar este encabezado, debe llamar al método ``checkNotModified()`` manualmente o incluir +:doc:`/controllers/components/check-http-cache` en su controlador:: public function index() { $articles = $this->Articles->find('all')->all(); - // Simple checksum of the article contents. - // You should use a more efficient implementation - // in a real world application. + // Suma de comprobación simple del contenido del artículo. + // Debería utilizar una implementación más eficiente en una aplicación del mundo real. $checksum = md5(json_encode($articles)); $response = $this->response->withEtag($checksum); @@ -949,22 +884,20 @@ To take advantage of this header, you must either call the .. note:: - Most proxy users should probably consider using the Last Modified Header - instead of Etags for performance and compatibility reasons. + La mayoría de los usuarios de proxy probablemente deberían considerar usar el encabezado de última modificación en + lugar de Etags por razones de rendimiento y compatibilidad. -The Last Modified Header -~~~~~~~~~~~~~~~~~~~~~~~~ +El último encabezado modificado +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. php:method:: withModified($time) -Also, under the HTTP cache validation model, you can set the ``Last-Modified`` -header to indicate the date and time at which the resource was modified for the -last time. Setting this header helps CakePHP tell caching clients whether the -response was modified or not based on their cache. +Además, bajo el modelo de validación de caché HTTP, puede configurar el encabezado ``Last-Modified`` para indicar la +fecha y hora en la que se modificó el recurso por última vez. Configurar este encabezado ayuda a CakePHP a decirle a los +clientes de almacenamiento en caché si la respuesta se modificó o no según su caché. -To take advantage of this header, you must either call the -``checkNotModified()`` method manually or include the -:doc:`/controllers/components/check-http-cache` in your controller:: +Para aprovechar este encabezado, debe llamar al método ``checkNotModified()`` manualmente o incluir +:doc:`/controllers/components/check-http-cache` en su controlador:: public function view() { @@ -977,74 +910,72 @@ To take advantage of this header, you must either call the // ... } -The Vary Header -~~~~~~~~~~~~~~~ +El encabezado variable +~~~~~~~~~~~~~~~~~~~~~~ .. php:method:: withVary($header) -In some cases, you might want to serve different content using the same URL. -This is often the case if you have a multilingual page or respond with different -HTML depending on the browser. Under such circumstances you can use the ``Vary`` -header:: +En algunos casos, es posible que desee publicar contenido diferente utilizando la misma URL. Este suele ser el caso si +tiene una página multilingüe o responde con HTML diferente según el navegador. En tales circunstancias, puede utilizar +el encabezado ``Vary``:: $response = $this->response->withVary('User-Agent'); $response = $this->response->withVary('Accept-Encoding', 'User-Agent'); $response = $this->response->withVary('Accept-Language'); -Sending Not-Modified Responses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Envío de respuestas no modificadas +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. php:method:: checkNotModified(Request $request) -Compares the cache headers for the request object with the cache header from the -response and determines whether it can still be considered fresh. If so, deletes -the response content, and sends the `304 Not Modified` header:: +Compara los encabezados de la caché del objeto de solicitud con el encabezado de la caché de la respuesta y determina +sitodavía se puede considerar nuevo. Si es así, elimina el contenido de la respuesta y envía el encabezado +`304 Not Modified`:: - // In a controller action. + // En una acción del controlador. if ($this->response->checkNotModified($this->request)) { return $this->response; } .. _response-cookies: -Setting Cookies ---------------- +Configuración de cookies +------------------------ -Cookies can be added to response using either an array or a :php:class:`Cake\\Http\\Cookie\\Cookie` -object:: +Las cookies se pueden agregar a la respuesta usando una matriz o un objeto :php:class:`Cake\\Http\\Cookie\\Cookie`:: use Cake\Http\Cookie\Cookie; use DateTime; - // Add a cookie + // Agregar una cookie $this->response = $this->response->withCookie(Cookie::create( 'remember_me', 'yes', - // All keys are optional + // Todas las claves son opcionales. [ 'expires' => new DateTime('+1 year'), 'path' => '', 'domain' => '', 'secure' => false, 'httponly' => false, - 'samesite' => null // Or one of CookieInterface::SAMESITE_* constants + 'samesite' => null // O una de las constantes CookieInterface::SAMESITE_* ] )); -See the :ref:`creating-cookies` section for how to use the cookie object. You -can use ``withExpiredCookie()`` to send an expired cookie in the response. This -will make the browser remove its local cookie:: +Consulte la sección :ref:`creating-cookies` para saber cómo utilizar el objeto cookie. Puede utilizar +``withExpiredCookie()`` para enviar una cookie caducada en la respuesta. Esto hará que el navegador elimine su cookie +local:: $this->response = $this->response->withExpiredCookie(new Cookie('remember_me')); .. _cors-headers: -Setting Cross Origin Request Headers (CORS) -=========================================== +Configuración de encabezados de solicitud de origen cruzado (CORS) +================================================================== -The ``cors()`` method is used to define `HTTP Access Control -`__ -related headers with a fluent interface:: +El método ``cors()`` se utiliza para definir +``Control de acceso HTTP `__ encabezados +relacionados con una interfaz fluida:: $this->response = $this->response->cors($this->request) ->allowOrigin(['*.cakephp.org']) @@ -1055,73 +986,68 @@ related headers with a fluent interface:: ->maxAge(300) ->build(); -CORS related headers will only be applied to the response if the following -criteria are met: +Los encabezados relacionados con CORS solo se aplicarán a la respuesta si se cumplen los siguientes criterios: #. The request has an ``Origin`` header. #. The request's ``Origin`` value matches one of the allowed Origin values. .. tip:: - CakePHP has no built-in CORS middleware because dealing with CORS requests - is very application specific. We recommend you build your own ``CORSMiddleware`` - if you need one and adjust the response object as desired. + CakePHP no tiene middleware CORS incorporado porque manejar solicitudes CORS es muy específico de la aplicación. + Le recomendamos que cree su propio ``CORSMiddleware`` si lo necesita y ajuste el objeto de respuesta como desee. -Common Mistakes with Immutable Responses -======================================== +Errores comunes con respuestas inmutables +========================================= -Response objects offer a number of methods that treat -responses as immutable objects. Immutable objects help prevent difficult to -track accidental side-effects, and reduce mistakes caused by method calls caused -by refactoring that change ordering. While they offer a number of benefits, -immutable objects can take some getting used to. Any method that starts with -``with`` operates on the response in an immutable fashion, and will **always** -return a **new** instance. Forgetting to retain the modified instance is the most -frequent mistake people make when working with immutable objects:: +Los objetos de respuesta ofrecen varios métodos que tratan las respuestas como objetos inmutables. Los objetos inmutables +ayudan a prevenir efectos secundarios accidentales difíciles de rastrear y reducen los errores causados por llamadas a +métodos causadas por la refactorización que cambia el orden. Si bien ofrecen una serie de beneficios, es posible que sea +necesario algo de tiempo para acostumbrarse a los objetos inmutables. Cualquier método que comience con ``with`` opera +en la respuesta de forma inmutable y **siempre** devolverá una **nueva** instancia. Olvidar conservar la instancia +modificada es el error más frecuente que cometen las personas cuando trabajan con objetos inmutables: $this->response->withHeader('X-CakePHP', 'yes!'); -In the above code, the response will be lacking the ``X-CakePHP`` header, as the -return value of the ``withHeader()`` method was not retained. To correct the -above code you would write:: +En el código anterior, a la respuesta le faltará el encabezado ``X-CakePHP``, ya que el valor de retorno del método +``withHeader()`` no se retuvo. Para corregir el código anterior escribirías:: $this->response = $this->response->withHeader('X-CakePHP', 'yes!'); .. php:namespace:: Cake\Http\Cookie -Cookie Collections -================== +Colección de Cookies +===================== .. php:class:: CookieCollection -``CookieCollection`` objects are accessible from the request and response objects. -They let you interact with groups of cookies using immutable patterns, which -allow the immutability of the request and response to be preserved. +Se puede acceder a los objetos ``CookieCollection`` desde los objetos de solicitud y respuesta. Le permiten interactuar +con grupos de cookies utilizando patrones inmutables, que permiten preservar la inmutabilidad de la solicitud y la +respuesta. .. _creating-cookies: -Creating Cookies ----------------- +Creando cookies +--------------- .. php:class:: Cookie -``Cookie`` objects can be defined through constructor objects, or by using the -fluent interface that follows immutable patterns:: +Los objetos ``Cookie`` se pueden definir a través de objetos constructores o utilizando la interfaz fluida que sigue +patrones inmutables:: use Cake\Http\Cookie\Cookie; - // All arguments in the constructor + // Todos los argumentos en el constructor. $cookie = new Cookie( - 'remember_me', // name - 1, // value - new DateTime('+1 year'), // expiration time, if applicable - '/', // path, if applicable - 'example.com', // domain, if applicable - false, // secure only? - true // http only ? + 'remember_me', // nombre + 1, // valor + new DateTime('+1 year'), // tiempo de vencimiento, si corresponde + '/', // ruta, si corresponde + 'example.com', // dominio, si corresponde + false, // ¿Solo seguro? + true // ¿Solo http? ); - // Using the builder methods + // Usando los métodos constructores $cookie = (new Cookie('remember_me')) ->withValue('1') ->withExpiry(new DateTime('+1 year')) @@ -1130,67 +1056,63 @@ fluent interface that follows immutable patterns:: ->withSecure(false) ->withHttpOnly(true); -Once you have created a cookie, you can add it to a new or existing -``CookieCollection``:: +Una vez que haya creado una cookie, puede agregarla a una ``CookieCollection`` nueva o existente:: use Cake\Http\Cookie\CookieCollection; - // Create a new collection + // Crear una nueva colección $cookies = new CookieCollection([$cookie]); - // Add to an existing collection + // Agregar a una colección existente $cookies = $cookies->add($cookie); - // Remove a cookie by name + // Eliminar una cookie por nombre $cookies = $cookies->remove('remember_me'); .. note:: - Remember that collections are immutable and adding cookies into, or removing - cookies from a collection, creates a *new* collection object. + Recuerde que las colecciones son inmutables y agregar o eliminar cookies de una colección crea un *nuevo* objeto + de colección. -Cookie objects can be added to responses:: +Se pueden agregar objetos cookie a las respuestas:: - // Add one cookie + // Agregar una cookie $response = $this->response->withCookie($cookie); - // Replace the entire cookie collection + // Reemplazar toda la colección de cookies $response = $this->response->withCookieCollection($cookies); -Cookies set to responses can be encrypted using the -:ref:`encrypted-cookie-middleware`. +Las cookies configuradas para las respuestas se pueden cifrar utilizando :ref:`middleware-cookie-encrypted`. -Reading Cookies +Leyendo Cookies --------------- -Once you have a ``CookieCollection`` instance, you can access the cookies it -contains:: +Una vez que tenga una instancia ``CookieCollection``, podrá acceder a las cookies que contiene:: - // Check if a cookie exists + // Comprobar si existe una cookie $cookies->has('remember_me'); - // Get the number of cookies in the collection + // Obtener el número de cookies de la colección. count($cookies); - // Get a cookie instance. Will throw an error if the cookie is not found + // Obtener una instancia de cookie. Lanzará un error si no se encuentra la cookie. $cookie = $cookies->get('remember_me'); - // Get a cookie or null + // Obtener una cookie o nulo $cookie = $cookies->remember_me; - // Check if a cookie exists + // Comprobar si existe una cookie $exists = isset($cookies->remember_me) -Once you have a ``Cookie`` object you can interact with it's state and modify -it. Keep in mind that cookies are immutable, so you'll need to update the -collection if you modify a cookie:: +Una vez que tenga un objeto ``Cookie``, puede interactuar con su estado y modificarlo. Tenga en cuenta que las cookies +son inmutables, por lo que deberá actualizar la colección si modifica una cookie:: - // Get the value + // Obtener el valor $value = $cookie->getValue() - // Access data inside a JSON value + // Acceder a datos dentro de un valor JSON $id = $cookie->read('User.id'); - // Check state + // Comprobar estado $cookie->isHttpOnly(); $cookie->isSecure(); From 39e83d38ff7f7f57b40cd18a523a68a9eec81817 Mon Sep 17 00:00:00 2001 From: Alberto Rodriguez Date: Sat, 18 Nov 2023 15:43:50 -0400 Subject: [PATCH 107/337] minor fix --- es/controllers/request-response.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index 5eff5f62e5..539d77e696 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -10,8 +10,8 @@ respuesta le permite crear respuestas HTTP sin esfuerzo desde sus controladores. .. index:: $this->request .. _cake-request: -Petición -======== +Solicitud (Request) +=================== .. php:class:: ServerRequest @@ -28,13 +28,13 @@ Algunas de las tareas que realiza ``ServerRequest`` incluyen: la dirección IP del cliente y los nombres de subdominio/dominio en el servidor en el que se ejecuta su aplicación. * Proporcionar acceso a los parámetros de solicitud tanto como índices de matriz como propiedades de objetos. -El objeto de petición de CakePHP implementa `PSR-7 ServerRequestInterface `_, lo que +El objeto de la solicitud de CakePHP implementa `PSR-7 ServerRequestInterface `_, lo que facilita el uso de bibliotecas desde fuera de CakePHP. .. _request-parameters: -Parámetros de petición ----------------------- +Parámetros de la solicitud +-------------------------- La solicitud expone los parámetros de enrutamiento a través del método ``getParam()``:: @@ -83,8 +83,8 @@ Si desea acceder a todos los parámetros de consulta, puede utilizar ``getQueryP $query = $this->request->getQueryParams(); -Datos del cuerpo de la petición -------------------------------- +Datos del cuerpo de la solicitud +-------------------------------- .. php:method:: getData($name, $default = null) From b1b04f61acfa88bcdd57a3608a6f1233bda58a85 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 19 Nov 2023 22:56:41 -0500 Subject: [PATCH 108/337] Make http client variable consistent We had some mismatched examples. --- en/core-libraries/httpclient.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/en/core-libraries/httpclient.rst b/en/core-libraries/httpclient.rst index 8c66cc20fa..95dc9a6168 100644 --- a/en/core-libraries/httpclient.rst +++ b/en/core-libraries/httpclient.rst @@ -59,8 +59,8 @@ If you have created a PSR-7 request object you can send it using 'http://example.com/search', ClientRequest::METHOD_GET ); - $client = new Client(); - $response = $client->sendRequest($request); + $http = new Client(); + $response = $http->sendRequest($request); Creating Multipart Requests with Files ====================================== @@ -477,7 +477,7 @@ instead. You can force select a transport adapter using a constructor option:: use Cake\Http\Client\Adapter\Stream; - $client = new Client(['adapter' => Stream::class]); + $http = new Client(['adapter' => Stream::class]); Events ====== From 14b46a076c832d8d5e97003efaf250a5ea7998f5 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 20 Nov 2023 10:31:18 -0500 Subject: [PATCH 109/337] Fix formatting --- en/core-libraries/httpclient.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/en/core-libraries/httpclient.rst b/en/core-libraries/httpclient.rst index 95dc9a6168..32bb491ded 100644 --- a/en/core-libraries/httpclient.rst +++ b/en/core-libraries/httpclient.rst @@ -489,6 +489,8 @@ caching, logging etc. HttpClient.beforeSend --------------------- +:: + // Somewhere before calling one of the HTTP client's methods which makes a request $http->getEventManager()->on( 'HttpClient.beforeSend', @@ -512,6 +514,8 @@ HttpClient.beforeSend HttpClient.afterSend --------------------- +:: + // Somewhere before calling one of the HTTP client's methods which makes a request $http->getEventManager()->on( 'HttpClient.afterSend', From 53a1c08f32235806118a11bebed11cd5f3565ecc Mon Sep 17 00:00:00 2001 From: nitramx Date: Mon, 20 Nov 2023 21:10:22 +0100 Subject: [PATCH 110/337] Update Table::get() params in docs from array to named args --- en/orm/retrieving-data-and-resultsets.rst | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index e39b27107a..e38e78c2cf 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -41,9 +41,7 @@ viewing entities and their related data. You can do this by using ``get()``:: $article = $articles->get($id); // Get a single article, and related comments - $article = $articles->get($id, [ - 'contain' => ['Comments'], - ]); + $article = $articles->get($id, contain: ['Comments']); If the get operation does not find any results a ``Cake\Datasource\Exception\RecordNotFoundException`` will be raised. You can @@ -56,27 +54,19 @@ Like ``find()``, ``get()`` also has caching integrated. You can use the // In a controller or table method. // Use any cache config or CacheEngine instance & a generated key - $article = $articles->get($id, [ - 'cache' => 'custom', - ]); + $article = $articles->get($id, cache: 'custom'); // Use any cache config or CacheEngine instance & specific key - $article = $articles->get($id, [ - 'cache' => 'custom', 'key' => 'mykey' - ]); + $article = $articles->get($id, cache: 'custom', key: 'mykey'); // Explicitly disable caching - $article = $articles->get($id, [ - 'cache' => false - ]); + $article = $articles->get($id, cache: false); Optionally you can ``get()`` an entity using :ref:`custom-find-methods`. For example you may want to get all translations for an entity. You can achieve that by using the ``finder`` option:: - $article = $articles->get($id, [ - 'finder' => 'translations', - ]); + $article = $articles->get($id, 'translations'); The list of options supported by get() are: From 8675d5dd6e41c6a6ff60425a075133a0ebbdb56e Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 21 Nov 2023 17:43:48 -0500 Subject: [PATCH 111/337] Update migration guide for cakephp/cakephp#17401 --- en/appendices/5-1-upgrade-guide.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 13ae586242..10b140e8b8 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -5,6 +5,15 @@ 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 +================ + +- 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. + Deprecations ============ From cc5ceb429587cfb5428f61b8659a19d865df24bc Mon Sep 17 00:00:00 2001 From: Alberto Rodriguez Date: Wed, 22 Nov 2023 06:58:28 -0400 Subject: [PATCH 112/337] fix: html references --- es/controllers/request-response.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index 539d77e696..fc9fe1c4c8 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -46,7 +46,7 @@ Para obtener todos los parámetros de enrutamiento como una matriz, use ``getAtt Se accede a todos los :ref:`route-elements` a través de esta interfaz. -Además de :ref:`elementos-de-ruta`, a menudo también necesita acceso a :ref:`argumentos-pasados`. Ambos también están +Además de :ref:`route-elements`, a menudo también necesita acceso a :ref:`passed-arguments`. Ambos también están disponibles en el objeto de solicitud: // Argumentos pasados @@ -1081,7 +1081,7 @@ Se pueden agregar objetos cookie a las respuestas:: // Reemplazar toda la colección de cookies $response = $this->response->withCookieCollection($cookies); -Las cookies configuradas para las respuestas se pueden cifrar utilizando :ref:`middleware-cookie-encrypted`. +Las cookies configuradas para las respuestas se pueden cifrar utilizando :ref:`encrypted-cookie-middleware`. Leyendo Cookies --------------- From d3cada55ba3454d02c7b16a5c57fb2a522b4e586 Mon Sep 17 00:00:00 2001 From: Alberto Rodriguez Date: Wed, 22 Nov 2023 07:11:55 -0400 Subject: [PATCH 113/337] minor fixes --- es/controllers/request-response.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index fc9fe1c4c8..f44e72fdb9 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -299,7 +299,7 @@ detectores que puedes crear: * Comparación basada en opciones: las comparaciones basadas en opciones utilizan una lista de opciones para crear una expresión regular. Las llamadas posteriores para agregar un detector de opciones ya definido fusionarán las opciones. * Detectores de devolución de llamada: los detectores de devolución de llamada le permiten proporcionar un tipo de - "callback" para manejar la verificación. La devolución de llamada recibirá el objeto de solicitud como único parámetro. + "callback" para manejar la verificación. La devolución de llamada recibirá el objeto de solicitud como único parámetro. .. php:method:: addDetector($name, $options) @@ -555,7 +555,7 @@ Las solicitudes exponen los datos del archivo cargado en ``getData()`` o ``getUp $files[0]->moveTo($targetPath); Manipulación de URI ------------------ +------------------- Las solicitudes contienen un objeto URI, que contiene métodos para interactuar con el URI solicitado:: From 398d04c34da119ea564e0bb441845bcd17b8ac70 Mon Sep 17 00:00:00 2001 From: Alberto Rodriguez Date: Wed, 22 Nov 2023 07:34:17 -0400 Subject: [PATCH 114/337] minor fixes --- es/controllers/request-response.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index f44e72fdb9..ab695f10c8 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -226,7 +226,7 @@ Variables de entorno (de $_SERVER y $_ENV) .. php:method:: putenv($key, $value = null) ``ServerRequest::getEnv()`` es un contenedor para la función global ``getenv()`` y actúa como un captador/establecedor de -variables de entorno sin tener que modificar los globales ``$_SERVER`` y ``$_ENV` `:: +variables de entorno sin tener que modificar los globales ``$_SERVER`` y ``$_ENV``:: // Obtener el host $host = $this->request->getEnv('HTTP_HOST'); @@ -701,9 +701,7 @@ Para establecer una cadena como cuerpo de respuesta, haga lo siguiente: $response = $response->withStringBody('My Body'); // Si quieres una respuesta json - $response = $response - ->withType('application/json') - ->withStringBody(json_encode(['Foo' => 'bar'])); + $response = $response->withType('application/json')->withStringBody(json_encode(['Foo' => 'bar'])); .. php:method:: withBody($body) @@ -815,7 +813,7 @@ encabezado. Establecer una respuesta como privada indica que toda o parte de ell aprovechar las cachés compartidas, la directiva de control debe configurarse como pública. El segundo parámetro de este método se utiliza para especificar una ``max-age`` para el caché, que es el número de -segundos después de los cuales la respuesta ya no se considera nueva: +segundos después de los cuales la respuesta ya no se considera nueva:: public function view() { From fdf653ec9bfc9f12a9cecaf24dde05bd5a95b962 Mon Sep 17 00:00:00 2001 From: Alberto Rodriguez Date: Wed, 22 Nov 2023 07:39:49 -0400 Subject: [PATCH 115/337] minor format fixes --- es/controllers/request-response.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index ab695f10c8..7e653e53a3 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -971,9 +971,8 @@ local:: Configuración de encabezados de solicitud de origen cruzado (CORS) ================================================================== -El método ``cors()`` se utiliza para definir -``Control de acceso HTTP `__ encabezados -relacionados con una interfaz fluida:: +El método ``cors()`` se utiliza para definir `Control de acceso HTTP +`__ encabezados relacionados con una interfaz fluida:: $this->response = $this->response->cors($this->request) ->allowOrigin(['*.cakephp.org']) From 3ebddf5d522e969ca7b6000dc19844ae125e9ff9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florencio=20Hern=C3=A1ndez?= Date: Thu, 23 Nov 2023 07:49:40 +0000 Subject: [PATCH 116/337] Create spanish translation to development/routing --- es/development/routing.rst | 1508 ++++++++++++++++++------------------ 1 file changed, 769 insertions(+), 739 deletions(-) diff --git a/es/development/routing.rst b/es/development/routing.rst index 2babaf749a..8e50db6d36 100644 --- a/es/development/routing.rst +++ b/es/development/routing.rst @@ -5,40 +5,40 @@ Routing .. php:class:: RouterBuilder -Routing provides you tools that map URLs to controller actions. By defining -routes, you can separate how your application is implemented from how its URLs -are structured. +El enrutamiento te provee de herramientas que permiten mapear URLs a acciones +de un controlador. Al definir rutas, puedes separar cómo está implementada tu +aplicación y cómo están estructuradas sus URLs. -Routing in CakePHP also encompasses the idea of reverse routing, where an array -of parameters can be transformed into a URL string. By using reverse routing, -you can re-factor your application's URL structure without having to update all -your code. +El enrutamiento en CakePHP también abarca la idea de enrutamiento inverso, donde +una matriz de parámetros se puede transformar en una cadena URL. Al utilizar el +enrutamiento inverso, puedes refactorizar la estructura de tus URLs sin necesidad +de actualizar todo tu código. .. index:: routes.php -Quick Tour -========== +Vistazo rápido +============== -This section will teach you by example the most common uses of the CakePHP -Router. Typically you want to display something as a landing page, so you add -this to your **config/routes.php** file:: +Esta sección te enseñará los usos más comunes del enrutamiento en CakePHP con +ejemplos. Normalmente deseas mostrar algo como una página de destino, por lo que +tendrás que añadir esto a tu archivo **config/routes.php**:: /** @var \Cake\Routing\RouteBuilder $routes */ $routes->connect('/', ['controller' => 'Articles', 'action' => 'index']); -This will execute the index method in the ``ArticlesController`` when the -homepage of your site is visited. Sometimes you need dynamic routes that will -accept multiple parameters, this would be the case, for example of a route for -viewing an article's content:: +Esto ejecutará el método index que se encuentra en ``ArticlesController`` cuando +se visite la página principal de tu sitio. A veces necesitas rutas dinámicas que +aceptarán múltiples parámetos, por ejemplo cuando necesites una ruta para ver +el contenido de un artículo:: $routes->connect('/articles/*', ['controller' => 'Articles', 'action' => 'view']); -The above route will accept any URL looking like ``/articles/15`` and invoke the -method ``view(15)`` in the ``ArticlesController``. This will not, though, -prevent people from trying to access URLs looking like ``/articles/foobar``. If -you wish, you can restrict some parameters to conform to a regular expression:: +La ruta anterior aceptará cualquier URL que se parezca a ``/article/15`` e invocará +el método ``view(15)`` de ``ArticlesController``. Esto no prevendrá que las personas +intenten acceder a URLs como ``/articles/foobar``. Si quieres, puedes restringir +algunos parámetros que se ajusten a una expresión regular:: - // Using fluent interface + // Utilizando una interfaz fluida $routes->connect( '/articles/{id}', ['controller' => 'Articles', 'action' => 'view'], @@ -46,34 +46,36 @@ you wish, you can restrict some parameters to conform to a regular expression:: ->setPatterns(['id' => '\d+']) ->setPass(['id']); - // Using options array + // Utilizando una matriz de opciones $routes->connect( '/articles/{id}', ['controller' => 'Articles', 'action' => 'view'], ['id' => '\d+', 'pass' => ['id']] ); -The previous example changed the star matcher by a new placeholder ``{id}``. -Using placeholders allows us to validate parts of the URL, in this case we used -the ``\d+`` regular expression so that only digits are matched. Finally, we told -the Router to treat the ``id`` placeholder as a function argument to the -``view()`` function by specifying the ``pass`` option. More on using this -option later. +En el ejemplo anterior se cambió el comparador asterisco por un nuevo marcador de +posición ``{id}``. Utilizar marcadores de posición nos permite valiadr partes de +la URL, en este caso utilizamos la expresión regular ``\d+`` por lo que sólo los +dígitos son comparados. Finalmente, le indicamos al enrutador que trate el marcador +de posición ``id`` como un argumento de función para el método ``view()`` +especificando la opción ``pass``. +Hablaremos más sobre el uso de esta opción más adelante. -The CakePHP Router can also reverse match routes. That means that from an -array containing matching parameters, it is capable of generating a URL string:: +El enrutador de CakePHP también puede revertir rutas de coincidencia. Esto quiere +decir que desde una matriz que contiene parámetros de coincidencia es capaz de generar +una cadena de URL:: use Cake\Routing\Router; echo Router::url(['controller' => 'Articles', 'action' => 'view', 'id' => 15]); - // Will output + // Obtendrás como salida /articles/15 -Routes can also be labelled with a unique name, this allows you to quickly -reference them when building links instead of specifying each of the routing -parameters:: +Las rutas también pueden etiquetarse con un nombre único, esto te permite referenciarlas +rápidamente cuando creas enlaces en lugar de especificar cada uno de los parámetros de +la ruta:: - // In routes.php + // En routes.php $routes->connect( '/upgrade', ['controller' => 'Subscriptions', 'action' => 'create'], @@ -83,52 +85,53 @@ parameters:: use Cake\Routing\Router; echo Router::url(['_name' => 'upgrade']); - // Will output + // Obtendrás como salida /upgrade -To help keep your routing code DRY, the Router has the concept of 'scopes'. -A scope defines a common path segment, and optionally route defaults. Any routes -connected inside a scope will inherit the path/defaults from their wrapping -scopes:: +Para ayudar a mantener tu código de enrutamiento :term:`DRY`, el Enrutador tiene el concepto +de 'ámbitos'. +Un ámbito define un segmento de ruta común y, opcionalmente, rutas predeterminadas. +Cualquier ruta conectada dentro de un ámbito heredará la ruta y valores por defecto +de su ámbito:: $routes->scope('/blog', ['plugin' => 'Blog'], function (RouteBuilder $routes) { $routes->connect('/', ['controller' => 'Articles']); }); -The above route would match ``/blog/`` and send it to +La rua anterior coincidiría con ``/blog/`` y la enviaría a ``Blog\Controller\ArticlesController::index()``. -The application skeleton comes with a few routes to get you started. Once you've -added your own routes, you can remove the default routes if you don't need them. +El esqueleto de la aplicación viene con algunas rutas de inicio. Una vez has añadido +tus tuyas propias, puedes eliminar las rutas por defecto si no las necesitas. .. index:: {controller}, {action}, {plugin} .. index:: greedy star, trailing star .. _connecting-routes: .. _routes-configuration: -Connecting Routes -================= +Conectando Rutas +================ -To keep your code :term:`DRY` you should use 'routing scopes'. Routing -scopes not only let you keep your code DRY, they also help Router optimize its -operation. This method defaults to the ``/`` scope. To create a scope and connect -some routes we'll use the ``scope()`` method:: +Para mantener tu código :term:`DRY` debes utilizar 'ámbitos de ruta'. Los ámbitos +de ruta no sólo te facilitan mantener tu código DRY, sino que ayudan al Enrutador a +optimizar sus operaciones. Este método se aplica por defecto al ámbito ``/``. Para +crear un ámbito y conectar algunas rutas utilizarás el método ``scope()``:: - // In config/routes.php + // En config/routes.php use Cake\Routing\RouteBuilder; use Cake\Routing\Route\DashedRoute; $routes->scope('/', function (RouteBuilder $routes) { - // Connect the generic fallback routes. + // Conecta las rutas alternativas genéricas. $routes->fallbacks(DashedRoute::class); }); -The ``connect()`` method takes up to three parameters: the URL template you wish -to match, the default values for your route elements, and the options for the -route. Options frequently include regular expression rules to help the router -match elements in the URL. +El método ``connect()`` acepta hasta tres parámetros: la plantilla de URL para la que +deseas conincidencias, los valores predeterminados para los elementos de tu ruta. +Las opciones frecuentemente incluyen reglas de expresión regular que para ayudar al +enrutador a coincidir con elementos de la URL. -The basic format for a route definition is:: +El formato básico para la definición de una ruta es:: $routes->connect( '/url/template', @@ -136,126 +139,125 @@ The basic format for a route definition is:: ['option' => 'matchingRegex'] ); -The first parameter is used to tell the router what sort of URL you're trying to -control. The URL is a normal slash delimited string, but can also contain -a wildcard (\*) or :ref:`route-elements`. Using a wildcard tells the router -that you are willing to accept any additional arguments supplied. Routes without -a \* only match the exact template pattern supplied. +El primer parámetro se utiliza para indicarle al enrutador qué tipo de URL se +está intentando controlar. La URL es una cadena normal delimitada por barras +diagonales, pero también puede contener un comodín (\*) o :ref:`route-elements`. +El uso de un comodín le indica al enrutador que puede aceptar cualquier argumento +adicional que se le proporcione. Las rutas sin \* sólo coincidirán con el patrón +de plantilla exacto proporcionado. -Once you've specified a URL, you use the last two parameters of ``connect()`` to -tell CakePHP what to do with a request once it has been matched. The second -parameter defines the route 'target'. This can be defined either as an array, or -as a destination string. A few examples of route targets are:: +Una vez que hayas especificado una URL, utiliza los dos últimos parámetros de +``connect()`` para indicar a CakePHP qué debe hacer con la solicitud cuando +haya coincidencia. El segundo parámetro define la ruta 'objetivo'. Esto se puede +definir como una matriz o como una cadena de destino. Algunos ejemplos de ruta +objetivo son:: - // Array target to an application controller + // Matriz de destino a un controlador de aplicación $routes->connect( '/users/view/*', ['controller' => 'Users', 'action' => 'view'] ); $routes->connect('/users/view/*', 'Users::view'); - // Array target to a prefixed plugin controller + // Matriz de destino a un controlador de plugin con prefijo $routes->connect( '/admin/cms/articles', ['prefix' => 'Admin', 'plugin' => 'Cms', 'controller' => 'Articles', 'action' => 'index'] ); $routes->connect('/admin/cms/articles', 'Cms.Admin/Articles::index'); -The first route we connect matches URLs starting with ``/users/view`` and maps -those requests to the ``UsersController->view()``. The trailing ``/*`` tells the -router to pass any additional segments as method arguments. For example, -``/users/view/123`` would map to ``UsersController->view(123)``. +La primera ruta que conectamos coincide con las URL que comienzan con ``/users/view`` +y asigna esas solucitudes al ``UsersController->view()``. El ``/*`` indica al enrutador +para pasar cualquier segmento adicional como argumentos del método. Por ejemplo, +``/users/view/123`` se asignaría a ``UsersController->view(123)``. -The above example also illustrates string targets. String targets provide -a compact way to define a route's destination. String targets have the following -syntax:: +El ejemplo anterior también ilustra los destinos de cadena. Los destinos de cadena +proporcionan una forma compacta de definir el destino de una ruta. Los destinos de +cadena tienen la siguiente sintaxis:: [Plugin].[Prefix]/[Controller]::[action] -Some example string targets are:: +Algunos ejemplos de destino de cadena son:: - // Application controller + // Controlador de aplicación 'Articles::view' - // Application controller with prefix + // Controlador de aplicación con prefijo Admin/Articles::view - // Plugin controller + // Controlador de plugin Cms.Articles::edit - // Prefixed plugin controller + // Controlador de plugin con prefijo Vendor/Cms.Management/Admin/Articles::view -Earlier we used the greedy star (``/*``) to capture additional path segments, -there is also the trailing star (``/**``). Using a trailing double star, -will capture the remainder of a URL as a single passed argument. This is useful -when you want to use an argument that included a ``/`` in it:: +Anteriormente usamos el asterisco final (``/*``) para capturar segmentos de ruta adicionales, +también está el doble asterisco final (``/**``). Utilizando el doble asterisco final, +capturará el resto de una URL como un único argumento. Esto es útil cuando se desea +utilizar un argumento que incluye ``/``:: $routes->connect( '/pages/**', ['controller' => 'Pages', 'action' => 'show'] ); -The incoming URL of ``/pages/the-example-/-and-proof`` would result in a single -passed argument of ``the-example-/-and-proof``. +La URL entrante ``/pages/the-example-/-and-proof`` daría como resultado el paso de un +único argumento ``the-example-/-and-proof``. -The second parameter of ``connect()`` can define any parameters that -compose the default route parameters:: +El segundo parámetro de ``connect()`` puede definir cualquier parámetro para componer +los parámetros de ruta po predeterminado:: $routes->connect( '/government', ['controller' => 'Pages', 'action' => 'display', 5] ); -This example uses the second parameter of ``connect()`` to -define default parameters. If you built an application that features products for -different categories of customers, you might consider creating a route. This -allows you to link to ``/government`` rather than ``/pages/display/5``. +Este ejemplo utiliza el segundo parámetro de ``connect()`` para definir los parámetros +predeterminados. Si creas una aplicación que presenta productos para diferentes categorías +de clientes, podrías considerar crear una ruta. Esto permite enlazar ``/government`` en +lugar de ``/pages/display/5``. -A common use for routing is to rename controllers and their actions. Instead of -accessing our users controller at ``/users/some-action/5``, we'd like to be able -to access it through ``/cooks/some-action/5``. The following route takes care of -that:: +Un uso común del enrutamiento es renombrar los controladores y sus acciones. En lugar de +acceder a nuestro controlador de usuarios como ``/users/some-action/5``, nos gustaría acceder +a él a través de ``/cooks/some-action/5``. La siguiente ruta se encarga de eso:: $routes->connect( '/cooks/{action}/*', ['controller' => 'Users'] ); -This is telling the Router that any URL beginning with ``/cooks/`` should be -sent to the ``UsersController``. The action called will depend on the value of -the ``{action}`` parameter. By using :ref:`route-elements`, you can create -variable routes, that accept user input or variables. The above route also uses -the greedy star. The greedy star indicates that this route should accept any -additional positional arguments given. These arguments will be made available in -the :ref:`passed-arguments` array. - -When generating URLs, routes are used too. Using -``['controller' => 'Users', 'action' => 'some-action', 5]`` as -a URL will output ``/cooks/some-action/5`` if the above route is the -first match found. - -The routes we've connected so far will match any HTTP verb. If you are building -a REST API you'll often want to map HTTP actions to different controller methods. -The ``RouteBuilder`` provides helper methods that make defining routes for -specific HTTP verbs simpler:: - - // Create a route that only responds to GET requests. +Esto indica al enrutador que cualquier URL que empieze por ``/cooks/`` deberá ser +enviada al ``UsersController``. La acción invocada dependerá del valor del parámetro ``{action}``. +Utilizando :ref:`route-elements`, puedes crear rutas variables que aceptan entradas del usuario +o variables. La ruta anterior también utiliza el asteristo final. El asterisco final indica que +esta ruta debe aceptar cualquier argumento posicional adicional dado. Estos argumentos estarán +disponibles en la matriz :ref:`passed-arguments`. + +Al generar URL también se utilizan rutas. Utilizando +``['controller' => 'Users', 'action' => 'some-action', 5]`` como una URL, generará +``/cooks/some-action/5`` si la ruta anterior es la primera coincidencia encontrada. + +Las ruts que hemos conectado hasta ahora coincidirán con cualquier tipo de petición HTTP. Si estás +contruyendo un API REST, a menudo querrás asignar acciones HTTP a diferentes métodos de +controlador. El ``RouteBuilder`` proporciona métodos auxiliares que facilitan la definición +de rutas para tipos de peticiones HTTP específicas más simples:: + + // Crea una ruta que sólo responde a peticiones GET. $routes->get( '/cooks/{id}', ['controller' => 'Users', 'action' => 'view'], 'users:view' ); - // Create a route that only responds to PUT requests + // Crea una ruta que sólo responde a peticiones PUT $routes->put( '/cooks/{id}', ['controller' => 'Users', 'action' => 'update'], 'users:update' ); -The above routes map the same URL to different controller actions based on the -HTTP verb used. GET requests will go to the 'view' action, while PUT requests -will go to the 'update' action. There are HTTP helper methods for: +Las rutas anteriores asignan la misma URL a diferentes acciones del controlador según +el tipo de petición HTTP utilizada. Las solicitudes GET irán a la acción 'view', mientras +que las solicitudes PUT irán a la acción UPDATE. Existen métodos auxiliares HTTP para: * GET * POST @@ -265,22 +267,22 @@ will go to the 'update' action. There are HTTP helper methods for: * OPTIONS * HEAD -All of these methods return the route instance allowing you to leverage the -:ref:`fluent setters ` to further configure your route. +Todos estos métodos devuelven una instancia de ruta, lo que permite aprovechar la +:ref:`fluent setterts ` para configurar aún más la ruta. .. _route-elements: -Route Elements --------------- +Elementos de ruta +----------------- -You can specify your own route elements and doing so gives you the -power to define places in the URL where parameters for controller -actions should lie. When a request is made, the values for these -route elements are found in ``$this->request->getParam()`` in the controller. -When you define a custom route element, you can optionally specify a regular -expression - this tells CakePHP how to know if the URL is correctly formed or -not. If you choose to not provide a regular expression, any non ``/`` character -will be treated as part of the parameter:: +Puedes especificar tus propios elementos de ruta y al hacerlo podrás definir los +lugares de la URL donde los parámetros para las acciones del controlador deben estar. +Cuando se realiza una solicitud, los valores para estos elementos de ruta se encuentran +en ``$this->request->getParam()`` en el controlador. +Cuando defines un elemento de ruta personalizado, opcionalmente puedes especificar +una expresión regular; esto le dice a CakePHP como saber si la URL está formada +correctamente o no. Si eliges no proporcionar una expresión regular, cualquier caracter +que no sea ``/`` será tratado como parte del parámetro:: $routes->connect( '/{controller}/{id}', @@ -293,22 +295,21 @@ will be treated as part of the parameter:: ['id' => '[0-9]+'] ); -The above example illustrates how to create a quick way to view -models from any controller by crafting a URL that looks like -``/controllername/{id}``. The URL provided to ``connect()`` specifies two -route elements: ``{controller}`` and ``{id}``. The ``{controller}`` element -is a CakePHP default route element, so the router knows how to match and -identify controller names in URLs. The ``{id}`` element is a custom -route element, and must be further clarified by specifying a -matching regular expression in the third parameter of ``connect()``. +El ejemplo anterior ilustra cómo crear una forma rápida de ver modelos desde cualquier +controlador creando una URL que se parezca a ``/controllername/{id}``. La URL proporcionada +a ``connect()`` especifica dos elementos de ruta: ``{controller}`` y ``{id}``. El elemento +``{controller}`` es un elemento de ruta predeterminado de CakePHP, por lo que el enrutador +conoce cómo identificar y emparejar los nombres de controladores en la URL. El elemento +``{id}`` es un elemento de ruta personalizado y debe aclararse especificando una expresión +regular en el tercer parámetro de ``connect()``. -CakePHP does not automatically produce lowercased and dashed URLs when using the -``{controller}`` parameter. If you need this, the above example could be -rewritten like so:: +CakePHP no produce automáticamente URL en minúsculas y con guiones cuando utiliza el +parámetro ``{controller}``. Si necesitas hacer esto, el ejemplo anterior podría ser +reescrito así:: use Cake\Routing\Route\DashedRoute; - // Create a builder with a different route class. + // Crea un constructor con una clase de ruta diferente $routes->scope('/', function (RouteBuilder $routes) { $routes->setRouteClass(DashedRoute::class); $routes->connect('/{controller}/{id}', ['action' => 'view']) @@ -321,35 +322,36 @@ rewritten like so:: ); }); -The ``DashedRoute`` class will make sure that the ``{controller}`` and -``{plugin}`` parameters are correctly lowercased and dashed. +La clase ``DashedRoute`` se asegurará de que los parámetros ``{controller}`` y +``{plugin}`` están correctamente en minúsculas y con guiones. .. note:: - Patterns used for route elements must not contain any capturing - groups. If they do, Router will not function correctly. + Los patrones utilizados por los elementos de ruta no deben contener + ningún grupo de captura. Si lo hacen, el enrutador no funcionará + correctamente. -Once this route has been defined, requesting ``/apples/5`` would call the ``view()`` -method of the ApplesController. Inside the ``view()`` method, you would need to -access the passed ID at ``$this->request->getParam('id')``. +Una vez que se ha definido esta ruta, al solicitar ``/apples/5`` se llamará al método +``view()`` de ApplesController. Dento del método ``view()``, necesitarás acceder al ID +pasado en ``$this->request->getParam('id')``. -If you have a single controller in your application and you do not want the -controller name to appear in the URL, you can map all URLs to actions in your -controller. For example, to map all URLs to actions of the ``home`` controller, -e.g have URLs like ``/demo`` instead of ``/home/demo``, you can do the -following:: +Si tienes un único controlador en tu aplicación y no quieres que el nombre del +controlador aparezca en la URL, puedes asignar todas las URL a acciones en tu +controlador. Por ejemplo, para asignar todas las URL a acciones del contolador +``home``, para tener una URL como ``/demo`` en lugar de ``/home/demo``, puedes +hacer lo siguiente:: $routes->connect('/{action}', ['controller' => 'Home']); -If you would like to provide a case insensitive URL, you can use regular -expression inline modifiers:: +Si quieres proporcionar una URL que no distinga entre mayúsculas y minúsculas, +puedes utilizar modificadores en línea de expresiones regulares:: $routes->connect( '/{userShortcut}', ['controller' => 'Teachers', 'action' => 'profile', 1], )->setPatterns(['userShortcut' => '(?i:principal)']); -One more example, and you'll be a routing pro:: +Un ejemplo más y serás un profesional del enrutamiento:: $routes->connect( '/{controller}/{year}/{month}/{day}', @@ -360,98 +362,99 @@ One more example, and you'll be a routing pro:: 'day' => '0[1-9]|[12][0-9]|3[01]' ]); -This is rather involved, but shows how powerful routes can be. The URL supplied -has four route elements. The first is familiar to us: it's a default route -element that tells CakePHP to expect a controller name. +Esto es bastante complicado, pero muestra cuán poderosas pueden ser las rutas. La URL +proporcionada tiene cuatro elementos de ruta. El primero nos resulta familiar: es +un elemento de ruta por defecto que incica a CakePHP que espere un nombre de controlador. -Next, we specify some default values. Regardless of the controller, -we want the ``index()`` action to be called. +A continuación, especificamos algunos valores predeterminados. Independientemente +del controlador, queremos que se llame a la acción ``index()``. -Finally, we specify some regular expressions that will match years, -months and days in numerical form. Note that parenthesis (capturing groups) -are not supported in the regular expressions. You can still specify -alternates, as above, but not grouped with parenthesis. +Finalmente, especificamos algunas expresiones regulares que coincidirán con año, mes +y día en forma numérica. Ten en cuenta que los paréntesis (captura de grupos) no se +admiten en expresiones regulares. Aún podemos especificar alternativas, como se +indicó anteriormente, pero no agrupadas entre paréntesis. -Once defined, this route will match ``/articles/2007/02/01``, -``/articles/2004/11/16``, handing the requests to -the ``index()`` actions of their respective controllers, with the date -parameters in ``$this->request->getParam()``. +Una vez definida, esta ruta coincidirá con ``/articles/2007/02/01``, +``/articles/2004/11/16``, entregando las solicitudes a la acción ``index()`` +de sus respectivos controladores, con los parámetros de fecha en +``$this->request->getParams()``. -Reserved Route Elements ------------------------ +Elementos de Ruta Reservados +---------------------------- -There are several route elements that have special meaning in -CakePHP, and should not be used unless you want the special meaning - -* ``controller`` Used to name the controller for a route. -* ``action`` Used to name the controller action for a route. -* ``plugin`` Used to name the plugin a controller is located in. -* ``prefix`` Used for :ref:`prefix-routing` -* ``_ext`` Used for :ref:`File extentions routing `. -* ``_base`` Set to ``false`` to remove the base path from the generated URL. If - your application is not in the root directory, this can be used to generate - URLs that are 'cake relative'. -* ``_scheme`` Set to create links on different schemes like `webcal` or `ftp`. - Defaults to the current scheme. -* ``_host`` Set the host to use for the link. Defaults to the current host. -* ``_port`` Set the port if you need to create links on non-standard ports. -* ``_full`` If ``true`` the value of ``App.fullBaseUrl`` mentioned in - :ref:`general-configuration` will be prepended to generated URLs. -* ``#`` Allows you to set URL hash fragments. -* ``_https`` Set to ``true`` to convert the generated URL to https or ``false`` - to force http. Prior to 4.5.0 use ``_ssl``. -* ``_method`` Define the HTTP verb/method to use. Useful when working with +Hay varios elementos de ruta que tienen un significado especial en CakePHP, +y no deben usarse a menos que desee un significado especial + +* ``controller`` Se utiliza para nombrar el controlador de una ruta. +* ``action`` Se utiliza para nombrar la acción del controlador para una ruta. +* ``plugin`` Se utiliza para nombrar el complemento en el que se encuentra un controlador. +* ``prefix`` Usado para :ref:`prefix-routing` +* ``_ext`` Usado para :ref:`File extentions routing `. +* ``_base`` Se establece a ``false`` para eliminar la ruta base de la URL generada. Si + su aplicación no está en el directorio raíz, esto puede utilizarse para generar URL + que son 'cake relative'. +* ``_scheme`` Configurado para crear enlaces en diferentes esquemas como `webcal` o `ftp`. + El valor predeterminado es el esquema actual. +* ``_host`` Establece el host que se utilizará para el enlace. El valor predeterminado + es el host actual. +* ``_port`` Establece el puerto si necesitamos crear enlaces en puertos no estándar. +* ``_full`` Si es ``true`` el valor de ``App.fullBaseUrl`` mencionado en + :ref:`general-configuration` se atepondrá a la URL generada. +* ``#`` Permite configurar fragmentos de hash de URL. +* ``_https`` Establecerlo en ``true`` para convertir la URL generada a https o``false`` + para forzar http. Antes de 4.5.0 utilizar ``_ssl``. +* ``_method`` Define el tipo de petición/método a utilizar. Útil cuando trabajamos con :ref:`resource-routes`. -* ``_name`` Name of route. If you have setup named routes, you can use this key - to specify it. +* ``_name`` Nombre de la ruta. Si has configurado rutas con nombre, puedes utilizar + esta clave para especificarlo. .. _route-fluent-methods: -Configuring Route Options -------------------------- +Configurando Opciones de Ruta +----------------------------- -There are a number of route options that can be set on each route. After -connecting a route you can use its fluent builder methods to further configure -the route. These methods replace many of the keys in the ``$options`` parameter -of ``connect()``:: +Hay varias opciones de ruta que se pueden configurar en cada ruta. Después de +conectar una ruta, puedes utilizar sus métodos de creación fluidos para configurar +aún más la ruta. Estos métodos reemplazan muchas de las claves en el parámetro +``$options`` de ``connect()``:: $routes->connect( '/{lang}/articles/{slug}', ['controller' => 'Articles', 'action' => 'view'], ) - // Allow GET and POST requests. + // Permite peticiones GET y POST. ->setMethods(['GET', 'POST']) - // Only match on the blog subdomain. + // Sólo coincide con el subdominio del blog. ->setHost('blog.example.com') - // Set the route elements that should be converted to passed arguments + // Establecer los elementos de ruta que deben convertirse en argumentos pasados ->setPass(['slug']) - // Set the matching patterns for route elements + // Establecer los patrones de coincidencia para los elementos de ruta ->setPatterns([ 'slug' => '[a-z0-9-_]+', 'lang' => 'en|fr|es', ]) - // Also allow JSON file extensions + // También permite archivos con extensión JSON ->setExtensions(['json']) - // Set lang to be a persistent parameter + // Establecer lang para que sea un parámetro persistente ->setPersist(['lang']); -Passing Parameters to Action ----------------------------- +Pasar Parámetros a una Acción +----------------------------- -When connecting routes using :ref:`route-elements` you may want to have routed -elements be passed arguments instead. The ``pass`` option indicates which route -elements should also be made available as arguments passed into the controller -functions:: +Cuando conectamos rutas utilizando ::ref:`route-elements` es posible que desees +que los elementos enrutados se pasen como argumentos. La opción ``pass`` indica +qué elementos de ruta también deben estaar disponibles como argumentos pasados +a las funciones del controlador:: // src/Controller/BlogsController.php public function view($articleId = null, $slug = null) { - // Some code here... + // Algún código aquí... } // routes.php @@ -460,23 +463,25 @@ functions:: '/blog/{id}-{slug}', // For example, /blog/3-CakePHP_Rocks ['controller' => 'Blogs', 'action' => 'view'] ) - // Define the route elements in the route template - // to prepend as function arguments. Order matters as this - // will pass the `$id` and `$slug` elements as the first and - // second parameters. Any additional passed parameters in your - // route will be added after the setPass() arguments. + // Definir los elementos de ruta en la plantilla de ruta + // para anteponerlos como argumentos de la función. El orden + // es importante ya que esto pasará los elementos `$id` y `$slug` + // como primer y segundo parámetro. Cualquier otro parámetro + // adicional pasado en tu ruta se agregará después de los + // argumentos de setPass(). ->setPass(['id', 'slug']) - // Define a pattern that `id` must match. + // Definir un patrón con el que `id` debe coincidir. ->setPatterns([ 'id' => '[0-9]+', ]); }); -Now thanks to the reverse routing capabilities, you can pass in the URL array -like below and CakePHP will know how to form the URL as defined in the routes:: +Ahora, gracias a las capacidades de enturamiento inverso, puedes pasar la matriz +de URL como se muestra a continuación y CakePHP sabrá cómo formar la URL como se +define en las rutas:: // view.php - // This will return a link to /blog/3-CakePHP_Rocks + // Esto devolverá un enlace a /blog/3-CakePHP_Rocks echo $this->Html->link('CakePHP Rocks', [ 'controller' => 'Blog', 'action' => 'view', @@ -484,7 +489,7 @@ like below and CakePHP will know how to form the URL as defined in the routes:: 'slug' => 'CakePHP_Rocks' ]); - // You can also used numerically indexed parameters. + // También podemos utilizar índices numéricos como parámetros. echo $this->Html->link('CakePHP Rocks', [ 'controller' => 'Blog', 'action' => 'view', @@ -494,159 +499,164 @@ like below and CakePHP will know how to form the URL as defined in the routes:: .. _path-routing: -Using Path Routing ------------------- +Uso del Enrutamiento de Ruta +---------------------------- -We talked about string targets above. The same also works for URL generation using -``Router::pathUrl()``:: +Hablamos de objetivos de cadena anteriormente. Lo mismo también funciona para la +generación de URL usando ``Router::pathUrl()``:: echo Router::pathUrl('Articles::index'); - // outputs: /articles + // salida: /articles echo Router::pathUrl('MyBackend.Admin/Articles::view', [3]); - // outputs: /admin/my-backend/articles/view/3 + // salida: /admin/my-backend/articles/view/3 .. tip:: - IDE support for Path Routing autocomplete can be enabled with `CakePHP IdeHelper Plugin `_. + La compatibilidad del IDE para el autocompletado del enrutamiento de ruta se puede habilitar con `CakePHP IdeHelper Plugin `_. .. _named-routes: -Using Named Routes ------------------- +Usar Rutas con Nombre +--------------------- -Sometimes you'll find typing out all the URL parameters for a route too verbose, -or you'd like to take advantage of the performance improvements that named -routes have. When connecting routes you can specify a ``_name`` option, this -option can be used in reverse routing to identify the route you want to use:: +A veces encontrarás que escribir todos los parámetros de la URL para una ruta es +demasiado detallado, o le gustaría aprovechar las mejoras de rendimiento que tienen +las rutas con nombre. Al conectar rutas, puedes especificar una opción ``_name``, +esta opción se puede utilizar en rutas inversas para identificar la ruta que deseas +utilizar:: - // Connect a route with a name. + // Conectar una ruta con nombre. $routes->connect( '/login', ['controller' => 'Users', 'action' => 'login'], ['_name' => 'login'] ); - // Name a verb specific route + // Nombrar una ruta específica según el tipo de petición $routes->post( '/logout', ['controller' => 'Users', 'action' => 'logout'], 'logout' ); - // Generate a URL using a named route. + // Generar una URL utilizando una ruta con nombre. $url = Router::url(['_name' => 'logout']); - // Generate a URL using a named route, - // with some query string args. + // Generar una URL utilizando una ruta con nombre, + // con algunos argumentos de cadena en la consulta. $url = Router::url(['_name' => 'login', 'username' => 'jimmy']); -If your route template contains any route elements like ``{controller}`` you'll -need to supply those as part of the options to ``Router::url()``. +Si tu plantilla de ruta contienen elementos de ruta como ``{controller}`` deberás +proporcionarlos como parte de las opciones de ``Router::url()``. .. note:: - Route names must be unique across your entire application. The same - ``_name`` cannot be used twice, even if the names occur inside a different - routing scope. + Los nombres de las rutas deben ser únicos en toda la aplicación. El mismo + ``_name`` no se puede utilizar dos veces, incluso si los nombres aparecen + dentro de un alcance de enrutamiento diferente. -When building named routes, you will probably want to stick to some conventions -for the route names. CakePHP makes building up route names easier by allowing -you to define name prefixes in each scope:: +Al crear rutas con nombre, probablemente querrás ceñirte a algunas convenciones +par alos nombres de las rutas. CakePHP facilita la creación de nombres de rutas +al permitir definir prefijos de nombres en cada ámbito:: $routes->scope('/api', ['_namePrefix' => 'api:'], function (RouteBuilder $routes) { - // This route's name will be `api:ping` + // El nombre de esta ruta será `api:ping` $routes->get('/ping', ['controller' => 'Pings'], 'ping'); }); - // Generate a URL for the ping route + // Generar una URL para la ruta de ping Router::url(['_name' => 'api:ping']); - // Use namePrefix with plugin() + // Utilizar namePrefix con plugin() $routes->plugin('Contacts', ['_namePrefix' => 'contacts:'], function (RouteBuilder $routes) { - // Connect routes. + // Conectar rutas. }); - // Or with prefix() + // O con prefix() $routes->prefix('Admin', ['_namePrefix' => 'admin:'], function (RouteBuilder $routes) { - // Connect routes. + // Conectar rutas. }); -You can also use the ``_namePrefix`` option inside nested scopes and it works as -you'd expect:: +También puedes utilizar la opción ``_namePrefix`` dentro de ámbitos anidados y +funciona como se esperaba:: $routes->plugin('Contacts', ['_namePrefix' => 'contacts:'], function (RouteBuilder $routes) { $routes->scope('/api', ['_namePrefix' => 'api:'], function (RouteBuilder $routes) { - // This route's name will be `contacts:api:ping` + // Este nombre de ruta será `contacts:api:ping` $routes->get('/ping', ['controller' => 'Pings'], 'ping'); }); }); - // Generate a URL for the ping route + // Generar una URL para la ruta de ping Router::url(['_name' => 'contacts:api:ping']); +Las rutas conectadas en ámbitos con nombre sólo se les agregarán nombres si la +ruta también tiene nombre. A las rutas sin nombre no se les aplicará el ``_namePrefix``. Routes connected in named scopes will only have names added if the route is also named. Nameless routes will not have the ``_namePrefix`` applied to them. .. index:: admin routing, prefix routing .. _prefix-routing: -Prefix Routing --------------- +Enrutamiento de Prefijo +----------------------- .. php:staticmethod:: prefix($name, $callback) -Many applications require an administration section where -privileged users can make changes. This is often done through a -special URL such as ``/admin/users/edit/5``. In CakePHP, prefix routing -can be enabled by using the ``prefix`` scope method:: +Muchas aplicaciones requieren una sección de adminitración donde +los usuarios con privilegios puedan realizar cambios. Esto se hace +a menudo a través de una URL especial como ``/admin/users/edit/5``. +En CakePHP, el enrutamiento de prefijo puede ser habilitado utilizando +el método de ámbito ``prefix``:: use Cake\Routing\Route\DashedRoute; $routes->prefix('Admin', function (RouteBuilder $routes) { - // All routes here will be prefixed with `/admin`, and - // have the `'prefix' => 'Admin'` route element added that - // will be required when generating URLs for these routes + // Todas las rutas aquí tendrán el prefijo `/admin`, y + // tendrán el elemento de ruta `'prefix' => 'Admin'` agregado que + // será necesario para generar URL para estas rutas $routes->fallbacks(DashedRoute::class); }); -Prefixes are mapped to sub-namespaces in your application's ``Controller`` -namespace. By having prefixes as separate controllers you can create smaller and -simpler controllers. Behavior that is common to the prefixed and non-prefixed -controllers can be encapsulated using inheritance, -:doc:`/controllers/components`, or traits. Using our users example, accessing -the URL ``/admin/users/edit/5`` would call the ``edit()`` method of our -**src/Controller/Admin/UsersController.php** passing 5 as the first parameter. -The view file used would be **templates/Admin/Users/edit.php** +Los prefijos se asignan a subespacios de nombres en el espacio de nombres +``Controller`` en tu aplicación. Al tener prefijos como controladores separados, +puedes crear controladores más pequeños y simples. El comportamiento que es común +a los controladores con y sin prefijo se puede encapsular mediante herencia, +:doc:`/controllers/components`, o traits. Utilizando nuestro ejemplo de usuarios, +acceder a la URL ``/admin/users/edit/5`` llamaría al médito ``edit()`` de nuestro +**src/Controller/Admin/UsersController.php** pasando 5 como primer parámetro. +El archivo de vista utilizado sería **templates/Admin/Users/edit.php** -You can map the URL /admin to your ``index()`` action of pages controller using -following route:: +Puedes asignar la URL /admin a tu acción ``index()`` del controlador pages utilizando +la siguiente ruta:: $routes->prefix('Admin', function (RouteBuilder $routes) { - // Because you are in the admin scope, - // you do not need to include the /admin prefix - // or the Admin route element. + // Dado que te encuentras en el ámbito de admin, + // no necesitas incluir el prefijo /admin ni el + // elemento de ruta Admin. $routes->connect('/', ['controller' => 'Pages', 'action' => 'index']); }); -When creating prefix routes, you can set additional route parameters using -the ``$options`` argument:: +Al crear rutas de prefijo, puedes establecer parámetros de ruta adicionales +utilizando el argumento ``$options``:: $routes->prefix('Admin', ['param' => 'value'], function (RouteBuilder $routes) { - // Routes connected here are prefixed with '/admin' and - // have the 'param' routing key set. + // Las rutas conectadas aquí tienen el prefijo '/admin' y + // tienen configurada la clave de enrutamiento 'param'. $routes->connect('/{controller}'); }); -Multi word prefixes are by default converted using dasherize inflection, ie ``MyPrefix`` -would be mapped to ``my-prefix`` in the URL. Make sure to set a path for such prefixes -if you want to use a different format like for example underscoring:: +Los prefijos con varias palabras se convierten de forma predeterminada utilizando la +inflexión dasherize, es decir, ``MyPrefix`` se asignará a ``my-prefix``en la URL. +Asegúrate de establecer una ruta para dichos prefijos si deseas utilizar un formato +diferente como, por ejemplo, subrayado:: $routes->prefix('MyPrefix', ['path' => '/my_prefix'], function (RouteBuilder $routes) { - // Routes connected here are prefixed with '/my_prefix' + // Las rutas conectadas aquí tiene el prefijo '/my_prefix' $routes->connect('/{controller}'); }); -You can define prefixes inside plugin scopes as well:: +También puedes definir prefijos dentro del alcance de un plugin:: $routes->plugin('DebugKit', function (RouteBuilder $routes) { $routes->prefix('Admin', function (RouteBuilder $routes) { @@ -654,10 +664,10 @@ You can define prefixes inside plugin scopes as well:: }); }); -The above would create a route template like ``/debug-kit/admin/{controller}``. -The connected route would have the ``plugin`` and ``prefix`` route elements set. +Lo anterior crearía una plantilla de ruta como ``/debug-kit/admin/{controller}``. +La ruta conectada tendría establecidos los elementos de ruta ``plugin`` y ``prefix``. -When defining prefixes, you can nest multiple prefixes if necessary:: +Al definir prefijos, puedes anidar varios prefijos si es necesario:: $routes->prefix('Manager', function (RouteBuilder $routes) { $routes->prefix('Admin', function (RouteBuilder $routes) { @@ -665,24 +675,23 @@ When defining prefixes, you can nest multiple prefixes if necessary:: }); }); -The above would create a route template like ``/manager/admin/{controller}/{action}``. -The connected route would have the ``prefix`` route element set to -``Manager/Admin``. +Lo anterior crearía una plantilla de ruta como ``/manager/admin/{controller}/{action}``. +La ruta conectada tendría establecido el elemento de ruta ``prefix`` a ``Manager/Admin``. -The current prefix will be available from the controller methods through +El prefijo actual estará disponible desde los métodos del controlador a través de ``$this->request->getParam('prefix')`` -When using prefix routes it's important to set the ``prefix`` option, and to -use the same CamelCased format that is used in the ``prefix()`` method. Here's -how to build this link using the HTML helper:: +Cuando usamos rutas de prefijo es importante configurar la opción ``prefix`` y +utilizar el mismo formato CamelCased que se utiliza in el método ``prefix()``. +A continuación se explico cómo crear este enlace utilizando el helper HTML:: - // Go into a prefixed route. + // Ve a una ruta de prefijo echo $this->Html->link( 'Manage articles', ['prefix' => 'Manager/Admin', 'controller' => 'Articles', 'action' => 'add'] ); - // Leave a prefix + // Deja un prefijo echo $this->Html->link( 'View Post', ['prefix' => false, 'controller' => 'Articles', 'action' => 'view', 5] @@ -690,56 +699,57 @@ how to build this link using the HTML helper:: .. index:: plugin routing -Creating Links to Prefix Routes -------------------------------- +Crear Enlaces a Rutas de Prefijo +-------------------------------- -You can create links that point to a prefix, by adding the prefix key to your -URL array:: +Puedes crear enlaces que apunten a un prefijo añadiendo la clave del prefijo a la matriz +de URL:: echo $this->Html->link( 'New admin todo', ['prefix' => 'Admin', 'controller' => 'TodoItems', 'action' => 'create'] ); -When using nesting, you need to chain them together:: +Al utilizar anidamiento, es necesario encadenarlos entre sí:: echo $this->Html->link( 'New todo', ['prefix' => 'Admin/MyPrefix', 'controller' => 'TodoItems', 'action' => 'create'] ); -This would link to a controller with the namespace ``App\\Controller\\Admin\\MyPrefix`` and the file path -``src/Controller/Admin/MyPrefix/TodoItemsController.php``. +Esto se vincularía a un controlador con el espacio de nombre ``App\\Controller\\Admin\\MyPrefix`` y +la ruta de archivo ``src/Controller/Admin/MyPrefix/TodoItemsController.php``. .. note:: - The prefix is always CamelCased here, even if the routing result is dashed. - The route itself will do the inflection if necessary. + Aquí el prefijo siempre es CamelCased, incluso si el resultado del enrutamiento + es discontinuo. + La propia ruta hará la inflexión si es necesario. -Plugin Routing --------------- +Enrutamiento de Plugin +---------------------- .. php:staticmethod:: plugin($name, $options = [], $callback) -Routes for :doc:`/plugins` should be created using the ``plugin()`` -method. This method creates a new routing scope for the plugin's routes:: +Las rutas para :doc:`/plugins` deben crearse utilizando el método ``plugin()``. +Este método crea un nuevo ámbito de enrutamiento para las rutas del plugin:: $routes->plugin('DebugKit', function (RouteBuilder $routes) { - // Routes connected here are prefixed with '/debug-kit' and - // have the plugin route element set to 'DebugKit'. + // Las rutas conectadas aquí tienen el prefijo '/debug-kit' y + // el elemento de ruta plugin configurado a 'DebugKit'. $routes->connect('/{controller}'); }); -When creating plugin scopes, you can customize the path element used with the -``path`` option:: +Cuando creamos ámbitos de plugin, puedes personalizar el elemento de ruta utilizado +con la opción ``path``:: $routes->plugin('DebugKit', ['path' => '/debugger'], function (RouteBuilder $routes) { - // Routes connected here are prefixed with '/debugger' and - // have the plugin route element set to 'DebugKit'. + // Las rutas conectadas aquí tiene el prefijo '/debugger' y + // el elemento de ruta plugin configurado a 'DebugKit'. $routes->connect('/{controller}'); }); -When using scopes you can nest plugin scopes within prefix scopes:: +Al utilizar ámbitos, puedes anidar ámbitos de plugin dentro de ámbitos de prefijos:: $routes->prefix('Admin', function (RouteBuilder $routes) { $routes->plugin('DebugKit', function (RouteBuilder $routes) { @@ -747,43 +757,43 @@ When using scopes you can nest plugin scopes within prefix scopes:: }); }); -The above would create a route that looks like ``/admin/debug-kit/{controller}``. -It would have the ``prefix``, and ``plugin`` route elements set. The -:ref:`plugin-routes` section has more information on building plugin routes. +Lo anteior crearía una ruta similar a ``/admin/debug-kit/{controller}``. +Tendría configurados los elementos de ruta ``prefix`` y ``plugin``. En la sección +:ref:`plugin-routes` hay más información sobre la creación de rutas de plugin. -Creating Links to Plugin Routes +Crear Enlaces a Rutas de Plugin ------------------------------- -You can create links that point to a plugin, by adding the plugin key to your -URL array:: +Puedes crear enlaces que apunten a un plugin añadiendo la clave plugin a tu +matrix de URL:: echo $this->Html->link( 'New todo', ['plugin' => 'Todo', 'controller' => 'TodoItems', 'action' => 'create'] ); -Conversely if the active request is a plugin request and you want to create -a link that has no plugin you can do the following:: +Por el contrario, si la solicitud activa es una solicitud de plugin y deseas crear +un enlace que no tenga plugin puedes hacer lo siguiente:: echo $this->Html->link( 'New todo', ['plugin' => null, 'controller' => 'Users', 'action' => 'profile'] ); -By setting ``'plugin' => null`` you tell the Router that you want to -create a link that is not part of a plugin. +Estableciendo ``'plugin' => null`` le indicas al Enrutador que quieres +crear un enlace que no forme parte de un plugin. -SEO-Friendly Routing --------------------- +Enrutamiento SEO-Friendly +------------------------- -Some developers prefer to use dashes in URLs, as it's perceived to give -better search engine rankings. The ``DashedRoute`` class can be used in your -application with the ability to route plugin, controller, and camelized action -names to a dashed URL. +Algunos desarrolladores prefieren utilizar guiones en las URL, ya que se +percibe que dan un mejor posicionamiento en los motores de búsqueda. +La clase ``DashedRoute`` se puede utilizar en tu aplicación con la capacidad +de enrutar plugin, controlador y acciones camelizadas a una URL con guiones. -For example, if we had a ``ToDo`` plugin, with a ``TodoItems`` controller, and a -``showItems()`` action, it could be accessed at ``/to-do/todo-items/show-items`` -with the following router connection:: +Por ejemplo, si tenemos un plugin ``ToDo``, con un controlador ``TodoItems``, y +una acción ``showItems()``, se podría acceder en ``/to-do/todo-items/show-items`` +con la siguiente conexión de enrutador:: use Cake\Routing\Route\DashedRoute; @@ -791,19 +801,20 @@ with the following router connection:: $routes->fallbacks(DashedRoute::class); }); -Matching Specific HTTP Methods ------------------------------- +Coincidencia de Métodos HTTP Específicos +---------------------------------------- -Routes can match specific HTTP methods using the HTTP verb helper methods:: +Las rutas pueden coincidir con métodos HTTP específicos utilizando los métodos +del helper HTTP:: $routes->scope('/', function (RouteBuilder $routes) { - // This route only matches on POST requests. + // Esta ruta sólo coincide con peticiones POST. $routes->post( '/reviews/start', ['controller' => 'Reviews', 'action' => 'start'] ); - // Match multiple verbs + // Coincide con múltiples tipos de peticiones $routes->connect( '/reviews/start', [ @@ -813,10 +824,10 @@ Routes can match specific HTTP methods using the HTTP verb helper methods:: )->setMethods(['POST', 'PUT']); }); -You can match multiple HTTP methods by using an array. Because the ``_method`` -parameter is a routing key, it participates in both URL parsing and URL -generation. To generate URLs for method specific routes you'll need to include -the ``_method`` key when generating the URL:: +Puedes hacer coincidir múltiples métodos HTTP utilizando una matriz. Dada que el +parámetro ``_method`` es una clave de enturamiento, participa tanto en el análisis +como en la generación de URL. Para generar URLs para rutas específicas de un método +necesitarás incluir la clave ``_method`` al generar la URL:: $url = Router::url([ 'controller' => 'Reviews', @@ -824,38 +835,39 @@ the ``_method`` key when generating the URL:: '_method' => 'POST', ]); -Matching Specific Hostnames ---------------------------- +Coincidencia con Nombres de Dominio Específicos +-------------------------------------------- -Routes can use the ``_host`` option to only match specific hosts. You can use -the ``*.`` wildcard to match any subdomain:: +Las rutas pueden utilizar la opción ``_host`` para coincidir sólo con dominios +específicos. Puedes utilizar el comodín ``*.`` para coincidir con cualquier +subdominio:: $routes->scope('/', function (RouteBuilder $routes) { - // This route only matches on http://images.example.com + // Esta ruta sólo coincide en http://images.example.com $routes->connect( '/images/default-logo.png', ['controller' => 'Images', 'action' => 'default'] )->setHost('images.example.com'); - // This route only matches on http://*.example.com + // Esta ruta sólo coincide en http://*.example.com $routes->connect( '/images/old-log.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('*.example.com'); }); -The ``_host`` option is also used in URL generation. If your ``_host`` option -specifies an exact domain, that domain will be included in the generated URL. -However, if you use a wildcard, then you will need to provide the ``_host`` -parameter when generating URLs:: +La opción ``_host`` también se utiliza en la generación de URL. Si tu opción +``_host`` especifica un dominio exacto, ese dominio se incluirá en la URL +generada. Sin embargo, si utilizas un comodín, tendrás que indicar el parámetro +``_host`` al generar la URL:: - // If you have this route + // Si tienes esta ruta $routes->connect( '/images/old-log.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('images.example.com'); - // You need this to generate a url + // Necesitas esto para generar la URL echo Router::url([ 'controller' => 'Images', 'action' => 'oldLogo', @@ -865,34 +877,33 @@ parameter when generating URLs:: .. index:: file extensions .. _file-extensions: -Routing File Extensions ------------------------ - +Enrutamiento de Extensiones de Archivo +-------------------------------------- .. php:staticmethod:: extensions(string|array|null $extensions, $merge = true) -To handle different file extensions in your URLs, you can define the extensions -using the :php:meth:`Cake\\Routing\\RouteBuilder::setExtensions()` method:: +Para manejar diferentes extensiones de archivo en tus URL, puedes definir las +extensiones utilizando el método :php:meth:`Cake\\Routing\\RouteBuilder::setExtensions()`:: $routes->scope('/', function (RouteBuilder $routes) { $routes->setExtensions(['json', 'xml']); }); -This will enable the named extensions for all routes that are being connected in -that scope **after** the ``setExtensions()`` call, including those that are being -connected in nested scopes. +Esto habilitará ls extensiones nombradas para todas las rutas que se estén conectando +en ese ámbito **después** de la llamada a ``setExtensions()``, incluidas aquellas que +se estén conectando en ámbitos anidados. .. note:: - Setting the extensions should be the first thing you do in a scope, as the - extensions will only be applied to routes connected **after** the extensions - are set. + Configurar las extensiones debe ser lo primero que hagas en un ámbito, ya que + las extensiones sólo se aplicarán a rutas conectadas **después** de configurar + las extensiones. - Also be aware that re-opened scopes will **not** inherit extensions defined in - previously opened scopes. + También ten en cuenta que los ámbitos reabiertos **no** heredarán las extensiones + definidas en ámbitos abiertos anteriormente. -By using extensions, you tell the router to remove any matching file extensions -from the URL, and then parse what remains. If you want to create a URL such as -/page/title-of-page.html you would create your route using:: +Al utilizar extensiones, le indicas al enrutador que elimine cualquier extensión de +archivo coincidente en la URL y luego analice lo que queda. Si deseas crear una URL como +/page/title-of-page.html, crearías su ruta usando:: $routes->scope('/page', function (RouteBuilder $routes) { $routes->setExtensions(['json', 'xml', 'html']); @@ -902,7 +913,7 @@ from the URL, and then parse what remains. If you want to create a URL such as )->setPass(['title']); }); -Then to create links which map back to the routes simply use:: +Luego, para crear enlaces que correspondan con las rutas, simplemente usa:: $this->Html->link( 'Link title', @@ -911,140 +922,140 @@ Then to create links which map back to the routes simply use:: .. _route-scoped-middleware: -Route Scoped Middleware -======================= +Middleware de Ámbito de Ruta +============================ -While Middleware can be applied to your entire application, applying middleware -to specific routing scopes offers more flexibility, as you can apply middleware -only where it is needed allowing your middleware to not concern itself with -how/where it is being applied. +Si bien el Middleware se puede aplicar a toda tu aplicación, aplicar middleware +a ámbitos de enrutamiento específicos ofrece más flexibilidad, ya que puedes aplicar +middleware sólo donde sea necesario, lo que permite que tu middleware no se preocupe +por cómo y dónde se aplica. .. note:: - Applied scoped middleware will be run by :ref:`RoutingMiddleware `, - normally at the end of your application's middleware queue. + El middleware con ámbito aplicado se ejecutará mediante :ref:`RoutingMiddleware `, + normalmente al final de la cola de middleware de tu aplicación. -Before middleware can be applied to a scope, it needs to be -registered into the route collection:: +Antes de que se pueda aplicar middleware a tu acplicación, es necesario +registrarlo en la colección de rutas:: - // in config/routes.php + // en config/routes.php use Cake\Http\Middleware\CsrfProtectionMiddleware; use Cake\Http\Middleware\EncryptedCookieMiddleware; $routes->registerMiddleware('csrf', new CsrfProtectionMiddleware()); $routes->registerMiddleware('cookies', new EncryptedCookieMiddleware()); -Once registered, scoped middleware can be applied to specific -scopes:: +Una vez registrado, el middleware con ámbito se podrá aplicar +a ámbitos específicos:: $routes->scope('/cms', function (RouteBuilder $routes) { - // Enable CSRF & cookies middleware + // Activa CSRF y cookies middleware $routes->applyMiddleware('csrf', 'cookies'); $routes->get('/articles/{action}/*', ['controller' => 'Articles']); }); -In situations where you have nested scopes, inner scopes will inherit the -middleware applied in the containing scope:: +En situaciones en las que tienes ámbitos anidados, los ámbitos internos +heredarán el middleware aplicado en el ámbito contenedor:: $routes->scope('/api', function (RouteBuilder $routes) { $routes->applyMiddleware('ratelimit', 'auth.api'); $routes->scope('/v1', function (RouteBuilder $routes) { $routes->applyMiddleware('v1compat'); - // Define routes here. + // Definir las rutas aquí. }); }); -In the above example, the routes defined in ``/v1`` will have 'ratelimit', -'auth.api', and 'v1compat' middleware applied. If you re-open a scope, the -middleware applied to routes in each scope will be isolated:: +En el ejemplo anterior, las rutas definidas en ``/v1`` tendrán aplicado el +middleware 'ratelimit', 'auth.api' y 'v1compat'. Si vuelves a abrir un ámbito, +el middleware aplicado a las rutas en cada ámbito quedará aislado:: $routes->scope('/blog', function (RouteBuilder $routes) { $routes->applyMiddleware('auth'); - // Connect the authenticated actions for the blog here. + // Conecta las acciones authenticadas para el blog aquí. }); $routes->scope('/blog', function (RouteBuilder $routes) { - // Connect the public actions for the blog here. + // Conecta las acciones públicas para el blog aquí. }); -In the above example, the two uses of the ``/blog`` scope do not share -middleware. However, both of these scopes will inherit middleware defined in -their enclosing scopes. +En el ejemplo anterior, los dos usos del alcance ``/blog`` no comparten middleware. +Sin embargo, ambos ámbitos heredarán el middleware definido en los ámbitos que los +engloban. -Grouping Middleware -------------------- +Agrupación de Middleware +------------------------ -To help keep your route code :abbr:`DRY (Do not Repeat Yourself)` middleware can -be combined into groups. Once combined groups can be applied like middleware -can:: +Para ayudar a mantener tu código de ruta :abbr:`DRY (Do not Repeat Yourself)` el middleware +se puede combinar en grupos. Una vez combinados, los grupos pueden aplicarse como middleware:: $routes->registerMiddleware('cookie', new EncryptedCookieMiddleware()); $routes->registerMiddleware('auth', new AuthenticationMiddleware()); $routes->registerMiddleware('csrf', new CsrfProtectionMiddleware()); $routes->middlewareGroup('web', ['cookie', 'auth', 'csrf']); - // Apply the group + // Aplicar el grupo $routes->applyMiddleware('web'); .. _resource-routes: -RESTful Routing -=============== +Enrutamiento RESTful +==================== -Router helps generate RESTful routes for your controllers. RESTful routes are -helpful when you are creating API endpoints for your application. If we wanted -to allow REST access to a recipe controller, we'd do something like this:: +El enrutador ayuda a generar rutas RESTful para tus controladores. Las rutas RESTful +son útiles cuando estás creando API endpoints para tus aplicaciones. Si quisiéramos +permitir el accesos REST a un controlador de recetas, haríamos algo como esto:: - // In config/routes.php... + // En config/routes.php... $routes->scope('/', function (RouteBuilder $routes) { $routes->setExtensions(['json']); $routes->resources('Recipes'); }); -The first line sets up a number of default routes for REST -access where method specifies the desired result format, for example, xml, -json and rss. These routes are HTTP Request Method sensitive. +La primera línea configura una serie de rutas predeterminadas para el acceso REST +donde el método especifica el formato de resultado deseado, por ejemplo, xml, json +y rss. Estas rutas son sensible al método de solicitud HTTP. -=========== ===================== ============================== -HTTP format URL.format Controller action invoked -=========== ===================== ============================== +=========== ===================== ================================ +HTTP format URL.format Acción del controlador invocada +=========== ===================== ================================ GET /recipes.format RecipesController::index() ------------ --------------------- ------------------------------ +----------- --------------------- -------------------------------- GET /recipes/123.format RecipesController::view(123) ------------ --------------------- ------------------------------ +----------- --------------------- -------------------------------- POST /recipes.format RecipesController::add() ------------ --------------------- ------------------------------ +----------- --------------------- -------------------------------- PUT /recipes/123.format RecipesController::edit(123) ------------ --------------------- ------------------------------ +----------- --------------------- -------------------------------- PATCH /recipes/123.format RecipesController::edit(123) ------------ --------------------- ------------------------------ +----------- --------------------- -------------------------------- DELETE /recipes/123.format RecipesController::delete(123) -=========== ===================== ============================== +=========== ===================== ================================ .. note:: - The default for pattern for resource IDs only matches integers or UUIDs. - If your IDs are different you will have to supply a regular expression pattern - via the ``id`` option, for example, ``$builder->resources('Recipes', ['id' => '.*'])``. + El patrón predeterminado para los ID de recursos sólo coincide con números + enterors o UUID. Si tus ID son diferentes, tendrás que proporcionar un + patrón de expresión regular a través de la opción ``id``, por ejemplo + ``$builder->resources('Recipes', ['id' => '.*'])``. -The HTTP method being used is detected from a few different sources. -The sources in order of preference are: +El método HTTP utilizado se detecta desde algunas fuentes diferentes. +Las fuentes en orden de preferencia son: -#. The ``_method`` POST variable -#. The ``X_HTTP_METHOD_OVERRIDE`` header. -#. The ``REQUEST_METHOD`` header +#. La variable POST ``_method`` +#. El encabezado The ``X_HTTP_METHOD_OVERRIDE``. +#. El encabezado ``REQUEST_METHOD`` -The ``_method`` POST variable is helpful in using a browser as a -REST client (or anything else that can do POST). Just set -the value of ``_method`` to the name of the HTTP request method you -wish to emulate. +La variable POST ``_method`` es útil para utilizar un navegador como +cliente REST (o cualquier otra cosa que pueda realizar POST). +Simplemente establece el valor de ``_method()`` con el nombre del +método de la solicitud HTTP que deseas emular. -Creating Nested Resource Routes -------------------------------- +Crear Rutas de Recursos Anidadas +-------------------------------- -Once you have connected resources in a scope, you can connect routes for -sub-resources as well. Sub-resource routes will be prepended by the original -resource name and a id parameter. For example:: +Una vez hayas conectado recursos en un alcance, también puedes conectar rutas para +subrecursos. Las rutas de subrecursos estarán precedidas por el nombre del recurso +original y un parámetro de identificación. Por ejemplo:: $routes->scope('/api', function (RouteBuilder $routes) { $routes->resources('Articles', function (RouteBuilder $routes) { @@ -1052,19 +1063,19 @@ resource name and a id parameter. For example:: }); }); -Will generate resource routes for both ``articles`` and ``comments``. The -comments routes will look like:: +Generará rutas de recursos tanto para ``articles`` como para ``comments``. +Las rutas de comments se verán así:: /api/articles/{article_id}/comments /api/articles/{article_id}/comments/{id} -You can get the ``article_id`` in ``CommentsController`` by:: +Puedes obtener el ``article_id`` en ``CommentsController`` mediante:: $this->request->getParam('article_id'); -By default resource routes map to the same prefix as the containing scope. If -you have both nested and non-nested resource controllers you can use a different -controller in each context by using prefixes:: +De forma predeterminada, las rutas de recursos se asignan al mismo prefijo que el +ámbito contenedor. Si tienes controladores de recursos anidados y no anidados, puedes +utilizar un controlador diferente en cada contexto mediante el uso de prefijos:: $routes->scope('/api', function (RouteBuilder $routes) { $routes->resources('Articles', function (RouteBuilder $routes) { @@ -1072,64 +1083,65 @@ controller in each context by using prefixes:: }); }); -The above would map the 'Comments' resource to the -``App\Controller\Articles\CommentsController``. Having separate controllers lets -you keep your controller logic simpler. The prefixes created this way are -compatible with :ref:`prefix-routing`. +Lo anterior asignará el recursos 'Comments' a +``App\Controller\Articles\CommentsController``. Tener controladores separados +te permite mantener la lógica del controlador más simple. Los prefijos creados de +esta manera son compatibles con :ref:`prefix-routing`. .. note:: - While you can nest resources as deeply as you require, it is not recommended - to nest more than 2 resources together. + Si bien puedes anidar recursos con la profundidas que necesites, no se recomienda + anidar más de dos recursos juntos. -Limiting the Routes Created ---------------------------- +Limitar las Rutas Creadas +------------------------- -By default CakePHP will connect 6 routes for each resource. If you'd like to -only connect specific resource routes you can use the ``only`` option:: +Por defecto, CakePHP conectará 6 rutas para cada recursos. Si deseas conectar +sólo rutas de recursos específicas podrás utilizar la opción ``only``:: $routes->resources('Articles', [ 'only' => ['index', 'view'] ]); -Would create read only resource routes. The route names are ``create``, -``update``, ``view``, ``index``, and ``delete``. +Crearía rutas de recurso de sólo lectura. Los nombres de las rutas son +``create``, ``update``, ``view``, ``index``, and ``delete``. -The default **route name and controller action used** are as follows: +El **nombre de ruta y acción del controlador utilizados** predeterminados son +los siguientes: -=========== ======================= -Route name Controller action used -=========== ======================= -create add ------------ ----------------------- -update edit ------------ ----------------------- -view view ------------ ----------------------- -index index ------------ ----------------------- -delete delete -=========== ======================= +============== ================================= +Nombre de ruta Acción del controlador utilizada +============== ================================= +create add +-------------- --------------------------------- +update edit +-------------- --------------------------------- +view view +-------------- --------------------------------- +index index +-------------- --------------------------------- +delete delete +============== ================================= -Changing the Controller Actions Used ------------------------------------- +Cambiar las Acciones del Controlador Utilizadas +----------------------------------------------- -You may need to change the controller action names that are used when connecting -routes. For example, if your ``edit()`` action is called ``put()`` you can -use the ``actions`` key to rename the actions used:: +Es posible que debas cambiar los nombres de las acciones del controlador que se +utilizan al conectar rutas. Por ejemplo, si tu acción ``edit()`` se llama ``put()`` +puedes utilizar la clave ``actions`` para renombrar las acciones utilizadas:: $routes->resources('Articles', [ 'actions' => ['update' => 'put', 'create' => 'add'] ]); -The above would use ``put()`` for the ``edit()`` action, and ``add()`` -instead of ``create()``. +Lo anterior utilizaría ``put()`` para la acción ``edit()`` y ``add()`` +en lugar de ``create()``. -Mapping Additional Resource Routes ----------------------------------- +Mapeo de Rutas de Recursos Adicionales +-------------------------------------- -You can map additional resource methods using the ``map`` option:: +Puedes asignar métodos de recursos adicionales utilizando la opción ``map``:: $routes->resources('Articles', [ 'map' => [ @@ -1139,12 +1151,12 @@ You can map additional resource methods using the ``map`` option:: ] ] ]); - // This would connect /articles/deleteAll + // Esto conectaría /articles/deleteAll -In addition to the default routes, this would also connect a route for -`/articles/delete-all`. By default the path segment will match the key name. You -can use the 'path' key inside the resource definition to customize the path -name:: +Además de las rutas predeterminadas, esto también conectaría una ruta para +`/articles/delete-all`. De forma predeterminada, el segmento de ruta coincidirá +con el nombre de la clave. Puedes utilizar la clave 'path' dentro de la defición +del recurso para personalizar el nombre de la ruta:: $routes->resources('Articles', [ 'map' => [ @@ -1155,16 +1167,17 @@ name:: ], ], ]); - // This would connect /articles/update-many + // Esto conectaría /articles/update-many -If you define 'only' and 'map', make sure that your mapped methods are also in -the 'only' list. +Si defines 'only' and 'map', asegúrate de que tus métodos asignados también están +en la lista 'only'. -Prefixed Resource Routing -------------------------- +Enrutamiento de Recursos Prefijados +----------------------------------- -Resource routes can be connected to controllers in routing prefixes by -connecting routes within a prefixed scope or by using the ``prefix`` option:: +[[Continuar]] +Las rutas de recursos pueden conectarse a los controladores en prefijos de +enrutamiento conectando rutas en un ámbito prefijado or utilizando la opción ``prefix``:: $routes->resources('Articles', [ 'prefix' => 'Api', @@ -1172,11 +1185,12 @@ connecting routes within a prefixed scope or by using the ``prefix`` option:: .. _custom-rest-routing: -Custom Route Classes for Resource Routes ----------------------------------------- +Clases de Ruta Personalizada para Rutas de Recursos +--------------------------------------------------- -You can provide ``connectOptions`` key in the ``$options`` array for -``resources()`` to provide custom setting used by ``connect()``:: +Puedes proporcionar la clave ``coneectOptions`` en la matriz ``$options`` para +``resources()`` para proporcionar la configuración personalizada utilizada por +``connect()``:: $routes->scope('/', function (RouteBuilder $routes) { $routes->resources('Books', [ @@ -1186,14 +1200,15 @@ You can provide ``connectOptions`` key in the ``$options`` array for ]; }); -URL Inflection for Resource Routes ----------------------------------- -By default, multi-worded controllers' URL fragments are the dashed -form of the controller's name. For example, ``BlogPostsController``'s URL fragment -would be **/blog-posts**. +Inflexión de URL para Rutas de Recursos +--------------------------------------- -You can specify an alternative inflection type using the ``inflect`` option:: +De forma predeterminada, los fragmentos de URL de los controladores con varias +palabras están en la forma con guiones del nombre del controlador. Por ejemplo, +el fragmento de URL de ``BlogPostsController`` sería **/blog-posts**. + +Puedes especificar un tipo de inflexión alternativo utilizando la opción ``inflect``:: $routes->scope('/', function (RouteBuilder $routes) { $routes->resources('BlogPosts', [ @@ -1201,13 +1216,14 @@ You can specify an alternative inflection type using the ``inflect`` option:: ]); }); -The above will generate URLs styled like: **/blog_posts**. +Lo anterior generará una URL del tipo: **/blog_posts**. -Changing the Path Element -------------------------- +Cambiar el Elemento de Ruta +--------------------------- -By default resource routes use an inflected form of the resource name for the -URL segment. You can set a custom URL segment with the ``path`` option:: +De forma predeterminada, las rutas de recursos utilizan una forma inflexionada +del nombre del recurso para el segmento de URL. Puedes configurar un segmento +de ruta personalizado con la opción ``path``:: $routes->scope('/', function (RouteBuilder $routes) { $routes->resources('BlogPosts', ['path' => 'posts']); @@ -1216,24 +1232,25 @@ URL segment. You can set a custom URL segment with the ``path`` option:: .. index:: passed arguments .. _passed-arguments: -Passed Arguments -================ +Argumentos Pasados +================== -Passed arguments are additional arguments or path segments that are -used when making a request. They are often used to pass parameters -to your controller methods. :: +Los argumentos pasados son argumentos adicionales or segmentos de ruta +que se utilizan al realizar una solicitud. A menudo se utilizan para +pasar parámetros a los métodos de tu controlador:: http://localhost/calendars/view/recent/mark -In the above example, both ``recent`` and ``mark`` are passed arguments to -``CalendarsController::view()``. Passed arguments are given to your controllers -in three ways. First as arguments to the action method called, and secondly they -are available in ``$this->request->getParam('pass')`` as a numerically indexed -array. When using custom routes you can force particular parameters to go into -the passed arguments as well. +En el ejemplo anterior, tanto ``recent`` como ``mark`` se pasan como argumentos a +``CalendarsController::view()``. Los argumentos pasados se entregan a tus +controladores de tres maneras. En primer lugar, como argumentos para el método de +acción llamado y, en segundo lugar, están disponibles en +``$this->request->getParams('pass')`` como una matriz indexada numéricamente. Al +utilizar rutas personalizadas, también puedes forzar que parámetros particulares +entren en los argumentos pasados. -If you were to visit the previously mentioned URL, and you -had a controller action that looked like:: +Si visitara la URL mencionada anteriormente, y tuviera una acción de controlador +similar a:: class CalendarsController extends AppController { @@ -1243,7 +1260,7 @@ had a controller action that looked like:: } } -You would get the following output:: +Otendrías el siguiente resultado:: Array ( @@ -1251,13 +1268,13 @@ You would get the following output:: [1] => mark ) -This same data is also available at ``$this->request->getParam('pass')`` in your -controllers, views, and helpers. The values in the pass array are numerically -indexed based on the order they appear in the called URL:: +Estos mismos datos también están disponibles en ``$this->request->getParam('pass')`` +en tus controladores, vistas y helpers. Los valores en la matriz de paso están +indexados numéricamente según el orden en el que aparecen en la URL llamada:: debug($this->request->getParam('pass')); -Either of the above would output:: +Cualquiera de los anteriores generaría:: Array ( @@ -1265,77 +1282,78 @@ Either of the above would output:: [1] => mark ) -When generating URLs, using a :term:`arreglo de enrutamiento` you add passed -arguments as values without string keys in the array:: +Al generar URL, utilizando un :term:`arreglo de enrutamiento` agregas argumentos +pasados como valores sin claves de cadena en la matriz:: ['controller' => 'Articles', 'action' => 'view', 5] -Since ``5`` has a numeric key, it is treated as a passed argument. +Dado que ``5`` es una clave numérica, se trata como un argumento pasado. -Generating URLs -=============== +Generando URL +============= .. php:staticmethod:: url($url = null, $full = false) .. php:staticmethod:: reverse($params, $full = false) -Generating URLs or Reverse routing is a feature in CakePHP that is used to -allow you to change your URL structure without having to modify all your code. +Generar URL o enrutamiento inverso es una característica de CakePHP que se +utiliza para permitirte cambiar la estructura de tu URL sin tener que modificar +todo tu código. -If you create URLs using strings like:: +Si creas URL utilizando cadenas como:: $this->Html->link('View', '/articles/view/' . $id); -And then later decide that ``/articles`` should really be called -'posts' instead, you would have to go through your entire -application renaming URLs. However, if you defined your link like:: +Y luego decides que ``/articles`` realmente debería llamarse ``posts``, +tendría que ir por toda tu aplicación renombrando las URL. Sin embargo, +si definiste tu enlace como:: - //`link()` uses Router::url() internally and accepts a routing array + //`link()` utiliza internamente Router::url() y acepta una matriz de enrutamiento $this->Html->link( 'View', ['controller' => 'Articles', 'action' => 'view', $id] ); -or:: +o:: - //'Router::reverse()' operates on the request parameters array - //and will produce a url string, valid input for `link()` + //'Router::reverse()' opera en la matriz de parámetos de la petición + //y producirá una cadena de url válida para `link()` $requestParams = Router::getRequest()->getAttribute('params'); $this->Html->link('View', Router::reverse($requestParams)); -Then when you decided to change your URLs, you could do so by defining a -route. This would change both the incoming URL mapping, as well as the -generated URLs. +Luego, cuando decidieras cambiar tus URL, podrías hacerlo definiendo una ruta. +Esto cambiaría tanto la asignación de URL entrante como las URL generadas. -The choice of technique is determined by how well you can predict the routing -array elements. +La elección de la técnica está determinada por qué tan bien se pueden predecir +los elementos de la matriz de enrutamiento. -Using ``Router::url()`` ------------------------ +Utilizando ``Router::url()`` +---------------------------- -``Router::url()`` allows you to use :term:`routing arrays ` in -situations where the array elements required are fixed or easily deduced. +``Router::url()`` te permite utilizar :term:`routing arrays ` +en situaciones donde los elementos requeridos de la matriz son fijos o se deducen +fácilmente. -It will provide reverse routing when the destination url is well defined:: +Proporcionará enrutamiento inverso cuando la url de destino esté bien definida:: $this->Html->link( 'View', ['controller' => 'Articles', 'action' => 'view', $id] ); -It is also useful when the destination is unknown but follows a well -defined pattern:: +También es útil cuando el destino es desconocido pero sigue un patrón bien definido:: $this->Html->link( 'View', ['controller' => $controller, 'action' => 'view', $id] ); -Elements with numeric keys are treated as :ref:`passed-arguments`. +Los elementos con claves numéricas se tratan como :ref:`passed-arguments`. -When using routing arrays, you can define both query string parameters and -document fragments using special keys:: +Al utilizar matrices de enrutamiento, puedes definir tanto los parámetros de +la cadena de consulta como los fragmentos de documentos utilizando claves +especiales:: $routes->url([ 'controller' => 'Articles', @@ -1344,192 +1362,198 @@ document fragments using special keys:: '#' => 'top' ]); - // Will generate a URL like. + // Generará una URL del tipo. /articles/index?page=1#top -You can also use any of the special route elements when generating URLs: - -* ``_ext`` Used for :ref:`file-extensions` routing. -* ``_base`` Set to ``false`` to remove the base path from the generated URL. If - your application is not in the root directory, this can be used to generate - URLs that are 'cake relative'. -* ``_scheme`` Set to create links on different schemes like ``webcal`` or - ``ftp``. Defaults to the current scheme. -* ``_host`` Set the host to use for the link. Defaults to the current host. -* ``_port`` Set the port if you need to create links on non-standard ports. -* ``_method`` Define the HTTP verb the URL is for. -* ``_full`` If ``true`` the value of ``App.fullBaseUrl`` mentioned in - :ref:`general-configuration` will be prepended to generated URLs. -* ``_https`` Set to ``true`` to convert the generated URL to https or ``false`` - to force http. Prior to 4.5.0 use ``_ssl`` -* ``_name`` Name of route. If you have setup named routes, you can use this key - to specify it. - -Using ``Router::reverse()`` ---------------------------- - -``Router::reverse()`` allows you to use the :ref:`request-parameters` in cases -where the current URL with some modification is the basis for the destination -and the elements of the current URL are unpredictable. - -As an example, imagine a blog that allowed users to create **Articles** and -**Comments**, and to mark both as either *published* or *draft*. Both the index -page URLs might include the user id. The **Comments** URL might also include -an article id to identify what article the comment refers to. - -Here are urls for this scenario:: +También puedes utilizar cualquiera de los elementos de ruta especiales al generar URL: + +* ``_ext`` Se utiliza para enrutamiento de :ref:`file-extensions`. +* ``_base`` Establecer en ``false`` para eliminar la ruta base de la URL generada. + Si tu aplicación no está en el directorio raíz, esto se puede utilizar para generar + URL relativas a cake. +* ``_scheme`` Configurado para crear enlaces en diferentes esquemas como ``webcal`` o + ``ftp``. El valor predeterminado es el esquema actual. +* ``_host`` Establece el host que se utilizará en el enlace. El valor por defecto es el + del host actual. +* ``_port`` Establece el puerto si necesitas crear enlaces a puestos no estándar. +* ``_method`` Define el verbo HTTP para el que es la URL. +* ``_full`` Si es ``true`` el valor de ``App.fullBaseUrl`` mencionado en + :ref:`general-configuration` se antepondrá a las URL generadas. +* ``_https`` Establecer en ``true`` para convertir la URL generada a https o ``false`` + para forzar http. +* ``_name`` Nombre de la ruta. Si has configurado rutas con nombre, puedes utilizar esta + clave para especificarlas. + +Utilizando ``Router::reverse()`` +-------------------------------- + +``Router::reverse()`` te permite utilizar los :ref:`request-parameters` en casos +donde la URL actual con algunas modificaciones es la base para el destino y los +elementos de la URL actual son impredecibles. + +Como ejemplo, imagina un blog que permite a los usuarios crear **Articles** y +**Comments**, y marcar ambos como *published* o *draft*. Ambas URL de la página index +puedes incluir el id de usuario. La URL de **Comments** también puede incluir un +id de article para identificar a qué artículo se refiere el comentario. + +Aquí están las url para este escenario:: /articles/index/42 /comments/index/42/18 -When the author uses these pages, it would be convenient to include links -that allow the page to be displayed with all results, published only, -or draft only. +Cuando el autor utilice estas páginas, sería conveniente incluir enlaces que +permitan mostrar la página con todos los resultados, sólo publicados o sólo +borrador. -To keep the code DRY, it would be best to include the links through -an element:: +Para mantener el código DRY, sería mejor incluir los enlaces a través de un +elemento:: // element/filter_published.php $params = $this->getRequest()->getAttribute('params'); - /* prepare url for Draft */ + /* preparar la url para Borrador */ $params = Hash::insert($params, '?.published', 0); echo $this->Html->link(__('Draft'), Router::reverse($params)); - /* Prepare url for Published */ + /* Preparar la url para Publicados */ $params = Hash::insert($params, '?.published', 1); echo $this->Html->link(__('Published'), Router::reverse($params)); - /* Prepare url for All */ + /* Preparar la url para Todos */ $params = Hash::remove($params, '?.published'); echo $this->Html->link(__('All'), Router::reverse($params)); -The links generated by these method calls would include one or two pass -parameters depending on the structure of the current URL. And the code -would work for any future URL, for example, if you started using -pathPrefixes or if you added more pass parameters. +Los enlaces generados por estas llamadas incluirían uno o dos parámetros +de paso dependiendo de la estructura de la URL actual. Y el código +funcionaría para cualquier URL futura, por ejemplo, si comenzara a usar +prefijos de ruta o si agregara más parámetros del paso. -Routing Arrays vs Request Parameters -------------------------------------- +Matrices de Enrutamiento vs Parámetros de Solicitud +--------------------------------------------------- -The significant difference between the two arrays and their use in these -reverse routing methods is in the way they include pass parameters. +La diferencia significativa entre las dos matrices y su uso en estos métodos +de enrutamiento inverso está la forma en la que incluyen los parámetros +de paso. -Routing arrays include pass parameters as un-keyed values in the array:: +Las matrices de enrutamiento incluyen los parámetros de paso como valores +sin clave en la matriz:: $url = [ 'controller' => 'Articles', 'action' => 'View', - $id, //a pass parameter - 'page' => 3, //a query argument + $id, //un parámetro de paso + 'page' => 3, //un argumento de consulta ]; -Request parameters include pass parameters on the 'pass' key of the array:: +Los parámetros de consulta incluyen parámtros de paso en la clave 'pass' +de la matriz:: $url = [ 'controller' => 'Articles', 'action' => 'View', - 'pass' => [$id], //the pass parameters - '?' => ['page' => 3], //the query arguments + 'pass' => [$id], //los parámetros de paso + '?' => ['page' => 3], //los parámtros de consulta ]; -So it is possible, if you wish, to convert the request parameters into -a routing array or vice versa. +Por lo tanto, si los deseas, es posible convertir los parámetros de solicitud +en una matriz de enrutamiento o viceversa. .. _asset-routing: -Generating Asset URLs -===================== +Generando URL de Activos +======================== -The ``Asset`` class provides methods for generating URLs to your application's -css, javascript, images and other static asset files:: +La clase ``Asset`` proporciona métodos para generar URL para los archivos css, +javascript, imágenes y otros archivos de activos estáticos de tu aplicación:: use Cake\Routing\Asset; - // Generate a URL to APP/webroot/js/app.js + // Generar una URL para APP/webroot/js/app.js $js = Asset::scriptUrl('app.js'); - // Generate a URL to APP/webroot/css/app.css + // Generar una URL para APP/webroot/css/app.css $css = Asset::cssUrl('app.css'); - // Generate a URL to APP/webroot/image/logo.png + // Generar una URL para APP/webroot/image/logo.png $img = Asset::imageUrl('logo.png'); - // Generate a URL to APP/webroot/files/upload/photo.png + // Generar una URL para APP/webroot/files/upload/photo.png $file = Asset::url('files/upload/photo.png'); -The above methods also accept an array of options as their second parameter: +Los métodos anteriores también aceptan una matriz de opciones como segundo parámetro: -* ``fullBase`` Append the full URL with domain name. -* ``pathPrefix`` Path prefix for relative URLs. -* ``plugin``` You can provide ``false``` to prevent paths from being treated as - a plugin asset. -* ``timestamp`` Overrides the value of ``Asset.timestamp`` in Configure. Set to - ``false`` to skip timestamp generation. Set to ``true`` to apply timestamps - when debug is true. Set to ``'force'`` to always enable timestamping - regardless of debug value. +* ``fullBase`` Agrega la URL completa con el nombre de dominio. +* ``pathPrefix`` Prefijo de ruta para URL relativas. +* ``plugin`` Puedes añdirlo como ``false`` para evitar que las rutas se traten como + un recurso de un plugin. +* ``timestamp`` Sobrescribe el valor de ``Asset.timestamp`` en Configure. Establecer + a ``false`` para omitir la generación de la marca de tiempo. Establecer a ``true`` + para aplicar marcas de tiempo cuando el debug is true. Set to ``'force'`` para habilitar + siempre la marca de tiempo independientemente del valor de debug. :: - // Generates http://example.org/img/logo.png + // Genera http://example.org/img/logo.png $img = Asset::url('logo.png', ['fullBase' => true]); - // Generates /img/logo.png?1568563625 - // Where the timestamp is the last modified time of the file. + // Genera /img/logo.png?1568563625 + // Donde la marca de tiempo es la ultima hora de modificación del archivo $img = Asset::url('logo.png', ['timestamp' => true]); -To generate asset URLs for files in plugins use :term:`Sintaxis de plugin`:: +Para generar URL de activo para archivos en un plugin utiliza +:term:`Sintaxis de plugin`:: - // Generates `/debug_kit/img/cake.png` + // Genera `/debug_kit/img/cake.png` $img = Asset::imageUrl('DebugKit.cake.png'); .. _redirect-routing: -Redirect Routing -================ +Redirección de Enrutamiento +=========================== -Redirect routing allows you to issue HTTP status 30x redirects for -incoming routes, and point them at different URLs. This is useful -when you want to inform client applications that a resource has moved -and you don't want to expose two URLs for the same content. +La redirección de enrutamiento te permite emitir redirección de estado +HTTP 30x para rutas entrantes y apuntarlas a URL diferentes. Esto es útil +cuando deseas informar a las aplicaciones cliente que un recurso se ha +movido y no deseas exponer dos URL para el mismo contenido. -Redirection routes are different from normal routes as they perform an actual -header redirection if a match is found. The redirection can occur to -a destination within your application or an outside location:: +Las rutas de redireccionamiento son diferentes de las rutas normales en que +realizan una redirección de encabezado real si se encuentra una coincidencia. +La redirección puede ocurrir a un destino dentro de tu aplicación o a una +ubicación externa:: $routes->scope('/', function (RouteBuilder $routes) { $routes->redirect( '/home/*', ['controller' => 'Articles', 'action' => 'view'], ['persist' => true] - // Or ['persist'=>['id']] for default routing where the - // view action expects $id as an argument. + // O ['persist'=>['id']] para el enrutamiento predeterminado + // donde la acción view espera $id como argumento. ); }) -Redirects ``/home/*`` to ``/articles/view`` and passes the parameters to -``/articles/view``. Using an array as the redirect destination allows -you to use other routes to define where a URL string should be -redirected to. You can redirect to external locations using -string URLs as the destination:: +Redirige ``/home/*`` a ``/articles/view`` y pasa los parámetros a +``/articles/view``. El uso de una matriz como destino de +redireccionamiento te permite utilizar otras rutas para definir +hacia dónde se debe dirigir un cadena de URL. Puedes redirigir a +ubicaciones externas utilizando una cadena de URL como destino:: $routes->scope('/', function (RouteBuilder $routes) { $routes->redirect('/articles/*', 'http://google.com', ['status' => 302]); }); -This would redirect ``/articles/*`` to ``http://google.com`` with a -HTTP status of 302. +Esto redirigiría ``/articles/*`` a ``http://google.com`` con un estado +HTTP de 302. .. _entity-routing: -Entity Routing -============== +Enrutamiento de Entidades +========================= -Entity routing allows you to use an entity, an array or object implement -``ArrayAccess`` as the source of routing parameters. This allows you to refactor -routes more easily, and generate URLs with less code. For example, if you start -off with a route that looks like:: +El enrutamiento de entidades te permite utilizar una entidad, una matriz o un objeto +que implemente ``ArrayAccess`` como una fuente de parámetros de enrutamiento. Esto +te permite refactorizar rutas fácilmente y generar URL con menos código. Por ejemplo, +si comienzas con un ruta similar a:: $routes->get( '/view/{id}', @@ -1537,59 +1561,60 @@ off with a route that looks like:: 'articles:view' ); -You can generate URLs to this route using:: +Puedes generar URL para esta ruta utilizando:: - // $article is an entity in the local scope. + // $article es una entidad en el ámbito local. Router::url(['_name' => 'articles:view', 'id' => $article->id]); -Later on, you may want to expose the article slug in the URL for SEO purposes. -In order to do this you would need to update everywhere you generate a URL to -the ``articles:view`` route, which could take some time. If we use entity routes -we pass the entire article entity into URL generation allowing us to skip any -rework when URLs require more parameters:: +Más adelante, es posible que desees exponer el slug del artículo en la URL con +fines de SEO. Para hacer esto necesitarás actualizar todos los lugares donde +generes una URL a la ruta ``articles:view``, lo que podría llevar algún tiempo. +Si utilizamos rutas de entidad, pasamos toda la entidad del artículo a la +generación de URL, lo que nos permite omitir cualquier reelaboración cuando las +URL requiren más parámetros:: use Cake\Routing\Route\EntityRoute; - // Create entity routes for the rest of this scope. + // Crea más rutas de entidad para el resto de este ámbito. $routes->setRouteClass(EntityRoute::class); - // Create the route just like before. + // Crea la ruta como antes. $routes->get( '/view/{id}/{slug}', ['controller' => 'Articles', 'action' => 'view'], 'articles:view' ); -Now we can generate URLs using the ``_entity`` key:: +Ahora podemos generar URL utilizando la clave ``_entity``:: Router::url(['_name' => 'articles:view', '_entity' => $article]); -This will extract both the ``id`` property and the ``slug`` property out of the -provided entity. +Esto extraerá las propiedades ``id`` y ``slug`` de la entidad proporcionada. .. _custom-route-classes: -Custom Route Classes -==================== +Clases de Ruta Personalizadas +============================= -Custom route classes allow you to extend and change how individual routes parse -requests and handle reverse routing. Route classes have a few conventions: +Las clases de ruta personalizadas te permiten ampliar y cambiar la forma en que +las rutas individuales analizan las solicitudes y manejan el enrutamiento inverso. +Las clases de ruta tienen algunas convenciones: -* Route classes are expected to be found in the ``Routing\\Route`` namespace of - your application or plugin. -* Route classes should extend :php:class:`Cake\\Routing\\Route\\Route`. -* Route classes should implement one or both of ``match()`` and/or ``parse()``. +* Se espera que las clases de ruta se encuentren en el espacio de nombres +``Routing\\Route`` de tu aplicación o plugin. +* Las clases de ruta deben extender :php:class:`Cake\\Routing\\Route\\Route`. +* Las clases de ruta deben implementar uno o ambos ``match()`` y/o ``parse()``. -The ``parse()`` method is used to parse an incoming URL. It should generate an -array of request parameters that can be resolved into a controller & action. -Return ``null`` from this method to indicate a match failure. +El método ``parse()`` se utiliza para analizar una URL entrante. Debería generar +una matriz de parámetros de solicitud que pueda resolverse en un controlador +y acción. Este método devuelve ``null`` para indicar un error de coincidencia. -The ``match()`` method is used to match an array of URL parameters and create a -string URL. If the URL parameters do not match the route ``false`` should be -returned. +El método ``match()`` se utiliza para hacer coincidir una matriz de parámetros +de URL y crear una cadena de URL. Si los parámertos de la URL no coinciden, de +debe devolver la ruta ``false``. -You can use a custom route class when making a route by using the ``routeClass`` -option:: +Puedes utilizar una clase de ruta personalizada al realizar una ruta utilizando +la opción ``routeClass``:: $routes->connect( '/{slug}', @@ -1597,7 +1622,7 @@ option:: ['routeClass' => 'SlugRoute'] ); - // Or by setting the routeClass in your scope. + // O configurando routeClass en su ámbito. $routes->scope('/', function (RouteBuilder $routes) { $routes->setRouteClass('SlugRoute'); $routes->connect( @@ -1606,43 +1631,45 @@ option:: ); }); -This route would create an instance of ``SlugRoute`` and allow you -to implement custom parameter handling. You can use plugin route classes using -standard :term:`Sintaxis de plugin`. +Esta ruta crearía una instancia de ``SlugRoute`` y te permitiría implementar +un manejo de parámetros personalizado. Puedes utilizar clases de ruta de plugin +utilizando el estándar :term:`Sintaxis de plugin`. -Default Route Class -------------------- +Clase de Ruta Predeterminada +---------------------------- .. php:staticmethod:: setRouteClass($routeClass = null) -If you want to use an alternate route class for your routes besides the -default ``Route``, you can do so by calling ``RouterBuilder::setRouteClass()`` -before setting up any routes and avoid having to specify the ``routeClass`` -option for each route. For example using:: +Si desea utilizar una ruta de clase alternativa para tus rutas además de la +``Ruta`` predeterminada, puedes hacerlo llamando a ``RouterBuilder::setRouteClass()`` +antes de configurar cualquier ruta y evitar tener que especificar la opción +``routeClass`` para cada ruta. Por ejemplo utilizando:: use Cake\Routing\Route\DashedRoute; $routes->setRouteClass(DashedRoute::class); -will cause all routes connected after this to use the ``DashedRoute`` route class. -Calling the method without an argument will return current default route class. +hará que todas las rutas conectadas después de esto utilicen la clase de ruta +``DashedRoute``. Llamando al método sin un argumento devolverá la clase de ruta +predeterminada actual. -Fallbacks Method ----------------- +Método de Respaldo/Alternativas +------------------ .. php:method:: fallbacks($routeClass = null) -The fallbacks method is a simple shortcut for defining default routes. The -method uses the passed routing class for the defined rules or if no class is -provided the class returned by ``RouterBuilder::setRouteClass()`` is used. +El método de respaldo es un atajo simple para definir rutas predeterminadas. +El método utiliza la clase de enrutamiento pasada para las reglas definidas o, +si no se proporciona ninguna clase, se utiliza la clase devuelta por +``RouterBuilder::setRouteClass()``. -Calling fallbacks like so:: +Llamar a alternativas así:: use Cake\Routing\Route\DashedRoute; $routes->fallbacks(DashedRoute::class); -Is equivalent to the following explicit calls:: +Es equivalente a las siguientes llamadas explícitas:: use Cake\Routing\Route\DashedRoute; @@ -1651,33 +1678,35 @@ Is equivalent to the following explicit calls:: .. note:: - Using the default route class (``Route``) with fallbacks, or any route - with ``{plugin}`` and/or ``{controller}`` route elements will result in - inconsistent URL case. + El uso de la clase de ruta predeterminada (``Route``) con alternativas, + or cualquier ruta con elemento de ruta ``{plugin}`` o ``{controller}`` + dará como resultado una URL inconsistente. .. warning:: - Fallback route templates are very generic and allow URLs to be generated - and parsed for controllers & actions that do not exist. Fallback URLs can - also introduce ambiguity and duplication in your URLs. + Las plantillas de ruta alternativas son muy genéricas y permites generar y + analizar URL para controladore sy acciones que no existen. Las URL + alternativas también pueden introducir ambigüedad y duplicidad en tus URL. - As your application grows, it is recommended to move away from fallback URLs - and explicitly define the routes in your application. + A medida que tu aplicaicón crece, se recomienda alejarse de las URL alternativas + y definir explícitamente las rutas en tu aplicación. -Creating Persistent URL Parameters -================================== +Crear Parámetros de URL Persistentes +==================================== -You can hook into the URL generation process using URL filter functions. Filter -functions are called *before* the URLs are matched against the routes, this -allows you to prepare URLs before routing. +Puedes conectarte al proceso de generación de URL utilizando funciones de filtro +de URL. Las funciones de filtro se llaman *antes* de que las URL coincidan con las +rutas, esto te permite preparar las URL antes de enrutarlas. -Callback filter functions should expect the following parameters: +La devolución de llamada de las funciones de filtro deben contar con los siguientes +parámetos: -- ``$params`` The URL parameter array being processed. -- ``$request`` The current request (``Cake\Http\ServerRequest`` instance). +- ``$params`` La matriz de parámetros de URL que se está procensando. +- ``$request`` La petición actual (instancia de ``Cake\Http\ServerRequest``). -The URL filter function should *always* return the parameters even if unmodified. +La función de filtro de URL *siempre* debería devolver los parámetros incluso si +no están modificados. -URL filters allow you to implement features like persistent parameters:: +Los filtros de URL te permiten implementar funciones como parámetros persistentes:: Router::addUrlFilter(function (array $params, ServerRequest $request) { if ($request->getParam('lang') && !isset($params['lang'])) { @@ -1686,10 +1715,10 @@ URL filters allow you to implement features like persistent parameters:: return $params; }); -Filter functions are applied in the order they are connected. +Las funciones de filtro se aplican en el orden en que están conectadas. -Another use case is changing a certain route on runtime (plugin routes for -example):: +Otro caso de uso es cambiar una determinada ruta en tiempo de ejecución +(por ejemplo, rutas de plugin):: Router::addUrlFilter(function (array $params, ServerRequest $request) { if (empty($params['plugin']) || $params['plugin'] !== 'MyPlugin' || empty($params['controller'])) { @@ -1704,19 +1733,20 @@ example):: return $params; }); -This will alter the following route:: +Esto alterará la siguiente ruta:: Router::url(['plugin' => 'MyPlugin', 'controller' => 'Languages', 'action' => 'view', 'es']); -into this:: +en esto:: Router::url(['plugin' => 'MyPlugin', 'controller' => 'Locations', 'action' => 'index', 'language' => 'es']); .. warning:: - If you are using the caching features of :ref:`routing-middleware` you must - define the URL filters in your application ``bootstrap()`` as filters are - not part of the cached data. + Si estás utilizando las funcionees de almacenamiento de caché de + :ref:`routing-middleware` debes definir los filtros de URL en tu aplicación + ``bootstrap()`` ya que los filtros no son parte de los datos almacenados en + caché. .. meta:: :title lang=es: Enrutamiento - :keywords lang=en: controller actions,default routes,mod rewrite,code index,string url,php class,incoming requests,dispatcher,url url,meth,maps,match,parameters,array,config,cakephp,apache,router + :keywords lang=es: controller actions,default routes,mod rewrite,code index,string url,php class,incoming requests,dispatcher,url url,meth,maps,match,parameters,array,config,cakephp,apache,router From 1f46bd3c7ff42df9c5449fa7e0277cb8858dd517 Mon Sep 17 00:00:00 2001 From: Alejandro Ibarra Date: Thu, 23 Nov 2023 12:57:32 +0100 Subject: [PATCH 117/337] Fix routing.rst issues --- es/development/routing.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/es/development/routing.rst b/es/development/routing.rst index 8e50db6d36..0c87e63448 100644 --- a/es/development/routing.rst +++ b/es/development/routing.rst @@ -647,7 +647,7 @@ utilizando el argumento ``$options``:: }); Los prefijos con varias palabras se convierten de forma predeterminada utilizando la -inflexión dasherize, es decir, ``MyPrefix`` se asignará a ``my-prefix``en la URL. +inflexión dasherize, es decir, ``MyPrefix`` se asignará a ``my-prefix`` en la URL. Asegúrate de establecer una ruta para dichos prefijos si deseas utilizar un formato diferente como, por ejemplo, subrayado:: @@ -836,7 +836,7 @@ necesitarás incluir la clave ``_method`` al generar la URL:: ]); Coincidencia con Nombres de Dominio Específicos --------------------------------------------- +----------------------------------------------- Las rutas pueden utilizar la opción ``_host`` para coincidir sólo con dominios específicos. Puedes utilizar el comodín ``*.`` para coincidir con cualquier @@ -1600,8 +1600,7 @@ Las clases de ruta personalizadas te permiten ampliar y cambiar la forma en que las rutas individuales analizan las solicitudes y manejan el enrutamiento inverso. Las clases de ruta tienen algunas convenciones: -* Se espera que las clases de ruta se encuentren en el espacio de nombres -``Routing\\Route`` de tu aplicación o plugin. +* Se espera que las clases de ruta se encuentren en el espacio de nombres ``Routing\\Route`` de tu aplicación o plugin. * Las clases de ruta deben extender :php:class:`Cake\\Routing\\Route\\Route`. * Las clases de ruta deben implementar uno o ambos ``match()`` y/o ``parse()``. @@ -1654,7 +1653,7 @@ hará que todas las rutas conectadas después de esto utilicen la clase de ruta predeterminada actual. Método de Respaldo/Alternativas ------------------- +------------------------------- .. php:method:: fallbacks($routeClass = null) From b7cf0de3a74afd217053171393accfd3c7f35ba7 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Thu, 23 Nov 2023 21:51:26 +0100 Subject: [PATCH 118/337] fix testing docs (#7773) --- en/development/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index 8631555d03..f1af49c6f8 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -412,7 +412,7 @@ contains the fixture extension: - + The extension is included in your application and plugins generated by ``bake`` From d94743968195abbc8c47f73453bdfb13d4bd9d23 Mon Sep 17 00:00:00 2001 From: Alejandro Ibarra Date: Fri, 24 Nov 2023 09:41:01 +0100 Subject: [PATCH 119/337] Fix grammar / syntax errors --- es/appendices.rst | 2 +- es/appendices/5-0-migration-guide.rst | 26 +++++++------- es/appendices/5-0-upgrade-guide.rst | 10 +++--- es/appendices/cakephp-development-process.rst | 2 +- es/appendices/glossary.rst | 2 +- es/appendices/phpunit10.rst | 4 +-- es/console-commands.rst | 6 ++-- es/console-commands/completion.rst | 2 +- es/console-commands/cron-jobs.rst | 2 +- es/console-commands/i18n.rst | 10 ++---- es/console-commands/option-parsers.rst | 4 +-- es/console-commands/server.rst | 14 ++++---- es/contributing/backwards-compatibility.rst | 6 ++-- .../cakephp-coding-conventions.rst | 24 ++++++------- es/contributing/code.rst | 2 +- es/contributing/documentation.rst | 14 ++++---- es/controllers.rst | 2 +- es/controllers/middleware.rst | 2 +- es/controllers/request-response.rst | 4 +-- es/core-libraries/caching.rst | 4 +-- es/core-libraries/email.rst | 10 ++---- es/core-libraries/inflector.rst | 4 +-- es/core-libraries/logging.rst | 8 ++--- es/core-libraries/number.rst | 4 +-- es/development/configuration.rst | 4 +-- es/development/debugging.rst | 6 ++-- es/development/rest.rst | 34 +++++++++---------- es/development/routing.rst | 34 +++++++++---------- es/development/sessions.rst | 4 +-- es/index.rst | 4 +-- es/installation.rst | 34 +++++++++---------- es/intro.rst | 2 +- es/intro/cakephp-folder-structure.rst | 4 +-- es/intro/where-to-get-help.rst | 4 +-- es/orm.rst | 12 +++---- es/plugins.rst | 4 +-- es/security/csrf.rst | 4 +-- es/views.rst | 4 +-- es/views/helpers/flash.rst | 10 +++--- 39 files changed, 161 insertions(+), 171 deletions(-) diff --git a/es/appendices.rst b/es/appendices.rst index 6c3b11879c..5c2ef86c3c 100644 --- a/es/appendices.rst +++ b/es/appendices.rst @@ -1,7 +1,7 @@ Apéndices ######### -En los apéndices encontrarás información relacionada a las nuevas características +En los apéndices encontrarás información relacionada con las nuevas características introducidas en cada versión, así como también las guías de migración entre versiones. Guía de Migración a 5.x diff --git a/es/appendices/5-0-migration-guide.rst b/es/appendices/5-0-migration-guide.rst index 887195b9af..034972f6af 100644 --- a/es/appendices/5-0-migration-guide.rst +++ b/es/appendices/5-0-migration-guide.rst @@ -63,7 +63,7 @@ Consola - ``BaseCommand::__construct()`` ha sido eliminado. - Se ha eliminado ``ConsoleIntegrationTestTrait::useCommandRunner()`` porque ya no es necesario. -- ``Shell`` Ha sido eliminado y debe ser sustituido por `Command `__ +- ``Shell`` Ha sido eliminado y debe ser sustituido por `Command `__ - Ahora ``BaseCommand`` emite los eventos ``Command.beforeExecute`` and ``Command.afterExecute`` cuando el método ``execute()`` del comando es invocado por el framework. @@ -118,7 +118,7 @@ Base de datos - ``DateType::setLocaleFormat()`` ya no acepta array. - ``Query`` ahora solo acepta parámetros ``\Closure`` en lugar de ``callable``. Los callables se pueden convertir a closures usando la nueva sintaxis de array de primera clase de PHP 8.1. -- ``Query::execute()`` ya no ejecuta los resultados de la devoluciones de llamadas. Debe utilizar ``Query::all()`` en su lugar. +- ``Query::execute()`` ya no ejecuta el resultado de la ejeción de la consulta. Debe utilizar ``Query::all()`` en su lugar. - ``TableSchemaAwareInterface`` fue eliminado. - ``Driver::quote()`` fue eliminado. En su lugar, utiliza declaraciones preparadas. - ``Query::orderBy()`` fue añadido para reemplazar ``Query::order()``. @@ -168,7 +168,7 @@ I18n ---- - Se cambió el nombre de ``FrozenDate`` a `Date` y el de ``FrozenTime`` a `DateTime`. -- ``Time`` ahora extiende de ``Cake\Chronos\ChronosTime`` y por lo tanto es inmutable. +- ``Time`` ahora extiende de ``Cake\Chronos\ChronosTime`` y. por lo tanto, es inmutable. - ``Date::parseDateTime()`` ha sido eliminado. - ``Date::parseTime()`` ha sido eliminado. - ``Date::setToStringFormat()`` y ``Date::setJsonEncodeFormat()`` ya no aceptan un array. @@ -192,7 +192,7 @@ Mailer ORM --- -- ``EntityTrait::has()`` ahora devuelve ``true`` cuando existe un atributo y se estable +- ``EntityTrait::has()`` ahora devuelve ``true`` cuando existe un atributo y es estable en ``null``. En versiones anteriores de CakePHP esto devolvía ``false``. Consulte las notas de la version 4.5.0 para saber como adoptar este comportamiento en 4.x. - ``EntityTrait::extractOriginal()`` ahora devuelve solo los campos existentes, similar a ``extractOriginalChanged()``. @@ -204,7 +204,7 @@ ORM coincidiendo con el comportamiento original de 3.x. - ``Table::query()`` se ha eliminado en favor de funciones específicas de tipo de consulta. - ``Table::updateQuery()``, ``Table::selectQuery()``, ``Table::insertQuery()``, y - ``Table::deleteQuery()`` se añadieron y ahora devuelven los nuevos objetos de consulta de tipo especifico. + ``Table::deleteQuery()`` se añadieron y ahora devuelven los nuevos objetos de consulta de tipo específico. - Se añadieron ``SelectQuery``, ``InsertQuery``, ``UpdateQuery`` y ``DeleteQuery`` que representan solo un tipo de consulta y no permiten cambiar entre tipos de consulta, sin llamar a funciones no relacionadas con el tipo de consulta especifico. @@ -248,7 +248,7 @@ Vistas - Dentro ``View::initialize()``, preferentemente usar ``addHelper()`` en lugar de ``loadHelper()``. De todas formas, todas las configuraciones de helpers se cargarán después. - ``View\Widget\FileWidget`` ya no es compatible con la subida de ficheros en forma - arrays. Esto esta alineado con los cambios en ``ServerRequest`` y ``Validation``. + arrays. Esto está alineado con los cambios en ``ServerRequest`` y ``Validation``. - ``FormHelper`` ya no estable ``autocomplete=off`` en los campos de token CSRF. Esto fue una solución para un error de Safari que no es relevante. @@ -271,8 +271,8 @@ Base de datos ORM --- -- Llamar a ``Table::find()`` con opciones de array esta obsoleto. Utiliza `named arguments `__ - en su lugar. Por ejemplo, en lugar de ``find('all', ['conditions' => $array])`` usar +- Llamar a ``Table::find()`` con opciones de array está obsoleto. Utiliza `named arguments `__ + en su lugar. Por ejemplo, en lugar de ``find('all', ['conditions' => $array])`` usar ``find('all', conditions: $array)``. De manera similar, para las opciones de finders personalizados, en lugar de ``find('list', ['valueField' => 'name'])`` usar ``find('list', valueField: 'name')`` o varios argumentos como ``find(type: 'list', valueField: 'name', conditions: $array)``. @@ -311,7 +311,7 @@ Base de datos - ``EnumType`` fue añadido para permitir el mapeo entre enumeraciones respaldadas por PHP y una cadena o columna entera. - ``getMaxAliasLength()`` y ``getConnectionRetries()`` se añadieron a ``DriverInterface``. - Los drivers compatibles ahora agregan automáticamente el incremento automático solo a las claves primarias enteras denominadas "id" - en lugar de a todas las claves primarias enteras. Si se establece 'autoIncrement' en false, siempre se deshabilita en todos los drivers compatibles. + en lugar de a todas las claves primarias enteras. Si se establece 'autoIncrement' como false, siempre se deshabilita en todos los drivers compatibles. Http ---- @@ -363,7 +363,7 @@ Por ejemplo, un finder para obtener publicaciones por categoría o usuario:: return $query; } -ahora se pueden escribir como:: +Ahora se pueden escribir como:: public function findByCategoryOrUser(SelectQuery $query, ?int $categoryId = null, ?int $userId = null) { @@ -391,7 +391,7 @@ Un cambio similar se ha aplicado al método ``RepositoryInterface::get()``:: ]); } -ahora se pueden escribir como:: +Ahora se pueden escribir como:: public function view(int $id) { @@ -406,8 +406,8 @@ TestSuite Instalador de plugins --------------------- - El instalador de plugins se ha actualizado para manejar automáticamente la carga automática de clases para los plugins - de tu aplicación. Por lo tanto, puede eliminar el espacio de nombres para las asignaciones de rutas para - tus plugins de tu ``composer.json`` y simplemente ejecutar ``composer dumpautoload``. + de tu aplicación. Por lo tanto, puedes eliminar el espacio de nombres para las asignaciones de rutas de + tus plugins del ``composer.json`` y simplemente ejecutar ``composer dumpautoload``. .. meta:: :title lang=es: 5.0 Guía de migración diff --git a/es/appendices/5-0-upgrade-guide.rst b/es/appendices/5-0-upgrade-guide.rst index f6e444e81d..921bf05820 100644 --- a/es/appendices/5-0-upgrade-guide.rst +++ b/es/appendices/5-0-upgrade-guide.rst @@ -57,10 +57,10 @@ plugin:: Actualizar dependencias de CakePHP ================================== -Después de aplicar las refactorizaciones de rector necesitas actualizar CakePHP, sus plugins, PHPUnit -y tal vez otras dependencias en tu ``composer.json``. -Este proceso depende de gran medida de tu aplicación por lo que le recomendamos que compare tu -``composer.json`` con el que esta presente en `cakephp/app +Después de aplicar las refactorizaciones de Rector necesitas actualizar CakePHP, sus plugins, PHPUnit +y tal vez otras dependencias en el ``composer.json``. +Este proceso depende de gran medida de tu aplicación por lo que te recomendamos que compares el +``composer.json`` con el que está presente en `cakephp/app `__. After the version strings are adjusted in your ``composer.json`` execute @@ -69,7 +69,7 @@ After the version strings are adjusted in your ``composer.json`` execute Actualiza los archivos de la aplicación basándose en las últimas plantillas =========================================================================== -A continuación, asegurate de que el resto de tu aplicación este actualizado basándose en la ultima version de `cakephp/app +A continuación, asegúrate de que el resto de tu aplicación esté actualizado basándose en la última version de `cakephp/app `__. .. meta:: diff --git a/es/appendices/cakephp-development-process.rst b/es/appendices/cakephp-development-process.rst index 1045bbeb06..b3e4c24174 100644 --- a/es/appendices/cakephp-development-process.rst +++ b/es/appendices/cakephp-development-process.rst @@ -12,7 +12,7 @@ Los proyectos de CakePHP en general siguen `semver `__. És - Las versiones **A.B.C** son *lanzamientos de parches*. Deben ser compatibles con el lanzamiento de parche anterior. La excepción a esta regla es si se descubre un problema de seguridad y la única solución es romper una API existente. -Consulta el :doc:/contributing/backwards-compatibility para ver lo que consideramos como compatible hacia atrás y cambios que rompen la compatibilidad. +Consulta el :doc:/contributing/backwards-compatibility para ver lo que consideramos como compatible con versiones previas y cambios que rompen la compatibilidad. Lanzamientos Principales ========================= diff --git a/es/appendices/glossary.rst b/es/appendices/glossary.rst index 842404ae8b..644cab68c2 100644 --- a/es/appendices/glossary.rst +++ b/es/appendices/glossary.rst @@ -85,4 +85,4 @@ Glosario .. meta:: :title lang=es: Glosario - :keywords lang=en: html attributes,array class,array controller,glossary glossary,target blank,dot notation,routing configuration,forgery,replay,router,syntax,config,submissions + :keywords lang=en: html attributes,array class,array controller,glossary,target blank,dot notation,routing configuration,forgery,replay,router,syntax,config,submissions diff --git a/es/appendices/phpunit10.rst b/es/appendices/phpunit10.rst index 59761f3911..f9071f0ef6 100644 --- a/es/appendices/phpunit10.rst +++ b/es/appendices/phpunit10.rst @@ -15,7 +15,7 @@ Se recomienda dejar que PHPUnit actualice su archivo de configuración a través ¡Asegúrese de que ya está en PHPUnit 10 a través de ``vendor/bin/phpunit --version`` antes de ejecutar este comando! -Con este comando ejecutado, tu ``phpunit.xml`` ya tiene la mayoría de los cambios recomendados presentes. +Una vez hayas ejecutado este comando, tu ``phpunit.xml`` tendrá mayoría de los cambios recomendados. Nuevo sistema de eventos ------------------------ @@ -51,7 +51,7 @@ debe convertirse a:: se ha añadido el método estático ``self::withConsecutive()`` a través del método ``Cake\TestSuite\PHPUnitConsecutiveTrait`` a la clase base ``Cake\TestSuite\TestCase`` para que no tenga que agregar manualmente este trait a tus clases de TestCase. -los proveedores de datos tienen que ser estáticos +Los proveedores de datos tienen que ser estáticos ================================================= Si tus testcases aprovechan la función de proveedor de datos de PHPUnit entonces diff --git a/es/console-commands.rst b/es/console-commands.rst index dc0636fa6b..a7b47f1436 100644 --- a/es/console-commands.rst +++ b/es/console-commands.rst @@ -18,7 +18,7 @@ La Console CakePHP utiliza un sistema de tipo `dispatcher` para cargar comandos, argumentos e invocar el comando correcto. Aunque los ejemplos a continuación usan bash, el console de CakePHP es compatible con cualquier shell de Unix (\*nix) y Windows. -Una aplicación CakePHP tiene un directorio **src/Command** que contiene sus comandos. Tambien incluye +Una aplicación CakePHP tiene un directorio **src/Command** que contiene sus comandos. También incluye un ejecutable en el directorio **bin** .. code-block:: console @@ -30,7 +30,7 @@ un ejecutable en el directorio **bin** Para Windows, el comando es ``bin\cake`` (note el `backslash`) -Ejecutar la console sin argumentos listará todos los comandos disponibles. Tu +Ejecutar la console sin argumentos listará todos los comandos disponibles. Tú puedes, de esta manera, ejecutar cualquiera de los comandos listados usando su nombre: .. code-block:: console @@ -92,7 +92,7 @@ Revisa la sección :ref:`plugin-commands` sobre como agregar comandos en los `pl Renombrando Comandos ==================== -Hay casos en los cuáles querrás renombrar comandos para crear comandos anidados o subcomandos. Mientras que +Hay casos en los cuales querrás renombrar comandos para crear comandos anidados o subcomandos. Mientras que el descubrimiento automático de comandos no hará esto, tu pueds registrar tus comandos para darles el nombre que desees. diff --git a/es/console-commands/completion.rst b/es/console-commands/completion.rst index d140e28ca7..351841f754 100644 --- a/es/console-commands/completion.rst +++ b/es/console-commands/completion.rst @@ -43,7 +43,7 @@ Regresará:: opciones -------- -Como tercera y última opción, genera opciones para el (sub)comando dado, tal como se establece en getOptionParser. +Como tercera y última opción, genera opciones para el (sub)comando dado, tal como se establece en ``getOptionParser``. (Incluidas las opciones predeterminadas heredadas de Shell). Por ejemplo:: diff --git a/es/console-commands/cron-jobs.rst b/es/console-commands/cron-jobs.rst index 858af21361..e521ca01bc 100644 --- a/es/console-commands/cron-jobs.rst +++ b/es/console-commands/cron-jobs.rst @@ -24,7 +24,7 @@ Puedes ver más información aquí: https://es.wikipedia.org/wiki/Cron_(Unix) Trabajos cron en hosting compartido ----------------------------------- -En algunos hosting compartidos ``cd /full/path/to/root && bin/cake mycommand myparam`` +En algunos servidores compartidos ``cd /full/path/to/root && bin/cake mycommand myparam`` Puede que no funcione. En su lugar puedes usar ``php /full/path/to/root/bin/cake.php mycomando myparam``. diff --git a/es/console-commands/i18n.rst b/es/console-commands/i18n.rst index abe4752565..1710c4a546 100644 --- a/es/console-commands/i18n.rst +++ b/es/console-commands/i18n.rst @@ -80,13 +80,9 @@ un archivo POT y lo sobrescribirá de forma predeterminada: Extracción de mensajes de las bibliotecas principales de CakePHP ---------------------------------------------------------------- -By default, the extract shell script will ask you if you like to extract -the messages used in the CakePHP core libraries. Set ``--extract-core`` to yes -or no to set the default behavior: - -orma predeterminada, el script de extracción le preguntará si desea extraer -los mensajes utilizados en las bibliotecas principales de CakePHP. -Configure ``--extract-core`` en sí o no para establecer el comportamiento +De forma predeterminada, el script de extracción le preguntará si desea extraer +los mensajes utilizados en el código de CakePHP. +Configura ``--extract-core`` en ``yes`` o ``no`` para establecer el comportamiento predeterminado: .. code-block:: console diff --git a/es/console-commands/option-parsers.rst b/es/console-commands/option-parsers.rst index 9c9ac46111..9c2b96d30b 100644 --- a/es/console-commands/option-parsers.rst +++ b/es/console-commands/option-parsers.rst @@ -84,7 +84,7 @@ Validación de Argumentos ------------------------ Al crear argumentos posicionales, puede utilizar el indicador ``required`` para -indicar que un argumento debe estar presente cuando se llama a un shell.Además, +indicar que un argumento debe estar presente cuando se llama a un shell. Además, puedes usar ``choices`` para forzar que un argumento provenga de una lista de opciones válidas:: @@ -363,7 +363,7 @@ Al pasar una matriz o una cadena, puede establecer el valor de la descripción:: // Leer el valor actual $parser->getDescription(); -Establecer el epilogo +Establecer el epílogo --------------------- .. php:method:: setEpilog($text) diff --git a/es/console-commands/server.rst b/es/console-commands/server.rst index 36ad9f91f2..ce9b051f33 100644 --- a/es/console-commands/server.rst +++ b/es/console-commands/server.rst @@ -1,29 +1,29 @@ Herramienta de servidor ####################### -El ``ServerCommand`` le permite crear un servidor web simple utilizando el +El ``ServerCommand`` te permite crear un servidor web simple utilizando el servidor web PHP integrado. Si bien este servidor *no* está diseñado para uso en producción, puede ser útil en el desarrollo cuando desea probar rápidamente -una idea y no quiere perder tiempo configurando Apache o Nginx. Puede iniciar -el comando del servidor con: +una idea y no quiere perder tiempo configurando Apache o Nginx. Puedes iniciar +el servidor con el comando: .. code-block:: console bin/cake server -Debería ver que el servidor arranca y se conecta al puerto 8765. Puede visitar +Deberías ver que el servidor arranca y se conecta al puerto 8765. Puedes visitar el servidor CLI visitando ``http://localhost:8765`` en su navegador web. -Puede cerrar el servidor presionando ``CTRL-C`` en su terminal. +Para cerrar el servidor presiona ``CTRL-C`` en tu terminal. .. note:: - Pruebe ``bin/cake server -H 0.0.0.0`` si no se puede acceder al servidor + Prueba ``bin/cake server -H 0.0.0.0`` si no se puede acceder al servidor desde otros hosts. Cambiar el puerto y la raíz del documento ========================================= -Puede personalizar el puerto y la raíz del documento usando las opciones: +Puedes personalizar el puerto y el directorio raíz usando las opciones: .. code-block:: console diff --git a/es/contributing/backwards-compatibility.rst b/es/contributing/backwards-compatibility.rst index 2de0448513..f63cfe12c9 100644 --- a/es/contributing/backwards-compatibility.rst +++ b/es/contributing/backwards-compatibility.rst @@ -8,7 +8,7 @@ versiones ``major``. Puedes familiarizarte con el `versionado semántico de CakePHP. Pero resumiendo, el versionado semántico significa que sólo las liberaciones de versiones ``major`` (tales como 2.0, 3.0, 4.0) pueden romper la compatibilidad hacia atrás. Las liberaciones ``minor`` (tales como 2.1, 3.1, 3.2) -pueden introducir nuevas funcionalidades pero no pueden romper la compatibilidad. +pueden introducir nuevas funcionalidades, pero no pueden romper la compatibilidad. Los lanzamientos de correcciones de errores (tales como 3.0.1) no añaden nuevas funcionaliades, sólo correcciones de errores o mejoras de rendimiento. @@ -42,7 +42,7 @@ Interfaces Con excepción de las liberaciones ``major``, las interfaces que provee CakePHP **no** tendrán ningún cambio en los métodos existentes. Podrán añadirse nuevos -métodos pero no habrá cambios en los ya existentes. +métodos, pero no habrá cambios en los ya existentes. Clases ------ @@ -62,7 +62,7 @@ defecto, pero si sobreescribes métodos con una firma diferente puedes encontrar ``fatal errors``. Los métodos con nuevos argumentos estarán documentados en las guías de migración.. -La siguiente tabla esboza varios casos de uso y que compatibilidad puedes esperar +La siguiente tabla esboza varios casos de uso y qué compatibilidad puedes esperar de CakePHP: +---------------------------------------+--------------------------+ diff --git a/es/contributing/cakephp-coding-conventions.rst b/es/contributing/cakephp-coding-conventions.rst index be350ac561..d6118b2b17 100644 --- a/es/contributing/cakephp-coding-conventions.rst +++ b/es/contributing/cakephp-coding-conventions.rst @@ -23,7 +23,7 @@ Configuración del *IDE* Asegúrate de que tu *IDE* haga *trim* por la derecha para que no haya espacios al final de las líneas. -La mayoría de los *IDEs* modernos soportan archivos ``.editorconfig``. El +La mayoría de los *IDE* modernos soportan archivos ``.editorconfig``. El esqueleto de aplicación de CakePHP viene con él por defecto y contiene las mejores prácticas de forma predeterminada. @@ -51,7 +51,7 @@ O también:: } } -En los casos donde utilices llamadas de funciones que ocupen más de un línea +En los casos donde utilices llamadas de funciones que ocupen más de una línea usa las siguientes guías: * El paréntesis de abertura de la llamada de la función deberá ser lo @@ -138,9 +138,9 @@ Operador ternario ----------------- Los operadores ternarios están permitidos cuando toda su declaración cabe en una -sola línea. Operadores más largos deberán ir dentro dentro de una declaración +sola línea. Operadores más largos deberán ir dentro de una declaración ``if else``. Los operadores ternarios no deberían ir nunca anidados y opcionalmente -pueden utilizarse paréntesis entorno a las condiciones para dar claridad:: +pueden utilizarse paréntesis alrededor de las condiciones para dar claridad:: // Correcto, sencillo y legible $variable = isset($options['variable']) ? $options['variable'] : true; @@ -172,7 +172,7 @@ Intenta ser siempre lo más estricto posible. Si una comparación no es estricta de forma deliberada, puede ser inteligente añadir un comentario para evitar confundirla con un error. -Para comprobar si una variables es ``null`` se recomienda utilizar comprobación +Para comprobar si una variable es ``null`` se recomienda utilizar la comprobación estricta:: if ($value === null) { @@ -378,7 +378,7 @@ object resource Tipo resource (devuelto por ejemplo por mysql\_connect()). Recuerda que cuando especificas el tipo como mixed deberás indicar - si es desconocido o cuales son los tipos posibles. + si es desconocido o cuáles son los tipos posibles. callable Función Callable. @@ -388,7 +388,7 @@ Puedes combinar tipos usando el caracter ``|``:: Para más de dos tipos normalmente lo mejor es utilizar ``mixed``. -Cuando se devuelva el propio objeto, p.ej. para encadenar, deberás utilizar +Cuando se devuelva el propio objeto, por ejemplo para encadenar, deberás utilizar ``$this`` en su lugar:: /** @@ -467,7 +467,7 @@ Los nombres de las clases deberán escribirse en ``CamelCase``, por ejemplo:: Variables --------- -Los nombres de variables deberán ser todo lo descriptibles que puedan pero +Los nombres de variables deberán ser todo lo descriptibles que puedan, pero también lo más corto posible. Se escribirán en minúscula salvo que estén compuestos por múltiples palabras, en cuyo caso irán en ``camelBack``. Los nombres de las variables que referencien objetos deberán ir asociados de algún modo a la clase @@ -516,15 +516,15 @@ Tipo (bool) Cast a boolean. (int) - Cast a integer. + Cast an integer. (float) Cast a float. (string) Cast a string. (array) - Cast a array. + Cast an array. (object) - Cast a object. + Cast an object. Por favor utiliza ``(int)$var`` en lugar de ``intval($var)`` y ``(float)$var`` en lugar de ``floatval($var)`` cuando aplique. @@ -611,4 +611,4 @@ por defecto puedes asegurarte de que las claves necesarias están definidas:: .. meta:: :title lang=es: Estándares de codificación - :keywords lang=es: llaves, nivel de tabulación, errores logicos, estructuras de control,expr,estándares de codificación,paréntesis,foreach, legibilidad,moose,nuevas funcionalidades,repositorio,desarrolladores + :keywords lang=es: llaves, nivel de tabulación, errores logicos, estructuras de control, expr, estándares de codificación, paréntesis, foreach, legibilidad,moose,nuevas funcionalidades,repositorio,desarrolladores diff --git a/es/contributing/code.rst b/es/contributing/code.rst index a001325ee1..fd11eb2bc8 100644 --- a/es/contributing/code.rst +++ b/es/contributing/code.rst @@ -32,7 +32,7 @@ Clona el código fuente de CakePHP desde GitHub: * Si no tienes una cuenta de `GitHub `_ créate una. * Haz un *fork* del `repositorio CakePHP `_ - haciendo click en el botón **Fork**. + haciendo clic en el botón **Fork**. Después de haber hecho el fork, clónalo en tu equipo local:: diff --git a/es/contributing/documentation.rst b/es/contributing/documentation.rst index 309b116277..2773f7e0d0 100644 --- a/es/contributing/documentation.rst +++ b/es/contributing/documentation.rst @@ -22,7 +22,7 @@ Nueva traducción ---------------- Nos gustaría poder disponer de traducciones que estén todo lo completas posible. -Sin embargo hay ocasiones donde un archivo de traducción no está al día, por lo +Sin embargo, hay ocasiones donde un archivo de traducción no está al día, por lo que debes considerar siempre la versión en inglés como la versión acreditada. Si tu idioma no está entre los disponibles, por favor, contacta con nosotros a @@ -30,7 +30,7 @@ través de Github y estudiaremos la posibilidad de crear la estructura de archiv para ello. Las siguientes secciones son las primeras que deberías considerar -traducir ya que estos archivos no cambian a menudo: +traducir, ya que estos archivos no cambian a menudo: - index.rst - intro.rst @@ -48,7 +48,7 @@ dichos cambios en los demás idiomas. Por ejemplo, si se crea un nuevo archivo en inglés en **en/file.rst** tendremos que: -- Añadir el archivo en todos los idiomas: **fr/file.rst**, **zh/file.rst**,... +- Añadir el archivo en todos los idiomas: **fr/file.rst**, **zh/file.rst**, ... - Borrar el contenido pero manteniendo el ``title``, ``meta`` información y ``toc-tree`` que pueda haber. Se añadirá la siguiente nota mientras nadie traduzca el archivo:: @@ -87,7 +87,7 @@ Consejos para traductores - Usa la `Forma informal `_. - Traduce el título y el contenido a la vez. - Compara con la versión en inglés antes de subir una corrección (si corriges - algo pero no indicas una referencia tu subida no será aceptada). + algo, pero no indicas una referencia tu subida no será aceptada). - Si necesitas escribir un término en inglés envuélvelo en etiquetas ````. E.g. "asdf asdf *Controller* asdf" o "asdf asdf Kontroller (*Controller*) asfd" como proceda. @@ -114,7 +114,7 @@ Tamaño de línea --------------- Las líneas de texto deberían medir como máximo 40 caracteres. Las únicas -excepciones son URLs largas y fragmentos de código. +excepciones son URL largas y fragmentos de código. Cabeceras y secciones --------------------- @@ -154,7 +154,7 @@ Marcado en línea * Dos acentos graves (*``*): ``texto`` para ejemplos de código. Lo usaramos para nombres de opciones de métodos, columnas de tablas, objetos (excluyendo la palabra "objeto") y para nombres de métodos y funciones - (incluídos los paréntesis ) + (incluídos los paréntesis) * ````cascadeCallbacks````, ````true````, ````id````, ````PagesController````, ````config()````, etc. @@ -206,7 +206,7 @@ Pueden crearse listas de definiciones haciendo lo siguiente:: CakePHP Un framework MVC para PHP -Los términos no pueden ocupar más de una línea pero las definiciones pueden +Los términos no pueden ocupar más de una línea, pero las definiciones pueden ocupar más líneas mientras se aniden consistentemente. Enlaces diff --git a/es/controllers.rst b/es/controllers.rst index 3e0d8b6e80..ae342a66b8 100644 --- a/es/controllers.rst +++ b/es/controllers.rst @@ -14,7 +14,7 @@ a los modelos correctos y se muestre la respuesta o vista correcta. Los controladores se pueden considerar como una capa intermedia entre el Modelo y la Vista. Quieres mantener tus controladores delgados, y tus modelos gruesos. -Esto te ayudará a reutilizar tu código y lo hará mas fácil de probar. +Esto te ayudará a reutilizar tu código y lo hará más fácil de probar. Comúnmente, un controlador se usa para administrar la lógica en torno a un solo modelo. Por diff --git a/es/controllers/middleware.rst b/es/controllers/middleware.rst index b1806c5e94..cefa1954e0 100644 --- a/es/controllers/middleware.rst +++ b/es/controllers/middleware.rst @@ -85,7 +85,7 @@ Puedes usar el objeto ``MiddlewareQueue`` para agregar el middleware:: } } -Adicionalmente, aparte de agregarlo al final de la ``MiddlewareQueue`` tu puedes realizar distintas +Adicionalmente, aparte de agregarlo al final de la ``MiddlewareQueue``, puedes realizar distintas operaciones:: $layer = new \App\Middleware\CustomMiddleware; diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index 7e653e53a3..ff035b378d 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -200,7 +200,7 @@ todos los archivos cargados posiblemente existentes:: Los archivos cargados que se agregaron a la solicitud a través de este método *no* estarán disponibles en los datos del cuerpo de la solicitud, es decir, no puede recuperarlos a través de - :php:meth:`Cake\\Http\\ServerRequest::getData()` ! Si los necesita en los datos de la solicitud (también), entonces + :php:meth:`Cake\\Http\\ServerRequest::getData()` ! Si los necesita en los datos de la solicitud (también), entonces debe configurarlos mediante :php:meth:`Cake\\Http\\ServerRequest::withData()` o :php:meth:`Cake\\Http\ \ServerRequest::withParsedBody()`. @@ -234,7 +234,7 @@ variables de entorno sin tener que modificar los globales ``$_SERVER`` y ``$_ENV // Establecer un valor, generalmente útil en las pruebas. $this->request->withEnv('REQUEST_METHOD', 'POST'); -Para acceder a todas las variables de entorno en una solicitud utilice ``getServerParams()``:: +Para acceder a todas las variables de entorno en una solicitud, utilice ``getServerParams()``:: $env = $this->request->getServerParams(); diff --git a/es/core-libraries/caching.rst b/es/core-libraries/caching.rst index 45eec8b243..ffa7ea2568 100644 --- a/es/core-libraries/caching.rst +++ b/es/core-libraries/caching.rst @@ -249,9 +249,7 @@ ahorras múltiples conexiones de red cuando usas Memcached:: ]); // $resultado contendrá - ['articulo-primer-post' => true, 'articulo-primer-post-comentarios' => - - true] + ['articulo-primer-post' => true, 'articulo-primer-post-comentarios' => true] Escrituras Atómicas ------------------- diff --git a/es/core-libraries/email.rst b/es/core-libraries/email.rst index 1ab482d10d..338b640ac3 100644 --- a/es/core-libraries/email.rst +++ b/es/core-libraries/email.rst @@ -366,10 +366,6 @@ Ahora puedes registrar el mailer como un oyente de eventos y el método `onRegis // Adjuntar al gestor de eventos de Usuarios $this->Users->getEventManager()->on($this->getMailer('User')); -:: note :: - - Para obtener información sobre cómo registrar objetos oyentes de eventos, consulta la documentación de :ref:`registro-de-oyentes-de-eventos`. - .. _email-transport: Configuración de Transportes @@ -434,15 +430,15 @@ Para configurar tu mailer para usar un transporte específico, puedes usar el m // Usa un objeto construido. $mailer->setTransport(new \Cake\Mailer\Transport\DebugTransport()); -:: warning :: +.. warning :: Deberás tener habilitado el acceso para aplicaciones menos seguras en tu cuenta de Google para que funcione: `Permitir que aplicaciones menos seguras accedan a tu cuenta `__. -:: note :: +.. note ::   `Configuración SMTP de Gmail `__. -:: note :: +.. note :: Para usar SSL + SMTP, necesitarás tener SSL configurado en tu instalación de PHP. También se pueden proporcionar opciones de configuración como una cadena :term:`DSN`. Esto es útil cuando trabajas con variables de entorno o proveedores de :term:`PaaS`:: diff --git a/es/core-libraries/inflector.rst b/es/core-libraries/inflector.rst index b5616621da..1bb5d1af2b 100644 --- a/es/core-libraries/inflector.rst +++ b/es/core-libraries/inflector.rst @@ -122,7 +122,7 @@ Generando formas de tabla y nombre de clase .. php:staticmethod:: dasherize($dashed) .. php:staticmethod:: tableize($camelCase) -Cuando se genera código, o usando las convenciones de CakePHP tu puedes necesitar generar inflecciones para los nombres de tabla o de clase:: +Cuando se genera código, o usando las convenciones de CakePHP, puedes necesitar generar inflecciones para los nombres de tabla o de clase:: // UserProfileSetting Inflector::classify('user_profile_settings'); @@ -174,7 +174,7 @@ en tu archivo **config/bootstrap.php**:: Las reglas suministradas se fusionarán en los conjuntos de inflexión respectivos definidos en ``Cake/Utility/Inflector``, y las reglas añadidas tendrán prioridad sobre las reglas principales del núcleo. Puedes usar ``Inflector::reset()`` -para eliminar las reglas y restaurar el estado original del Inflector." +para eliminar las reglas y restaurar el estado original del Inflector. .. meta:: :title lang=es: Objeto Inflector diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index bd497c38f7..1729ff0119 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -3,7 +3,7 @@ Logging Si bien la configuración de la clase Configure de CakePHP puede ayudarte a ver lo que está sucediendo en el sistema, hay momentos en los que necesitarás registrar -datos en el disco para averiguar lo que está ocurriendo. Con tecnologías como SOAP, AJAX y APIs REST, +datos en el disco para averiguar lo que está ocurriendo. Con tecnologías como SOAP, AJAX y API REST, la depuración puede ser bastante difícil. Logging también puede ser una forma de averiguar lo que ha estado ocurriendo @@ -69,7 +69,7 @@ Una vez que se crea una configuración, no se puede cambiar. En su lugar, debes la configuración y volver a crearla utilizando :php:meth:`Cake\\Log\\Log::drop()` y :php:meth:`Cake\\Log\\Log::setConfig()`. -ambién es posible crear loggers proporcionando un cierre (closure). Esto es útil +También es posible crear loggers proporcionando un cierre (closure). Esto es útil cuando necesitas un control completo sobre cómo se construye el objeto del logger. El cierre debe devolver la instancia del logger. Por ejemplo:: @@ -174,7 +174,7 @@ Utilizar un nivel que no esté en la lista de niveles anteriores resultará en u En muchas ocasiones, querrás configurar diferentes comportamientos de registro para diferentes subsistemas o partes de tu aplicación. Tomemos como ejemplo una tienda en línea. -Probablemente quieras manejar el registro de pedidos y pagos de manera diferente a como lo haces +Probablemente, quieras manejar el registro de pedidos y pagos de manera diferente a como lo haces con otros registros menos críticos. CakePHP expone este concepto como ámbitos de registro. Cuando se escriben mensajes de registro, @@ -273,7 +273,7 @@ utilizar un almacenamiento completamente diferente para tus registros. Usar syslog es prácticamente como usar el motor de registro de archivos predeterminado, simplemente necesitas especificar ``Syslog`` como el motor a utilizar para el registro de logs. El siguiente fragmento de configuración reemplazará el ``logger`` predeterminado con syslog, esto se debe hacer -en el archivo **config/bootstrap.php**":: +en el archivo **config/bootstrap.php**:: Log::setConfig('default', [ 'engine' => 'Syslog' diff --git a/es/core-libraries/number.rst b/es/core-libraries/number.rst index bffb7261d3..5edea0903e 100644 --- a/es/core-libraries/number.rst +++ b/es/core-libraries/number.rst @@ -148,8 +148,8 @@ Formato de Porcentajes Al igual que :php:meth:`Cake\\I18n\\Number::precision()`, este método formatea un número según la precisión proporcionada (donde los números se redondean para cumplir con la -precisión dada). Este método también expresa el número como un porcentaje -y agrega la salida con un signo de porcentaje. :: +precisión dada). Adicionalmente, también expresa el número como un porcentaje +y agrega un signo de porcentaje a la salida. :: // Llamado como NumberHelper. Salida: 45.69% echo $this->Number->toPercentage(45.691873645); diff --git a/es/development/configuration.rst b/es/development/configuration.rst index 195135d284..a607285155 100644 --- a/es/development/configuration.rst +++ b/es/development/configuration.rst @@ -136,14 +136,14 @@ A continuación se muestra una descripción de las variables y cómo afectan a t - (string) 'force' - Siempre añade la marca de tiempo. - **Asset.cacheTime** - Establece el tiempo de caché del archivo de activo. Esto determina el encabezado ``Cache-Control`` de HTTP's ``max-age`` y el tiempo de ``Expire`` del encabezado de HTTP para los activos. Esto puede tomar cualquier valor que la función `strtotime `_ tu versión de PHP pueda tomar. El valor predeterminado es ``+1 día``. + Establece el tiempo de caché del archivo de activo. Esto determina el encabezado ``Cache-Control``, ``max-age`` y el tiempo de ``Expire`` del encabezado de HTTP para los activos. Esto puede tomar cualquier valor que la función `strtotime `_ tu versión de PHP pueda tomar. El valor predeterminado es ``+1 día``. Usar un CDN ----------- Para utilizar un CDN para cargar tus activos estáticos, cambia las variables ``App.imageBaseUrl``, ``App.cssBaseUrl``, ``App.jsBaseUrl`` para que apunten a la URI del CDN, por ejemplo: ``https://micdn.ejemplo.com/`` (nota la barra diagonal al final ``/``). -Todas las imágenes, scripts y estilos cargados a través de HtmlHelper agregarán la ruta absoluta del CDN, coincidiendo con la misma ruta relativa utilizado en la aplicación. Ten en cuenta que hay un caso de uso específico cuando se utilizan activos basados en plugins: los plugins no utilizarán el prefijo del plugin cuando se utiliza una URI absoluta ``...BaseUrl``, por ejemplo, por defecto: +Todas las imágenes, scripts y estilos cargados a través de HtmlHelper agregarán la ruta absoluta del CDN, coincidiendo con la misma ruta relativa utilizada en la aplicación. Ten en cuenta que hay un caso de uso específico cuando se utilizan activos basados en plugins: los plugins no utilizarán el prefijo del plugin cuando se utiliza una URI absoluta ``...BaseUrl``, por ejemplo, por defecto: * ``$this->Helper->assetUrl('TestPlugin.logo.png')`` resuelve a ``test_plugin/logo.png`` diff --git a/es/development/debugging.rst b/es/development/debugging.rst index fabadb0a3b..8314c84dc2 100644 --- a/es/development/debugging.rst +++ b/es/development/debugging.rst @@ -3,7 +3,7 @@ Depuración La depuración es una parte inevitable y necesaria de cualquier ciclo de desarrollo. Aunque CakePHP no ofrece ninguna herramienta que se conecte directamente -con algun IDE o editor, CakePHP proporciona varias herramientas para +con algún IDE o editor, CakePHP proporciona varias herramientas para asistirte en la depuración y exponer lo que se está ejecutando bajo el capó de tu aplicación. @@ -113,7 +113,7 @@ Generando seguimientos de pila .. php:staticmethod:: trace($options) Devuelve el seguimiento de pila actual. Cada línea de la pila incluye -cual método llama, incluyendo el archivo y la línea en la que se originó +cuál método llama, incluyendo el archivo y la línea en la que se originó la llamada:: // En PostsController::index() @@ -185,7 +185,7 @@ Kit De Depuración ================= DebugKit es un complemento que proporciona una serie de buenas herramientas de depuración. -Principalmente provee una barra de herramientas en el HTML +Principalmente, provee una barra de herramientas en el HTML renderizado, que porporciona una gran cantidad de información sobre tu aplicación y la solicitud actual. Ver el capítulo :doc:`/debug-kit` para saber cómo instalar y usar DebugKit. diff --git a/es/development/rest.rst b/es/development/rest.rst index 48ad6e2cbd..59f11a72b4 100644 --- a/es/development/rest.rst +++ b/es/development/rest.rst @@ -1,9 +1,9 @@ REST #### -Muchos de los nuevos programadores de aplicaciones se estan dando cuenta -de la necesidad de abrir el núcleo de la funcionalidad a un mayor publico. -Proporcionando acceso fácil y sin restricciones al núcleo de su API puede +Muchos de los nuevos programadores de aplicaciones se están dando cuenta +de la necesidad de abrir el núcleo de la funcionalidad a un mayor público. +Proporcionando acceso fácil y sin restricciones al núcleo de su API puede ayudar a que su plataforma sea aceptada, y permite realizar mashups y fácil integración con otros sistemas. @@ -16,10 +16,10 @@ Exponer una API utilizando REST en CakePHP es simple. La Configuración Simple ======================= -La forma más rapida para empezar a utilizar REST es agregar unas lineas para -configurar la `resource routes ` en su archivo **config/routes.php** . +La forma más rapida para empezar a utilizar REST es agregar unas líneas para +configurar la `resource routes ` en su archivo **config/routes.php**. -Una vez que la ruta se ha configurado para mapear las solicitudes REST a +Una vez que la ruta se ha configurado para mapear las solicitudes REST a cierto controlador de acciones, se puede proceder a crear la lógica de nuestro controlador de acciones. Un controlador básico podría visualizarse de la siguiente forma:: @@ -92,21 +92,21 @@ controlador de acciones. Un controlador básico podría visualizarse de la sigui } } -Los controladores RESTful a menudo usan extensiones parseadas para mostrar diferentes vistas +Los controladores RESTful a menudo usan extensiones parseadas para mostrar diferentes vistas, basado en diferentes tipos de solicitudes. Como estamos tratando con solicitudes REST, estaremos haciendo vistas XML. Puedes realizar vistas en JSON usando el CakePHP :doc:`/views/json-and-xml-views`. Mediante el uso de :php:class:`XmlView` se puede -definir una opción de ``serialize``. Esta opción se usa para definir qué variables de vistas +definir una opción de ``serialize``. Esta opción se usa para definir qué variables de vistas `` XmlView`` deben serializarse en XML. -Si se quiere modificar los datos antes de convertirlos en XML, no se debería definir la +Si se quiere modificar los datos antes de convertirlos en XML, no se debería definir la opción ``serialize``, y en lugar de eso, se debería usar archivos plantilla. Colocaremos las vistas REST de nuestro RecipesController dentro de **templates/Recipes/xml**. también podemos utilizar el :php:class:`Xml` para una salida XML rápida y fácil en esas vistas. De esta forma, así podría verse nuestra vista de índice:: // templates/Recipes/xml/index.php - // Realizar un formateo y manipulacion en + // Realizar un formateo y manipulacion en // $recipes array. $xml = Xml::fromArray(['response' => $recipes]); echo $xml->asXML(); @@ -114,7 +114,7 @@ De esta forma, así podría verse nuestra vista de índice:: Al entregar un tipo de contenido específico usando :php:meth:`Cake\\Routing\\Router::extensions()`, CakePHP busca automáticamente un asistente de vista que coincida con el tipo. Como estamos utilizando -XML como tipo de contenido, no hay un asistente incorporado, sin embargo, si creara uno, se cargaría +XML como tipo de contenido, no hay un asistente incorporado, sin embargo, si creara uno, se cargaría automáticamente para nuestro uso en esas vistas. El XML procesado terminará pareciéndose a esto:: @@ -138,12 +138,12 @@ El XML procesado terminará pareciéndose a esto:: Crear la lógica para la acción de edición es un poco más complicado, pero no mucho. -Ya que se está proporcionando una API que genera XML como salida, es una opción natural +Ya que se está proporcionando una API que genera XML como salida, es una opción natural recibir XML como entrada. No te preocupes, las clases :php:class:`Cake\\Controller\\Component\\RequestHandler` -y :php:class:`Cake\\Routing\\Router` hacen las cosas mucho mas fáciles. Si un POST o +y :php:class:`Cake\\Routing\\Router` hacen las cosas mucho más fáciles. Si un POST o una solicitud PUT tiene un tipo de contenido XML, entonces la entrada se ejecuta a través de la clase de CakePHP :php:class:`Xml`, y la representación del arreglo de los datos se asigna a ``$this->request->getData()``. -Debido a esta característica, el manejo de datos XML y POST se hace en continuamente en paralelo: no se +Debido a esta característica, el manejo de datos XML y POST se hace en continuamente en paralelo: no se requieren cambios en el controlador o el código del modelo. Todo lo que necesita debe terminar en ``$this->request->getData()``. @@ -152,15 +152,15 @@ Aceptando Entradas en otros formatos Por lo general, las aplicaciones REST no solo generan contenido en formatos de datos alternativos, sino que también acepta datos en diferentes formatos. En CakePHP, el :php:class:`RequestHandlerComponent` ayuda a fácilitar esto. -Por defecto, decodificará cualquier entrada de datos en JSON / XML para solicitudes POST / PUT y proporcionar una -versión del arreglo de esos datos en ``$this->request->getData()``. También puedes conectar deserializadores +Por defecto, decodificará cualquier entrada de datos en JSON / XML para solicitudes POST / PUT y proporcionar una +versión del arreglo de esos datos en ``$this->request->getData()``. También puedes conectar deserializadores adicionales para formatos alternativos si los necesitas, usando: :php:meth:`RequestHandler::addInputType()`. Enrutamiento RESTful ==================== El enrutador de CakePHP fácilita la conexión de rutas de recursos RESTful. Ver la sección -`resource-routes` para más información. +`resource-routes` para más información. .. meta:: :title lang=es: REST diff --git a/es/development/routing.rst b/es/development/routing.rst index 0c87e63448..8db2d5e089 100644 --- a/es/development/routing.rst +++ b/es/development/routing.rst @@ -20,7 +20,7 @@ Vistazo rápido ============== Esta sección te enseñará los usos más comunes del enrutamiento en CakePHP con -ejemplos. Normalmente deseas mostrar algo como una página de destino, por lo que +ejemplos. Normalmente, deseas mostrar algo como una página de destino, por lo que tendrás que añadir esto a tu archivo **config/routes.php**:: /** @var \Cake\Routing\RouteBuilder $routes */ @@ -191,7 +191,7 @@ Algunos ejemplos de destino de cadena son:: // Controlador de plugin con prefijo Vendor/Cms.Management/Admin/Articles::view -Anteriormente usamos el asterisco final (``/*``) para capturar segmentos de ruta adicionales, +Anteriormente, usamos el asterisco final (``/*``) para capturar segmentos de ruta adicionales, también está el doble asterisco final (``/**``). Utilizando el doble asterisco final, capturará el resto de una URL como un único argumento. Esto es útil cuando se desea utilizar un argumento que incluye ``/``:: @@ -557,7 +557,7 @@ proporcionarlos como parte de las opciones de ``Router::url()``. dentro de un alcance de enrutamiento diferente. Al crear rutas con nombre, probablemente querrás ceñirte a algunas convenciones -par alos nombres de las rutas. CakePHP facilita la creación de nombres de rutas +para los nombres de las rutas. CakePHP facilita la creación de nombres de rutas al permitir definir prefijos de nombres en cada ámbito:: $routes->scope('/api', ['_namePrefix' => 'api:'], function (RouteBuilder $routes) { @@ -683,7 +683,7 @@ El prefijo actual estará disponible desde los métodos del controlador a travé Cuando usamos rutas de prefijo es importante configurar la opción ``prefix`` y utilizar el mismo formato CamelCased que se utiliza in el método ``prefix()``. -A continuación se explico cómo crear este enlace utilizando el helper HTML:: +A continuación se explica cómo crear este enlace utilizando el helper HTML:: // Ve a una ruta de prefijo echo $this->Html->link( @@ -1002,7 +1002,7 @@ Enrutamiento RESTful El enrutador ayuda a generar rutas RESTful para tus controladores. Las rutas RESTful son útiles cuando estás creando API endpoints para tus aplicaciones. Si quisiéramos -permitir el accesos REST a un controlador de recetas, haríamos algo como esto:: +permitir el acceso REST a un controlador de recetas, haríamos algo como esto:: // En config/routes.php... @@ -1047,7 +1047,7 @@ Las fuentes en orden de preferencia son: La variable POST ``_method`` es útil para utilizar un navegador como cliente REST (o cualquier otra cosa que pueda realizar POST). -Simplemente establece el valor de ``_method()`` con el nombre del +Simplemente, establece el valor de ``_method()`` con el nombre del método de la solicitud HTTP que deseas emular. Crear Rutas de Recursos Anidadas @@ -1083,7 +1083,7 @@ utilizar un controlador diferente en cada contexto mediante el uso de prefijos:: }); }); -Lo anterior asignará el recursos 'Comments' a +Lo anterior asignará el recurso 'Comments' a ``App\Controller\Articles\CommentsController``. Tener controladores separados te permite mantener la lógica del controlador más simple. Los prefijos creados de esta manera son compatibles con :ref:`prefix-routing`. @@ -1096,7 +1096,7 @@ esta manera son compatibles con :ref:`prefix-routing`. Limitar las Rutas Creadas ------------------------- -Por defecto, CakePHP conectará 6 rutas para cada recursos. Si deseas conectar +Por defecto, CakePHP conectará 6 rutas para cada recurso. Si deseas conectar sólo rutas de recursos específicas podrás utilizar la opción ``only``:: $routes->resources('Articles', [ @@ -1342,7 +1342,7 @@ Proporcionará enrutamiento inverso cuando la url de destino esté bien definida ['controller' => 'Articles', 'action' => 'view', $id] ); -También es útil cuando el destino es desconocido pero sigue un patrón bien definido:: +También es útil cuando el destino es desconocido, pero sigue un patrón bien definido:: $this->Html->link( 'View', @@ -1392,9 +1392,9 @@ donde la URL actual con algunas modificaciones es la base para el destino y los elementos de la URL actual son impredecibles. Como ejemplo, imagina un blog que permite a los usuarios crear **Articles** y -**Comments**, y marcar ambos como *published* o *draft*. Ambas URL de la página index -puedes incluir el id de usuario. La URL de **Comments** también puede incluir un -id de article para identificar a qué artículo se refiere el comentario. +**Comments**, y marcar ambos como *published* o *draft*. Ambas URL de la página index +pueden incluir el ID del usuario. La URL de **Comments** también puede incluir el +ID de un **Article** para identificar a qué artículo se refieren los comentarios. Aquí están las url para este escenario:: @@ -1535,7 +1535,7 @@ ubicación externa:: Redirige ``/home/*`` a ``/articles/view`` y pasa los parámetros a ``/articles/view``. El uso de una matriz como destino de redireccionamiento te permite utilizar otras rutas para definir -hacia dónde se debe dirigir un cadena de URL. Puedes redirigir a +hacia dónde se debe dirigir una cadena de URL. Puedes redirigir a ubicaciones externas utilizando una cadena de URL como destino:: $routes->scope('/', function (RouteBuilder $routes) { @@ -1553,7 +1553,7 @@ Enrutamiento de Entidades El enrutamiento de entidades te permite utilizar una entidad, una matriz o un objeto que implemente ``ArrayAccess`` como una fuente de parámetros de enrutamiento. Esto te permite refactorizar rutas fácilmente y generar URL con menos código. Por ejemplo, -si comienzas con un ruta similar a:: +si comienzas con una ruta similar a:: $routes->get( '/view/{id}', @@ -1609,7 +1609,7 @@ una matriz de parámetros de solicitud que pueda resolverse en un controlador y acción. Este método devuelve ``null`` para indicar un error de coincidencia. El método ``match()`` se utiliza para hacer coincidir una matriz de parámetros -de URL y crear una cadena de URL. Si los parámertos de la URL no coinciden, de +de URL y crear una cadena de URL. Si los parámertos de la URL no coinciden, se debe devolver la ruta ``false``. Puedes utilizar una clase de ruta personalizada al realizar una ruta utilizando @@ -1648,7 +1648,7 @@ antes de configurar cualquier ruta y evitar tener que especificar la opción $routes->setRouteClass(DashedRoute::class); -hará que todas las rutas conectadas después de esto utilicen la clase de ruta +Hará que todas las rutas conectadas después de esto utilicen la clase de ruta ``DashedRoute``. Llamando al método sin un argumento devolverá la clase de ruta predeterminada actual. @@ -1736,7 +1736,7 @@ Esto alterará la siguiente ruta:: Router::url(['plugin' => 'MyPlugin', 'controller' => 'Languages', 'action' => 'view', 'es']); -en esto:: +En esto:: Router::url(['plugin' => 'MyPlugin', 'controller' => 'Locations', 'action' => 'index', 'language' => 'es']); diff --git a/es/development/sessions.rst b/es/development/sessions.rst index 1167fb8a57..464451fb73 100644 --- a/es/development/sessions.rst +++ b/es/development/sessions.rst @@ -92,7 +92,7 @@ Manejadores de Sesiones Los manejadores de sesiones también se pueden definir en el array de configuración de la sesión. Al definir la clave de configuración 'handler.engine', puedes nombrar la clase o proporcionar una instancia del manejador. La clase/objeto debe implementar la interfaz nativa de PHP ``SessionHandlerInterface``. Implementar esta interfaz permitirá que ``Session`` mapee automáticamente los métodos para el manejador. Tanto los manejadores de sesiones de base de datos como de caché utilizan este método para guardar sesiones. Las configuraciones adicionales - para el manejador deben colocarse dentro del array del manejador. Luego puedes leer esos valores desde dentro de tu manejador:: +Para el manejador deben colocarse dentro del array del manejador. Luego puedes leer esos valores desde dentro de tu manejador:: 'Session' => [ 'handler' => [ @@ -173,7 +173,7 @@ En la mayoría de los casos, esta será la configuración predeterminada, por lo cualquier sesión recién creada como un archivo en, por ejemplo, ``/var/lib/php/session``. Pero esto también significa que cualquier tarea computacionalmente intensiva, como consultar un gran -conjunto de datos combinada con una sesión activa, **bloqueará ese archivo de sesión**, lo que +conjunto de datos combinado con una sesión activa, **bloqueará ese archivo de sesión**, lo que bloqueará a los usuarios para, por ejemplo, abrir una segunda pestaña de tu aplicación para hacer algo más mientras tanto. diff --git a/es/index.rst b/es/index.rst index 41f437ee6e..4f5131b4fd 100644 --- a/es/index.rst +++ b/es/index.rst @@ -1,11 +1,11 @@ Bienvenido ########## -CakePHP 3 es un ``framework`` de desarrollo web que funciona con PHP |phpversion| (min. PHP |minphpversion|). +CakePHP 5 es un ``framework`` de desarrollo web que funciona con PHP |phpversion| (min. PHP |minphpversion|). Puedes leer :doc:`CakePHP de un Vistazo ` para introducirte en los fundamentos de CakePHP 3. El manual de CakePHP (``Cookbook``) es un proyecto de documentación abierto, -editable y mantenido por la comunidad. Fíjate en el icono del lápiz anclado en +editable y mantenido por la comunidad. Fíjate en el icono del lápiz anclado en el lado derecho de la página; te llevará al editor online de GitHub de la página en la que estés permitiéndote contribuir con cualquier añadido, borrado o corrección de la documentación. diff --git a/es/installation.rst b/es/installation.rst index a3cb5d76b9..0a8bcb64e9 100644 --- a/es/installation.rst +++ b/es/installation.rst @@ -1,7 +1,7 @@ Instalación ########### -CakePHP se instala rápida y fácilmente. Los requisitos mínimos son +CakePHP se instala rápida y fácilmente. ¡Los requisitos mínimos son un servidor web y una copia de CakePHP, y ya! Aunque este manual se enfoca principalmente en configurar Apache (ya que es el más utilizado), puedes configurar CakePHP para que corra con una variedad de servidores web @@ -16,7 +16,7 @@ Requisitos - extensión mbstring. - extensión intl. -Técnicamente una base de datos no es necesaria, pero imaginamos que la +Técnicamente, una base de datos no es necesaria, pero imaginamos que la mayoría de aplicaciones utiliza alguna. CakePHP soporta una gran variedad de sistemas de bases de datos: @@ -96,14 +96,14 @@ Permisos CakePHP utiliza el directorio **tmp** para varias operaciones. Descripciones de Modelos, el caché de las vistas y la información de la sesión son algunos -ejemplos de lo anterior. El directorio **logs** es utilizado para para escribir +ejemplos de lo anterior. El directorio **logs** es utilizado para escribir ficheros de log por el motor de ``FileLog`` por defecto. Asegúrate de que los directorios **logs**, **tmp** y todos sus subdirectorios tengan permisos de escritura por el usuario del Servidor Web. La instalación de CakePHP a través de Composer se encarga de este proceso haciendo que dichos directorios tengan los permisos abiertos globalmente con el fin de que puedas -tener ajustado todo de manera más rápida. Obviamente es recomendable que revises, y +tener ajustado todo de manera más rápida. Obviamente, es recomendable que revises, y modifiques si es necesario, los permisos tras la instalación vía Composer para mayor seguridad. @@ -129,10 +129,10 @@ colocarla en el directorio raíz de tu Servidor Web, o tan complejo y flexible como lo desees. Esta sección cubrirá los dos tipos principales de instalación de CakePHP: Desarrollo y Producción. -- Desarrollo: fácil de arrancar, las URLs de la aplicación incluyen +- Desarrollo: fácil de arrancar, las URL de la aplicación incluyen el nombre del directorio de la aplicación de CakePHP y es menos segura. - Producción: Requiere tener la habilidad de configurar el directorio raíz - del Servidor Web, cuenta con URLs limpias y es bastante segura. + del Servidor Web, cuenta con URL limpias y es bastante segura. Desarrollo ========== @@ -272,7 +272,7 @@ obtener información. # Deny from all -#. Asegura que tu estás cargando mod\_rewrite correctamente. Debes +#. Asegura que tú estás cargando mod\_rewrite correctamente. Debes ver algo similar a esto: .. code-block:: apacheconf @@ -286,8 +286,8 @@ obtener información. ajustes estén activados. Verifica que tus archivos .htaccess está actualmente en directorio - correcto. Algunos sistemas operativo tratan los archivos que empiezan - con '.' como oculto y por lo tanto no podrás copiarlos. + correcto. Algunos sistemas operativos tratan los archivos que empiezan + con '.' como ocultos y, por lo tanto, no podrás copiarlos. #. Asegúrate que tu copia de CakePHP provenga desde la sección descargas del sitio o de nuestro repositorio de Git, y han sido desempacados correctamente, @@ -340,7 +340,7 @@ obtener información. Para muchos servicios de alojamiento (GoDaddy, 1and1), tu servidor web estará actualmente sirviendo desde un directorio de usuario que - actualmente usa mod\_rewrite. Si tu estás instalando CakePHP en la carpeta + actualmente usa mod\_rewrite. Si tú estás instalando CakePHP en la carpeta de usuario (http://example.com/~username/cakephp/), o alguna otra estructura de URL que ya utilice mod\_rewrite, necesitarás agregar una declaración a los archivos .htaccess que CakePHP usa (.htaccess, @@ -380,20 +380,20 @@ obtener información. Lo anterior simplemente previene que archivos adicionales incorrectos sean enviados a index.php en su lugar muestre la página 404 de tu servidor web. - Adicionalmente puedes crear una página 404 que concuerde, o usar la página 404 + Adicionalmente, puedes crear una página 404 que concuerde, o usar la página 404 incluida en CakePHP agregando una directiva ``ErrorDocument``: .. code-block:: apacheconf ErrorDocument 404 /404-not-found -nginx +Nginx ----- -nginx no hace uso de un archivo .htaccess como Apache, por esto es necesario -crear la reescritura de URL en la configuraciones de *site-available*. Esto +Nginx no hace uso de un archivo .htaccess como Apache, por esto es necesario +crear la reescritura de URL en la configuracion de *sites-available*. Esto usualmente se encuentra en ``/etc/nginx/sites-available/your_virtual_host_conf_file``. -Dependiendo de la configuración, tu necesitarás modificar esto, pero por lo menos, +Dependiendo de la configuración, necesitarás modificar esto, pero por lo menos, necesitas PHP corriendo como una instancia FastCGI: .. code-block:: nginx @@ -466,7 +466,7 @@ a www.example.com consulta el enlace de nginx anterior): IIS7 (Windows) -------------- -IIS7 no soporta de manera nativa los archivos .htaccess. Mientras hayan +IIS7 no soporta de manera nativa los archivos .htaccess. Mientras haya *add-ons* que puedan agregar soporte a estos archivos, puedes también importar las reglas htaccess en IIS para usar las redirecciones nativas de CakePHP. Para hacer esto, sigue los siguientes pasos: @@ -515,7 +515,7 @@ funcionar correctamente. No puedo usar Redireccionamientos de URL ---------------------------------------- -Si no quieres o no puedes obtener mod\_rewirte (o algun otro modulo +Si no quieres o no puedes obtener mod\_rewirte (o algún otro módulo compatible) en el servidor a correr, necesitarás usar el decorador de URL incorporado en CakePHP. En **config/app.php**, descomentar la línea para que se vea así:: diff --git a/es/intro.rst b/es/intro.rst index 426d7f5a5f..76d034d827 100644 --- a/es/intro.rst +++ b/es/intro.rst @@ -134,7 +134,7 @@ siguientes pasos: #. Las reglas de rescritura del servidor web envían la petición a **webroot/index.php**. #. Tu aplicación es cargada y ligada a un ``HttpServer``. #. Se inicializa el ``midleware`` de tu aplicación. -#. Una petición y respuesta son precesadas a través del ``Middleware PSR-7`` que tu aplicación utiliza. Normalmente esto incluye la captura de errores y enrutamiento. +#. Una petición y respuesta son precesadas a través del ``Middleware PSR-7`` que tu aplicación utiliza. Normalmente, esto incluye la captura de errores y enrutamiento. #. Si no recibe ninguna respuesta del ``middleware`` y la petición contiene información de enrutamiento, se selecciona un controlador y una acción. #. La acción del controlador es ejecutada y el controlador interactúa con los Modelos y Componentes necesarios. #. El controlador delega la creación de la respuesta a la Vista para generar la salida a partir de los datos del modelo. diff --git a/es/intro/cakephp-folder-structure.rst b/es/intro/cakephp-folder-structure.rst index cb9fb00b47..9d1996d6b5 100644 --- a/es/intro/cakephp-folder-structure.rst +++ b/es/intro/cakephp-folder-structure.rst @@ -25,8 +25,8 @@ directorios de primer nivel que deberías ver: esta carpeta es normalmente utilizada para almacenar descripciones de modelos y a veces información de sesión. - La carpeta *vendor* es donde CakePHP y otras dependencias de la aplicación - serán instaladas por `Composer `_. Editar éstos archivos no es - recomendado, ya que Composer sobre escribirá tus cambios en la próxima actualización.. + serán instaladas por `Composer `_. Editar estos archivos no es + recomendado, ya que Composer sobreescribirá tus cambios en la próxima actualización. - El directorio *webroot* es la raíz de los documentos públicos de tu aplicación. Contiene todos los archivos que quieres que sean accesibles públicamente. diff --git a/es/intro/where-to-get-help.rst b/es/intro/where-to-get-help.rst index b04f0eb312..14f53280ed 100644 --- a/es/intro/where-to-get-help.rst +++ b/es/intro/where-to-get-help.rst @@ -18,7 +18,7 @@ El Cookbook Este manual probablemente debería ser el primer lugar al que debas acudir para obtener respuestas. Como muchos otros proyectos de código libre, nuevos colaboradores se unen regularmente. Intenta encontrar por ti mismo las respuestas -a tus preguntas primero, puede que así tardes más en encontrar las respuestas +a tus preguntas primero, puede que así tardes más en encontrar las respuestas, pero permanecerán durante más tiempo - y además aliviarás nuestra carga de soporte. Tanto el manual como la API tienen una versión online. @@ -141,4 +141,4 @@ Español .. meta:: :title lang=es: Donde obtener ayuda :description lang=es: Donde obtener ayuda con CakePHP: La página oficial de CakePHP, El Cookbook, La Bakery, La API, en los casos de prueba, el canal IRC, El grupo Google de CakePHP o CakePHP Questions. - :keywords lang=es: cakephp,ayuda cakephp ,ayuda con cakephp,donde obtener ayuda,cakephp irc,cakephp preguntas,cakephp api,cakephp casos de prueba,proyectos código abierto,canal irc,código de referencia,canal irc,herramientas de desarrollo,caso de prueba,bakery + :keywords lang=es: cakephp,ayuda cakephp,ayuda con cakephp,donde obtener ayuda,cakephp irc,cakephp preguntas,cakephp api,cakephp casos de prueba,proyectos código abierto,canal irc,código de referencia,canal irc,herramientas de desarrollo,caso de prueba,bakery diff --git a/es/orm.rst b/es/orm.rst index 6ed39411a0..a24fb3a46d 100644 --- a/es/orm.rst +++ b/es/orm.rst @@ -2,7 +2,7 @@ Acceso a la base de datos & ORM ############################### En CakePHP el acceso a la base de datos se hace por medio de dos objetos primarios. -El primero son **repositories** -repositorios- o **table objects** -objetos de tabla-. +El primer tipo de objeto son **repositories** -repositorios- o **table objects** -objetos de tabla-. Estos objetos proveen acceso a colecciones de datos. Nos permiten guardar nuevos registros, modificar y borrar existentes, definir relaciones y realizar operaciones en masa. El segundo tipo de objeto son **entities** -entidades-. Las Entidades representan registros @@ -38,7 +38,7 @@ comenzar a utilizar el ORM. Por ejemplo si quisieramos leer datos de nuestra tab Como se ve, no es necesario agregar código extra ni ninguna otra configuración, gracias al uso de las convenciones de CakePHP. Si quisieramos modificar nuestra clase ArticlesTable para agregar asociaciones o definir métodos -adicionales deberiamos agregar las siguientes lineas en **src/Model/Table/ArticlesTable.php** :: +adicionales deberiamos agregar las siguientes líneas en **src/Model/Table/ArticlesTable.php** :: namespace App\Model\Table; @@ -50,7 +50,7 @@ adicionales deberiamos agregar las siguientes lineas en **src/Model/Table/Articl } Las clases Table usan una version en CamelCase del nombre de la tabla, con el sufijo ``Table``. -Una vez que tú clase fue creada, puedes obtener una referencia a esta usando :php:class:`~Cake\\ORM\\TableRegistry` como antes:: +Una vez que tu clase fue creada, puedes obtener una referencia a esta usando :php:class:`~Cake\\ORM\\TableRegistry` como antes:: use Cake\ORM\TableRegistry; @@ -59,8 +59,8 @@ Una vez que tú clase fue creada, puedes obtener una referencia a esta usando :p $articles = TableRegistry::getTableLocator()->get('Articles'); Ahora que tenemos una clase Table concreta, probablemente querramos usar una clase Entity concreta. -Las clases Entity permiten definir métodos de acceso y mutación, lógica para registros individuales y mucho mas. -Comenzaremos agregando las siguientes lineas en **src/Model/Entity/Article.php**:: +Las clases Entity permiten definir métodos de acceso y mutación, lógica para registros individuales y mucho más. +Comenzaremos agregando las siguientes líneas en **src/Model/Entity/Article.php**:: namespace App\Model\Entity; @@ -89,7 +89,7 @@ carguemos entidades de nuestra base de datos, vamos a obtener instancias de nues CakePHP usa convenciones de nombres para asociar las clases Table y Entity. Si necesitas modificar qué entidad utilizada una tabla, puedes usar el método ``entityClass()`` para especificar el nombre de una clase. -Vea :doc:`/orm/table-objects` y :doc:`/orm/entities` para mas información sobre como utilizar objetos Table y Entity en su aplicación. +Vea :doc:`/orm/table-objects` y :doc:`/orm/entities` para más información sobre como utilizar objetos Table y Entity en su aplicación. Más información =============== diff --git a/es/plugins.rst b/es/plugins.rst index 5d77801dc6..f6ebd8a323 100644 --- a/es/plugins.rst +++ b/es/plugins.rst @@ -319,7 +319,7 @@ Los Objetos de Plugin permiten a un autor de plugin definir lógica de configura Rutas del Plugin ================ -Los plugins pueden proporcionar archivos de rutas que contienen sus propias rutas. Cada plugin puede contener un archivo **config/routes.php** . Este archivo de rutas se puede cargar cuando se agrega el plugin o en el archivo de rutas de la aplicación. Para crear las rutas del plugin ContactManager, coloca lo siguiente en **plugins/ContactManager/config/routes.php**:: +Los plugins pueden proporcionar archivos de rutas que contienen sus propias rutas. Cada plugin puede contener un archivo **config/routes.php**. Este archivo de rutas se puede cargar cuando se agrega el plugin o en el archivo de rutas de la aplicación. Para crear las rutas del plugin ContactManager, coloca lo siguiente en **plugins/ContactManager/config/routes.php**:: `__. De esta manera, otras personas pueden usarlo como dependencia de Composer. También puedes proponer tu plugin a la lista de `awesome-cakephp `_. -Elige un nombre semánticamente significativo para el nombre del paquete. Idealmente, este debería llevar el prefijo del framework, en este caso "cakephp" como el framework. El nombre del proveedor generalmente será tu nombre de usuario de GitHub. **No** uses el espacio de nombres de CakePHP (cakephp) ya que está reservado para los plugins propiedad de CakePHP. La convención es usar letras minúsculas y guiones como separadores. +Elige un nombre semánticamente significativo para el nombre del paquete. Idealmente, este debería llevar el prefijo del framework, en este caso "cakephp" como el framework. El nombre del proveedor generalmente será tu nombre de usuario de GitHub. **No** uses el espacio de nombres de CakePHP (cakephp), ya que está reservado para los plugins propiedad de CakePHP. La convención es usar letras minúsculas y guiones como separadores. Entonces, si creaste un plugin "Logging" con tu cuenta de GitHub "FooBar", un buen nombre sería `foo-bar/cakephp-logging`. Y el plugin propiedad de CakePHP llamado "Localized" se puede encontrar bajo `cakephp/localized`, respectivamente. diff --git a/es/security/csrf.rst b/es/security/csrf.rst index a191232e97..e83c5559cc 100644 --- a/es/security/csrf.rst +++ b/es/security/csrf.rst @@ -148,7 +148,7 @@ a través del atributo del objeto de Request llamado ``csrfToken``. Usar la cook cuando tu código JavaScript reside en archivos separados de las plantillas de vista de CakePHP, y cuando ya tienes funcionalidad para analizar cookies mediante JavaScript. -Si tienes archivos JavaScript separados pero no quieres ocuparte de manejar cookies, +Si tienes archivos JavaScript separados, pero no quieres ocuparte de manejar cookies; podrías, por ejemplo, configurar el token en una variable global de JavaScript en tu diseño, mediante la definición de un bloque de script como este:: @@ -164,7 +164,7 @@ Otra alternativa sería poner el token en una metaetiqueta personalizada como es echo $this->Html->meta('csrfToken', $this->request->getAttribute('csrfToken')); -que luego se podría acceder en tus scripts buscando el elemento ``meta`` con +Que luego se podría acceder en tus scripts buscando el elemento ``meta`` con el nombre ``csrfToken``, que podría ser tan simple como esto cuando se usa jQuery:: var csrfToken = $('meta[name="csrfToken"]').attr('content'); diff --git a/es/views.rst b/es/views.rst index cf3f36c03b..2e0a099e31 100644 --- a/es/views.rst +++ b/es/views.rst @@ -56,7 +56,7 @@ Plantillas de Vista La capa de vista de CakePHP es la forma en que te comunicas con tus usuarios. La mayor parte del tiempo, tus vistas estarán renderizando documentos HTML/XHTML para los navegadores, pero también podrías necesitar responder a una aplicación remota a través de JSON o generar un archivo CSV para un usuario. -Los archivos de plantilla de CakePHP son archivos PHP regulares y utilizan la `sintaxis PHP alternativa `_ para las estructuras de control y la salida. Estos archivos contienen la lógica necesaria para preparar los datos recibidos del controlador en un formato de presentación que está listo para tu audiencia." +Los archivos de plantilla de CakePHP son archivos PHP regulares y utilizan la `sintaxis PHP alternativa `_ para las estructuras de control y la salida. Estos archivos contienen la lógica necesaria para preparar los datos recibidos del controlador en un formato de presentación que está listo para tu audiencia. Alternativas de impresion ------------------------- @@ -119,7 +119,7 @@ parte tiene usos distintos y se cubrirán en este capítulo: construir formularios, funcionalidades AJAX, paginar datos de modelos o servir feeds RSS. - **cells**: estas clases proporcionan características similares a un controlador para crear componentes de interfaz de usuario autosuficientes. Consulta la :doc:`/views/cells` - documentación para obtener más información." + documentación para obtener más información. Variables de Vista ------------------ diff --git a/es/views/helpers/flash.rst b/es/views/helpers/flash.rst index 890079d981..277364483b 100644 --- a/es/views/helpers/flash.rst +++ b/es/views/helpers/flash.rst @@ -13,17 +13,17 @@ el directorio **templates/element/flash**. Puedes notar CakePHP's App template viene con tres elementos flash: **success.php**, **default.php**, and **error.php**. -Renderizando Mnesajes Flash +Renderizando Mensajes Flash ============================= -Para renderizar un mensaje flash, puedes simplemente utilizar el método FlashHelper's ``render()`` -en tu template default ``templates/layout/default.php``:: +Para renderizar un mensaje flash, puedes simplemente utilizar el método ``render()`` +del FlashHelper en el template default ``templates/layout/default.php``:: Flash->render() ?> -Por defecto, CakePHP utiliza un "flash" key para los mensajes flash messages en la sesión. Sin embargo, si +Por defecto, CakePHP utiliza un "flash" key para los mensajes flash messages en la sesión. Sin embargo, si has especificado un "key" al establecer el mensaje flash en -:doc:`FlashComponent `, puedes especificar cual "key" de flash renderizar:: +:doc:`FlashComponent `, puedes especificar cuál "key" de flash renderizar:: Flash->render('other') ?> From 8de4e357be9b5c2157faff8fae455867423b6f10 Mon Sep 17 00:00:00 2001 From: othercorey Date: Tue, 28 Nov 2023 02:09:45 -0600 Subject: [PATCH 120/337] Add notes for getBooleanOption() and getMultipleOption() --- en/appendices/5-1-upgrade-guide.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 10b140e8b8..b475c7c1be 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -27,6 +27,11 @@ I18n New Features ============ +Console +------- + +- ``Arguments::getBooleanOption()`` and ``Arguments::getMultipleOption()`` were added. + Http ---- From 53be91e8adde08e2f7ec29c52d54c31ef67c95cf Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 28 Nov 2023 10:30:17 -0500 Subject: [PATCH 121/337] Add docs for cakephp/cakephp#17457 --- en/appendices/5-1-upgrade-guide.rst | 6 ++++++ en/views.rst | 2 +- en/views/cells.rst | 10 ++++++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index b475c7c1be..647b16c933 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -46,3 +46,9 @@ Validation - ``Validation::enum()`` and ``Validator::enum()`` were added. These validation methods simplify validating backed enum values. + +View +---- + +- View cells now emit events around their actions ``Cell.beforeAction`` and + ``Cell.afterAction``. diff --git a/en/views.rst b/en/views.rst index 2f8f2ddcb5..255a4b9f11 100644 --- a/en/views.rst +++ b/en/views.rst @@ -119,7 +119,7 @@ Another example, using if/elseif/else. Notice the colons: If you'd prefer to use a templating language like `Twig `_, checkout the `CakePHP Twig Plugin -`__ +`__ Template files are stored in **templates/**, in a folder named after the controller that uses the files, and named after the action it corresponds to. diff --git a/en/views/cells.rst b/en/views/cells.rst index cdd7c0f3f8..5c48db28f5 100644 --- a/en/views/cells.rst +++ b/en/views/cells.rst @@ -298,3 +298,13 @@ Loading a specific Helper just for a specific cell can be done via the following } } + +Cell Events +=========== + +Cells trigger the following events around the cell action: + +* ``Cell.beforeAction`` +* ``Cell.afterAction`` + +.. versionadded:: 5.1.0 From d2088413c52590e7e2d36aaf509df4831533fe28 Mon Sep 17 00:00:00 2001 From: mscherer Date: Tue, 28 Nov 2023 21:22:21 +0100 Subject: [PATCH 122/337] Consistent aliasing for assocs. --- en/orm/associations.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/en/orm/associations.rst b/en/orm/associations.rst index 093f6f49e5..2b0bd333e6 100644 --- a/en/orm/associations.rst +++ b/en/orm/associations.rst @@ -186,18 +186,18 @@ If you want to break different addresses into multiple associations, you can do { public function initialize(array $config): void { - $this->hasOne('HomeAddress', [ + $this->hasOne('HomeAddresses', [ 'className' => 'Addresses' ]) ->setProperty('home_address') - ->setConditions(['HomeAddress.label' => 'Home']) + ->setConditions(['HomeAddresses.label' => 'Home']) ->setDependent(true); - $this->hasOne('WorkAddress', [ + $this->hasOne('WorkAddresses', [ 'className' => 'Addresses' ]) ->setProperty('work_address') - ->setConditions(['WorkAddress.label' => 'Work']) + ->setConditions(['WorkAddresses.label' => 'Work']) ->setDependent(true); } } @@ -205,7 +205,7 @@ If you want to break different addresses into multiple associations, you can do .. note:: If a column is shared by multiple hasOne associations, you must qualify it with the association alias. - In the above example, the 'label' column is qualified with the 'HomeAddress' and 'WorkAddress' aliases. + In the above example, the 'label' column is qualified with the 'HomeAddresses' and 'WorkAddresses' aliases. Possible keys for hasOne association arrays include: From 5b30dd2950d94acebb8f3b676e19fa0fd89baabe Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 30 Nov 2023 02:44:01 +0100 Subject: [PATCH 123/337] Consistent AM Spelling --- en/console-commands/input-output.rst | 14 +++++++------- en/development/testing.rst | 2 +- en/orm/behaviors/translate.rst | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/en/console-commands/input-output.rst b/en/console-commands/input-output.rst index 23f298f3d0..dd53af0a21 100644 --- a/en/console-commands/input-output.rst +++ b/en/console-commands/input-output.rst @@ -195,7 +195,7 @@ Writing to ``stdout`` and ``stderr`` is another common operation in CakePHP:: $io->err('Error message'); In addition to vanilla output methods, CakePHP provides wrapper methods that -style output with appropriate ANSI colours:: +style output with appropriate ANSI colors:: // Green text on stdout $io->success('Success message'); @@ -307,9 +307,9 @@ new output style you could do:: $io->setStyle('flashy', ['text' => 'magenta', 'blink' => true]); This would then allow you to use a ```` tag in your shell output, and if -ansi colours are enabled, the following would be rendered as blinking magenta +ansi colors are enabled, the following would be rendered as blinking magenta text ``$this->out('Whoooa Something went wrong');``. When -defining styles you can use the following colours for the ``text`` and +defining styles you can use the following colors for the ``text`` and ``background`` attributes: * black @@ -332,10 +332,10 @@ truthy value enables them. Adding a style makes it available on all instances of ConsoleOutput as well, so you don't have to redeclare styles for both stdout and stderr objects. -Turning Off Colouring -===================== +Turning Off Coloring +==================== -Although colouring is pretty, there may be times when you want to turn it off, +Although coloring is pretty, there may be times when you want to turn it off, or force it on:: $io->outputAs(ConsoleOutput::RAW); @@ -350,6 +350,6 @@ no styling is done at all. There are three modes you can use. This is a good mode to use if you are outputting XML or, want to debug why your styling isn't working. -By default on \*nix systems ConsoleOutput objects default to colour output. +By default on \*nix systems ConsoleOutput objects default to color output. On Windows systems, plain output is the default unless the ``ANSICON`` environment variable is present. diff --git a/en/development/testing.rst b/en/development/testing.rst index f1af49c6f8..069d6fe934 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -111,7 +111,7 @@ and number passed. .. note:: - If you are on a Windows system you probably won't see any colours. + If you are on a Windows system you probably won't see any colors. Test Case Conventions ===================== diff --git a/en/orm/behaviors/translate.rst b/en/orm/behaviors/translate.rst index bdf9f64612..0f8372c5a3 100644 --- a/en/orm/behaviors/translate.rst +++ b/en/orm/behaviors/translate.rst @@ -57,7 +57,7 @@ language abbreviation with area code `UN M.49 :doc:`Internationalization and Localization `. Thus you are consistent and switching the language works identical for both, the - ``Translate Behaviour`` and ``Internationalization and Localization``. + ``Translate`` behavior and ``Internationalization and Localization``. So it's recommended to use either the two letter ISO code of the language like ``en``, ``fr``, ``de`` or the full locale name such as ``fr_FR``, ``es_AR``, From 257283f1df7a5d7989deca77d4ed24ba05338829 Mon Sep 17 00:00:00 2001 From: Al <7813306+mehov@users.noreply.github.com> Date: Fri, 1 Dec 2023 10:43:31 +0100 Subject: [PATCH 124/337] =?UTF-8?q?Address=20`WITH=20RECURSIVE=20=E2=80=A6?= =?UTF-8?q?`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- en/orm/query-builder.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 685ae5cd33..76f5bf0600 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -1885,6 +1885,8 @@ To build that query with the ORM query builder we would use:: ], ]); +If you need to build a recursive query (`WITH RECURSIVE …`), chain `->recursive()` onto `return $cte`. + Executing Complex Queries ------------------------- From a09a6eac759d1db7f855f31085af1fa69fa3aec5 Mon Sep 17 00:00:00 2001 From: Al <7813306+mehov@users.noreply.github.com> Date: Wed, 6 Dec 2023 17:27:53 +0100 Subject: [PATCH 125/337] Commit suggestion by @markstory in en/orm/query-builder.rst Co-authored-by: Mark Story --- en/orm/query-builder.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 76f5bf0600..4c0726bebf 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -1885,7 +1885,7 @@ To build that query with the ORM query builder we would use:: ], ]); -If you need to build a recursive query (`WITH RECURSIVE …`), chain `->recursive()` onto `return $cte`. +If you need to build a recursive query (``WITH RECURSIVE …``), chain ``->recursive()`` onto ``return $cte``. Executing Complex Queries ------------------------- From 4db979f56cd0f1267a626569da483ebd4842210f Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 8 Dec 2023 22:52:40 -0500 Subject: [PATCH 126/337] Add docs for LogTestTrait Refs cakephp/cakephp#17458 --- en/appendices/5-1-upgrade-guide.rst | 6 ++++ en/core-libraries/logging.rst | 49 +++++++++++++++++++++++++++-- en/development/testing.rst | 5 +++ 3 files changed, 58 insertions(+), 2 deletions(-) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 647b16c933..34a8216798 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -41,6 +41,12 @@ Http events when requests are sent. You can use these events to perform logging, caching or collect telemetry. +TestSuite +--------- + +- ``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. + Validation ---------- diff --git a/en/core-libraries/logging.rst b/en/core-libraries/logging.rst index 188005ca4a..d67e771b95 100644 --- a/en/core-libraries/logging.rst +++ b/en/core-libraries/logging.rst @@ -295,7 +295,7 @@ following keys: used. See ``syslog`` documentation for more options Creating Log Engines -===================== +==================== Log engines can be part of your application, or part of plugins. If for example you had a database logger called @@ -347,7 +347,7 @@ interface as it only requires you to implement the ``log()`` method. .. _logging-formatters: Logging Formatters ------------------- +================== Logging formatters allow you to control how log messages are formatted independent of the storage engine. Each core provided logging engine comes with @@ -378,6 +378,51 @@ To implement your own logging formatter you need to extend method you need to implement is ``format($level, $message, $context)`` which is responsible for formatting log messages. +.. _log-testing: + +Testing Logs +============ + +To test logging, add ``Cake\TestSuite\LogTestTrait`` to your test case. The +``LogTestTrait`` uses PHPUnit hooks to attach log engines that intercept the log +messages your application is making. Once you have captured logs you can perform +assertions on log messages your application is emitting. For example:: + + namespace App\Test\TestCase\Controller; + + use Cake\TestSuite\LogTestTrait; + use Cake\TestSuite\TestCase; + + class UsersControllerTest extends TestCase + { + use LogTestTrait; + + public function setUp(): void + { + parent::setUp(); + $this->setupLog([ + 'error' => ['scopes' => ['app.security']] + ]); + } + + public function testResetPassword() + { + $this->post('/users/resetpassword', ['email' => 'bob@example.com']); + $this->assertLogMessageContains('info', 'bob@example.com reset password', 'app.security'); + } + } + +You use ``setupLog()`` to define the log messages you wish to capture and +perform assertions on. After logs have been emitted you can make assertions on +the contents of logs, or the absence of them: + +* ``assertLogMessage(string $level, string $expectedMessage, ?string $scope = null, string $failMsg = '')`` Assert that a log message was found. +* ``assertLogMessageContains(string $level, string $expectedMessage, ?string $scope = null, string $failMsg = '')`` Assert that a log message contains the substring. +* ``assertLogAbsent(string $level, ?string $failMsg = '')`` Assert that no log messages of the given level were captured. + +The ``LogTestTrait`` will automatically clean up any loggers that were +configured. + Log API ======= diff --git a/en/development/testing.rst b/en/development/testing.rst index 8631555d03..22ca1ffac6 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1885,6 +1885,11 @@ Testing Email See :ref:`email-testing` for information on testing email. +Testing Logging +=============== + +See :ref:`log-testing` for information on testing log messages. + Creating Test Suites ==================== From 4acb90be91b2328cb2bac1f7313b18db2a800512 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 8 Dec 2023 22:55:58 -0500 Subject: [PATCH 127/337] Fix formatting --- en/core-libraries/logging.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/en/core-libraries/logging.rst b/en/core-libraries/logging.rst index d67e771b95..99430519da 100644 --- a/en/core-libraries/logging.rst +++ b/en/core-libraries/logging.rst @@ -416,9 +416,13 @@ You use ``setupLog()`` to define the log messages you wish to capture and perform assertions on. After logs have been emitted you can make assertions on the contents of logs, or the absence of them: -* ``assertLogMessage(string $level, string $expectedMessage, ?string $scope = null, string $failMsg = '')`` Assert that a log message was found. -* ``assertLogMessageContains(string $level, string $expectedMessage, ?string $scope = null, string $failMsg = '')`` Assert that a log message contains the substring. -* ``assertLogAbsent(string $level, ?string $failMsg = '')`` Assert that no log messages of the given level were captured. +* ``assertLogMessage(string $level, string $expectedMessage, ?string $scope + = null, string $failMsg = '')`` Assert that a log message was found. +* ``assertLogMessageContains(string $level, string $expectedMessage, ?string + $scope = null, string $failMsg = '')`` Assert that a log message contains the + substring. +* ``assertLogAbsent(string $level, ?string $failMsg = '')`` Assert that no log + messages of the given level were captured. The ``LogTestTrait`` will automatically clean up any loggers that were configured. From dab772e62f5ef9daff98aebc8d0b8b2c243ddfd1 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 11 Dec 2023 11:11:14 +0000 Subject: [PATCH 128/337] Bump actions/stale from 8 to 9 Bumps [actions/stale](https://github.com/actions/stale) from 8 to 9. - [Release notes](https://github.com/actions/stale/releases) - [Changelog](https://github.com/actions/stale/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/stale/compare/v8...v9) --- updated-dependencies: - dependency-name: actions/stale dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/stale.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 2ca96f675b..3be2c5aef0 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -16,7 +16,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/stale@v8 + - uses: actions/stale@v9 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' From 9aba46312d99f030bd13353cc1956f960f272e5e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 11 Dec 2023 11:11:20 +0000 Subject: [PATCH 129/337] Bump actions/setup-python from 4 to 5 Bumps [actions/setup-python](https://github.com/actions/setup-python) from 4 to 5. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/v4...v5) --- updated-dependencies: - dependency-name: actions/setup-python dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 92ff003173..5056c7f7eb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,7 +24,7 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: actions/setup-python@v4 + - uses: actions/setup-python@v5 with: python-version: 3.11 From 18179e49422f8624b0cfc165e284ad920f4127b7 Mon Sep 17 00:00:00 2001 From: Mark Scherer Date: Tue, 12 Dec 2023 10:10:41 +0100 Subject: [PATCH 130/337] Fix versions --- en/appendices.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/appendices.rst b/en/appendices.rst index 2ce90232a9..363169458a 100644 --- a/en/appendices.rst +++ b/en/appendices.rst @@ -4,7 +4,7 @@ Appendices Appendices contain information regarding the new features introduced in each version and the migration path between versions. -4.x Migration Guide +5.x Migration Guide =================== .. toctree:: @@ -16,7 +16,7 @@ introduced in each version and the migration path between versions. Backwards Compatibility Shimming ================================ -If you need/want to shim 3.x behavior, or partially migrate in steps, check out +If you need/want to shim 4.x behavior, or partially migrate in steps, check out the `Shim plugin `__ that can help mitigate some BC breaking changes. Forwards Compatibility Shimming From cf2afc781ffa8c88a662d0c1da5ad4de86057c68 Mon Sep 17 00:00:00 2001 From: Kearney Taaffe Date: Tue, 19 Dec 2023 15:44:03 -0600 Subject: [PATCH 131/337] Update database.rst Fixed a typo and corrected a file name --- en/tutorials-and-examples/cms/database.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/database.rst b/en/tutorials-and-examples/cms/database.rst index 9bfc2c8dde..6cd6c912ea 100644 --- a/en/tutorials-and-examples/cms/database.rst +++ b/en/tutorials-and-examples/cms/database.rst @@ -150,7 +150,7 @@ able to connect to the database' section has a green chef hat. .. note:: - The file **config/app_local.php** in your is a local override of the file **config/app_local.php** + The file **config/app_local.php** is a local override of the file **config/app.php** used to configure your development environment quickly. Creating our First Model From 619730b9df09f37b5d92e54866f13a13f05438bb Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Thu, 21 Dec 2023 18:40:54 +0100 Subject: [PATCH 132/337] unbuffered resultsets are no more --- en/orm/retrieving-data-and-resultsets.rst | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index e38e78c2cf..24c46a1f14 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -918,24 +918,7 @@ and you can use any collection method on ResultSet objects. Result set objects will lazily load rows from the underlying prepared statement. By default results will be buffered in memory allowing you to iterate a result -set multiple times, or cache and iterate the results. If you need work with -a data set that does not fit into memory you can disable buffering on the query -to stream results:: - - $query->disableBufferedResults(); - -Turning buffering off has a few caveats: - -#. You will not be able to iterate a result set more than once. -#. You will also not be able to iterate & cache the results. -#. Buffering cannot be disabled for queries that eager load hasMany or - belongsToMany associations, as these association types require eagerly - loading all results so that dependent queries can be generated. - -.. warning:: - - Streaming results will still allocate memory for the entire results when - using PostgreSQL and SQL Server. This is due to limitations in PDO. +set multiple times, or cache and iterate the results. Result sets allow you to cache/serialize or JSON encode results for API results:: From 0f501b317b5d7898c4ba2c9fb2c41cfec94212e7 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Thu, 21 Dec 2023 18:51:51 +0100 Subject: [PATCH 133/337] add info about removed resultset buffering toggle to migration docs --- en/appendices/5-0-migration-guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index bd825d9f3d..cf16de128d 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -132,6 +132,7 @@ Database - ``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 en/disable ResultSet buffering has been removed. Results are always buffered. Datasource ---------- From 9cea138c31d9052e1b37d6d7bc39512f26420223 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Thu, 21 Dec 2023 18:53:33 +0100 Subject: [PATCH 134/337] Update en/appendices/5-0-migration-guide.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Edgaras Janušauskas --- en/appendices/5-0-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index cf16de128d..e996809d75 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -132,7 +132,7 @@ Database - ``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 en/disable ResultSet buffering has been removed. Results are always buffered. +- The ability to enable/disable ResultSet buffering has been removed. Results are always buffered. Datasource ---------- From fcde462e7e1cd63fad6608c9fd9d90361e89dd8b Mon Sep 17 00:00:00 2001 From: Joe Theuerkauf Date: Mon, 25 Dec 2023 10:17:30 -0500 Subject: [PATCH 135/337] Remove "blog" tutorial (#7786) * Completely remove docs for the blog tutorial - caused odd page continuity * Add tips for using bake to create structures and migrations * Split database.rst so the Articles model is a separate page * Minor grammar and phrasing updates --- en/migrations.rst | 2 +- en/tutorials-and-examples.rst | 11 +- .../blog-auth-example/auth.rst | 381 ---------- en/tutorials-and-examples/blog/blog.rst | 233 ------ en/tutorials-and-examples/blog/part-three.rst | 391 ---------- en/tutorials-and-examples/blog/part-two.rst | 696 ------------------ .../cms/articles-controller.rst | 12 +- .../cms/articles-model.rst | 85 +++ en/tutorials-and-examples/cms/database.rst | 112 ++- .../cms/installation.rst | 20 +- 10 files changed, 155 insertions(+), 1788 deletions(-) delete mode 100644 en/tutorials-and-examples/blog-auth-example/auth.rst delete mode 100755 en/tutorials-and-examples/blog/blog.rst delete mode 100644 en/tutorials-and-examples/blog/part-three.rst delete mode 100644 en/tutorials-and-examples/blog/part-two.rst create mode 100644 en/tutorials-and-examples/cms/articles-model.rst diff --git a/en/migrations.rst b/en/migrations.rst index 51dcf6e52e..00218e316e 100644 --- a/en/migrations.rst +++ b/en/migrations.rst @@ -1,4 +1,4 @@ Migrations ########## -This page has `moved `__. +This page has `moved `__. diff --git a/en/tutorials-and-examples.rst b/en/tutorials-and-examples.rst index 07c26d5134..788172a197 100644 --- a/en/tutorials-and-examples.rst +++ b/en/tutorials-and-examples.rst @@ -14,19 +14,12 @@ and components. tutorials-and-examples/cms/installation tutorials-and-examples/cms/database + tutorials-and-examples/cms/articles-model tutorials-and-examples/cms/articles-controller tutorials-and-examples/cms/tags-and-users tutorials-and-examples/cms/authentication tutorials-and-examples/cms/authorization -.. toctree:: - :hidden: - - tutorials-and-examples/blog/blog - tutorials-and-examples/blog/part-two - tutorials-and-examples/blog/part-three - tutorials-and-examples/blog-auth-example/auth - .. meta:: :title lang=en: Tutorials & Examples - :keywords lang=en: application tutorials,glob,bakery,repository,applications,blog,acl + :keywords lang=en: application tutorials,glob,bakery,repository,applications,blog,cms,acl diff --git a/en/tutorials-and-examples/blog-auth-example/auth.rst b/en/tutorials-and-examples/blog-auth-example/auth.rst deleted file mode 100644 index c4f9277fe1..0000000000 --- a/en/tutorials-and-examples/blog-auth-example/auth.rst +++ /dev/null @@ -1,381 +0,0 @@ -Blog Tutorial - Authentication -############################## - -Following our :doc:`/tutorials-and-examples/blog/blog` example, imagine we -wanted to disallow unauthenticated users to create articles. - -Creating Users Table and Controller -=================================== - -First, let's create a new table in our blog database to hold our users' data: - -.. code-block:: mysql - - CREATE TABLE users ( - id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, - email VARCHAR(255), - password VARCHAR(255), - role VARCHAR(20), - created DATETIME DEFAULT NULL, - modified DATETIME DEFAULT NULL - ); - -If you are using PostgreSQL, connect to cake_blog database and execute the following SQL instead: - -.. code-block:: SQL - - CREATE TABLE users ( - id SERIAL PRIMARY KEY, - email VARCHAR(255), - password VARCHAR(255), - role VARCHAR(20), - created TIMESTAMP DEFAULT NULL, - modified TIMESTAMP DEFAULT NULL - ); - -We have adhered to the CakePHP conventions in naming tables, but we're also -taking advantage of another convention: By using the email and password -columns in a users table, CakePHP will be able to auto-configure most things for -us when implementing the user login. - -Next step is to create our ``UsersTable`` class, responsible for finding, saving -and validating any user data:: - - // src/Model/Table/UsersTable.php - namespace App\Model\Table; - - use Cake\ORM\Table; - use Cake\Validation\Validator; - - class UsersTable extends Table - { - public function validationDefault(Validator $validator): Validator - { - return $validator - ->notEmpty('email', 'An email is required') - ->email('email') - ->notEmpty('password', 'A password is required') - ->notEmpty('role', 'A role is required') - ->add('role', 'inList', [ - 'rule' => ['inList', ['admin', 'author']], - 'message' => 'Please enter a valid role' - ]); - } - - } - -Let's also create our ``UsersController``. The following content corresponds to -parts of a basic baked ``UsersController`` class using the code generation -utilities bundled with CakePHP:: - - // src/Controller/UsersController.php - - namespace App\Controller; - - use App\Controller\AppController; - use Cake\Event\EventInterface; - - class UsersController extends AppController - { - public function index() - { - $this->set('users', $this->Users->find()->all()); - } - - public function view($id) - { - $user = $this->Users->get($id); - $this->set(compact('user')); - } - - public function add() - { - $user = $this->Users->newEmptyEntity(); - if ($this->request->is('post')) { - $user = $this->Users->patchEntity($user, $this->request->getData()); - if ($this->Users->save($user)) { - $this->Flash->success(__('The user has been saved.')); - return $this->redirect(['action' => 'add']); - } - $this->Flash->error(__('Unable to add the user.')); - } - $this->set('user', $user); - } - } - -In the same way we created the views for our articles by using the code -generation tool, we can implement the user views. For the purpose of this -tutorial, we will show just the **add.php**: - -.. code-block:: php - - - -
    - Form->create($user) ?> -
    - - Form->control('email') ?> - Form->control('password') ?> - Form->control('role', [ - 'options' => ['admin' => 'Admin', 'author' => 'Author'] - ]) ?> -
    - Form->button(__('Submit')); ?> - Form->end() ?> -
    - -Adding Authentication -===================== - -We're now ready to add our authentication layer. In CakePHP this is handled by -the ``authentication`` plugin. Let's start off by installing it. Use composer to -install the Authentication Plugin: - -.. code-block:: console - - php composer.phar require "cakephp/authentication:^2.0" - -Then add the following to your application's ``bootstrap()`` method:: - - // in src/Application.php in the bootstrap() method. - $this->addPlugin('Authentication'); - -Adding Password Hashing -======================= - -Next, we'll create the ``User`` entity and add password hashing. Create the -**src/Model/Entity/User.php** entity file and add the following:: - - // src/Model/Entity/User.php - namespace App\Model\Entity; - - use Authentication\PasswordHasher\DefaultPasswordHasher; - use Cake\ORM\Entity; - - class User extends Entity - { - // Make all fields mass assignable except for primary key field "id". - protected array $_accessible = [ - '*' => true, - 'id' => false - ]; - - // ... - - protected function _setPassword($password) - { - if (strlen($password) > 0) { - return (new DefaultPasswordHasher)->hash($password); - } - } - - // ... - } - -Now every time the password property is assigned to the user it will be hashed -using the ``DefaultPasswordHasher`` class. - -Configuring Authentication -========================== - -Now it's time to configure the Authentication Plugin. -The Plugin will handle the authentication process using 3 different classes: - -* ``Application`` will use the Authentication Middleware and provide an - AuthenticationService, holding all the configuration we want to define how are - we going to check the credentials, and where to find them. -* ``AuthenticationService`` will be a utility class to allow you configure the - authentication process. -* ``AuthenticationMiddleware`` will be executed as part of the middleware queue, - this is before your Controllers are processed by the framework, and will pick the - credentials and process them to check if the user is authenticated. - -Authentication logic is divided into specific classes and the authentication -process happens before your controller layer. First authentication checks if the -user is authenticated (based in the configuration you provided) and injects the -user and the authentication results into the request for further reference. - -In **src/Application.php**, add the following imports:: - - // In src/Application.php add the following imports - use Authentication\AuthenticationService; - use Authentication\AuthenticationServiceInterface; - use Authentication\AuthenticationServiceProviderInterface; - use Authentication\Middleware\AuthenticationMiddleware; - use Psr\Http\Message\ServerRequestInterface; - -Then implement the authentication interface on your application class:: - - // in src/Application.php - class Application extends BaseApplication - implements AuthenticationServiceProviderInterface - { - -Then add the following:: - - // src/Application.php - public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue - { - $middlewareQueue - // ... other middleware added before - ->add(new RoutingMiddleware($this)) - // add Authentication after RoutingMiddleware - ->add(new AuthenticationMiddleware($this)); - - return $middlewareQueue; - } - - public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface - { - $authenticationService = new AuthenticationService([ - 'unauthenticatedRedirect' => '/users/login', - 'queryParam' => 'redirect', - ]); - - // Load identifiers, ensure we check email and password fields - $authenticationService->loadIdentifier('Authentication.Password', [ - 'fields' => [ - 'username' => 'email', - 'password' => 'password', - ], - ]); - - // Load the authenticators, you want session first - $authenticationService->loadAuthenticator('Authentication.Session'); - // Configure form data check to pick email and password - $authenticationService->loadAuthenticator('Authentication.Form', [ - 'fields' => [ - 'username' => 'email', - 'password' => 'password', - ], - 'loginUrl' => '/users/login', - ]); - - return $authenticationService; - } - -In you ``AppController`` class add the following code:: - - // src/Controller/AppController.php - public function initialize(): void - { - parent::initialize(); - $this->loadComponent('Flash'); - - // Add this line to check authentication result and lock your site - $this->loadComponent('Authentication.Authentication'); - -Now, on every request, the ``AuthenticationMiddleware`` will inspect the request -session to look for an authenticated user. If we are loading the -``/users/login`` page, it'll inspect also the posted form data (if any) to -extract the credentials. By default the credentials will be extracted from the -``email`` and ``password`` fields in the request data. The authentication -result will be injected in a request attribute named ``authentication``. You can -inspect the result at any time using -``$this->request->getAttribute('authentication')`` from your controller actions. -All your pages will be restricted as the ``AuthenticationComponent`` is checking -the result on every request. When it fails to find any authenticated user, it'll -redirect the user to the ``/users/login`` page. Note at this point, the site -won't work as we don't have a login page yet. If you visit your site, you'll -get an "infinite redirect loop". So, let's fix that! - -In your ``UsersController``, add the following code:: - - public function beforeFilter(\Cake\Event\EventInterface $event) - { - parent::beforeFilter($event); - // Configure the login action to not require authentication, preventing - // the infinite redirect loop issue - $this->Authentication->addUnauthenticatedActions(['login']); - } - - public function login() - { - $this->request->allowMethod(['get', 'post']); - $result = $this->Authentication->getResult(); - // regardless of POST or GET, redirect if user is logged in - if ($result->isValid()) { - // redirect to /articles after login success - $redirect = $this->request->getQuery('redirect', [ - 'controller' => 'Articles', - 'action' => 'index', - ]); - - return $this->redirect($redirect); - } - // display error if user submitted and authentication failed - if ($this->request->is('post') && !$result->isValid()) { - $this->Flash->error(__('Invalid email or password')); - } - } - -Add the template logic for your login action:: - - -
    - Flash->render() ?> -

    Login

    - Form->create() ?> -
    - - Form->control('email', ['required' => true]) ?> - Form->control('password', ['required' => true]) ?> -
    - Form->submit(__('Login')); ?> - Form->end() ?> - - Html->link("Add User", ['action' => 'add']) ?> -
    - -Now login page will allow us to correctly login into the application. -Test it by requesting any page of your site. After being redirected -to the ``/users/login`` page, enter the email and password you -picked previously when creating your user. You should be redirected -successfully after login. - -We need to add a couple more details to configure our application. We want all -``view`` and ``index`` pages accessible without logging in so we'll add this -specific configuration in ``AppController``:: - - // in src/Controller/AppController.php - public function beforeFilter(\Cake\Event\EventInterface $event) - { - parent::beforeFilter($event); - // for all controllers in our application, make index and view - // actions public, skipping the authentication check. - $this->Authentication->addUnauthenticatedActions(['index', 'view']); - } - -Logout -====== - -Add the logout action to the ``UsersController`` class:: - - // in src/Controller/UsersController.php - public function logout() - { - $result = $this->Authentication->getResult(); - // regardless of POST or GET, redirect if user is logged in - if ($result->isValid()) { - $this->Authentication->logout(); - return $this->redirect(['controller' => 'Users', 'action' => 'login']); - } - } - -Now you can visit ``/users/logout`` to log out. You should then be sent to the -login page. If you've made it this far, congratulations, you now have a simple -blog that: - -* Allows authenticated users to create and edit articles. -* Allows unauthenticated users to view articles and tags. - -Suggested Follow-up Reading ---------------------------- - -#. :doc:`/bake/usage` Generating basic CRUD code -#. `Authentication Plugin `__ documentation. - -.. meta:: - :title lang=en: Simple Authentication Application - :keywords lang=en: auto increment,authorization application,model user,array,conventions,authentication,urls,cakephp,delete,doc,columns diff --git a/en/tutorials-and-examples/blog/blog.rst b/en/tutorials-and-examples/blog/blog.rst deleted file mode 100755 index 498a9a3b03..0000000000 --- a/en/tutorials-and-examples/blog/blog.rst +++ /dev/null @@ -1,233 +0,0 @@ -Blog Tutorial -############# - -This tutorial will walk you through the creation of a simple blog application. -We'll be installing CakePHP, creating a database, and creating enough -application logic to list, add, edit, and delete blog articles. - -Here's what you'll need: - -#. A running web server. We're going to assume you're using Apache, - though the instructions for using other servers should be very - similar. We might have to play a little with the server - configuration, but most folks can get CakePHP up and running without - any configuration at all. Make sure you have PHP |minphpversion| or greater, and - that the ``mbstring`` and ``intl`` extensions are enabled in PHP. -#. A database server. We're going to be using MySQL server in this - tutorial. You'll need to know enough about SQL in order to create a - database: CakePHP will be taking the reins from there. Since we're using MySQL, - also make sure that you have ``pdo_mysql`` enabled in PHP. -#. Basic PHP knowledge. - -Let's get started! - -Getting CakePHP -=============== - -The easiest way to install CakePHP is to use Composer. Composer is a simple way -of installing CakePHP from your terminal or command line prompt. First, you'll -need to download and install Composer if you haven't done so already. If you -have cURL installed, it's as easy as running the following:: - - curl -s https://getcomposer.org/installer | php - -Or, you can download ``composer.phar`` from the -`Composer website `_. - -Then simply type the following line in your terminal from your -installation directory to install the CakePHP application skeleton -in the directory that you wish to use it with. For this example we will be using -"blog" but feel free to change it to something else.:: - - php composer.phar create-project --prefer-dist cakephp/app:4.* blog - -In case you've already got composer installed globally, you may instead type:: - - composer self-update && composer create-project --prefer-dist cakephp/app:4.* blog - -The advantage to using Composer is that it will automatically complete some -important set up tasks, such as setting the correct file permissions and -creating your config/app.php file for you. - -There are other ways to install CakePHP. If you cannot or don't want to use -Composer, check out the :doc:`/installation` section. - -Regardless of how you downloaded and installed CakePHP, once your set up is -completed, your directory setup should look something like the following:: - - cake_install/ - bin/ - config/ - logs/ - plugins/ - src/ - tests/ - tmp/ - vendor/ - webroot/ - .editorconfig - .gitignore - .htaccess - .travis.yml - composer.json - index.php - phpunit.xml.dist - README.md - -Now might be a good time to learn a bit about how CakePHP's directory -structure works: check out the -:doc:`/intro/cakephp-folder-structure` section. - -Directory Permissions on tmp and logs -===================================== - -The ``tmp`` and ``logs`` directories need to have proper permissions to be writable -by your webserver. If you used Composer for the install, this should have been done -for you and confirmed with a "Permissions set on " message. If you instead -got an error message or want to do it manually, the best way would be to find out -what user your webserver runs as (````) and change the ownership of -these two directories to that user. The final command you run (in \*nix) -might look something like this:: - - chown -R www-data tmp - chown -R www-data logs - -If for some reason CakePHP can't write to these directories, you'll be -informed by a warning while not in production mode. - -While not recommended, if you are unable to set the permissions to the same as -your webserver, you can simply set write permissions on the folder by running a -command such as:: - - chmod -R 777 tmp - chmod -R 777 logs - -Creating the Blog Database -========================== - -Next, let's set up the underlying MySQL database for our blog. If you -haven't already done so, create an empty database for use in this -tutorial with the name of your choice such as ``cake_blog``. Right now, -we'll just create a single table to store our articles. - -.. code-block:: mysql - - # First, create our articles table - CREATE TABLE articles ( - id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, - title VARCHAR(50), - body TEXT, - created DATETIME DEFAULT NULL, - modified DATETIME DEFAULT NULL - ); - -If you are using PostgreSQL, connect to cake_blog database and execute the following SQL instead: - -.. code-block:: SQL - - -- First, create our articles table - CREATE TABLE articles ( - id SERIAL PRIMARY KEY, - title VARCHAR(50), - body TEXT, - created TIMESTAMP DEFAULT NULL, - modified TIMESTAMP DEFAULT NULL - ); - -We'll also throw in a few articles to use for testing purposes. Execute the following -SQL statements into your database (works for both MySQL and PostgreSQL): - -.. code-block:: mysql - - # Then insert some articles for testing: - INSERT INTO articles (title,body,created) - VALUES ('The title', 'This is the article body.', NOW()); - INSERT INTO articles (title,body,created) - VALUES ('A title once again', 'And the article body follows.', NOW()); - INSERT INTO articles (title,body,created) - VALUES ('Title strikes back', 'This is really exciting! Not.', NOW()); - -The choices on table and column names are not arbitrary. If you -follow CakePHP's database naming conventions, and CakePHP's class naming -conventions (both outlined in -:doc:`/intro/conventions`), you'll be able to take -advantage of a lot of free functionality and avoid configuration. -CakePHP is flexible enough to accommodate even inconsistent legacy -database schemas, but adhering to the conventions will save you time. - -Check out :doc:`/intro/conventions` for more -information, but it's suffice to say that naming our table 'articles' -automatically hooks it to our Articles model, and having fields called -'modified' and 'created' will be automatically managed by CakePHP. - -Database Configuration -====================== - -Next, let's tell CakePHP where our database is and how to connect to it. -For many, this will be the first and last time you will need to configure -anything. - -The configuration should be pretty straightforward: just replace the -values in the ``Datasources.default`` array in the **config/app.php** file -with those that apply to your setup. A sample completed configuration -array might look something like the following:: - - return [ - // More configuration above. - 'Datasources' => [ - 'default' => [ - 'className' => 'Cake\Database\Connection', - 'driver' => 'Cake\Database\Driver\Mysql', - 'persistent' => false, - 'host' => 'localhost', - 'username' => 'cake_blog', - 'password' => 'AngelF00dC4k3~', - 'database' => 'cake_blog', - 'encoding' => 'utf8', - 'timezone' => 'UTC', - ], - ], - // More configuration below. - ]; - -Once you've saved your **config/app.php** file, you should be able to open -your browser and see the CakePHP welcome page. It should also tell -you that your database connection file was found, and that CakePHP -can successfully connect to the database. - -.. note:: - - A copy of CakePHP's default configuration file is found in - **config/app.default.php**. - -Optional Configuration -====================== - -There are a few other items that can be configured. Most developers -complete these laundry-list items, but they're not required for -this tutorial. One is defining a custom string (or "salt") for use -in security hashes. - -The security salt is used for generating hashes. If you used Composer this too is taken -care of for you during the install. Else you'd need to change the default salt value -by editing **config/app.php**. It doesn't matter much what the new value is, as long as -it's not guessable:: - - 'Security' => [ - 'salt' => 'something long and containing lots of different values.', - ], - -A Note on mod\_rewrite -====================== - -Occasionally new users will run into mod\_rewrite issues. For example -if the CakePHP welcome page looks a little funny (no images or CSS styles). -This probably means mod\_rewrite is not functioning on your system. Please refer -to the :ref:`url-rewriting` section to help resolve any issues you are having. - -Now continue to :doc:`/tutorials-and-examples/blog/part-two` to start building -your first CakePHP application. - -.. meta:: - :title lang=en: Blog Tutorial - :keywords lang=en: model view controller,object oriented programming,application logic,directory setup,basic knowledge,database server,server configuration,reins,documentroot,readme,repository,web server,productivity,lib,sql,aim,cakephp,servers,apache,downloads diff --git a/en/tutorials-and-examples/blog/part-three.rst b/en/tutorials-and-examples/blog/part-three.rst deleted file mode 100644 index b40a02c8ad..0000000000 --- a/en/tutorials-and-examples/blog/part-three.rst +++ /dev/null @@ -1,391 +0,0 @@ -Blog Tutorial - Part 3 -###################### - -Create a Tree Category -====================== - -Let's continue our blog application and imagine we want to categorize our -articles. We want the categories to be ordered, and for this, we will use the -:doc:`Tree behavior ` to help us organize the -categories. - -But first, we need to modify our tables. - -Migrations Plugin -================= - -We will use the `migrations plugin `_ to -create a table in our database. If you already have an articles table in your -database, erase it. - -Now open your application's **composer.json** file. Normally you would see that -the migrations plugin is already under ``require``. If not, add it by executing:: - - composer require cakephp/migrations:~1.0 - -The migrations plugin will now be in your application's **plugins** folder. -Also, add ``$this->addPlugin('Migrations');`` to your application's ``bootstrap`` method. - -Once the plugin is loaded, run the following command to create a migration file:: - - bin/cake bake migration CreateArticles title:string body:text category_id:integer created modified - -A migration file will be generated in the **/config/Migrations** folder with the following:: - - table('articles'); - $table->addColumn('title', 'string', [ - 'default' => null, - 'limit' => 255, - 'null' => false, - ]); - $table->addColumn('body', 'text', [ - 'default' => null, - 'null' => false, - ]); - $table->addColumn('category_id', 'integer', [ - 'default' => null, - 'limit' => 11, - 'null' => false, - ]); - $table->addColumn('created', 'datetime', [ - 'default' => null, - 'null' => false, - ]); - $table->addColumn('modified', 'datetime', [ - 'default' => null, - 'null' => false, - ]); - $table->create(); - } - } - -Run another command to create a ``categories`` table. If you need to specify -a field length, you can do it within brackets in the field type, ie:: - - bin/cake bake migration CreateCategories parent_id:integer lft:integer[10] rght:integer[10] name:string[100] description:string created modified - -This will generate the following file in **config/Migrations**:: - - table('categories'); - $table->addColumn('parent_id', 'integer', [ - 'default' => null, - 'limit' => 11, - 'null' => false, - ]); - $table->addColumn('lft', 'integer', [ - 'default' => null, - 'limit' => 10, - 'null' => false, - ]); - $table->addColumn('rght', 'integer', [ - 'default' => null, - 'limit' => 10, - 'null' => false, - ]); - $table->addColumn('name', 'string', [ - 'default' => null, - 'limit' => 100, - 'null' => false, - ]); - $table->addColumn('description', 'string', [ - 'default' => null, - 'limit' => 255, - 'null' => false, - ]); - $table->addColumn('created', 'datetime', [ - 'default' => null, - 'null' => false, - ]); - $table->addColumn('modified', 'datetime', [ - 'default' => null, - 'null' => false, - ]); - $table->create(); - } - } - -Now that the migration files are created, you can edit them before creating -your tables. We need to change the ``'null' => false`` for the ``parent_id`` -field with ``'null' => true`` because a top-level category has a null -``parent_id``. - -Run the following command to create your tables:: - - bin/cake migrations migrate - -Modifying the Tables -==================== - -With our tables set up, we can now focus on categorizing our articles. - -We suppose you already have the files (Tables, Controllers and Templates of -Articles) from part 2. So we'll just add the references to categories. - -We need to associate the Articles and Categories tables together. Open -the **src/Model/Table/ArticlesTable.php** file and add the following:: - - // src/Model/Table/ArticlesTable.php - - namespace App\Model\Table; - - use Cake\ORM\Table; - - class ArticlesTable extends Table - { - public function initialize(array $config): void - { - $this->addBehavior('Timestamp'); - // Just add the belongsTo relation with CategoriesTable - $this->belongsTo('Categories', [ - 'foreignKey' => 'category_id', - ]); - } - } - -Generate Skeleton Code for Categories -===================================== - -Create all files by launching bake commands:: - - bin/cake bake model Categories - bin/cake bake controller Categories - bin/cake bake template Categories - -Alternatively, you can bake all with just one line:: - - bin/cake bake all Categories - -The bake tool has created all your files in a snap. You can give them a quick -read if you want re-familiarize yourself with how CakePHP works. - -.. note:: - If you are on Windows remember to use \\ instead of /. - -You'll need to edit the following in **templates/Categories/add.php** -and **templates/Categories/edit.php**:: - - echo $this->Form->control('parent_id', [ - 'options' => $parentCategories, - 'empty' => 'No parent category' - ]); - -Attach TreeBehavior to CategoriesTable -====================================== - -The :doc:`TreeBehavior ` helps you manage hierarchical Tree -structures in database table. It uses the `MPTT logic -`_ to manage the data. -MPTT tree structures are optimized for reads, which often makes them a good fit -for read heavy applications like blogs. - -If you open the **src/Model/Table/CategoriesTable.php** file, you'll see -that the TreeBehavior has been attached to your CategoriesTable in the -``initialize()`` method. Bake adds this behavior to any Tables that contain -``lft`` and ``rght`` columns:: - - $this->addBehavior('Tree'); - -With the TreeBehavior attached you'll be able to access some features like -reordering the categories. We'll see that in a moment. - -But for now, you have to remove the following controls in your Categories add and -edit template files:: - - echo $this->Form->control('lft'); - echo $this->Form->control('rght'); - -In addition you should disable or remove the requirePresence from the validator -for both the ``lft`` and ``rght`` columns in your CategoriesTable model:: - - public function validationDefault(Validator $validator): Validator - { - $validator - ->add('id', 'valid', ['rule' => 'numeric']) - ->allowEmptyString('id', 'create'); - - $validator - ->add('lft', 'valid', ['rule' => 'numeric']) - // ->requirePresence('lft', 'create') - ->notEmpty('lft'); - - $validator - ->add('rght', 'valid', ['rule' => 'numeric']) - // ->requirePresence('rght', 'create') - ->notEmpty('rght'); - } - -These fields are automatically managed by the TreeBehavior when -a category is saved. - -Using your web browser, add some new categories using the -``/yoursite/categories/add`` controller action. - -Reordering Categories with TreeBehavior -======================================= - -In your categories index template file, you can list the categories and re-order -them. - -Let's modify the index method in your **CategoriesController.php** and add -``moveUp()`` and ``moveDown()`` methods to be able to reorder the categories in -the tree:: - - class CategoriesController extends AppController - { - public function index() - { - $categories = $this->Categories->find() - ->order(['lft' => 'ASC']) - ->all(); - $this->set(compact('categories')); - $this->viewBuilder()->setOption('serialize', ['categories']); - } - - public function moveUp($id = null) - { - $this->request->allowMethod(['post', 'put']); - $category = $this->Categories->get($id); - if ($this->Categories->moveUp($category)) { - $this->Flash->success('The category has been moved Up.'); - } else { - $this->Flash->error('The category could not be moved up. Please, try again.'); - } - return $this->redirect($this->referer(['action' => 'index'])); - } - - public function moveDown($id = null) - { - $this->request->allowMethod(['post', 'put']); - $category = $this->Categories->get($id); - if ($this->Categories->moveDown($category)) { - $this->Flash->success('The category has been moved down.'); - } else { - $this->Flash->error('The category could not be moved down. Please, try again.'); - } - return $this->redirect($this->referer(['action' => 'index'])); - } - } - -In **templates/Categories/index.php** replace the existing content with:: - -
    -

    -
      -
    • Html->link(__('New Category'), ['action' => 'add']) ?>
      • -
    -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    IdParent IdLftRghtNameDescriptionCreated
    id ?>parent_id ?>lft ?>rght ?>name) ?>description) ?>created) ?> - Html->link(__('View'), ['action' => 'view', $category->id]) ?> - Html->link(__('Edit'), ['action' => 'edit', $category->id]) ?> - Form->postLink(__('Delete'), ['action' => 'delete', $category->id], ['confirm' => __('Are you sure you want to delete # {0}?', $category->id)]) ?> - Form->postLink(__('Move down'), ['action' => 'moveDown', $category->id], ['confirm' => __('Are you sure you want to move down # {0}?', $category->id)]) ?> - Form->postLink(__('Move up'), ['action' => 'moveUp', $category->id], ['confirm' => __('Are you sure you want to move up # {0}?', $category->id)]) ?> -
    -
    - -Modifying the ArticlesController -================================ - -In our ``ArticlesController``, we'll get the list of all the categories. -This will allow us to choose a category for an Article when creating or editing -it:: - - // src/Controller/ArticlesController.php - - namespace App\Controller; - - use Cake\Http\Exception\NotFoundException; - - class ArticlesController extends AppController - { - // ... - - public function add() - { - $article = $this->Articles->newEmptyEntity(); - if ($this->request->is('post')) { - $article = $this->Articles->patchEntity($article, $this->request->getData()); - if ($this->Articles->save($article)) { - $this->Flash->success(__('Your article has been saved.')); - return $this->redirect(['action' => 'index']); - } - $this->Flash->error(__('Unable to add your article.')); - } - $this->set('article', $article); - - // Just added the categories list to be able to choose - // one category for an article - $categories = $this->Articles->Categories->find('treeList')->all(); - $this->set(compact('categories')); - } - } - -Modifying the Articles Templates -================================ - -The article add file should look something like this: - -.. code-block:: php - - - -

    Add Article

    - Form->create($article); - // just added the categories control - echo $this->Form->control('category_id'); - echo $this->Form->control('title'); - echo $this->Form->control('body', ['rows' => '3']); - echo $this->Form->button(__('Save Article')); - echo $this->Form->end(); - -When you go to the address ``/yoursite/articles/add`` you should see a list -of categories to choose. - -.. meta:: - :title lang=en: Blog Tutorial Migrations and Tree - :keywords lang=en: doc models,migrations,tree,controller actions,model article,php class,model class,model object,business logic,database table,naming convention,bread and butter,callbacks,prefixes,nutshell,interaction,array,cakephp,interface,applications,delete diff --git a/en/tutorials-and-examples/blog/part-two.rst b/en/tutorials-and-examples/blog/part-two.rst deleted file mode 100644 index 150846a883..0000000000 --- a/en/tutorials-and-examples/blog/part-two.rst +++ /dev/null @@ -1,696 +0,0 @@ -Blog Tutorial - Part 2 -###################### - -Create an Article Model -======================= - -Models are the bread and butter of CakePHP applications. By -creating a CakePHP model that will interact with our database, -we'll have the foundation in place needed to do our view, add, -edit, and delete operations later. - -CakePHP's model class files are split between ``Table`` and ``Entity`` objects. -``Table`` objects provide access to the collection of entities stored in a -specific table and go in **src/Model/Table**. The file we'll be creating will -be saved to **src/Model/Table/ArticlesTable.php**. The completed file should -look like this:: - - // src/Model/Table/ArticlesTable.php - - namespace App\Model\Table; - - use Cake\ORM\Table; - - class ArticlesTable extends Table - { - public function initialize(array $config): void - { - $this->addBehavior('Timestamp'); - } - } - -Naming conventions are very important in CakePHP. By naming our Table object -``ArticlesTable``, CakePHP can automatically infer that this Table object will -be used in the ``ArticlesController``, and will be tied to a database table called -``articles``. - -.. note:: - - CakePHP will dynamically create a model object for you if it - cannot find a corresponding file in **src/Model/Table**. This also means - that if you accidentally name your file wrong (i.e. articlestable.php or - ArticleTable.php), CakePHP will not recognize any of your settings and will - use the generated model instead. - -For more on models, such as callbacks, and validation, check out the :doc:`/orm` -chapter of the Manual. - -.. note:: - - If you completed :doc:`Part 1 of the Blog Tutorial - ` and created the ``articles`` table in - our Blog database you can leverage CakePHP's bake console and its code - generation capabilities to create the ``ArticlesTable`` model:: - - bin/cake bake model Articles - -For more on bake and its code generation features please visit :doc:`/bake/usage`. - -Create the Articles Controller -============================== - -Next, we'll create a controller for our articles. The controller is -where all interaction with articles will happen. In a nutshell, it's the place -where you play with the business logic contained in the models and get work -related to articles done. We'll place this new controller in a file called -**ArticlesController.php** inside the **src/Controller** directory. Here's -what the basic controller should look like:: - - // src/Controller/ArticlesController.php - - namespace App\Controller; - - class ArticlesController extends AppController - { - } - -Now, let's add an action to our controller. Actions often represent -a single function or interface in an application. For example, when -users request www.example.com/articles/index (which is also the same -as www.example.com/articles/), they might expect to see a listing of -articles. The code for that action would look like this:: - - // src/Controller/ArticlesController.php - - namespace App\Controller; - - class ArticlesController extends AppController - { - public function index() - { - $articles = $this->Articles->find()->all(); - $this->set(compact('articles')); - } - } - -By defining function ``index()`` in our ``ArticlesController``, users can now -access the logic there by requesting www.example.com/articles/index. Similarly, -if we were to define a function called ``foobar()``, users would be able to -access that at www.example.com/articles/foobar. - -.. warning:: - - You may be tempted to name your controllers and actions a certain - way to obtain a certain URL. Resist that temptation. Follow - :doc:`/intro/conventions` (capitalization, plural names, etc.) and create - readable, understandable action names. You can map URLs to your code using - :doc:`/development/routing` covered later on. - -The single instruction in the action uses ``set()`` to pass resultset -from the controller to the view (which we'll create next). The ``find()`` method -of the ``ArticlesTable`` object returns an instance of ``Cake\\ORM\\Query`` and -calling its ``all()`` method returns as instance of ``Cake\\Collection\\CollectionInterface`` -which is set as a view variable called 'articles'. - -.. note:: - - If you completed :doc:`Part 1 of the Blog Tutorial - ` and created the ``articles`` table in - your Blog database you can leverage CakePHP's bake console and its code - generation capabilities to create the ArticlesController class:: - - bin/cake bake controller Articles - -For more on bake and its code generation features please visit :doc:`/bake/usage`. - -To learn more about CakePHP's controllers, check out the -:doc:`/controllers` chapter. - -Creating Article Views -====================== - -Now that we have our data flowing from our model, and our application -logic is defined by our controller, let's create a view for -the index action we created above. - -CakePHP views are just presentation-flavored fragments that fit inside -an application's layout. For most applications, they're HTML mixed -with PHP, but they may end up as XML, CSV, or even binary data. - -A layout is presentation code that is wrapped around a view. -Multiple layouts can be defined, and you can switch between -them, but for now, let's just use the default. - -Remember in the last section how we assigned the 'articles' variable -to the view using the ``set()`` method? That would hand down the query -object collection to the view to be invoked with a ``foreach`` iteration. - -CakePHP's template files are stored in **templates** inside a folder -named after the controller they correspond to (we'll have to create -a folder named 'Articles' in this case). To format this article data in a -nice table, our view code might look something like this: - -.. code-block:: php - - - -

    Blog articles

    - - - - - - - - - - - - - - - - -
    IdTitleCreated
    id ?> - Html->link($article->title, ['action' => 'view', $article->id]) ?> - - created->format(DATE_RFC850) ?> -
    - -Hopefully this should look somewhat simple. - -You might have noticed the use of an object called ``$this->Html``. This is an -instance of the CakePHP :php:class:`Cake\\View\\Helper\\HtmlHelper` class. -CakePHP comes with a set of view helpers that make things like linking, form -output a snap. You can learn more about how to use them in -:doc:`/views/helpers`, but what's important to note here is that the ``link()`` -method will generate an HTML link with the given title (the first parameter) and -URL (the second parameter). - -When specifying URLs in CakePHP, it is recommended that you use the -array format. This is explained in more detail in the section on -Routes. Using the array format for URLs allows you to take -advantage of CakePHP's reverse routing capabilities. You can also -specify URLs relative to the base of the application in the form of -``/controller/action/param1/param2`` or use :ref:`named routes `. - -At this point, you should be able to point your browser to -http://www.example.com/articles/index. You should see your view, -correctly formatted with the title and table listing of the articles. - -If you happened to have clicked on one of the links we created in -this view (that link a article's title to a URL ``/articles/view/some\_id``), -you were probably informed by CakePHP that the action hasn't yet -been defined. If you were not so informed, either something has -gone wrong, or you actually did define it already, in which case -you are very sneaky. Otherwise, we'll create it in the -``ArticlesController`` now:: - - // src/Controller/ArticlesController.php - - namespace App\Controller; - - class ArticlesController extends AppController - { - public function index() - { - $this->set('articles', $this->Articles->find()->all()); - } - - public function view($id = null) - { - $article = $this->Articles->get($id); - $this->set(compact('article')); - } - } - -The ``set()`` call should look familiar. Notice we're using -``get()`` rather than ``find()`` because we only really want -a single article's information. - -Notice that our view action takes a parameter: the ID of the article -we'd like to see. This parameter is handed to the action through -the requested URL. If a user requests ``/articles/view/3``, then the value -'3' is passed as ``$id``. - -We also do a bit of error checking to ensure a user is actually accessing -a record. By using the ``get()`` function in the Articles table, we make sure -the user has accessed a record that exists. In case the requested article is not -present in the database, or the id is false the ``get()`` function will throw -a ``NotFoundException``. - -Now let's create the view for our new 'view' action and place it in -**templates/Articles/view.php** - -.. code-block:: php - - - -

    title) ?>

    -

    body) ?>

    -

    Created: created->format(DATE_RFC850) ?>

    - -Verify that this is working by trying the links at ``/articles/index`` or -manually requesting an article by accessing ``/articles/view/{id}``, replacing -``{id}`` by an article 'id'. - -Adding Articles -=============== - -Reading from the database and showing us the articles is a great -start, but let's allow for the adding of new articles. - -First, start by creating an ``add()`` action in the -``ArticlesController``:: - - // src/Controller/ArticlesController.php - - namespace App\Controller; - - use App\Controller\AppController; - - class ArticlesController extends AppController - { - public function initialize(): void - { - parent::initialize(); - - $this->loadComponent('Flash'); // Include the FlashComponent - } - - public function index() - { - $this->set('articles', $this->Articles->find()->all()); - } - - public function view($id) - { - $article = $this->Articles->get($id); - $this->set(compact('article')); - } - - public function add() - { - $article = $this->Articles->newEmptyEntity(); - if ($this->request->is('post')) { - $article = $this->Articles->patchEntity($article, $this->request->getData()); - if ($this->Articles->save($article)) { - $this->Flash->success(__('Your article has been saved.')); - return $this->redirect(['action' => 'index']); - } - $this->Flash->error(__('Unable to add your article.')); - } - $this->set('article', $article); - } - } - -.. note:: - - You need to include the :doc:`/controllers/components/flash` component in any controller - where you will use it. If necessary, include it in your ``AppController``. - -Here's what the ``add()`` action does: if the HTTP method of the -request was POST, try to save the data using the Articles model. If for some -reason it doesn't save, just render the view. This gives us a -chance to show the user validation errors or other warnings. - -Every CakePHP request includes a ``ServerRequest`` object which is accessible using -``$this->request``. The request object contains useful information regarding the -request that was just received, and can be used to control the flow of your -application. In this case, we use the :php:meth:`Cake\\Http\\ServerRequest::is()` -method to check that the request is a HTTP POST request. - -When a user uses a form to POST data to your application, that -information is available in ``$this->request->getData()``. You can use the -:php:func:`pr()` or :php:func:`debug()` functions to print it out if you want to -see what it looks like. - -We use FlashComponent's ``success()`` and ``error()`` methods to set a message -to a session variable. These methods are provided using PHP's `magic method -features `_. -Flash messages will be displayed on the page after redirection. In the layout we -have ``Flash->render() ?>`` which displays the message and clears the -corresponding session variable. The controller's -:php:meth:`Cake\\Controller\\Controller::redirect` function redirects to another -URL. The param ``['action' => 'index']`` translates to URL /articles i.e the -index action of the ``ArticlesController``. You can refer to -:php:func:`Cake\\Routing\\Router::url()` function on the `API -`_ to see the formats in which you can specify a URL for -various CakePHP functions. - -Calling the ``save()`` method will check for validation errors and -abort the save if any occur. We'll discuss how those errors are -handled in the following sections. - -Data Validation -=============== - -CakePHP goes a long way toward taking the monotony out of form input -validation. Everyone hates coding up endless forms and their -validation routines. CakePHP makes it easier and faster. - -To take advantage of the validation features, you'll need to use CakePHP's -:doc:`/views/helpers/form` helper in your views. The -:php:class:`Cake\\View\\Helper\\FormHelper` is available by default to all views -at ``$this->Form``. - -Here's our add view: - -.. code-block:: php - - - -

    Add Article

    - Form->create($article); - echo $this->Form->control('title'); - echo $this->Form->control('body', ['rows' => '3']); - echo $this->Form->button(__('Save Article')); - echo $this->Form->end(); - ?> - -We use the FormHelper to generate the opening tag for an HTML -form. Here's the HTML that ``$this->Form->create()`` generates: - -.. code-block:: html - -
    - -If ``create()`` is called with no parameters supplied, it assumes -you are building a form that submits via POST to the current controller's -``add()`` action (or ``edit()`` action when ``id`` is included in -the form data). - -The ``$this->Form->control()`` method is used to create form elements -of the same name. The first parameter tells CakePHP which field -they correspond to, and the second parameter allows you to specify -a wide array of options - in this case, the number of rows for the -textarea. There's a bit of introspection and automagic here: -``control()`` will output different form elements based on the model -field specified. - -The ``$this->Form->end()`` call ends the form. Outputting hidden inputs if -CSRF/Form Tampering prevention is enabled. - -Now let's go back and update our **templates/Articles/index.php** -view to include a new "Add Article" link. Before the ````, add -the following line:: - - Html->link('Add Article', ['action' => 'add']) ?> - -You may be wondering: how do I tell CakePHP about my validation -requirements? Validation rules are defined in the model. Let's look -back at our Articles model and make a few adjustments:: - - // src/Model/Table/ArticlesTable.php - - namespace App\Model\Table; - - use Cake\ORM\Table; - use Cake\Validation\Validator; - - class ArticlesTable extends Table - { - public function initialize(array $config): void - { - $this->addBehavior('Timestamp'); - } - - public function validationDefault(Validator $validator): Validator - { - $validator - ->notEmptyString('title') - ->requirePresence('title', 'create') - ->notEmptyString('body') - ->requirePresence('body', 'create'); - - return $validator; - } - } - -The ``validationDefault()`` method tells CakePHP how to validate your data when -the ``save()`` method is called. Here, we've specified that both the body and -title fields must not be empty, and are required for both create and update -operations. CakePHP's validation engine is strong, with a number of pre-built -rules (credit card numbers, email addresses, etc.) and flexibility for adding -your own validation rules. For more information on that -setup, check the :doc:`/core-libraries/validation` documentation. - -Now that your validation rules are in place, use the app to try to add -an article with an empty title or body to see how it works. Since we've used the -:php:meth:`Cake\\View\\Helper\\FormHelper::control()` method of the FormHelper to -create our form elements, our validation error messages will be shown -automatically. - -Editing Articles -================ - -Post editing: here we go. You're a CakePHP pro by now, so you -should have picked up a pattern. Make the action, then the view. -Here's what the ``edit()`` action of the ``ArticlesController`` would look -like:: - - // src/Controller/ArticlesController.php - - public function edit($id = null) - { - $article = $this->Articles->get($id); - if ($this->request->is(['post', 'put'])) { - $this->Articles->patchEntity($article, $this->request->getData()); - if ($this->Articles->save($article)) { - $this->Flash->success(__('Your article has been updated.')); - return $this->redirect(['action' => 'index']); - } - $this->Flash->error(__('Unable to update your article.')); - } - - $this->set('article', $article); - } - -This action first ensures that the user has tried to access an existing record. -If they haven't passed in an ``$id`` parameter, or the article does not -exist, we throw a ``NotFoundException`` for the CakePHP ErrorHandler to take -care of. - -Next the action checks whether the request is either a POST or a PUT request. If -it is, then we use the POST data to update our article entity by using the -``patchEntity()`` method. Finally we use the table object to save the entity -back or kick back and show the user validation errors. - -The edit view might look something like this: - -.. code-block:: php - - - -

    Edit Article

    - Form->create($article); - echo $this->Form->control('title'); - echo $this->Form->control('body', ['rows' => '3']); - echo $this->Form->button(__('Save Article')); - echo $this->Form->end(); - ?> - -This view outputs the edit form (with the values populated), along -with any necessary validation error messages. - -CakePHP will determine whether a ``save()`` generates an insert or an -update statement based on the state of the entity. - -You can now update your index view with links to edit specific -articles: - -.. code-block:: php - - - -

    Blog articles

    -

    Html->link("Add Article", ['action' => 'add']) ?>

    -
    - - - - - - - - - - - - - - - - - - -
    IdTitleCreatedAction
    id ?> - Html->link($article->title, ['action' => 'view', $article->id]) ?> - - created->format(DATE_RFC850) ?> - - Html->link('Edit', ['action' => 'edit', $article->id]) ?> -
    - -Deleting Articles -================= - -Next, let's make a way for users to delete articles. Start with a -``delete()`` action in the ``ArticlesController``:: - - // src/Controller/ArticlesController.php - - public function delete($id) - { - $this->request->allowMethod(['post', 'delete']); - - $article = $this->Articles->get($id); - if ($this->Articles->delete($article)) { - $this->Flash->success(__('The article with id: {0} has been deleted.', h($id))); - return $this->redirect(['action' => 'index']); - } - } - -This logic deletes the article specified by ``$id``, and uses -``$this->Flash->success()`` to show the user a confirmation -message after redirecting them on to ``/articles``. If the user attempts to -do a delete using a GET request, the ``allowMethod()`` will throw an Exception. -Uncaught exceptions are captured by CakePHP's exception handler, and a nice -error page is displayed. There are many built-in -:doc:`Exceptions ` that can be used to indicate the various -HTTP errors your application might need to generate. - -Because we're just executing some logic and redirecting, this -action has no view. You might want to update your index view with -links that allow users to delete articles, however: - -.. code-block:: php - - - -

    Blog articles

    -

    Html->link('Add Article', ['action' => 'add']) ?>

    - - - - - - - - - - - - - - - - - - - -
    IdTitleCreatedActions
    id ?> - Html->link($article->title, ['action' => 'view', $article->id]) ?> - - created->format(DATE_RFC850) ?> - - Form->postLink( - 'Delete', - ['action' => 'delete', $article->id], - ['confirm' => 'Are you sure?']) - ?> - Html->link('Edit', ['action' => 'edit', $article->id]) ?> -
    - -Using :php:meth:`~Cake\\View\\Helper\\FormHelper::postLink()` will create a link -that uses JavaScript to do a POST request deleting our article. - -.. warning:: - - Allowing content to be deleted using GET requests is dangerous, as web - crawlers could accidentally delete all your content. - -.. note:: - - This view code also uses the ``FormHelper`` to prompt the user with a - JavaScript confirmation dialog before they attempt to delete an - article. - -Routes -====== - -For some, CakePHP's default routing works well enough. Developers -who are sensitive to user-friendliness and general search engine -compatibility will appreciate the way that CakePHP's URLs map to -specific actions. So we'll just make a quick change to routes in -this tutorial. - -For more information on advanced routing techniques, see -:ref:`routes-configuration`. - -By default, CakePHP responds to a request for the root of your site -(for example, http://www.example.com) using its ``PagesController``, rendering -a view called "home". Instead, we'll replace this with our -ArticlesController by creating a routing rule. - -CakePHP's routing is found in **config/routes.php**. You'll want -to comment out or remove the line that defines the default root -route. It looks like this: - -.. code-block:: php - - $builder->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']); - -This line connects the URL '/' with the default CakePHP home page. -We want it to connect with our own controller, so replace that line -with this one: - -.. code-block:: php - - $builder->connect('/', ['controller' => 'Articles', 'action' => 'index']); - -This should connect users requesting '/' to the ``index()`` action of -our ``ArticlesController``. - -.. note:: - - CakePHP also makes use of 'reverse routing'. If, with the above - route defined, you pass - ``['controller' => 'Articles', 'action' => 'index']`` to a - function expecting an array, the resulting URL used will be '/'. - It's therefore a good idea to always use arrays for URLs as this - means your routes define where a URL goes, and also ensures that - links point to the same place. - -Conclusion -========== - -Keep in mind that this tutorial was very basic. CakePHP has *many* more -features to offer, and is flexible in ways we didn't wish to cover -here for simplicity's sake. Use the rest of this manual as a guide -for building more feature-rich applications. - -Now that you've created a basic CakePHP application, you can either continue to -:doc:`/tutorials-and-examples/blog/part-three`, or start your own project. You -can also peruse the :doc:`/topics` or `API `_ to -learn more about CakePHP. - -If you need help, there are many ways to get the help you need - please see the -:doc:`/intro/where-to-get-help` page. Welcome to CakePHP! - -Suggested Follow-up Reading ---------------------------- - -These are common tasks people learning CakePHP usually want to study next: - -1. :ref:`view-layouts`: Customizing your website layout -2. :ref:`view-elements`: Including and reusing view snippets -3. :doc:`/bake/usage`: Generating basic CRUD code -4. :doc:`/tutorials-and-examples/blog-auth-example/auth`: User authentication - and authorization tutorial - -.. meta:: - :title lang=en: Blog Tutorial Adding a Layer - :keywords lang=en: doc models,validation check,controller actions,model post,php class,model class,model object,business logic,database table,naming convention,bread and butter,callbacks,prefixes,nutshell,interaction,array,cakephp,interface,applications,delete diff --git a/en/tutorials-and-examples/cms/articles-controller.rst b/en/tutorials-and-examples/cms/articles-controller.rst index 06d30ad314..b52cd0de53 100644 --- a/en/tutorials-and-examples/cms/articles-controller.rst +++ b/en/tutorials-and-examples/cms/articles-controller.rst @@ -547,5 +547,15 @@ that uses JavaScript to do a POST request deleting our article. JavaScript confirmation dialog before they attempt to delete an article. -With a basic articles management setup, we'll create the :doc:`basic actions +.. tip:: + + The ``ArticlesController`` can also be built with ``bake``: + + .. code-block:: console + + /bin/cake bake controller articles + + However, this does not build the **templates/Articles/*.php** files. + +With a basic articles management setup, we'll create the :doc:`basic actions for our Tags and Users tables `. diff --git a/en/tutorials-and-examples/cms/articles-model.rst b/en/tutorials-and-examples/cms/articles-model.rst new file mode 100644 index 0000000000..d9fd3c2036 --- /dev/null +++ b/en/tutorials-and-examples/cms/articles-model.rst @@ -0,0 +1,85 @@ +CMS Tutorial - Creating our First Model +####################################### + +Models are the heart of CakePHP applications. They enable us to read and +modify our data. They allow us to build relations between our data, validate +data, and apply application rules. Models provide the foundation necessary to +create our controller actions and templates. + +CakePHP's models are composed of ``Table`` and ``Entity`` objects. ``Table`` +objects provide access to the collection of entities stored in a specific table. +They are stored in **src/Model/Table**. The file we'll be creating will be saved +to **src/Model/Table/ArticlesTable.php**. The completed file should look like +this:: + + addBehavior('Timestamp'); + } + } + +We've attached the :doc:`/orm/behaviors/timestamp` behavior, which will +automatically populate the ``created`` and ``modified`` columns of our table. +By naming our Table object ``ArticlesTable``, CakePHP can use naming conventions +to know that our model uses the ``articles`` table. CakePHP also uses +conventions to know that the ``id`` column is our table's primary key. + +.. note:: + + CakePHP will dynamically create a model object for you if it + cannot find a corresponding file in **src/Model/Table**. This also means + that if you accidentally name your file wrong (i.e. articlestable.php or + ArticleTable.php), CakePHP will not recognize any of your settings and will + use the generated model instead. + +We'll also create an Entity class for our Articles. Entities represent a single +record in the database and provide row-level behavior for our data. Our entity +will be saved to **src/Model/Entity/Article.php**. The completed file should +look like this:: + + true, + 'body' => true, + 'published' => true, + 'created' => true, + 'modified' => true, + 'users' => true, + ]; + } + +Right now, our entity is quite slim; we've only set up the ``_accessible`` +property, which controls how properties can be modified by +:ref:`entities-mass-assignment`. + +.. tip:: + The ``ArticlesTable`` and ``Article`` Entity classes can be generated from a + terminal: + + .. code-block:: console + + bin/cake bake model articles + +We can't do much with this model yet. Next, we'll create our first +:doc:`Controller and Template ` +to allow us to interact with our model. diff --git a/en/tutorials-and-examples/cms/database.rst b/en/tutorials-and-examples/cms/database.rst index 6cd6c912ea..7abbcf9a2f 100644 --- a/en/tutorials-and-examples/cms/database.rst +++ b/en/tutorials-and-examples/cms/database.rst @@ -110,7 +110,7 @@ following SQL instead: (1, 'First Post', 'first-post', 'This is the first post.', TRUE, NOW(), NOW()); -You may have noticed that the ``articles_tags`` table used a composite primary +You may have noticed that the ``articles_tags`` table uses a composite primary key. CakePHP supports composite primary keys almost everywhere, allowing you to have simpler schemas that don't require additional ``id`` columns. @@ -153,80 +153,58 @@ able to connect to the database' section has a green chef hat. The file **config/app_local.php** is a local override of the file **config/app.php** used to configure your development environment quickly. -Creating our First Model -======================== +Migrations +========== -Models are the heart of CakePHP applications. They enable us to read and -modify our data. They allow us to build relations between our data, validate -data, and apply application rules. Models provide the foundation necessary to -create our controller actions and templates. +The SQL statements to create the tables for this tutorial can also be generated +using the Migrations Plugin. Migrations provide a platform-independent way to +run queries so the subtle differences between MySQL, PostgreSQL, SQLite, etc. +don't become obstacles. -CakePHP's models are composed of ``Table`` and ``Entity`` objects. ``Table`` -objects provide access to the collection of entities stored in a specific table. -They are stored in **src/Model/Table**. The file we'll be creating will be saved -to **src/Model/Table/ArticlesTable.php**. The completed file should look like -this:: +.. code-block:: console - addColumn('article_id', 'integer', [ + 'autoIncrement' => true, + 'default' => null, + 'limit' => 11, + 'null' => false, + ]); + $table->addColumn('tag_id', 'integer', [ + 'autoIncrement' => true, + 'default' => null, + 'limit' => 11, + 'null' => false, + ]); - class ArticlesTable extends Table - { - public function initialize(array $config): void - { - parent::initialize($config); - $this->addBehavior('Timestamp'); - } - } + Remove those lines to prevent foreign key problems. Once adjustments are + done:: -We've attached the :doc:`/orm/behaviors/timestamp` behavior, which will -automatically populate the ``created`` and ``modified`` columns of our table. -By naming our Table object ``ArticlesTable``, CakePHP can use naming conventions -to know that our model uses the ``articles`` table. CakePHP also uses -conventions to know that the ``id`` column is our table's primary key. + bin/cake migrations migrate -.. note:: +Likewise, the starter data records can be done with seeds. - CakePHP will dynamically create a model object for you if it - cannot find a corresponding file in **src/Model/Table**. This also means - that if you accidentally name your file wrong (i.e. articlestable.php or - ArticleTable.php), CakePHP will not recognize any of your settings and will - use the generated model instead. +.. code-block:: console -We'll also create an Entity class for our Articles. Entities represent a single -record in the database and provide row-level behavior for our data. Our entity -will be saved to **src/Model/Entity/Article.php**. The completed file should -look like this:: + bin/cake bake seed Users + bin/cake bake seed Articles - true, - 'body' => true, - 'published' => true, - 'created' => true, - 'modified' => true, - 'users' => true, - ]; - } - -Right now, our entity is quite slim; we've only set up the ``_accessible`` -property, which controls how properties can be modified by -:ref:`entities-mass-assignment`. - -We can't do much with our models yet. Next, we'll create our first -:doc:`Controller and Template ` to allow us to interact -with our model. +Fill the seed data above into the new ``UsersSeed`` and ``ArticlesSeed`` +classes, then:: + + bin/cake migrations seed + +Read more about building migrations and data seeding: `Migrations +`__ + +With the database built, we can now build :doc:`Models +`. diff --git a/en/tutorials-and-examples/cms/installation.rst b/en/tutorials-and-examples/cms/installation.rst index 25de250972..d7c7c3ab50 100644 --- a/en/tutorials-and-examples/cms/installation.rst +++ b/en/tutorials-and-examples/cms/installation.rst @@ -14,8 +14,7 @@ Here's what you'll need: ``pdo_mysql`` enabled in PHP. #. Basic PHP knowledge. -Before starting you should make sure that you have got an up to date PHP -version: +Before starting you should make sure that you're using a supported PHP version: .. code-block:: console @@ -65,12 +64,12 @@ There are other ways to install CakePHP. If you cannot or don't want to use Composer, check out the :doc:`/installation` section. Regardless of how you downloaded and installed CakePHP, once your set up is -completed, your directory setup should look something like the following:: +completed, your directory setup should look like the following, though other +files may also be present:: cms/ bin/ config/ - logs/ plugins/ resources/ src/ @@ -79,12 +78,8 @@ completed, your directory setup should look something like the following:: tmp/ vendor/ webroot/ - .editorconfig - .gitignore - .htaccess composer.json index.php - phpunit.xml.dist README.md Now might be a good time to learn a bit about how CakePHP's directory structure @@ -93,6 +88,13 @@ works: check out the :doc:`/intro/cakephp-folder-structure` section. If you get lost during this tutorial, you can see the finished result `on GitHub `_. +.. tip:: + + The ``bin/cake`` console utility can build most of the classes and data + tables in this tutorial automatically. However, we recommend following along + with the manual code examples to understand how the pieces fit together and + how to add your application logic. + Checking our Installation ========================= @@ -115,4 +117,4 @@ bullet points should be green chef hats other than CakePHP being able to connect your database. If not, you may need to install additional PHP extensions, or set directory permissions. -Next, we will build our :doc:`Database and create our first model `. +Next, we will build our :doc:`Database`. From e412f09c646ccebfa19b379fb2165951a4c22d33 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 31 Dec 2023 12:40:47 -0500 Subject: [PATCH 136/337] Clarify session documentation further Refs cakephp/cakephp#17513 --- en/development/sessions.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/en/development/sessions.rst b/en/development/sessions.rst index d4e2a785a2..e451a0dd22 100644 --- a/en/development/sessions.rst +++ b/en/development/sessions.rst @@ -15,8 +15,10 @@ Session Configuration Session configuration is generally defined in **/config/app.php**. The available options are: -* ``Session.timeout`` - The number of *minutes* before CakePHP's session - handler expires the session. +* ``Session.timeout`` - The number of *minutes* a session can remain 'idle'. If + no request is received for ``timeout`` minutes, CakePHP's session + handler will expire the session. You can set this option to ``0`` to disable + server side idle timeouts. * ``Session.defaults`` - Allows you to use the built-in default session configurations as a base for your session configuration. See below for the @@ -49,7 +51,7 @@ this:: ] ]); -As of v4.0 CakePHP also sets the `SameSite `__ attribute to ``Lax`` +CakePHP also sets the `SameSite `__ attribute to ``Lax`` by default for session cookies, which helps protect against CSRF attacks. You can change the default value by setting ``session.cookie_samesite`` php.ini config:: @@ -80,8 +82,7 @@ configured using:: Configure::write('Session', [ 'defaults' => 'php', 'ini' => [ - // Invalidate the cookie after 30 minutes without visiting - // any page on the site. + // Invalidate the cookie after 30 minutes 'session.cookie_lifetime' => 1800 ] ]); @@ -93,7 +94,7 @@ client reports, you should use ``Session.timeout``. Please note that ``Session.timeout`` corresponds to the total time of inactivity for a user (i.e. the time without visiting any page where the session -is used), and does not limit the total amount of minutes a user can stay +is used), and does not limit the total amount of minutes a user can stay active on the site. Built-in Session Handlers & Configuration From dad8707e06a94833952d9d6f5fdd17eca02802cd Mon Sep 17 00:00:00 2001 From: mscherer Date: Mon, 1 Jan 2024 13:37:48 +0100 Subject: [PATCH 137/337] Enum update --- en/orm/database-basics.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 7ccd4b4d73..e3cb8a4365 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -479,8 +479,8 @@ Where ``ArticleStatus`` contains something like:: enum ArticleStatus: string { - case PUBLISHED = 'Y'; - case UNPUBLISHED = 'N'; + case Published = 'Y'; + case Unpublished = 'N'; } .. _adding-custom-database-types: From dfa169bb7cdbc750584686046c63f995698d7fda Mon Sep 17 00:00:00 2001 From: mscherer Date: Mon, 1 Jan 2024 13:47:38 +0100 Subject: [PATCH 138/337] Add conventions --- en/orm/database-basics.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index e3cb8a4365..e4542470b0 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -485,6 +485,12 @@ Where ``ArticleStatus`` contains something like:: .. _adding-custom-database-types: +Recommendation: Use a tinyint/smallint type here. + +Conventions for enums: +- The case is ``CamelCase``. +- Use `{Entity}{ColumnName}` as enum name to auto-map during baking to your baked (form) fields. + Adding Custom Types ------------------- From 8604a4a782e2cd7f156626ac3c75401da684ae8c Mon Sep 17 00:00:00 2001 From: mscherer Date: Mon, 1 Jan 2024 14:58:14 +0100 Subject: [PATCH 139/337] Add conventions --- en/contributing/cakephp-coding-conventions.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/en/contributing/cakephp-coding-conventions.rst b/en/contributing/cakephp-coding-conventions.rst index 4b764eff17..f690c69264 100644 --- a/en/contributing/cakephp-coding-conventions.rst +++ b/en/contributing/cakephp-coding-conventions.rst @@ -569,6 +569,16 @@ underscore character, for example:: define('LONG_NAMED_CONSTANT', 2); +Enums +----- +Enum cases are defined in ``CamelCase`` style:: + + enum ArticleStatus: string + { + case Published = 'Y'; + case NotPublishedYet = 'N'; + } + Careful when using empty()/isset() ================================== From 29bf13f13dceb193ecac0e7725c6e38a83b1bf4e Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 1 Jan 2024 22:12:15 -0500 Subject: [PATCH 140/337] Add docs for Server.terminate event Refs cakephp/cakephp#17514 --- en/appendices/5-1-upgrade-guide.rst | 4 ++++ en/controllers/request-response.rst | 22 +++++++++++++++++++++- 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 34a8216798..1287cb0833 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -40,6 +40,10 @@ Http - ``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. TestSuite --------- diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 47f1c5671c..18217dbb90 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -1040,7 +1040,7 @@ will make the browser remove its local cookie:: .. _cors-headers: Setting Cross Origin Request Headers (CORS) -=========================================== +------------------------------------------- The ``cors()`` method is used to define `HTTP Access Control `__ @@ -1067,6 +1067,26 @@ criteria are met: is very application specific. We recommend you build your own ``CORSMiddleware`` if you need one and adjust the response object as desired. +Running logic after the Response has been sent +---------------------------------------------- + +In fastcgi based environments you can listen to the ``Server.terminate`` event +to run logic **after** the response has been sent to the client. Make sure your +application's **webroot/index.php** contains the following:: + + $server = new Server(new Application(dirname(__DIR__) . '/config')); + + $request = ServerRequest::fromGlobals(); + $response = $server->run($request); + $server->emit($response); + $server->terminate($request, $response); + +.. warning:: + In non fastcgi environments the ``Server.terminate`` event is fired before + the response is sent. + +.. versionadded:: 5.1.0 + Common Mistakes with Immutable Responses ======================================== From 947c569782650b0705ed284cdde11912019f815a Mon Sep 17 00:00:00 2001 From: Mark Story Date: Wed, 3 Jan 2024 16:08:40 -0500 Subject: [PATCH 141/337] Add docs notes for cakephp/cakephp#17521 --- en/appendices/5-1-upgrade-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 34a8216798..da96d27aa6 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -44,6 +44,8 @@ Http TestSuite --------- +- ``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. From 3050e78649cd8474e35ab66ceef9b235492a1829 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 4 Jan 2024 13:07:23 -0500 Subject: [PATCH 142/337] Tweak wording and update conventions docs for enums --- en/contributing/cakephp-coding-conventions.rst | 1 + en/intro/conventions.rst | 4 ++++ en/orm/database-basics.rst | 10 +++++----- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/en/contributing/cakephp-coding-conventions.rst b/en/contributing/cakephp-coding-conventions.rst index f690c69264..3f04fb3283 100644 --- a/en/contributing/cakephp-coding-conventions.rst +++ b/en/contributing/cakephp-coding-conventions.rst @@ -571,6 +571,7 @@ underscore character, for example:: Enums ----- + Enum cases are defined in ``CamelCase`` style:: enum ArticleStatus: string diff --git a/en/intro/conventions.rst b/en/intro/conventions.rst index a2bf72cee2..7a98cf25c2 100644 --- a/en/intro/conventions.rst +++ b/en/intro/conventions.rst @@ -114,6 +114,10 @@ Entity class names are singular CamelCased and have no suffix. ``User``, matching the ``users``, ``menu_links`` and ``user_favorite_pages`` tables respectively. +Enum class names should use a ``{Entity}{Column}`` convention, and enum cases +should use CamelCased names. + + View Conventions ================ diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index e4542470b0..402f9ecd8b 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -483,13 +483,13 @@ Where ``ArticleStatus`` contains something like:: case Unpublished = 'N'; } -.. _adding-custom-database-types: +CakePHP recommends a few conventions for enums: -Recommendation: Use a tinyint/smallint type here. +- Enum classnames should follow ``{Entity}{ColumnName}`` style to enable + detection while running bake and to aid with project consistency. +- Enum cases should use CamelCase style. -Conventions for enums: -- The case is ``CamelCase``. -- Use `{Entity}{ColumnName}` as enum name to auto-map during baking to your baked (form) fields. +.. _adding-custom-database-types: Adding Custom Types ------------------- From 58ccfad60035843516b7883b4a3ff9e2b678f34f Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 6 Jan 2024 23:26:08 -0500 Subject: [PATCH 143/337] Add docs for casting functions Refs cakephp/cakephp#17295 --- en/appendices/5-1-upgrade-guide.rst | 7 +++++++ en/controllers/request-response.rst | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index da96d27aa6..5deb064675 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -32,6 +32,13 @@ Console - ``Arguments::getBooleanOption()`` and ``Arguments::getMultipleOption()`` were added. +Core +---- + +- The ``toString``, ``toInt``, ``toBool`` were added. These methods give you + a typesafe way to cast request data or other input. Should casting not + succeed, ``null`` will be returned. + Http ---- diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 47f1c5671c..c5ea1f9b7e 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -100,6 +100,25 @@ If you want to access all the query parameters you can use $query = $this->request->getQueryParams(); +You can use the casting utility functions to provide typesafe access to request +data and other input:: + + use function Cake\Core\toBool; + use function Cake\Core\toInt; + use function Cake\Core\toString; + + // $active is bool|null. + $active = toBool($this->request->getQuery('active')); + + // $page is int|null. + $page = toInt($this->request->getQuery('page')); + + // $query is string|null. + $query = toString($this->request->getQuery('query')); + +.. versionadded:: 5.1.0 + Casting functions were added. + Request Body Data ----------------- From 73b168c45f95a2747c3cf493d48a4db4a5d223d8 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 8 Jan 2024 20:57:06 -0500 Subject: [PATCH 144/337] Update en/appendices/5-1-upgrade-guide.rst Co-authored-by: othercorey --- en/appendices/5-1-upgrade-guide.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 5deb064675..4b0ddd8364 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -35,9 +35,8 @@ Console Core ---- -- The ``toString``, ``toInt``, ``toBool`` were added. These methods give you - a typesafe way to cast request data or other input. Should casting not - succeed, ``null`` will be returned. +- 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. Http ---- From 68fdd7956f15bfb92dcabd17e932d06553db72c6 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 8 Jan 2024 23:10:44 -0500 Subject: [PATCH 145/337] Remove setAction from the docs It was removed from the code because of low usage and incompatibility with the DI container. Fixes cakephp/cakephp#17537 --- en/controllers.rst | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/en/controllers.rst b/en/controllers.rst index 3af2f63fe9..4e252e9775 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -434,20 +434,6 @@ By using the second parameter you can define a status code for your redirect:: See the :ref:`redirect-component-events` section for how to redirect out of a life-cycle handler. -Forwarding to an Action on the Same Controller ----------------------------------------------- - -.. php:method:: setAction($action, $args...) - -If you need to forward the current action to a different action on the *same* -controller, you can use ``Controller::setAction()`` to update the request -object, modify the view template that will be rendered and forward execution to -the named action:: - - // From a delete action, you can render the updated - // list page. - $this->setAction('index'); - Loading Additional Models ========================= From 206590155593a3a03a4bec971803e8be758f2798 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 12 Jan 2024 16:04:40 -0500 Subject: [PATCH 146/337] Improve example --- en/controllers/request-response.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 18217dbb90..af4866dde0 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -1074,11 +1074,12 @@ In fastcgi based environments you can listen to the ``Server.terminate`` event to run logic **after** the response has been sent to the client. Make sure your application's **webroot/index.php** contains the following:: - $server = new Server(new Application(dirname(__DIR__) . '/config')); + $app = new Application(dirname(__DIR__) . '/config')) + $server = new Server($app); - $request = ServerRequest::fromGlobals(); - $response = $server->run($request); + $response = $server->run(ServerRequest::fromGlobals()); $server->emit($response); + $request = $app->getContainer()->get(ServerRequest::class); $server->terminate($request, $response); .. warning:: From 341ae3f3a4359e4a770e71479c8577dc96c45a13 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 13 Jan 2024 16:21:01 -0500 Subject: [PATCH 147/337] Add note for cakephp/cakephp#17543 --- en/appendices/5-1-upgrade-guide.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 0c4b44a2f8..40bfa9c37e 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -27,6 +27,12 @@ I18n New Features ============ +Command +------- + +- ``bin/cake plugin list`` now includes the current version number for each + plugin if available. + Console ------- From d95d955c3ddec2331a150d734eb79d2e4b1383d1 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 13 Jan 2024 16:54:24 -0500 Subject: [PATCH 148/337] Add notes to 5.1 docs for redis tls connections --- en/appendices/5-1-upgrade-guide.rst | 7 +++++++ en/core-libraries/caching.rst | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 40bfa9c37e..add5676461 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -27,6 +27,13 @@ I18n 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 ------- diff --git a/en/core-libraries/caching.rst b/en/core-libraries/caching.rst index ec0c0ddfa4..27f787acb9 100644 --- a/en/core-libraries/caching.rst +++ b/en/core-libraries/caching.rst @@ -169,6 +169,13 @@ RedisEngine uses the following engine specific options: * ``persistent`` Should a persistent connection be made to Redis. * ``timeout`` Connection timeout for Redis. * ``unix_socket`` Path to a unix socket for Redis. +* ``tls`` Connect to redis over TLS. +* ``ssl_key`` The ssl private key used for TLS connections. +* ``ssl_ca`` The ssl certificate authority file for TLS connections. +* ``ssl_cert`` The ssl certificate used for TLS connections. + +.. versionadded:: 5.1.0 + TLS connections were added in 5.1 MemcacheEngine Options ---------------------- From 3d14350cf7aa96a911a8626971eafb739dd31623 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Tue, 16 Jan 2024 15:48:02 +0100 Subject: [PATCH 149/337] adjust docs for plugin list command (#7796) --- en/appendices/5-1-upgrade-guide.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index add5676461..29a1301776 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -37,8 +37,8 @@ Cache Command ------- -- ``bin/cake plugin list`` now includes the current version number for each - plugin if available. +- ``bin/cake plugin list`` has been added to list all available plugins, + their load configuration and version. Console ------- @@ -48,6 +48,7 @@ Console 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. From 00ecd7ba8bdb7acbdf0cd6eb67c24a9085352a4f Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 16 Jan 2024 12:34:12 -0500 Subject: [PATCH 150/337] Update the terminate docs to reflect new changes. Refs cakephp/cakephp#17545 --- en/controllers/request-response.rst | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 4836ce504b..638bf7eedd 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -1090,16 +1090,10 @@ Running logic after the Response has been sent ---------------------------------------------- In fastcgi based environments you can listen to the ``Server.terminate`` event -to run logic **after** the response has been sent to the client. Make sure your -application's **webroot/index.php** contains the following:: - - $app = new Application(dirname(__DIR__) . '/config')) - $server = new Server($app); - - $response = $server->run(ServerRequest::fromGlobals()); - $server->emit($response); - $request = $app->getContainer()->get(ServerRequest::class); - $server->terminate($request, $response); +to run logic **after** the response has been sent to the client. The +``terminate`` event will be passed a ``request`` and ``response``. The +``request`` is fetched from the applications' DI container, or from +``Router::getRequest()`` if the DI container does not have a request registered. .. warning:: In non fastcgi environments the ``Server.terminate`` event is fired before From 52bb9f84d42160d22bbb42e59bce6354e6b8dc60 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Wed, 17 Jan 2024 20:10:24 +0100 Subject: [PATCH 151/337] add info about different array structure for marshalling deeper assocs via patchEntity --- en/orm/saving-data.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst index 6ee1aec049..c0e0f8c1df 100644 --- a/en/orm/saving-data.rst +++ b/en/orm/saving-data.rst @@ -443,6 +443,8 @@ merge deeper to deeper levels, you can use the third parameter of the method:: // In a controller. $associated = ['Tags', 'Comments.Users']; + // or + $associated = ['Tags', 'Comments' => ['associated' => ['Users']]]; $article = $articles->get(1, ['contain' => $associated]); $articles->patchEntity($article, $this->request->getData(), [ 'associated' => $associated, From 9f8d8aad0a6926a1e342df8f2e5ebcd149e64e91 Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 18 Jan 2024 13:07:51 +0530 Subject: [PATCH 152/337] Improved docs for `fetchModel()` --- en/controllers.rst | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/en/controllers.rst b/en/controllers.rst index 4e252e9775..4eaf686bb7 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -434,22 +434,8 @@ By using the second parameter you can define a status code for your redirect:: See the :ref:`redirect-component-events` section for how to redirect out of a life-cycle handler. -Loading Additional Models -========================= - -.. php:method:: fetchModel(string $alias, array $config = []) - -The ``fetchModel()`` method is useful to load models or ORM tables that -are not the controller's default. Models retrieved with this method will not be -set as properties on your controller:: - - // Get an ElasticSearch model - $articles = $this->fetchModel('Articles', 'Elastic'); - - // Get a webservices model - $github = $this->fetchModel('GitHub', 'Webservice'); - -.. versionadded:: 4.5.0 +Loading Additional Tables/Models +================================ .. php:method:: fetchTable(string $alias, array $config = []) @@ -463,6 +449,25 @@ the controller's default one:: ) ->all(); +.. php:method:: fetchModel(string $alias, array $config = []) + +The ``fetchModel()`` method is useful to load non ORM models or ORM tables that +are not the controller's default:: + + // ModelAwareTrait need to be explicity added to your controler first for fetchModel() to work. + use ModelAwareTrait; + + // Get an ElasticSearch model + $articles = $this->fetchModel('Articles', 'Elastic'); + + // Get a webservices model + $github = $this->fetchModel('GitHub', 'Webservice'); + + // If you skip the 2nd argument it will by default try to load a ORM table. + $authors = $this->fetchModel('Authors'); + +.. versionadded:: 4.5.0 + Paginating a Model ================== From bb8fc0dae1e6c9269997bf5a3fa6970013454ec1 Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 18 Jan 2024 19:36:06 +0530 Subject: [PATCH 153/337] Fix method signature --- en/controllers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/controllers.rst b/en/controllers.rst index 4eaf686bb7..ea73d1213a 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -449,7 +449,7 @@ the controller's default one:: ) ->all(); -.. php:method:: fetchModel(string $alias, array $config = []) +.. php:method:: fetchModel(string|null $modelClass = null, string|null $modelType = null) The ``fetchModel()`` method is useful to load non ORM models or ORM tables that are not the controller's default:: From 39ad1950be143cd2e35d1fb4f101b3c2d3aac062 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Fri, 19 Jan 2024 16:26:42 +0100 Subject: [PATCH 154/337] Update en/orm/saving-data.rst Co-authored-by: Mark Story --- en/orm/saving-data.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst index c0e0f8c1df..fe9ab20969 100644 --- a/en/orm/saving-data.rst +++ b/en/orm/saving-data.rst @@ -443,7 +443,7 @@ merge deeper to deeper levels, you can use the third parameter of the method:: // In a controller. $associated = ['Tags', 'Comments.Users']; - // or + // or using nested arrays $associated = ['Tags', 'Comments' => ['associated' => ['Users']]]; $article = $articles->get(1, ['contain' => $associated]); $articles->patchEntity($article, $this->request->getData(), [ From 030914cdab9b555327de4909f9e87cb60d8e511f Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 20 Jan 2024 21:32:27 -0500 Subject: [PATCH 155/337] Add notes to 5.1 upgrade guide for roundingMode Refs cakephp/cakephp#17552 --- en/appendices/5-1-upgrade-guide.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-upgrade-guide.rst index 29a1301776..1e13781932 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-upgrade-guide.rst @@ -65,6 +65,12 @@ Http 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. + TestSuite --------- @@ -84,3 +90,5 @@ 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. From 7d5b5fc881f13ef1125e91690c573e405be281c7 Mon Sep 17 00:00:00 2001 From: othercorey Date: Tue, 23 Jan 2024 03:51:10 -0600 Subject: [PATCH 156/337] Add notes for https://github.com/cakephp/cakephp/pull/17340 --- en/appendices/5-0-migration-guide.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index e996809d75..53b5781f75 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -56,6 +56,12 @@ 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 ------- From 9e9833e83ae37333c6d76c600ecf6587b5dd06ac Mon Sep 17 00:00:00 2001 From: Corey Taylor Date: Tue, 23 Jan 2024 23:01:16 -0600 Subject: [PATCH 157/337] Rename 5.1 upgrade guide to migration guide --- en/appendices.rst | 2 +- .../{5-1-upgrade-guide.rst => 5-1-migration-guide.rst} | 4 ++-- en/appendices/migration-guides.rst | 1 + 3 files changed, 4 insertions(+), 3 deletions(-) rename en/appendices/{5-1-upgrade-guide.rst => 5-1-migration-guide.rst} (98%) diff --git a/en/appendices.rst b/en/appendices.rst index 1897e9bc4f..903e6f29da 100644 --- a/en/appendices.rst +++ b/en/appendices.rst @@ -12,7 +12,7 @@ introduced in each version and the migration path between versions. appendices/5-0-upgrade-guide appendices/5-0-migration-guide - appendices/5-1-upgrade-guide + appendices/5-1-migration-guide Backwards Compatibility Shimming ================================ diff --git a/en/appendices/5-1-upgrade-guide.rst b/en/appendices/5-1-migration-guide.rst similarity index 98% rename from en/appendices/5-1-upgrade-guide.rst rename to en/appendices/5-1-migration-guide.rst index 1e13781932..12a65dd4f8 100644 --- a/en/appendices/5-1-upgrade-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -1,5 +1,5 @@ -5.1 Upgrade Guide -################# +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 diff --git a/en/appendices/migration-guides.rst b/en/appendices/migration-guides.rst index e7a9c98dc2..d371baf803 100644 --- a/en/appendices/migration-guides.rst +++ b/en/appendices/migration-guides.rst @@ -9,4 +9,5 @@ each version and the migration path between 4.x and 5.x. ./5-0-upgrade-guide ./5-0-migration-guide + ./5-1-migration-guide ./phpunit10 From 35365d66d53a59257252ff35a37a603c09dde605 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Wed, 24 Jan 2024 15:21:01 +0100 Subject: [PATCH 158/337] remove info about cyclic dependency problem in auto-wiring DIC feature --- en/development/dependency-injection.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst index 0fb0c40e37..132beeeefb 100644 --- a/en/development/dependency-injection.rst +++ b/en/development/dependency-injection.rst @@ -292,15 +292,11 @@ Auto Wiring is turned off by default. To enable it:: // In src/Application.php public function services(ContainerInterface $container): void { - $container->add(\Cake\Controller\ComponentRegistry::class); $container->delegate( new \League\Container\ReflectionContainer() ); } -The ``$container->add(\Cake\Controller\ComponentRegistry::class);`` is needed to -fix a cyclic dependency between ``ComponentRegistry`` and ``Controller``. - While your dependencies will now be resolved automatically, this approach will not cache resolutions which can be detrimental to performance. To enable caching:: From a27690819ff04aab2893648c79584e1b9e780f00 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 11 Feb 2024 23:07:09 -0500 Subject: [PATCH 159/337] Give the ORM docs a read through and fix old content - Use fetchTable() more - Remove references to old versions - Improve wording --- en/orm.rst | 6 ++-- en/orm/behaviors.rst | 2 +- en/orm/query-builder.rst | 25 ++------------ en/orm/retrieving-data-and-resultsets.rst | 5 ++- en/orm/saving-data.rst | 42 +++++++++++------------ en/orm/table-objects.rst | 6 ++-- en/orm/validation.rst | 4 +-- 7 files changed, 34 insertions(+), 56 deletions(-) diff --git a/en/orm.rst b/en/orm.rst index 409aa23bd1..96019ceab6 100644 --- a/en/orm.rst +++ b/en/orm.rst @@ -59,7 +59,7 @@ In other contexts, you can use the ``LocatorAwareTrait`` which add accessor meth public function someMethod() { - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); // more code. } @@ -88,7 +88,7 @@ load entities from the database we'll get instances of our new Article class:: use Cake\ORM\Locator\LocatorAwareTrait; - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $resultset = $articles->find()->all(); foreach ($resultset as $row) { @@ -113,11 +113,11 @@ More Information orm/query-builder orm/table-objects orm/entities + orm/associations orm/retrieving-data-and-resultsets orm/validation orm/saving-data orm/deleting-data - orm/associations orm/behaviors orm/schema-system console-commands/schema-cache diff --git a/en/orm/behaviors.rst b/en/orm/behaviors.rst index afe238d62f..6195c538a8 100644 --- a/en/orm/behaviors.rst +++ b/en/orm/behaviors.rst @@ -222,7 +222,7 @@ these cases you can use the ``implementedFinders`` configuration key to rename or exclude finder methods. For example if we wanted to rename our ``find(slug)`` method we could do the following:: - protected $_defaultConfig = [ + protected array $_defaultConfig = [ 'implementedFinders' => [ 'slugged' => 'findSlug', ] diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 4c0726bebf..e148f0462c 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -591,27 +591,6 @@ Also, it's possible to create the simple variant by passing a value to ``case()` # CASE published WHEN true THEN 'Y' ELSE 'N' END; -Prior to 4.3.0, you would need to use:: - - $query = $articles->find(); - $publishedCase = $query->newExpr() - ->addCase( - $query->newExpr()->add(['published' => 'Y']), - 1, - 'integer' - ); - $unpublishedCase = $query->newExpr() - ->addCase( - $query->newExpr()->add(['published' => 'N']), - 1, - 'integer' - ); - - $query->select([ - 'number_published' => $query->func()->count($publishedCase), - 'number_unpublished' => $query->func()->count($unpublishedCase) - ]); - The ``addCase`` function can also chain together multiple statements to create ``if .. then .. [elseif .. then .. ] [ .. else ]`` logic inside your SQL. @@ -1144,7 +1123,7 @@ use the ``IS`` operator to automatically create the correct expression:: $query = $categories->find() ->where(['parent_id IS' => $parentId]); -The above will create ``parent_id` = :c1`` or ``parent_id IS NULL`` depending on +The above will create ``parent_id = :c1`` or ``parent_id IS NULL`` depending on the type of ``$parentId`` Automatic IS NOT NULL Creation @@ -1156,7 +1135,7 @@ can use the ``IS NOT`` operator to automatically create the correct expression:: $query = $categories->find() ->where(['parent_id IS NOT' => $parentId]); -The above will create ``parent_id` != :c1`` or ``parent_id IS NOT NULL`` +The above will create ``parent_id != :c1`` or ``parent_id IS NOT NULL`` depending on the type of ``$parentId`` diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index 24c46a1f14..0fcece5a6e 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -19,7 +19,7 @@ be more complicated than in previous CakePHP versions. There are now various ways to inspect the data returned by the ORM. - ``debug($query)`` Shows the SQL and bound parameters, does not show results. -- ``sql($query)`` Shows the final rendered SQL, but only when having DebugKit installed. +- ``sql($query)`` Shows the final rendered SQL, but only when you have DebugKit installed. - ``debug($query->all())`` Shows the ResultSet properties (not the results). - ``debug($query->toList())`` Show results in an array. - ``debug(iterator_to_array($query))`` Shows query results in an array format. @@ -136,8 +136,7 @@ execute until you start fetching rows, convert it to an array, or when the ->contain(['Comments', 'Authors']) ->limit(10); -You can also provide many commonly used options to ``find()``. This can help -with testing as there are fewer methods to mock:: +You can also provide many commonly used options to ``find()``:: // In a controller or table method. $query = $articles->find('all', diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst index fe9ab20969..322e197678 100644 --- a/en/orm/saving-data.rst +++ b/en/orm/saving-data.rst @@ -24,7 +24,7 @@ passing it to the ``save()`` method in the ``Table`` class:: use Cake\ORM\Locator\LocatorAwareTrait; - $articlesTable = $this->getTableLocator()->get('Articles'); + $articlesTable = $this->fetchTable('Articles'); $article = $articlesTable->newEmptyEntity(); $article->title = 'A New Article'; @@ -42,7 +42,7 @@ Updating your data is achieved by using the ``save()`` method :: use Cake\ORM\Locator\LocatorAwareTrait; - $articlesTable = $this->getTableLocator()->get('Articles'); + $articlesTable = $this->fetchTable('Articles'); $article = $articlesTable->get(12); // Return article with id 12 $article->title = 'CakePHP is THE best PHP framework!'; @@ -57,7 +57,7 @@ Saving With Associations By default the ``save()`` method will also save one level of associations:: - $articlesTable = $this->getTableLocator()->get('Articles'); + $articlesTable = $this->fetchTable('Articles'); $author = $articlesTable->Authors->findByUserName('mark')->first(); $article = $articlesTable->newEmptyEntity(); @@ -130,7 +130,7 @@ one or many entities from request data. You can convert a single entity using:: // In a controller - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); // Validate and convert to an Entity object $entity = $articles->newEntity($this->request->getData()); @@ -169,7 +169,7 @@ associations should be marshalled:: // In a controller - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); // New entity with nested associations $entity = $articles->newEntity($this->request->getData(), [ @@ -183,7 +183,7 @@ should be marshalled. Alternatively, you can use dot notation for brevity:: // In a controller - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); // New entity with nested associations using dot notation $entity = $articles->newEntity($this->request->getData(), [ @@ -201,7 +201,7 @@ change the validation set to be used per association:: // In a controller - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); // Bypass validation on Tags association and // Designate 'signup' validation set for Comments.Users @@ -325,7 +325,7 @@ When creating forms that create/update multiple records at once you can use // In a controller. - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $entities = $articles->newEntities($this->request->getData()); In this situation, the request data for multiple articles should look like:: @@ -371,7 +371,7 @@ keep ids of associated entities:: // In a controller - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $entity = $articles->newEntity($this->request->getData(), [ 'associated' => [ 'Tags', 'Comments' => [ @@ -405,7 +405,7 @@ persisted. You can merge an array of raw data into an existing entity using the // In a controller. - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $article = $articles->get(1); $articles->patchEntity($article, $this->request->getData()); $articles->save($article); @@ -420,7 +420,7 @@ patching an entity, pass the ``validate`` option as follows:: // In a controller. - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $article = $articles->get(1); $articles->patchEntity($article, $data, ['validate' => false]); @@ -546,7 +546,7 @@ delete for those not in the list:: // In a controller. use Cake\Collection\Collection; - $comments = $this->getTableLocator()->get('Comments'); + $comments = $this->fetchTable('Comments'); $present = (new Collection($entity->comments))->extract('id')->filter()->toList(); $comments->deleteAll([ 'article_id' => $article->id, @@ -563,7 +563,7 @@ the original entities array will be removed and not present in the result:: // In a controller. - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $list = $articles->find('popular')->toList(); $patched = $articles->patchEntities($list, $this->request->getData()); foreach ($patched as $entity) { @@ -725,7 +725,7 @@ using ``newEntity()`` for passing into ``save()``. For example:: // In a controller - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $article = $articles->newEntity($this->request->getData()); if ($articles->save($article)) { // ... @@ -742,7 +742,7 @@ and the entity has a primary key value, an 'exists' query will be issued. The Once you've loaded some entities you'll probably want to modify them and update your database. This is a pretty simple exercise in CakePHP:: - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $article = $articles->find('all')->where(['id' => 2])->first(); $article->title = 'My new title'; @@ -859,7 +859,7 @@ the singular, :ref:`underscored ` version of the asso ], ]; - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $article = $articles->newEntity($data, [ 'associated' => ['Users'] ]); @@ -881,7 +881,7 @@ singular, :ref:`underscored ` version of the associat ], ]; - $users = $this->getTableLocator()->get('Users'); + $users = $this->fetchTable('Users'); $user = $users->newEntity($data, [ 'associated' => ['Profiles'] ]); @@ -902,7 +902,7 @@ plural, :ref:`underscored ` version of the associatio ] ]; - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $article = $articles->newEntity($data, [ 'associated' => ['Comments'] ]); @@ -954,7 +954,7 @@ the plural, :ref:`underscored ` version of the associ ] ]; - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $article = $articles->newEntity($data, [ 'associated' => ['Tags'] ]); @@ -1039,7 +1039,7 @@ The example above will only work if the property ``_joinData`` is already a reference to a Join Table Entity. If you don't already have a ``_joinData`` entity, you can create one using ``newEntity()``:: - $coursesMembershipsTable = $this->getTableLocator()->get('CoursesMemberships'); + $coursesMembershipsTable = $this->fetchTable('CoursesMemberships'); $student->courses[0]->_joinData = $coursesMembershipsTable->newEntity([ 'grade' => 80.12, 'days_attended' => 30 @@ -1217,7 +1217,7 @@ be an array of entities created using ``newEntities()`` / ``patchEntities()``. ], ]; - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); $entities = $articles->newEntities($data); $result = $articles->saveMany($entities); diff --git a/en/orm/table-objects.rst b/en/orm/table-objects.rst index 1cd834eebd..082c36dfe7 100644 --- a/en/orm/table-objects.rst +++ b/en/orm/table-objects.rst @@ -96,7 +96,7 @@ can do this by using the ``TableLocator`` class:: // In a controller - $articles = $this->getTableLocator()->get('Articles'); + $articles = $this->fetchTable('Articles'); ``TableLocator`` provides the various dependencies for constructing a table, and maintains a registry of all the constructed table instances making @@ -109,10 +109,10 @@ being triggered as a default class is used instead of your actual class. To correctly load plugin table classes use the following:: // Plugin table - $articlesTable = $this->getTableLocator()->get('PluginName.Articles'); + $articlesTable = $this->fetchTable('PluginName.Articles'); // Vendor prefixed plugin table - $articlesTable = $this->getTableLocator()->get('VendorName/PluginName.Articles'); + $articlesTable = $this->fetchTable('VendorName/PluginName.Articles'); .. _table-callbacks: diff --git a/en/orm/validation.rst b/en/orm/validation.rst index ecf5d21819..4b89481870 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -269,14 +269,14 @@ network. These types of rules are often referred to as 'domain rules' or 'application rules'. CakePHP exposes this concept through 'RulesCheckers' which are applied -before entities are persisted. Some example domain rules are: +before entities are persisted. Some example application rules are: * Ensuring email uniqueness * State transitions or workflow steps, for example, updating an invoice's status. * Preventing the modification of soft deleted items. * Enforcing usage/rate limit caps. -Domain rules are checked when calling the Table ``save()`` and ``delete()`` methods. +Application rules are checked when calling the Table ``save()`` and ``delete()`` methods. .. _creating-a-rules-checker: From 8a1182a7add11ce14a20a4e498f8b43f21ee06b3 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 11 Feb 2024 23:07:47 -0500 Subject: [PATCH 160/337] Disable contents entries in TOC --- config/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/config/conf.py b/config/conf.py index 87cad35de4..4a0bb878a1 100644 --- a/config/conf.py +++ b/config/conf.py @@ -117,3 +117,7 @@ """ # todo_include_todos = True + +# turn off contents entries for classes/functions +# generally we add titles for methods and classes instead. +toc_object_entries = False From 96efa5f54a934c2df6eae4775b719f3184321ae3 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 12 Feb 2024 07:02:06 -0800 Subject: [PATCH 161/337] Apply suggestions from code review Co-authored-by: othercorey --- en/orm/query-builder.rst | 4 ++-- en/orm/retrieving-data-and-resultsets.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index e148f0462c..74c55a8f0f 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -1123,7 +1123,7 @@ use the ``IS`` operator to automatically create the correct expression:: $query = $categories->find() ->where(['parent_id IS' => $parentId]); -The above will create ``parent_id = :c1`` or ``parent_id IS NULL`` depending on +The above will generate``parent_id = :c1`` or ``parent_id IS NULL`` depending on the type of ``$parentId`` Automatic IS NOT NULL Creation @@ -1135,7 +1135,7 @@ can use the ``IS NOT`` operator to automatically create the correct expression:: $query = $categories->find() ->where(['parent_id IS NOT' => $parentId]); -The above will create ``parent_id != :c1`` or ``parent_id IS NOT NULL`` +The above will generate``parent_id != :c1`` or ``parent_id IS NOT NULL`` depending on the type of ``$parentId`` diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index 0fcece5a6e..1bb8bf0b95 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -19,7 +19,7 @@ be more complicated than in previous CakePHP versions. There are now various ways to inspect the data returned by the ORM. - ``debug($query)`` Shows the SQL and bound parameters, does not show results. -- ``sql($query)`` Shows the final rendered SQL, but only when you have DebugKit installed. +- ``sql($query)`` Shows the final rendered SQL when DebugKit is installed. - ``debug($query->all())`` Shows the ResultSet properties (not the results). - ``debug($query->toList())`` Show results in an array. - ``debug(iterator_to_array($query))`` Shows query results in an array format. From fde5ed955a79b97cfb3cabcec51c6f95883916b2 Mon Sep 17 00:00:00 2001 From: Oliver Nowak Date: Tue, 20 Feb 2024 00:40:36 +0100 Subject: [PATCH 162/337] Add Sqlite min version requirement --- en/appendices/5-0-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 53b5781f75..0d4ccde413 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -42,7 +42,7 @@ Global - MariaDB (10.1 or higher) - PostgreSQL (9.6 or higher) - Microsoft SQL Server (2012 or higher) - - SQLite 3 + - SQLite 3 (3.16 or higher) Auth ---- From 02bcb6e28c0736e1a5c09fe5e776766165873381 Mon Sep 17 00:00:00 2001 From: mscherer Date: Wed, 21 Feb 2024 23:03:28 +0100 Subject: [PATCH 163/337] Docs for autoLinkUrls() maxLength --- en/appendices/5-1-migration-guide.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 12a65dd4f8..ce00978760 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -14,6 +14,8 @@ Behavior Changes are using ``aria-required`` attribute in styling or scripting you'll need to update your application. +- Text Utility and TextHelper methods around truncation and maximum length are using + a UTF-8 character for ``ellipsis`` instead of ``...`` legacy characters. Deprecations ============ @@ -92,3 +94,11 @@ View ``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. From d2399ea6782f97761b31b583ca765cd0eafa5ce0 Mon Sep 17 00:00:00 2001 From: mscherer Date: Thu, 22 Feb 2024 17:59:30 +0100 Subject: [PATCH 164/337] Docs for autoLinkUrls() maxLength --- en/views/helpers/text.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/en/views/helpers/text.rst b/en/views/helpers/text.rst index 145c62c3c0..65164826ee 100644 --- a/en/views/helpers/text.rst +++ b/en/views/helpers/text.rst @@ -56,6 +56,11 @@ are linked appropriately given the supplied ``$options``. This method automatically escapes its input. Use the ``escape`` option to disable this if necessary. +Further options: + * ``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. + Converting Text into Paragraphs =============================== From fdcdf383956a0e9ba62140e16b296a863b067f43 Mon Sep 17 00:00:00 2001 From: Mark Scherer Date: Thu, 22 Feb 2024 22:13:26 +0100 Subject: [PATCH 165/337] Update text.rst --- en/views/helpers/text.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/views/helpers/text.rst b/en/views/helpers/text.rst index 65164826ee..5c2a7f6872 100644 --- a/en/views/helpers/text.rst +++ b/en/views/helpers/text.rst @@ -57,7 +57,7 @@ This method automatically escapes its input. Use the ``escape`` option to disable this if necessary. Further options: - * ``stripProtocol``: Strips ``http://`` and ``https://`` from the beginning of the link. Default off. + * ``stripProtocol``: Strips ``http://`` and ``https://`` from the beginning of the link label. 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. From b7ba8e838f9c4a5676ff60ec963fa51fbf3fe063 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 22 Feb 2024 17:48:15 -0500 Subject: [PATCH 166/337] Fix formatting --- en/views/helpers/text.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/en/views/helpers/text.rst b/en/views/helpers/text.rst index 5c2a7f6872..08f73f5362 100644 --- a/en/views/helpers/text.rst +++ b/en/views/helpers/text.rst @@ -57,9 +57,12 @@ This method automatically escapes its input. Use the ``escape`` option to disable this if necessary. Further options: - * ``stripProtocol``: Strips ``http://`` and ``https://`` from the beginning of the link label. 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. + +* ``stripProtocol``: Strips ``http://`` and ``https://`` from the beginning of + the link label. 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 ellipsis. Converting Text into Paragraphs =============================== From 9bdb9754f180c91345d558a9d4a20a15fc05270a Mon Sep 17 00:00:00 2001 From: Tadahisa MOTO-OKA Date: Fri, 1 Mar 2024 18:01:15 +0900 Subject: [PATCH 167/337] (WIP) add Japanese translation to CakePHP 5.x migration guide --- ja/appendices/5-0-migration-guide.rst | 411 ++++++++++++++++++++++++++ ja/appendices/5-0-upgrade-guide.rst | 74 +++++ ja/appendices/migration-guides.rst | 11 +- ja/appendices/phpunit10.rst | 65 ++++ 4 files changed, 554 insertions(+), 7 deletions(-) create mode 100644 ja/appendices/5-0-migration-guide.rst create mode 100644 ja/appendices/5-0-upgrade-guide.rst create mode 100644 ja/appendices/phpunit10.rst diff --git a/ja/appendices/5-0-migration-guide.rst b/ja/appendices/5-0-migration-guide.rst new file mode 100644 index 0000000000..473674c717 --- /dev/null +++ b/ja/appendices/5-0-migration-guide.rst @@ -0,0 +1,411 @@ +5.0 移行ガイド +################### + +CakePHP 5.0 には、破壊的な変更が含まれており、4.x リリースとの後方互換性はありません。 +5.0 にアップグレードする前に、最初に 4.5 にアップグレードし、すべての非推奨警告を解消してください。 + +5.0 にアップグレードする方法の段階的な手順については、 +:doc:`/appendices/5-0-upgrade-guide` を参照してください。 + +非推奨機能の削除 +=========================== + +4.5 で非推奨の警告を発していたすべてのメソッド、プロパティと機能が削除されました。 + + +破壊的変更 +================ + +非推奨機能の削除に加えて、破壊的変更が行われました。 + +全体 +------ + +- 全ての関数について、可能な限り、引数や返り値の型が明示されるようになりました。DockBlockに書かれた注釈(annotation)に合致するように意図しましたが、DockBlock側を修正した箇所もあります。 +- クラスのpropertyについても同様に型が可能な限り明示されるようになりました。こちらでも注釈を修正した箇所もあります。 +- 次の定数が削除されました : ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``, ``WEEK``, ``MONTH``, ``YEAR`` +- 全ての ``#[\AllowDynamicProperties]`` 指定が削除されました。これは以下のクラスで使用されていました。 + - ``Command/Command`` + - ``Console/Shell`` + - ``Controller/Component`` + - ``Controller/Controller`` + - ``Mailer/Mailer`` + - ``View/Cell`` + - ``View/Helper`` + - ``View/View`` +- サポート対象のデータベースエンジンのバージョンが更新されました。 + - MySQL (5.7 以上) + - MariaDB (10.1 以上) + - PostgreSQL (9.6 以上) + - Microsoft SQL Server (2012 以上) + - SQLite 3 (3.16 以上) + +Auth +---- + +- `Auth` は削除されました。代わりにプラグイン `cakephp/authentication `__ および + `cakephp/authorization `__ をお使い下さい。 + +Cache +----- + +- ``Wincache`` エンジンは削除されました。wincache拡張は PHP 8 ではサポートされていないため、です。 + +Collection +---------- + +- `combine()` は、指定した key path や group path が存在しないまたは null 値の場合に、例外を投げるようになりました。 + この挙動は、 `indexBy()` や `groupBy()` と同じです。 + +Console +------- + +- ``BaseCommand::__construct()`` は削除されました。 +- ``ConsoleIntegrationTestTrait::useCommandRunner()`` は、もはや必要無いため削除されました。 +- ``Shell`` は削除されました。代わりに `Command `__ をお使い下さい。 +- ``BaseCommand`` は ``execute()`` メソッドがフレームワークから呼び出される前後に ``Command.beforeExecute`` および + ``Command.afterExecute`` のイベントを発行するようになりました。 + +Connection +---------- + +- ``Connection::prepare()`` は削除されました。これは、SQL文、パラメータ、パラメータ型の情報を渡すことで ``Connection::execute()`` の1回の呼び出しに置き換えることができます。 +- ``Connection::enableQueryLogging()`` は削除されました。データベース接続設定においてロギングを有効にしていない場合、 ``$connection->getDriver()->setLogger()`` を呼び出して logger インスタンスを設定することにより、後からロギングを有効にできます。 + +Controller +---------- + +- ``Controller::__construct()`` は削除されました。サブクラスでoverrideしていた場合は、コードの調整をお願いします。 +- Component は、 Controller の読み込み後に dynamic property として設定されることは無くなりました。代わりに Controller は ``__get()`` を用いて Component へのアクセスを提供します。この変更は、 Component の存在有無を ``property_exists()`` でチェックしているアプリケーションに影響を与えます。 +- 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::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/ja/appendices/5-0-upgrade-guide.rst b/ja/appendices/5-0-upgrade-guide.rst new file mode 100644 index 0000000000..5f34ec911c --- /dev/null +++ b/ja/appendices/5-0-upgrade-guide.rst @@ -0,0 +1,74 @@ +5.0 Upgrade Guide +################# + +First, check that your application is running on latest CakePHP 4.x version. + +Fix Deprecation Warnings +======================== + +Once your application is running on latest CakePHP 4.x, enable deprecation warnings in **config/app.php**:: + + 'Error' => [ + 'errorLevel' => E_ALL, + ] + +Now that you can see all the warnings, make sure these are fixed before proceeding with the upgrade. + +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. + +Upgrade to PHP 8.1 +================== + +If you are not running on **PHP 8.1 or higher**, you will need to upgrade PHP before updating CakePHP. + +.. note:: + CakePHP 5.0 requires **a minimum of PHP 8.1**. + +.. _upgrade-tool-use: + +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. + +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: + +.. code-block:: console + + # Install the upgrade tool + git clone https://github.com/cakephp/upgrade + cd upgrade + git checkout 5.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 + +Update CakePHP Dependency +========================= + +After applying rector refactorings you need to upgrade CakePHP, its plugins, PHPUnit +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. + +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/ja/appendices/migration-guides.rst b/ja/appendices/migration-guides.rst index 0f27158620..73d3fdba32 100644 --- a/ja/appendices/migration-guides.rst +++ b/ja/appendices/migration-guides.rst @@ -1,14 +1,11 @@ 移行ガイド ################ -移行ガイドは、各バージョンで導入された新機能に関する情報と、3.x と 4.x の間の移行手順を解説します。 +移行ガイドは、各バージョンで導入された新機能に関する情報と、4.x から 5.x への移行手順を解説します。 .. toctree:: :maxdepth: 1 - ./4-0-upgrade-guide - ./4-0-migration-guide - ./4-1-migration-guide - ./4-2-migration-guide - ./4-3-migration-guide - ./4-4-migration-guide + ./5-0-upgrade-guide + ./5-0-migration-guide + ./phpunit10 diff --git a/ja/appendices/phpunit10.rst b/ja/appendices/phpunit10.rst new file mode 100644 index 0000000000..ff93663740 --- /dev/null +++ b/ja/appendices/phpunit10.rst @@ -0,0 +1,65 @@ +PHPUnit 10 Upgrade +################## + +With CakePHP 5 the minimum PHPUnit version has changed from ``^8.5 || ^9.3`` to ``^10.1``. +This introduces a few breaking changes from PHPUnit as well as from CakePHP's side. + +phpunit.xml adjustments +======================= + +It is recommended to let PHPUnit update its configuration file via the following command:: + + vendor/bin/phpunit --migrate-configuration + +.. note:: + + Make sure you are already on PHPUnit 10 via ``vendor/bin/phpunit --version`` before executing this command! + +With this command out of the way your ``phpunit.xml`` already has most of the recommended changes present. + +New event system +---------------- + +PHPUnit 10 removed the old hook system and introduced a new `Event system +`_ +which requires the following code in your ``phpunit.xml`` to be adjusted from:: + + + + + +to:: + + + + + +``->withConsecutive()`` has been removed +======================================== + +You can convert the removed ``->withConsecutive()`` method to a +working interim solution like you can see here:: + + ->withConsecutive(['firstCallArg'], ['secondCallArg']) + +should be converted to:: + + ->with( + ...self::withConsecutive(['firstCallArg'], ['secondCallArg']) + ) + +the static ``self::withConsecutive()`` method has been added via the ``Cake\TestSuite\PHPUnitConsecutiveTrait`` +to the base ``Cake\TestSuite\TestCase`` class so you don't have to manually add that trait to your Testcase classes. + +data providers have to be static +================================ + +If your testcases leverage the data provider feature of PHPUnit then +you have to adjust your data providers to be static:: + + public function myProvider(): array + +should be converted to:: + + public static function myProvider(): array + From f18a78fd9ac100a4aa4aa7b63f61ecc4ebb8f7d5 Mon Sep 17 00:00:00 2001 From: Tadahisa MOTO-OKA Date: Fri, 1 Mar 2024 19:46:27 +0900 Subject: [PATCH 168/337] fix missing link and delete unnecessary files --- ja/appendices.rst | 11 +- ja/appendices/4-0-migration-guide.rst | 472 -------------------------- ja/appendices/4-0-upgrade-guide.rst | 107 ------ ja/appendices/4-1-migration-guide.rst | 274 --------------- ja/appendices/4-2-migration-guide.rst | 204 ----------- ja/appendices/4-3-migration-guide.rst | 321 ------------------ ja/appendices/4-4-migration-guide.rst | 218 ------------ ja/appendices/5-0-migration-guide.rst | 2 +- ja/appendices/fixture-upgrade.rst | 143 -------- ja/plugins.rst | 4 + 10 files changed, 9 insertions(+), 1747 deletions(-) delete mode 100644 ja/appendices/4-0-migration-guide.rst delete mode 100644 ja/appendices/4-0-upgrade-guide.rst delete mode 100644 ja/appendices/4-1-migration-guide.rst delete mode 100644 ja/appendices/4-2-migration-guide.rst delete mode 100644 ja/appendices/4-3-migration-guide.rst delete mode 100644 ja/appendices/4-4-migration-guide.rst delete mode 100644 ja/appendices/fixture-upgrade.rst diff --git a/ja/appendices.rst b/ja/appendices.rst index 045d876a56..186c7c2380 100644 --- a/ja/appendices.rst +++ b/ja/appendices.rst @@ -4,22 +4,19 @@ ここでは、各バージョンで導入された新機能に関する情報と、 バージョン間の移行手順を解説します。 -4.x 移行ガイド +5.x 移行ガイド ============== .. toctree:: :maxdepth: 1 - appendices/4-0-migration-guide - appendices/4-1-migration-guide - appendices/4-2-migration-guide - appendices/4-3-migration-guide - appendices/fixture-upgrade + appendices/5-0-upgrade-guide + appendices/5-0-migration-guide 後方互換性の補完 ================ -3.x の挙動に関する対応が必要な場合、または段階的な移行に関する助けが必要な場合、 +4.x の挙動に関する対応が必要な場合、または段階的な移行に関する助けが必要な場合、 `Shim プラグイン `__ を確認してください。 後方互換性を損なう変更を移行するのに役立ちます。 diff --git a/ja/appendices/4-0-migration-guide.rst b/ja/appendices/4-0-migration-guide.rst deleted file mode 100644 index 028b28beaa..0000000000 --- a/ja/appendices/4-0-migration-guide.rst +++ /dev/null @@ -1,472 +0,0 @@ -4.0 移行ガイド -############## - -CakePHP 4.0 には、重大な変更が含まれており、3.x リリースとの後方互換性はありません。 -4.0 にアップグレードする前に、最初に 3.8 にアップグレードし、すべての非推奨警告を解消してください。 - -4.0 にアップグレードする方法の段階的な手順については、 -:doc:`/appendices/4-0-upgrade-guide` を参照してください。 - -非推奨機能の削除 -================ - -3.8 から非推奨の警告を発していたすべてのメソッド、プロパティと機能が削除されました。 - -認証機能がスタンドアロンのプラグイン `Authentication -`__ および -`Authorization `__ に分割されました。 -以前の RssHelper については、同様の機能を持つスタンドアロンの `Feed plugin -`__ をご覧ください。 - -非推奨 -====== - -以下は、非推奨メソッド、プロパティと動作の一覧です。 -これらの機能は、 4.x でも引き続き機能し、 5.0.0 で削除されます。 - -Component ---------- - -* ``AuthComponent`` および関連するクラスは廃止され、 5.0.0 で削除されます。代わりに、 - 上記の認証および認可ライブラリを使用する必要があります。 -* ``SecurityComponent`` は非推奨です。代わりに、フォーム改ざん保護のためには ``FormProtectionComponent`` を使用し、 - ``requireSecure`` 機能のためには :ref:`https-enforcer-middleware` を使用してください。 - -Filesystem ----------- - -* このパッケージは非推奨であり、 5.0 で削除されます。多くの設計上の問題があり、そして、 - すでに多くの素晴らしいパッケージが存在する場合、この頻繁に使用されるパッケージを修正することに - 努力する価値はありません。 - -ORM ---- - -* ``Entity::isNew()`` をセッターとして使うことは非推奨です。代わりに ``setNew()`` を使用してください。 -* ``Entity::unsetProperty()`` は、他のメソッドに合わせて ``Entity::unset()`` に名前が変更されました。 -* ``TableSchemaInterface::primaryKey()`` は ``TableSchemaInterface::getPrimaryKey()`` - に名前が変更されました。 - -View ----- - -* ``JsonView`` の特別なビュー変数 ``_serialize`` 、 ``_jsonOptions`` および ``_jsonp`` は非推奨になりました。 - 代わりに、 ``viewBuilder()->setOption($optionName, $optionValue)`` を、それらのオプションを設定するために使用してください。 -* ``XmlView`` の特別なビュー変数 ``_serialize`` 、 ``_rootNode`` および ``_xmlOptions`` は非推奨になりました。 - 代わりに、 ``viewBuilder()->setOption($optionName, $optionValue)`` を、それらのオプションを設定するために使用してください。 -* ``HtmlHelper::tableHeaders()`` は、ネストされたリストとして定義される属性を持つヘッダーセルを優先するようになりました。 - 例: ``['Title', ['class' => 'special']]`` -* ``ContextInterface::primaryKey()`` は ``ContextInterface::getPrimaryKey()`` に名前が変更されました。 - -Mailer ------- - -* ``Cake\Mailer\Email`` クラスは非推奨になります。代わりに、 ``Cake\Mailer\Mailer`` を使用してください。 - -App ---- - -* ``App::path()`` はクラスパスでは非推奨になりました。 - 代わりに ``\Cake\Core\App::classPath()`` を使用してください。 - -破壊的変更 -========== - -非推奨機能の削除に加えて、破壊的変更が行われました。 - -Cache ------ - -* ``Cake\Cache\CacheEngine::gc()`` と、このメソッドのすべての実装が削除されました。 - このメソッドは、ほとんどのキャッシュドライバーでノーオペレーションであり、ファイルキャッシュでのみ使用されていました。 - -Controller ----------- - -* ``Cake\Controller\Controller::referer()`` は、デフォルトで ``local`` パラメーターを、 - false ではなく true に設定します。 - これにより、デフォルトでアプリケーションのドメインに制限されるため、リファラルヘッダーの使用がより安全になります。 -* アクションの呼び出し時のコントローラーメソッド名のマッチングで、大文字と小文字が区別されるようになりました。 - たとえば、コントローラーメソッドが ``forgotPassword()`` の場合、 URL で文字列 ``forgotpassword`` - を使用すると、アクション名としてマッチしません。 - -Console -------- - -* ``ConsoleIo::styles()`` は ``getStyle()`` および ``setStyle()`` に分割されました。これは ``ConsoleOutput`` にも影響します。 - -Component ---------- - -* ``Cake\Controller\Component\RequestHandlerComponent`` は、リクエストパラメーターではなくリクエスト属性として、 - ``isAjax`` を設定するようになりました。したがって、 ``$request->getParam('isAjax')`` の代わりに - ``$request->getAttribute('isAjax')`` を使用する必要があります。 -* ``RequestHandlerComponent`` の入力データ解析機能は削除され。 - 代わりに、 :ref:`body-parser-middleware` を使用する必要があります。 -* ``Cake\Controller\Component\PaginatorComponent`` は、リクエストパラメーターではなくリクエスト属性として、 - ページングパラメーター情報を設定するようになりました。したがって、 ``$request->getParam('paging')`` の代わりに、 - ``$request->getAttribute('paging')`` を使用する必要があります。 - -Database --------- - -* ``Cake\Database\TypeInterface`` の型マッピングクラスは ``Type`` を継承しなくなり、 - ``BatchCastingInterface`` 機能を活用します。 -* ``Cake\Database\Type::map()`` は、セッターとしてのみ機能します。 - 型インスタンスを検査するには ``Type::getMap()`` を使用する必要があります。 -* Date 、 Time 、 Timestamp および Datetime カラムタイプは、デフォルトで不変の時刻オブジェクトを返すようになりました。 -* ``BoolType`` は、空でない文字列値を ``true`` にマーシャリングしたり、空文字列を - ``false`` にマーシャリングしなくなりました。代わりに、非ブール文字列値は ``null`` に変換されます。 -* ``DecimalType`` は、浮動小数ではなく文字列を使用して 10 進数値を表すようになりました。 - 浮動小数を使用することで、精度が低下していました。 -* ``JsonType`` は、データベースコンテキストの値を準備するときに ``null`` を保持するようになりました。 - 3.x では、 ``'null'`` を出力します。 -* ``StringType`` は、配列値を、空文字列の代わりに ``null`` にマーシャリングします。 -* ``Cake\Database\Connection::setLogger()`` は ロギングを無効化するために ``null`` を受け入れなくなりました。 - 代わりに、 ``Psr\Log\NullLogger`` のインスタンスを渡して、ロギングを無効にします。 -* ``Database\Log\LoggingStatement`` 、 ``Database\QueryLogger`` および ``Database\Log\LoggedQuery`` - の内部実装が変更されました。これらのクラスを拡張する場合は、コードを更新する必要があります。 -* ``Cake\Database\Log\LoggingStatement`` 、 ``Cake\Database\QueryLogger`` および ``Cake\Database\Log\LoggedQuery`` - の内部実装が変更されました。これらのクラスを拡張する場合は、コードを更新する必要があります。 -* ``Cake\Database\Schema\CacheCollection`` および ``Cake\Database\SchemaCache`` の内部実装が変更されました。 - これらのクラスを拡張する場合は、コードを更新する必要があります。 -* データべーススキーマは、 ``CHAR`` カラムを ``string`` ではなく、新しい ``char`` 型にマッピングするようになりました。 -* SqlServer の datetime カラムは、名前を一致させるために 'timestamp' ではなく 'datetime' - 型にマップされるようになりました。 -* MySQL 、 PostgreSQL および SqlServer のデータベーススキーマは、少数秒をサポートするカラムを、 - 新しい抽象少数型にマップするようになりました。 - - * **MySQL** - - #. ``DATETIME(1-6)`` => ``datetimefractional`` - #. ``TIMESTAMP(1-6)`` => ``timestampfractional`` - - * **PostgreSQL** - - #. ``TIMESTAMP`` => ``timestampfractional`` - #. ``TIMESTAMP(1-6)`` => ``timestampfractional`` - - * **SqlServer** - - #. ``DATETIME2`` => ``datetimefractional`` - #. ``DATETIME2(1-7) => ``datetimefractional`` - -* PostgreSQL のスキーマは、タイムゾーンをサポートするカラムを、新しい抽象タイムゾーン型にマップするようになりました。 - (0) 精度を指定しても、上記の通常の分数型の場合のように、型マッピングは変更されません。 - - * **PostgreSQL** - - #. ``TIMESTAMPTZ`` => ``timestamptimezone`` - #. ``TIMESTAMPTZ(0-6)`` => ``timestamptimezone`` - #. ``TIMESTAMP WITH TIME ZONE`` => ``timestamptimezone`` - #. ``TIMESTAMP(0-6) WITH TIME ZONE`` => ``timestamptimezone`` - -Datasources ------------ - -* ``ModelAwareTrait::$modelClass`` は protected になりました。 - -Error ------ - -* エラーハンドラークラス ``BaseErrorHandler`` 、 ``ErrorHandler`` および ``ConsoleErrorHandler`` の内部が変更されました。 - これらのクラスを拡張した場合は、それに応じて更新する必要があります。 -* ``ErrorHandlerMiddleware`` は、例外レンダラークラス名またはインスタンスではなく、 - コンストラクター引数として、エラーハンドラークラス名またはインスタンスを受け取るようになりました。 - -Event ------ - -* 件名のないイベントで ``getSubject()`` を呼び出すと、例外が発生するようになりました。 - -Http ----- - -* ``Cake\Http\ServerRequest::referer()`` は、デフォルトで ``local`` パラメーターを false ではなく true に設定します。 - これにより、リファラーヘッダーはデフォルトでアプリケーションのドメインに制限されるため、リファラーヘッダーの使用がより安全になります。 -* パラメーターが欠落している場合の ``Cake\Http\ServerRequest::getParam()`` のデフォルト値は、 - ``false`` ではなく ``null`` になりました。 -* ``Cake\Http\Client\Request::body()`` は削除されました。代わりに、 ``getBody()`` か ``withBody()`` を使用してください。 -* ``Cake\Http\Client\Response::isOk()`` は、すべての 2xx および 3xx レスポンスコードに対して、 ``true`` を返すようになりました。 -* ``Cake\Http\Cookie\Cookie::getExpiresTimestamp()`` は、数値を返すようになりました。 - これにより、 ``setcookie()`` で使用されているものと型が一致します。 -* ``Cake\Http\ServerRequest::referer()`` は、現在のリクエストにリファラーがない場合、 ``null`` を返すようになりました。 - 以前は、 ``/`` を返していました。 -* ``Cake\Cookie\CookieCollection::get()`` は、存在しないクッキーにアクセスすると、例外を返すようになりました。 - クッキーの存在をチェックするために ``has()`` を使用してください。 -* ``Cake\Http\ResponseEmitter::emit()`` のシグネチャが変更され、 2 番目の引数がなくなりました。 -* ``App.mergeFilesAsObjects`` のデフォルト値は ``true`` になりました。アプリケーションがファイルアップロードを使用する場合、 - このフラグを ``false`` に設定することで、 3.x の動作との互換性を維持できます。 -* ``Cake\Http\Response::getCookie()`` によって返される配列キーが変更されました。 - ``expire`` が ``expires`` に、 ``httpOnly`` が ``httponly`` に変わりました。 - -Http\Session ------------- - -* セッションクッキー名は、デフォルトで ``CAKEPHP`` に設定されなくなりました。代わりに、 ``php.ini`` ファイルで定義された、 - デフォルトのクッキー名が使用されます。``Session.cookie`` 設定オプションを使用してクッキー名を設定できます。 -* セッションクッキーは、デフォルトで ``SameSite`` 属性が ``Lax`` に設定されるようになります。 - 詳細については、 :ref:`session-configuration` セクションを確認してください。 - -I18n ----- - -* ``Cake\I18n\Date`` や ``Cake\I18n\FrozenDate`` オブジェクトを JSON エンコードすると、 - 以前の形式 ``yyyy-MM-dd'T'HH:mm:ssxxx`` ではなく、 ``yyyy-MM-dd`` 形式で - 日付部分のみの文字列が生成されるようになりました。 - -Mailer ------- - -* ``Email::set()`` は削除されました。代わりに ``Email::setViewVars()`` を使用してください。 -* ``Email::createView()`` は削除されました。 -* ``Email::viewOptions()`` は削除されました。代わりに - ``$email->getRenderer()->viewBuilder()->setOption()`` を使用してください。 - -ORM ---- - -* ``Table::newEntity()`` は、入力として配列を必要とし、検証が実行されずに偶発的な保存がされることを防ぐために、 - 検証を実施します。つまり、入力無しでエンティティーを作成するには、 ``Table::newEmptyEntity()`` を使用する必要があります。 -* ``Query::where()`` に ``['name' => null]`` のような条件を使用すると、例外が発生します。 - 3.x では、 SQL の ``name = NULL`` のような条件のSQLを生成していましたが、これは常に 0 行と一致するため、誤った結果を返します。 - ``null`` と比較するときは、 ``['name IS' => null]`` のような ``IS`` 演算子を使用する必要があります。 -* false ではなく、エンティティーではない結果で、 ``Model.beforeSave`` イベントを停止すると、例外が発生します。 - この変更により、 ``Table::save()`` は常にエンティティーまたは false を返します。 -* テーブルクラスは、テーブル名とカラム名のエイリアスがデータベースによって切り捨てられた場合に、例外を投げるようになりました。 - これは実際のエイリアスが一致しない場合、隠れたエラーが発生する前に警告を発するものです。 -* ``TableLocator::get()`` および ``TableRegistry::get()`` は常に **CamelCase** 形式のエイリアスを期待するようになりました。 - 予期せぬ形式のエイリアスが渡された場合、テーブルやエンティティクラスが正しくロードされません。 -* ``IsUnique`` ルールはデフォルトで有効になっていた ``allowMultipleNulls`` オプションを受け付けなくなりました。 - このオプションは 4.2 で再度追加されましたが、デフォルトでは無効になっています。 - -Router ------- - -* ``Router::prefix()`` および ``$routes->prefix()`` で生成されたルーティングプレフィックスは、 - アンダースコアーではなく、キャメルケースになりました。``my_admin`` の代わりに、 ``MyAdmin`` を使用する必要があります。 - この変更により、プレフィックスが他のルーティングパラメーターで正規化され、語尾変化のオーバーヘッドが削除されます。 -* ``RouteBuilder::resources()`` は、 URL 内のリソース名をデフォルトではアンダースコア形式の代わりにダッシュ形式で変換するようになりました。 - ``$options`` 引数で、 ``'inflect' => 'underscore'`` を使用することで、アンダースコア形式での変換を保持できます。 -* ``Router::plugin()`` および ``Router::prefix()`` は、デフォルトで URL のダッシュ形式のプラグイン/プレフィックス名を - 使用するようになりました。``$options`` 引数で、 ``'path'`` キーを使用して、下線（または他のカスタムパス）を保持できます。 -* ``Router`` は、リクエストのスタックではなく、リクエストの単一インスタンスのみへの参照を維持します。 - ``Router::pushRequest()`` 、 ``Router::setRequestInfo()`` および ``Router::setRequestContext()`` は削除されました。 - 代わりに、 ``Router::setRequest()`` を使用してください。 - ``Router::popRequest()`` は削除されました。``Router::getRequest()`` には、 ``$current`` 引数がなくなりました。 - -TestSuite ---------- - -* ``Cake\TestSuite\TestCase::$fixtures`` は、コンマ区切りの文字列にすることができなくなりました。配列でなければなりません。 - -Utility -------- - -* ``Cake\Utility\Xml::fromArray()`` は ``$options`` パラメーターの配列を必要とします。 -* ``Cake\Filesystem\Folder::copy($to, array $options = [])`` および - ``Cake\Filesystem\Folder::move($to, array $options = [])`` には、 - 最初の引数として抽出されたターゲットパスがあります。 -* ``Xml::build()`` の ``readFile`` オプションは、デフォルトで true ではなくなりました。 - 代わりに、ローカルファイルを読み取るために、 ``readFile`` を有効にする必要があります。 -* ``Hash::sort()`` は、方向パラメーターで ``SORT_ASC`` および ``SORT_DESC`` 定数を受け入れるようになりました。 -* ``Inflector::pluralize()`` は ``index`` を ``indices`` ではなく ``indexes`` に反映するようになりました。 - これは、この複数形のコアおよびエコシステムでの技術的な使用を反映しています。 - -View ----- - -* テンプレートは、 app や plugin ルート上の ``src/Template/`` から ``templates/`` フォルダーへ移動されました。 - この変更により、 ``src`` フォルダーには、 composer のオートローダーを介して - オートロードされるクラスを持つファイルのみが含まれるようになりました。 -* ``Cell`` 、 ``Element`` 、 ``Email`` および ``Plugin`` といった特別なテンプレートフォルダーは、 - それぞれ小文字の ``cell`` 、 ``element`` 、 ``email`` および ``plugin`` に名前が変更されました。 - これにより、特別なフォルダーとアプリケーションのコントローラー名に対応する ``CamelCase`` 形式のフォルダーを - 視覚的に区別しやすくなります。 -* テンプレートの拡張子も、 ``.ctp`` から ``.php`` に変更されました。 - 特別な拡張子は、実際の利点を提供せず、代わりに、 ``.ctp`` 拡張子を持つファイルを PHP ファイルとして認識するように - エディターや IDE を設定する必要がありました。 -* ``ViewBuilder::setLayout()`` または ``View::setLayout()`` の引数として ``false`` を使用して、 - ``View::$layout`` プロパティを ``false`` に設定することはできなくなりました。 - 代わりに、 ``ViewBuilder::disableAutoLayout()`` や ``View::disableAutoLayout()`` を使用して、 - レイアウトなしでビューテンプレートを描画します。 -* ``Cake\View\View`` は、 ``render()`` が複数回呼び出された場合、 ``null`` を返す代わりに再描画します。 -* 定数 ``View::NAME_ELEMENT`` と ``View::NAME_LAYOUT`` は削除されました。 - ``View::TYPE_ELEMENT`` と ``View::TYPE_LAYOUT`` が使用できます。 - -Helper ------- - -* ``Cake\View\Helper\PaginatorHelper::hasPage()`` の引数が逆になっています。 - これにより、 'model' が第 2 引数である他のページネーターメソッドとの一貫性が保たれます。 -* ``Cake\View\Helper\UrlHelper::build()`` は第 2 引数にブール値を受け入れなくなりました。 - 代わりに、 ``['fullBase' => true]`` を使用しなければなりません。 -* コンテキスト無しでフォームを作成するには、 ``FormHelper::create()`` の最初の引数として、 - ``null`` のみを使用する必要があります。コンテキストを推測できない他の値を渡すと、例外がスローされます。 -* ``Cake\View\Helper\FormHelper`` および ``Cake\View\Helper\HtmlHelper`` は、 HTML データ属性 - ``data-confirm-message`` を使用して、 ``confirm`` オプションを持つメソッドの確認メッセージを保持するようになりました。 -* ``Cake\View\Helper\FormHelper::button()`` は、 HTML エンティティーがデフォルトで、ボタンテキストと - HTML 属性 をエンコードするようになりました。新しいオプション ``escapeTitle`` が追加され、 - 他の HTML 属性とは別にタイトルのエスケープを制御できるようになりました。 -* ``Cake\View\Helper\SecureFieldTokenTrait`` が削除されました。 - そのフォームトークンデータ構築機能は、内部クラス ``FormProtector`` に含まれるようになりました。 -* ``HtmlHelper::docType()`` メソッドが削除されました。HTML4 および XHTML は廃止され、 - HTML5 の doctype は非常に短く、直接入力するのが簡単です。 -* ``HtmlHelper::scriptBlock()`` および ``HtmlHelper::scriptStart()`` の ``safe`` オプションが削除されました。 - 有効にすると、現在無効になっている XHTML のみに必要な ``CDATA`` タグを生成します。 - -Log ---- - -* ``Cake\Log\LogTrait::log()`` および ``Cake\Log\Log::write()`` などのログ関連メソッドは、 - ``$message`` 引数に文字列のみを受け入れるようになりました。 - この変更は、 API を `PSR-3 `__ 標準に合わせるために必要でした。 - -その他 ------- - -* アプリケーションの ``config/bootstrap.php`` には、 ``Router::fullBaseUrl()`` への呼び出しを含めてください。 - 最新のスケルトンアプリケーションの ``bootstrap.php`` を参照し、それに応じて更新します。 -* ``App::path()`` は、 ``Template`` の代わりに ``$type`` および ``templates`` を使用して、 - テンプレートへのパスを取得します。同様にロケールフォルダーのパスを取得するには、 ``Locale`` の代わりに - ``locales`` を使用します。 -* ``ObjectRegistry::get()`` は、指定された名前のオブジェクトがロードされていない場合、例外をスローするようになりました。 - ``ObjectRegistry::has()`` を使用して、オブジェクトがレジストリーに存在することを確認する必要があります。 - マジックゲッター ``ObjectRegistry::__get()`` は、指定された名前のオブジェクトがロードされない場合、 - 引き続き ``null`` を返します。 -* ロケールファイルは、 ``src/Locale`` から ``resources/locales`` に移動しました。 -* CakePHP にバンドルされていた ``cacert.pem`` ファイルは、 - `composer/ca-bundle `__ - への依存関係に置き換えられました。 - - -新機能 -====== - -Console -------- - -* コマンドクラスは、 ``defaultName()`` メソッドを実装して、慣習に基づいた CLI 名を上書きできます。 - -Core ----- - -* ``InstanceConfigTrait::getConfigOrFail()`` および ``StaticConfigTrait::getConfigOrFail()`` が追加されました。 - 他の ``orFail`` メソッドと同様に、これらのメソッドは要求されたキーが存在しないか - ``null`` 値を持っている場合に例外を発生させます。 - -Database --------- - -* データベースのタイムゾーンが PHP のタイムゾーンと一致しない場合は、 ``DateTime::setDatabaseTimezone()`` を使用できます。 - 詳しくは、 `datetime-type` をご覧ください。 -* ``DateTime::setKeepDatabaseTimezone()`` により、クエリーによって生成された DateTime オブジェクトに、 - データベースのタイムゾーンを保持できます。 -* ``Cake\Database\Log\LoggedQuery`` は ``JsonSerializable`` を実装するようになりました。 -* ``Cake\Database\Connection`` で PSR-3 のロガーを使用できるようになりました。 - その結果、スタンドアロンのデータベースパッケージを使用しているユーザーは、 - ロギングに ``cakephp/log`` パッケージを使用することを強制されなくなりました。 -* ``Cake\Database\Connection`` で PSR-16 のキャッシャー を使用できるようになりました。 - その結果、スタンドアロンのデータベースパッケージを使用しているユーザーは、 - キャッシングに ``cakephp/cache`` パッケージを使用することを強制されなくなりました。 - 新しいメソッド ``Cake\Database\Connection::setCache()`` および ``Cake\Database\Connection::getCache()`` が追加されました。 -* ``Cake\Databases\ConstraintsInterface`` が ``Cake\Datasource\FixtureInterface`` から抽出されました。 - このインターフェースは、制約をサポートするフィクスチャー実装によって実装する必要があります。 - これは、私たちの経験からは一般にリレーショナルデータベースです。 -* 抽象型 ``char`` が追加されました。このタイプは、固定長の文字列カラムを処理します。 -* 抽象型 ``datetimefractional`` および ``timestampfractional`` が追加されました。 - このタイプは、秒の小数部を持つカラムデータ型を処理します。 -* SqlServer スキーマは、 SYSDATETIME() などの関数を含むデフォルト値をサポートするようになりました。 -* 抽象型 ``datetimetimezone`` および ``timestamptimezone`` が追加されました。 - このタイプは、タイムゾーンをサポートするカラムデータ型を処理します。 - -Error ------ - -* 接頭辞付きのコントローラーアクションによってエラーが発生した場合、 - ``ErrorController`` は接頭辞付きのエラーテンプレートがある場合は、それを利用します。 - この動作は ``debug`` がオフの場合にのみ適用されます。 - -Http ----- - -* フレームワーク全体を含めずに ``cakephp/http`` を使用できます。 -* CakePHP は `PSR-15: HTTP Server Request Handlers - `__ の仕様をサポートするようになりました。 - 結果としてミドルウェアは ``Psr\Http\Server\MiddlewareInterface`` を実装するようになりました。 - CakePHP 3.x スタイルの呼び出し可能なダブルパスミドルウェアは、後方互換性のために引き続きサポートされています。 -* ``Cake\Http\Client`` は `PSR-18: HTTP Client `__ - の仕様に準拠するようになりました。 -* ``Cake\Http\Client\Response::isSuccess()`` が追加されました。このメソッドは、 - レスポンスステータスコードが 2xx の場合 true を返します。 -* ``CspMiddleware`` が追加され、コンテンツセキュリティポリシーヘッダーの定義がより簡単になりました。 -* ``HttpsEnforcerMiddleware`` が追加されました。これにより ``SecureComponent`` の ``requireSecure`` 機能が - 置き換えられました。 -* Cookie は ``SameSite`` 属性をサポートするようになりました。 - -I18n ----- - -* ``Date`` および ``FrozenDate`` は、 ``today('Asia/Tokyo')`` のようなさまざまなファクトリーヘルパーの - タイムゾーンパラメーターを尊重するようになりました。 - -Mailer ------- - -* メールメッセージ生成の責務は ``Cake\Mailer\Renderer`` に移されました。 - これは主にアーキテクチャーの変更であり、 ``Email`` クラスの使用方法には影響しません。 - 唯一の違いは、テンプレート変数を設定するために ``Email::set()`` の代わりに ``Email::setViewVars()`` - を使用する必要があることです。 - -ORM ---- - -* ``Table::saveManyOrFail()`` メソッドが追加され、エラーの場合に失敗した特定のエンティティーで - ``PersistenceFailedException`` をスローします。 -* コールバックを含む多くのエンティティーを一度に削除するための ``Table::deleteMany()`` - および ``Table::deleteManyOrFail()`` メソッドが追加されました。 - エンティティーはトランザクションセーフで削除されます。 -* 新しい空のエンティティーオブジェクトを作成するために ``Table::newEmptyEntity()`` が追加されました。 - これはフィールドバリデーションをトリガーしません。 - エンティティは、空のレコードとして検証エラーなしで永続化できます。 -* ``Cake\ORM\RulesChecker::isLinkedTo()`` および ``isNotLinkedTo()`` が追加されました。 - これらの新しいアプリケーションルールを使用すると、関連付けがあるかもしくは関連レコードがあるかどうかを確認できます。 -* 新しい型クラス ``DateTimeFractionalType`` がマイクロ秒精度の日付型として追加されました。 - この型をデフォルトの ``datetime`` 型として ``TypeFactory`` に追加するか、個々のカラムに再マッピングすることで、 - この型の使用を選択できます。このタイプをデータベースタイプに自動的にマッピングする方法については、 - Database migration notes を参照してください。 -* タイムゾーンをサポートする日時型に、新しい型クラス ``DateTimeTimezoneType`` が追加されました。 - この型をデフォルトの ``datetime`` 型として ``TypeFactory`` に追加するか、個々のカラムに再マッピングすることで、 - この型の使用を選択できます。このタイプをデータベースタイプに自動的にマッピングする方法については、 - Database migration notes を参照してください。 - -Routing -------- - -* ``Cake\Routing\Asset`` が追加されました。このクラスは、 ``Router::url()`` と同等の静的インターフェースで、 - アセットURL生成を公開します。詳しくは `asset-routing` をご覧ください。 - -TestSuite ---------- - -* ``TestSite\EmailTrait::assertMailContainsAttachment()`` が追加されました。 - -Validation ----------- - -* ``Validation::dateTime()`` がマイクロ秒を含む値を受け入れるようになりました。 - -View ----- - -* ``FormHelper`` は、エンティティーの ORM テーブルクラスで "notEmpty" とマークされたフィールドの - HTML5 検証メッセージを生成するようになりました。この機能は ``autoSetCustomValidity`` - クラス設定オプションで切り替えることができます。 -* ``FormHelper`` は、日時フィールドのネイティブ HTML5 入力タグを生成するようになりました。 - 詳しくは、`Form Helper ` ページを参照してください。 - 以前のマークアップを保持する必要がある場合は、シム化された FormHelper が - `Shim plugin `__ にあり、 - 古い動作・生成が含まれています（4.x ブランチ）。 -* ``FormHelper`` は、時間コンポーネントを持つ ``datetime`` ウィジェットのデフォルトのステップサイズを - 秒に設定するようになりました。フィールドが新しい ``datetimefractional`` もしくは ``timestampfractional`` - データベースタイプからのものである場合、デフォルトはミリ秒です。 diff --git a/ja/appendices/4-0-upgrade-guide.rst b/ja/appendices/4-0-upgrade-guide.rst deleted file mode 100644 index 59c9a5d3e2..0000000000 --- a/ja/appendices/4-0-upgrade-guide.rst +++ /dev/null @@ -1,107 +0,0 @@ -4.0 アップグレードガイド -######################## - -4.0 にアップグレードする前に、まず 最新の CakePHP 3.x へのアップグレードを済ませておいてください。 - -.. note:: - アップグレードツールは、最新のCakePHP3.xで実行されているアプリケーションでのみ機能します。CakePHP 4.0 にアップデートした後は、アップグレードツールを実行できません。 - -非推奨の警告を修正 -======================== - -まず、非推奨警告の表示を有効にします。 :: - - // config/app.php - 'Error' => [ - 'errorLevel' => E_ALL, - ] - -次に、アプリケーションとそのプラグインが発行する非推奨の警告を修正していきます。 - -PHP 7.2 へのアップグレード -========================== - -CakePHP 4.0 は **PHP 7.2** を必要とします。PHPのバージョンが古い場合は、CakePHP を更新する前に PHP をアップグレードしてください。 - -.. note:: - CakePHP 4.0を動作させるには、 **PHP 7.2以上** が必要です。. - -.. _upgrade-tool-use: - -アップグレードツールの使用 -========================== - -CakePHP 4 は、 strict モードを採用し、多くのタイプヒントを使用するため、 -メソッドシグネチャおよびファイル名の変更に関する後方互換性のない変更が多数あります。 -この単調な書き換え作業を半自動的に修正するために、CLI によるアップグレードツールを -使用することができます。 - -.. warning:: - cakephp40およびphpunit80の `file_rename` コマンドとrectorのルールスクリプトは、 - アプリケーションの依存関係を4.0に更新する **前** に実行することを前提としています。 - アプリケーションの依存関係がすでに4.xまたはPHPUnit8に更新されている場合、 - `cakephp40` のrectorルールスクリプトは正しく実行されません。 - -.. code-block:: console - - # アップグレードツールをインストール - git clone https://github.com/cakephp/upgrade - cd upgrade - git checkout 4.x - composer install --no-dev - -アップグレードツールをインストールすると、アプリケーションまたはプラグインで実行できるようになります。 - -.. code-block:: console - - # ロケールファイルの名前を変更する - bin/cake upgrade file_rename locales - - # テンプレートファイルの名前を変更する - bin/cake upgrade file_rename templates - -テンプレートファイルとロケールファイルの名前を変更したら、 **/config/app.php** 内の -``App.paths.locales`` と ``App.paths.templates`` のパスを必ず更新してください。 -必要に応じて、 `app config のスケルトン `_ -を参照してください。 - -Rector によるリファクタリングを適用する ---------------------------------------- - -次に、 ``rector`` コマンドを使用して、非推奨となった多くの CakePHP および PHPUnit のメソッドコールを -自動的に修正します。依存関係をアップグレードする **前** に、 rector を適用することが重要です。 :: - - bin/cake upgrade rector --rules phpunit80 - bin/cake upgrade rector --rules cakephp40 - -アップグレードツールを使用して、CakePHPのマイナーバージョンごとに新しいrectorルールを -適用することもできます。:: - - # Run the rector rules for the 4.0 -> 4.1 upgrade. - bin/cake upgrade rector --rules cakephp41 - -CakePHP の依存関係をアップデートする -==================================== - -``rector`` によるリファクタリングを適用した後、下記の composer コマンドを使用して CakePHP と PHPUnit をアップデートします。 - -.. code-block:: console - - php composer.phar require --dev --update-with-dependencies "phpunit/phpunit:^8.0" - php composer.phar require --update-with-dependencies "cakephp/cakephp:4.0.*" - -Application.php -=============== - -次に、 ``src/Application.php`` が更新され、cakephp/appにあるものと同じ -メソッドシグネチャを持つようになっていることを確認します。 -最新の `Application.php `__ -はGitHubにあります。 - -ある種のRESTAPIを提供している場合は、 :ref:`body-parser-middleware` を含める必要があります。 - -最後に、 ``AuthComponent`` をまだ使用している場合は、 -新しい `AuthenticationMiddleware `__ -および -`AuthorizationMiddleware `__ へのアップグレードを -検討する必要があります。 diff --git a/ja/appendices/4-1-migration-guide.rst b/ja/appendices/4-1-migration-guide.rst deleted file mode 100644 index 7ea93d9c3e..0000000000 --- a/ja/appendices/4-1-migration-guide.rst +++ /dev/null @@ -1,274 +0,0 @@ -4.1 移行ガイド -############## - -CakePHP 4.1 は 4.0 からのAPI互換アップグレードです。 -このページでは、4.1で追加された非推奨事項と機能の概要を説明します。 - -4.1.0へのアップグレード -======================= - -CakePHP 4.1.0にアップグレードするには、次の Composer コマンドを実行してください。:: - - php composer.phar require --update-with-dependencies "cakephp/cakephp:4.1.x" - -非推奨 -============ - -4.1では、いくつかの非推奨機能が導入されています。 -これらの機能はすべて 4.x の間は継続されますが、5.0 で削除されます。 -非推奨機能の更新を自動化するには、`upgrade tool ` を使用します。:: - - bin/cake upgrade rector --rules cakephp41 - -.. note:: - これはCakePHP 4.1の変更点のみを更新します。CakePHP 4.0の変更を最初に適用していることを確認してください。 - -Controller ----------- - -* ``PaginatorComponent`` の ``sortWhitelist`` オプションは非推奨になりました。 - 代わりに、``sortableFields`` を使用してください。 -* ``PaginatorComponent`` の ``whitelist`` オプションは非推奨になりました。 - 代わりに、``allowedParameters`` を使用してください。 - -Database --------- - -* ``TableSchema::getPrimary()`` は非推奨になりました。 - 代わりに、 ``getPrimaryKey()`` を使用してください。 -* ``Cake\Database\Schema\BaseSchema`` は - ``Cake\Database\Schema\SchemaDialect`` に名前が変更されました。 -* ``Cake\Database\Schema\MysqlSchema`` は - ``Cake\Database\Schema\MysqlSchemaDialect`` に名前が変更されました。 -* ``Cake\Database\Schema\SqliteSchema`` は - ``Cake\Database\Schema\SqliteSchemaDialect`` に名前が変更されました。 -* ``Cake\Database\Schema\SqlserverSchema`` は - ``Cake\Database\Schema\SqlserverSchemaDialect`` に名前が変更されました。 -* ``Cake\Database\Schema\PostgresSchema`` は - ``Cake\Database\Schema\PostgresSchemaDialect`` に名前が変更され、内部マークされました。 -* ``DateTimeType::setTimezone()`` は非推奨になりました。 - 代わりに、 ``setDatabaseTimezone()`` を使用してください。 -* ``FunctionBuilder::cast([...])`` に対するマジックメソッド署名は非推奨になりました。 - 代わりに、 ``FunctionBuilder::cast('field', 'type')`` を使用してください。 -* ``Cake\Database\Expression\Comparison`` は - ``Cake\Database\Expression\ComparisonExpression`` に名前が変更されました。 - -Datasource ----------- - -* ``Paginator`` の ``sortWhitelist`` オプションは非推奨になりました。 - 代わりに、 ``sortableFields`` を使用してください。 -* ``Paginator`` の ``whitelist`` オプションは非推奨になりました。 - 代わりに、 ``allowedParameters`` を使用してください。 - -Form ----- - - -* ``Form::schema()`` は非推奨になりました。 - 代わりに、 ``Form::getSchema()`` か ``Form::setSchema()`` を使用してください。 - -Http ----- - -* ``CsrfProtectionMiddleware::whitelistCallback()`` は非推奨になりました。 - 代わりに、 ``skipCheckCallback()`` を使用してください。 -* ``ServerRequest::input()`` は非推奨になりました。 - PHP の生の入力を文字列として取得するには、 ``(string)$request->getBody()`` を使用してください。 - ``BodyParserMiddleware`` を使ってリクエストのボディを解析してください。そうすれば、 ``$request->getParsedBody()`` で配列やオブジェクトとして利用できるようにします。 -* フレームワーク内でのクッキー作成との一貫性を高めるために、 - ``CsrfProtectionMiddleware`` の ``httpOnly`` オプションは、``httponly`` に変更されました。 - -ORM ---- - -* ``QueryExpression::or_()`` と ``QueryExpression::and_()`` は非推奨になりました。 - 代わりに ``or()`` と ``and()`` を使用してください。 - -Routing -------- - -* ``Cake\Routing\Exception\RedirectException`` は非推奨になりました。 - 代わりに、 ``Cake\Http\Exception\RedirectException`` を使用してください。 - -View ----- - -* ``Form/ContextInterface::primaryKey()`` は非推奨になりました。 - 代わりに、 ``getPrimaryKey()`` を使用してください。 - - -Behaviorの変更 -============== - - -以下の変更はどのメソッドの署名も変更しませんが、メソッドのセマンティクスや動作を変更します。 - -Database --------- - -* MySQL: （未だにブーリアン型にマップされている） ``TINYINT(1)`` 以外の整数の表示幅は無視されるようになりました。 - MySQL 8では表示幅は非推奨です。 - -Http ----- - -* アップロードしたファイルの正規化は、``ServerRequest`` から ``ServerRequestFactory`` に移動されました。 - これは、ネストされたファイルアップロード配列を使用するリクエストオブジェクトを作成している場合、 - テストに影響を与える可能性があります。 - ``IntegrationTestCaseTrait`` を使ったテストは変更する必要はありません。 - -ORM ---- - -* ``Cake\ORM\TableRegistry`` は非推奨になりました。 - テーブルロケーターインスタンスを取得するためには、 - 代わりに ``Cake\ORM\Locator\LocatorAwareTrait::getTableLocator()`` か - ``Cake\Datasource\FactoryLocator::get('Table')`` を使用してください。 - ``Controller``, ``Command``, ``TestCase`` のようなクラスは、 - すでに ``Cake\ORMLocator\LocatorAwareTrait`` を使用しています。 - そのため、これらのクラスでは ``$this->getTableLocator()->get('ModelName')`` を使うことができます。 -* BelongsToMany アソシエーションは、ジャンクションテーブルの BelongsTo アソシエーションで設定された bindingKey を尊重するようになりました。 - 以前は、ターゲットテーブルの主キーが常に代わりに使用されていました。 -* アソシエーション名が適切に大文字と小文字を区別するようになりました。 - そのため、 ``Query::contain()`` や ``Table::hasMany()`` のような関数で参照する際には、適切にマッチさせなければなりません。 -* ``Cake\ORM\AssociationCollection`` は、内部で保持しているオブジェクトマップのキーを生成するために、 - アソシエーション名を小文字にしなくなりました。 - -TestSuite ---------- - -* ``TestCase::setAppNamespace()`` は、保存と復元が簡単になるように、以前のアプリの名前空間を返すようになりました。 -* MySQL予約キーワードの変更に伴い、GroupsFixtureの名前がSectionsFixtureに変更されました。 - -View ----- - -* フォームヘルパーのデフォルトの値のソースが ``context`` の代わりに ``data, context`` に設定されるようになりました。 - もし ``setValueSources()`` を使って値のソースを変更する場合は、コードを更新する必要があるかもしれません。 -* CakePHPで提供されている ``FormHelper`` コンテキストクラスは、コンストラクタに ``$request`` オブジェクトを取らなくなりました。 - -新機能 -====== - -Datasource ----------- - -* ``EntityInterface::getAccessible()`` が追加されました。 - -Console -------- - -* 環境変数 ``NO_COLOR`` が設定されている場合、すべての出力に色の ANSI エスケープコードは含まれません。 - 詳しくは `no-color.org `__ を参照してください。 -* コマンドはシェルが ``$io->setInteractivate(false)`` を使っていたのと同じように対話モードを無効にすることができるようになりました。 - これは、必要に応じてプロンプトを回避し、デフォルト値を使用します。 - ``--quiet`` / ``-q`` を使うことで、既存のすべてのコマンドに対して直接呼び出すことができるようになりました。 - -Database --------- - -* MySQL 8 がサポートされました。テストも行われています。 -* SQL関数の集約を表現するために ``AggregateExpression`` を追加しました。 - ``FunctionsBuilder::aggregate()`` は新しい集約SQL関数をラップするのに使えます。 -* 任意の集約式にウィンドウ関数のサポートが追加されました。 - ``AggregateExpression`` はウィンドウ式をラップしたため、連鎖的な呼び出しによって任意のインスタンスを簡単に拡張することができます。 -* 集約関数が ``FILTER (WHERE ...)`` 区をサポートしました。 -* PostgreSQL と SQLServer は エイリアスを持つ集約関数に対して ``HAVING`` 条件をサポートするようになりました。 -* ``FunctionsBuilder::cast()`` が追加されました。 -* Common Table Expression (CTE) が追加されました。 - CTEは、`Query::with()` を用いてクエリにアタッチすることが可能です。 -* ``Query::orderAsc()`` と ``Query::orderDesc()`` はClosureをフィールドとして受け付けるようになり、 - 提供されている ``QueryExpression`` オブジェクトを使って複雑なオーダー式を構築できるようになりました。 - -Error ------ - -* ウェブコンテキストではHTMLを、CLIコンテキストではANSIスタイルで出力するようになりました。 - 周期的な構造や繰り返しオブジェクトの出力がよりシンプルになりました。 - 周期的なオブジェクトは一度だけダンプされ、完全な値に戻るために参照 ID を使用します。 -* ``Debugger::addEditor()`` と ``Debugger::setEditor()`` が追加されました。 - これらのメソッドにより、エディタのフォーマットを追加したり、好みのエディタを設定したりすることができます。 -* 設定値として ``Debugger.editor`` が追加されました。この値は、優先されるエディタのリンク形式として使用されます。 -* ``ErrorHandlerMiddleware`` は ``Http\Exception\RedirectException`` をハンドルするようになり、 - それらの例外を HTTP リダイレクトレスポンスに変換するようになりました。 -* ``BaseErrorHandler`` は設定されたエラーロガーを使ってPHPの警告やエラーをログに記録するようになりました。 -* カスタムエラーロガーに必要なインターフェイスを正式なものにするために ``ErrorLoggerInterface`` が追加されました。 - -Form ----- - -* ``Form::set()`` を追加しました。 - このメソッドは ``View::set()`` や ``Controller::set()`` と同じようにフォームオブジェクトにデータを追加することができます。 - -Http ----- - -* ``BaseApplication::addOptionalPlugin()`` を追加しました。 - このメソッドは、プラグインの読み込みや、開発者依存のため存在しない可能性のあるプラグインのエラー処理を行います。 -* ``Cake\HttpException\RedirectException`` を追加しました。 - この例外は Routing パッケージの ``RedirectException`` を置き換えるもので、 アプリケーションのどこでも発生させることができます。 -* ``CsrfProtectionMiddleware`` は ``samesite`` 属性を設定したクッキーを作成することができるようになりました。 -* ``Session::read()`` が2番目のパラメータでデフォルト値を設定できるようになりました。 -* ``Session::readOrFail()`` は、キーが見つからなかった場合に例外を発生させたい場合に便利な ``read()`` 操作のラッパーとして追加されました。 - -I18n ----- - -* ``Time`` , ``FrozenTime`` , ``Date`` , ``FrozenDate`` の ``setJsonEncodeFormat`` メソッドは、 - カスタムの文字列を返すための callable を受け入れるようになりました。 -* ``parseDateTime()`` と ``parseDate()`` は、 ``disableLenientParsing()`` を使用して、簡潔な構文解析を無効にすることができます。 - デフォルトでは有効になっています。（IntlDateFormatter と同様です） - -Log ---- - -* ログメッセージに ``{foo}`` スタイルのプレースホルダを含めることができるようになりました。 - これらのプレースホルダは ``$context`` パラメータの値に置き換えられます。 - -ORM ---- - -* ORMはリクエストデータから各エンティティがマージされた後に - ``Model.afterMarshal`` イベントをトリガーするようになりました。 -* ``TranslateBehavior`` を使用しているときに、 ``locale`` finderオプションを使用して、 - 単一の検索呼び出しのロケールを変更することができます。 -* ``Query::clearResult()`` が追加されました。 - このメソッドを使うと、クエリの結果を削除して再実行できるようになります。 -* ``Table::delete()`` は、cascadeCallbackの操作中に依存するアソシエーションが削除に失敗した場合、 - 削除操作を中止してfalseを返すようになりました。 -* ``Table::saveMany()`` は保存されたエンティティに対して - ``Model.afterSaveCommit`` イベントを起動するようになりました。 - -Routing -------- - -* ルートパス文字列からURL配列を素早く生成するための便利な関数 ``urlArray()`` が導入されました。 - -TestSuite ---------- - -* ``FixtureManager::unload()`` は、フィクスチャがアンロードされている間、 - テストの *end* でテーブルを切り詰めることはなくなりました。 - テーブルはフィクスチャのセットアップ中にも切り捨てられます。 - 切り捨て処理が少なくなったため、テストスイートの実行がより速くなるはずです。 -* メールボディアサーションは、失敗メッセージにメールの内容を含めるようになり、 - テストのデバッグがより簡単になりました。 -* チェーン可能なフィクスチャ設定を可能にするために、``TestCase::addFixture()`` が追加されました。 - これは、IDEでも自動補完可能です。 - -View ----- - -* ``TextHelper::::slug()`` を追加しました。 - このメソッドは、 ``Cake\Utility\Text::slug()`` を委譲します。 -* ヘルパーを追加するためのチェイン可能なラッパーメソッドとして - ``ViewBuilder::addHelper()`` を追加しました。 -* ルートパスからのリンクやURLをより簡単に作成するために、ビュー層でIDEをサポートした - ``HtmlHelper::linkFromPath()`` と ``UrlHelper::urlFromPath()`` を追加しました。 - -Utility -------- - -* ``Hash::combine()`` は ``$keyPath`` パラメータに ``null`` を指定できるようになりました。 - nullを指定すると、数値インデックス付きの出力配列になります。 diff --git a/ja/appendices/4-2-migration-guide.rst b/ja/appendices/4-2-migration-guide.rst deleted file mode 100644 index 5e66ff126d..0000000000 --- a/ja/appendices/4-2-migration-guide.rst +++ /dev/null @@ -1,204 +0,0 @@ -4.2 移行ガイド -############## - -CakePHP 4.2 は 4.0 からのAPI互換アップグレードです。 -このページでは、4.2で追加された非推奨事項と機能の概要を説明します。 - -4.2.0へのアップグレード -======================= - -CakePHP 4.2.0にアップグレードするには、次の Composer コマンドを実行してください。:: - - php composer.phar require --update-with-dependencies "cakephp/cakephp:4.2.x" - -非推奨 -============ - -4.2では、いくつかの非推奨機能が導入されています。 -これらの機能はすべて 4.x の間は継続されますが、5.0 で削除されます。 -非推奨機能の更新を自動化するには、`upgrade tool ` を使用します。:: - - bin/cake upgrade rector --rules cakephp42 - -.. note:: - これはCakePHP 4.2の変更点のみを更新します。CakePHP 4.1の変更を最初に適用していることを確認してください。 - -パスごとに非推奨を無効にするための新しい設定オプションが追加されました。 -詳細は `deprecation-warnings` を参照してください。 - -Core ----- - -- ``Exception::responseHeader()`` は非推奨になりました。 - HTTP のレスポンスヘッダを設定するには ``HttpException::setHeaders()`` を使用しなければなりません。 - レスポンスヘッダを設定するアプリケーションやプラグインの例外は ``HttpException`` のサブクラスに更新する必要があります。 -- ``Cake\Core\Exception\Exception`` は - ``Cake\Core\Exception\CakeException`` に名前が変更されました。 - -Database --------- - -- ``Cake\Database\Exception`` は ``Cake\Database\Exception\DatabaseException`` に名前が変更されました。 - -ORM ---- - -- ``TableLocator::allowFallbackClass()`` が追加されました。 - このメソッドは、自動的に生成されるフォールバックテーブルクラスを無効にします。 - 現在は無効にすることがオプトインされていますが、将来的にはデフォルトになります。 -- ``ORM\Behavior::getTable()`` は非推奨になりました。 - 代わりに、``table()`` を使用してください。 - この変更により、``ORM\Table`` 間でメソッドの戻り値が異なるようになったため、メソッド名も異なるものになりました。 - -Behaviorの変更 -============== - -以下の変更はどのメソッドのシグネチャも変更しませんが、メソッドのセマンティクスや動作を変更します。 - -Collection ----------- - -- ``Collection::groupBy()`` と ``Collection::indexBy()`` は、パスが存在しない場合や - パスに NULL 値が含まれている場合に例外をスローするようになりました。 - null をサポートする必要がある場合は、コールバックを使用してデフォルト値を返すようにしました。 - -Controller ----------- - -- ``Controller::$components`` は protected になりました。 - 以前は protected として文書化されていました。 - これは、実装で可視性を public に変更できるため、ほとんどのアプリケーションコードに影響を与えることはないはずです。 - -Component ---------- - -- ``FlashComponent::set()`` を ``Exception`` インスタンスと一緒に使用する場合、 - デフォルトで ``element`` オプションを ``error`` に設定するようになりました。 - -Database --------- - -- ``TimeType`` は ``H:i`` 形式の値を正しくマーシャルするようになりました。 - ※以前は、これらの値はバリデーション実行後に ``null`` にキャストされていました。 - -Error ------ - -- 例外コードは ``HttpException`` の HTTP ステータスコードとしてのみ使用されるようになりました。 - その他の例外で 500 以外の値を返すHTTPコードは ``ExceptionRenderer::$exceptionHttpCodes`` によって制御されます。 - - .. note:: - 例外が更新されるまで以前の動作に戻す必要がある場合は、 - カスタムの ExceptionRenderer を作成して ``getHttpCode()`` 関数をオーバーライドすることができます。 - 詳細は `custom-exceptionrenderer` を参照してください。 - -- ``ConsoleErrorHandler`` は例外コードを ``ConsoleException`` の終了コードとしてのみ使用するようになりました。 - -Validation ----------- - -- ``Validation::time()`` は、分がない場合に文字列を拒否するようになりました。 - ※以前は時間のみの数字を受け付けていましたが、APIのドキュメントでは分が必要だと示されていました。 - -破壊的変更 -========== - -API の背後に、対応が必要ないくつかの破壊的変更があります。 -これらの変更は通常、テストにのみ影響します。 - -I18n ----- -- `Aura.Intl `_ パッケージへの依存性は、もはやメンテナンスされていないため削除されました。 - アプリ/プラグインが :ref:`custom translation loaders ` を持っている場合、 - ``Aura\Intl\Package`` の代わりに ``Cake\I18n\Package`` のインスタンスを返す必要があります。 - -テスト ------- - -- UUID 周辺のフィクスチャ名が統合されました (``UuidItemsFixture``, ``BinaryUuidItemsFixture``)。 - これらの名前を使用している場合は、必ず更新してください。 - ``UuidportfoliosFixture`` は core では使われていませんでしたが、現在は削除されています。 - -新機能 -====== - -私たちは、機能を出荷できるようにするために、新しいプロセスを追加し、 -コミュニティからのフィードバックを集めて それらの機能を進化させていきます。 -私たちはこの仕組みを `experimental-features` と呼んでいます。 - -Core ----- - -- コンテナ :doc:`/development/dependency-injection` の実験的サポートが追加されました。 - -Console -------- - -- ``ConsoleIo::comment()`` が追加されました。 - このメソッドは、生成されたヘルプテキストのコメントのように、テキストを青く整形します。 -- ``TableHelper`` は ```` 書式タグをサポートするようになりました。 - これは、セルの内容を（左ではなく）右端に揃えます。 - -Database --------- - -- ``SqlServer`` はデフォルトでクライアント側のバッファリングされたカーソルを準備された文のために作成するようになりました。 - これは、サーバー側の SCROLL カーソルのパフォーマンスの問題を修正するために変更されました。 - ほとんどの結果セットでパフォーマンスが向上されることを確認してください。 - - .. warning:: - クエリ結果が大きいユーザの場合、``Query::disableBufferedResults()`` が呼ばれないと - クライアント側のバッファの割り当てにエラーが発生する可能性があります。 - 最大バッファサイズは ``php.ini`` で ``pdo_sqlsrv.client_buffer_max_kb_size`` で設定できます。 - 詳細は https://docs.microsoft.com/ja-jp/sql/connect/php/cursor-types-pdo-sqlsrv-driver?view=sql-server-ver15#pdo_sqlsrv-and-client-side-cursors - を参照してください。 -- 現在の結果キャスティングモードを取得するために ``Query::isResultsCastingEnabled()`` が追加されました。 -- 照合（ collation ）に文字列リテラルを使えるように、 ``StringExpression`` が追加されました。 -- ``IdentifierExpression`` が照合（ collation ）をサポートするようになりました。 - -Http ----- - -- ``Cake\Http\Middleware\SessionCsrfProtectionMiddleware`` が追加されました。 - このミドルウェアは、CSRFトークンをクッキーではなく、セッションに格納します。 - これにより、CSRFトークンはセッションに合わせてユーザスコープ化され、時間ベースのものとなり、 - クッキーベースのCSRFトークンよりもセキュリティが強化されます。 - このミドルウェアは ``CsrfProtectionMiddleware`` の代替品です。 - -- ``hal+json``, ``hal+xml``, ``jsonld`` が ``Response`` に追加され、 - ``withType()`` で使用できるようになりました。 -- ``Client::createFromUrl()`` を追加しました。このメソッドを使うと、 - ベースパスを含む特定のドメインにスコープされたHTTPクライアントを作成することができます。 -- 新しいユーティリティクラス ``CakeHttp\\FlashMessage`` が追加され、 - そのインスタンスは ``ServerRequest::getFlash()`` を通して利用できるようになりました。 - ``FlashComponent`` に似たクラスで、フラッシュメッセージを設定することができます。 - 特にミドルウェアからのフラッシュメッセージを設定するのに便利です。 - -ORM ---- - -- ``Table::subquery()`` と ``Query::subquery()`` が追加されました。 - これらのメソッドを使うと、自動エイリアスを持たないクエリオブジェクトを作成することができます。 - これにより、サブクエリや一般的なテーブル式を作成する際のオーバーヘッドや複雑さを軽減することができます。 -- 3.xで利用可能だった ``IsUnique`` ルールは ``allowMultipleNulls`` オプションを受け入れるようになりました。 - 3.x とは異なり、デフォルトでは無効になっています。 - -TestSuite ---------- - -- ``EmailTrait::assertMailSubjectContains()`` と - ``assertMailSubjectContainsAt()`` が追加されました。 -- ``mockService()`` に ``ConsoleIntegrationTestTrait`` と ``IntegrationTestCaseTrait`` が追加されました。 - このメソッドは :doc:`/development/dependency-injection` コンテナに注入されたサービスを - モックオブジェクトやスタブオブジェクトに置き換えることを可能にします。 - -View ----- - -- コンテキストクラスは ``attributes()`` の結果に - ``comment``, ``null``, ``default`` のメタデータオプションを含めるようになりました。 -- ``ViewBuilder::addHelper()`` は、ヘルパーのコンストラクタにオプションを渡すための - ``$options`` パラメータを受け付けるようになりました。 -- オプション ``assetUrlClassName``` が ``UrlHelper``` に追加されました。 - このオプションを使うと、デフォルトのアセットの URL リゾルバをアプリケーション固有のものに置き換えることができます。 - これは、アセットキャッシュバストのパラメータをカスタマイズする必要がある場合に便利です。 diff --git a/ja/appendices/4-3-migration-guide.rst b/ja/appendices/4-3-migration-guide.rst deleted file mode 100644 index e8b836c496..0000000000 --- a/ja/appendices/4-3-migration-guide.rst +++ /dev/null @@ -1,321 +0,0 @@ -4.3 移行ガイド -############## - -CakePHP 4.3 は 4.0 からのAPI互換アップグレードです。 -このページでは、4.3で追加された非推奨事項と機能の概要を説明します。 - -4.3.0へのアップグレード -======================= - -CakePHP 4.3.0にアップグレードするには、次の Composer コマンドを実行してください。:: - - php composer.phar require --update-with-dependencies "cakephp/cakephp:^4.3" - -非推奨 -============ - -4.3では、いくつかの非推奨機能が導入されています。 -これらの機能はすべて 4.x の間は継続されますが、5.0 で削除されます。 -非推奨機能の更新を自動化するには、 :ref:`upgrade tool ` を使用します。:: - - bin/cake upgrade rector --rules cakephp43 - -.. note:: - これはCakePHP 4.3の変更点のみを更新します。CakePHP 4.2の変更を最初に適用していることを確認してください。 - -新しい設定オプションが追加され、パスごとに非推奨を無効にすることができるようになりました。 -詳細は :ref:`deprecation-warnings` を参照してください。 - -Connection ----------- - -- ``Connection::supportsDynamicConstraints()`` は非推奨となりました。 - フィクスチャが動的に制約を削除したり作成したりしないようになったためです。 - -Controller ----------- - -- ``Controller.shutdown`` コンポーネントのイベントコールバックの名前が - ``shutdown`` から ``afterFilter`` に変更されました。これにより、コールバックの一貫性が高まりました。 - -Database --------- - -- 可変のdatetimeクラスを ``DateTimeType`` やその他の時間関連の型クラスで使用することは、非推奨となります。 - そのため、他の型クラスのメソッドである ``DateTimeType::useMutable()``, ``DateTimeType::useImmutable()`` や - 同様のメソッドは非推奨となります。 -- ``DriverInterface`` で定義された機能定数を受け付ける ``DriverInterface::supports()`` を採用している - ``DriverInterface::supportsQuoting()`` および ``DriverInterface::supportSavepoints()`` は現在、非推奨となっています。 -- ``DriverInterface::supportsDynamicConstraints()`` は、フィクスチャが動的な制約の削除、作成を試みないため、非推奨となりました。 - -I18n ----- - -- datetime クラスの ``Time`` と ``Date`` は非推奨です。 - 代わりに、不変的な代替クラスである ``FrozenTime`` と ``FrozenDate`` を使用してください。 - -Log ---- - -- ``FileLog`` は、``dateFormat`` 設定オプションを ``DefaultFormatter`` に移動しました。 -- ``ConsoleLog`` は、``dateFormat`` 設定オプションを ``DefaultFormatter`` に移動しました。 -- ``SyslogLog`` では、``format`` 設定オプションを ``LegacySyslogFormatter`` に移動しました。 - 現在のデフォルトは ``DefaultFormatter`` です。 - -Middleware ----------- - -- "ダブルパス"のミドルウェア、つまり、``__invoke($request, $response, $next)`` メソッドを持つクラスは非推奨です。 - 代わりに、``function($request, $handler)`` というシグネチャを持つ ``Closure`` や、 - ``PsrhttpHttpServer\MiddlewareInterface`` を実装したクラスを使用してください。 - -Network -------- - -- ``Socket::$connected`` は非推奨です。代わりに ``isConnected()`` を使用してください。 -- ``Socket::$description`` は非推奨です。 -- ``Socket::$encrypted`` は非推奨です。代わりに ``isEncrypted()`` を使用してください。 -- ``Socket::$lastError`` は非推奨です。代わりに ``lastError()`` を使用してください。 - -ORM ---- -- ``ModelAwareTrait::loadModel()`` は非推奨です。 - 代わりに、新しい ``LocatorAwareTrait::fetchTable()`` を使用してください。 - 例えば、コントローラではデフォルトのテーブルインスタンスを取得するために ``$this->fetchTable()`` を実行することもできますし、 - デフォルト以外のテーブルを取得するには ``$this->fetchTable('Foos')`` を使用することもできます。 -- クエリをプロキシするすべての ``ResultSetInterface`` メソッド（ ```CollectionInterface``` を含む） - （これらは強制的に結果を取得し、その結果に対してプロキシされたメソッドを呼び出します）は非推奨になりました。 - 非推奨な使い方の例として、 ``$query->combine('id', 'title');`` があります。 - これを ``$query->all()->combine('id', 'title');`` に変更する必要があります。 -- バリデータオブジェクトを ``Table::save()`` の ``validate`` オプションに渡すことは、非推奨です。 - バリデーターはテーブルクラス内で定義するか、代わりに ``setValidator()`` を使用してください。 -- ``Association::setName()`` は非推奨です。 - アソシエーション名は、アソシエーションが存在するときに定義されるべきです。 -- ``QueryExpression::addCase()`` は非推奨です。代わりに ``case()`` を使用してください。 - また、 ``['value' => 'literal']`` および ``['column' => 'identifier']`` の構文は、新しい流暢なケースビルダーではサポートされていません。 - -Routing -------- - -- ``:controller`` のようなコロンの付いたルートプレースホルダーは非推奨です。 - 代わりに ``{controller}`` のような波括弧付きのプレースホルダーを使用してください。 - -TestSuite ---------- - -- ``TestFixture::$fields`` と ``TestFixture::$import`` は非推奨です。 - アプリケーションを :doc:`new fixture system <./fixture-upgrade>` に変換する必要があります。 -- ``TestCase::$dropTables`` は非推奨です。 - テスト実行中にテーブルを削除することは 新しいマイグレーションやスキーマダンプベースのフィクスチャとは互換性がなく、5.0では削除されます。 - -View ----- - -- FormHelperメソッドの非関連性オプション（例： ``['disabled']`` ）は非推奨となりました。 -- ``ViewBuilder::setHelpers()`` の第2引数 ``$merge`` は非推奨となり、 - 専用の ``ViewBuilder::addHelpers()`` メソッドを使うことで、マージと上書きの操作が明確に分離できるようになりました。 - -Behaviorの変更 -============== - -以下の変更はどのメソッドのシグネチャも変更しませんが、メソッドのセマンティクスや動作を変更します。 - -Collection ----------- - -- 同一の実装で、 ``$preserveKeys`` パラメータを ``$keepKeys`` に名称変更しました。 - -Command -------- - -- ``cake i18n extract`` には ``--relative-paths`` オプションがなくなりました。 - このオプションはデフォルトでオンになっています。 - -Core ----- - -- ``Configure::load()`` は、無効な設定エンジンが使用されている場合、例外を発生させるようになりました。 - -Database --------- - -- ``ComparisonExpression`` は、生成された ``IdentifierExpression`` のsqlを()でラップしなくなりました。 - これは ``Query::where()`` や、その他の ``ComparisonExpression`` が生成される場所に影響します。 - -Datasource ----------- - -- ``ConnectionManager::alias()`` の ``$alias`` と ``$source`` のパラメータ名を、それぞれの内容に合わせて変更しました。 - これはドキュメントと名前付きパラメータにのみ影響します。 - -Http ----- - -- ``Http\Client`` は、``ini_get('user_agent')`` で 'CakePHP' を - ユーザーエージェントのフォールバックとして使用するようになりました。 - -ORM ---- - -- ``Entity::isEmpty()`` と ``Entity::hasValue()`` を、'0'を空でない値として扱うように調整しました。 - これにより、ドキュメントや本来の意図に沿った動作となります。 -- ``TranslateBehavior`` のエンティティ検証エラーは、 ``{lang}`` ではなく ``_translations.{lang}`` のパスに設定されるようになりました。 - これにより、エンティティエラーのパスが、リクエストデータに使用されるフィールドと同じになります。 - 一度に複数の翻訳を変更するフォームがある場合は、検証エラーの表示方法を更新する必要があるかもしれません。 -- カラムを選択する際に、カラムに設定されているデフォルトの型よりも関数式で指定された型が優先されるようになりました。 - 例えば、 ``$query->select(['id' => $query->func()->min('id')])`` を使うと、 - 取得したエンティティの `id` の値は、`integer` ではなく `float` になります。 - -Routing -------- - -- ``Router::connect()``, ``Router::prefix()``, ``Router::plugin()``, ``Router::scope()`` は非推奨です。 - 代わりに、対応する非静的な ``RouteBuilder`` メソッドを使用してください。 -- ``RouteBuilder::resources()`` は、'braced' プレースホルダーを使用するルートを生成するようになりました。 - -TestSuite ---------- - -- ``TestCase::deprecated()`` は、コールバックによって - 少なくとも1つのdeprecation warningが発生したことをアサートするようになりました。 - -Validation ----------- - -- ``Validator::setProvider()`` は、オブジェクトでも文字列でもないプロバイダ名が使用された場合、 - 例外を発生させるようになりました。 - これまでは、エラーは発生しませんでしたが、そのプロバイダも動作しませんでした。 - -View ----- - -- ``ViewBuilder::build()`` の ``$vars`` パラメータは非推奨です。 - 代わりに ``setVar()`` を使用してください。 -- ``HtmlHelper::script()`` と ``HtmlHelper::css()`` は、スキームを含む絶対URLをエスケープするようになりました。 - -破壊的変更 -========== - -API の背後に、対応が必要ないくつかの破壊的変更があります。 -これらの変更は通常、テストにのみ影響します。 - -Log ---- - -- ``BaseLog::_getFormattedDate()`` と ``dateFormat`` の設定が削除されました。 - メッセージのフォーマットロジックがログフォーマッタに移されたためです。 - -View ----- - -- ``TimeHelper::fromString()`` は、 ``Time`` ではなく ``FrozenTime`` のインスタンスを返すようになりました。 - -新機能 -====== - -Controller ----------- - -- ``Controller::middleware()`` が追加され、単一のコントローラに対してのみミドルウェアを定義することができるようになりました。 - 詳しくは :ref:`controller-middleware` をご覧ください。 -- コントローラでは、アクションパラメータに ``float``, ``int``, ``bool``, ``array`` のいずれかの型宣言をサポートするようになりました。 - ブール型で渡されるパラメータは、 ``0`` か ``1`` のどちらかでなければなりません。 - -Core ----- - -- ``deprecationWarning()`` は、重複した通知を出さなくなりました。代わりに 最初に表示されるようになりました。 - これにより、テスト出力の読みやすさ これにより、テスト出力の可読性が向上し、HTMLの文脈での視覚的ノイズも改善されます。 - ``app_local.php`` で、 ``Error.allowDuplicateDeprecations`` を ``true`` に設定することで、 - 重複した通知出力を復元することができます。 -- CakePHP の ``league/container`` への依存度が ``^4.1.1`` に変更されました。 - DIコンテナは実験的とされていますが、このアップグレードにより、 - サービスプロバイダーの定義のアップグレードが必要になる可能性があります。 - -Database --------- - -* データベースマッピングタイプは、カラムのSQL生成とカラムスキーマの反映を指定するために、 - ``Cake\Database\SchemaAwareInterface`` を実装できるようになりました。 - これにより、カスタムタイプで非標準のカラムを扱うことができます。 -* ログに記録されるクエリは、postgres、sqlite、mysql の各ドライバで - ``TRUE`` と ``FALSE`` を使用するようになりました。 - これにより、クエリをコピーして対話型プロンプトで実行することが容易になりました。 -* ``DateTimeType`` では、リクエストデータをユーザーのタイムゾーンから - アプリケーションのタイムゾーンに変換できるようになりました。 - 詳しくは :ref:`converting-request-data-from-user-timezone` をご覧ください。 -* ``JsonType::setEncodingOptions()`` が追加されました。 - このメソッドでは、データを永続化する際にORMがJSONをシリアライズする際の - ``json_encode()`` オプションを定義することができます。 -* すべての機能チェックをひとつの関数にまとめた ``DriverInterface::sets()`` を追加しました。 - ドライバーは、カスタム機能名、または 機能 constants: の定数のいずれかをサポートします。 - - * ``FEATURE_CTE`` - * ``FEATURE_JSON`` - * ``FEATURE_QUOTE`` - * ``FEATURE_SAVEPOINT`` - * ``FEATURE_WINDOW`` - -- ``PDO::inTranaction()`` が返すステータスを反映する ``DriverInterface::inTransaction()`` を追加しました。 -- ``CASE, WHEN, THEN`` 文のための流暢なビルダーが追加されました。 - -Form ----- - -* ``Form::execute()`` に ``$options`` パラメータが追加されました。 - このパラメータは、どのバリデータを適用するかを選択したり、バリデーションを無効にするために使用できます。 -* ``Form::validate()`` に ``$validator`` パラメータが追加され、適用するバリデーションセットを選択できるようになりました。 - このパラメータは、適用されるバリデーションセットを選択します。 - -Http ----- - -- ``CspMiddleware`` は、``cspScriptNonce`` と ``cspStyleNonce`` のリクエスト属性を設定するようになり、 - 厳格なコンテンツセキュリティポリシーの採用を効率化しました。 -- ``Client::addMockResponse()`` と ``clearMockResponses()`` が追加されました。 - -Log ---- - -- ログエンジンは、書き込む前にメッセージ文字列をフォーマットするためにフォーマッタを使用するようになりました。 - これは ``formatter`` 設定オプションで設定できます。 - 詳細は :ref:`logging-formatters` のセクションを参照してください。 -- ``JsonFormatter`` が追加され、任意のログエンジンの ``formatter`` オプションとして設定できるようになりました。 - -ORM ---- - -- HasManyおよびBelongsToManyのアソシエーションを ``contain()`` するクエリは、 - 結果キャストのステータスを伝搬するようになりました。 - これにより、すべてのアソシエーションからの結果は、タイプマッピングオブジェクトでキャストされるか、 - まったくキャストされないかのいずれかになります。 -- ``Table`` では、 ``displayField`` のデフォルトの候補となるフィールドのリストに - ``label`` が含まれるようになりました。 -- nullを許容するカラムに対して、 ``Query::whereNotInListOrNull()`` と ``QueryExpression::notInOrNull()`` を追加しました。 - なぜなら、 ``null != value`` は常にfalseであり、カラムがnullの場合、 ``NOT IN`` のテストは常に失敗するからです。 -- ``LocatorAwareTrait::fetchTable()`` が追加されました。 - これにより、 ``$this->fetchTable()`` を使って、コントローラ、コマンド、メーラー、セルなどの - traitを使ったクラスのテーブルインスタンスを取得することができます。 - ``LocatorAwareTrait::$defaultTable`` プロパティを設定することで、デフォルトのテーブルエイリアスを指定することができます。 - -TestSuite ---------- - -- ``IntegrationTestTrait::enableCsrfToken()`` において、 - カスタムのCSRFクッキー/セッションキー名を使用できるようになりました。 -- HTTPモックを簡単に書けるように ``HttpClientTrait`` を追加しました。 - 詳細は :ref:`httpclient-testing` を参照してください。 -- 新しいフィクスチャシステムが導入されました。 - このフィクスチャシステムはスキーマとデータを分離し、既存のマイグレーションを再利用してテストスキーマを定義することができます。 - アップグレードの方法は :doc:`./fixture-upgrade` ガイドで説明しています。 - -View ----- - -- ``HtmlHelper::script()`` と ``HtmlHelper::css()`` は、 - ``cspScriptNonce`` と ``cspStyleNonce`` のリクエスト属性が存在する場合、 - 生成されたタグに ``nonce`` 属性を追加するようになりました。 -- ``FormHelper::control()`` はバリデータのメタデータに基づいて - ``aria-invalid``, ``aria-required`` , ``aria-describedby`` 属性を生成するようになりました。 - 自動ラベル要素を無効にしてプレースホルダーを提供した場合には、 ``aria-label`` 属性が設定されます。 -- ``ViewBuilder::addHelpers()`` が追加され、マージと上書きの操作が明確に分離されました。 diff --git a/ja/appendices/4-4-migration-guide.rst b/ja/appendices/4-4-migration-guide.rst deleted file mode 100644 index 7b153a65af..0000000000 --- a/ja/appendices/4-4-migration-guide.rst +++ /dev/null @@ -1,218 +0,0 @@ -4.4 移行ガイド -################### - -CakePHP 4.4 は 4.0 からのAPI互換アップグレードです。 -このページでは、4.4で追加された非推奨事項と機能の概要を説明します。 - -4.4.0へのアップグレード -======================= - -CakePHP 4.4.0にアップグレードするには、次の Composer コマンドを実行してください。:: - - php composer.phar require --update-with-dependencies "cakephp/cakephp:^4.4" - -.. note:: - CakePHP 4.4を動作させるには、PHP 7.4以上が必要です。 - -非推奨 -============ - -4.4では、いくつかの非推奨機能が導入されています。 -これらの機能はすべて 4.x の間は継続されますが、5.0 で削除されます。 - -Controller ----------- - -- ``Controller::paginate()`` の ``paginator`` オプションは非推奨です。 - 代わりに、 ``className`` を使用してください。 -- ``PaginatorComponent`` の ``paginator`` オプションは非推奨です。 - 代わりに、 ``className`` を使用してください。 - -Datasource ----------- - -- ``FactoryLocator::add()`` はもはやクロージャ・ファクトリ関数を受け付けません。 - 代わりに ``LocatorInterface`` のインスタンスを渡さなければなりません。 -- ``Cake\Datasource\Paging\Paginator`` は ``Cake\Datasource\Paging\NumericPaginator`` に名称変更されました。 - -ErrorHandler & ConsoleErrorHandler ----------------------------------- - -``ErrorHandler`` と ``ConsoleErrorHandler`` クラスは、非推奨となりました。 -これらのクラスは、新しい ``ExceptionTrap`` と ``ErrorTrap`` クラスに置き換わりました。 -トラップクラスは、より拡張可能で一貫性のあるエラーおよび例外処理フレームワークを提供します。 -新しいシステムにアップグレードするためには、（例えば ``config/bootstrap.php`` 中の） -``ErrorHandler`` と ``ConsoleErrorHandler`` の使い方を以下のように置き換えることができます。:: - - use Cake\Error\ErrorTrap; - use Cake\Error\ExceptionTrap; - - (new ErrorTrap(Configure::read('Error')))->register(); - (new ExceptionTrap(Configure::read('Error')))->register(); - -より詳細なドキュメントについては、 :doc:`/development/errors` を参照してください。 -さらに、非推奨のエラー処理システムに関連する以下のメソッドも非推奨となります。: - -* ``Debugger::outputError()`` -* ``Debugger::getOutputFormat()`` -* ``Debugger::setOutputFormat()`` -* ``Debugger::addFormat()`` -* ``Debugger::addRenderer()`` -* ``ErrorLoggerInterface::log()``。 代わりに ``logException()`` を実装してください。 -* ``ErrorLoggerInterface::logMessage()``。 代わりに ``logError()`` を実装してください。 - -RequestHandlerComponent ------------------------- - -``RequestHandlerComponent`` はゆるやかに非推奨になりました。 -``AuthComponent`` のように ``RequestHandler`` を使用しても、ランタイム非推奨にはなりませんが、 -5.0では削除される **予定** です。 - -- ``accepts()`` を ``$this->request->accepts()`` に置き換えてください。 -- ``requestedWith()`` をカスタムリクエスト検出器に置き換えてください。 - (例えば、 ``$this->request->is('json')`` など) -- ``prefers()`` を ``ContentTypeNegotiation`` に置き換えてください。 - :ref:`controller-viewclasses` を参照してください。 -- ``renderAs()`` を ``Controller`` のコントローラコンテンツネゴシエーション機能に置き換えてください。 -- ``checkHttpCache`` オプションを :doc:`/controllers/components/check-http-cache` に置き換えてください。 -- ``RequestHandlerComponent`` でビュークラスマッピングを定義する代わりに、 :ref:`controller-viewclasses` - を使用してください。 - -PaginationComponent -------------------- - -``PaginationComponent`` は非推奨で、5.0で削除される予定です。 -必要なページング設定を行うには、 ``Controller::$paginate`` プロパティ、 -または ``Controller::paginate()`` メソッドの ``$settings`` パラメータを使用します。 - -ORM ---- - -- ``SaveOptionsBuilder`` は非推奨となりました。代わりにオプション配列を使用してください。 - -プラグイン ----------- - -- プラグインクラス名は、プラグイン名に "Plugin" サフィックスを付加したものと一致するようになりました。 - 例えば、"ADmad/I18n" のプラグインクラスは、``ADmad\I18n\Plugin`` ではなく、 - ``ADmad\I18n\I18nPlugin`` となります。CakePHP 4.3以降のときと同様です。 - 後方互換性のため、旧スタイルの名前も引き続きサポートされます。 - -TestSuite ---------- - -- ``ConsoleIntegrationTestTrait`` は、 - cakephp/cakephp パッケージ全体を必要とせずにコンソールアプリケーションをテストできるように、 - 依存関係とともに console パッケージに移動されました。 - - - ``Cake\TestSuite\ConsoleIntegrationTestTrait`` は ``Cake\Console\TestSuite\ConsoleIntegrationTestTrait`` に移動しました。 - - ``Cake\TestSuite\Constraint\Console\*`` は ``Cake\Console\TestSuite\Constraint\*`` に移動しました。 - - ``Cake\TestSuite\Stub\ConsoleInput`` は ``Cake\Console\TestSuite\StubConsoleInput`` に移動しました。 - - ``Cake\TestSuite\Stub\ConsoleOutput`` は ``Cake\Console\TestSuite\StubConsoleOutput`` に移動しました。 - - ``Cake\TestSuite\Stub\MissingConsoleInputException`` は ``Cake\Console\TestSuite\MissingConsoleInputException`` に移動しました。 - -- ``ContainerStubTrait`` は、 - cakephp/cakephp パッケージ全体を必要とせずにコンソールアプリケーションをテストできるように、 - core パッケージに移動されました。 - - - ``Cake\TestSuite\ContainerStubTrait`` は ``Cake\Core\TestSuite\ContainerStubTrait`` に移動しました。 - -- ``HttpClientTrait`` は、 - cakephp/cakephp パッケージ全体を必要とせずにhttpアプリケーションをテストできるように、 - http パッケージに移動されました。 - - - ``Cake\TestSuite\HttpClientTrait`` は ``Cake\Http\TestSuite\HttpClientTrait`` に移動しました。 - -Behaviorの変更 -============== - -以下の変更は、どのメソッドのシグネチャも変更しませんが、 -メソッドのセマンティクスや動作は変更します。 - -ORM ---- - -* ``Table::saveMany()`` は、まだ 'dirty' で、オリジナルのフィールド値を含むエンティティで - ``Model.afterSaveCommit`` イベントをトリガーするようになりました。 - これは ``Model.afterSaveCommit`` のイベントペイロードを ``Table::save()`` と一致させるためのものです。 - -Routing -------- - -* ``Router::parseRequest()`` は、クライアントが無効な HTTP メソッドを使用した場合に、 - ``InvalidArgumentException`` の代わりに ``BadRequestException`` を発生させるようになりました。 - -新機能 -====== - -Cache ------ - -* ``RedisEngine`` は ``deleteAsync()`` と ``clearBlocking()`` メソッドをサポートするようになりました。 - これらのメソッドは、Redis の ``UNLINK`` オペレーションを使用して、 - 後で Redis が削除できるようにデータをマークします。 - - -Command -------- - -* ``bin/cake routes`` は、ルートテンプレート内の衝突をハイライトするようになりました。 -* ``Command::getDescription()`` では、カスタムの説明文を設定することができます。:ref:`console-command-description` を参照してください。 - -Controller ----------- - -* ``Controller::viewClasses()`` が追加されました。 - このメソッドは、コンテントタイプネゴシエーションを行う必要があるコントローラで実装する必要があります。 - ビュークラスは、content-type ネゴシエーションに参加するために、 - 静的メソッド ``contentType()`` を実装する必要があります。 - -Database --------- - -* ``SQLite`` ドライバが PHP8.1+ でメモリ内共有データベースをサポートするようになりました。 -* ``Query::newExpr()`` の代わりに ``Query::expr()`` が追加されました。 -* ``QueryExpression::case()`` ビルダーは、``CakeDatabaseTypedResultInterface`` を実装した - ``then()`` と ``else()`` に渡す式からの型推定をサポートするようになりました。 - -Error ------ - -* ``ErrorTrap`` と ``ExceptionTrap`` が追加されました。 - これらのクラスは、アプリケーションのための最新のエラー処理システムの基礎を形成しています。 - 詳しくは :doc:`/development/errors` をご覧ください。 - -Http ----- - -* ``BaseApplication::handle()`` は、 ``$request`` を - 常にサービスコンテナに追加するようになりました。 -* ``HttpsEnforcerMiddleware`` に ``hsts`` オプションが追加され、 - ``Strict-Transport-Security`` ヘッダーを設定することができるようになりました。 - -Mailer ------- - -* ``Mailer`` が ``autoLayout`` 設定を受け付けるようになり、 - ``false`` を設定することで ``ViewBuilder`` での自動レイアウトを無効にできるようになりました。 - -ORM ---- - -* ``TreeBehavior`` に ``cascadeCallbacks`` オプションが追加されました。 - このオプションを有効にすると、 ``TreeBehavior`` は ``find()`` の結果をイテレートして、個別にレコードを削除するようになります。 - これにより、ツリーノードを削除する際に ORM コールバックを使用することができるようになります。 - -Routing -------- - -* ``RoutingMiddleware`` は、マッチした ``Route`` インスタンスに "route" リクエスト属性を - 設定するようになりました。 - -View ----- - -* ``View::contentType()`` が追加されました。 - ビューは、content-typeネゴシエーションに参加するために、このメソッドを実装する必要があります。 -* ``View::TYPE_MATCH_ALL`` が追加されました。 - この特別なcontent-typeにより、content-typeネゴシエーションがマッチしない場合のフォールバックビューを構築することができます。 diff --git a/ja/appendices/5-0-migration-guide.rst b/ja/appendices/5-0-migration-guide.rst index 473674c717..7969b8d2d9 100644 --- a/ja/appendices/5-0-migration-guide.rst +++ b/ja/appendices/5-0-migration-guide.rst @@ -299,7 +299,7 @@ Core ---- - The ``services()`` method was added to ``PluginInterface``. -- ``PluginCollection::addFromConfig()`` has been added to :ref:`simplify plugin loading `. +- ``PluginCollection::addFromConfig()`` has been added to :ref:`プラグインの読み込み `. Database -------- diff --git a/ja/appendices/fixture-upgrade.rst b/ja/appendices/fixture-upgrade.rst deleted file mode 100644 index f2f073e41b..0000000000 --- a/ja/appendices/fixture-upgrade.rst +++ /dev/null @@ -1,143 +0,0 @@ -フィクスチャのアップグレード -############################ - -4.3.0では、フィクスチャのスキーマとデータ管理の責務が分割されました。 -フィクスチャクラスやマイグレーションでスキーマを管理することは、 -アプリケーションに複雑さとメンテナンスコストをもたらしていました。 -4.3.0 では新しい API が追加され、既存のマイグレーションやスキーマ管理ツールを -テストでより簡単に再利用できるようになりました。 - -新しいフィクスチャシステムにアップグレードするには、いくつかのアップデートを行う必要があります: - -#. まず、``phpunit.xml`` から ```` ブロックを削除します。 -#. 次の内容を ``phpunit.xml`` に追加します:: - - - - - - これは、テストフィクスチャマネージャからスキーマの管理を取り除きます。 - 代わりに アプリケーションは、各テスト実行の最初にスキーマを作成/更新する必要があります。 -#. 次に、スキーマを作成するために ``tests/boostrap.php`` を更新します。 - スキーマを作成するにはいくつかの異なる方法があります。 - CakePHPで提供されている方法については、`creating-test-database-schema` を参照してください。 -#. それから、フィクスチャから ``$fields`` と ``$import`` のプロパティをすべて削除してください。 - これらのプロパティは新しいフィクスチャシステムでは使用されません。 - -テストは引き続き通過するはずです。 -そして、`fixture-state-management` を使って実験できるようになります。 -大幅な性能向上を実現する ``TransactionStrategy`` を試すことができます。 -``TransactionStrategy`` のトレードオフは、テストごとに自動インクリメントの値が ``1`` から始まらなくなることです。 - -レガシーなフィクスチャのドキュメント -==================================== - -以下の説明は、4.3.0以前のデフォルトであるリスナー・ベースのフィクスチャにのみ適用されます。 - -.. _fixture-schema: - -フィクスチャのスキーマ ----------------------- - -テーブルの一部となるフィールドとその定義を ``$fields`` で指定します。 -これらのフィールドを定義するためのフォーマットは、 :php:class:`Cake\\Schema\Table` と同じです。 -テーブルの定義に使用できるキーは以下のとおりです: - -型 - CakePHP の内部データ型。現在サポートされているものは以下: - - - ``string``: は ``VARCHAR`` にマップします - - ``char``: は ``CHAR`` にマップします - - ``uuid``: は ``UUID`` にマップします - - ``text``: は ``TEXT`` にマップします - - ``integer``: は ``INT`` にマップします - - ``biginteger``: は ``BIGINTEGER`` にマップします - - ``decimal``: は ``DECIMAL`` にマップします - - ``float``: は ``FLOAT`` にマップします - - ``datetime``: は ``DATETIME`` にマップします - - ``datetimefractional``: は ``DATETIME(6)`` か ``TIMESTAMP`` にマップします - - ``timestamp``: は ``TIMESTAMP`` にマップします - - ``timestampfractional``: は ``TIMESTAMP(6)`` か ``TIMESTAMP`` にマップします - - ``time``: は ``TIME`` にマップします - - ``date``: は ``DATE`` にマップします - - ``binary``: は ``BLOB`` にマップします -長さ - フィールドに必要な長さを設定します。 -精度 - floatおよびdecimalフィールドで使用される小数点以下の桁数を設定します。 -null - ``true`` （NULLを許可する場合）、または ``false`` （許可しない場合）を設定します。 -デフォルト - フィールドが取るデフォルト値。 - -テーブル情報のインポート ------------------------- - -フィクスチャ・ファイルでスキーマを定義することは、プラグインやライブラリを作成するときや、 -データベース・ベンダー間でポータブルにする必要のあるアプリケーションを作成するときに、とても便利です。 -フィクスチャでスキーマを再定義することは、大規模なアプリケーションでは維持するのが難しくなります。 -そのため、CakePHP では既存の接続からスキーマをインポートし、 -反映されたテーブル定義を使用してテストスイートで使用するテーブル定義を作成する機能を提供しています。 - -まずは例を挙げて説明します。 -articlesという名前のテーブルがあるとして、前節で示した例の フィクスチャを変更します。 -(**tests/Fixture/ArticlesFixture.php**) を次のように変更します:: - - class ArticlesFixture extends TestFixture - { - public $import = ['table' => 'articles']; - } - -別の接続を使用したい場合は、以下を使用します:: - - class ArticlesFixture extends TestFixture - { - public $import = ['table' => 'articles', 'connection' => 'other']; - } - -通常、フィクスチャに沿ったTableクラスもあるはずです。 -それを使用してテーブル名を取得することも可能です:: - - class ArticlesFixture extends TestFixture - { - public $import = ['model' => 'Articles']; - } - -また、プラグインシンタックスにも対応しています。 - -既存のモデル/テーブルからテーブル定義をインポートするのは当然として、 -前のセクションで示したように、フィクスチャ上でレコードを直接定義することができます。 -例えば以下のようになります:: - - class ArticlesFixture extends TestFixture - { - public $import = ['table' => 'articles']; - public $records = [ - [ - 'title' => 'First Article', - 'body' => 'First Article Body', - 'published' => '1', - 'created' => '2007-03-18 10:39:23', - 'modified' => '2007-03-18 10:41:31' - ], - [ - 'title' => 'Second Article', - 'body' => 'Second Article Body', - 'published' => '1', - 'created' => '2007-03-18 10:41:23', - 'modified' => '2007-03-18 10:43:31' - ], - [ - 'title' => 'Third Article', - 'body' => 'Third Article Body', - 'published' => '1', - 'created' => '2007-03-18 10:43:23', - 'modified' => '2007-03-18 10:45:31' - ] - ]; - } - -最後に、フィクスチャでスキーマをロード/作成しないことも可能です。 -これは、すでにテスト用のデータベースを用意していて、空のテーブルをすべて作成している場合に便利です。 -フィクスチャに ``$fields`` も ``$import`` も定義しないことで、 -フィクスチャはレコードを挿入し、各テストメソッドでレコードを切り詰めるだけになります。 diff --git a/ja/plugins.rst b/ja/plugins.rst index e1a6c5721d..c01f802f30 100644 --- a/ja/plugins.rst +++ b/ja/plugins.rst @@ -1,6 +1,8 @@ プラグイン ############ +.. todo:: (Japanese) このファイルは https://github.com/cakephp/docs/pull/7813 においてCIのエラーを回避するために修正されましたが、きちんと翻訳が更新された訳ではありません。翻訳を頑張りましょう。 + CakePHP では、コントローラー・モデル・ビューの組み合わせを設定し、 他の CakePHP アプリケーションで使用できるよう事前にパッケージ化された アプリケーションプラグインとしてリリースできます。あなたのアプリケーションの１つに、 @@ -86,6 +88,8 @@ Composer を使ったプラグインのインストール php composer.phar dumpautoload +.. _loading-a-plugin: + プラグインの読み込み ==================== From 2bdc2f3a0d7532c9ec6487808c64c4d580a18bd3 Mon Sep 17 00:00:00 2001 From: Tadahisa MOTO-OKA Date: Fri, 1 Mar 2024 20:01:03 +0900 Subject: [PATCH 169/337] temporary fix of missing link in ja/development/testing.rst --- ja/development/testing.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/ja/development/testing.rst b/ja/development/testing.rst index 309be61f9a..49680b3b87 100644 --- a/ja/development/testing.rst +++ b/ja/development/testing.rst @@ -1,6 +1,8 @@ テスト ####### +.. todo:: (Japanese) このファイルは https://github.com/cakephp/docs/pull/7813 においてCIのエラーを回避するために修正されましたが、きちんと翻訳が更新された訳ではありません。翻訳を頑張りましょう。 + CakePHP には `PHPUnit `_ をベースとした高度なインテグレーションが組み込まれており、PHPUnit 本体が持つ機能に加えて、CakePHPでテストをスマートに管理するための便利な拡張機能を備えています。このセクションでは、PHPUnit のインストールからユニットテストの 始め方、そしてCakePHP が提供する拡張機能について説明します。 @@ -399,7 +401,7 @@ PHPUnitの設定 -※リスナーは非推奨であり、 :doc:`フィクスチャ構成を更新` する必要があります。 +※リスナーは非推奨であり、フィクスチャ構成を更新する必要があります。 .. _creating-test-database-schema: @@ -544,7 +546,7 @@ SQLダンプファイルをロードしたい場合は、下記のメソッド .. versionchanged:: 4.3.0 - 4.3.0より前のフィクスチャは、テーブルのスキーマも定義していました。フィクスチャでスキーマを定義する必要がある場合は、 :ref:`fixture-schema` を確認できます。 + 4.3.0より前のフィクスチャは、テーブルのスキーマも定義していました。フィクスチャでスキーマを定義する必要がある場合は、fixture-schema を確認できます。 動的データ -------------- From 153c4892a2ec4c21deed1d87a9d2566c5e1625af Mon Sep 17 00:00:00 2001 From: JohanIclicks <85666871+JohanIclicks@users.noreply.github.com> Date: Fri, 8 Mar 2024 11:12:47 +0100 Subject: [PATCH 170/337] Update query-builder.rst resultsArray needs to call ->all() first before it can call toList() --- en/orm/query-builder.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 74c55a8f0f..0762f72bdf 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -97,6 +97,7 @@ The easiest way is to either call the ``all()`` or ``toList()`` methods:: $resultsArray = $articles ->find() ->where(['id >' => 1]) + ->all() ->toList(); foreach ($resultsArray as $article) { From f5414d4a17d17076d8c863ecac5806bfc010c49f Mon Sep 17 00:00:00 2001 From: ADmad Date: Sat, 9 Mar 2024 00:41:58 +0530 Subject: [PATCH 171/337] Fix class name --- en/controllers/pagination.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/controllers/pagination.rst b/en/controllers/pagination.rst index 1e91b6e738..903f541744 100644 --- a/en/controllers/pagination.rst +++ b/en/controllers/pagination.rst @@ -269,7 +269,7 @@ Using a paginator class directly You can also use a paginator directly.:: // Create a paginator - $paginator = new \Cake\Datasource\Paginator\Paginator(); + $paginator = new \Cake\Datasource\Paginator\NumericPaginator(); // Paginate the model $results = $paginator->paginate( From 5332640e5ca5933aa8c6330136aa21742f29f147 Mon Sep 17 00:00:00 2001 From: othercorey Date: Sat, 9 Mar 2024 20:51:37 -0600 Subject: [PATCH 172/337] Fix code quoting --- en/appendices/5-0-migration-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 0d4ccde413..cefc55ef43 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -59,8 +59,8 @@ Cache 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()`. +- ``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 ------- From 0df1db7998d061cb2a3a7afb58d7ca35d4f0b503 Mon Sep 17 00:00:00 2001 From: Tadahisa MOTO-OKA Date: Mon, 11 Mar 2024 17:50:31 +0900 Subject: [PATCH 173/337] complete Japanese translation of Migration Guides on CakePHP 5 --- ja/appendices/5-0-migration-guide.rst | 287 ++++++++++---------------- ja/appendices/5-0-upgrade-guide.rst | 66 +++--- ja/appendices/phpunit10.rst | 44 ++-- 3 files changed, 158 insertions(+), 239 deletions(-) diff --git a/ja/appendices/5-0-migration-guide.rst b/ja/appendices/5-0-migration-guide.rst index 7969b8d2d9..0f2ae073f2 100644 --- a/ja/appendices/5-0-migration-guide.rst +++ b/ja/appendices/5-0-migration-guide.rst @@ -77,262 +77,199 @@ Controller - ``Controller::__construct()`` は削除されました。サブクラスでoverrideしていた場合は、コードの調整をお願いします。 - Component は、 Controller の読み込み後に dynamic property として設定されることは無くなりました。代わりに Controller は ``__get()`` を用いて Component へのアクセスを提供します。この変更は、 Component の存在有無を ``property_exists()`` でチェックしているアプリケーションに影響を与えます。 -- 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);``. +- Component が発行していた ``Controller.shutdown`` イベントは、 ``shutdown`` から ``afterFilter`` に名称変更されました。Controller に合わせるためです。これにより callback はより首尾一貫したものとなります。 +- ``PaginatorComponent`` は削除されました。代わりに、 Controller で ``$this->paginate()`` を呼び出すか、直接 ``Cake\Datasource\Paging\NumericPaginator`` を用いて下さい。 +- ``RequestHandlerComponent`` は削除されました。アップグレード方法は `4.4 移行ガイド `__ を参照して下さい。 +- ``SecurityComponent`` は削除されました。代わりに ``FormProtectionComponent`` で耐タンパ性を得たり、 ``HttpsEnforcerMiddleware`` を使って HTTPS を強制したりして下さい。 +- ``Controller::paginate()`` は、その引数 ``$settings`` において ``contain`` オプション等を受け付けなくなりました。代わりに ``finder`` オプションを使って ``$this->paginate($this->Articles, ['finder' => 'published'])`` などとして下さい。事前にクエリを組み立てておいてそれを ``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. +- 関数 ``getTypeName()`` は削除されました。代わりに、PHPの ``get_debug_type()`` をお使い下さい。 +- 依存ライブラリ ``league/container`` は ``4.x`` に更新されました。これによって ``ServiceProvider`` の実装には追加の型ヒントが必要となります。 +- ``deprecationWarning()`` には引数 ``$version`` が追加されました。 +- ``App.uploadedFilesAsObjects`` オプションは、PHPそのもののファイルアップロードにおける array 生成に倣い、削除されました。 +- ``ClassLoader`` は削除されました。代わりに Composer の autoload の仕組みをお使い下さい。 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. +- ``DateTimeType`` および ``DateType`` は、常に変更不可能(immutable)なオブジェクトを返すようになりました。また、 ``Date`` オブジェクトの interface は ``ChronosDate`` の interface を反映するようになり、CakePHP 4.x で存在した時刻関連のメソッドが無くなりました。 +- ``DateType::setLocaleFormat()`` は array を受け付けないようになりました。 +- ``Query`` は ``callable`` ではなく ``\Closure`` なパラメータのみを受け付けるようになりました。 callable なオブジェクトは PHP 8.1 で導入された、第一級 callable の記法で書き換え可能です。（訳注 : `PHPのマニュアル 「第一級callableを生成する記法」 `_ ） +- ``Query::execute()`` は、結果を整形するコールバックを呼ばないようになりました。代わりに ``Query::all()`` をお使い下さい。 +- ``TableSchemaAwareInterface`` は削除されました。 +- ``Driver::quote()`` は削除されました。代わりに prepared statement をお使い下さい。 +- ``Query::orderBy()`` は ``Query::order()`` の代わりに追加されました。 +- ``Query::groupBy()`` は ``Query::group()`` の代わりに追加されました。 +- ``SqlDialectTrait`` は削除されました。ここで提供されていた全ての機能は ``Driver`` クラスそのものに実装されました。 +- ``CaseExpression`` は削除されました。代わりに ``QueryExpression::case()`` または ``CaseStatementExpression`` をお使い下さい。 +- ``Connection::connect()`` は削除されました。代わりに ``$connection->getDriver()->connect()`` をお使い下さい。 +- ``Connection::disconnect()`` は削除されました。代わりに ``$connection->getDriver()->disconnect()`` をお使い下さい。 +- クエリのログの scope として ``queriesLog`` だけではなく ``cake.database.queries`` も使えるようになりました。 +- 結果セットのバッファリングを有効化・無効化する機能は削除されました。常にバッファリングされます。 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. +- ``getAccessible()`` メソッドが ``EntityInterface`` に追加されました。ORM外でこの interface を実装している場合は、このメソッドも実装する必要があります。 +- ``aliasField()`` メソッドが ``RepositoryInterface`` に追加されました。ORM外でこの interface を実装している場合は、このメソッドも実装する必要があります。 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 +- Event に載せるデータ(payload) は、配列である必要があります。配列ではないオブジェクト、例えば ``ArrayAccess`` は array へのキャストで失敗して ``TypeError`` を出すようになります。 +- イベントハンドラは void メソッドとして実装し、結果は返り値として返却するのではなく ``$event->setResult()`` に渡す方法が推奨されます。 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()`` +- ``ErrorHandler`` および ``ConsoleErrorHandler`` は削除されました。対応方法は `4.4 移行ガイド `__ をご覧下さい。 +- ``ExceptionRenderer`` は削除されました。代わりに ``WebExceptionRenderer`` をお使い下さい。 +- ``ErrorLoggerInterface::log()`` は削除されました。代わりに ``ErrorLoggerInterface::logException()`` をお使い下さい。 +- ``ErrorLoggerInterface::logMessage()`` は削除されました。代わりに ``ErrorLoggerInterface::logError()`` をお使い下さい。 Filesystem ---------- -- The Filesystem package was removed, and ``Filesystem`` class was moved to the Utility package. +- Filesystem というパッケージは削除されました。 ``Filesystem`` というクラスは Utility のパッケージに移動されました。 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. +- ``ServerRequest`` の ``files`` は、 array とは互換性は無くなりました。この挙動は 4.1.0 でデフォルトでは停止されていました。この ``files`` は常に ``UploadedFileInterfaces`` オブジェクトを持つようになります。 I18n ---- -- ``FrozenDate`` was renamed to `Date` and ``FrozenTime`` was renamed to `DateTime`. -- ``Time`` now extends ``Cake\Chronos\ChronosTime`` and is therefore immutable. -- ``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``). +- ``FrozenDate`` は `Date` に名称変更され、また ``FrozenTime`` も `DateTime` に名称変更されました。 +- ``Time`` は ``Cake\Chronos\ChronosTime`` を継承するようになりました。その結果として変更不可能(immutable)になりました。 +- ``Date::parseDateTime()`` は削除されました。 +- ``Date::parseTime()`` は削除されました。 +- ``Date::setToStringFormat()`` および ``Date::setJsonEncodeFormat()`` は、配列を受け付けないようになりました。 +- ``Date::i18nFormat()`` および ``Date::nice()`` は、タイムゾーンの引数を受け付けないようになりました。 +- ベンダ名が接頭辞に付いたプラグイン（例えば ``FooBar/Awesome``）への翻訳ファイルは、接頭辞を含むファイル名として下さい（例えば ``foo_bar_awesome.po``）。これは、同名の接頭辞無しのプラグイン（例えば ``Awesome``）の翻訳ファイル（この例では ``awesome.po``）との衝突を避けるためのものです。 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. +- Logエンジンの設定において、特定のスコープを無効化する際には ``false`` ではなくて ``null`` を用いるようになりました。設定ファイルにおいて ``'scopes' => false`` となっている箇所は ``'scopes' => null`` と書き換えて下さい。 Mailer ------ -- ``Email`` has been removed. Use `Mailer `__ instead. -- ``cake.mailer`` has been added as an alternative to the ``email`` scope +- ``Email`` は削除されました。代わりに `Mailer `__ をお使い下さい。 +- ログのスコープとして ``email`` の代わりに ``cake.mailer`` も指定できるようになりました。 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. +- ``EntityTrait::has()`` は、属性が存在してその値が ``null`` である場合、 ``true`` を返すようになりました。過去のCakePHPのバージョンにおいては ``false`` を返していました。4.x の挙動が必要な場合の対応方法は、4.5.0 のリリースノートを参照して下さい。（訳注 : 4.5のリリースノートは日本語には翻訳されていません。 `英語版の 4.5 の Migration Guide `_ の中では ``EntityTrait::hasValue()`` を使うように案内されています。） +- ``EntityTrait::extractOriginal()`` は ``extractOriginalChanged()`` と同様に、存在するフィールドのみを返すようになりました。 +- Finder の引数は連想配列である必要があります。過去にはこれは推奨事項という位置付けでした。 +- ``TranslateBehavior`` はデフォルトでは ``ShadowTable`` ストラテジを採用するようになりました。もしも ``Eav`` ストラテジを利用中で、その挙動を維持する必要があるのならば、設定を変更する必要があります。 +- ``isUnique`` ルールの ``allowMultipleNulls`` オプションは、デフォルトではtrueとなり、本来の 3.x の挙動に合致するようになりました。 +- ``Table::query()`` は、後述のクエリタイプごとのメソッドが提供されたことに伴い、削除されました。（訳注 : 5.0.5 時点においては実際には削除されておらず、 ``Table::query()`` は ``Table::selectQuery()`` を呼び出しているようです。） +- ``Table::updateQuery()``, ``Table::selectQuery()``, ``Table::insertQuery()``, ``Table::deleteQuery()`` の4つのメソッドが追加されました。これらは以下に示すクエリタイプごとのオブジェクトを返します。 +- ``SelectQuery``, ``InsertQuery``, ``UpdateQuery``, ``DeleteQuery`` の4つの型が追加されました。クエリのタイプが型として指定されることで、クエリタイプが変更されたり、無関係な別のクエリタイプの関数を呼んだりするのを防ぐようになりました。 +- ``Table::_initializeSchema()`` は削除されました。代わりに ``initialize()`` の中で ``$this->getSchema()`` を呼んで下さい。 +- ``SaveOptionsBuilder`` は削除されました。通常の配列をお使い下さい。 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. +- ``Router`` のstaticメソッドの ``connect()``, ``prefix()``, ``scope()``, ``plugin()`` は削除されました。代わりに ``RouteBuilder`` のインスタンスのメソッドをお使い下さい。 +- ``RedirectException`` は削除されました。代わりに ``\Cake\Http\Exception\RedirectException`` をお使い下さい。 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. +- ``TestSuite`` は削除されました。単体テストの設定をカスタマイズするには、環境変数を使って下さい。 +- ``TestListenerTrait`` は削除されました。PHPUnitがこれらの listener のサポートを打ち切ったためです。詳細は :doc:`/appendices/phpunit10` を参照して下さい。 +- ``IntegrationTestTrait::configRequest()`` が複数回呼ばれた際、設定を上書きするのではなく merge するようになりました。 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\```. +- ``Validation::isEmpty()`` は、ファイルアップロードの配列には対応しないようになりました。PHPのファイルアップロードの配列への対応は ``ServerRequest`` からも削除されていますので、この問題はテストの外側の問題だとは捉えないようにして下さい。 +- 以前は、ほとんどの validation エラーの文言は ``The provided value is invalid`` という単純なものでした。今では例えば ``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 +- ``ViewBuilder`` のオプションは、本当の意味で連想配列となりました（stringのキーを用います）。 +- ``NumberHelper`` および ``TextHelper`` は ``engine`` 設定を受け付けないようになりました。 +- ``ViewBuilder::setHelpers()`` のパラメータ ``$merge`` は削除されました。代わりに ``ViewBuilder::addHelpers()`` をお使い下さい。 +- ``View::initialize()`` の中では、 ``loadHelper()`` よりも ``addHelper()`` の方が望ましいようになりました。設定されたヘルパーはいずれにせよ後で読み込まれます。 +- ``View\Widget\FileWidget`` は、PHPのファイルアップロードの配列とは互換性が無くなりました。この変更は ``ServerRequest`` や ``Validation`` と同じ趣旨のものです。 +- ``FormHelper`` は、CSRF対策トークンのフィールドでは ``autocomplete=off`` を設定しないようになりました。これはSafariのバグへの応急措置として設定されましたが、今ではもう関係はありません。 + +非推奨 ============ -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. +以下は非推奨となったメソッド、プロパティ、挙動の一覧です。これらの機能は 5.x では動作し続けますが、 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. +- ``Query::order()`` は非推奨となりました。代わりに ``Query::orderBy()`` をお使い下さい。この変更はSQL文の機能名称に合わせたものになります。 +- ``Query::group()`` は非推奨となりました。代わりに ``Query::groupBy()`` をお使い下さい。この変更はSQL文の機能名称に合わせたものになります。 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)``. +- ``Table::find()`` のオプションを配列で指定することは非推奨となりました。代わりに `名前付き引数 `__ を使用して下さい。例えば ``find('all', ['conditions' => $array])`` の代わりに ``find('all', conditions: $array)`` です。カスタムの finder オプションについても同様に ``find('list', ['valueField' => 'name'])`` の代わりに ``find('list', valueField: 'name')`` を使用して下さい。複数の名前付き引数の場合は例えば ``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. +CakePHP 5 は、PHP 8.1 以上で有効な型システムを活用します。 +CakePHPは ``assert()`` を使うことによっても、詳細なエラーメッセージや、型の安全性を提供します。 +本番運用モードにおいては、 ``assert()`` でのコード生成を停止させてパフォーマンスを向上させることができます。 +この方法については :ref:`symlink-assets` を参照して下さい。（訳注 : このリンク先は、2024年3月時点ではまだ翻訳されていません。 `英語版 `__ で ``zend.assertions`` を設定している箇所を参照して下さい。） 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()`` +- コールバック関数を用いて重複した値を除去するメソッド ``unique()`` が追加されました。 +- ``reject()`` は、trueっぽい値のみを除外するデフォルトのコールバック関数が利用可能になりました。これは ``filter()`` のデフォルトの挙動の真逆となります。 Core ---- -- The ``services()`` method was added to ``PluginInterface``. -- ``PluginCollection::addFromConfig()`` has been added to :ref:`プラグインの読み込み `. +- ``PluginInterface`` には ``services()`` メソッドが追加されました。 +- :ref:`プラグインの読み込み ` に ``PluginCollection::addFromConfig()`` が追加されました。 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. +- ``ConnectionManager``は read / write の接続ロールをサポートしました。データベース接続設定において ``read`` や ``write`` のキーで指定した設定項目によって共通の設定項目を上書きすることで、接続ロールを構成することができます。 +- 結果セットを整形するコールバックを実行できるメソッド ``Query::all()`` が追加されました。 +- SQLにコメントを追加するメソッド ``Query::comment()`` が追加されました。これによりクエリのデバッグが楽になります。 +- PHPの enum と、データベースの string や integer 型との間の橋渡しをする ``EnumType`` が追加されました。 +- ``DriverInterface`` に ``getMaxAliasLength()`` と ``getConnectionRetries()`` が追加されました。 +- 以前は integer 型の主キー全てに自動的に auto-increment 指定を入れていましたが、 "id" という名前の integer 型の主キーにのみこの動作をするようになりました。 'autoIncrement' を false に設定することで、この挙動を無効にできます。 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. +- `PSR-17 `__ factory interface への対応が追加されました。これによって ``cakephp/http`` パッケージは、 php-http のように自動で interface resolution を有効にするライブラリに対してclient実装を提供できるようになりました。 +- 例外を発することなく便利に cookie を操作できる方法として ``CookieCollection::__get()`` と ``CookieCollection::__isset()`` が追加されました。 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:: +モデルのエンティティには opt-in 方式で利用可能な新しい機能、より厳格なプロパティ操作、が追加されました。 +この新しい機能は「必須フィールド」と呼ばれます。 +有効化されると、エンティティで定義されていないプロパティにアクセスした場合に例外が発生します。 +これは以下のようなコードに影響を与えます:: $entity->get(); $entity->has(); @@ -340,17 +277,16 @@ exceptions. This impacts the following usage:: 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. - +フィールドは ``array_key_exists`` が true を返す場合に「定義されている」と判断されます。 +これは null 値も含まれます。 +この機能はうんざりするようなものであるかもしれないので、5.0 まで導入が延期されてきました。 +将来はこれをデフォルトでオンにしようと検討していますが、フィードバックがあればぜひお知らせ下さい。 -Typed Finder Parameters +型付きFinderパラメータ ----------------------- -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:: +テーブルの finder のパラメータは必須のものにすることができるようになりました。 +例えばブログ記事の投稿をカテゴリまたはユーザで検索するメソッドは、以前はこのようなコードになりました:: public function findByCategoryOrUser(SelectQuery $query, array $options) { @@ -364,7 +300,7 @@ For e.g. a finder for fetching posts by category or user:: return $query; } -can now be written as:: +これが今では次のように書くことができます:: public function findByCategoryOrUser(SelectQuery $query, ?int $categoryId = null, ?int $userId = null) { @@ -378,11 +314,10 @@ can now be written as:: 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])``. +この finder を呼び出す際は ``find('byCategoryOrUser', userId: $somevar)`` と書くことができます。 +さらに、特別な名前付き引数を用いて、条件を追加することもできます。例えば ``find('byCategoryOrUser', userId: $somevar, conditions: ['enabled' => true])`` のようになります。 -A similar change has been applied to the ``RepositoryInterface::get()`` method:: +同様の変更が ``RepositoryInterface::get()`` にも追加されました:: public function view(int $id) { @@ -392,7 +327,7 @@ A similar change has been applied to the ``RepositoryInterface::get()`` method:: ]); } -can now be written as:: +以前は上記のようなコードでしたが、今後は以下のようにも書けます:: public function view(int $id) { @@ -402,10 +337,8 @@ can now be written as:: TestSuite --------- -- ``IntegrationTestTrait::requestAsJson()`` has been added to set JSON headers for the next request. +- Integrationテストにおいて、次に発行するリクエストのヘッダに、JSON でやり取りする趣旨のヘッダを付与するメソッド ``IntegrationTestTrait::requestAsJson()`` が追加されました。 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``. +- プラグインのインストーラが更新されて、プラグインのクラスの autoload を自動的に制御するようになりました。 ``composer.json`` から、名前空間とパスの対応関係マップを削除して、 ``composer dumpautoload`` を実行することでもプラグインを動作させられます。 diff --git a/ja/appendices/5-0-upgrade-guide.rst b/ja/appendices/5-0-upgrade-guide.rst index 5f34ec911c..39291c1b05 100644 --- a/ja/appendices/5-0-upgrade-guide.rst +++ b/ja/appendices/5-0-upgrade-guide.rst @@ -1,44 +1,41 @@ -5.0 Upgrade Guide -################# +5.0 アップグレードガイド +######################### -First, check that your application is running on latest CakePHP 4.x version. +まず始めに、お手元のアプリケーションが CakePHP 4.x の最新バージョンで動作していることを確認して下さい。 -Fix Deprecation Warnings +非推奨警告の対応 ======================== -Once your application is running on latest CakePHP 4.x, enable deprecation warnings in **config/app.php**:: +CakePHP 4.x の最新バージョンで動作していることが確認できたら **config/app.php** の設定を変更して、非推奨警告を有効にします:: 'Error' => [ 'errorLevel' => E_ALL, ] -Now that you can see all the warnings, make sure these are fixed before proceeding with the upgrade. +これによって全ての警告が見えるようになります。アップグレードの作業を始める前に確実にこれを済ませておいて下さい。 -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. +- ``Table::query()`` は 4.5.0 で非推奨となりました。代わりに ``selectQuery()``, ``updateQuery()``, ``insertQuery()``, ``deleteQuery()`` を使用して下さい。 -Upgrade to PHP 8.1 -================== +PHP 8.1 にアップグレード +========================== -If you are not running on **PHP 8.1 or higher**, you will need to upgrade PHP before updating CakePHP. +もしもPHPのバージョンが **8.1 または それ以上** ではない場合、CakePHPのアップデートをする前にPHPのアップグレードをして下さい。 .. note:: - CakePHP 5.0 requires **a minimum of PHP 8.1**. + CakePHP 5.0 の実行には **最低でも PHP 8.1** が必要です。 .. _upgrade-tool-use: -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. + このアップグレード・ツールは、最新の CakePHP 4.x でのみ実行可能です。CakePHP を 5.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: +CakePHP 5 では、union型 や ``mixed`` 型を有効活用するので、メソッドのシグネチャやファイル名などで、後方互換性を持たない変更が多く含まれます。 +つまらない仕事をさっさと片付けるために、アップグレード用の CLI ツールを利用して下さい。 .. code-block:: console @@ -48,27 +45,20 @@ To help expedite fixing these tedious changes there is an upgrade CLI tool: git checkout 5.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 cakephp50 + bin/cake upgrade rector --rules chronos3 -Update CakePHP Dependency -========================= +CakePHPの依存関係の更新 +=========================== -After applying rector refactorings you need to upgrade CakePHP, its plugins, PHPUnit -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 -`__. +ツールでのアップグレードが完了した後には、 ``composer.json`` に示されている、CakePHPやそのプラグイン、PHPUnit、そしてその他の多くの依存関係をアップグレードしましょう。 +この作業の内容は、お手元のアプリケーションの状況によって変わりますので、 ``composer.json`` ファイルを、お手元のアプリケーションのものと、 CakePHP 5.x のアプリのテンプレート `cakephp/app `__ とで見比べると良いでしょう。 -After the version strings are adjusted in your ``composer.json`` execute -``composer update -W`` and check its output. +``composer.json`` のバージョンが調整されたら、 ``composer update -W`` を実行して、結果を確認しましょう。 -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 -`__. +次に、アプリケーションの他のファイルについても、アプリのテンプレート `cakephp/app `__ を見て、必要なアップデートを施します。 diff --git a/ja/appendices/phpunit10.rst b/ja/appendices/phpunit10.rst index ff93663740..efbef102ce 100644 --- a/ja/appendices/phpunit10.rst +++ b/ja/appendices/phpunit10.rst @@ -1,65 +1,61 @@ -PHPUnit 10 Upgrade -################## +PHPUnit 10 へのアップグレード +############################## -With CakePHP 5 the minimum PHPUnit version has changed from ``^8.5 || ^9.3`` to ``^10.1``. -This introduces a few breaking changes from PHPUnit as well as from CakePHP's side. +CakePHP 5 では、PHPUnit の最低バージョンが ``^8.5 || ^9.3`` から ``^10.1`` に変更されました。 +この文書は、PHPUnit や CakePHP 由来の、いくつかの破壊的変更を紹介するものです。 -phpunit.xml adjustments +phpunit.xml の調整 ======================= -It is recommended to let PHPUnit update its configuration file via the following command:: +PHPUnitの設定ファイルを、以下のコマンドで更新することが推奨されます:: vendor/bin/phpunit --migrate-configuration .. note:: - Make sure you are already on PHPUnit 10 via ``vendor/bin/phpunit --version`` before executing this command! + 上記のコマンドを実行する前に、 ``vendor/bin/phpunit --version`` を実行して PHPUnit 10 が実行されていることを確認して下さい。 -With this command out of the way your ``phpunit.xml`` already has most of the recommended changes present. +このコマンド（訳注 : ``vendor/bin/phpunit --migrate-configuration`` のこと）を実行することによって、お手元のプロジェクトの ``phpunit.xml`` ファイルには推奨される変更が適用された状態になります。 -New event system ----------------- +新しいイベントシステム +---------------------- -PHPUnit 10 removed the old hook system and introduced a new `Event system -`_ -which requires the following code in your ``phpunit.xml`` to be adjusted from:: +PHPUnit 10 は、古い hook の仕組みを削除した上で、新しい `イベントシステム `_ が導入されました。 +ここでは、以下に示すような ``phpunit.xml`` は…:: -to:: +次のように調整されます:: -``->withConsecutive()`` has been removed +``->withConsecutive()`` の削除 ======================================== -You can convert the removed ``->withConsecutive()`` method to a -working interim solution like you can see here:: +削除されたメソッド ``->withConsecutive()`` は、応急措置的に置き換え可能です。例えば以下のコードは:: ->withConsecutive(['firstCallArg'], ['secondCallArg']) -should be converted to:: +次のように置き換えられます:: ->with( ...self::withConsecutive(['firstCallArg'], ['secondCallArg']) ) -the static ``self::withConsecutive()`` method has been added via the ``Cake\TestSuite\PHPUnitConsecutiveTrait`` -to the base ``Cake\TestSuite\TestCase`` class so you don't have to manually add that trait to your Testcase classes. +``Cake\TestSuite\TestCase`` クラスには、 ``Cake\TestSuite\PHPUnitConsecutiveTrait`` 経由で、静的メソッド ``self::withConsecutive()`` が追加されました。なので、Testcase のクラスに手動で trait を仕込む必要はありません。 -data providers have to be static +data provider は static に ================================ -If your testcases leverage the data provider feature of PHPUnit then -you have to adjust your data providers to be static:: +お手元のプロジェクトのテストケースにおいて、PHPUnitの data provider 機能を活用している場合、それを static にする必要があります。例えば以下のコードは:: public function myProvider(): array -should be converted to:: +次のように置き換えて下さい:: public static function myProvider(): array From 24ee6da194f5d7ed06e0a475a18ea1ccdc87ad10 Mon Sep 17 00:00:00 2001 From: Tadahisa MOTO-OKA Date: Mon, 11 Mar 2024 17:53:50 +0900 Subject: [PATCH 174/337] Update PHPUnit Link --- en/appendices/phpunit10.rst | 2 +- es/appendices/phpunit10.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/en/appendices/phpunit10.rst b/en/appendices/phpunit10.rst index ff93663740..1cd56d3d3a 100644 --- a/en/appendices/phpunit10.rst +++ b/en/appendices/phpunit10.rst @@ -21,7 +21,7 @@ New event system ---------------- PHPUnit 10 removed the old hook system and introduced a new `Event system -`_ +`_ which requires the following code in your ``phpunit.xml`` to be adjusted from:: diff --git a/es/appendices/phpunit10.rst b/es/appendices/phpunit10.rst index f9071f0ef6..eb07323054 100644 --- a/es/appendices/phpunit10.rst +++ b/es/appendices/phpunit10.rst @@ -21,7 +21,7 @@ Nuevo sistema de eventos ------------------------ PHPUnit 10 eliminó el antiguo sistema de hook e introdujo un nuevo `Sistema de eventos -`_ +`_ Lo que requiere que se ajuste el siguiente código en su ``phpunit.xml`` desde:: From 10ec7d91fdb8b397f91b89802d918373f4826d5e Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 11 Mar 2024 13:55:05 -0400 Subject: [PATCH 175/337] Update component testing docs PHPUnit has deprecated the mock creation methods we were using in this example. By not using mocks we can test more of the actual functionality. Fixes cakephp/cakephp#17616 --- en/development/testing.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index 069d6fe934..45bc7e6514 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1680,14 +1680,13 @@ correctly by the ``adjust()`` method in our component. We create the file public function setUp(): void { parent::setUp(); - // Setup our component and fake test controller + // Setup our component and provide it a basic controller. + // If your component relies on Application features, use AppController. $request = new ServerRequest(); $response = new Response(); - $this->controller = $this->getMockBuilder('Cake\Controller\Controller') - ->setConstructorArgs([$request, $response]) - ->setMethods(null) - ->getMock(); + $this->controller = new Controller($request); $registry = new ComponentRegistry($this->controller); + $this->component = new PagematronComponent($registry); $event = new Event('Controller.startup', $this->controller); $this->component->startup($event); From bd50a304471b8218104c5abd068053a2fb99e5ec Mon Sep 17 00:00:00 2001 From: ADmad Date: Sat, 16 Mar 2024 13:10:59 +0530 Subject: [PATCH 176/337] Update 5-1-migration-guide.rst Refs cakephp/cakephp#17621 --- en/appendices/5-1-migration-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index ce00978760..e814a0bafa 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -17,6 +17,9 @@ Behavior Changes - 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. + Deprecations ============ From 47e4bc9902f376c28c8f29a89492b19c4e22ea6f Mon Sep 17 00:00:00 2001 From: ADmad Date: Sat, 16 Mar 2024 13:13:50 +0530 Subject: [PATCH 177/337] Update 5-1-migration-guide.rst Refs cakephp/cakephp#17628 --- en/appendices/5-1-migration-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index e814a0bafa..7ca4f323fd 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -20,6 +20,9 @@ Behavior Changes - ``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. + Deprecations ============ From 5501605a278daa55f663d60465d07fdd5b1f847f Mon Sep 17 00:00:00 2001 From: mscherer Date: Sat, 16 Mar 2024 19:34:49 +0100 Subject: [PATCH 178/337] Docs for enum additions. --- en/appendices/5-1-migration-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index e814a0bafa..561f919329 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -89,6 +89,8 @@ 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 ---- From 1247e2e2dac7309668f6c911d93508a59e490cfc Mon Sep 17 00:00:00 2001 From: othercorey Date: Mon, 18 Mar 2024 09:28:36 -0500 Subject: [PATCH 179/337] Add notes for pathCombine() https://github.com/cakephp/cakephp/pull/17630 --- en/appendices/5-1-migration-guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 9da9fe56d0..380553a2e8 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -59,6 +59,7 @@ 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. Http ---- From 8135712e8d2907bf4720153c35b40e1214622f87 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 24 Mar 2024 12:07:39 -0400 Subject: [PATCH 180/337] Remove docs for subcommands - Remove subcommand references from docs. - Add to the 5.0 migration guide as subcommands were not explicitly mentioned there previously. Fixes #7825 --- en/appendices/5-0-migration-guide.rst | 3 +++ en/console-commands/commands.rst | 2 +- en/console-commands/option-parsers.rst | 34 ++++++-------------------- 3 files changed, 11 insertions(+), 28 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index cefc55ef43..53223b3166 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -68,6 +68,9 @@ 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. diff --git a/en/console-commands/commands.rst b/en/console-commands/commands.rst index 0320143a2c..0b536146eb 100644 --- a/en/console-commands/commands.rst +++ b/en/console-commands/commands.rst @@ -482,7 +482,7 @@ Update the command class to the following:: } } -Now that we have an interactive subcommand, we can add a test case that tests +Now that we have an interactive command, we can add a test case that tests that we receive the proper response, and one that tests that we receive an incorrect response. Remove the ``testUpdateModified`` method and, add the following methods to **tests/TestCase/Command/UpdateTableCommandTest.php**:: diff --git a/en/console-commands/option-parsers.rst b/en/console-commands/option-parsers.rst index e9c0565ca7..ce25c19e99 100644 --- a/en/console-commands/option-parsers.rst +++ b/en/console-commands/option-parsers.rst @@ -194,32 +194,12 @@ Building a ConsoleOptionParser from an Array .. php:method:: buildFromArray($spec) -As previously mentioned, when creating subcommand option parsers, you can define -the parser spec as an array for that method. This can help make building -subcommand parsers easier, as everything is an array:: - - $parser->addSubcommand('check', [ - 'help' => __('Check the permissions between an ACO and ARO.'), - 'parser' => [ - 'description' => [ - __("Use this command to grant ACL permissions. Once executed, the "), - __("ARO specified (and its children, if any) will have ALLOW access "), - __("to the specified ACO action (and the ACO's children, if any)."), - ], - 'arguments' => [ - 'aro' => ['help' => __('ARO to check.'), 'required' => true], - 'aco' => ['help' => __('ACO to check.'), 'required' => true], - 'action' => ['help' => __('Action to check')], - ], - ], - ]); - -Inside the parser spec, you can define keys for ``arguments``, ``options``, -``description`` and ``epilog``. You cannot define ``subcommands`` inside an -array style builder. The values for arguments, and options, should follow the -format that :php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` and +Option parsers can also be defined as arrays. Within the array, you can define +keys for ``arguments``, ``options``, ``description`` and ``epilog``. The values +for arguments, and options, should follow the format that +:php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` and :php:func:`Cake\\Console\\ConsoleOptionParser::addOptions()` use. You can also -use buildFromArray on its own, to build an option parser:: +use ``buildFromArray`` on its own, to build an option parser:: public function getOptionParser() { @@ -287,8 +267,8 @@ returned as XML: cake bake --help xml cake bake -h xml -The above would return an XML document with the generated help, options, -arguments and subcommands for the selected shell. A sample XML document would +The above would return an XML document with the generated help, options, and +arguments for the selected shell. A sample XML document would look like: .. code-block:: xml From 60c6f4ae0b24b23520927e29830766a9e00f7dda Mon Sep 17 00:00:00 2001 From: Alejandro Ibarra Date: Wed, 27 Mar 2024 08:35:38 +0100 Subject: [PATCH 181/337] Add DDEV section to docs after cakephp type has been released --- en/installation.rst | 30 +++++++++++++++++++++++------- es/installation.rst | 30 ++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 7 deletions(-) diff --git a/en/installation.rst b/en/installation.rst index 935376b8a2..d7cdf766dd 100644 --- a/en/installation.rst +++ b/en/installation.rst @@ -117,19 +117,35 @@ Each time you run ``php composer.phar update`` you will receive patch releases for this minor version. You can instead change this to ``^5.0`` to also receive the latest stable minor releases of the ``5.x`` branch. -Installation using Oven +Installation using DDEV ----------------------- -Another quick way to install CakePHP is via `Oven `_. -It is a small PHP script which checks the necessary system requirements, -and creates a new CakePHP application. +Another quick way to install CakePHP is via `DDEV `_. +It is an open source tool for launching local web development environments. + +If you want to configure a new project, you just need:: + + mkdir my-cakephp-app + cd my-cakephp-app + ddev config --project-type=cakephp --docroot=webroot + ddev composer create --prefer-dist cakephp/app:~5.0 + ddev launch + +If you have an existing project:: + + git clone + cd + ddev config --project-type=cakephp --docroot=webroot + ddev composer install + ddev launch + +Please check `DDEV Docs `_ for details on how to install / update DDEV. .. note:: IMPORTANT: This is not a deployment script. It is aimed to help developers - install CakePHP for the first time and set up a development environment - quickly. Production environments should consider several other factors, like - file permissions, virtualhost configuration, etc. + to set up a development environment quickly. It is not intended for + production environments. Permissions =========== diff --git a/es/installation.rst b/es/installation.rst index 0a8bcb64e9..6a8cd489bc 100644 --- a/es/installation.rst +++ b/es/installation.rst @@ -91,6 +91,36 @@ Donde ```` es el nombre del branch que quieres seguir. Cada vez que ejecutes ``php composer.phar update`` recibirás las últimas actualizaciones del branch seleccionado. +Instalación usando DDEV +----------------------- + +Otra manera rápida de instalar CakePHP es via `DDEV `_. +DDEV es una herramienta de código abierto para lanzar ambientes de desarrollo web en local. + +Si quieres configurar un nuevo proyecto, sólo necesitas ejecutar:: + + mkdir my-cakephp-app + cd my-cakephp-app + ddev config --project-type=cakephp --docroot=webroot + ddev composer create --prefer-dist cakephp/app:~5.0 + ddev launch + +Si tienes un proyecto existente:: + + git clone + cd + ddev config --project-type=cakephp --docroot=webroot + ddev composer install + ddev launch + +Por favor revisa la `Documentación de DDEV `_ para más detalles de cómo instalar / actualizar DDEV. + +.. note:: + + IMPORTANTE: Ésto no es un script de despliegue. Su objetivo es ayudar desarrolladores a + configurar ambientes de desarrollo rápidamente. En ningún caso su intención es que sea utilizado + en ambientes de producción. + Permisos ======== From 8d4d1a511f002da1c8c2f5351ffd9bc226fc516d Mon Sep 17 00:00:00 2001 From: Tadahisa MOTO-OKA Date: Thu, 28 Mar 2024 02:10:14 +0900 Subject: [PATCH 182/337] Fix code quoting : apply 5332640e5ca5933aa8c6330136aa21742f29f147 to Japanese --- ja/appendices/5-0-migration-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/appendices/5-0-migration-guide.rst b/ja/appendices/5-0-migration-guide.rst index 0f2ae073f2..ae2dd33907 100644 --- a/ja/appendices/5-0-migration-guide.rst +++ b/ja/appendices/5-0-migration-guide.rst @@ -54,8 +54,8 @@ Cache Collection ---------- -- `combine()` は、指定した key path や group path が存在しないまたは null 値の場合に、例外を投げるようになりました。 - この挙動は、 `indexBy()` や `groupBy()` と同じです。 +- ``combine()`` は、指定した key path や group path が存在しないまたは null 値の場合に、例外を投げるようになりました。 + この挙動は、 ``indexBy()`` や ``groupBy()`` と同じです。 Console ------- From 2ae3b43ad80fb6a626108331506539d8c938280a Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 31 Mar 2024 12:10:24 +0530 Subject: [PATCH 183/337] Add info about TestCase::loadPlugins() change --- en/appendices/5-1-migration-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 380553a2e8..04683c1c43 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -23,6 +23,9 @@ Behavior Changes - ``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. + Deprecations ============ From 408a9c89cb7478997d1a41d27c1268c4bb51c593 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 1 Apr 2024 11:09:23 -0400 Subject: [PATCH 184/337] Add docs for cakephp/cakephp#17634 --- en/appendices/5-1-migration-guide.rst | 7 +++++++ en/orm/validation.rst | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 04683c1c43..eb1383b555 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -64,6 +64,13 @@ Core 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. +Datasource +---------- + +- ``RulesChecker::remove()``, ``removeCreate()``, ``removeUpdate()``, and + ``removeDelete()`` methods were added. These methods allow you to remove rules + by name. + Http ---- diff --git a/en/orm/validation.rst b/en/orm/validation.rst index 4b89481870..86fe8d9422 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -742,3 +742,22 @@ The same result can be expected when using ``newEntity()`` or $userEntity = $usersTable->newEntity(['email' => 'not an email!!']); $userEntity->getError('email'); // Invalid email + +Removing Rules +-------------- + +If you need to remove rules from a ``RulesChecker`` use a remove method:: + + // Remove a general rule by name + $rules->remove('ruleName'); + + // Remove a create rule + $rules->removeCreate('ruleName'); + + // Remove an update rule + $rules->removeUpdate('ruleName'); + + // Remove a delete rule + $rules->removeDelete('ruleName'); + +.. versionadded:: 5.1.0 From 645e629dc104def1d87f8642129d5df526eb2bcf Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 4 Apr 2024 07:53:25 +0530 Subject: [PATCH 185/337] Update request-response.rst Closes #7833 --- en/controllers/request-response.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 47f1c5671c..915afdb123 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -394,10 +394,10 @@ There are several built-in detectors that you can use: X-Requested-With = XMLHttpRequest. * ``is('ssl')`` Check to see whether the request is via SSL. * ``is('flash')`` Check to see whether the request has a User-Agent of Flash. -* ``is('json')`` Check to see whether the request has 'json' extension and - accept 'application/json' mimetype. -* ``is('xml')`` Check to see whether the request has 'xml' extension and accept - 'application/xml' or 'text/xml' mimetype. +* ``is('json')`` Check to see whether the request URL has 'json' extension or the + `Accept` header is set to 'application/json'. +* ``is('xml')`` Check to see whether the request URL has 'xml' extension or the `Accept` header is set to + 'application/xml' or 'text/xml'. ``ServerRequest`` also includes methods like :php:meth:`Cake\\Http\\ServerRequest::domain()`, From 3a818e4e057ecdeaf90d6d88cc06c36373ee73ce Mon Sep 17 00:00:00 2001 From: Slava Basko Date: Mon, 8 Apr 2024 19:11:40 -0700 Subject: [PATCH 186/337] make it more clear that Bake plugin will generate templates that using Enum::label() method. --- en/orm/database-basics.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 402f9ecd8b..9ff32ccc40 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -489,6 +489,11 @@ CakePHP recommends a few conventions for enums: detection while running bake and to aid with project consistency. - Enum cases should use CamelCase style. +.. note:: + + If Enum is created by hands, but view templates were generated by Bake plugin — don't forget + to implement EnumLabelInterface in your Enum. + .. _adding-custom-database-types: Adding Custom Types From 4d621bcf6fa223eb6102472e65930e4486060f0d Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 8 Apr 2024 23:31:58 -0400 Subject: [PATCH 187/337] Document changes in cakephp/cakephp#17656 --- en/appendices/5-1-migration-guide.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index eb1383b555..f93a1d56ae 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -64,6 +64,12 @@ Core 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. +Database +-------- + +- ``SelectQuery::__debugInfo()`` now includes which connection role the query + is for. + Datasource ---------- From 21db637fe56890554b9cd725c25192006ab55380 Mon Sep 17 00:00:00 2001 From: othercorey Date: Tue, 9 Apr 2024 03:08:58 -0500 Subject: [PATCH 188/337] Notes for https://github.com/cakephp/cakephp/pull/17658 --- en/appendices/5-1-migration-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index f93a1d56ae..c700547998 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -8,6 +8,8 @@ removed in 6.0.0. Behavior Changes ================ +- Connection now creats 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 From 712679c43631aedbc7694167d9501a33ee430415 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Wed, 10 Apr 2024 19:59:02 -0400 Subject: [PATCH 189/337] Demote note into a bullet point. Refs #7835 --- en/orm/database-basics.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 9ff32ccc40..68b8ac3ec8 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -488,11 +488,9 @@ CakePHP recommends a few conventions for enums: - Enum classnames should follow ``{Entity}{ColumnName}`` style to enable detection while running bake and to aid with project consistency. - Enum cases should use CamelCase style. +- Enums should implement the ``Cake\Database\Type\\EnumLabelInterface`` to + improve compatibility with bake, and ``FormHelper``. -.. note:: - - If Enum is created by hands, but view templates were generated by Bake plugin — don't forget - to implement EnumLabelInterface in your Enum. .. _adding-custom-database-types: From 90041d21d33047bd985a26b2684547110848716e Mon Sep 17 00:00:00 2001 From: othercorey Date: Wed, 10 Apr 2024 23:40:11 -0500 Subject: [PATCH 190/337] Notes for https://github.com/cakephp/cakephp/pull/17643 --- en/appendices/5-1-migration-guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index c700547998..09a8536b58 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -52,6 +52,7 @@ 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. Console ------- From a06bf2060325255354b1cc69a6f6eea241fe9678 Mon Sep 17 00:00:00 2001 From: othercorey Date: Wed, 10 Apr 2024 23:47:41 -0500 Subject: [PATCH 191/337] Fix quote --- en/appendices/5-1-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 09a8536b58..e0d29f09c1 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -9,7 +9,7 @@ Behavior Changes ================ - Connection now creats unique read and write drivers if the keys ``read`` or - ``write` are present in the config regardless of values. + ``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 From 226a5e9a872eb2712db222f5be46420f0e710b61 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 11 Apr 2024 10:39:22 -0400 Subject: [PATCH 192/337] Fix typo --- en/orm/database-basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 68b8ac3ec8..0ae41e0852 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -488,7 +488,7 @@ CakePHP recommends a few conventions for enums: - Enum classnames should follow ``{Entity}{ColumnName}`` style to enable detection while running bake and to aid with project consistency. - Enum cases should use CamelCase style. -- Enums should implement the ``Cake\Database\Type\\EnumLabelInterface`` to +- Enums should implement the ``Cake\Database\Type\EnumLabelInterface`` to improve compatibility with bake, and ``FormHelper``. From a0704119753aa30684826c3a28c38c0241dcb13c Mon Sep 17 00:00:00 2001 From: mnishig Date: Thu, 18 Apr 2024 10:01:59 +0900 Subject: [PATCH 193/337] Update database.rst --- ja/tutorials-and-examples/cms/database.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/ja/tutorials-and-examples/cms/database.rst b/ja/tutorials-and-examples/cms/database.rst index 78c6f16be3..2f93f9891b 100644 --- a/ja/tutorials-and-examples/cms/database.rst +++ b/ja/tutorials-and-examples/cms/database.rst @@ -113,6 +113,8 @@ CakePHP のモデルは ``Table`` と ``Entity`` オブジェクトで構成さ addBehavior('Timestamp'); } } @@ -152,9 +155,12 @@ Table オブジェクトを ``ArticlesTable`` と名付けることで、CakePHP class Article extends Entity { protected array $_accessible = [ - '*' => true, - 'id' => false, - 'slug' => false, + 'title' => true, + 'body' => true, + 'published' => true, + 'created' => true, + 'modified' => true, + 'users' => true, ]; } From 42ff37df2276e3299951aa0ae20de54cee8d5032 Mon Sep 17 00:00:00 2001 From: mnishig Date: Thu, 18 Apr 2024 10:07:50 +0900 Subject: [PATCH 194/337] Update articles-controller.rst The index() function update that it is same code english version. --- ja/tutorials-and-examples/cms/articles-controller.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ja/tutorials-and-examples/cms/articles-controller.rst b/ja/tutorials-and-examples/cms/articles-controller.rst index 0b5dbd3555..1ed95213c8 100644 --- a/ja/tutorials-and-examples/cms/articles-controller.rst +++ b/ja/tutorials-and-examples/cms/articles-controller.rst @@ -32,8 +32,7 @@ CMS チュートリアル - Articles コントローラーの作成 { public function index() { - $this->loadComponent('Paginator'); - $articles = $this->Paginator->paginate($this->Articles->find()); + $articles = $this->paginate($this->Articles); $this->set(compact('articles')); } } From fa3bfff883d5a62c62702037552820655dd963fd Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 18 Apr 2024 11:17:35 +0530 Subject: [PATCH 195/337] Update schema of translations table example `NOT NULL` is not required for translated fields --- en/orm/behaviors/translate.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/orm/behaviors/translate.rst b/en/orm/behaviors/translate.rst index 0f8372c5a3..9a0f8f90a2 100644 --- a/en/orm/behaviors/translate.rst +++ b/en/orm/behaviors/translate.rst @@ -35,8 +35,8 @@ fields to be translated. For that we create a shadow table ``articles_translatio CREATE TABLE `articles_translations` ( `id` int(11) NOT NULL, `locale` varchar(5) NOT NULL, - `title` varchar(255) NOT NULL, - `body` text NOT NULL, + `title` varchar(255), + `body` text, PRIMARY KEY (`id`,`locale`) ); From d1e2d7ecbd61f64a99a7539c34617186baf50afc Mon Sep 17 00:00:00 2001 From: ashcolor <38287738+ashcolor@users.noreply.github.com> Date: Tue, 23 Apr 2024 17:18:52 +0900 Subject: [PATCH 196/337] Update installation.rst cakephp version I updated the installation procedure for CakePHP from version 4 to version 5 as the existing one was still for version 4. --- ja/tutorials-and-examples/cms/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/tutorials-and-examples/cms/installation.rst b/ja/tutorials-and-examples/cms/installation.rst index 23c8277b6d..8b0ccb4637 100644 --- a/ja/tutorials-and-examples/cms/installation.rst +++ b/ja/tutorials-and-examples/cms/installation.rst @@ -42,7 +42,7 @@ cURL がインストールされていたら、次のように実行するのが .. code-block:: console - php composer.phar create-project --prefer-dist cakephp/app:4.* cms + php composer.phar create-project --prefer-dist cakephp/app:5.* cms `Composer Windows Installer `_ をダウンロードして実行した場合、インストールディレクトリー (例えば、 C:\\wamp\\www\\dev\\cakephp3) @@ -50,7 +50,7 @@ cURL がインストールされていたら、次のように実行するのが .. code-block:: console - composer self-update && composer create-project --prefer-dist cakephp/app:4.* cms + composer self-update && composer create-project --prefer-dist cakephp/app:5.* cms Composer を使うメリットは、 正しいファイルパーミッションの設定や、 **config/app.php** ファイルの作成などのように、自動的に完全なセットアップをしてくれることです。 From 0f5f250edb187e03f5648b799b629a854444196a Mon Sep 17 00:00:00 2001 From: othercorey Date: Sun, 28 Apr 2024 23:40:06 -0500 Subject: [PATCH 197/337] Add notes for Hash::insert() and remove() --- en/appendices/5-1-migration-guide.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index e0d29f09c1..90295ca8e3 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -8,7 +8,7 @@ removed in 6.0.0. Behavior Changes ================ -- Connection now creats unique read and write drivers if the keys ``read`` or +- Connection now creats 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 @@ -107,6 +107,11 @@ TestSuite - ``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. +Utility +------- + +- ``Hash::insert()`` and ``Hash::remove()`` now accept ``ArrayAccess`` objects along with ``array`` data. + Validation ---------- From d4a214948a5b91bfcfa7d507f6ad2cde8afff098 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Thu, 2 May 2024 14:25:50 +0200 Subject: [PATCH 198/337] Grammar --- en/orm/validation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/validation.rst b/en/orm/validation.rst index 4b89481870..d9fc401001 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -574,7 +574,7 @@ those rules into re-usable classes:: $rules->add(new CustomRule(...), 'ruleName'); -By creating custom rule classes you can keep your code DRY and tests your domain +By creating custom rule classes you can keep your code DRY and test your domain rules in isolation. Disabling Rules From 761b70e1d70c08a6402e22187f200475d692bdef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=BCrth?= Date: Thu, 2 May 2024 14:27:28 +0200 Subject: [PATCH 199/337] Add clarifying comment about usage of custom rule This should clear up questions like this one: https://discourse.cakephp.org/t/rule-isunique-and-allowmultiplenulls/9004 --- en/orm/validation.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/orm/validation.rst b/en/orm/validation.rst index d9fc401001..6100fd7a0f 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -534,6 +534,7 @@ Creating Custom re-usable Rules You may want to re-use custom domain rules. You can do so by creating your own invokable rule:: + // Using a custom rule of the application use App\ORM\Rule\IsUniqueWithNulls; // ... public function buildRules(RulesChecker $rules): RulesChecker From a0b9db252fe20a7c8513523e8e315e315804ad44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Seggewi=C3=9F?= <39218577+seggewiss@users.noreply.github.com> Date: Thu, 2 May 2024 19:50:27 +0200 Subject: [PATCH 200/337] Update installation.rst Running the provided install command leads to an error: `no matches found: cakephp/app:5.*` I removed the `.*` and the install was successful. --- en/tutorials-and-examples/cms/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/installation.rst b/en/tutorials-and-examples/cms/installation.rst index d7c7c3ab50..720be24a69 100644 --- a/en/tutorials-and-examples/cms/installation.rst +++ b/en/tutorials-and-examples/cms/installation.rst @@ -45,7 +45,7 @@ in the **cms** directory of the current working directory: .. code-block:: console - php composer.phar create-project --prefer-dist cakephp/app:5.* cms + php composer.phar create-project --prefer-dist cakephp/app:5 cms If you downloaded and ran the `Composer Windows Installer `_, then type the following line in From 7ca023126874715f656887895a3d1cac0b3ac2cc Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 3 May 2024 09:53:35 -0400 Subject: [PATCH 201/337] Add note for cakephp/cakephp#17676 --- en/appendices/5-1-migration-guide.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 90295ca8e3..dc66446bf5 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -8,23 +8,22 @@ removed in 6.0.0. Behavior Changes ================ -- Connection now creats unique read and write drivers if the keys ``read`` or +- 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. From fc70058eec590f309b6eb3626a774347918f79f2 Mon Sep 17 00:00:00 2001 From: Arhell Date: Mon, 6 May 2024 11:23:50 +0300 Subject: [PATCH 202/337] Update installation.rst (es, ja lang) --- es/tutorials-and-examples/cms/installation.rst | 2 +- ja/tutorials-and-examples/cms/installation.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/es/tutorials-and-examples/cms/installation.rst b/es/tutorials-and-examples/cms/installation.rst index 6df766aa26..66d05bf3fc 100644 --- a/es/tutorials-and-examples/cms/installation.rst +++ b/es/tutorials-and-examples/cms/installation.rst @@ -46,7 +46,7 @@ en la carpeta **cms** del directorio de trabajo actual: .. code-block:: console - php composer.phar create-project --prefer-dist cakephp/app:5.* cms + php composer.phar create-project --prefer-dist cakephp/app:5 cms Si ha descargado y ejecutado el `Instalador de Composer de Windows `_, entonces, escriba la siguiente línea en el diff --git a/ja/tutorials-and-examples/cms/installation.rst b/ja/tutorials-and-examples/cms/installation.rst index 8b0ccb4637..c16e23d19f 100644 --- a/ja/tutorials-and-examples/cms/installation.rst +++ b/ja/tutorials-and-examples/cms/installation.rst @@ -42,7 +42,7 @@ cURL がインストールされていたら、次のように実行するのが .. code-block:: console - php composer.phar create-project --prefer-dist cakephp/app:5.* cms + php composer.phar create-project --prefer-dist cakephp/app:5 cms `Composer Windows Installer `_ をダウンロードして実行した場合、インストールディレクトリー (例えば、 C:\\wamp\\www\\dev\\cakephp3) From f455951bdb1cbf4f6a733d8da4c39521d5880618 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 7 May 2024 18:08:53 -0400 Subject: [PATCH 203/337] Add migration notes for cakephp/cakephp#17654 --- en/appendices/5-1-migration-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index dc66446bf5..6429bd2209 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -57,6 +57,8 @@ Console ------- - ``Arguments::getBooleanOption()`` and ``Arguments::getMultipleOption()`` were added. +- ``Arguments::hasArgument()`` and ``getArgument()`` will now raise an exception + if an unknown argument name is provided. This helps prevent mixing up option/argument names. Core ---- From 0cd97ba460f8c72f7527738958eb1b95776d0ab2 Mon Sep 17 00:00:00 2001 From: Arhell Date: Mon, 13 May 2024 08:41:19 +0300 Subject: [PATCH 204/337] Update installation.rst (fr, pl) --- fr/tutorials-and-examples/cms/installation.rst | 2 +- pt/tutorials-and-examples/cms/installation.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/tutorials-and-examples/cms/installation.rst b/fr/tutorials-and-examples/cms/installation.rst index 2d69744e4d..5f0d15549c 100644 --- a/fr/tutorials-and-examples/cms/installation.rst +++ b/fr/tutorials-and-examples/cms/installation.rst @@ -45,7 +45,7 @@ d'application CakePHP dans le dossier **cms** du dossier courant: .. code-block:: console - php composer.phar create-project --prefer-dist cakephp/app:4.* cms + php composer.phar create-project --prefer-dist cakephp/app:5.* cms Si vous avez téléchargé et utilisé `l'Installer de Composer pour Windows `_, tapez la commande suivante dans diff --git a/pt/tutorials-and-examples/cms/installation.rst b/pt/tutorials-and-examples/cms/installation.rst index 1acd8315b6..a9e63cf316 100644 --- a/pt/tutorials-and-examples/cms/installation.rst +++ b/pt/tutorials-and-examples/cms/installation.rst @@ -48,7 +48,7 @@ esqueleto da aplicação do CakePHP no diretório **cms**. :: .. code-block:: console - php composer.phar create-project --prefer-dist cakephp/app:4.* cms + php composer.phar create-project --prefer-dist cakephp/app:5.* cms Caso você tenha feito o download e executado o `Instalador para Windows do Composer `_, então digite a linha From c9008578297ea0a46272ea6a4fb24b49678cafd1 Mon Sep 17 00:00:00 2001 From: "marc.wuerth" Date: Mon, 13 May 2024 09:46:32 +0200 Subject: [PATCH 205/337] Comment out ellipsis for better copy-paste-ability --- en/contributing/cakephp-coding-conventions.rst | 2 +- en/core-libraries/httpclient.rst | 16 ++++++++-------- en/orm/query-builder.rst | 2 +- en/orm/retrieving-data-and-resultsets.rst | 2 +- en/orm/validation.rst | 2 +- fr/core-libraries/httpclient.rst | 16 ++++++++-------- fr/orm/query-builder.rst | 2 +- fr/orm/retrieving-data-and-resultsets.rst | 12 ++++++------ fr/orm/validation.rst | 2 +- ja/contributing/cakephp-coding-conventions.rst | 2 +- ja/core-libraries/httpclient.rst | 16 ++++++++-------- ja/orm/retrieving-data-and-resultsets.rst | 2 +- ja/orm/validation.rst | 4 ++-- pt/core-libraries/httpclient.rst | 6 +++--- pt/orm/query-builder.rst | 2 +- pt/orm/retrieving-data-and-resultsets.rst | 2 +- 16 files changed, 45 insertions(+), 45 deletions(-) diff --git a/en/contributing/cakephp-coding-conventions.rst b/en/contributing/cakephp-coding-conventions.rst index 3f04fb3283..0e09182c56 100644 --- a/en/contributing/cakephp-coding-conventions.rst +++ b/en/contributing/cakephp-coding-conventions.rst @@ -265,7 +265,7 @@ Try to avoid unnecessary nesting by bailing early:: { ... if (!$success) { - throw new RuntimeException(...); + throw new RuntimeException(/* ... */); } ... diff --git a/en/core-libraries/httpclient.rst b/en/core-libraries/httpclient.rst index cdb11bcc3b..a4071cced6 100644 --- a/en/core-libraries/httpclient.rst +++ b/en/core-libraries/httpclient.rst @@ -45,9 +45,9 @@ Doing POST and PUT requests is equally simple:: ]); // Other methods as well. - $http->delete(...); - $http->head(...); - $http->patch(...); + $http->delete(/* ... */); + $http->head(/* ... */); + $http->patch(/* ... */); If you have created a PSR-7 request object you can send it using ``sendRequest()``:: @@ -502,11 +502,11 @@ is making:: There are methods to mock the most commonly used HTTP methods:: - $this->mockClientGet(...); - $this->mockClientPatch(...); - $this->mockClientPost(...); - $this->mockClientPut(...); - $this->mockClientDelete(...); + $this->mockClientGet(/* ... */); + $this->mockClientPatch(/* ... */); + $this->mockClientPost(/* ... */); + $this->mockClientPut(/* ... */); + $this->mockClientDelete(/* ... */); .. php:method:: newClientResponse(int $code = 200, array $headers = [], string $body = '') diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 0762f72bdf..3e336e9b87 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -457,7 +457,7 @@ complex expressions:: To build complex order clauses, use a Closure to build order expressions:: $query->orderAsc(function (QueryExpression $exp, SelectQuery $query) { - return $exp->addCase(...); + return $exp->addCase(/* ... */); }); diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index 1bb8bf0b95..55264ddd4e 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -614,7 +614,7 @@ Use the ``queryBuilder`` option to customize the query when using an array:: 'Authors' => [ 'foreignKey' => false, 'queryBuilder' => function (SelectQuery $q) { - return $q->where(...); // Full conditions for filtering + return $q->where(/* ... */); // Full conditions for filtering } ] ]); diff --git a/en/orm/validation.rst b/en/orm/validation.rst index 6100fd7a0f..36dbb62c3a 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -573,7 +573,7 @@ those rules into re-usable classes:: // Add the custom rule use App\Model\Rule\CustomRule; - $rules->add(new CustomRule(...), 'ruleName'); + $rules->add(new CustomRule(/* ... */), 'ruleName'); By creating custom rule classes you can keep your code DRY and test your domain rules in isolation. diff --git a/fr/core-libraries/httpclient.rst b/fr/core-libraries/httpclient.rst index d12596543c..76f40a7e95 100644 --- a/fr/core-libraries/httpclient.rst +++ b/fr/core-libraries/httpclient.rst @@ -46,9 +46,9 @@ Faire des requêtes POST et PUT est tout aussi simple:: ]); // Autres méthodes. - $http->delete(...); - $http->head(...); - $http->patch(...); + $http->delete(/* ... */); + $http->head(/* ... */); + $http->patch(/* ... */); Si vous avez créé un objet de requêtes PSR-7, vous pouvez l'envoyer avec ``sendRequest()``:: @@ -515,11 +515,11 @@ requêtes faites par votre application:: Il existe des méthodes pour mocker les méthodes HTTP les plus courantes:: - $this->mockClientGet(...); - $this->mockClientPatch(...); - $this->mockClientPost(...); - $this->mockClientPut(...); - $this->mockClientDelete(...); + $this->mockClientGet(/* ... */); + $this->mockClientPatch(/* ... */); + $this->mockClientPost(/* ... */); + $this->mockClientPut(/* ... */); + $this->mockClientDelete(/* ... */); .. php:method:: newClientResponse(int $code = 200, array $headers = [], string $body = '') diff --git a/fr/orm/query-builder.rst b/fr/orm/query-builder.rst index 6459b45551..9ddaa27788 100644 --- a/fr/orm/query-builder.rst +++ b/fr/orm/query-builder.rst @@ -478,7 +478,7 @@ des expressions complexes:: Pour construire des clauses de tri complexes, utilisez une Closure:: $query->orderAsc(function (QueryExpression $exp, Query $query) { - return $exp->addCase(...); + return $exp->addCase(/* ... */); }); Limiter les Résultats diff --git a/fr/orm/retrieving-data-and-resultsets.rst b/fr/orm/retrieving-data-and-resultsets.rst index 5458c77395..02613b7dd3 100644 --- a/fr/orm/retrieving-data-and-resultsets.rst +++ b/fr/orm/retrieving-data-and-resultsets.rst @@ -582,7 +582,7 @@ définir le second argument à ``true``:: $query = $articles->find(); $query->contain(['Authors', 'Comments'], true); - + .. note:: Les noms d'association dans les appels à ``contain()`` doivent respecter la @@ -667,7 +667,7 @@ passez un tableau:: 'Authors' => [ 'foreignKey' => false, 'queryBuilder' => function (Query $q) { - return $q->where(...); // Conditions complètes pour le filtrage + return $q->where(/* ... */); // Conditions complètes pour le filtrage } ] ]); @@ -801,7 +801,7 @@ l'association et charger d'autres champs de cette même association, vous pouvez parfaitement combiner ``innerJoinWith()`` et ``contain()``. L'exemple ci-dessous filtre les Articles qui ont des Tags spécifiques et charge ces Tags:: - + $filter = ['Tags.name' => 'CakePHP']; $query = $articles->find() ->distinct($articles->getPrimaryKey()) @@ -820,9 +820,9 @@ ces Tags:: $query ->select(['country_name' => 'Countries.name']) ->innerJoinWith('Countries'); - + Sinon, vous verrez les données dans ``_matchingData``, comme cela a été - décrit ci-dessous à propos de ``matching()``. C'est un angle mort de + décrit ci-dessous à propos de ``matching()``. C'est un angle mort de ``matching()``, qui ne sait pas que vous avez sélectionné des champs. .. warning:: @@ -949,7 +949,7 @@ exemple des tables se trouvant dans deux bases de données différentes. Habituellement, vous définisser la stratégie d'une association quand vous la définissez, dans la méthode ``Table::initialize()``, mais vous pouvez changer manuellement la stratégie de façon permanente:: - + $articles->Comments->setStrategy('select'); Récupération Avec la Stratégie de Sous-Requête diff --git a/fr/orm/validation.rst b/fr/orm/validation.rst index 10038c0634..a361edac1e 100644 --- a/fr/orm/validation.rst +++ b/fr/orm/validation.rst @@ -610,7 +610,7 @@ utile de packager ces règles dans des classes réutilisables:: // Ajouter la règle personnalisée use App\Model\Rule\CustomRule; - $rules->add(new CustomRule(...), 'ruleName'); + $rules->add(new CustomRule(/* ... */), 'ruleName'); En ajoutant des classes de règles personnalisées, vous pouvez garder votre code DRY et tester vos règles de domaine isolément. diff --git a/ja/contributing/cakephp-coding-conventions.rst b/ja/contributing/cakephp-coding-conventions.rst index 4710962427..3fb88e7023 100644 --- a/ja/contributing/cakephp-coding-conventions.rst +++ b/ja/contributing/cakephp-coding-conventions.rst @@ -254,7 +254,7 @@ false を、関数呼び出しが成功したかどうかを判定できるよ { ... if (!$success) { - throw new RuntimeException(...); + throw new RuntimeException(/* ... */); } ... diff --git a/ja/core-libraries/httpclient.rst b/ja/core-libraries/httpclient.rst index 39ad5b8aa2..d635ad8bfe 100644 --- a/ja/core-libraries/httpclient.rst +++ b/ja/core-libraries/httpclient.rst @@ -49,9 +49,9 @@ POST や PUT のリクエストを実行することは、同様に簡単です ]); // 他のメソッドも同様に、 - $http->delete(...); - $http->head(...); - $http->patch(...); + $http->delete(/* ... */); + $http->head(/* ... */); + $http->patch(/* ... */); If you have created a PSR-7 request object you can send it using ``sendRequest()``:: @@ -507,11 +507,11 @@ is making:: There are methods to mock the most commonly used HTTP methods:: - $this->mockClientGet(...); - $this->mockClientPatch(...); - $this->mockClientPost(...); - $this->mockClientPut(...); - $this->mockClientDelete(...); + $this->mockClientGet(/* ... */); + $this->mockClientPatch(/* ... */); + $this->mockClientPost(/* ... */); + $this->mockClientPut(/* ... */); + $this->mockClientDelete(/* ... */); .. php:method:: newClientResponse(int $code = 200, array $headers = [], string $body = '') diff --git a/ja/orm/retrieving-data-and-resultsets.rst b/ja/orm/retrieving-data-and-resultsets.rst index 24b93cc72f..a3e94d42a0 100644 --- a/ja/orm/retrieving-data-and-resultsets.rst +++ b/ja/orm/retrieving-data-and-resultsets.rst @@ -596,7 +596,7 @@ contain に条件を渡す 'Authors' => [ 'foreignKey' => false, 'queryBuilder' => function (SelectQuery $q) { - return $q->where(...); // フィルターのための完全な条件 + return $q->where(/* ... */); // フィルターのための完全な条件 } ] ]); diff --git a/ja/orm/validation.rst b/ja/orm/validation.rst index 6b7f034af9..44519111f2 100644 --- a/ja/orm/validation.rst +++ b/ja/orm/validation.rst @@ -561,7 +561,7 @@ CakePHP は、エンティティーが保存される前に適用される「ル // カスタムルールの追加 use App\Model\Rule\CustomRule; - $rules->add(new CustomRule(...), 'ruleName'); + $rules->add(new CustomRule(/* ... */), 'ruleName'); カスタムルールクラスを作ることでコードを *重複がない状態* (訳注：DRY = Don't Repeat Yourself の訳) @@ -605,7 +605,7 @@ CakePHP の ORM は検証に二層のアプローチを使う点がユニーク public function validationCustomName($validator) { - $validator->add(...); + $validator->add(/* ... */); return $validator; } diff --git a/pt/core-libraries/httpclient.rst b/pt/core-libraries/httpclient.rst index fbe7cd3855..3b7bc2c66a 100644 --- a/pt/core-libraries/httpclient.rst +++ b/pt/core-libraries/httpclient.rst @@ -45,9 +45,9 @@ Fazer solicitações POST e PUT é igualmente simples:: ]); // Outros métodos também. - $http->delete(...); - $http->head(...); - $http->patch(...); + $http->delete(/* ... */); + $http->head(/* ... */); + $http->patch(/* ... */); Se você criou um objeto de solicitação PSR-7, pode enviá-lo usando ``sendRequest()``:: diff --git a/pt/orm/query-builder.rst b/pt/orm/query-builder.rst index 96c9002793..136532b765 100644 --- a/pt/orm/query-builder.rst +++ b/pt/orm/query-builder.rst @@ -666,7 +666,7 @@ criam novos objetos de expressão que mudam **como** as condições são combina segundo tipo de métodos são **condições**. As condições são adicionadas a uma expressão em que são alinhadas com o combinador atual. -Por exemplo, chamar ``$exp->and_(...)`` criará um novo objeto ``Expression`` que +Por exemplo, chamar ``$exp->and_(/* ... */)`` criará um novo objeto ``Expression`` que combina todas as condições que ele contém com ``AND``. Enquanto ``$exp->or_()`` criará um novo objeto ``Expression`` que combina todas as condições adicionadas a ele com ``OR``. Um exemplo de adição de condições com um objeto ``Expression`` seria:: diff --git a/pt/orm/retrieving-data-and-resultsets.rst b/pt/orm/retrieving-data-and-resultsets.rst index da92145a55..1170b8dc26 100644 --- a/pt/orm/retrieving-data-and-resultsets.rst +++ b/pt/orm/retrieving-data-and-resultsets.rst @@ -568,7 +568,7 @@ case you should use an array passing ``foreignKey`` and ``queryBuilder``:: 'Authors' => [ 'foreignKey' => false, 'queryBuilder' => function ($q) { - return $q->where(...); // Full conditions for filtering + return $q->where(/* ... */); // Full conditions for filtering } ] ]); From 597301119b7700729e310d03cbb0b2e6ee9ee14a Mon Sep 17 00:00:00 2001 From: "marc.wuerth" Date: Mon, 13 May 2024 10:05:58 +0200 Subject: [PATCH 206/337] Add blank line before return statements in examples --- en/console-commands/commands.rst | 1 + en/controllers.rst | 1 + en/controllers/components.rst | 2 + en/core-libraries/events.rst | 3 + en/core-libraries/logging.rst | 2 + en/core-libraries/validation.rst | 1 + en/development/routing.rst | 2 + en/development/sessions.rst | 3 + en/development/testing.rst | 3 + en/orm/behaviors.rst | 1 + en/orm/database-basics.rst | 5 + en/orm/query-builder.rst | 8 + en/orm/retrieving-data-and-resultsets.rst | 2 + en/orm/table-objects.rst | 1 + en/orm/validation.rst | 5 + en/security/csrf.rst | 5 +- .../cms/articles-controller.rst | 3 + .../cms/authentication.rst | 1 + .../cms/authorization.rst | 2 + .../cms/tags-and-users.rst | 4 + en/views/helpers/breadcrumbs.rst | 1 + en/views/helpers/form.rst | 1 + es/console-commands/commands.rst | 1 + es/controllers.rst | 1 + es/controllers/components.rst | 2 + es/core-libraries/logging.rst | 2 + es/development/routing.rst | 2 + es/development/sessions.rst | 3 + es/security/csrf.rst | 1 + .../blog-auth-example/auth.rst | 2 + es/tutorials-and-examples/blog/part-three.rst | 3 + es/tutorials-and-examples/blog/part-two.rst | 3 + es/views/helpers/breadcrumbs.rst | 1 + fr/console-commands/commands.rst | 13 +- fr/console-commands/shells.rst | 1 + fr/controllers.rst | 1 + fr/controllers/components.rst | 2 + fr/controllers/components/authentication.rst | 6 + .../components/request-handling.rst | 1 + fr/controllers/middleware.rst | 3 +- fr/core-libraries/caching.rst | 1 + fr/core-libraries/events.rst | 3 + fr/core-libraries/logging.rst | 2 + fr/core-libraries/validation.rst | 1 + fr/development/routing.rst | 2 + fr/development/sessions.rst | 3 + fr/development/testing.rst | 12 +- fr/orm/behaviors.rst | 1 + fr/orm/database-basics.rst | 5 + fr/orm/query-builder.rst | 7 + fr/orm/retrieving-data-and-resultsets.rst | 13 +- fr/orm/table-objects.rst | 9 +- fr/orm/validation.rst | 6 + fr/security/csrf.rst | 1 + .../blog-auth-example/auth.rst | 2 + fr/tutorials-and-examples/blog/part-three.rst | 3 + fr/tutorials-and-examples/blog/part-two.rst | 3 + fr/tutorials-and-examples/bookmarks/intro.rst | 1 + .../bookmarks/part-two.rst | 7 + .../cms/articles-controller.rst | 3 + .../cms/authentication.rst | 1 + .../cms/authorization.rst | 2 + .../cms/tags-and-users.rst | 4 + fr/views/helpers/breadcrumbs.rst | 1 + fr/views/helpers/form.rst | 1 + ja/console-commands/commands.rst | 1 + ja/console-commands/shells.rst | 1 + ja/controllers.rst | 2 + ja/controllers/components.rst | 2 + ja/controllers/components/authentication.rst | 6 + ja/controllers/middleware.rst | 3 +- ja/core-libraries/events.rst | 3 + ja/core-libraries/logging.rst | 2 + ja/core-libraries/validation.rst | 1 + ja/development/errors.rst | 1 + ja/development/routing.rst | 2 + ja/development/sessions.rst | 3 + ja/development/testing.rst | 4 + ja/orm/behaviors.rst | 1 + ja/orm/database-basics.rst | 4 + ja/orm/query-builder.rst | 7 + ja/orm/retrieving-data-and-resultsets.rst | 3 + ja/orm/table-objects.rst | 1 + ja/orm/validation.rst | 6 + ja/security/csrf.rst | 1 + .../blog-auth-example/auth.rst | 2 + ja/tutorials-and-examples/blog/part-three.rst | 3 + ja/tutorials-and-examples/blog/part-two.rst | 3 + ja/tutorials-and-examples/bookmarks/intro.rst | 1 + .../bookmarks/part-two.rst | 7 + .../cms/articles-controller.rst | 3 + .../cms/authentication.rst | 1 + .../cms/tags-and-users.rst | 4 + ja/views/helpers/breadcrumbs.rst | 1 + ja/views/helpers/form.rst | 1 + pt/console-and-shells.rst | 1 + .../cakephp-coding-conventions.rst | 2 + pt/controllers.rst | 2 + pt/controllers/components.rst | 97 ++++++------ pt/controllers/components/authentication.rst | 6 + .../components/request-handling.rst | 1 + pt/controllers/middleware.rst | 144 +++++++++--------- pt/core-libraries/events.rst | 3 + pt/development/configuration.rst | 1 + pt/development/routing.rst | 2 + pt/development/sessions.rst | 5 +- pt/development/testing.rst | 4 + pt/orm/behaviors.rst | 1 + pt/orm/database-basics.rst | 4 + pt/orm/query-builder.rst | 7 + pt/orm/retrieving-data-and-resultsets.rst | 3 + .../blog-auth-example/auth.rst | 3 + pt/tutorials-and-examples/blog/part-three.rst | 3 + pt/tutorials-and-examples/blog/part-two.rst | 3 + pt/tutorials-and-examples/bookmarks/intro.rst | 1 + .../bookmarks/part-two.rst | 9 +- 116 files changed, 437 insertions(+), 144 deletions(-) diff --git a/en/console-commands/commands.rst b/en/console-commands/commands.rst index 0b536146eb..f8830bf7e4 100644 --- a/en/console-commands/commands.rst +++ b/en/console-commands/commands.rst @@ -62,6 +62,7 @@ command line:: $parser->addArgument('name', [ 'help' => 'What is your name', ]); + return $parser; } diff --git a/en/controllers.rst b/en/controllers.rst index ea73d1213a..4330e32740 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -417,6 +417,7 @@ You can redirect using :term:`routing array` values:: Or using a relative or absolute URL:: return $this->redirect('/orders/confirm'); + return $this->redirect('http://www.example.com'); Or to the referer page:: diff --git a/en/controllers/components.rst b/en/controllers/components.rst index fff1c088ab..d90ddb2d20 100644 --- a/en/controllers/components.rst +++ b/en/controllers/components.rst @@ -136,6 +136,7 @@ in your controller, you could access it like so:: { if ($this->Post->delete($this->request->getData('Post.id')) { $this->Flash->success('Post deleted.'); + return $this->redirect(['action' => 'index']); } } @@ -317,6 +318,7 @@ To redirect from within a component callback method you can use the following:: public function beforeFilter(EventInterface $event) { $event->stopPropagation(); + return $this->getController()->redirect('/'); } diff --git a/en/core-libraries/events.rst b/en/core-libraries/events.rst index df94cfe747..5aa43ad40f 100644 --- a/en/core-libraries/events.rst +++ b/en/core-libraries/events.rst @@ -65,8 +65,10 @@ has been created. To keep your Orders model clean you could use events:: 'order' => $order ]); $this->getEventManager()->dispatch($event); + return true; } + return false; } } @@ -456,6 +458,7 @@ directly or returning the value in the callback itself:: { // ... $alteredData = $event->getData('order') + $moreData; + return $alteredData; } diff --git a/en/core-libraries/logging.rst b/en/core-libraries/logging.rst index 188005ca4a..3d3ba86670 100644 --- a/en/core-libraries/logging.rst +++ b/en/core-libraries/logging.rst @@ -465,6 +465,7 @@ After installing Monolog using composer, configure the logger using the Log::setConfig('default', function () { $log = new Logger('app'); $log->pushHandler(new StreamHandler('path/to/your/combined.log')); + return $log; }); @@ -482,6 +483,7 @@ Use similar methods if you want to configure a different logger for your console Log::setConfig('default', function () { $log = new Logger('cli'); $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log')); + return $log; }); diff --git a/en/core-libraries/validation.rst b/en/core-libraries/validation.rst index 4af34141b5..4e4b37ddca 100644 --- a/en/core-libraries/validation.rst +++ b/en/core-libraries/validation.rst @@ -289,6 +289,7 @@ conditions only:: if (isset($context['data']['action'])) { return $context['data']['action'] === 'subscribe'; } + return false; }); $validator->requirePresence('email'); diff --git a/en/development/routing.rst b/en/development/routing.rst index bbfe38cc73..eef644438d 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -1683,6 +1683,7 @@ URL filters allow you to implement features like persistent parameters:: if ($request->getParam('lang') && !isset($params['lang'])) { $params['lang'] = $request->getParam('lang'); } + return $params; }); @@ -1701,6 +1702,7 @@ example):: $params['language'] = $params[0]; unset($params[0]); } + return $params; }); diff --git a/en/development/sessions.rst b/en/development/sessions.rst index e451a0dd22..b15c464b34 100644 --- a/en/development/sessions.rst +++ b/en/development/sessions.rst @@ -297,6 +297,7 @@ something like:: if ($result) { return $result; } + return parent::read($id); } @@ -304,6 +305,7 @@ something like:: public function write($id, $data): bool { Cache::write($id, $data, $this->cacheKey); + return parent::write($id, $data); } @@ -311,6 +313,7 @@ something like:: public function destroy($id): bool { Cache::delete($id, $this->cacheKey); + return parent::destroy($id); } diff --git a/en/development/testing.rst b/en/development/testing.rst index 45bc7e6514..0229b8aa1c 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -147,6 +147,7 @@ Our helper looks like:: public function bar($value) { $width = round($value / 100, 2) * 100; + return sprintf( '
    @@ -1810,8 +1811,10 @@ Expanding on the Orders example, say we have the following tables:: 'order' => $order ]); $this->getEventManager()->dispatch($event); + return true; } + return false; } } diff --git a/en/orm/behaviors.rst b/en/orm/behaviors.rst index 6195c538a8..c3c3aa8ea5 100644 --- a/en/orm/behaviors.rst +++ b/en/orm/behaviors.rst @@ -189,6 +189,7 @@ To prevent the save from continuing, simply stop event propagation in your callb if (...) { $event->stopPropagation(); $event->setResult(false); + return; } $this->slug($entity); diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 0ae41e0852..4337120538 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -528,6 +528,7 @@ class:: if ($value === null) { return null; } + return json_decode($value, true); } @@ -536,6 +537,7 @@ class:: if (is_array($value) || $value === null) { return $value; } + return json_decode($value, true); } @@ -549,6 +551,7 @@ class:: if ($value === null) { return PDO::PARAM_NULL; } + return PDO::PARAM_STR; } } @@ -623,6 +626,7 @@ used:: if (isset($data['null') && $data['null'] === false) { $sql .= ' NOT NULL'; } + return $sql; } @@ -727,6 +731,7 @@ value object and into SQL expressions:: if (is_array($value)) { return new Point($value[0], $value[1]); } + return null; } diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 0762f72bdf..15d04f36f3 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -169,6 +169,7 @@ by calling the ``SelectQuery``'s ``all()`` method) implements the collection int ->all() ->map(function ($row) { $row->trimmedTitle = trim($row->title); + return $row; }) ->combine('id', 'trimmedTitle') // combine() is another collection method @@ -668,6 +669,7 @@ of people, you could calculate their age with a result formatter:: $query->formatResults(function (\Cake\Collection\CollectionInterface $results) { return $results->map(function ($row) { $row['age'] = $row['birth_date']->diff(new \DateTime)->y; + return $row; }); }); @@ -689,6 +691,7 @@ expect:: return $q->formatResults(function (\Cake\Collection\CollectionInterface $authors) { return $authors->map(function ($author) { $author['age'] = $author['birth_date']->diff(new \DateTime)->y; + return $author; }); }); @@ -803,6 +806,7 @@ following:: ->where(function (QueryExpression $exp) { $orConditions = $exp->or(['author_id' => 2]) ->eq('author_id', 5); + return $exp ->add($orConditions) ->eq('published', true) @@ -831,6 +835,7 @@ the method chaining:: return $or->eq('author_id', 2) ->eq('author_id', 5); }); + return $exp ->not($orConditions) ->lte('view_count', 10); @@ -842,6 +847,7 @@ You can negate sub-expressions using ``not()``:: ->where(function (QueryExpression $exp) { $orConditions = $exp->or(['author_id' => 2]) ->eq('author_id', 5); + return $exp ->not($orConditions) ->lte('view_count', 10); @@ -865,6 +871,7 @@ It is also possible to build expressions using SQL functions:: $year = $q->func()->year([ 'created' => 'identifier' ]); + return $exp ->gte($year, 2014) ->eq('published', true); @@ -1193,6 +1200,7 @@ And can be used combined with aggregations too:: $query->newExpr(['Stocks.quantity', 'Products.unit_price']) ->setConjunction('*') ); + return [ 'Products.name', 'stock_quantity' => $stockQuantity, diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index 1bb8bf0b95..0fc95f8b86 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -947,6 +947,7 @@ extract a list of unique tags on a collection of articles by running:: if (!in_array($value, $output)) { $output[] = $value; } + return $output; }; @@ -1232,6 +1233,7 @@ This is particularly useful for building custom finder methods as described in t // Same as in the common words example in the previous section $mapper = ...; $reducer = ...; + return $query->mapReduce($mapper, $reducer); } diff --git a/en/orm/table-objects.rst b/en/orm/table-objects.rst index 082c36dfe7..f43c13f743 100644 --- a/en/orm/table-objects.rst +++ b/en/orm/table-objects.rst @@ -355,6 +355,7 @@ To prevent the save from continuing, simply stop event propagation in your callb if (...) { $event->stopPropagation(); $event->setResult(false); + return; } ... diff --git a/en/orm/validation.rst b/en/orm/validation.rst index 6100fd7a0f..13400c3210 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -112,6 +112,7 @@ used. An example validator for our articles table would be:: $validator ->notEmptyString('title', __('You need to provide a title')) ->notEmptyString('body', __('A body is required')); + return $validator; } } @@ -173,6 +174,7 @@ construction process into multiple reusable steps:: $validator = $this->validationDefault($validator); $validator->add('password', 'length', ['rule' => ['lengthBetween', 8, 100]]); + return $validator; } @@ -207,6 +209,7 @@ a validation rule:: 'message' => __('You need to provide a valid role'), 'provider' => 'table', ]); + return $validator; } @@ -224,6 +227,7 @@ You can also use closures for validation rules:: if ($value > 1) { return true; } + return 'Not a good value.'; } ]); @@ -543,6 +547,7 @@ You may want to re-use custom domain rules. You can do so by creating your own i 'errorField' => 'name', 'message' => 'Name must be unique per parent.', ]); + return $rules; } diff --git a/en/security/csrf.rst b/en/security/csrf.rst index 02d9fcae21..fe707035ee 100644 --- a/en/security/csrf.rst +++ b/en/security/csrf.rst @@ -48,6 +48,7 @@ stack you protect all the actions in application:: $csrf = new SessionCsrfProtectionMiddleware($options); $middlewareQueue->add($csrf); + return $middlewareQueue; } @@ -83,8 +84,8 @@ The available configuration options are: will fail. Defaults to ``false``. - ``httponly`` Whether or not the cookie will be set with the HttpOnly flag. Defaults to ``false``. Prior to 4.1.0 use the ``httpOnly`` option. -- ``samesite`` Allows you to declare if your cookie should be restricted to a - first-party or same-site context. Possible values are ``Lax``, ``Strict`` and +- ``samesite`` Allows you to declare if your cookie should be restricted to a + first-party or same-site context. Possible values are ``Lax``, ``Strict`` and ``None``. Defaults to ``null``. - ``field`` The form field to check. Defaults to ``_csrfToken``. Changing this will also require configuring FormHelper. diff --git a/en/tutorials-and-examples/cms/articles-controller.rst b/en/tutorials-and-examples/cms/articles-controller.rst index b52cd0de53..3253c071cd 100644 --- a/en/tutorials-and-examples/cms/articles-controller.rst +++ b/en/tutorials-and-examples/cms/articles-controller.rst @@ -203,6 +203,7 @@ to be created. Start by creating an ``add()`` action in the if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); @@ -347,6 +348,7 @@ now. Add the following action to your ``ArticlesController``:: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been updated.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to update your article.')); @@ -479,6 +481,7 @@ Next, let's make a way for users to delete articles. Start with a $article = $this->Articles->findBySlug($slug)->firstOrFail(); if ($this->Articles->delete($article)) { $this->Flash->success(__('The {0} article has been deleted.', $article->title)); + return $this->redirect(['action' => 'index']); } } diff --git a/en/tutorials-and-examples/cms/authentication.rst b/en/tutorials-and-examples/cms/authentication.rst index 7ff48410e1..5a99e695c8 100644 --- a/en/tutorials-and-examples/cms/authentication.rst +++ b/en/tutorials-and-examples/cms/authentication.rst @@ -289,6 +289,7 @@ Add the logout action to the ``UsersController`` class:: // regardless of POST or GET, redirect if user is logged in if ($result && $result->isValid()) { $this->Authentication->logout(); + return $this->redirect(['controller' => 'Users', 'action' => 'login']); } } diff --git a/en/tutorials-and-examples/cms/authorization.rst b/en/tutorials-and-examples/cms/authorization.rst index 6e2ffa8f23..41a0194ec5 100644 --- a/en/tutorials-and-examples/cms/authorization.rst +++ b/en/tutorials-and-examples/cms/authorization.rst @@ -201,6 +201,7 @@ logged in user. Replace your add action with the following:: if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); @@ -228,6 +229,7 @@ Next we'll update the ``edit`` action. Replace the edit method with the followin ]); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been updated.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to update your article.')); diff --git a/en/tutorials-and-examples/cms/tags-and-users.rst b/en/tutorials-and-examples/cms/tags-and-users.rst index 4adb88cabe..be51a717cf 100644 --- a/en/tutorials-and-examples/cms/tags-and-users.rst +++ b/en/tutorials-and-examples/cms/tags-and-users.rst @@ -85,6 +85,7 @@ articles. First, update the ``add`` action to look like:: if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); @@ -125,6 +126,7 @@ edit method should now look like:: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been updated.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to update your article.')); @@ -351,6 +353,7 @@ can add a virtual/computed field to the entity. In $str = $tags->reduce(function ($string, $tag) { return $string . $tag->title . ', '; }, ''); + return trim($str, ', '); } @@ -437,6 +440,7 @@ to **src/Model/Table/ArticlesTable.php**:: foreach ($newTags as $tag) { $out[] = $this->Tags->newEntity(['title' => $tag]); } + return $out; } diff --git a/en/views/helpers/breadcrumbs.rst b/en/views/helpers/breadcrumbs.rst index b3db2b67c4..08e96c54a7 100644 --- a/en/views/helpers/breadcrumbs.rst +++ b/en/views/helpers/breadcrumbs.rst @@ -186,6 +186,7 @@ when you want to transform the crumbs and overwrite the list:: $crumbs = $this->Breadcrumbs->getCrumbs(); $crumbs = collection($crumbs)->map(function ($crumb) { $crumb['options']['class'] = 'breadcrumb-item'; + return $crumb; })->toArray(); diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 5742a08682..707eff8b7b 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -2508,6 +2508,7 @@ could do the following:: $data += [ 'name' => '', ]; + return $this->_templates->format('autocomplete', [ 'name' => $data['name'], 'attrs' => $this->_templates->formatAttributes($data, ['name']) diff --git a/es/console-commands/commands.rst b/es/console-commands/commands.rst index 5d80bcd7c0..480123ad83 100644 --- a/es/console-commands/commands.rst +++ b/es/console-commands/commands.rst @@ -58,6 +58,7 @@ Nuestro método ``execute()`` no es muy interesante, leamos algunas entradas des $parser->addArgument('name', [ 'help' => 'What is your name', ]); + return $parser; } diff --git a/es/controllers.rst b/es/controllers.rst index ae342a66b8..5bdccff12c 100644 --- a/es/controllers.rst +++ b/es/controllers.rst @@ -407,6 +407,7 @@ Puedes redigir usando los valores de un array ordenado:: O usando una URL relativa o absoluta:: return $this->redirect('/orders/confirm'); + return $this->redirect('http://www.example.com'); O la referencia de la página:: diff --git a/es/controllers/components.rst b/es/controllers/components.rst index c4af604468..6c9adcf801 100644 --- a/es/controllers/components.rst +++ b/es/controllers/components.rst @@ -133,6 +133,7 @@ puedes acceder a él de esta forma:: { if ($this->Post->delete($this->request->getData('Post.id')) { $this->Flash->success('Post deleted.'); + return $this->redirect(['action' => 'index']); } } @@ -313,6 +314,7 @@ puedes usar lo siguiente:: public function beforeFilter(EventInterface $event) { $event->stopPropagation(); + return $this->getController()->redirect('/'); } diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index 1729ff0119..fe4f49c4da 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -465,6 +465,7 @@ Una vez instalado Monolog utilizando composer, configura el ``logger`` usando el Log::setConfig('default', function () { $log = new Logger('app'); $log->pushHandler(new StreamHandler('ruta/a/tu/combined.log')); + return $log; }); @@ -482,6 +483,7 @@ Utiliza métodos similares si deseas configurar un ``logger`` diferente para tu Log::setConfig('default', function () { $log = new Logger('cli'); $log->pushHandler(new StreamHandler('ruta/a/tu/combined-cli.log')); + return $log; }); diff --git a/es/development/routing.rst b/es/development/routing.rst index 8db2d5e089..a168745f1f 100644 --- a/es/development/routing.rst +++ b/es/development/routing.rst @@ -1711,6 +1711,7 @@ Los filtros de URL te permiten implementar funciones como parámetros persistent if ($request->getParam('lang') && !isset($params['lang'])) { $params['lang'] = $request->getParam('lang'); } + return $params; }); @@ -1729,6 +1730,7 @@ Otro caso de uso es cambiar una determinada ruta en tiempo de ejecución $params['language'] = $params[0]; unset($params[0]); } + return $params; }); diff --git a/es/development/sessions.rst b/es/development/sessions.rst index 464451fb73..5f00b789e8 100644 --- a/es/development/sessions.rst +++ b/es/development/sessions.rst @@ -236,6 +236,7 @@ Primero necesitamos crear nuestra clase personalizada y ponerla en **src/Http/Se if ($result) { return $result; } + return parent::read($id); @@ -245,6 +246,7 @@ Primero necesitamos crear nuestra clase personalizada y ponerla en **src/Http/Se public function write($id, $data): bool { Cache::write($id, $data, $this->cacheKey); + return parent::write($id, $data); } @@ -252,6 +254,7 @@ Primero necesitamos crear nuestra clase personalizada y ponerla en **src/Http/Se public function destroy($id): bool { Cache::delete($id, $this->cacheKey); + return parent::destroy($id); } diff --git a/es/security/csrf.rst b/es/security/csrf.rst index e83c5559cc..7375d9e105 100644 --- a/es/security/csrf.rst +++ b/es/security/csrf.rst @@ -36,6 +36,7 @@ La protección CSRF se puede aplicar a toda tu aplicación o a ámbitos de enrut $csrf = new SessionCsrfProtectionMiddleware($opciones); $middlewareQueue->add($csrf); + return $middlewareQueue; } diff --git a/es/tutorials-and-examples/blog-auth-example/auth.rst b/es/tutorials-and-examples/blog-auth-example/auth.rst index 5920a6043e..8480565e4a 100644 --- a/es/tutorials-and-examples/blog-auth-example/auth.rst +++ b/es/tutorials-and-examples/blog-auth-example/auth.rst @@ -95,6 +95,7 @@ de código que están incluidas en CakePHP:: $user = $this->Users->patchEntity($user, $this->request->getData()); if ($this->Users->save($user)) { $this->Flash->success(__('The user has been saved.')); + return $this->redirect(['action' => 'add']); } $this->Flash->error(__('Unable to add the user.')); @@ -361,6 +362,7 @@ Añade la acción ``logout`` a la clase ``UsersController``:: // sin importar si es POST o GET, redirige si el usuario esta autenticado if ($result->isValid()) { $this->Authentication->logout(); + return $this->redirect(['controller' => 'Users', 'action' => 'login']); } } diff --git a/es/tutorials-and-examples/blog/part-three.rst b/es/tutorials-and-examples/blog/part-three.rst index efa66b9c09..7ec38038c6 100644 --- a/es/tutorials-and-examples/blog/part-three.rst +++ b/es/tutorials-and-examples/blog/part-three.rst @@ -159,6 +159,7 @@ para poder reordenar las categorías en ese árbol:: } else { $this->Flash->error('The category could not be moved up. Please, try again.'); } + return $this->redirect($this->referer(['action' => 'index'])); } @@ -171,6 +172,7 @@ para poder reordenar las categorías en ese árbol:: } else { $this->Flash->error('The category could not be moved down. Please, try again.'); } + return $this->redirect($this->referer(['action' => 'index'])); } } @@ -246,6 +248,7 @@ Esto nos permitirá elegir una categoría para un Article al momento de crearlo $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); diff --git a/es/tutorials-and-examples/blog/part-two.rst b/es/tutorials-and-examples/blog/part-two.rst index e96344b767..d627bde3d0 100644 --- a/es/tutorials-and-examples/blog/part-two.rst +++ b/es/tutorials-and-examples/blog/part-two.rst @@ -269,6 +269,7 @@ ArticlesController:: $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); @@ -424,6 +425,7 @@ ser la acción ``edit()`` del controlador ``ArticlesController``:: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Tu artículo ha sido actualizado.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Tu artículo no se ha podido actualizar.')); @@ -512,6 +514,7 @@ Vamos a permitir a los usuarios que borren artículos. Empieza con una acción $article = $this->Articles->get($id); if ($this->Articles->delete($article)) { $this->Flash->success(__('El artículo con id: {0} ha sido eliminado.', h($id))); + return $this->redirect(['action' => 'index']); } } diff --git a/es/views/helpers/breadcrumbs.rst b/es/views/helpers/breadcrumbs.rst index e35e3eff81..0d3ed865b1 100644 --- a/es/views/helpers/breadcrumbs.rst +++ b/es/views/helpers/breadcrumbs.rst @@ -181,6 +181,7 @@ Esto puede ser útil cuando deseas transformar las migas y sobrescribir la lista $crumbs = $this->Breadcrumbs->getCrumbs(); $crumbs = collection($crumbs)->map(function ($crumb) { $crumb['options']['class'] = 'breadcrumb-item'; + return $crumb; })->toArray(); diff --git a/fr/console-commands/commands.rst b/fr/console-commands/commands.rst index c60537262e..7372817a8e 100644 --- a/fr/console-commands/commands.rst +++ b/fr/console-commands/commands.rst @@ -27,7 +27,7 @@ Hello world toute simple. Dans le répertoire **src/Command** de votre applicati public function execute(Arguments $args, ConsoleIo $io): int { $io->out('Hello world.'); - + return static::CODE_SUCCESS; } } @@ -61,6 +61,7 @@ Notre méthode ``execute()`` n'est pas très intéressente, ajoutons des entrée $parser->addArgument('name', [ 'help' => 'Quel est votre nom' ]); + return $parser; } @@ -68,7 +69,7 @@ Notre méthode ``execute()`` n'est pas très intéressente, ajoutons des entrée { $name = $args->getArgument('name'); $io->out("Hello {$name}."); - + return static::CODE_SUCCESS; } } @@ -82,7 +83,7 @@ Après avoir sauvegardé ce fichier, vous devriez pouvoir exécuter la commande # Affiche Hello jillian - + Changer le Nom Par Défaut de la Commande ======================================== @@ -127,7 +128,7 @@ pour définir des arguments. Nous pouvons aussi définir des options. Par exempl $name = mb_strtoupper($name); } $io->out("Hello {$name}."); - + return static::CODE_SUCCESS; } @@ -216,7 +217,7 @@ message et un code:: // Arrête l'exécution, affiche vers stderr, et définit le code de sortie à 99 $io->abort('Le nom doit avoir au moins 4 caractères.', 99); } - + return static::CODE_SUCCESS; } @@ -337,7 +338,7 @@ moment, mais testons simplement si la description de notre shell description s'a use Cake\TestSuite\ConsoleIntegrationTestTrait; use Cake\TestSuite\TestCase; - + class UpdateTableCommandTest extends TestCase { user ConsoleIntegrationTestTrait; diff --git a/fr/console-commands/shells.rst b/fr/console-commands/shells.rst index 377fcb9b8a..f88daa1129 100644 --- a/fr/console-commands/shells.rst +++ b/fr/console-commands/shells.rst @@ -152,6 +152,7 @@ Also, the task name must be added as a sub-command to the Shell's OptionParser:: // Link the option parsers together. 'parser' => $this->Sound->getOptionParser(), ]); + return $parser; } diff --git a/fr/controllers.rst b/fr/controllers.rst index 15b7d957b1..b22004c6b6 100644 --- a/fr/controllers.rst +++ b/fr/controllers.rst @@ -363,6 +363,7 @@ vous pouvez rediriger en utilisant les valeurs du :term:`tableau de routing`:: Ou utiliser une URL relative ou absolue:: return $this->redirect('/orders/confirm'); + return $this->redirect('http://www.example.com'); Ou rediriger vers l'URL appelante (referer):: diff --git a/fr/controllers/components.rst b/fr/controllers/components.rst index 32cb62c49f..c9b3d75be4 100644 --- a/fr/controllers/components.rst +++ b/fr/controllers/components.rst @@ -144,6 +144,7 @@ vous pouvez y accéder comme ceci:: { if ($this->Post->delete($this->request->getData('Post.id')) { $this->Flash->success('Publication effacée.'); + return $this->redirect(['action' => 'index']); } } @@ -324,6 +325,7 @@ Pour rediriger à partir d'une méthode de rappel de composant, vous pouvez util public function beforeFilter(EventInterface $event) { $event->stopPropagation(); + return $this->getController()->redirect('/'); } diff --git a/fr/controllers/components/authentication.rst b/fr/controllers/components/authentication.rst index bdb1669608..15bd92add6 100644 --- a/fr/controllers/components/authentication.rst +++ b/fr/controllers/components/authentication.rst @@ -247,6 +247,7 @@ connexion pourrait ressembler à cela:: $user = $this->Auth->identify(); if ($user) { $this->Auth->setUser($user); + return $this->redirect($this->Auth->redirectUrl()); } else { $this->Flash->error(__("Nom d'utilisateur ou mot de passe incorrect")); @@ -340,6 +341,7 @@ en cas d'échec:: if (empty($username) || empty($pass)) { return false; } + return $this->_findUser($username, $pass); } @@ -410,6 +412,7 @@ de façon aléatoire ces tokens d'API en utilisant les libraries de CakePHP:: // it during login. $entity->api_key = $hasher->hash($entity->api_key_plain); } + return true; } } @@ -476,6 +479,7 @@ colonne séparée du mot de passe standard hashé:: $entity->plain_password, env('SERVER_NAME') ); + return true; } } @@ -748,6 +752,7 @@ pouvez changer la fonction login selon:: $user->password = $this->request->getData('password'); $this->Users->save($user); } + return $this->redirect($this->Auth->redirectUrl()); } ... @@ -773,6 +778,7 @@ utilisateur que vous voulez pour la 'connexion':: $user = $this->Users->newEntity($this->request->getData()); if ($this->Users->save($user)) { $this->Auth->setUser($user->toArray()); + return $this->redirect([ 'controller' => 'Users', 'action' => 'home' diff --git a/fr/controllers/components/request-handling.rst b/fr/controllers/components/request-handling.rst index 14b320ea73..738e99454b 100644 --- a/fr/controllers/components/request-handling.rst +++ b/fr/controllers/components/request-handling.rst @@ -156,6 +156,7 @@ ajouter un gestionnaire de CSV pourrait ressembler à ceci:: foreach ($rows as &$row) { $row = str_getcsv($row, ','); } + return $rows; }; $this->loadComponent('RequestHandler', [ diff --git a/fr/controllers/middleware.rst b/fr/controllers/middleware.rst index 2379eab71b..9934105355 100644 --- a/fr/controllers/middleware.rst +++ b/fr/controllers/middleware.rst @@ -88,6 +88,7 @@ pour en attacher :: { // Attache le gestionnaire d'erreur dans la file du middleware $middlewareQueue->add(new ErrorHandlerMiddleware()); + return $middlewareQueue; } } @@ -140,7 +141,7 @@ appliquer un de leurs middlewares dans la file de middlewares de l'application:: use Cake\Http\MiddlewareQueue; use ContactManager\Middleware\ContactManagerContextMiddleware; - + class Plugin extends BasePlugin { public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue diff --git a/fr/core-libraries/caching.rst b/fr/core-libraries/caching.rst index 0600e705ce..297450ad5e 100644 --- a/fr/core-libraries/caching.rst +++ b/fr/core-libraries/caching.rst @@ -289,6 +289,7 @@ Par exemple:: // Stocke les données en cache Cache::write('cloud', $cloud); + return $cloud; Lire Plusieurs Clés d'un Coup diff --git a/fr/core-libraries/events.rst b/fr/core-libraries/events.rst index f132767986..098b4039dd 100644 --- a/fr/core-libraries/events.rst +++ b/fr/core-libraries/events.rst @@ -76,8 +76,10 @@ garder votre model Orders propre, vous pouvez utiliser les événements:: 'order' => $order ]); $this->getEventManager()->dispatch($event); + return true; } + return false; } } @@ -493,6 +495,7 @@ callback elle-même:: { // ... $alteredData = $event->getData('order') + $moreData; + return $alteredData; } diff --git a/fr/core-libraries/logging.rst b/fr/core-libraries/logging.rst index 9cf2e3cca8..d6a87d8ff1 100755 --- a/fr/core-libraries/logging.rst +++ b/fr/core-libraries/logging.rst @@ -493,6 +493,7 @@ utilisant la méthode ``Log::setConfig()``:: Log::setConfig('default', function () { $log = new Logger('app'); $log->pushHandler(new StreamHandler('path/to/your/combined.log')); + return $log; }); @@ -510,6 +511,7 @@ Utilisez des méthodes similaires pour configurer un logger différent pour la c Log::setConfig('default', function () { $log = new Logger('cli'); $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log')); + return $log; }); diff --git a/fr/core-libraries/validation.rst b/fr/core-libraries/validation.rst index 06cde26584..0c13a8eadd 100644 --- a/fr/core-libraries/validation.rst +++ b/fr/core-libraries/validation.rst @@ -371,6 +371,7 @@ certaines conditions seulement:: if (isset($context['data']['action'])) { return $context['data']['action'] === 'subscribe'; } + return false; }); $validator->requirePresence('email'); diff --git a/fr/development/routing.rst b/fr/development/routing.rst index 90c52cb82d..a6da47dcfe 100644 --- a/fr/development/routing.rst +++ b/fr/development/routing.rst @@ -1756,6 +1756,7 @@ l'utilisation de paramètres d'URL persistants:: if ($request->getParam('lang') && !isset($params['lang'])) { $params['lang'] = $request->getParam('lang'); } + return $params; }); @@ -1775,6 +1776,7 @@ Un autre cas lorsque l'on souhaite changer une route en particulier à la volée $params['language'] = $params[0]; unset($params[0]); } + return $params; }); diff --git a/fr/development/sessions.rst b/fr/development/sessions.rst index 2d64801872..9dd64a941c 100644 --- a/fr/development/sessions.rst +++ b/fr/development/sessions.rst @@ -280,6 +280,7 @@ devrait ressembler à:: if ($result) { return $result; } + return parent::read($id); } @@ -287,6 +288,7 @@ devrait ressembler à:: public function write($id, $data) { Cache::write($id, $data, $this->cacheKey); + return parent::write($id, $data); } @@ -294,6 +296,7 @@ devrait ressembler à:: public function destroy($id) { Cache::delete($id, $this->cacheKey); + return parent::destroy($id); } diff --git a/fr/development/testing.rst b/fr/development/testing.rst index 35aea296f5..2bd4de489e 100755 --- a/fr/development/testing.rst +++ b/fr/development/testing.rst @@ -155,6 +155,7 @@ barre de progression HTML. Notre helper ressemblera à cela:: public function bar($value) { $width = round($value / 100, 2) * 100; + return sprintf( '
    @@ -853,6 +854,7 @@ Supposons que nous avons déjà notre table Articles définie dans $query->where([ $this->alias() . '.published' => 1 ]); + return $query; } } @@ -1315,7 +1317,7 @@ service web. Commençons avec un exemple simple de controller qui renvoie du JSON:: use Cake\View\JsonView; - + class MarkersController extends AppController { public function viewClasses(): array @@ -1596,7 +1598,7 @@ d'assertions afin de tester les réponses plus simplement. Quelques exemples:: $this->assertResponseEmpty(); // Vérifie le contenu de la réponse - $this->assertResponseEquals('Ouais !'); + $this->assertResponseEquals('Ouais !'); // Vérifie que le contenu de la réponse n'est pas égal à... $this->assertResponseNotEquals('Non !'); @@ -1710,7 +1712,7 @@ Mocker les Injections de Dépendances Voir :ref:`mocking-services-in-tests` pour savoir comment remplacer des services injectés avec le conteneur d'injection de dépendances dans vos tests d'intégration. - + Mocker les Réponses du Client HTTP ================================== @@ -1929,8 +1931,10 @@ suivantes:: 'order' => $order ]); $this->getEventManager()->dispatch($event); + return true; } + return false; } } @@ -2004,7 +2008,7 @@ globaux:: Testing Email ============= - + Consultez :ref:`email-testing` pour savoir comment tester les emails. Créer des Suites de Test (Test Suites) diff --git a/fr/orm/behaviors.rst b/fr/orm/behaviors.rst index d720a1dd4f..075c68db18 100644 --- a/fr/orm/behaviors.rst +++ b/fr/orm/behaviors.rst @@ -195,6 +195,7 @@ de l'évènement dans votre callback:: { if (...) { $event->stopPropagation(); + return; } $this->slug($entity); diff --git a/fr/orm/database-basics.rst b/fr/orm/database-basics.rst index 7010425648..96d690c848 100644 --- a/fr/orm/database-basics.rst +++ b/fr/orm/database-basics.rst @@ -503,6 +503,7 @@ type JSON, nous pourrions créer la classe de type suivante:: if ($value === null) { return null; } + return json_decode($value, true); } @@ -511,6 +512,7 @@ type JSON, nous pourrions créer la classe de type suivante:: if (is_array($value) || $value === null) { return $value; } + return json_decode($value, true); } @@ -524,6 +526,7 @@ type JSON, nous pourrions créer la classe de type suivante:: if ($value === null) { return PDO::PARAM_NULL; } + return PDO::PARAM_STR; } @@ -609,6 +612,7 @@ spécifique:: if (isset($data['null') && $data['null'] === false) { $sql .= ' NOT NULL'; } + return $sql; } @@ -714,6 +718,7 @@ faire correspondre les données dans cet objet et les expressions SQL:: if (is_array($value)) { return new Point($value[0], $value[1]); } + return null; } diff --git a/fr/orm/query-builder.rst b/fr/orm/query-builder.rst index 6459b45551..f7ddc989f5 100644 --- a/fr/orm/query-builder.rst +++ b/fr/orm/query-builder.rst @@ -176,6 +176,7 @@ pouvez aussi le faire avec un objet Query:: ->order(['title' => 'DESC']) ->map(function ($row) { // map() est une méthode de collection, elle exécute la requête $row->trimmedTitle = trim($row->title); + return $row; }) ->combine('id', 'trimmedTitle') // combine() est une autre méthode de collection @@ -724,6 +725,7 @@ formatter*):: $query->formatResults(function (\Cake\Collection\CollectionInterface $results) { return $results->map(function ($row) { $row['age'] = $row['date_de_naissance']->diff(new \DateTime)->y; + return $row; }); }); @@ -746,6 +748,7 @@ comme vous pouvez vous y attendre:: return $q->formatResults(function (\Cake\Collection\CollectionInterface $auteurs) { return $auteurs->map(function ($auteur) { $auteur['age'] = $auteur['date_de_naissance']->diff(new \DateTime)->y; + return $auteur; }); }); @@ -864,6 +867,7 @@ nous pouvons faire ceci:: ->where(function (QueryExpression $exp) { $orConditions = $exp->or(['auteur_id' => 2]) ->eq('auteur_id', 5); + return $exp ->add($orConditions) ->eq('published', true) @@ -892,6 +896,7 @@ chaînage des méthodes:: return $or->eq('auteur_id', 2) ->eq('auteur_id', 5); }); + return $exp ->not($orConditions) ->lte('nombre_de_vues', 10); @@ -903,6 +908,7 @@ Vous pouvez faire une négation des sous-expressions en utilisant ``not()``:: ->where(function (QueryExpression $exp) { $orConditions = $exp->or(['author_id' => 2]) ->eq('author_id', 5); + return $exp ->not($orConditions) ->lte('view_count', 10); @@ -927,6 +933,7 @@ SQL:: $year = $q->func()->year([ 'created' => 'identifier' ]); + return $exp ->gte($year, 2014) ->eq('published', true); diff --git a/fr/orm/retrieving-data-and-resultsets.rst b/fr/orm/retrieving-data-and-resultsets.rst index 5458c77395..18b80e07e9 100644 --- a/fr/orm/retrieving-data-and-resultsets.rst +++ b/fr/orm/retrieving-data-and-resultsets.rst @@ -400,6 +400,7 @@ les articles d'un certain auteur, nous ferions ceci:: public function findEcritPar(Query $query, array $options) { $user = $options['user']; + return $query->where(['author_id' => $user->id]); } @@ -582,7 +583,7 @@ définir le second argument à ``true``:: $query = $articles->find(); $query->contain(['Authors', 'Comments'], true); - + .. note:: Les noms d'association dans les appels à ``contain()`` doivent respecter la @@ -801,7 +802,7 @@ l'association et charger d'autres champs de cette même association, vous pouvez parfaitement combiner ``innerJoinWith()`` et ``contain()``. L'exemple ci-dessous filtre les Articles qui ont des Tags spécifiques et charge ces Tags:: - + $filter = ['Tags.name' => 'CakePHP']; $query = $articles->find() ->distinct($articles->getPrimaryKey()) @@ -820,9 +821,9 @@ ces Tags:: $query ->select(['country_name' => 'Countries.name']) ->innerJoinWith('Countries'); - + Sinon, vous verrez les données dans ``_matchingData``, comme cela a été - décrit ci-dessous à propos de ``matching()``. C'est un angle mort de + décrit ci-dessous à propos de ``matching()``. C'est un angle mort de ``matching()``, qui ne sait pas que vous avez sélectionné des champs. .. warning:: @@ -949,7 +950,7 @@ exemple des tables se trouvant dans deux bases de données différentes. Habituellement, vous définisser la stratégie d'une association quand vous la définissez, dans la méthode ``Table::initialize()``, mais vous pouvez changer manuellement la stratégie de façon permanente:: - + $articles->Comments->setStrategy('select'); Récupération Avec la Stratégie de Sous-Requête @@ -1050,6 +1051,7 @@ exécutant:: if (!in_array($value, $output)) { $output[] = $value; } + return $output; }; @@ -1340,6 +1342,7 @@ comme décrit dans la section :ref:`custom-find-methods`:: // Comme dans l'exemple précédent sur la fréquence des mots $mapper = ...; $reducer = ...; + return $query->mapReduce($mapper, $reducer); } diff --git a/fr/orm/table-objects.rst b/fr/orm/table-objects.rst index 0600b5d7ab..b9933b109e 100644 --- a/fr/orm/table-objects.rst +++ b/fr/orm/table-objects.rst @@ -146,14 +146,14 @@ façon d'utiliser le sous-système d'events:: // Dans un controller $articles->save($article, ['variablePerso1' => 'votreValeur1']); - + // Dans ArticlesTable.php public function afterSave(Event $event, EntityInterface $entity, ArrayObject $options) { $variablePerso = $options['variablePerso1']; // 'votreValeur1' - $options['variablePerso2'] = 'votreValeur2'; - } - + $options['variablePerso2'] = 'votreValeur2'; + } + public function afterSaveCommit(Event $event, EntityInterface $entity, ArrayObject $options) { $variablePerso = $options['variablePerso1']; // 'votreValeur1' @@ -375,6 +375,7 @@ de l'event dans votre callback:: if (...) { $event->stopPropagation(); $event->setResult(false); + return; } ... diff --git a/fr/orm/validation.rst b/fr/orm/validation.rst index 10038c0634..1ac338dc3c 100644 --- a/fr/orm/validation.rst +++ b/fr/orm/validation.rst @@ -123,6 +123,7 @@ notre table ``articles``:: $validator ->notEmptyString('title', __('Vous devez indiquer un titre')) ->notEmptyString('body', __('Un contenu est nécessaire')); + return $validator; } } @@ -186,6 +187,7 @@ diviser leur process de construction en petites étapes réutilisables:: $validator = $this->validationDefault($validator); $validator->add('password', 'length', ['rule' => ['lengthBetween', 8, 100]]); + return $validator; } @@ -220,6 +222,7 @@ l'utiliser comme une règle de validation:: 'message' => __('Vous devez fournir un rôle valide'), 'provider' => 'table', ]); + return $validator; } @@ -237,6 +240,7 @@ Vous pouvez également utiliser des closures en tant que règles de validation:: if ($value > 1) { return true; } + return 'Valeur incorrecte.'; } ]); @@ -579,6 +583,7 @@ le faire en créant votre propre règle invokable:: 'errorField' => 'name', 'message' => 'Doit être unique pour chaque parent.' ]); + return $rules; } @@ -723,6 +728,7 @@ pour les transitions de données générées à l'intérieur de l'application:: 'errorField' => 'livraison', 'message' => 'Pas de frais de port gratuits pour une commande de moins de 100!' ]); + return $rules; } diff --git a/fr/security/csrf.rst b/fr/security/csrf.rst index c9110a502b..200b916db6 100644 --- a/fr/security/csrf.rst +++ b/fr/security/csrf.rst @@ -50,6 +50,7 @@ de votre Application, vous protégez toutes les actions de l'application:: $csrf = new SessionCsrfProtectionMiddleware($options); $middlewareQueue->add($csrf); + return $middlewareQueue; } diff --git a/fr/tutorials-and-examples/blog-auth-example/auth.rst b/fr/tutorials-and-examples/blog-auth-example/auth.rst index c4b0b6f632..f31ca57ca4 100755 --- a/fr/tutorials-and-examples/blog-auth-example/auth.rst +++ b/fr/tutorials-and-examples/blog-auth-example/auth.rst @@ -100,6 +100,7 @@ classe obtenue grâce à l'utilitaire de génération de code fourni par CakePHP $user = $this->Users->patchEntity($user, $this->request->getData()); if ($this->Users->save($user)) { $this->Flash->success(__("L'utilisateur a été sauvegardé.")); + return $this->redirect(['action' => 'add']); } $this->Flash->error(__("Impossible d'ajouter l\'utilisateur.")); @@ -378,6 +379,7 @@ Ajoutez l'action logout à votre classe ``UsersController``:: // Qu'on soit en POST ou en GET, rediriger l'utilisateur s'il est déjà connecté if ($result->isValid()) { $this->Authentication->logout(); + return $this->redirect(['controller' => 'Users', 'action' => 'login']); } } diff --git a/fr/tutorials-and-examples/blog/part-three.rst b/fr/tutorials-and-examples/blog/part-three.rst index 32bcf8e51f..8bde440b32 100644 --- a/fr/tutorials-and-examples/blog/part-three.rst +++ b/fr/tutorials-and-examples/blog/part-three.rst @@ -277,6 +277,7 @@ catégories dans l'arbre:: } else { $this->Flash->error("La catégorie n'a pas pu être remontée. Veuillez réessayer."); } + return $this->redirect($this->referer(['action' => 'index'])); } @@ -289,6 +290,7 @@ catégories dans l'arbre:: } else { $this->Flash->error("La catégorie n'a pas pu être descendue. Veuillez réessayer."); } + return $this->redirect($this->referer(['action' => 'index'])); } } @@ -364,6 +366,7 @@ lorsqu'on va le créer ou le modifier:: $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été enregistré.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__("Impossible d\'ajouter votre article.")); diff --git a/fr/tutorials-and-examples/blog/part-two.rst b/fr/tutorials-and-examples/blog/part-two.rst index 532bab5cc5..e0ce294da7 100755 --- a/fr/tutorials-and-examples/blog/part-two.rst +++ b/fr/tutorials-and-examples/blog/part-two.rst @@ -314,6 +314,7 @@ Premièrement, commençons par créer une action ``add()`` dans le $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été sauvegardé.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible d\'ajouter votre article.')); @@ -487,6 +488,7 @@ devrait ressembler:: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été mis à jour.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible de mettre à jour votre article.')); @@ -580,6 +582,7 @@ Articles (``ArticlesController``):: $article = $this->Articles->get($id); if ($this->Articles->delete($article)) { $this->Flash->success(__("L'article avec l'id: {0} a été supprimé.", h($id))); + return $this->redirect(['action' => 'index']); } } diff --git a/fr/tutorials-and-examples/bookmarks/intro.rst b/fr/tutorials-and-examples/bookmarks/intro.rst index 4684b86cfa..d9d2506690 100644 --- a/fr/tutorials-and-examples/bookmarks/intro.rst +++ b/fr/tutorials-and-examples/bookmarks/intro.rst @@ -272,6 +272,7 @@ dans une de vos entities. Ajoutons un setter pour le mot de passe. Dans protected function _setPassword($value) { $hasher = new DefaultPasswordHasher(); + return $hasher->hash($value); } } diff --git a/fr/tutorials-and-examples/bookmarks/part-two.rst b/fr/tutorials-and-examples/bookmarks/part-two.rst index 78bdb31913..c486403ab7 100644 --- a/fr/tutorials-and-examples/bookmarks/part-two.rst +++ b/fr/tutorials-and-examples/bookmarks/part-two.rst @@ -69,6 +69,7 @@ nous n'avons pas encore écrit ce code. Créons donc l'action login:: $user = $this->Auth->identify(); if ($user) { $this->Auth->setUser($user); + return $this->redirect($this->Auth->redirectUrl()); } $this->Flash->error('Votre username ou mot de passe est incorrect.'); @@ -110,6 +111,7 @@ probablement fournir un moyen de se déconnecter. Encore une fois, dans public function logout() { $this->Flash->success('Vous êtes maintenant déconnecté.'); + return $this->redirect($this->Auth->logout()); } @@ -212,6 +214,7 @@ les bookmarks. Dans notre ``BookmarksController``, ajoutez ce qui suit:: if ($bookmark->user_id == $user['id']) { return true; } + return parent::isAuthorized($user); } @@ -247,6 +250,7 @@ ressembler à ceci:: $bookmark->user_id = $this->Auth->user('id'); if ($this->Bookmarks->save($bookmark)) { $this->Flash->success('Le bookmark a été sauvegardé.'); + return $this->redirect(['action' => 'index']); } $this->Flash->error('Le bookmark ne peut être sauvegardé. Merci de réessayer.'); @@ -272,6 +276,7 @@ ceci:: $bookmark->user_id = $this->Auth->user('id'); if ($this->Bookmarks->save($bookmark)) { $this->Flash->success('Le bookmark a été sauvegardé.'); + return $this->redirect(['action' => 'index']); } else { $this->Flash->error('Le bookmark ne peut être sauvegardé. Merci de réessayer.'); @@ -335,6 +340,7 @@ pouvons ajouter un champ virtuel/calculé à l'entity. Dans $str = $tags->reduce(function ($string, $tag) { return $string . $tag->title . ', '; }, ''); + return trim($str, ', '); } @@ -410,6 +416,7 @@ chaîne de tag et trouver/construire les entities liées. Ajoutez ce qui suit da foreach ($newTags as $tag) { $out[] = $this->Tags->newEntity(['title' => $tag]); } + return $out; } diff --git a/fr/tutorials-and-examples/cms/articles-controller.rst b/fr/tutorials-and-examples/cms/articles-controller.rst index bddb19b1c2..f0ba714d51 100644 --- a/fr/tutorials-and-examples/cms/articles-controller.rst +++ b/fr/tutorials-and-examples/cms/articles-controller.rst @@ -217,6 +217,7 @@ la création d'articles. Commencez par créer une action ``add()`` dans le if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été sauvegardé.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible d\'ajouter votre article.')); @@ -367,6 +368,7 @@ dans votre ``ArticlesController``:: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été mis à jour.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible de mettre à jour l\'article.')); @@ -501,6 +503,7 @@ Commencez par créer une action ``delete()`` dans ``ArticlesController``:: $article = $this->Articles->findBySlug($slug)->firstOrFail(); if ($this->Articles->delete($article)) { $this->Flash->success(__('L\'article {0} a été supprimé.', $article->title)); + return $this->redirect(['action' => 'index']); } } diff --git a/fr/tutorials-and-examples/cms/authentication.rst b/fr/tutorials-and-examples/cms/authentication.rst index 718120adda..0dcc55471c 100644 --- a/fr/tutorials-and-examples/cms/authentication.rst +++ b/fr/tutorials-and-examples/cms/authentication.rst @@ -288,6 +288,7 @@ Ajoutez l'action de logout à la classe ``UsersController``:: // indépendamment de POST ou GET, rediriger si l'utilisateur est connecté if ($result && $result->isValid()) { $this->Authentication->logout(); + return $this->redirect(['controller' => 'Users', 'action' => 'login']); } } diff --git a/fr/tutorials-and-examples/cms/authorization.rst b/fr/tutorials-and-examples/cms/authorization.rst index 9590f9b67e..7d2f0456ab 100644 --- a/fr/tutorials-and-examples/cms/authorization.rst +++ b/fr/tutorials-and-examples/cms/authorization.rst @@ -198,6 +198,7 @@ l'utilisateur actuellement authentifié. Remplacez l'action ``add`` par le code if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été enregistré avec succès.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible d\'ajouter votre article.')); @@ -225,6 +226,7 @@ Ensuite nous allons modifier l'action ``edit``. Remplacez la méthode d'édition ]); if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été sauvegardé.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible de mettre à jour votre article.')); diff --git a/fr/tutorials-and-examples/cms/tags-and-users.rst b/fr/tutorials-and-examples/cms/tags-and-users.rst index a2894c8bd9..ef1f5b45e3 100644 --- a/fr/tutorials-and-examples/cms/tags-and-users.rst +++ b/fr/tutorials-and-examples/cms/tags-and-users.rst @@ -85,6 +85,7 @@ l'action ``add`` pour qu'elle ressemble à ceci:: if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été sauvegardé.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible de sauvegarder l\'article.')); @@ -127,6 +128,7 @@ maintenant ressembler à ceci:: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Votre article a été modifié.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Impossible de mettre à jour votre article.')); @@ -360,6 +362,7 @@ entity, nous ajoutons un champ virtuel/pré-calculé pour l'entity. Dans $str = $tags->reduce(function ($string, $tag) { return $string . $tag->title . ', '; }, ''); + return trim($str, ', '); } @@ -451,6 +454,7 @@ trouver/construire les entities correspondantes. Ajoutez le code suivant à foreach ($newTags as $tag) { $out[] = $this->Tags->newEntity(['title' => $tag]); } + return $out; } diff --git a/fr/views/helpers/breadcrumbs.rst b/fr/views/helpers/breadcrumbs.rst index 8b719a89be..417d889164 100644 --- a/fr/views/helpers/breadcrumbs.rst +++ b/fr/views/helpers/breadcrumbs.rst @@ -194,6 +194,7 @@ complètement réinitialiser la liste:: $crumbs = $this->Breadcrumbs->getCrumbs(); $crumbs = collection($crumbs)->map(function ($crumb) { $crumb['options']['class'] = 'breadcrumb-item'; + return $crumb; })->toArray(); diff --git a/fr/views/helpers/form.rst b/fr/views/helpers/form.rst index f9f0250ed4..e9875f21e9 100644 --- a/fr/views/helpers/form.rst +++ b/fr/views/helpers/form.rst @@ -2542,6 +2542,7 @@ vouliez construire un widget Autocomplete, vous pourriez le faire comme ceci:: $data += [ 'name' => '', ]; + return $this->_templates->format('autocomplete', [ 'name' => $data['name'], 'attrs' => $this->_templates->formatAttributes($data, ['name']) diff --git a/ja/console-commands/commands.rst b/ja/console-commands/commands.rst index 939ad7d25e..39fbab0d21 100644 --- a/ja/console-commands/commands.rst +++ b/ja/console-commands/commands.rst @@ -62,6 +62,7 @@ CakePHP には、開発のスピードアップと日常的なタスクの自動 $parser->addArgument('name', [ 'help' => 'What is your name' ]); + return $parser; } diff --git a/ja/console-commands/shells.rst b/ja/console-commands/shells.rst index c965361f52..f32d6f41b6 100644 --- a/ja/console-commands/shells.rst +++ b/ja/console-commands/shells.rst @@ -146,6 +146,7 @@ public メソッドのうち頭に _ が付かないものは、コマンドラ // オプションパーサーを互いにリンク 'parser' => $this->Sound->getOptionParser(), ]); + return $parser; } diff --git a/ja/controllers.rst b/ja/controllers.rst index b4ca388f23..117330e775 100644 --- a/ja/controllers.rst +++ b/ja/controllers.rst @@ -343,6 +343,7 @@ match-allビューは、content-typeのネゴシエーションが試みられ ['controller' => 'Orders', 'action' => 'thanks'] ); } + return $this->redirect( ['controller' => 'Orders', 'action' => 'confirm'] ); @@ -355,6 +356,7 @@ match-allビューは、content-typeのネゴシエーションが試みられ $url 引数に相対 URL または絶対 URL を指定することもできます。 :: return $this->redirect('/orders/thanks'); + return $this->redirect('http://www.example.com'); アクションにデータを渡すこともできます。 :: diff --git a/ja/controllers/components.rst b/ja/controllers/components.rst index 8708dd6a20..b97a58b116 100644 --- a/ja/controllers/components.rst +++ b/ja/controllers/components.rst @@ -140,6 +140,7 @@ CakePHP の中に含まれるコンポーネントの詳細については、各 { if ($this->Post->delete($this->request->getData('Post.id')) { $this->Flash->success('Post deleted.'); + return $this->redirect(['action' => 'index']); } } @@ -313,6 +314,7 @@ CakePHP の中に含まれるコンポーネントの詳細については、各 public function beforeFilter(EventInterface $event) { $event->stopPropagation(); + return $this->getController()->redirect('/'); } diff --git a/ja/controllers/components/authentication.rst b/ja/controllers/components/authentication.rst index 74ec8983f4..e50e2422f7 100644 --- a/ja/controllers/components/authentication.rst +++ b/ja/controllers/components/authentication.rst @@ -221,6 +221,7 @@ SSL 暗号化しないアプリケーションにもふさわしいものです $user = $this->Auth->identify(); if ($user) { $this->Auth->setUser($user); + return $this->redirect($this->Auth->redirectUrl()); } else { $this->Flash->error(__('Username or password is incorrect')); @@ -303,6 +304,7 @@ AuthComponent がユーザーレコードの格納にセッションを使用し if (empty($username) || empty($pass)) { return false; } + return $this->_findUser($username, $pass); } @@ -368,6 +370,7 @@ CakePHP のライブラリーを使用してランダムにこれらの API ト // トークンを Bcrypt で暗号化 $entity->api_key = $hasher->hash($entity->api_key_plain); } + return true; } } @@ -427,6 +430,7 @@ CakePHP のライブラリーを使用してランダムにこれらの API ト $entity->plain_password, env('SERVER_NAME') ); + return true; } } @@ -674,6 +678,7 @@ CakePHP は、1つのアルゴリズムから別のユーザーのパスワー $user->password = $this->request->getData('password'); $this->Users->save($user); } + return $this->redirect($this->Auth->redirectUrl()); } ... @@ -697,6 +702,7 @@ CakePHP は、1つのアルゴリズムから別のユーザーのパスワー $user = $this->Users->newEntity($this->request->getData()); if ($this->Users->save($user)) { $this->Auth->setUser($user->toArray()); + return $this->redirect([ 'controller' => 'Users', 'action' => 'home' diff --git a/ja/controllers/middleware.rst b/ja/controllers/middleware.rst index 8900fe3e09..876416a425 100644 --- a/ja/controllers/middleware.rst +++ b/ja/controllers/middleware.rst @@ -74,6 +74,7 @@ CakePHP はウェブアプリケーションの一般的なタスクを処理す { // ミドルウェアのキューにエラーハンドラーを結びつけます。 $middlewareQueue->add(new ErrorHandlerMiddleware()); + return $middlewareQueue; } } @@ -110,7 +111,7 @@ CakePHP はウェブアプリケーションの一般的なタスクを処理す If your middleware is only applicable to a subset of routes or individual -controllers you can use :ref:`Route scoped middleware `, +controllers you can use :ref:`Route scoped middleware `, or :ref:`Controller middleware `. プラグインからのミドルウェア追加 diff --git a/ja/core-libraries/events.rst b/ja/core-libraries/events.rst index 63613580d5..4a54582fec 100644 --- a/ja/core-libraries/events.rst +++ b/ja/core-libraries/events.rst @@ -63,8 +63,10 @@ CakePHP は、jQuery などの一般的な JavaScript フレームワークに 'order' => $order ]); $this->getEventManager()->dispatch($event); + return true; } + return false; } } @@ -434,6 +436,7 @@ DOM イベントのように、追加のリスナーへ通知されることを { // ... $alteredData = $event->getData('order') + $moreData; + return $alteredData; } diff --git a/ja/core-libraries/logging.rst b/ja/core-libraries/logging.rst index df9f2ede7a..e6dae37f19 100644 --- a/ja/core-libraries/logging.rst +++ b/ja/core-libraries/logging.rst @@ -428,6 +428,7 @@ Composer を使って Monolog をインストールしたら、 Log::setConfig('default', function () { $log = new Logger('app'); $log->pushHandler(new StreamHandler('path/to/your/combined.log')); + return $log; }); @@ -445,6 +446,7 @@ Composer を使って Monolog をインストールしたら、 Log::setConfig('default', function () { $log = new Logger('cli'); $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log')); + return $log; }); diff --git a/ja/core-libraries/validation.rst b/ja/core-libraries/validation.rst index 170729f76a..de9d3a1115 100644 --- a/ja/core-libraries/validation.rst +++ b/ja/core-libraries/validation.rst @@ -287,6 +287,7 @@ CakePHPは6つの異なる形状のデータに対して空の値のサポート if (isset($context['data']['action'])) { return $context['data']['action'] === 'subscribe'; } + return false; }); $validator->requirePresence('email'); diff --git a/ja/development/errors.rst b/ja/development/errors.rst index 9ddfd44114..778e5fa788 100644 --- a/ja/development/errors.rst +++ b/ja/development/errors.rst @@ -196,6 +196,7 @@ ExceptionRenderer の変更 public function missingWidget($error) { $response = $this->controller->response; + return $response->withStringBody('おっとウィジェットが見つからない！'); } } diff --git a/ja/development/routing.rst b/ja/development/routing.rst index 717769aa20..5782751f7e 100644 --- a/ja/development/routing.rst +++ b/ja/development/routing.rst @@ -1437,6 +1437,7 @@ URL フィルターは永続的なパラメーターなどを簡単に扱う機 if ($request->getParam('lang') && !isset($params['lang'])) { $params['lang'] = $request->getParam('lang'); } + return $params; }); @@ -1454,6 +1455,7 @@ URL フィルターは永続的なパラメーターなどを簡単に扱う機 $params['language'] = $params[0]; unset($params[0]); } + return $params; }); diff --git a/ja/development/sessions.rst b/ja/development/sessions.rst index da348ce978..1e54a0f490 100644 --- a/ja/development/sessions.rst +++ b/ja/development/sessions.rst @@ -258,6 +258,7 @@ IO をもたらします。 if ($result) { return $result; } + return parent::read($id); } @@ -265,6 +266,7 @@ IO をもたらします。 public function write($id, $data): bool { Cache::write($id, $data, $this->cacheKey); + return parent::write($id, $data); } @@ -272,6 +274,7 @@ IO をもたらします。 public function destroy($id): bool { Cache::delete($id, $this->cacheKey); + return parent::destroy($id); } diff --git a/ja/development/testing.rst b/ja/development/testing.rst index 49680b3b87..1be3a265ac 100644 --- a/ja/development/testing.rst +++ b/ja/development/testing.rst @@ -133,6 +133,7 @@ CakePHP が全般的にそうであるように、テストケースにもいく public function bar($value) { $width = round($value / 100, 2) * 100; + return sprintf( '
    @@ -745,6 +746,7 @@ CakePHPコアまたはプラグインからフィクスチャをロードする $query->where([ $this->alias() . '.published' => 1 ]); + return $query; } } @@ -1769,8 +1771,10 @@ Orders を例に詳しく説明します。以下のテーブルを持ってい 'order' => $order ]); $this->getEventManager()->dispatch($event); + return true; } + return false; } } diff --git a/ja/orm/behaviors.rst b/ja/orm/behaviors.rst index ecb211204d..857a1fcd65 100644 --- a/ja/orm/behaviors.rst +++ b/ja/orm/behaviors.rst @@ -175,6 +175,7 @@ sluggable behavior を作成してみます。 if (...) { $event->stopPropagation(); $event->setResult(false); + return; } $this->slug($entity); diff --git a/ja/orm/database-basics.rst b/ja/orm/database-basics.rst index c8072d236e..4e1b604837 100644 --- a/ja/orm/database-basics.rst +++ b/ja/orm/database-basics.rst @@ -443,6 +443,7 @@ Type クラスは次のメソッドを実装することが期待されます。 if ($value === null) { return null; } + return json_decode($value, true); } @@ -451,6 +452,7 @@ Type クラスは次のメソッドを実装することが期待されます。 if (is_array($value) || $value === null) { return $value; } + return json_decode($value, true); } @@ -464,6 +466,7 @@ Type クラスは次のメソッドを実装することが期待されます。 if ($value === null) { return PDO::PARAM_NULL; } + return PDO::PARAM_STR; } @@ -571,6 +574,7 @@ Type クラスが必要になります。 :: if (is_array($value)) { return new Point($value[0], $value[1]); } + return null; } diff --git a/ja/orm/query-builder.rst b/ja/orm/query-builder.rst index b71fc0b703..d8f5e5aecb 100644 --- a/ja/orm/query-builder.rst +++ b/ja/orm/query-builder.rst @@ -168,6 +168,7 @@ Query オブジェクトのメソッドに慣れたら、 :doc:`Collection map(function ($row) { // map() は Collection のメソッドで、クエリーを実行します $row->trimmedTitle = trim($row->title); + return $row; }) ->combine('id', 'trimmedTitle') // combine() も Collection のメソッドです @@ -550,6 +551,7 @@ ORM とオブジェクトの結果セットは強力である一方で、エン $query->formatResults(function (\Cake\Collection\CollectionInterface $results) { return $results->map(function ($row) { $row['age'] = $row['birth_date']->diff(new \DateTime)->y; + return $row; }); }); @@ -570,6 +572,7 @@ CakePHP はフォーマッタ関数が適切なスコープになるよう保証 return $q->formatResults(function (\Cake\Collection\CollectionInterface $authors) { return $authors->map(function ($author) { $author['age'] = $author['birth_date']->diff(new \DateTime)->y; + return $author; }); }); @@ -679,6 +682,7 @@ Conditions ->where(function (QueryExpression $exp) { $orConditions = $exp->or(['author_id' => 2]) ->eq('author_id', 5); + return $exp ->add($orConditions) ->eq('published', true) @@ -706,6 +710,7 @@ Conditions return $or->eq('author_id', 2) ->eq('author_id', 5); }); + return $exp ->not($orConditions) ->lte('view_count', 10); @@ -717,6 +722,7 @@ Conditions ->where(function (QueryExpression $exp) { $orConditions = $exp->or(['author_id' => 2]) ->eq('author_id', 5); + return $exp ->not($orConditions) ->lte('view_count', 10); @@ -740,6 +746,7 @@ SQL 関数を使った式を構築することも可能です。 :: $year = $q->func()->year([ 'created' => 'identifier' ]); + return $exp ->gte($year, 2014) ->eq('published', true); diff --git a/ja/orm/retrieving-data-and-resultsets.rst b/ja/orm/retrieving-data-and-resultsets.rst index 24b93cc72f..b9ec28ff61 100644 --- a/ja/orm/retrieving-data-and-resultsets.rst +++ b/ja/orm/retrieving-data-and-resultsets.rst @@ -357,6 +357,7 @@ finder メソッドは、あなたが作成したい finder の名前が ``Foo`` public function findOwnedBy(SelectQuery $query, array $options) { $user = $options['user']; + return $query->where(['author_id' => $user->id]); } } @@ -920,6 +921,7 @@ serialize が簡単にできるだけでなく、結果セットは 'Collection' if (!in_array($value, $output)) { $output[] = $value; } + return $output; }; @@ -1186,6 +1188,7 @@ reducer が呼ばれるごとに、reducer はユーザーごとのフォロワ // 前のセクションで説明した共通の単語の件と同じもの $mapper = ...; $reducer = ...; + return $query->mapReduce($mapper, $reducer); } diff --git a/ja/orm/table-objects.rst b/ja/orm/table-objects.rst index 3835b0430f..7ab7624052 100644 --- a/ja/orm/table-objects.rst +++ b/ja/orm/table-objects.rst @@ -344,6 +344,7 @@ Stopping Table Events if (...) { $event->stopPropagation(); $event->setResult(false); + return; } ... diff --git a/ja/orm/validation.rst b/ja/orm/validation.rst index 6b7f034af9..d1273da632 100644 --- a/ja/orm/validation.rst +++ b/ja/orm/validation.rst @@ -113,6 +113,7 @@ CakePHP ではデータの検証には二つの段階があります: $validator ->notEmptyString('title', __('タイトルを設定してください')) ->notEmptyString('body', __('本文は必須です')); + return $validator; } } @@ -174,6 +175,7 @@ CakePHP ではデータの検証には二つの段階があります: $validator = $this->validationDefault($validator); $validator->add('password', 'length', ['rule' => ['lengthBetween', 8, 100]]); + return $validator; } @@ -207,6 +209,7 @@ CakePHP ではデータの検証には二つの段階があります: 'message' => __('有効な権限を指定する必要があります'), 'provider' => 'table', ]); + return $validator; } @@ -224,6 +227,7 @@ CakePHP ではデータの検証には二つの段階があります: if ($value > 1) { return true; } + return '適切な値ではありません。'; } ]); @@ -531,6 +535,7 @@ CakePHP は、エンティティーが保存される前に適用される「ル 'errorField' => 'name', 'message' => 'Name must be unique per parent.' ]); + return $rules; } @@ -606,6 +611,7 @@ CakePHP の ORM は検証に二層のアプローチを使う点がユニーク public function validationCustomName($validator) { $validator->add(...); + return $validator; } diff --git a/ja/security/csrf.rst b/ja/security/csrf.rst index 85685d9f97..98018be596 100644 --- a/ja/security/csrf.rst +++ b/ja/security/csrf.rst @@ -52,6 +52,7 @@ CSRFプロテクションは、アプリケーション全体、または特定 $csrf = new SessionCsrfProtectionMiddleware($options); $middlewareQueue->add($csrf); + return $middlewareQueue; } diff --git a/ja/tutorials-and-examples/blog-auth-example/auth.rst b/ja/tutorials-and-examples/blog-auth-example/auth.rst index 8acbcc39d7..44746409ce 100644 --- a/ja/tutorials-and-examples/blog-auth-example/auth.rst +++ b/ja/tutorials-and-examples/blog-auth-example/auth.rst @@ -81,6 +81,7 @@ CakePHP にバンドルされているコード生成ユーティリティを利 $user = $this->Users->patchEntity($user, $this->request->getData()); if ($this->Users->save($user)) { $this->Flash->success(__('The user has been saved.')); + return $this->redirect(['action' => 'add']); } $this->Flash->error(__('Unable to add the user.')); @@ -342,6 +343,7 @@ composerを使ってAuthenticationプラグインをインストールします // POSTやGETに関係なく、ユーザーがログインしていればリダイレクトします if ($result->isValid()) { $this->Authentication->logout(); + return $this->redirect(['controller' => 'Users', 'action' => 'login']); } } diff --git a/ja/tutorials-and-examples/blog/part-three.rst b/ja/tutorials-and-examples/blog/part-three.rst index 8635ae8607..e56ada8bfc 100644 --- a/ja/tutorials-and-examples/blog/part-three.rst +++ b/ja/tutorials-and-examples/blog/part-three.rst @@ -262,6 +262,7 @@ categories の index テンプレートファイルでは、categories を一覧 } else { $this->Flash->error('The category could not be moved up. Please, try again.'); } + return $this->redirect($this->referer(['action' => 'index'])); } @@ -274,6 +275,7 @@ categories の index テンプレートファイルでは、categories を一覧 } else { $this->Flash->error('The category could not be moved down. Please, try again.'); } + return $this->redirect($this->referer(['action' => 'index'])); } } @@ -347,6 +349,7 @@ Articles コントローラーを編集する $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); diff --git a/ja/tutorials-and-examples/blog/part-two.rst b/ja/tutorials-and-examples/blog/part-two.rst index 52f1aee036..c885c4f258 100644 --- a/ja/tutorials-and-examples/blog/part-two.rst +++ b/ja/tutorials-and-examples/blog/part-two.rst @@ -280,6 +280,7 @@ Articles テーブルに対して ``get()`` を用いるとき、存在するレ $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('記事が保存されました。')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('記事の保存が出来ませんでした。')); @@ -436,6 +437,7 @@ CakePHP のバリデーションエンジンは強力で、 $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('記事が更新されました。')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('記事の更新が出来ませんでした。')); @@ -523,6 +525,7 @@ CakePHP は挿入あるいは更新のどちらを生成するかを決定しま $article = $this->Articles->get($id); if ($this->Articles->delete($article)) { $this->Flash->success(__('ID：{0}の記事が削除されました。', h($id))); + return $this->redirect(['action' => 'index']); } } diff --git a/ja/tutorials-and-examples/bookmarks/intro.rst b/ja/tutorials-and-examples/bookmarks/intro.rst index dd1955d54e..45611fd2d8 100644 --- a/ja/tutorials-and-examples/bookmarks/intro.rst +++ b/ja/tutorials-and-examples/bookmarks/intro.rst @@ -237,6 +237,7 @@ Scaffold コードの生成 protected function _setPassword($value) { $hasher = new DefaultPasswordHasher(); + return $hasher->hash($value); } } diff --git a/ja/tutorials-and-examples/bookmarks/part-two.rst b/ja/tutorials-and-examples/bookmarks/part-two.rst index 433e60b80d..1856bf02e2 100644 --- a/ja/tutorials-and-examples/bookmarks/part-two.rst +++ b/ja/tutorials-and-examples/bookmarks/part-two.rst @@ -61,6 +61,7 @@ AppController に追加しましょう。 :: $user = $this->Auth->identify(); if ($user) { $this->Auth->setUser($user); + return $this->redirect($this->Auth->redirectUrl()); } $this->Flash->error('あなたのユーザー名またはパスワードが不正です。'); @@ -104,6 +105,7 @@ AppController に追加しましょう。 :: public function logout() { $this->Flash->success('ログアウトしました。'); + return $this->redirect($this->Auth->logout()); } @@ -198,6 +200,7 @@ AppController に追加しましょう。 :: if ($bookmark->user_id == $user['id']) { return true; } + return parent::isAuthorized($user); } @@ -231,6 +234,7 @@ AppController に追加しましょう。 :: $bookmark->user_id = $this->Auth->user('id'); if ($this->Bookmarks->save($bookmark)) { $this->Flash->success('ブックマークを保存しました。'); + return $this->redirect(['action' => 'index']); } $this->Flash->error('ブックマークは保存できませんでした。もう一度お試しください。'); @@ -254,6 +258,7 @@ AppController に追加しましょう。 :: $bookmark->user_id = $this->Auth->user('id'); if ($this->Bookmarks->save($bookmark)) { $this->Flash->success('ブックマークを保存しました。'); + return $this->redirect(['action' => 'index']); } $this->Flash->error('ブックマークは保存できませんでした。もう一度お試しください。'); @@ -312,6 +317,7 @@ AppController に追加しましょう。 :: $str = $tags->reduce(function ($string, $tag) { return $string . $tag->title . ', '; }, ''); + return trim($str, ', '); } @@ -384,6 +390,7 @@ AppController に追加しましょう。 :: foreach ($newTags as $tag) { $out[] = $this->Tags->newEntity(['title' => $tag]); } + return $out; } diff --git a/ja/tutorials-and-examples/cms/articles-controller.rst b/ja/tutorials-and-examples/cms/articles-controller.rst index 1ed95213c8..352cf90b83 100644 --- a/ja/tutorials-and-examples/cms/articles-controller.rst +++ b/ja/tutorials-and-examples/cms/articles-controller.rst @@ -209,6 +209,7 @@ view テンプレートの作成 if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); @@ -341,6 +342,7 @@ edit アクションの追加 $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been updated.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to update your article.')); @@ -470,6 +472,7 @@ delete アクションの追加 $article = $this->Articles->findBySlug($slug)->firstOrFail(); if ($this->Articles->delete($article)) { $this->Flash->success(__('The {0} article has been deleted.', $article->title)); + return $this->redirect(['action' => 'index']); } } diff --git a/ja/tutorials-and-examples/cms/authentication.rst b/ja/tutorials-and-examples/cms/authentication.rst index 234525c636..f26e193f04 100644 --- a/ja/tutorials-and-examples/cms/authentication.rst +++ b/ja/tutorials-and-examples/cms/authentication.rst @@ -266,6 +266,7 @@ logout アクションを ``UsersController`` に追加します。:: // POST, GET を問わず、ユーザーがログインしている場合はリダイレクトします if ($result && $result->isValid()) { $this->Authentication->logout(); + return $this->redirect(['controller' => 'Users', 'action' => 'login']); } } diff --git a/ja/tutorials-and-examples/cms/tags-and-users.rst b/ja/tutorials-and-examples/cms/tags-and-users.rst index 8098e41a72..d72f4b9523 100644 --- a/ja/tutorials-and-examples/cms/tags-and-users.rst +++ b/ja/tutorials-and-examples/cms/tags-and-users.rst @@ -79,6 +79,7 @@ ArticlesTable の ``initialize`` メソッドに以下を追加することで if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); @@ -117,6 +118,7 @@ edit メソッドは次のようになります。 :: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been updated.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to update your article.')); @@ -337,6 +339,7 @@ CakePHP では、コントローラーのアクションをスリムに保ち、 $str = $tags->reduce(function ($string, $tag) { return $string . $tag->title . ', '; }, ''); + return trim($str, ', '); } @@ -422,6 +425,7 @@ CakePHP では、コントローラーのアクションをスリムに保ち、 foreach ($newTags as $tag) { $out[] = $this->Tags->newEntity(['title' => $tag]); } + return $out; } diff --git a/ja/views/helpers/breadcrumbs.rst b/ja/views/helpers/breadcrumbs.rst index b8648d5ac4..8b6dd20e6b 100644 --- a/ja/views/helpers/breadcrumbs.rst +++ b/ja/views/helpers/breadcrumbs.rst @@ -176,6 +176,7 @@ BreadcrumbsHelper は内部で ``StringTemplateTrait`` を使用しています $crumbs = $this->Breadcrumbs->getCrumbs(); $crumbs = collection($crumbs)->map(function ($crumb) { $crumb['options']['class'] = 'breadcrumb-item'; + return $crumb; })->toArray(); diff --git a/ja/views/helpers/form.rst b/ja/views/helpers/form.rst index cf42f298b3..68eb4ffeb8 100644 --- a/ja/views/helpers/form.rst +++ b/ja/views/helpers/form.rst @@ -2540,6 +2540,7 @@ autocomplete ウィジェットを作成したい場合、以下を実行でき $data += [ 'name' => '', ]; + return $this->_templates->format('autocomplete', [ 'name' => $data['name'], 'attrs' => $this->_templates->formatAttributes($data, ['name']) diff --git a/pt/console-and-shells.rst b/pt/console-and-shells.rst index 105f611294..f25b6e8281 100644 --- a/pt/console-and-shells.rst +++ b/pt/console-and-shells.rst @@ -516,6 +516,7 @@ série de chamadas de métodos:: 'short' => 'm', 'help' => __('The specific method you want help on.') ])->description(__('Lookup doc block comments for classes in CakePHP.')); + return $parser; } diff --git a/pt/contributing/cakephp-coding-conventions.rst b/pt/contributing/cakephp-coding-conventions.rst index 6886e7c0a5..eab94b75c0 100644 --- a/pt/contributing/cakephp-coding-conventions.rst +++ b/pt/contributing/cakephp-coding-conventions.rst @@ -212,6 +212,7 @@ Exemplo de uma definição de método:: if (expr) { declaração; } + return $var; } @@ -230,6 +231,7 @@ de uma função. Tente fazer suas funções retornarem algo, pelo menos ``true`` if (!($dnsInfo) || !($dnsInfo['phpType'])) { return $this->addError(); } + return true; } diff --git a/pt/controllers.rst b/pt/controllers.rst index ad037f1748..d44cd86f29 100644 --- a/pt/controllers.rst +++ b/pt/controllers.rst @@ -294,6 +294,7 @@ você pode querer redirecioná-lo para uma tela de recepção. :: ['controller' => 'Orders', 'action' => 'thanks'] ); } + return $this->redirect( ['controller' => 'Orders', 'action' => 'confirm'] ); @@ -307,6 +308,7 @@ corrente. Você também pode usar uma URL relativa ou absoluta como o parâmetro $url:: return $this->redirect('/orders/thanks'); + return $this->redirect('http://www.example.com'); Você também pode passar dados para a action:: diff --git a/pt/controllers/components.rst b/pt/controllers/components.rst index 425dea5277..43609cb2ed 100644 --- a/pt/controllers/components.rst +++ b/pt/controllers/components.rst @@ -1,14 +1,14 @@ Componentes ########### -Componentes são pacotes de lógica compartilhados entre controladores. O CakePHP -vem com um conjunto fantástico de componentes principais que você pode usar para +Componentes são pacotes de lógica compartilhados entre controladores. O CakePHP +vem com um conjunto fantástico de componentes principais que você pode usar para ajudar em várias tarefas comuns. Você também pode criar seus próprios componentes. -Se você deseja copiar e colar coisas entre controladores, considere criar seu próprio -componente para conter a funcionalidade. A criação de componentes mantém o código do +Se você deseja copiar e colar coisas entre controladores, considere criar seu próprio +componente para conter a funcionalidade. A criação de componentes mantém o código do controlador limpo e permite reutilizar o código entre diferentes controladores. -Para mais informações sobre os componentes incluídos no CakePHP, consulte o +Para mais informações sobre os componentes incluídos no CakePHP, consulte o capítulo para cada componente: .. toctree:: @@ -25,9 +25,9 @@ capítulo para cada componente: Configurando Componentes ======================== -Muitos dos componentes principais requerem configuração. Alguns exemplos de componentes -que requerem configuração são :doc:`/controllers/components/security` e -:doc:`/controllers/components/request-handling`. A configuração desses componentes e dos +Muitos dos componentes principais requerem configuração. Alguns exemplos de componentes +que requerem configuração são :doc:`/controllers/components/security` e +:doc:`/controllers/components/request-handling`. A configuração desses componentes e dos componentes em geral é geralmente feita via ``loadComponent()`` no método ``initialize()`` do seu Controlador ou através do array ``$components``:: @@ -45,7 +45,7 @@ do seu Controlador ou através do array ``$components``:: } Você pode configurar componentes em tempo de execução usando o método ``setConfig()``. -Muitas vezes, isso é feito no método ``beforeFilter()`` do seu controlador. O exemplo acima +Muitas vezes, isso é feito no método ``beforeFilter()`` do seu controlador. O exemplo acima também pode ser expresso como:: public function beforeFilter(EventInterface $event) @@ -53,7 +53,7 @@ também pode ser expresso como:: $this->RequestHandler->setConfig('viewClassMap', ['rss' => 'MyRssView']); } -Como os auxiliares, os componentes implementam os métodos ``getConfig()`` e +Como os auxiliares, os componentes implementam os métodos ``getConfig()`` e ``setConfig()`` para ler e gravar dados de configuração:: // Leia os dados de configuração. @@ -62,14 +62,14 @@ Como os auxiliares, os componentes implementam os métodos ``getConfig()`` e // Definir configuração $this->Csrf->setConfig('cookieName', 'token'); -Assim como os auxiliares, os componentes mesclam automaticamente sua propriedade -``$ _defaultConfig`` com a configuração do construtor para criar a propriedade +Assim como os auxiliares, os componentes mesclam automaticamente sua propriedade +``$ _defaultConfig`` com a configuração do construtor para criar a propriedade ``$_config`` que pode ser acessada com ``getConfig()`` e ``setConfig()``. Alias em Componentes -------------------- -Uma configuração comum a ser usada é a opção ``className``, que permite o alias +Uma configuração comum a ser usada é a opção ``className``, que permite o alias de componentes. Esse recurso é útil quando você deseja substituir ``$this->Auth`` ou outra referência de componente comum por uma implementação personalizada:: @@ -96,14 +96,14 @@ O exemplo acima seria *alias* ``MyAuthComponent`` para ``$this->Auth`` em seus c .. note:: - O alias de um componente substitui essa instância em qualquer lugar em que esse componente + O alias de um componente substitui essa instância em qualquer lugar em que esse componente seja usado, inclusive dentro de outros componentes. Carregando Componentes em Tempo Real ------------------------------------ -Você pode não precisar de todos os seus componentes disponíveis em todas as ações do controlador. -Em situações como essa, você pode carregar um componente em tempo de execução usando o método +Você pode não precisar de todos os seus componentes disponíveis em todas as ações do controlador. +Em situações como essa, você pode carregar um componente em tempo de execução usando o método ``loadComponent()`` no seu controlador:: // Em um método do controlador @@ -112,16 +112,16 @@ Em situações como essa, você pode carregar um componente em tempo de execuç .. note:: - Lembre-se de que os componentes carregados em tempo real não terão retornos de chamada perdidos. - Se você confiar nos retornos de chamada ``beforeFilter`` ou ``startup`` que estão sendo chamados, + Lembre-se de que os componentes carregados em tempo real não terão retornos de chamada perdidos. + Se você confiar nos retornos de chamada ``beforeFilter`` ou ``startup`` que estão sendo chamados, pode ser necessário chamá-los manualmente, dependendo de quando você carregar o componente. Usando Componentes ================== -Depois de incluir alguns componentes no seu controlador, usá-los é bastante simples. -Cada componente usado é exposto como uma propriedade no seu controlador. Se você -carregou a classe :php:class:`Cake\\Controller\\Component\\FlashComponent` no seu +Depois de incluir alguns componentes no seu controlador, usá-los é bastante simples. +Cada componente usado é exposto como uma propriedade no seu controlador. Se você +carregou a classe :php:class:`Cake\\Controller\\Component\\FlashComponent` no seu controlador, é possível acessá-lo da seguinte maneira:: class PostsController extends AppController @@ -136,14 +136,15 @@ controlador, é possível acessá-lo da seguinte maneira:: { if ($this->Post->delete($this->request->getData('Post.id')) { $this->Flash->success('Post deleted.'); + return $this->redirect(['action' => 'index']); } } .. note:: - Como os Modelos e os Componentes são adicionados aos Controladores - como propriedades, eles compartilham o mesmo 'namespace'. Certifique-se + Como os Modelos e os Componentes são adicionados aos Controladores + como propriedades, eles compartilham o mesmo 'namespace'. Certifique-se de não dar o mesmo nome a um componente de um modelo. .. _creating-a-component: @@ -151,12 +152,12 @@ controlador, é possível acessá-lo da seguinte maneira:: Criando um Componente ===================== -Suponha que nosso aplicativo precise executar uma operação matemática complexa -em muitas partes diferentes do aplicativo. Poderíamos criar um componente para +Suponha que nosso aplicativo precise executar uma operação matemática complexa +em muitas partes diferentes do aplicativo. Poderíamos criar um componente para hospedar essa lógica compartilhada para uso em muitos controladores diferentes. -O primeiro passo é criar um novo arquivo e classe de componente. Crie o arquivo em -**src/Controller/Component/MathComponent.php**. A estrutura básica do componente +O primeiro passo é criar um novo arquivo e classe de componente. Crie o arquivo em +**src/Controller/Component/MathComponent.php**. A estrutura básica do componente será semelhante a isso:: namespace App\Controller\Component; @@ -173,19 +174,19 @@ será semelhante a isso:: .. note:: - Todos os componentes devem estender :php:class:`Cake\\Controller\\Component`. + Todos os componentes devem estender :php:class:`Cake\\Controller\\Component`. Não fazer isso acionará uma exceção. Incluindo seu Componente em seus Controladores ---------------------------------------------- -Depois que nosso componente é concluído, podemos usá-lo nos controladores -do aplicativo carregando-o durante o método ``initialize()`` do controlador. -Uma vez carregado, o controlador receberá um novo atributo com o nome do componente, +Depois que nosso componente é concluído, podemos usá-lo nos controladores +do aplicativo carregando-o durante o método ``initialize()`` do controlador. +Uma vez carregado, o controlador receberá um novo atributo com o nome do componente, através do qual podemos acessar uma instância dele:: // Em um controlador - // Disponibilize o novo componente em $this->Math, + // Disponibilize o novo componente em $this->Math, // bem como o padrão $this->Csrf public function initialize(): void { @@ -194,8 +195,8 @@ através do qual podemos acessar uma instância dele:: $this->loadComponent('Csrf'); } -Ao incluir componentes em um controlador, você também pode declarar -um conjunto de parâmetros que serão passados para o construtor do componente. +Ao incluir componentes em um controlador, você também pode declarar +um conjunto de parâmetros que serão passados para o construtor do componente. Esses parâmetros podem ser manipulados pelo componente:: // Em seu controlador @@ -209,14 +210,14 @@ Esses parâmetros podem ser manipulados pelo componente:: $this->loadComponent('Csrf'); } -O exemplo acima passaria um array contendo precision e randomGenerator +O exemplo acima passaria um array contendo precision e randomGenerator para ``MathComponent::initialize()`` no parâmetro ``$config``. Usando Outros Componentes em seu Componente ------------------------------------------- -Às vezes, um de seus componentes pode precisar usar outro componente. -Nesse caso, você pode incluir outros componentes no seu componente +Às vezes, um de seus componentes pode precisar usar outro componente. +Nesse caso, você pode incluir outros componentes no seu componente exatamente da mesma maneira que os inclui nos controladores - usando o atributo ``$components``:: @@ -258,18 +259,18 @@ atributo ``$components``:: .. note:: - Ao contrário de um componente incluído em um controlador, + Ao contrário de um componente incluído em um controlador, nenhum retorno de chamada será acionado no componente de um componente. Acessando o Controlador de um Componente ---------------------------------------- -De dentro de um componente, você pode acessar o controlador atual através do +De dentro de um componente, você pode acessar o controlador atual através do registro:: $controller = $this->_registry->getController(); -Você pode acessar o controlador em qualquer método de retorno de chamada do objeto de +Você pode acessar o controlador em qualquer método de retorno de chamada do objeto de evento:: $controller = $event->getSubject(); @@ -277,22 +278,22 @@ evento:: Callback de Componentes ======================= -Os componentes também oferecem alguns retornos de chamada do ciclo de vida da solicitação que +Os componentes também oferecem alguns retornos de chamada do ciclo de vida da solicitação que permitem aumentar o ciclo da solicitação. .. php:method:: beforeFilter(EventInterface $event) - É chamado antes do método beforeFilter do controlador, + É chamado antes do método beforeFilter do controlador, mas *após* o método initialize() do controlador. .. php:method:: startup(EventInterface $event) - É chamado após o método beforeFilter do controlador, + É chamado após o método beforeFilter do controlador, mas antes que o controlador execute o manipulador de ações atual. .. php:method:: beforeRender(EventInterface $event) - É chamado após o controlador executar a lógica da ação solicitada, + É chamado após o controlador executar a lógica da ação solicitada, mas antes de o controlador renderizar visualizações e layout. .. php:method:: shutdown(EventInterface $event) @@ -301,10 +302,10 @@ permitem aumentar o ciclo da solicitação. .. php:method:: beforeRedirect(EventInterface $event, $url, Response $response) - É chamado quando o método de redirecionamento do controlador é chamado, - mas antes de qualquer ação adicional. Se esse método retornar ``false``, - o controlador não continuará redirecionando a solicitação. Os parâmetros - $url e $response permitem inspecionar e modificar o local ou qualquer outro + É chamado quando o método de redirecionamento do controlador é chamado, + mas antes de qualquer ação adicional. Se esse método retornar ``false``, + o controlador não continuará redirecionando a solicitação. Os parâmetros + $url e $response permitem inspecionar e modificar o local ou qualquer outro cabeçalho na resposta. .. meta:: diff --git a/pt/controllers/components/authentication.rst b/pt/controllers/components/authentication.rst index 6cde10e025..2e9eb11b09 100644 --- a/pt/controllers/components/authentication.rst +++ b/pt/controllers/components/authentication.rst @@ -216,6 +216,7 @@ trabalhar com um formulário de login pode se parecer com:: $user = $this->Auth->identify(); if ($user) { $this->Auth->setUser($user); + return $this->redirect($this->Auth->redirectUrl()); } else { $this->Flash->error(__('Username or password is incorrect')); @@ -302,6 +303,7 @@ caso de falha. :: if (empty($username) || empty($pass)) { return false; } + return $this->_findUser($username, $pass); } @@ -369,6 +371,7 @@ do CakePHP:: // possa verificá-lo durante o login. $entity->api_key = $hasher->hash($entity->api_key_plain); } + return true; } } @@ -432,6 +435,7 @@ a partir do hash da senha normal:: $entity->plain_password, env('SERVER_NAME') ); + return true; } } @@ -693,6 +697,7 @@ a função de login de acordo:: $user->password = $this->request->getData('password'); $this->Users->save($user); } + return $this->redirect($this->Auth->redirectUrl()); } ... @@ -717,6 +722,7 @@ logo após ele se registrar no seu aplicativo. Você pode fazer isso chamando $user = $this->Users->newEntity($this->request->getData()); if ($this->Users->save($user)) { $this->Auth->setUser($user->toArray()); + return $this->redirect([ 'controller' => 'Users', 'action' => 'home' diff --git a/pt/controllers/components/request-handling.rst b/pt/controllers/components/request-handling.rst index 4f19ab90c6..5adebed49b 100644 --- a/pt/controllers/components/request-handling.rst +++ b/pt/controllers/components/request-handling.rst @@ -150,6 +150,7 @@ parecer:: foreach ($rows as &$row) { $row = str_getcsv($row, ','); } + return $rows; }; $this->loadComponent('RequestHandler', [ diff --git a/pt/controllers/middleware.rst b/pt/controllers/middleware.rst index 2b772318d6..06d02facf0 100644 --- a/pt/controllers/middleware.rst +++ b/pt/controllers/middleware.rst @@ -1,28 +1,28 @@ Middleware ########## -Os objetos de middleware permitem que você 'embrulhe' seu aplicativo em camadas -reutilizáveis e composíveis de manipulação de solicitações ou lógica de criação -de respostas. Visualmente, seu aplicativo termina no centro e o middleware é envolvido -em volta do aplicativo como uma cebola. Aqui, podemos ver um aplicativo agrupado com os +Os objetos de middleware permitem que você 'embrulhe' seu aplicativo em camadas +reutilizáveis e composíveis de manipulação de solicitações ou lógica de criação +de respostas. Visualmente, seu aplicativo termina no centro e o middleware é envolvido +em volta do aplicativo como uma cebola. Aqui, podemos ver um aplicativo agrupado com os middlewares Routes, Assets, Exception Handling e CORS. .. image:: /_static/img/middleware-setup.png -Quando um pedido é tratado pelo seu aplicativo, ele entra no middleware mais externo. -Cada middleware pode delegar a solicitação/resposta para a próxima camada ou retornar -uma resposta. O retorno de uma resposta impede que as camadas inferiores vejam a solicitação. -Um exemplo disso é o plugin AssetMiddleware manipulando uma solicitação de uma imagem de +Quando um pedido é tratado pelo seu aplicativo, ele entra no middleware mais externo. +Cada middleware pode delegar a solicitação/resposta para a próxima camada ou retornar +uma resposta. O retorno de uma resposta impede que as camadas inferiores vejam a solicitação. +Um exemplo disso é o plugin AssetMiddleware manipulando uma solicitação de uma imagem de durante o desenvolvimento. .. image:: /_static/img/middleware-request.png -Se nenhum middleware executar uma ação para manipular a solicitação, um controlador +Se nenhum middleware executar uma ação para manipular a solicitação, um controlador será localizado e terá sua ação invocada ou uma exceção será gerada gerando uma página de erro. -O middleware faz parte da nova pilha HTTP no CakePHP que aproveita as interfaces de solicitação e -resposta PSR-7. O CakePHP também suporta o padrão PSR-15 para manipuladores de solicitações de -servidor, para que você possa usar qualquer middleware compatível com PSR-15 disponível em +O middleware faz parte da nova pilha HTTP no CakePHP que aproveita as interfaces de solicitação e +resposta PSR-7. O CakePHP também suporta o padrão PSR-15 para manipuladores de solicitações de +servidor, para que você possa usar qualquer middleware compatível com PSR-15 disponível em `The Packagist `_. Middleware em CakePHP @@ -30,24 +30,24 @@ Middleware em CakePHP O CakePHP fornece vários middlewares para lidar com tarefas comuns em aplicativos da web: -* ``Cake\Error\Middleware\ErrorHandlerMiddleware`` intercepta exceções do middleware - empacotado e renderiza uma página de erro usando o manipulador de +* ``Cake\Error\Middleware\ErrorHandlerMiddleware`` intercepta exceções do middleware + empacotado e renderiza uma página de erro usando o manipulador de exceção :doc:`/development/errors`. -* ``Cake\Routing\AssetMiddleware`` verifica se a solicitação está se referindo a um tema ou - arquivo estático do plug-in, como CSS, JavaScript ou arquivo de imagem armazenado na pasta +* ``Cake\Routing\AssetMiddleware`` verifica se a solicitação está se referindo a um tema ou + arquivo estático do plug-in, como CSS, JavaScript ou arquivo de imagem armazenado na pasta raiz da web de um plug-in ou na pasta correspondente a um Tema. -* ``Cake\Routing\Middleware\RoutingMiddleware`` usa o ``Router`` para analisar a URL +* ``Cake\Routing\Middleware\RoutingMiddleware`` usa o ``Router`` para analisar a URL recebida e atribuir parâmetros de roteamento à solicitação. -* ``Cake\I18n\Middleware\LocaleSelectorMiddleware`` habilita a troca automática de idioma no +* ``Cake\I18n\Middleware\LocaleSelectorMiddleware`` habilita a troca automática de idioma no cabeçalho ``Accept-Language`` enviado pelo navegador. -* ``Cake\Http\Middleware\SecurityHeadersMiddleware`` facilita adicionar cabeçalhos relacionados +* ``Cake\Http\Middleware\SecurityHeadersMiddleware`` facilita adicionar cabeçalhos relacionados à segurança como ``X-Frame-Options`` às respostas. -* ``Cake\Http\Middleware\EncryptedCookieMiddleware`` oferece a capacidade de manipular cookies +* ``Cake\Http\Middleware\EncryptedCookieMiddleware`` oferece a capacidade de manipular cookies criptografados, caso você precise manipular cookies com dados ofuscados. * ``Cake\Http\Middleware\CsrfProtectionMiddleware`` adiciona proteção CSRF ao seu aplicativo. -* ``Cake\Http\Middleware\BodyParserMiddleware`` permite decodificar JSON, XML e outros corpos +* ``Cake\Http\Middleware\BodyParserMiddleware`` permite decodificar JSON, XML e outros corpos de solicitação codificados com base no cabeçalho ``Content-Type``. -* ``Cake\Http\Middleware\CspMiddleware`` simplifica a adição de cabeçalhos de política de +* ``Cake\Http\Middleware\CspMiddleware`` simplifica a adição de cabeçalhos de política de segurança de conteúdo ao seu aplicativo. .. _using-middleware: @@ -58,8 +58,8 @@ Usando Middleware O middleware pode ser aplicado ao seu aplicativo globalmente ou individualmente a escopos de roteamento. -Para aplicar o middleware a todas as solicitações, use o método ``middleware`` da sua classe -``App\Application``. O método de gancho ``middleware`` do seu aplicativo será chamado no +Para aplicar o middleware a todas as solicitações, use o método ``middleware`` da sua classe +``App\Application``. O método de gancho ``middleware`` do seu aplicativo será chamado no início do processo de solicitação; você pode usar o objeto ``MiddlewareQueue`` para anexar o middleware:: @@ -75,6 +75,7 @@ middleware:: { // Vincule o manipulador de erros à fila do middleware. $middlwareQueue->add(new ErrorHandlerMiddleware()); + return $middlwareQueue; } } @@ -89,7 +90,7 @@ Além de adicionar ao final do ``MiddlewareQueue``, você pode executar várias // O middleware precedido será o primeiro da fila. $middlwareQueue->prepend($layer); - // Insira em um slot específico. Se o slot estiver + // Insira em um slot específico. Se o slot estiver // fora dos limites, ele será adicionado ao final. $middlwareQueue->insertAt(2, $layer); @@ -109,14 +110,14 @@ Além de adicionar ao final do ``MiddlewareQueue``, você pode executar várias $layer ); -Além de aplicar o middleware a todo o aplicativo, você pode aplicar o -middleware a conjuntos específicos de rotas usando +Além de aplicar o middleware a todo o aplicativo, você pode aplicar o +middleware a conjuntos específicos de rotas usando :ref:`Scope Middleware `. Adicionando Middleware a partir de Plugins ------------------------------------------ -Os plug-ins podem usar seu método de gancho ``middleware`` para aplicar qualquer +Os plug-ins podem usar seu método de gancho ``middleware`` para aplicar qualquer middleware que eles tenham à fila de middleware do aplicativo:: // Em plugins/ContactManager/src/Plugin.php @@ -139,19 +140,19 @@ middleware que eles tenham à fila de middleware do aplicativo:: Criando um Middleware ===================== -O middleware pode ser implementado como funções anônimas (Closures) ou classes que -estendem ``Psr\Http\Server\MiddlewareInterface``. Embora os Closures sejam -adequados para tarefas menores, eles tornam os testes mais difíceis e podem criar -uma classe ``Application`` complicada. As classes de middleware no CakePHP têm +O middleware pode ser implementado como funções anônimas (Closures) ou classes que +estendem ``Psr\Http\Server\MiddlewareInterface``. Embora os Closures sejam +adequados para tarefas menores, eles tornam os testes mais difíceis e podem criar +uma classe ``Application`` complicada. As classes de middleware no CakePHP têm algumas convenções: -* Os arquivos de classe Middleware devem ser colocados em ** src/Middleware**. Por exemplo: +* Os arquivos de classe Middleware devem ser colocados em ** src/Middleware**. Por exemplo: **src/Middleware/CorsMiddleware.php** -* As classes de middleware devem ter o sufixo ``Middleware``. Por exemplo: +* As classes de middleware devem ter o sufixo ``Middleware``. Por exemplo: ``LinkMiddleware``. * O Middleware deve implementar ``Psr\Http\Server\MiddlewareInterface``. -O middleware pode retornar uma resposta chamando ``$handler->handle()`` +O middleware pode retornar uma resposta chamando ``$handler->handle()`` ou criando sua própria resposta. Podemos ver as duas opções em nosso middleware simples:: // Em src/Middleware/TrackingCookieMiddleware.php @@ -169,9 +170,9 @@ ou criando sua própria resposta. Podemos ver as duas opções em nosso middlewa public function process( ServerRequestInterface $request, RequestHandlerInterface $handler - ): ResponseInterface + ): ResponseInterface { - // Chamar $handler->handle() delega o controle para + // Chamar $handler->handle() delega o controle para // o *próximo* middleware na fila do seu aplicativo. $response = $handler->handle($request); @@ -188,7 +189,7 @@ ou criando sua própria resposta. Podemos ver as duas opções em nosso middlewa } } -Agora que criamos um middleware muito simples, vamos anexá-lo ao nosso +Agora que criamos um middleware muito simples, vamos anexá-lo ao nosso aplicativo:: // Em src/Application.php @@ -216,10 +217,10 @@ aplicativo:: Roteamento de Middleware ======================== -O middleware de roteamento é responsável por aplicar as rotas no seu aplicativo e -resolver o: plug-in, o controlador e a ação que uma solicitação está pedindo. -Ele pode armazenar em cache a coleção de rotas usada no seu aplicativo para aumentar o -tempo de inicialização. Para habilitar o cache de rotas em, forneça o +O middleware de roteamento é responsável por aplicar as rotas no seu aplicativo e +resolver o: plug-in, o controlador e a ação que uma solicitação está pedindo. +Ele pode armazenar em cache a coleção de rotas usada no seu aplicativo para aumentar o +tempo de inicialização. Para habilitar o cache de rotas em, forneça o :ref:`cache configuration ` desejado como um parâmetro:: // Em Application.php @@ -229,7 +230,7 @@ tempo de inicialização. Para habilitar o cache de rotas em, forneça o $middlwareQueue->add(new RoutingMiddleware($this, 'routing')); } -O exemplo acima usaria o mecanismo de cache ``routing`` para armazenar a coleção +O exemplo acima usaria o mecanismo de cache ``routing`` para armazenar a coleção de rotas gerada. .. _security-header-middleware: @@ -237,8 +238,8 @@ de rotas gerada. Middleware de Cabeçalho de Segurança ==================================== -A camada ``Security Headers Middleware`` facilita a aplicação de cabeçalhos -relacionados à segurança em seu aplicativo. Depois de configurado, o middleware +A camada ``Security Headers Middleware`` facilita a aplicação de cabeçalhos +relacionados à segurança em seu aplicativo. Depois de configurado, o middleware pode aplicar os seguintes cabeçalhos às respostas: * ``X-Content-Type-Options`` @@ -247,7 +248,7 @@ pode aplicar os seguintes cabeçalhos às respostas: * ``X-Permitted-Cross-Domain-Policies`` * ``Referrer-Policy`` -Esse middleware é configurado usando uma interface simples antes de ser aplicado à +Esse middleware é configurado usando uma interface simples antes de ser aplicado à pilha de middleware do seu aplicativo:: use Cake\Http\Middleware\SecurityHeadersMiddleware; @@ -266,14 +267,14 @@ pilha de middleware do seu aplicativo:: Middleware do Cabeçalho da Política de Segurança de Conteúdo ============================================================ -O ``CspMiddleware`` facilita a adição de cabeçalhos referente a política de segurança de +O ``CspMiddleware`` facilita a adição de cabeçalhos referente a política de segurança de conteúdo em seu aplicativo. Antes de usá-lo, você deve instalar o ``paragonie/csp-builder``: .. code-block::bash composer require paragonie/csp-builder -Você pode configurar o middleware usando uma matriz ou passando um +Você pode configurar o middleware usando uma matriz ou passando um objeto ``CSPBuilder`` integrado:: use Cake\Http\Middleware\CspMiddleware; @@ -296,10 +297,10 @@ objeto ``CSPBuilder`` integrado:: Middleware de Cookie Criptografado ================================== -Se o seu aplicativo possui cookies que contêm dados que você deseja ofuscar e -proteger contra adulterações do usuário, você pode usar o middleware de cookies -criptografado do CakePHP para criptografar e descriptografar de forma transparente -os dados de cookies via middleware. Os dados dos cookies são criptografados via +Se o seu aplicativo possui cookies que contêm dados que você deseja ofuscar e +proteger contra adulterações do usuário, você pode usar o middleware de cookies +criptografado do CakePHP para criptografar e descriptografar de forma transparente +os dados de cookies via middleware. Os dados dos cookies são criptografados via OpenSSL usando AES:: use Cake\Http\Middleware\EncryptedCookieMiddleware; @@ -313,10 +314,10 @@ OpenSSL usando AES:: $middlwareQueue->add($cookies); .. note:: - É recomendável que a chave de criptografia usada para os dados do + É recomendável que a chave de criptografia usada para os dados do cookie seja usada *exclusivamente* para os dados do cookie. -Os algoritmos de criptografia e o estilo de preenchimento usados pelo middleware +Os algoritmos de criptografia e o estilo de preenchimento usados pelo middleware do cookie são compatíveis com o ``CookieComponent`` de versões anteriores do CakePHP. .. _csrf-middleware: @@ -328,11 +329,11 @@ A proteção CSRF pode ser aplicada a todo o aplicativo ou a escopos de roteamen .. note:: - Você não pode usar as duas abordagens a seguir juntas; deve escolher apenas uma. - Se você usar as duas abordagens juntas, ocorrerá um erro de incompatibilidade de + Você não pode usar as duas abordagens a seguir juntas; deve escolher apenas uma. + Se você usar as duas abordagens juntas, ocorrerá um erro de incompatibilidade de token CSRF em cada solicitação `PUT` e` POST` -Ao aplicar o ``CsrfProtectionMiddleware`` à pilha de middleware do Aplicativo, +Ao aplicar o ``CsrfProtectionMiddleware`` à pilha de middleware do Aplicativo, você protege todas as ações no aplicativo:: // Em src/Application.php @@ -345,10 +346,11 @@ você protege todas as ações no aplicativo:: $csrf = new CsrfProtectionMiddleware($options); $middlwareQueue->add($csrf); + return $middlwareQueue; } -Ao aplicar o ``CsrfProtectionMiddleware`` aos escopos de roteamento, você pode +Ao aplicar o ``CsrfProtectionMiddleware`` aos escopos de roteamento, você pode incluir ou excluir grupos de rotas específicos:: // Em src/Application.php @@ -386,27 +388,27 @@ Quando ativado, você pode acessar o token CSRF atual no objeto de solicitação .. note:: - Você deve aplicar o middleware de proteção CSRF apenas para URLs que manipulam solicitações - com estado usando cookies/sessão. Solicitações sem estado, por ex. ao desenvolver uma API, + Você deve aplicar o middleware de proteção CSRF apenas para URLs que manipulam solicitações + com estado usando cookies/sessão. Solicitações sem estado, por ex. ao desenvolver uma API, não são afetados pelo CSRF; portanto, o middleware não precisa ser aplicado a essas URLs. Integração com FormHelper ------------------------- -O ``CsrfProtectionMiddleware`` se integra perfeitamente ao ``FormHelper``. Cada vez +O ``CsrfProtectionMiddleware`` se integra perfeitamente ao ``FormHelper``. Cada vez que você cria um formulário com ``FormHelper``, ele insere um campo oculto que contém o token CSRF. .. note:: - Ao usar a proteção CSRF, você sempre deve iniciar seus formulários com o ``FormHelper``. + Ao usar a proteção CSRF, você sempre deve iniciar seus formulários com o ``FormHelper``. Caso contrário, será necessário criar manualmente entradas ocultas em cada um dos seus formulários. Solicitações de Proteção CSRF e AJAX ------------------------------------ -Além de solicitar parâmetros de dados, os tokens CSRF podem ser enviados por meio -de um cabeçalho especial ``X-CSRF-Token``. O uso de um cabeçalho geralmente facilita -a integração de um token CSRF com aplicativos pesados de JavaScript ou endpoints de API +Além de solicitar parâmetros de dados, os tokens CSRF podem ser enviados por meio +de um cabeçalho especial ``X-CSRF-Token``. O uso de um cabeçalho geralmente facilita +a integração de um token CSRF com aplicativos pesados de JavaScript ou endpoints de API baseados em XML/JSON. O token CSRF pode ser obtido através do cookie ``csrfToken``. @@ -417,11 +419,11 @@ O token CSRF pode ser obtido através do cookie ``csrfToken``. Body Parser Middleware ====================== -Se seu aplicativo aceitar JSON, XML ou outros corpos de solicitação codificados, -o ``BodyParserMiddleware`` permitirá que você decodifique essas solicitações em -uma matriz que esteja disponível em ``$request->getParsedData()`` e -``$request->getData()``. Por padrão, apenas os corpos ``json`` serão analisados, -mas a análise XML pode ser ativada com uma opção. Você também pode definir seus +Se seu aplicativo aceitar JSON, XML ou outros corpos de solicitação codificados, +o ``BodyParserMiddleware`` permitirá que você decodifique essas solicitações em +uma matriz que esteja disponível em ``$request->getParsedData()`` e +``$request->getData()``. Por padrão, apenas os corpos ``json`` serão analisados, +mas a análise XML pode ser ativada com uma opção. Você também pode definir seus próprios analisadores:: use Cake\Http\Middleware\BodyParserMiddleware; @@ -435,7 +437,7 @@ próprios analisadores:: // Desativar a análise JSON $bodies = new BodyParserMiddleware(['json' => false]); - // Adicione seu próprio analisador que corresponda aos + // Adicione seu próprio analisador que corresponda aos // valores do cabeçalho do tipo de conteúdo à chamada que pode analisá-los. $bodies = new BodyParserMiddleware(); $bodies->addParser(['text/csv'], function ($body, $request) { diff --git a/pt/core-libraries/events.rst b/pt/core-libraries/events.rst index 1eb6e6901f..389ce25a61 100644 --- a/pt/core-libraries/events.rst +++ b/pt/core-libraries/events.rst @@ -65,8 +65,10 @@ o Model Orders limpo você poderia usar eventos:: 'order' => $order ]); $this->eventManager()->dispatch($event); + return true; } + return false; } } @@ -453,6 +455,7 @@ diretamente ou retornando o valor no próprio callback:: { // ... $alteredData = $event->getData('order') + $moreData; + return $alteredData; } // Outro callback diff --git a/pt/development/configuration.rst b/pt/development/configuration.rst index 45de3cd029..9f2df9b85b 100644 --- a/pt/development/configuration.rst +++ b/pt/development/configuration.rst @@ -431,6 +431,7 @@ aplicação:: public function read($key) { $xml = Xml::build($this->_path . $key . '.xml'); + return Xml::toArray($xml); } diff --git a/pt/development/routing.rst b/pt/development/routing.rst index 6cc1751c22..9edfecaa5c 100644 --- a/pt/development/routing.rst +++ b/pt/development/routing.rst @@ -1286,6 +1286,7 @@ Os filtros de URL permitem implementar recursos como parâmetros persistentes:: if ($request->getParam('lang') && !isset($params['lang'])) { $params['lang'] = $request->getParam('lang'); } + return $params; }); @@ -1303,6 +1304,7 @@ Outro caso de uso está mudando uma determinada rota no tempo de execução (rot $params['language'] = $params[0]; unset($params[0]); } + return $params; }); diff --git a/pt/development/sessions.rst b/pt/development/sessions.rst index a37405bfd4..9f2c515e71 100644 --- a/pt/development/sessions.rst +++ b/pt/development/sessions.rst @@ -251,6 +251,7 @@ A classe deve se parecer com:: if ($result) { return $result; } + return parent::read($id); } @@ -258,6 +259,7 @@ A classe deve se parecer com:: public function write($id, $data) { Cache::write($id, $data, $this->cacheKey); + return parent::write($id, $data); } @@ -265,6 +267,7 @@ A classe deve se parecer com:: public function destroy($id) { Cache::delete($id, $this->cacheKey); + return parent::destroy($id); } @@ -409,4 +412,4 @@ e :doc:`/views/helpers/flash`. .. meta:: :title lang=pt: Sessões - :keywords lang=pt: sessões padrão, classes de sessão, recursos utilitários, encerramento de sessão, ids de sessão, persistência de dados, chave de sessão, cookie de sessão, dados de sessão, última sessão, core do banco de dados, nível de segurança, useragent, razões de segurança, id de sessão, attr, countdown, regeneração, sessions, config \ No newline at end of file + :keywords lang=pt: sessões padrão, classes de sessão, recursos utilitários, encerramento de sessão, ids de sessão, persistência de dados, chave de sessão, cookie de sessão, dados de sessão, última sessão, core do banco de dados, nível de segurança, useragent, razões de segurança, id de sessão, attr, countdown, regeneração, sessions, config diff --git a/pt/development/testing.rst b/pt/development/testing.rst index 9804eb9a9d..475964031d 100644 --- a/pt/development/testing.rst +++ b/pt/development/testing.rst @@ -137,6 +137,7 @@ que vamos testar estará formatando a barra de progresso HTML. Nosso ajudante se public function bar($value) { $width = round($value / 100, 2) * 100; + return sprintf( '
    @@ -684,6 +685,7 @@ Digamos que já temos nossa classe de tabela de artigos definida em $query->where([ $this->alias() . '.published' => 1 ]); + return $query; } } @@ -1707,8 +1709,10 @@ Expandindo no exemplo Orders, digamos que temos as seguintes tabelas:: 'order' => $order ]); $this->eventManager()->dispatch($event); + return true; } + return false; } } diff --git a/pt/orm/behaviors.rst b/pt/orm/behaviors.rst index d88db14b6e..9641237a7e 100644 --- a/pt/orm/behaviors.rst +++ b/pt/orm/behaviors.rst @@ -192,6 +192,7 @@ evento em seu callback:: { if (...) { $event->stopPropagation(); + return; } $this->slug($entity); diff --git a/pt/orm/database-basics.rst b/pt/orm/database-basics.rst index 7d5ba2b005..fc338e054b 100644 --- a/pt/orm/database-basics.rst +++ b/pt/orm/database-basics.rst @@ -443,6 +443,7 @@ poderíamos fazer a seguinte classe de tipo:: if ($value === null) { return null; } + return json_decode($value, true); } @@ -451,6 +452,7 @@ poderíamos fazer a seguinte classe de tipo:: if (is_array($value) || $value === null) { return $value; } + return json_decode($value, true); } @@ -464,6 +466,7 @@ poderíamos fazer a seguinte classe de tipo:: if ($value === null) { return PDO::PARAM_NULL; } + return PDO::PARAM_STR; } @@ -575,6 +578,7 @@ mapear dados nesse objeto de valor e em expressões SQL:: if (is_array($value)) { return new Point($value[0], $value[1]); } + return null; } diff --git a/pt/orm/query-builder.rst b/pt/orm/query-builder.rst index 96c9002793..5071d026d1 100644 --- a/pt/orm/query-builder.rst +++ b/pt/orm/query-builder.rst @@ -176,6 +176,7 @@ você também pode fazer em um objeto Query:: ->order(['title' => 'DESC']) ->map(function ($row) { // map() é um método de coleção, ele executa a consulta $row->trimmedTitle = trim($row->title); + return $row; }) ->combine('id', 'trimmedTitle') // combine() é outro método de coleção @@ -573,6 +574,7 @@ um formatador de resultados:: $query->formatResults(function (\Cake\Collection\CollectionInterface $results) { return $results->map(function ($row) { $row['age'] = $row['birth_date']->diff(new \DateTime)->y; + return $row; }); }); @@ -594,6 +596,7 @@ funcionaria conforme o esperado:: return $q->formatResults(function (\Cake\Collection\CollectionInterface $authors) { return $authors->map(function ($author) { $author['age'] = $author['birth_date']->diff(new \DateTime)->y; + return $author; }); }); @@ -705,6 +708,7 @@ No entanto, se quisermos usar as condições ``AND`` e ``OR``, poderíamos fazer ->where(function (QueryExpression $exp) { $orConditions = $exp->or_(['author_id' => 2]) ->eq('author_id', 5); + return $exp ->add($orConditions) ->eq('published', true) @@ -731,6 +735,7 @@ Muitas vezes, é mais fácil ler do que encadear métodos:: return $or->eq('author_id', 2) ->eq('author_id', 5); }); + return $exp ->not($orConditions) ->lte('view_count', 10); @@ -742,6 +747,7 @@ Você pode negar sub-expressões usando ``not()``:: ->where(function (QueryExpression $exp) { $orConditions = $exp->or_(['author_id' => 2]) ->eq('author_id', 5); + return $exp ->not($orConditions) ->lte('view_count', 10); @@ -764,6 +770,7 @@ Também é possível construir expressões usando as funções SQL:: $year = $q->func()->year([ 'created' => 'identifier' ]); + return $exp ->gte($year, 2014) ->eq('published', true); diff --git a/pt/orm/retrieving-data-and-resultsets.rst b/pt/orm/retrieving-data-and-resultsets.rst index da92145a55..90b39253d7 100644 --- a/pt/orm/retrieving-data-and-resultsets.rst +++ b/pt/orm/retrieving-data-and-resultsets.rst @@ -347,6 +347,7 @@ Neste exemplo mostramos como encontrarmos um artigo quando este estiver publicad public function findOwnedBy(Query $query, array $options) { $user = $options['user']; + return $query->where(['author_id' => $user->id]); } @@ -924,6 +925,7 @@ articles by running:: if (!in_array($value, $output)) { $output[] = $value; } + return $output; }; @@ -1188,6 +1190,7 @@ This is particularly useful for building custom finder methods as described in t // Same as in the common words example in the previous section $mapper = ...; $reducer = ...; + return $query->mapReduce($mapper, $reducer); } diff --git a/pt/tutorials-and-examples/blog-auth-example/auth.rst b/pt/tutorials-and-examples/blog-auth-example/auth.rst index bf5c47d832..9f3cb94f4a 100644 --- a/pt/tutorials-and-examples/blog-auth-example/auth.rst +++ b/pt/tutorials-and-examples/blog-auth-example/auth.rst @@ -92,6 +92,7 @@ geração de código ``bake`` fornecido com CakePHP:: $user = $this->Users->patchEntity($user, $this->request->getData()); if ($this->Users->save($user)) { $this->Flash->success(__('O usuário foi salvo.')); + return $this->redirect(['action' => 'add']); } $this->Flash->error(__('Não é possível adicionar o usuário.')); @@ -202,6 +203,7 @@ execute as ações de ``login`` e ``logout``:: $user = $this->Auth->identify(); if ($user) { $this->Auth->setUser($user); + return $this->redirect($this->Auth->redirectUrl()); } $this->Flash->error(__('Usuário ou senha ínvalido, tente novamente')); @@ -315,6 +317,7 @@ criado:: //$article = $this->Articles->patchEntity($article, $newData); if ($this->Articles->save($article)) { $this->Flash->success(__('Seu artigo foi salvo.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Não foi possível adicionar seu artigo.')); diff --git a/pt/tutorials-and-examples/blog/part-three.rst b/pt/tutorials-and-examples/blog/part-three.rst index c81b1e7b56..f7276e1a5b 100644 --- a/pt/tutorials-and-examples/blog/part-three.rst +++ b/pt/tutorials-and-examples/blog/part-three.rst @@ -267,6 +267,7 @@ moveUp() e moveDown() para ser capaz de reordenar as categorias na árvore: } else { $this->Flash->error('The category could not be moved up. Please, try again.'); } + return $this->redirect($this->referer(['action' => 'index'])); } @@ -279,6 +280,7 @@ moveUp() e moveDown() para ser capaz de reordenar as categorias na árvore: } else { $this->Flash->error('The category could not be moved down. Please, try again.'); } + return $this->redirect($this->referer(['action' => 'index'])); } } @@ -356,6 +358,7 @@ ele: $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Your article has been saved.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Unable to add your article.')); diff --git a/pt/tutorials-and-examples/blog/part-two.rst b/pt/tutorials-and-examples/blog/part-two.rst index e9b69007c8..5f30bc5d4a 100644 --- a/pt/tutorials-and-examples/blog/part-two.rst +++ b/pt/tutorials-and-examples/blog/part-two.rst @@ -280,6 +280,7 @@ Primeiro, comece criando a action ``add()`` no ``ArticlesController``:: $article = $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Seu artigo foi salvo.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Não é possível adicionar o seu artigo.')); @@ -439,6 +440,7 @@ a action ``edit()`` que deverá ser inserida no ``ArticlesController``:: $this->Articles->patchEntity($article, $this->request->getData()); if ($this->Articles->save($article)) { $this->Flash->success(__('Seu artigo foi atualizado.')); + return $this->redirect(['action' => 'index']); } $this->Flash->error(__('Seu artigo não pôde ser atualizado.')); @@ -527,6 +529,7 @@ A seguir, vamos criar uma forma de deletar artigos. Comece com uma action $article = $this->Articles->get($id); if ($this->Articles->delete($article)) { $this->Flash->success(__('O artigo com id: {0} foi deletado.', h($id))); + return $this->redirect(['action' => 'index']); } } diff --git a/pt/tutorials-and-examples/bookmarks/intro.rst b/pt/tutorials-and-examples/bookmarks/intro.rst index 3955fa3070..86fa41d627 100644 --- a/pt/tutorials-and-examples/bookmarks/intro.rst +++ b/pt/tutorials-and-examples/bookmarks/intro.rst @@ -233,6 +233,7 @@ para a senha. Em **src/Model/Entity/User.php** adicione o seguinte:: protected function _setPassword($value) { $hasher = new DefaultPasswordHasher(); + return $hasher->hash($value); } } diff --git a/pt/tutorials-and-examples/bookmarks/part-two.rst b/pt/tutorials-and-examples/bookmarks/part-two.rst index 2bcb1c0af2..1db885160b 100644 --- a/pt/tutorials-and-examples/bookmarks/part-two.rst +++ b/pt/tutorials-and-examples/bookmarks/part-two.rst @@ -66,6 +66,7 @@ Então, vamos criar a ação de login:: $user = $this->Auth->identify(); if ($user) { $this->Auth->setUser($user); + return $this->redirect($this->Auth->redirectUrl()); } $this->Flash->error('Your username or password is incorrect.'); @@ -103,6 +104,7 @@ fornecer uma maneira de encerrar a sessão também. Mais uma vez, no public function logout() { $this->Flash->success('You are now logged out.'); + return $this->redirect($this->Auth->logout()); } @@ -200,6 +202,7 @@ para os bookmarks. Em seu ``BookmarksController`` adicione o seguinte:: if ($bookmark->user_id == $user['id']) { return true; } + return parent::isAuthorized($user); } @@ -236,6 +239,7 @@ Com isso removido, nós também vamos atualizar o método add:: $bookmark->user_id = $this->Auth->user('id'); if ($this->Bookmarks->save($bookmark)) { $this->Flash->success('The bookmark has been saved.'); + return $this->redirect(['action' => 'index']); } $this->Flash->error('The bookmark could not be saved. Please, try again.'); @@ -245,7 +249,7 @@ Com isso removido, nós também vamos atualizar o método add:: } Ao definir a propriedade da entidade com os dados da sessão, nós removemos -qualquer possibilidade do user modificar algo que não pertenca a ele. +qualquer possibilidade do user modificar algo que não pertenca a ele. Nós vamos fazer o mesmo para o formulário edit e action edit. Sua ação edit deve ficar assim:: @@ -259,6 +263,7 @@ ação edit deve ficar assim:: $bookmark->user_id = $this->Auth->user('id'); if ($this->Bookmarks->save($bookmark)) { $this->Flash->success('The bookmark has been saved.'); + return $this->redirect(['action' => 'index']); } $this->Flash->error('The bookmark could not be saved. Please, try again.'); @@ -317,6 +322,7 @@ entidade. Em **src/Model/Entity/Bookmark.php** adicione o seguinte:: $str = $tags->reduce(function ($string, $tag) { return $string . $tag->title . ', '; }, ''); + return trim($str, ', '); } @@ -384,6 +390,7 @@ entidades relacionadas. Adicione o seguinte em foreach ($new as $tag) { $out[] = $this->Tags->newEntity(['title' => $tag]); } + return $out; } From b656640450d6983703226ffe9f01871133f5950e Mon Sep 17 00:00:00 2001 From: Arhell Date: Wed, 15 May 2024 00:35:40 +0300 Subject: [PATCH 207/337] Update query-builder.rst (fr, ja, pl) --- fr/orm/query-builder.rst | 1 + ja/orm/query-builder.rst | 1 + pt/orm/query-builder.rst | 1 + 3 files changed, 3 insertions(+) diff --git a/fr/orm/query-builder.rst b/fr/orm/query-builder.rst index ab655a9941..c0e008f675 100644 --- a/fr/orm/query-builder.rst +++ b/fr/orm/query-builder.rst @@ -100,6 +100,7 @@ La façon la plus simple est d'appeler les méthodes ``all()`` ou ``toArray()``: $resultsArray = $articles ->find() ->where(['id >' => 1]) + ->all() ->toList(); foreach ($resultsArray as $article) { diff --git a/ja/orm/query-builder.rst b/ja/orm/query-builder.rst index d8f5e5aecb..654051b4ce 100644 --- a/ja/orm/query-builder.rst +++ b/ja/orm/query-builder.rst @@ -94,6 +94,7 @@ SQL が出力されます。 :: $resultsArray = $articles ->find() ->where(['id >' => 1]) + ->all() ->toList(); foreach ($resultsArray as $article) { diff --git a/pt/orm/query-builder.rst b/pt/orm/query-builder.rst index c372c35b2b..c13da9cc8d 100644 --- a/pt/orm/query-builder.rst +++ b/pt/orm/query-builder.rst @@ -103,6 +103,7 @@ A maneira mais fácil é chamar os métodos ``all()`` ou ``toList()``:: $resultsArray = $articles ->find() ->where(['id >' => 1]) + ->all() ->toList(); foreach ($resultsArray as $article) { From f5de5be7375e1067b917d7491323be5bd5a797ca Mon Sep 17 00:00:00 2001 From: nigro64 Date: Sat, 18 May 2024 10:24:59 +0200 Subject: [PATCH 208/337] Update dependency-injection.rst replace wrong method name --- fr/development/dependency-injection.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/development/dependency-injection.rst b/fr/development/dependency-injection.rst index 0ad91610b5..00487ff5e9 100644 --- a/fr/development/dependency-injection.rst +++ b/fr/development/dependency-injection.rst @@ -157,7 +157,7 @@ comme 'partagé':: // dans votre méthode Application::services() - $container->share(BillingService::class); + $container->addShared(BillingService::class); Étendre des Définitions ----------------------- @@ -197,7 +197,7 @@ injectable:: use Cake\Core\ServiceConfig; // Utilisez une instance partagée - $container->share(ServiceConfig::class); + $container->addShared(ServiceConfig::class); La classe ``ServiceConfig`` fournit une vue en lecture seule de toutes les données disponibles dans ``Configure``, ainsi vous n'avez pas à vous soucier From d23c34fa23b621b2a76aeecff163d7911ffc8f9d Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 20 May 2024 11:48:23 -0400 Subject: [PATCH 209/337] Add docs for the banner helper Refs cakephp/cakephp#17686 --- en/appendices/5-1-migration-guide.rst | 4 ++++ en/console-commands/input-output.rst | 20 ++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 6429bd2209..e39823474f 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -52,6 +52,10 @@ 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 ------- diff --git a/en/console-commands/input-output.rst b/en/console-commands/input-output.rst index dd53af0a21..3d03c3cd03 100644 --- a/en/console-commands/input-output.rst +++ b/en/console-commands/input-output.rst @@ -148,6 +148,19 @@ progress bar as necessary:: $progress->increment(4); $progress->draw(); +Banner Helper +------------- + +The ``BannerHelper`` can be used to format one or more lines of text into +a banner with a background and horizontal padding:: + + $io->helper('Banner') + ->withPadding(5) + ->withStyle('success.bg') + ->output(['Work complete']); + +.. versionadded:: 5.1.0 + The ``BannerHelper`` was added in 5.1 Getting User Input ================== @@ -300,6 +313,10 @@ are several built-in styles, and you can create more. The built-in ones are * ``info`` Informational messages. Cyan text. * ``comment`` Additional text. Blue text. * ``question`` Text that is a question, added automatically by shell. +* ``info.bg`` White background with cyan text. +* ``warning.bg`` Yellow background with black text. +* ``error.bg`` Red background with black text. +* ``success.bg`` Green background with black text. You can create additional styles using ``$io->setStyle()``. To declare a new output style you could do:: @@ -332,6 +349,9 @@ truthy value enables them. Adding a style makes it available on all instances of ConsoleOutput as well, so you don't have to redeclare styles for both stdout and stderr objects. +.. versionchanged:: 5.1.0 + The ``info.bg``, ``warning.bg``, ``error.bg``, and ``success.bg`` were added. + Turning Off Coloring ==================== From cd73d6de5f09e5e6abcd7d3b984b865e4e4a9b6f Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 20 May 2024 22:49:22 -0400 Subject: [PATCH 210/337] Update deploy workflow for 5.next --- .github/workflows/{deploy_5x.yml => deploy_5next.yml} | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) rename .github/workflows/{deploy_5x.yml => deploy_5next.yml} (82%) diff --git a/.github/workflows/deploy_5x.yml b/.github/workflows/deploy_5next.yml similarity index 82% rename from .github/workflows/deploy_5x.yml rename to .github/workflows/deploy_5next.yml index 31a5400ab4..7e211505ca 100644 --- a/.github/workflows/deploy_5x.yml +++ b/.github/workflows/deploy_5next.yml @@ -1,15 +1,15 @@ --- -name: 'deploy_5.x' +name: 'deploy_5.next' on: push: branches: - - 5.x + - 5.next workflow_dispatch: concurrency: group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: ${{ github.ref != 'refs/heads/5.x' }} + cancel-in-progress: ${{ github.ref != 'refs/heads/5.next' }} jobs: deploy: @@ -23,6 +23,6 @@ jobs: - name: Push to dokku uses: dokku/github-action@master with: - git_remote_url: 'ssh://dokku@apps.cakephp.org:22/book-5' + git_remote_url: 'ssh://dokku@apps.cakephp.org:22/book-5next' git_push_flags: '-f' ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }} From 5f5c2848bb8ccb4daccfc96863dd68426fcda926 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 20 May 2024 23:28:09 -0400 Subject: [PATCH 211/337] Bump template version --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 5793b68834..f6d654ebf0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ docutils==0.20.1 sphinx==7.0.1 sphinxcontrib-phpdomain==0.11.1 -cakephpsphinx>=0.1.57,<1.0 +cakephpsphinx>=0.1.58,<1.0 From 63b24612c9378ec2df3676af6bfa0dd98dc51cbf Mon Sep 17 00:00:00 2001 From: Arhell Date: Wed, 22 May 2024 01:30:41 +0300 Subject: [PATCH 212/337] Update dependency-injection.rst (ja) --- ja/development/dependency-injection.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/development/dependency-injection.rst b/ja/development/dependency-injection.rst index 248c6f3319..435c5b78ce 100644 --- a/ja/development/dependency-injection.rst +++ b/ja/development/dependency-injection.rst @@ -125,7 +125,7 @@ CakePHPはコントローラーでアクションを呼ぶ際サービスコン // あなたのApplication::services()メソッド内で - $container->share(BillingService::class); + $container->addShared(BillingService::class); 定義の拡張 --------------------- @@ -163,7 +163,7 @@ CakePHPはコントローラーでアクションを呼ぶ際サービスコン use Cake\Core\ServiceConfig; // シェアされたインスタンスを使用する - $container->share(ServiceConfig::class); + $container->addShared(ServiceConfig::class); ``ServiceConfig`` クラスは ``Configure`` で利用可能な全データのread-onlyな一覧を提供します。 なので、誤って設定が変わる心配はありません。 From 640f8596527ede6072f91a0de3cc28b5dec5a56d Mon Sep 17 00:00:00 2001 From: MarwanSalim <45453458+MarwanSalim@users.noreply.github.com> Date: Sat, 25 May 2024 12:26:42 +0800 Subject: [PATCH 213/337] Update entities.rst As mentioned previously: >The has() method will return true if a field is defined. --- en/orm/entities.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/entities.rst b/en/orm/entities.rst index d13241d39e..8eadeea6e0 100644 --- a/en/orm/entities.rst +++ b/en/orm/entities.rst @@ -138,7 +138,7 @@ value:: $article->isEmpty('title'); // false $article->hasValue('title'); // true - $article->has('user_id'); // false + $article->has('user_id'); // true $article->isEmpty('user_id'); // true $article->hasValue('user_id'); // false From 5372c5489cd622e51798a595c8e5e5ff7b4e79a8 Mon Sep 17 00:00:00 2001 From: MarwanSalim <45453458+MarwanSalim@users.noreply.github.com> Date: Tue, 28 May 2024 14:42:34 +0800 Subject: [PATCH 214/337] Update query-builder.rst As mentioned in the migration guide: https://book.cakephp.org/5/en/appendices/5-0-migration-guide.html#database >Query::orderBy() was added to replace Query::order(). >Query::groupBy() was added to replace Query::group(). --- en/orm/query-builder.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index b2cefeb069..372908f917 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -58,7 +58,7 @@ that ``SelectQuery`` objects are lazy, and will not be executed unless you tell to:: $query->where(['id' => 1]); // Return the same query object - $query->order(['title' => 'DESC']); // Still same object, no SQL executed + $query->orderBy(['title' => 'DESC']); // Still same object, no SQL executed You can of course chain the methods you call on SelectQuery objects:: @@ -66,7 +66,7 @@ You can of course chain the methods you call on SelectQuery objects:: ->find() ->select(['id', 'name']) ->where(['id !=' => 1]) - ->order(['created' => 'DESC']); + ->orderBy(['created' => 'DESC']); foreach ($query->all() as $article) { debug($article->created); @@ -165,7 +165,7 @@ by calling the ``SelectQuery``'s ``all()`` method) implements the collection int // An advanced example $results = $articles->find() ->where(['id >' => 1]) - ->order(['title' => 'DESC']) + ->orderBy(['title' => 'DESC']) ->all() ->map(function ($row) { $row->trimmedTitle = trim($row->title); @@ -432,20 +432,20 @@ Ordering Results To apply ordering, you can use the ``order`` method:: $query = $articles->find() - ->order(['title' => 'ASC', 'id' => 'ASC']); + ->orderBy(['title' => 'ASC', 'id' => 'ASC']); -When calling ``order()`` multiple times on a query, multiple clauses will be +When calling ``orderBy()`` multiple times on a query, multiple clauses will be appended. However, when using finders you may sometimes need to overwrite the -``ORDER BY``. Set the second parameter of ``order()`` (as well as -``orderAsc()`` or ``orderDesc()``) to ``SelectQuery::OVERWRITE`` or to ``true``:: +``ORDER BY``. Set the second parameter of ``orderBy()`` (as well as +``orderByAsc()`` or ``orderByDesc()``) to ``SelectQuery::OVERWRITE`` or to ``true``:: $query = $articles->find() - ->order(['title' => 'ASC']); + ->orderBy(['title' => 'ASC']); // Later, overwrite the ORDER BY clause instead of appending to it. $query = $articles->find() - ->order(['created' => 'DESC'], SelectQuery::OVERWRITE); + ->orderBy(['created' => 'DESC'], SelectQuery::OVERWRITE); -The ``orderAsc`` and ``orderDesc`` methods can be used when you need to sort on +The ``orderByAsc`` and ``orderByDesc`` methods can be used when you need to sort on complex expressions:: $query = $articles->find(); @@ -453,11 +453,11 @@ complex expressions:: 'title' => 'identifier', 'synopsis' => 'identifier' ]); - $query->orderAsc($concat); + $query->orderByAsc($concat); To build complex order clauses, use a Closure to build order expressions:: - $query->orderAsc(function (QueryExpression $exp, SelectQuery $query) { + $query->orderByAsc(function (QueryExpression $exp, SelectQuery $query) { return $exp->addCase(/* ... */); }); @@ -1069,7 +1069,7 @@ You can use ``identifier()`` in comparisons to aggregations too:: $query = $this->Orders->find(); $query->select(['Customers.customer_name', 'total_orders' => $query->func()->count('Orders.order_id')]) ->contain('Customers') - ->group(['Customers.customer_name']) + ->groupBy(['Customers.customer_name']) ->having(['total_orders >=' => $query->identifier('Customers.minimum_order_count')]); .. warning:: @@ -1781,14 +1781,14 @@ through ``FunctionsBuilder::aggregate()``. These are the most commonly supported window features. Most features are provided by ``AggregateExpresion``, but make sure you follow your database documentation on use and restrictions. -- ``order($fields)`` Order the aggregate group the same as a query ORDER BY. +- ``orderBy($fields)`` Order the aggregate group the same as a query ORDER BY. - ``partition($expressions)`` Add one or more partitions to the window based on column names. - ``rows($start, $end)`` Define a offset of rows that precede and/or follow the current row that should be included in the aggregate function. - ``range($start, $end)`` Define a range of row values that precede and/or follow the current row that should be included in the aggregate function. This - evaluates values based on the ``order()`` field. + evaluates values based on the ``orderBy()`` field. If you need to re-use the same window expression multiple times you can create named windows using the ``window()`` method:: From aa5501b5899d38eb658ee63bbceb97139f887d99 Mon Sep 17 00:00:00 2001 From: Arhell Date: Wed, 29 May 2024 00:18:03 +0300 Subject: [PATCH 215/337] Update entities.rst (fr) --- fr/orm/entities.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/orm/entities.rst b/fr/orm/entities.rst index 4075493bec..6edc6b3eb4 100644 --- a/fr/orm/entities.rst +++ b/fr/orm/entities.rst @@ -150,10 +150,10 @@ vérifier si un champ contient une valeur 'non-empty':: $article->isEmpty('title'); // false $article->hasValue('title'); // true - $article->has('user_id'); // false + $article->has('user_id'); // true $article->isEmpty('user_id'); // true $article->hasValue('user_id'); // false - + $article->has('text'); // true $article->isEmpty('text'); // true $article->hasValue('text'); // false From acc7c7a052e5d210cea841979e2ade8f0f94b968 Mon Sep 17 00:00:00 2001 From: ADmad Date: Wed, 29 May 2024 13:57:19 +0530 Subject: [PATCH 216/337] Replace SecurityComponent with FormProtectionComponent --- en/views/helpers/form.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 707eff8b7b..117ccf8188 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -2018,12 +2018,12 @@ Closing the Form * ``$secureAttributes`` - Optional. Allows you to provide secure attributes which will be passed as HTML attributes into the hidden input elements - generated for the SecurityComponent. + generated for the FormProtectionComponent. The ``end()`` method closes and completes a form. Often, ``end()`` will only output a closing form tag, but using ``end()`` is a good practice as it enables FormHelper to insert the hidden form elements that -:php:class:`Cake\\Controller\\Component\\SecurityComponent` requires: +:php:class:`Cake\\Controller\\Component\\FormProtection` requires: .. code-block:: php From 049f5a83a3c6ffcfb4635c1b3b538917f942adfe Mon Sep 17 00:00:00 2001 From: ADmad Date: Wed, 29 May 2024 13:58:05 +0530 Subject: [PATCH 217/337] Update en/views/helpers/form.rst --- en/views/helpers/form.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 117ccf8188..f04d057957 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -2023,7 +2023,7 @@ Closing the Form The ``end()`` method closes and completes a form. Often, ``end()`` will only output a closing form tag, but using ``end()`` is a good practice as it enables FormHelper to insert the hidden form elements that -:php:class:`Cake\\Controller\\Component\\FormProtection` requires: +:php:class:`Cake\\Controller\\Component\\FormProtectionComponent` requires: .. code-block:: php From 55838677b8a1b02756989cb5f7de88c3a7019c82 Mon Sep 17 00:00:00 2001 From: Arhell Date: Thu, 30 May 2024 00:16:39 +0300 Subject: [PATCH 218/337] Replace SecurityComponent with FormProtectionComponent (fr, ja) --- fr/views/helpers/form.rst | 4 ++-- ja/views/helpers/form.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/fr/views/helpers/form.rst b/fr/views/helpers/form.rst index e9875f21e9..2cd319302a 100644 --- a/fr/views/helpers/form.rst +++ b/fr/views/helpers/form.rst @@ -2051,13 +2051,13 @@ Fermer le Formulaire * ``$secureAttributes`` - Optionnel. Vous permet de fournir des attributs qui seront utilisés comme attributs HTML aux inputs ``hidden`` générés par le - ``SecurityComponent``. + ``FormProtectionComponent``. La méthode ``end()`` ferme et complète le marquage du formulaire. Souvent, ``end()`` se contente d'afficher la balise fermante du formulaire, mais l'utilisation de ``end()`` est une bonne pratique puisqu'elle permet également au FormHelper d'ajouter les champs cachées dont le -:php:class:`Cake\\Controller\\Component\\SecurityComponent` a besoin: +:php:class:`Cake\\Controller\\Component\\FormProtectionComponent` a besoin: .. code-block:: php diff --git a/ja/views/helpers/form.rst b/ja/views/helpers/form.rst index 68eb4ffeb8..ede8761f4a 100644 --- a/ja/views/helpers/form.rst +++ b/ja/views/helpers/form.rst @@ -2071,12 +2071,12 @@ submit 入力は、基本的なテキストやイメージが必要な場合に .. php:method:: end($secureAttributes = []) -* ``$secureAttributes`` - オプション。SecurityComponent 用に生成された非表示の +* ``$secureAttributes`` - オプション。FormProtectionComponent 用に生成された非表示の input 要素に HTML 属性として渡されるセキュアな属性を提供できます。 ``end()`` は、フォームを閉じて完成します。 多くの場合、 ``end()`` は終了タグだけを出力しますが、 ``end()`` を使うと、 -FormHelper が :php:class:`Cake\\Controller\\Component\\SecurityComponent` に必要な +FormHelper が :php:class:`Cake\\Controller\\Component\\FormProtectionComponent` に必要な hidden フォーム要素を挿入できるようになります。 .. code-block:: php From a51aaa61153a712d38c0b15d6ae0c560629c41fb Mon Sep 17 00:00:00 2001 From: "T.Yajima" Date: Fri, 7 Jun 2024 10:09:15 +0900 Subject: [PATCH 219/337] =?UTF-8?q?fix:=20unify=20"=E9=96=A2=E6=95=B0"=20t?= =?UTF-8?q?o=20"=E3=83=A1=E3=82=BD=E3=83=83=E3=83=89"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ja/tutorials-and-examples/cms/articles-controller.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/tutorials-and-examples/cms/articles-controller.rst b/ja/tutorials-and-examples/cms/articles-controller.rst index 352cf90b83..4c96ab65fb 100644 --- a/ja/tutorials-and-examples/cms/articles-controller.rst +++ b/ja/tutorials-and-examples/cms/articles-controller.rst @@ -37,9 +37,9 @@ CMS チュートリアル - Articles コントローラーの作成 } } -``ArticlesController`` の ``index()`` 関数を定義することで、ユーザーは、 +``ArticlesController`` の ``index()`` メソッドを定義することで、ユーザーは、 **www.example.com/articles/index** をリクエストすることで、そこにあるロジックに -アクセスできるようになります。同様に、 ``foobar()`` という関数を定義した場合、 +アクセスできるようになります。同様に、 ``foobar()`` というメソッドを定義した場合、 ユーザーはそのメソッドに **www.example.com/articles/foobar** で、アクセスできます。 特定の URL を取得できるように、コントローラーとアクションの名前を付けたいという 誘惑に駆られるかもしれません。その誘惑に抗ってください。代わりに、 :doc:`/intro/conventions` From 3f93eec44c7e4d38201769f03b186bd3a2f949b4 Mon Sep 17 00:00:00 2001 From: "T.Yajima" Date: Fri, 7 Jun 2024 10:11:42 +0900 Subject: [PATCH 220/337] fix: corrected to natural Japanese --- ja/tutorials-and-examples/cms/articles-controller.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/tutorials-and-examples/cms/articles-controller.rst b/ja/tutorials-and-examples/cms/articles-controller.rst index 4c96ab65fb..1e13eb15bc 100644 --- a/ja/tutorials-and-examples/cms/articles-controller.rst +++ b/ja/tutorials-and-examples/cms/articles-controller.rst @@ -20,7 +20,7 @@ CMS チュートリアル - Articles コントローラーの作成 コントローラーのメソッドです。例えば、ユーザーが **www.example.com/articles/index** (**www.example.com/articles** と同じ) をリクエストした場合、CakePHP は、 ``ArticlesController`` の ``index`` メソッドを呼びます。このメソッドは、モデル層に問い合わせ、 -ビューでテンプレートを描画してレスポンスの準備する必要があります。そのアクションのコードは、 +ビューでテンプレートを描画してレスポンスを準備する必要があります。そのアクションのコードは、 次のようになります。 :: Date: Fri, 7 Jun 2024 23:46:28 +0900 Subject: [PATCH 221/337] modify datasources default setting referencing --- fr/tutorials-and-examples/cms/database.rst | 4 ++-- ja/tutorials-and-examples/cms/database.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/fr/tutorials-and-examples/cms/database.rst b/fr/tutorials-and-examples/cms/database.rst index 68c07c5e33..afd3e834dc 100644 --- a/fr/tutorials-and-examples/cms/database.rst +++ b/fr/tutorials-and-examples/cms/database.rst @@ -132,9 +132,9 @@ de configuration complétée ressemblera à ceci:: // D'autres configurations au dessus 'Datasources' => [ 'default' => [ - 'className' => 'Cake\Database\Connection', + 'className' => Connection::class, // Remplacez Mysql par Postgres si vous utilisez PostgreSQL - 'driver' => 'Cake\Database\Driver\Mysql', + 'driver' => Mysql::class, 'persistent' => false, 'host' => 'localhost', 'username' => 'cakephp', diff --git a/ja/tutorials-and-examples/cms/database.rst b/ja/tutorials-and-examples/cms/database.rst index 2f93f9891b..3a80dc1d1a 100644 --- a/ja/tutorials-and-examples/cms/database.rst +++ b/ja/tutorials-and-examples/cms/database.rst @@ -77,8 +77,8 @@ CMS チュートリアル - データベース作成 // 上には他の設定があります 'Datasources' => [ 'default' => [ - 'className' => 'Cake\Database\Connection', - 'driver' => 'Cake\Database\Driver\Mysql', + 'className' => Connection::class, + 'driver' => Mysql::class, 'persistent' => false, 'host' => 'localhost', 'username' => 'cakephp', From 4d3d0927426bb73be9ad571547cfe58da90ecc44 Mon Sep 17 00:00:00 2001 From: "T.Yajima" Date: Wed, 12 Jun 2024 11:15:06 +0900 Subject: [PATCH 222/337] fix: tweaked fine notation --- ja/appendices/5-0-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/appendices/5-0-migration-guide.rst b/ja/appendices/5-0-migration-guide.rst index ae2dd33907..532a3ebd3b 100644 --- a/ja/appendices/5-0-migration-guide.rst +++ b/ja/appendices/5-0-migration-guide.rst @@ -247,7 +247,7 @@ Core Database -------- -- ``ConnectionManager``は read / write の接続ロールをサポートしました。データベース接続設定において ``read`` や ``write`` のキーで指定した設定項目によって共通の設定項目を上書きすることで、接続ロールを構成することができます。 +- ``ConnectionManager`` は read / write の接続ロールをサポートしました。データベース接続設定において ``read`` や ``write`` のキーで指定した設定項目によって共通の設定項目を上書きすることで、接続ロールを構成することができます。 - 結果セットを整形するコールバックを実行できるメソッド ``Query::all()`` が追加されました。 - SQLにコメントを追加するメソッド ``Query::comment()`` が追加されました。これによりクエリのデバッグが楽になります。 - PHPの enum と、データベースの string や integer 型との間の橋渡しをする ``EnumType`` が追加されました。 From 781b778961ebdce5db84cccde0ba420fb82f0eaa Mon Sep 17 00:00:00 2001 From: Joshua Vogel Date: Fri, 14 Jun 2024 08:39:37 +0300 Subject: [PATCH 223/337] Update routing.rst Fixed a typo --- en/development/routing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/development/routing.rst b/en/development/routing.rst index eef644438d..864b9ef620 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -839,7 +839,7 @@ the ``*.`` wildcard to match any subdomain:: // This route only matches on http://*.example.com $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('*.example.com'); }); @@ -851,7 +851,7 @@ parameter when generating URLs:: // If you have this route $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('images.example.com'); From b0f61ad2c9197d09c5aee7932e460aff80b40b69 Mon Sep 17 00:00:00 2001 From: Arhell Date: Sat, 15 Jun 2024 00:31:30 +0300 Subject: [PATCH 224/337] Update routing.rst (es, fr, ja, pt) --- es/development/routing.rst | 4 ++-- fr/development/routing.rst | 4 ++-- ja/development/routing.rst | 4 ++-- pt/development/routing.rst | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/es/development/routing.rst b/es/development/routing.rst index a168745f1f..686fbd0ce2 100644 --- a/es/development/routing.rst +++ b/es/development/routing.rst @@ -851,7 +851,7 @@ subdominio:: // Esta ruta sólo coincide en http://*.example.com $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('*.example.com'); }); @@ -863,7 +863,7 @@ generada. Sin embargo, si utilizas un comodín, tendrás que indicar el parámet // Si tienes esta ruta $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('images.example.com'); diff --git a/fr/development/routing.rst b/fr/development/routing.rst index a6da47dcfe..68fc6ccdb0 100644 --- a/fr/development/routing.rst +++ b/fr/development/routing.rst @@ -887,7 +887,7 @@ n'importe quelle sous-domaine:: // Cette route matchera sur tous les sous-domaines http://*.example.com $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('*.example.com'); }); @@ -899,7 +899,7 @@ paramètre lors de la génération d'URL:: // Si vous avez cette route $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('images.example.com'); diff --git a/ja/development/routing.rst b/ja/development/routing.rst index 5782751f7e..d61a56a6a4 100644 --- a/ja/development/routing.rst +++ b/ja/development/routing.rst @@ -781,7 +781,7 @@ SEO に親和性があるルーティング // このルートは http://*.example.com のみマッチします。 $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('*.example.com'); }); @@ -792,7 +792,7 @@ SEO に親和性があるルーティング // このルートを持つ場合、 $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('images.example.com'); diff --git a/pt/development/routing.rst b/pt/development/routing.rst index 9edfecaa5c..64e2045c19 100644 --- a/pt/development/routing.rst +++ b/pt/development/routing.rst @@ -699,7 +699,7 @@ pode usar o curinga ``*.`` para corresponder a qualquer subdomínio:: // Esta rota corresponde apenas a http://*.example.com $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('*.example.com'); }); @@ -710,7 +710,7 @@ curinga, precisará fornecer o parâmetro ``_host`` ao gerar URLs:: // Se você tem esta rota $routes->connect( - '/images/old-log.png', + '/images/old-logo.png', ['controller' => 'Images', 'action' => 'oldLogo'] )->setHost('images.example.com'); From 51e9c610094c28ac1fceaac244f887b28a2dc018 Mon Sep 17 00:00:00 2001 From: Tomoya Date: Mon, 17 Jun 2024 00:23:36 +0900 Subject: [PATCH 225/337] remove loading paginator component --- ja/tutorials-and-examples/cms/articles-controller.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/ja/tutorials-and-examples/cms/articles-controller.rst b/ja/tutorials-and-examples/cms/articles-controller.rst index 1e13eb15bc..18b6a8a9ad 100644 --- a/ja/tutorials-and-examples/cms/articles-controller.rst +++ b/ja/tutorials-and-examples/cms/articles-controller.rst @@ -182,13 +182,12 @@ view テンプレートの作成 { parent::initialize(); - $this->loadComponent('Paginator'); $this->loadComponent('Flash'); // FlashComponent をインクルード } public function index() { - $articles = $this->Paginator->paginate($this->Articles->find()); + $articles = $this->paginate($this->Articles->find()); $this->set(compact('articles')); } From 5e873f224e2d95a05ad88c7e6f3f62eda960951d Mon Sep 17 00:00:00 2001 From: Tomoya Date: Mon, 17 Jun 2024 00:27:02 +0900 Subject: [PATCH 226/337] remove paginator component page --- ja/contents.rst | 1 - ja/controllers/components/pagination.rst | 324 ----------------------- 2 files changed, 325 deletions(-) delete mode 100644 ja/controllers/components/pagination.rst diff --git a/ja/contents.rst b/ja/contents.rst index 58b0d4ea4d..585fc42155 100644 --- a/ja/contents.rst +++ b/ja/contents.rst @@ -43,7 +43,6 @@ core-libraries/internationalization-and-localization core-libraries/logging core-libraries/form - controllers/components/pagination plugins development/rest security diff --git a/ja/controllers/components/pagination.rst b/ja/controllers/components/pagination.rst deleted file mode 100644 index 0790eb69ea..0000000000 --- a/ja/controllers/components/pagination.rst +++ /dev/null @@ -1,324 +0,0 @@ -ページネーション -################# - -.. php:namespace:: Cake\Controller\Component - -.. php:class:: PaginatorComponent - -フレキシブルでかつユーザーフレンドリーなウェブアプリケーションを作成する際の主たる障害の -一つとなるのが、直感的なユーザーインターフェイスです。多くのアプリケーションはすぐに巨大となり -かつ複雑になり、デザイナーやプログラマーは、何百件、何千件ものレコードが表示されることに -対応しきれなくなってきます。リファクタリングするには時間がかかり、パフォーマンスやユーザー満足度が -犠牲になることが多いです。 - -１ページあたりに表示されるレコードの数を一定数に抑えることは、すべてのアプリケーションにとって -重大な課題であり、開発者にとって頭の痛い問題でした。CakePHP は素早く、かつ簡単に、 -データをページ分けする方法を提供することで、開発者への負担を軽減します。 - -CakePHP におけるページネーションは、コントローラーにおけるコンポーネントによって提供され、 -ページ分けされたクエリーをより簡単にビルドできるようにします。ビューの中の -:php:class:`~Cake\\View\\Helper\\PaginatorHelper` は、ページネーションのリンクや -ボタンを作り出すことを容易にすることに使われます。 - -基本的な使用方法 -================ - -クエリをページ分割するには、まず ``PaginatorComponent`` をロードする必要があります。 :: - - class ArticlesController extends AppController - { - public function initialize(): void - { - parent::initialize(); - $this->loadComponent('Paginator'); - } - } - -一度ロードされれば、ORMテーブルクラスや ``Query`` オブジェクトをページ分割することができます。 :: - - public function index() - { - // ORM テーブルのページ分割 - $this->set('articles', $this->paginate($this->Articles)); - - // 部分的に完了したクエリをページ分割する - $query = $this->Articles->find('published'); - $this->set('articles', $this->paginate($query)); - } - -高度な使用方法 -============== - -``PaginatorComponent`` は、 ``$paginate`` のコントローラプロパティや ``paginate()`` の引数 -``$settings`` として設定することで、より複雑なユースケースをサポートしています。 -これらの条件はページ分割クエリの基礎となります。 -これらの条件は URLから渡される ``sort``, ``direction``, ``limit``, ``page`` -のパラメータによって拡張されます。　:: - - class ArticlesController extends AppController - { - public $paginate = [ - 'limit' => 25, - 'order' => [ - 'Articles.title' => 'asc' - ] - ]; - } - -.. tip:: - デフォルトの ``order`` オプションは配列として定義されていなければなりません。 - -:php:meth:`~Cake\\ORM\\Table::find()` でサポートされているオプションのいずれかを -ページ分割の設定に含めることができます。 -ページネーションオプションを :ref:`custom-find-methods` にバンドルする方が -すっきりしていてシンプルです。 -``finder`` オプションを使用することで、ページ分割の際にファインダーを使用することができます。 :: - - class ArticlesController extends AppController - { - public $paginate = [ - 'finder' => 'published', - ]; - } - -ファインダーメソッドに追加のオプションが必要な場合は、これらの値を finder: に渡すことができます。 :: - - class ArticlesController extends AppController - { - // タグごとに記事を検索する - public function tags() - { - $tags = $this->request->getParam('pass'); - - $customFinderOptions = [ - 'tags' => $tags - ]; - - // カスタム Finder メソッドは、ArticlesTable.php の中で "findTagged" と呼ばれる - // 以下のような構文となっている - // public function findTagged(Query $query, array $options) { - // そのため、taggedをキーとして使用する - $settings = [ - 'finder' => [ - 'tagged' => $customFinderOptions - ] - ]; - $articles = $this->paginate($this->Articles, $settings); - $this->set(compact('articles', 'tags')); - } - } - -一般的なページネーションの値を定義することに加え、コントローラーには１セット以上の -ページネーションに関するデフォルト設定を定義することができます。そのためには、 -設定を加えたいモデルの後に、配列におけるキー名称を加えるだけです。 :: - - class ArticlesController extends AppController - { - public $paginate = [ - 'Articles' => [], - 'Authors' => [], - ]; - } - -``Articles`` や ``Authors`` のキーの値は、基本的な ``$paginate`` 配列に含まれる -すべてのプロパティを含めることができます。 - -一度 ``paginate()`` を使って結果を作成した後は コントローラのリクエストは -ページングパラメータで更新されます。 -ページングのメタデータは ``$this->request->getParam('paging')`` で取得できます。 - -シンプルなページネーション -========================== - -デフォルトではページネーションは ``count()`` クエリを使って結果セットのサイズを計算し、 -ページ番号のリンクを表示できるようにしています。 -非常に大きなデータセットでは、このcountクエリは非常に高価になります。 -'Next' と 'Previous' リンクだけを表示したい場合は、カウントクエリを行わない -'simple' paginator を使うことができます。 :: - - public function initialize(): void - { - parent::initialize(); - - // Load the paginator component with the simple paginator strategy. - $this->loadComponent('Paginator', [ - 'paginator' => new \Cake\Datasource\SimplePaginator(), - ]); - } - -``SimplePaginator`` を使っている場合、ページ番号やカウンターデータ、最後のページへのリンク、 -総レコード数のコントロールを生成することはできません。 - -PaginatorComponent を直接使用する -================================= - -他のコンポーネントからデータをページ分割する必要がある場合は -``PaginatorComponent`` を直接使うと良いでしょう。 -``PaginatorComponent`` はコントローラメソッドと似たようなAPIを持っています。　:: - - $articles = $this->Paginator->paginate($articleTable->find(), $config); - - // または - $articles = $this->Paginator->paginate($articleTable, $config); - -最初のパラメータは、ページ分割したいテーブルオブジェクトの検索結果からの -クエリオブジェクトでなければなりません。 -オプションで、テーブルオブジェクトを渡してクエリを作成することもできます。 -2番目のパラメータは、ページ分割に使用する設定の配列です。 -この配列はコントローラの ``$paginate`` プロパティと同じ構造でなければなりません。 -``Query`` オブジェクトをページ分割する際には、 ``finder`` オプションは無視されます。 -これは、ページ分割したいクエリを渡していることを前提としています。 - -.. _paginating-multiple-queries: - -複数のクエリのページ分割 -======================== - -コントローラの ``$paginate`` プロパティと ``paginate()`` メソッドを呼び出す際に -``scope`` オプションを使うことで、1つのコントローラのアクションの中で複数のモデルを -ページ分割することができます。 :: - - // ページ分割するプロパティ - public $paginate = [ - 'Articles' => ['scope' => 'article'], - 'Tags' => ['scope' => 'tag'] - ]; - - // コントローラーアクションにおいて - $articles = $this->paginate($this->Articles, ['scope' => 'article']); - $tags = $this->paginate($this->Tags, ['scope' => 'tag']); - $this->set(compact('articles', 'tags')); - -``scope`` オプションを指定すると、 ``PaginatorComponent`` がスコープされた -クエリ文字列パラメータを検索するようになります。 -例えば、以下のURLはタグと記事を同時にページ分割するのに使えます。 :: - - /dashboard?article[page]=1&tag[page]=3 - -スコープされたHTML要素やページネーション用のURLを生成する方法については -:ref:`paginator-helper-multiple` のセクションを参照してください。 - -同じモデルを複数回ページ分割する -================================== - -1つのコントローラアクション内で同じモデルを複数回ページ分割するには、 -モデルのエイリアスを定義する必要があります。 -テーブルレジストリの使用方法の詳細については、 :ref:`table-registry-usage` を参照してください。 :: - - // コントローラーアクションにおいて - $this->paginate = [ - 'ArticlesTable' => [ - 'scope' => 'published_articles', - 'limit' => 10, - 'order' => [ - 'id' => 'desc', - ], - ], - 'UnpublishedArticlesTable' => [ - 'scope' => 'unpublished_articles', - 'limit' => 10, - 'order' => [ - 'id' => 'desc', - ], - ], - ]; - - $publishedArticles = $this->paginate( - $this->Articles->find('all', [ - 'scope' => 'published_articles' - ])->where(['published' => true]) - ); - - // ページ分割コンポーネントで差別化できるようにテーブルオブジェクトを追加登録します。 - $unpublishedArticlesTable = $this->fetchTable('UnpublishedArticles', [ - 'className' => 'App\Model\Table\ArticlesTable', - 'table' => 'articles', - 'entityClass' => 'App\Model\Entity\Article', - ]); - - $unpublishedArticles = $this->paginate( - $unpublishedArticlesTable->find('all', [ - 'scope' => 'unpublished_articles' - ])->where(['published' => false]) - ); - -.. _control-which-fields-used-for-ordering: - -ソート時に使用するフィールドの制御 -================================== - -デフォルトでは、テーブルが持つ非仮想カラムに対してソートを行うことができます。 -これはインデックス化されていないカラムをソートしてしまうことになり、 -ソートするのにコストがかかるため、望ましくないこともあります。 -ソートできるフィールドのホワイトリストを ``sortableFields`` オプションを使って設定することができます。 -このオプションは関連するデータやページ分割クエリの一部である計算フィールドをソートしたい場合に必要です。 :: - - public $paginate = [ - 'sortableFields' => [ - 'id', 'title', 'Users.username', 'created' - ] - ]; - -ホワイトリストにないフィールドでソートしようとするリクエストは無視されます。 - -1ページあたりの最大行数を制限する -================================= - -ページごとに取得される結果の数は ``limit`` パラメータとしてユーザに公開されます。 -一般的に、ユーザがページ分割されたセットのすべての行を取得できるようにすることは望ましくありません。 -オプションの ``maxLimit`` は、外部からこの制限値を高く設定することはできないことを保証します。 -デフォルトでは、CakePHPはフェッチできる行の最大数を100に制限しています。 -もしこのデフォルト値がアプリケーションにとって適切でない場合は、 -ページ分割オプションの一部として調整することができます。 :: - - public $paginate = [ - // 他のキーはこちら - 'maxLimit' => 10 - ]; - -リクエストのリミットパラメータがこの値よりも大きければ、 ``maxLimit`` の値まで減らされます。 - -追加の関連付けへのジョイン -=============================== - -追加の関連付けをページ分割されたテーブルにロードするには、 ``contain`` パラメータを使用します。 :: - - public function index() - { - $this->paginate = [ - 'contain' => ['Authors', 'Comments'] - ]; - - $this->set('articles', $this->paginate($this->Articles)); - } - -範囲外のページ要求 -================== - -PaginatorComponent は、存在しないページにアクセスしようとすると ``NotFoundException``` をスローします。 - -そのため、通常のエラーページをレンダリングさせるか、 try catch ブロックを使用して -``NotFoundException`` が発生した場合に適切な処理を行うことができます。 :: - - use Cake\Http\Exception\NotFoundException; - - public function index() - { - try { - $this->paginate(); - } catch (NotFoundException $e) { - // 最初のページや最後のページにリダイレクトするようにします。 - // $this->request->getAttribute('page')を指定すると、必要な情報が得られます。 - } - } - -ビューのページネーション -======================== - -ページネーションナビゲーションのリンクの作り方は、 :php:class:`~Cake\\View\\Helper\PaginatorHelper` -のドキュメントを確認してください。 - -.. - meta:: - :title lang=ja: ページネーション - :keywords lang=ja: order array,query conditions,php class,web applications,headaches,obstacles,complexity,programmers,parameters,paginate,designers,cakephp,satisfaction,developers From e85b805ba34619e740671cb8f0ce40764258f4ab Mon Sep 17 00:00:00 2001 From: Tomoya Date: Mon, 17 Jun 2024 01:18:37 +0900 Subject: [PATCH 227/337] add pagination page --- ja/controllers/pagination.rst | 287 ++++++++++++++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 ja/controllers/pagination.rst diff --git a/ja/controllers/pagination.rst b/ja/controllers/pagination.rst new file mode 100644 index 0000000000..4f3269e7da --- /dev/null +++ b/ja/controllers/pagination.rst @@ -0,0 +1,287 @@ +ページネーション +########## + +フレキシブルでかつユーザーフレンドリーなウェブアプリケーションを作成する際の主たる障害の +一つとなるのが、直感的なユーザーインターフェイスです。多くのアプリケーションはすぐに巨大となり +かつ複雑になり、デザイナーやプログラマーは、何百件、何千件ものレコードが表示されることに +対応しきれなくなってきます。リファクタリングするには時間がかかり、パフォーマンスやユーザー満足度が +犠牲になることが多いです。 + +１ページあたりに表示されるレコードの数を一定数に抑えることは、すべてのアプリケーションにとって +重大な課題であり、開発者にとって頭の痛い問題でした。CakePHP は素早く、かつ簡単に、 +データをページ分けする方法を提供することで、開発者への負担を軽減します。 + +CakePHP におけるページネーションは、コントローラーにおけるコンポーネントによって提供され、 +ページ分けされたクエリーをより簡単にビルドできるようにします。ビューの中の +:php:class:`~Cake\\View\\Helper\\PaginatorHelper` は、ページネーションのリンクや +ボタンを作り出すことを容易にすることに使われます。 + +基本的な使用方法 +=========== + +一度ロードされれば、ORMテーブルクラスや ``Query`` オブジェクトをページ分割することができます。 :: + + public function index() + { + // ORM テーブルのページ分割 + $this->set('articles', $this->paginate($this->Articles)); + + // 部分的に完了したクエリをページ分割する + $query = $this->Articles->find('published')->contain('Comments'); + $this->set('articles', $this->paginate($query)); + } + +高度な使用方法 +============== + +``$paginate`` のコントローラプロパティや ``paginate()`` の引数 +``$settings`` として設定することで、より複雑なユースケースをサポートしています。 +これらの条件はページ分割クエリの基礎となります。 +これらの条件は URLから渡される ``sort``, ``direction``, ``limit``, ``page`` +のパラメータによって拡張されます。　:: + + class ArticlesController extends AppController + { + protected array $paginate = [ + 'limit' => 25, + 'order' => [ + 'Articles.title' => 'asc', + ], + ]; + } + +.. tip:: + デフォルトの ``order`` オプションは配列として定義されていなければなりません。 + +ページネーションオプションを :ref:`custom-find-methods` にバンドルする方が +すっきりしていてシンプルです。 +``finder`` オプションを使用することで、ページ分割の際にファインダーを使用することができます。 :: + + class ArticlesController extends AppController + { + protected array $paginate = [ + 'finder' => 'published', + ]; + } + +ファインダーメソッドに追加のオプションが必要な場合は、これらの値を finder: に渡すことができます。 :: + + class ArticlesController extends AppController + { + // タグごとに記事を検索する + public function tags() + { + $tags = $this->request->getParam('pass'); + + $customFinderOptions = [ + 'tags' => $tags + ]; + + // カスタム Finder メソッドは、ArticlesTable.php の中で "findTagged" と呼ばれる + // 以下のような構文となっている + // public function findTagged(Query $query, array $options) { + // そのため、taggedをキーとして使用する + $settings = [ + 'finder' => [ + 'tagged' => $customFinderOptions + ] + ]; + $articles = $this->paginate($this->Articles, $settings); + $this->set(compact('articles', 'tags')); + } + } + +一般的なページネーションの値を定義することに加え、コントローラーには１セット以上の +ページネーションに関するデフォルト設定を定義することができます。そのためには、 +設定を加えたいモデルの後に、配列におけるキー名称を加えるだけです。 :: + + class ArticlesController extends AppController + { + protected array $paginate = [ + 'Articles' => [], + 'Authors' => [], + ]; + } + +``Articles`` や ``Authors`` のキーの値は、基本的な ``$paginate`` 配列に含まれる +すべてのプロパティを含めることができます。 + +一度 ``paginate()`` を使って結果を作成した後は コントローラのリクエストは +ページングパラメータで更新されます。 +ページングのメタデータは ``$this->request->getParam('paging')`` で取得できます。 + +シンプルなページネーション +================= + +デフォルトではページネーションは ``count()`` クエリを使って結果セットのサイズを計算し、 +ページ番号のリンクを表示できるようにしています。 +非常に大きなデータセットでは、このcountクエリは非常に高価になります。 +'Next' と 'Previous' リンクだけを表示したい場合は、カウントクエリを行わない +'simple' paginator を使うことができます。 :: + + class ArticlesController extends AppController + { + protected array $paginate = [ + 'className' => 'Simple', // Or use Cake\Datasource\Paging\SimplePaginator::class FQCN + ]; + } + +``SimplePaginator`` を使っている場合、ページ番号やカウンターデータ、最後のページへのリンク、 +総レコード数のコントロールを生成することはできません。 + +.. _paginating-multiple-queries: + +複数のクエリのページ分割 +=========================== + +コントローラの ``$paginate`` プロパティと ``paginate()`` メソッドを呼び出す際に +``scope`` オプションを使うことで、1つのコントローラのアクションの中で複数のモデルを +ページ分割することができます。 :: + + // ページ分割するプロパティ + protected array $paginate = [ + 'Articles' => ['scope' => 'article'], + 'Tags' => ['scope' => 'tag'] + ]; + + // コントローラーアクションにおいて + $articles = $this->paginate($this->Articles, ['scope' => 'article']); + $tags = $this->paginate($this->Tags, ['scope' => 'tag']); + $this->set(compact('articles', 'tags')); + +``scope`` オプションを指定すると、 ``PaginatorComponent`` がスコープされた +クエリ文字列パラメータを検索するようになります。 +例えば、以下のURLはタグと記事を同時にページ分割するのに使えます。 :: + + /dashboard?article[page]=1&tag[page]=3 + +スコープされたHTML要素やページネーション用のURLを生成する方法については +:ref:`paginator-helper-multiple` のセクションを参照してください。 + +同じモデルを複数回ページ分割する +---------------------------------------- + +1つのコントローラアクション内で同じモデルを複数回ページ分割するには、 +モデルのエイリアスを定義する必要があります。 +テーブルレジストリの使用方法の詳細については、 :ref:`table-registry-usage` を参照してください。 :: + + // コントローラーアクションにおいて + $this->paginate = [ + 'Articles' => [ + 'scope' => 'published_articles', + 'limit' => 10, + 'order' => [ + 'id' => 'desc', + ], + ], + 'UnpublishedArticles' => [ + 'scope' => 'unpublished_articles', + 'limit' => 10, + 'order' => [ + 'id' => 'desc', + ], + ], + ]; + + $publishedArticles = $this->paginate( + $this->Articles->find('all', scope: 'published_articles') + ->where(['published' => true]) + ); + + // ページ分割コンポーネントで差別化できるようにテーブルオブジェクトを追加登録します。 + $unpublishedArticlesTable = $this->fetchTable('UnpublishedArticles', [ + 'className' => 'App\Model\Table\ArticlesTable', + 'table' => 'articles', + 'entityClass' => 'App\Model\Entity\Article', + ]); + + $unpublishedArticles = $this->paginate( + $unpublishedArticlesTable->find('all', scope: 'unpublished_articles') + ->where(['published' => false]) + ); + +.. _control-which-fields-used-for-ordering: + +ソート時に使用するフィールドの制御 +====================================== + +デフォルトでは、テーブルが持つ非仮想カラムに対してソートを行うことができます。 +これはインデックス化されていないカラムをソートしてしまうことになり、 +ソートするのにコストがかかるため、望ましくないこともあります。 +ソートできるフィールドのホワイトリストを ``sortableFields`` オプションを使って設定することができます。 +このオプションは関連するデータやページ分割クエリの一部である計算フィールドをソートしたい場合に必要です。 :: + + protected array $paginate = [ + 'sortableFields' => [ + 'id', 'title', 'Users.username', 'created', + ], + ]; + +ホワイトリストにないフィールドでソートしようとするリクエストは無視されます。 + +1ページあたりの最大行数を制限する +========================================= + +ページごとに取得される結果の数は ``limit`` パラメータとしてユーザに公開されます。 +一般的に、ユーザがページ分割されたセットのすべての行を取得できるようにすることは望ましくありません。 +オプションの ``maxLimit`` は、外部からこの制限値を高く設定することはできないことを保証します。 +デフォルトでは、CakePHPはフェッチできる行の最大数を100に制限しています。 +もしこのデフォルト値がアプリケーションにとって適切でない場合は、 +ページ分割オプションの一部として調整することができます。 :: + + protected array $paginate = [ + // Other keys here. + 'maxLimit' => 10 + ]; + +リクエストのリミットパラメータがこの値よりも大きければ、 ``maxLimit`` の値まで減らされます。 + +範囲外のページ要求 +========================== + +``Controller::paginate()`` は、存在しないページにアクセスしようとすると ``NotFoundException``` をスローします。 + +そのため、通常のエラーページをレンダリングさせるか、 try catch ブロックを使用して +``NotFoundException`` が発生した場合に適切な処理を行うことができます。 :: + + use Cake\Http\Exception\NotFoundException; + + public function index() + { + try { + $this->paginate(); + } catch (NotFoundException $e) { + // 最初のページや最後のページにリダイレクトするようにします。 + // $e->getPrevious()->getAttributes('pagingParams')を指定すると、必要な情報が得られます。 + } + } + +paginatorクラスを直接利用する +================================ + +paginatorクラスを直接利用することも可能です。 :: + + // paginatorのインスタンスを生成する + $paginator = new \Cake\Datasource\Paginator\NumericPaginator(); + + // モデルをページネーションする + $results = $paginator->paginate( + // ページ分割が必要なクエリまたはテーブルインスタンス + $this->fetchTable('Articles'), + // リクエストパラメーター + $this->request->getQueryParams(), + // Config array having the same structure as options as Controller::$paginate + [ + 'finder' => 'latest', + ] + ); + +ビューのページネーション +====================== + +ページネーションナビゲーションのリンクの作り方は、 :php:class:`~Cake\\View\\Helper\PaginatorHelper` +のドキュメントを確認してください。 + +.. meta:: + :title lang=ja: ページネーション + :keywords lang=ja: paginate,pagination,paging From a4c9a2fe5a72147d32f6a24ad3c394d1b2743b71 Mon Sep 17 00:00:00 2001 From: Tomoya Date: Mon, 17 Jun 2024 01:22:27 +0900 Subject: [PATCH 228/337] mod paginator link --- ja/contents.rst | 1 + ja/controllers.rst | 2 +- ja/topics.rst | 2 +- ja/views/helpers/paginator.rst | 2 +- 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/ja/contents.rst b/ja/contents.rst index 585fc42155..782643f714 100644 --- a/ja/contents.rst +++ b/ja/contents.rst @@ -43,6 +43,7 @@ core-libraries/internationalization-and-localization core-libraries/logging core-libraries/form + controllers/pagination plugins development/rest security diff --git a/ja/controllers.rst b/ja/controllers.rst index 117330e775..24cd24f7c2 100644 --- a/ja/controllers.rst +++ b/ja/controllers.rst @@ -442,7 +442,7 @@ CakePHP のコントローラーに紐づけることができます。 :: このメソッドはモデルから取得した結果をページ分けするために使われます。 ページサイズやモデルの検索条件などを指定できます。 -`paginate()` のより詳しい使い方は :doc:`ページネーション ` +`paginate()` のより詳しい使い方は :doc:`ページネーション ` の章を参照してください。 ``$paginate`` 属性は ``paginate()`` がどうふるまうかを簡単にカスタマイズする方法を提供します。 :: diff --git a/ja/topics.rst b/ja/topics.rst index d3f942acf6..bdba22a85d 100644 --- a/ja/topics.rst +++ b/ja/topics.rst @@ -25,7 +25,7 @@ CakePHP のすべての重要な部分の紹介 * :doc:`/development/sessions` * :doc:`/development/rest` * :doc:`/controllers/components/authentication` -* :doc:`/controllers/components/pagination` +* :doc:`/controllers/pagination` * :ref:`csrf-middleware` * :doc:`/core-libraries/email` * :doc:`/views/helpers/form` diff --git a/ja/views/helpers/paginator.rst b/ja/views/helpers/paginator.rst index 40ac6aaed7..04c9882f93 100644 --- a/ja/views/helpers/paginator.rst +++ b/ja/views/helpers/paginator.rst @@ -10,7 +10,7 @@ PaginatorHelper は、ページ番号や次ページへ／前ページへのリ と連携して機能します。 ページ制御を組み込んだデータセットの作成や、ページ制御関連のクエリーについての詳細は -:doc:`/controllers/components/pagination` を参照してください。 +:doc:`/controllers/pagination` を参照してください。 .. _paginator-templates: From 518ed8c03e51f4cf91bbbc027148c76d899ff5c4 Mon Sep 17 00:00:00 2001 From: Tomoya Date: Mon, 17 Jun 2024 01:30:05 +0900 Subject: [PATCH 229/337] fix title underline --- ja/controllers/pagination.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/ja/controllers/pagination.rst b/ja/controllers/pagination.rst index 4f3269e7da..375e431de6 100644 --- a/ja/controllers/pagination.rst +++ b/ja/controllers/pagination.rst @@ -1,5 +1,5 @@ ページネーション -########## +################# フレキシブルでかつユーザーフレンドリーなウェブアプリケーションを作成する際の主たる障害の 一つとなるのが、直感的なユーザーインターフェイスです。多くのアプリケーションはすぐに巨大となり @@ -17,7 +17,7 @@ CakePHP におけるページネーションは、コントローラーにおけ ボタンを作り出すことを容易にすることに使われます。 基本的な使用方法 -=========== +================ 一度ロードされれば、ORMテーブルクラスや ``Query`` オブジェクトをページ分割することができます。 :: @@ -111,7 +111,7 @@ CakePHP におけるページネーションは、コントローラーにおけ ページングのメタデータは ``$this->request->getParam('paging')`` で取得できます。 シンプルなページネーション -================= +========================== デフォルトではページネーションは ``count()`` クエリを使って結果セットのサイズを計算し、 ページ番号のリンクを表示できるようにしています。 @@ -132,7 +132,7 @@ CakePHP におけるページネーションは、コントローラーにおけ .. _paginating-multiple-queries: 複数のクエリのページ分割 -=========================== +======================== コントローラの ``$paginate`` プロパティと ``paginate()`` メソッドを呼び出す際に ``scope`` オプションを使うことで、1つのコントローラのアクションの中で複数のモデルを @@ -159,7 +159,7 @@ CakePHP におけるページネーションは、コントローラーにおけ :ref:`paginator-helper-multiple` のセクションを参照してください。 同じモデルを複数回ページ分割する ----------------------------------------- +================================== 1つのコントローラアクション内で同じモデルを複数回ページ分割するには、 モデルのエイリアスを定義する必要があります。 @@ -203,7 +203,7 @@ CakePHP におけるページネーションは、コントローラーにおけ .. _control-which-fields-used-for-ordering: ソート時に使用するフィールドの制御 -====================================== +================================== デフォルトでは、テーブルが持つ非仮想カラムに対してソートを行うことができます。 これはインデックス化されていないカラムをソートしてしまうことになり、 @@ -220,7 +220,7 @@ CakePHP におけるページネーションは、コントローラーにおけ ホワイトリストにないフィールドでソートしようとするリクエストは無視されます。 1ページあたりの最大行数を制限する -========================================= +================================= ページごとに取得される結果の数は ``limit`` パラメータとしてユーザに公開されます。 一般的に、ユーザがページ分割されたセットのすべての行を取得できるようにすることは望ましくありません。 @@ -237,7 +237,7 @@ CakePHP におけるページネーションは、コントローラーにおけ リクエストのリミットパラメータがこの値よりも大きければ、 ``maxLimit`` の値まで減らされます。 範囲外のページ要求 -========================== +================== ``Controller::paginate()`` は、存在しないページにアクセスしようとすると ``NotFoundException``` をスローします。 @@ -277,7 +277,7 @@ paginatorクラスを直接利用することも可能です。 :: ); ビューのページネーション -====================== +======================== ページネーションナビゲーションのリンクの作り方は、 :php:class:`~Cake\\View\\Helper\PaginatorHelper` のドキュメントを確認してください。 From c984d7011f54f9ce788e227055c5936696bc3d77 Mon Sep 17 00:00:00 2001 From: Tomoya Date: Mon, 17 Jun 2024 01:35:19 +0900 Subject: [PATCH 230/337] remove paginator component toctree --- ja/controllers/components.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/ja/controllers/components.rst b/ja/controllers/components.rst index b97a58b116..e1f8796150 100644 --- a/ja/controllers/components.rst +++ b/ja/controllers/components.rst @@ -17,7 +17,6 @@ CakePHP の中に含まれるコンポーネントの詳細については、各 /controllers/components/authentication /controllers/components/flash /controllers/components/security - /controllers/components/pagination /controllers/components/request-handling /controllers/components/form-protection /controllers/components/check-http-cache From d10733da8d6157e176c88241344d350963bcb68c Mon Sep 17 00:00:00 2001 From: Tomoya Date: Mon, 17 Jun 2024 07:02:57 +0900 Subject: [PATCH 231/337] remove load FlushComponent cms tutorial --- ja/tutorials-and-examples/cms/articles-controller.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/ja/tutorials-and-examples/cms/articles-controller.rst b/ja/tutorials-and-examples/cms/articles-controller.rst index 18b6a8a9ad..9cc46ca734 100644 --- a/ja/tutorials-and-examples/cms/articles-controller.rst +++ b/ja/tutorials-and-examples/cms/articles-controller.rst @@ -181,8 +181,6 @@ view テンプレートの作成 public function initialize(): void { parent::initialize(); - - $this->loadComponent('Flash'); // FlashComponent をインクルード } public function index() From f70902e4b39880a500d74e9f40114a1862aa2dc1 Mon Sep 17 00:00:00 2001 From: yosus <5551430+yosus@users.noreply.github.com> Date: Tue, 18 Jun 2024 20:38:46 +0800 Subject: [PATCH 232/337] Update csrf.rst Added a use to prevent this error PHP Fatal error: Could not check compatibility between App\Application::routes(App\RouteBuilder $routes): void and Cake\Http\BaseApplication::routes(Cake\Routing\RouteBuilder $routes): void, because class App\RouteBuilder is not available .... --- en/security/csrf.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/security/csrf.rst b/en/security/csrf.rst index fe707035ee..38b212cec5 100644 --- a/en/security/csrf.rst +++ b/en/security/csrf.rst @@ -57,6 +57,7 @@ apply CSRF to specific groups of routes:: // in src/Application.php use Cake\Http\Middleware\CsrfProtectionMiddleware; + use Cake\Routing\RouteBuilder; public function routes(RouteBuilder $routes) : void { From 39cc16746aa1c41af4c880fac1fdf84422aea07d Mon Sep 17 00:00:00 2001 From: Arhell Date: Wed, 19 Jun 2024 01:19:04 +0300 Subject: [PATCH 233/337] Update csrf.rst (fr, ja) --- fr/security/csrf.rst | 1 + ja/security/csrf.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/fr/security/csrf.rst b/fr/security/csrf.rst index 200b916db6..bc3ff26802 100644 --- a/fr/security/csrf.rst +++ b/fr/security/csrf.rst @@ -59,6 +59,7 @@ l'utilisation de CSRF à certains groupes de routes:: // dans src/Application.php use Cake\Http\Middleware\CsrfProtectionMiddleware; + use Cake\Routing\RouteBuilder; public function routes(RouteBuilder $routes) : void { diff --git a/ja/security/csrf.rst b/ja/security/csrf.rst index 98018be596..4ed459cabb 100644 --- a/ja/security/csrf.rst +++ b/ja/security/csrf.rst @@ -60,6 +60,7 @@ CSRFプロテクションは、アプリケーション全体、または特定 // src/Application.php use Cake\Http\Middleware\CsrfProtectionMiddleware; + use Cake\Routing\RouteBuilder; public function routes(RouteBuilder $routes) : void { From b8cd2aeb494e0df7a979c9113671d01b53254586 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 24 Jun 2024 00:30:56 -0400 Subject: [PATCH 234/337] Add docs notes for cakephp/cakephp#17714 --- en/appendices/5-1-migration-guide.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index e39823474f..b43caca714 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -26,6 +26,10 @@ Behavior Changes 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. Deprecations ============ From 3bc9c826bdf8e1465f065474cd96c3d1ba13527c Mon Sep 17 00:00:00 2001 From: yosus <5551430+yosus@users.noreply.github.com> Date: Wed, 26 Jun 2024 16:31:05 +0800 Subject: [PATCH 235/337] Update authentication.rst Return null required. --- en/tutorials-and-examples/cms/authentication.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/tutorials-and-examples/cms/authentication.rst b/en/tutorials-and-examples/cms/authentication.rst index 5a99e695c8..1f584d4a92 100644 --- a/en/tutorials-and-examples/cms/authentication.rst +++ b/en/tutorials-and-examples/cms/authentication.rst @@ -61,6 +61,7 @@ add the following:: if (strlen($password) > 0) { return (new DefaultPasswordHasher())->hash($password); } + return null; } } From 829e4fab0bb103d05daa9472fa75a5d067c1bdcc Mon Sep 17 00:00:00 2001 From: Arhell Date: Fri, 28 Jun 2024 00:24:44 +0300 Subject: [PATCH 236/337] Update authentication.rst (fr, ja) --- fr/tutorials-and-examples/cms/authentication.rst | 1 + ja/tutorials-and-examples/cms/authentication.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/fr/tutorials-and-examples/cms/authentication.rst b/fr/tutorials-and-examples/cms/authentication.rst index 0dcc55471c..a2054e00b4 100644 --- a/fr/tutorials-and-examples/cms/authentication.rst +++ b/fr/tutorials-and-examples/cms/authentication.rst @@ -64,6 +64,7 @@ le code suivant:: if (strlen($password) > 0) { return (new DefaultPasswordHasher())->hash($password); } + return null; } } diff --git a/ja/tutorials-and-examples/cms/authentication.rst b/ja/tutorials-and-examples/cms/authentication.rst index f26e193f04..e5fa84099d 100644 --- a/ja/tutorials-and-examples/cms/authentication.rst +++ b/ja/tutorials-and-examples/cms/authentication.rst @@ -55,6 +55,7 @@ ArticlesController と同様に、手動、もしくは bake シェルを使用 if (strlen($password) > 0) { return (new DefaultPasswordHasher())->hash($password); } + return null; } } From 5b6fb777c38e665b5cf3c877b3aff147ea43d468 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 30 Jun 2024 20:13:58 +0530 Subject: [PATCH 237/337] Update PHP version --- config/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/conf.py b/config/conf.py index 4a0bb878a1..2d223b0094 100644 --- a/config/conf.py +++ b/config/conf.py @@ -112,7 +112,7 @@ epub_tocdepth = 2 rst_epilog = """ -.. |phpversion| replace:: **8.2** +.. |phpversion| replace:: **8.3** .. |minphpversion| replace:: 8.1 """ From 3e9d042bc0e3bb9b0ff8f3bae9637a4ce46184db Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 30 Jun 2024 20:18:33 +0530 Subject: [PATCH 238/337] Update intro.rst --- en/intro.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/en/intro.rst b/en/intro.rst index c62d67c3a3..25291def5e 100644 --- a/en/intro.rst +++ b/en/intro.rst @@ -37,7 +37,7 @@ The model objects can be thought of as "Friend", "User", "Comment", or use Cake\ORM\Locator\LocatorAwareTrait; - $users = $this->getTableLocator()->get('Users'); + $users = $this->fetchTable('Users'); $resultset = $users->find()->all(); foreach ($resultset as $row) { echo $row->username; @@ -52,7 +52,7 @@ something like:: use Cake\ORM\Locator\LocatorAwareTrait; - $users = $this->getTableLocator()->get('Users'); + $users = $this->fetchTable('Users'); $user = $users->newEntity(['email' => 'mark@example.com']); $users->save($user); @@ -67,7 +67,7 @@ For example, the view could use model data to render an HTML view template conta or a XML formatted result for others to consume:: // In a view template file, we'll render an 'element' for each user. - +
  • element('user_info', ['user' => $user]) ?>
    • From f3fb2b73338e3f72fa9c490635f7b823d9cf2874 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 30 Jun 2024 21:36:14 +0530 Subject: [PATCH 239/337] Update forums list --- en/intro/where-to-get-help.rst | 37 ++++++++++++++-------------------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/en/intro/where-to-get-help.rst b/en/intro/where-to-get-help.rst index 68813f6866..85af585493 100644 --- a/en/intro/where-to-get-help.rst +++ b/en/intro/where-to-get-help.rst @@ -49,22 +49,22 @@ practical examples for function and data member usage for a class. :: tests/TestCase/ -The IRC Channel -=============== +Slack +===== -**IRC Channels on irc.freenode.net:** +`CakePHP Slack Support Channel `_ -- `#cakephp `_ -- General Discussion -- `#cakephp-docs `_ -- Documentation -- `#cakephp-bakery `_ -- Bakery -- `#cakephp-fr `_ -- French Canal. - -If you're stumped, give us a holler in the CakePHP IRC channel. -Someone from the `development team `_ -is usually there, especially during the daylight hours for North and South -America users. We'd love to hear from you, whether you need some help, want to +If you're stumped, give us a holler in the CakePHP Slack support channel. +We'd love to hear from you, whether you need some help, want to find users in your area, or would like to donate your brand new sports car. +Discord +======= + +`CakePHP Discord `_ + +You can also join us on Discord. + .. _cakephp-official-communities: Official CakePHP Forum @@ -94,7 +94,7 @@ Danish French ------ -- `French CakePHP Community `_ +- `French CakePHP Slack Channel `_ German ------ @@ -102,11 +102,6 @@ German - `German CakePHP Slack Channel `_ - `German CakePHP Facebook Group `_ -Iranian -------- - -- `Iranian CakePHP Community `_ - Dutch ----- @@ -121,16 +116,14 @@ Japanese Portuguese ---------- -- `Portuguese CakePHP Google Group `_ +- `Portuguese CakePHP Slack Channel `_ Spanish ------- - `Spanish CakePHP Slack Channel `_ -- `Spanish CakePHP IRC Channel `_ -- `Spanish CakePHP Google Group `_ .. meta:: :title lang=en: Where to Get Help - :description lang=en: Where to get help with CakePHP: The official CakePHP website, The Cookbook, The Bakery, The API, in the test cases, the IRC channel, The CakePHP Google Group or CakePHP Questions. + :description lang=en: Where to get help with CakePHP: The official CakePHP website, The Cookbook, The Bakery, The API, in the test cases, Slack, Discord, CakePHP Questions. :keywords lang=en: cakephp,cakephp help,help with cakephp,where to get help,cakephp irc,cakephp questions,cakephp api,cakephp test cases,open source projects,channel irc,code reference,irc channel,developer tools,test case,bakery From e00adb099dc0ae935643ef866827c83f45b144d1 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 30 Jun 2024 21:52:16 +0530 Subject: [PATCH 240/337] Update articles-controller.rst --- en/tutorials-and-examples/cms/articles-controller.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/tutorials-and-examples/cms/articles-controller.rst b/en/tutorials-and-examples/cms/articles-controller.rst index 3253c071cd..18add5b372 100644 --- a/en/tutorials-and-examples/cms/articles-controller.rst +++ b/en/tutorials-and-examples/cms/articles-controller.rst @@ -137,7 +137,7 @@ While this is a simple action, we've used some powerful CakePHP features. We start our action off by using ``findBySlug()`` which is a :ref:`Dynamic Finder `. This method allows us to create a basic query that finds articles by a given slug. We then use ``firstOrFail()`` to either fetch -the first record, or throw a ``NotFoundException``. +the first record, or throw a ``\Cake\Datasource\Exception\RecordNotFoundException``. Our action takes a ``$slug`` parameter, but where does that parameter come from? If a user requests ``/articles/view/first-post``, then the value 'first-post' is @@ -359,7 +359,7 @@ now. Add the following action to your ``ArticlesController``:: This action first ensures that the user has tried to access an existing record. If they haven't passed in an ``$slug`` parameter, or the article does not exist, -a ``NotFoundException`` will be thrown, and the CakePHP ErrorHandler will render +a ``RecordNotFoundException`` will be thrown, and the CakePHP ErrorHandler will render the appropriate error page. Next the action checks whether the request is either a POST or a PUT request. If From 9daf1105815c278dce69bc41759df2a759b6ce72 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 30 Jun 2024 22:17:02 +0530 Subject: [PATCH 241/337] Update info for disabling "auto-tables" --- en/development/application.rst | 15 ++++++++++++++- en/development/configuration.rst | 32 +------------------------------- 2 files changed, 15 insertions(+), 32 deletions(-) diff --git a/en/development/application.rst b/en/development/application.rst index e57fe27436..767f691327 100644 --- a/en/development/application.rst +++ b/en/development/application.rst @@ -63,6 +63,19 @@ global event listeners:: // Call the parent to `require_once` config/bootstrap.php parent::bootstrap(); + // CakePHP has the ability to fallback to using the `Cake\ORM\Table` + // class to represent your database tables when a related class is + // not created for that table. But using this "auto-tables" feature + // can make debugging more difficult in some scenarios. So we disable + // this feature except for the CLI environment (since the classes + // would not be present when using the `bake` code generation tool). + if (PHP_SAPI !== 'cli') { + FactoryLocator::add( + 'Table', + (new TableLocator())->allowFallbackClass(false) + ); + } + // Load MyPlugin $this->addPlugin('MyPlugin'); } @@ -74,4 +87,4 @@ each test method. .. meta:: :title lang=en: CakePHP Application - :keywords lang=en: http, middleware, psr-7, events, plugins, application, baseapplication + :keywords lang=en: http, middleware, psr-7, events, plugins, application, baseapplication,auto tables,auto-tables,generic table,class diff --git a/en/development/configuration.rst b/en/development/configuration.rst index d3a43a7ab1..736e00f838 100644 --- a/en/development/configuration.rst +++ b/en/development/configuration.rst @@ -564,36 +564,6 @@ The built in configuration engines are: By default your application will use ``PhpConfig``. -Disabling Generic Tables -======================== - -While utilizing generic table classes - also called auto-tables - when quickly -creating new applications and baking models is useful, generic table class can -make debugging more difficult in some scenarios. - -You can check if any query was emitted from a generic table class via DebugKit -via the SQL panel in DebugKit. If you're still having trouble diagnosing an -issue that could be caused by auto-tables, you can throw an exception when -CakePHP implicitly uses a generic ``Cake\ORM\Table`` instead of your concrete -class like so:: - - // In your bootstrap.php - use Cake\Event\EventManager; - use Cake\Http\Exception\InternalErrorException; - - $isCakeBakeShellRunning = (PHP_SAPI === 'cli' && isset($argv[1]) && $argv[1] === 'bake'); - if (!$isCakeBakeShellRunning) { - EventManager::instance()->on('Model.initialize', function($event) { - $subject = $event->getSubject(); - if (get_class($subject) === 'Cake\ORM\Table') { - $msg = sprintf( - 'Missing table class or incorrect alias when registering table class for database table %s.', - $subject->getTable()); - throw new InternalErrorException($msg); - } - }); - } - .. meta:: :title lang=en: Configuration - :keywords lang=en: finished configuration,legacy database,database configuration,value pairs,default connection,optional configuration,example database,php class,configuration database,default database,configuration steps,index database,configuration details,class database,host localhost,inflections,key value,database connection,piece of cake,basic web,auto tables,auto-tables,generic table,class + :keywords lang=en: finished configuration,legacy database,database configuration,value pairs,default connection,optional configuration,example database,php class,configuration database,default database,configuration steps,index database,configuration details,class database,host localhost,inflections,key value,database connection,piece of cake,basic web From 729fe299c7cbd3b9fa20cb5a1ac5026eee9413f8 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 7 Jul 2024 12:34:50 -0400 Subject: [PATCH 242/337] Add documentation for DI + components Refs cakephp/cakephp#17723 --- en/appendices/5-1-migration-guide.rst | 6 ++++++ en/controllers/components.rst | 23 +++++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index b43caca714..e3c1e2dba1 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -76,6 +76,12 @@ Core 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. +Controller +---------- + +- Components can now use the DI container to have dependencies resolved and + provided as constructor parameters just like Controllers and Commands do. + Database -------- diff --git a/en/controllers/components.rst b/en/controllers/components.rst index d90ddb2d20..cd5d3b7385 100644 --- a/en/controllers/components.rst +++ b/en/controllers/components.rst @@ -183,6 +183,29 @@ component would look something like this:: All components must extend :php:class:`Cake\\Controller\\Component`. Failing to do this will trigger an exception. +Components can use :doc:`/development/dependency-injection` to receive services +as constructor parameters:: + + namespace App\Controller\Component; + + use Cake\Controller\Component; + use App\Service\UserService; + + class SsoComponent extends Component + { + public function __construct( + ComponentRegistry $registry, + array $config = [], + UserService $users + ) { + parent::__construct($registry, $config); + $this->users = $users; + } + } + +.. versionadded: 5.1.0 + DI container support for Components was added. + Including your Component in your Controllers -------------------------------------------- From ac004090c23fd02689134e911623ebedc958c8f2 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 8 Jul 2024 00:38:22 -0400 Subject: [PATCH 243/337] Adding docs for cakephp/cakephp#17733 --- en/appendices/5-1-migration-guide.rst | 4 ++++ en/orm/database-basics.rst | 23 +++++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index e3c1e2dba1..7d026f2ec9 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -85,6 +85,10 @@ Controller 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. diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 4337120538..40dde2e1e2 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -400,6 +400,14 @@ json Maps to a ``JSON`` type if it's available, otherwise it maps to ``TEXT``. enum See :ref:`enum-type`. +geometry + Maps to a generic geometry storage type. +point + Maps to a single point in geospatial storage. +linestring + Maps to a single line in geospatial storage. +polygon + Maps to a single polygon in geospatial storage. These types are used in both the schema reflection features that CakePHP provides, and schema generation features CakePHP uses when using test fixtures. @@ -411,6 +419,10 @@ automatically convert input parameters from ``DateTime`` instances into a timestamp or formatted datestrings. Likewise, 'binary' columns will accept file handles, and generate file handles when reading data. +.. versionchanged:: 5.1.0 + The ``geometry``, ``point``, ``linestring``, and ``polygon`` types were + added. + .. _datetime-type: DateTime Type @@ -491,6 +503,17 @@ CakePHP recommends a few conventions for enums: - Enums should implement the ``Cake\Database\Type\EnumLabelInterface`` to improve compatibility with bake, and ``FormHelper``. +Geospatial Types +---------------- + +The ``geometry``, ``point``, ``linestring``, and ``polygon`` types are also known +as the "geospatial types". CakePHP offers limited support for geospatial +columns. Currently they can be defined in migrations, read in schema reflection, +and have values set as text. + +.. versionadded:: 5.1.0 + Geospatial schema types were added. + .. _adding-custom-database-types: From b774392f8751191623945bd8aeb5f02ade67aa03 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 8 Jul 2024 00:54:14 -0400 Subject: [PATCH 244/337] Fix whitespace --- en/orm/database-basics.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 40dde2e1e2..2b43457b2b 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -514,7 +514,6 @@ and have values set as text. .. versionadded:: 5.1.0 Geospatial schema types were added. - .. _adding-custom-database-types: Adding Custom Types From 5f2e23a5120841e4e6378b320f8ed29d4d2d2ec7 Mon Sep 17 00:00:00 2001 From: "T.Yajima" Date: Fri, 12 Jul 2024 10:10:31 +0900 Subject: [PATCH 245/337] fix: corrected the sentence --- ja/tutorials-and-examples/blog/part-two.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/tutorials-and-examples/blog/part-two.rst b/ja/tutorials-and-examples/blog/part-two.rst index c885c4f258..ad6b742703 100644 --- a/ja/tutorials-and-examples/blog/part-two.rst +++ b/ja/tutorials-and-examples/blog/part-two.rst @@ -186,7 +186,7 @@ CakePHP のリバースルーティング機能を活用することができま この時点で、ブラウザーから http://www.example.com/articles/index を開いてみてください。 タイトルと投稿内容のテーブル一覧がまとめられているビューが表示されるはずです。 -ビューの中のリンク (投稿記事のタイトルから ``/articles/view/どれかのID番号``いう表示を出します。 +ビューの中のリンク (投稿記事のタイトル) は ``/articles/view/どれかのID番号`` というリンクを表示します。 もしそういう表示が出ない場合には、何かおかしくなってしまったか、もうすでにあなたが その定義作業をしてしまったから（仕事がハヤイ！）か、のどちらかです。 そうでないなら、これから ``ArticlesController`` の中に作ってみましょう。 :: From 178138bb4c30442f38394376ea400b4fea007448 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 11 Jul 2024 23:29:11 -0400 Subject: [PATCH 246/337] Document change in cakephp/cakephp#17738 --- en/appendices/5-1-migration-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 7d026f2ec9..eb743a63f9 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -30,6 +30,9 @@ Behavior Changes 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. Deprecations ============ From a85f4da11386486cb86b0f1b45ecc12f19b3ade4 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 22 Jul 2024 10:45:38 -0400 Subject: [PATCH 247/337] Document change in cakephp/cakephp#17747 --- en/appendices/5-1-migration-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index eb743a63f9..26986eefe4 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -33,6 +33,8 @@ Behavior Changes - ``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 ``;``. Deprecations ============ From 9556f213ec147d5b9f50fc34389f2a23f55e98cc Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 23 Jul 2024 16:58:19 +0200 Subject: [PATCH 248/337] Add note for cakephp/cakephp#17693 --- en/appendices/5-1-migration-guide.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 26986eefe4..6aa341e908 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -73,6 +73,13 @@ Console - ``Arguments::hasArgument()`` and ``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 ---- @@ -81,12 +88,6 @@ Core 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. -Controller ----------- - -- Components can now use the DI container to have dependencies resolved and - provided as constructor parameters just like Controllers and Commands do. - Database -------- @@ -104,6 +105,12 @@ Datasource ``removeDelete()`` methods were added. These methods allow you to remove rules by name. +Error +----- + +- ``ErrorLoggerInterface`` now extends ``Psr\Log\LoggerInterface`` improving + interoperability with custom loggers that use PSR-3 traits and interfaces. + Http ---- From c7a23b7a510ab583c6a6e03ae470bd9e6f44ea4c Mon Sep 17 00:00:00 2001 From: "T.Yajima" Date: Thu, 25 Jul 2024 10:19:27 +0900 Subject: [PATCH 249/337] fix: corrected one of the notations --- ja/tutorials-and-examples/blog-auth-example/auth.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/tutorials-and-examples/blog-auth-example/auth.rst b/ja/tutorials-and-examples/blog-auth-example/auth.rst index 44746409ce..2656a098d6 100644 --- a/ja/tutorials-and-examples/blog-auth-example/auth.rst +++ b/ja/tutorials-and-examples/blog-auth-example/auth.rst @@ -256,7 +256,7 @@ composerを使ってAuthenticationプラグインをインストールします デフォルトでは、認証情報はリクエストデータの ``email`` と ``password`` フィールドから 抽出されます。認証結果は ``authentication`` という名前のリクエスト属性に注入されます。 この結果はいつでもコントローラのアクションから -``$this->request->getAttribute('authentication')``を使って調べることができます。 +``$this->request->getAttribute('authentication')`` を使って調べることができます。 すべてのページは ``AuthenticationComponent`` がリクエストごとに結果をチェックしているため、 制限されてしまいます。認証されたユーザを見つけられなかった場合は ユーザーを ``/users/login`` のページにリダイレクトします。 From c0d6d8117a7689cabdace69d7a7e1ece6a5e3cbf Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 25 Jul 2024 09:42:50 +0200 Subject: [PATCH 250/337] Add docs for cakephp/cakephp#17750 --- en/appendices/5-1-migration-guide.rst | 2 ++ en/views/helpers/html.rst | 20 ++++++++++++-------- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 6aa341e908..b6c752c624 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -166,3 +166,5 @@ Helpers * ``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/views/helpers/html.rst b/en/views/helpers/html.rst index 596f678883..a432d69a54 100644 --- a/en/views/helpers/html.rst +++ b/en/views/helpers/html.rst @@ -137,14 +137,15 @@ key in the $attributes parameter to ``true``, ie - ``['block' => true]``. If you set the "type" attribute using the $attributes parameter, CakePHP contains a few shortcuts: -======== ====================== - type translated value -======== ====================== -html text/html -rss application/rss+xml -atom application/atom+xml -icon image/x-icon -======== ====================== +========= ====================== + type translated value +========= ====================== +html text/html +rss application/rss+xml +atom application/atom+xml +icon image/x-icon +csrfToken The current CSRF token +========= ====================== .. code-block:: php @@ -215,6 +216,9 @@ In addition to making predefined meta tags, you can create link elements:: Any attributes provided to meta() when called this way will be added to the generated link tag. +.. versionchanged:: 5.1.0 + The ``csrfToken`` type was added. + Linking to Images ----------------- From 7deb334724e01d0e2af0e09aacc27f6d5fa6165f Mon Sep 17 00:00:00 2001 From: Joshua Vogel Date: Sun, 28 Jul 2024 21:11:35 +0300 Subject: [PATCH 251/337] Update time.rst The function as it appears in the code in 5.x branch is that the third argument needs to be a string or false, not null. https://github.com/cakephp/cakephp/blob/f0b88ba6cc42e319fd012a32e96af7b3826fefdc/src/View/Helper/TimeHelper.php#L405 --- en/views/helpers/time.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/views/helpers/time.rst b/en/views/helpers/time.rst index 775a63cf23..b1ba1c9d9e 100644 --- a/en/views/helpers/time.rst +++ b/en/views/helpers/time.rst @@ -29,7 +29,7 @@ posts using the TimeHelper:: echo $this->Time->format( $post->created, \IntlDateFormatter::FULL, - null, + false, $user->time_zone ); // Will display 'Saturday, August 22, 2011 at 11:53:00 PM GMT' From efd13fa314a5dc5b83d7990e049d9e2495f1ff6a Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 28 Jul 2024 19:25:55 -0400 Subject: [PATCH 252/337] Update 5.1 migration guide for cakephp/cakephp#17752 --- en/appendices/5-1-migration-guide.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index b6c752c624..c8a1af5581 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -35,6 +35,7 @@ Behavior Changes 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. Deprecations ============ @@ -105,11 +106,6 @@ Datasource ``removeDelete()`` methods were added. These methods allow you to remove rules by name. -Error ------ - -- ``ErrorLoggerInterface`` now extends ``Psr\Log\LoggerInterface`` improving - interoperability with custom loggers that use PSR-3 traits and interfaces. Http ---- From 5108893c11ef3e1a55b8ae7044e73bb1400b0593 Mon Sep 17 00:00:00 2001 From: Arhell Date: Tue, 30 Jul 2024 00:44:22 +0300 Subject: [PATCH 253/337] Update time.rst (fr, ja) --- fr/views/helpers/time.rst | 2 +- ja/views/helpers/time.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/views/helpers/time.rst b/fr/views/helpers/time.rst index 15cd51d418..dcbc762452 100644 --- a/fr/views/helpers/time.rst +++ b/fr/views/helpers/time.rst @@ -31,7 +31,7 @@ pouvons corriger la date et le temps de nos posts en utilisant le TimeHelper:: echo $this->Time->format( $post->created, \IntlDateFormatter::FULL, - null, + false, $user->time_zone ); // Affichera 'Saturday, August 22, 2011 at 11:53:00 PM GMT' diff --git a/ja/views/helpers/time.rst b/ja/views/helpers/time.rst index df96a94a31..ee6fc25240 100644 --- a/ja/views/helpers/time.rst +++ b/ja/views/helpers/time.rst @@ -30,7 +30,7 @@ TimeHelper を使って投稿日時を補正することができます。 :: echo $this->Time->format( $post->created, \IntlDateFormatter::FULL, - null, + false, $user->time_zone ); // GMT+0 のユーザーには 'Saturday, August 22, 2011 at 11:53:00 PM GMT' と From e3c85520e3a02bf8c04aa85d5fbd1bb3df145ada Mon Sep 17 00:00:00 2001 From: issa <12658523+issakujitsuk@users.noreply.github.com> Date: Wed, 31 Jul 2024 18:41:30 +0900 Subject: [PATCH 254/337] Update installation.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix typo "ソケッット" -> "ソケット" --- ja/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/installation.rst b/ja/installation.rst index f626bfc4d6..2b29d530de 100644 --- a/ja/installation.rst +++ b/ja/installation.rst @@ -481,7 +481,7 @@ server ディレクティブの例は、次の通りです。 .. note:: 最近の PHP-FPM の設定では、アドレス 127.0.0.1 の TCP 9000 ポートの代わりに unix php-fpm - ソケッットを待ち受けるように設定します。もし、上記の設定で 502 bad gateway エラーになった場合、 + ソケットを待ち受けるように設定します。もし、上記の設定で 502 bad gateway エラーになった場合、 TCP ポートの代わりに unix ソケットパスを使用するために ``fastcgi_pass`` を更新してください (例: fastcgi_pass unix:/var/run/php/php7.1-fpm.sock;)。 From 733cbaa274e19f5415314af9a50fdcbebdc82a14 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 2 Aug 2024 15:03:17 -0400 Subject: [PATCH 255/337] Add docs for cakephp/cakephp#17743 --- en/appendices/5-1-migration-guide.rst | 3 +++ en/controllers/request-response.rst | 10 +++++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index c8a1af5581..dc9f173acd 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -125,6 +125,9 @@ 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. TestSuite --------- diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 0d810466f5..674f45b371 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -106,6 +106,8 @@ data and other input:: use function Cake\Core\toBool; use function Cake\Core\toInt; use function Cake\Core\toString; + use function Cake\I18n\toDate; + use function Cake\I18n\toDateTime; // $active is bool|null. $active = toBool($this->request->getQuery('active')); @@ -116,6 +118,12 @@ data and other input:: // $query is string|null. $query = toString($this->request->getQuery('query')); + // Parse a date based on the format or null + $date = toDate($this->request->getQuery('date'), 'Y-m-d'); + + // Parse a datetime based on a format or null + $date = toDateTime($this->request->getQuery('datetime'), 'Y-m-d H:i:s'); + .. versionadded:: 5.1.0 Casting functions were added. @@ -413,7 +421,7 @@ There are several built-in detectors that you can use: X-Requested-With = XMLHttpRequest. * ``is('ssl')`` Check to see whether the request is via SSL. * ``is('flash')`` Check to see whether the request has a User-Agent of Flash. -* ``is('json')`` Check to see whether the request URL has 'json' extension or the +* ``is('json')`` Check to see whether the request URL has 'json' extension or the `Accept` header is set to 'application/json'. * ``is('xml')`` Check to see whether the request URL has 'xml' extension or the `Accept` header is set to 'application/xml' or 'text/xml'. From c3e9af23bdff41abf91780e393a05315a208e799 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20M=2E=20Gonz=C3=A1lez=20Mart=C3=ADn?= Date: Tue, 6 Aug 2024 10:00:22 +0100 Subject: [PATCH 256/337] Small clarification about prefix routing extra params --- en/development/routing.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/en/development/routing.rst b/en/development/routing.rst index 864b9ef620..df835199a3 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -637,6 +637,10 @@ the ``$options`` argument:: $routes->connect('/{controller}'); }); +Note the additional route parameters will be added to all the connected routes defined +inside the prefix block. You will need to use all the paramenters in the url array to +build the route later, if you don't use them you'll get a ``MissingRouteException``. + Multi word prefixes are by default converted using dasherize inflection, ie ``MyPrefix`` would be mapped to ``my-prefix`` in the URL. Make sure to set a path for such prefixes if you want to use a different format like for example underscoring:: From e37c540bd74c367f1c1a229189d4fec0a91ca181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20M=2E=20Gonz=C3=A1lez=20Mart=C3=ADn?= Date: Tue, 6 Aug 2024 11:24:54 +0100 Subject: [PATCH 257/337] fix typo --- en/development/routing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/routing.rst b/en/development/routing.rst index df835199a3..3faeffd7e2 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -638,7 +638,7 @@ the ``$options`` argument:: }); Note the additional route parameters will be added to all the connected routes defined -inside the prefix block. You will need to use all the paramenters in the url array to +inside the prefix block. You will need to use all the parameters in the url array to build the route later, if you don't use them you'll get a ``MissingRouteException``. Multi word prefixes are by default converted using dasherize inflection, ie ``MyPrefix`` From 65feded4a577637be92d34874cb906bd042655ef Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Wed, 7 Aug 2024 12:25:04 +0200 Subject: [PATCH 258/337] clarify Date/Time object doesn't extend DateTimeInterface anymore --- en/appendices/5-0-migration-guide.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 53223b3166..356f08b39e 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -182,6 +182,8 @@ I18n - ``FrozenDate`` was renamed to `Date` and ``FrozenTime`` was renamed to `DateTime`. - ``Time`` now extends ``Cake\Chronos\ChronosTime`` and is therefore immutable. +- ``Date`` and ``Time`` 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. From a1434ed23e4fd6e15395a9e47dd5eb3a5913ad67 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Wed, 7 Aug 2024 20:52:11 +0200 Subject: [PATCH 259/337] clarify Date objects don't extend DateTimeInterface --- en/appendices/5-0-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index 356f08b39e..d82accf36c 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -182,7 +182,7 @@ I18n - ``FrozenDate`` was renamed to `Date` and ``FrozenTime`` was renamed to `DateTime`. - ``Time`` now extends ``Cake\Chronos\ChronosTime`` and is therefore immutable. -- ``Date`` and ``Time`` objects do not extend ``DateTimeInterface`` anymore - therefore you can't compare them with ``DateTime`` objects. +- ``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. From 42cd3775a6f9a7861499fc1a96de5d32d82cbd8a Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 9 Aug 2024 22:58:00 -0400 Subject: [PATCH 260/337] 5.x Rename cookbook to book Simplify documentation naming conventions across the various file formats. --- config/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config/conf.py b/config/conf.py index 2d223b0094..cdea028feb 100644 --- a/config/conf.py +++ b/config/conf.py @@ -63,7 +63,7 @@ # (source start file, target name, title, author, # documentclass [howto/manual]). latex_documents = [ - ('pdf-contents', 'CakePHPCookbook.tex', u'CakePHP Cookbook Documentation', + ('pdf-contents', 'CakePHPBook.tex', u'CakePHP Book', u'Cake Software Foundation', 'manual'), ] @@ -72,7 +72,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'cakephpcookbook', u'CakePHP Cookbook Documentation', + ('index', 'cakephpbook', u'CakePHP Book', [u'CakePHP'], 1) ] @@ -80,7 +80,7 @@ # -- Options for Epub output ------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = u'CakePHP Cookbook' +epub_title = u'CakePHP Book' epub_author = u'Cake Software Foundation, Inc.' epub_publisher = u'Cake Software Foundation, Inc.' epub_copyright = u'%d, Cake Software Foundation, Inc.' % datetime.datetime.now().year @@ -98,7 +98,7 @@ epub_identifier = 'https://cakephp.org' # A unique identification for the text. -epub_uid = 'cakephpcookbook1393624653' +epub_uid = 'cakephpbook1393624653' # A list of files that should not be packed into the epub file. epub_exclude_files = [ From 1f5d26ec1084b25e169095847cfea6da7e396d49 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 11 Aug 2024 00:04:47 -0400 Subject: [PATCH 261/337] Bump requirements. --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 5793b68834..f6d654ebf0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ docutils==0.20.1 sphinx==7.0.1 sphinxcontrib-phpdomain==0.11.1 -cakephpsphinx>=0.1.57,<1.0 +cakephpsphinx>=0.1.58,<1.0 From 129bc7e886277fc6be3e97209240109f4f60b891 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 11 Aug 2024 21:37:10 -0400 Subject: [PATCH 262/337] Update ServerRequest::getBody() documentation This was missed in the 4 -> 5 upgrade. `ServerRequest::input()` was deprecated in 4.1 Fixes #7896 --- en/controllers/request-response.rst | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 915afdb123..eb602193ad 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -224,20 +224,24 @@ replace all possibly existing uploaded files:: PUT, PATCH or DELETE Data ------------------------- -.. php:method:: input($callback, [$options]) +.. php:method:: getBody() When building REST services, you often accept request data on ``PUT`` and ``DELETE`` requests. Any ``application/x-www-form-urlencoded`` request body data -will automatically be parsed and set to ``$this->data`` for ``PUT`` and -``DELETE`` requests. If you are accepting JSON or XML data, see below for how -you can access those request bodies. +will automatically be parsed and available via ``$request->getData()`` for ``PUT`` and +``DELETE`` requests. If you are accepting JSON or XML data, you can +access the raw data with ``getBody()``:: -When accessing the input data, you can decode it with an optional function. -This is useful when interacting with XML or JSON request body content. -Additional parameters for the decoding function can be passed as arguments to -``input()``:: + // Get the stream wrapper on the request body + $body = $request->getBody(); - $jsonData = $this->request->input('json_decode'); + // Get the request body as a string + $bodyString = (string)$request->getBody(); + +If your requests contain XML or JSON request content, you should consider using +:ref:`body-parser-middleware` to have CakePHP automatically parse those content +types making the parsed data available in ``$request->getData()`` and +``$request->getParsedBody()``. Environment Variables (from $_SERVER and $_ENV) ----------------------------------------------- @@ -394,7 +398,7 @@ There are several built-in detectors that you can use: X-Requested-With = XMLHttpRequest. * ``is('ssl')`` Check to see whether the request is via SSL. * ``is('flash')`` Check to see whether the request has a User-Agent of Flash. -* ``is('json')`` Check to see whether the request URL has 'json' extension or the +* ``is('json')`` Check to see whether the request URL has 'json' extension or the `Accept` header is set to 'application/json'. * ``is('xml')`` Check to see whether the request URL has 'xml' extension or the `Accept` header is set to 'application/xml' or 'text/xml'. From 8cc846e41d19eb02c55981f40ae8292ab58652ea Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 11 Aug 2024 23:09:03 -0400 Subject: [PATCH 263/337] Update PDF file reference --- README.md | 2 +- en/index.rst | 2 +- es/index.rst | 2 +- fr/index.rst | 2 +- ja/index.rst | 2 +- pt/index.rst | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 6b26889962..312c67b6c3 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ Building the PDF is a non-trivial task. 2. Run `make latex-en`. 3. Run `make pdf-en`. -At this point the completed PDF should be in `build/latex/en/CakePHPCookbook.pdf`. +At this point the completed PDF should be in `build/latex/en/CakePHPBook.pdf`. Contributing ------------ diff --git a/en/index.rst b/en/index.rst index 6a16ace998..7f50e3d67a 100644 --- a/en/index.rst +++ b/en/index.rst @@ -19,7 +19,7 @@ contribute any additions, deletions, or corrections to the documentation. Enjoy the CakePHP cookbook almost anywhere. Available as both a PDF and EPUB, you can now read it on more devices, as well as offline. - - `PDF <../_downloads/en/CakePHPCookbook.pdf>`_ + - `PDF <../_downloads/en/CakePHPBook.pdf>`_ - `EPUB <../_downloads/en/CakePHP.epub>`_ - `Original Source `_ diff --git a/es/index.rst b/es/index.rst index 4f5131b4fd..e599339324 100644 --- a/es/index.rst +++ b/es/index.rst @@ -19,7 +19,7 @@ o corrección de la documentación. Disfruta del manual de CakePHP en cualquier sitio. Disponible tanto en PDF como en EPUB, puedes leerlo en más dispositivos y de manera offline. - - `PDF <../_downloads/es/CakePHPCookbook.pdf>`_ + - `PDF <../_downloads/es/CakePHPBook.pdf>`_ - `EPUB <../_downloads/es/CakePHP.epub>`_ - `Original Source `_ diff --git a/fr/index.rst b/fr/index.rst index 0f202e93aa..ed92295f2a 100644 --- a/fr/index.rst +++ b/fr/index.rst @@ -22,7 +22,7 @@ la documentation. EPUB, vous pouvez maintenant lire les docs sur plus d'appareils et hors-ligne. - - `PDF <../_downloads/fr/CakePHPCookbook.pdf>`_. + - `PDF <../_downloads/fr/CakePHPBook.pdf>`_. - `EPUB <../_downloads/fr/CakePHP.epub>`_. - `Source originale `_. diff --git a/ja/index.rst b/ja/index.rst index bc9292b66c..77ec99f27b 100644 --- a/ja/index.rst +++ b/ja/index.rst @@ -20,7 +20,7 @@ CakePHP クックブックは、オープンに開発されている、コミュ どこでも CakePHP のレシピをお楽しみいただけます。PDF と EPUB をご用意しましたので、 多くのデバイス上でオフラインでドキュメントを読むことができます。 - - `PDF (英語) <../_downloads/en/CakePHPCookbook.pdf>`_ + - `PDF (英語) <../_downloads/en/CakePHPBook.pdf>`_ - `EPUB <../_downloads/ja/CakePHP.epub>`_ - `オリジナルソース `_ diff --git a/pt/index.rst b/pt/index.rst index 048965aa2f..fd8f81e3a9 100644 --- a/pt/index.rst +++ b/pt/index.rst @@ -20,7 +20,7 @@ quaisquer adições, exclusões ou correções para a documentação. Consulte o *cookbook* do CakePHP praticamente em qualquer lugar. Disponível como PDF e EPUB, você pode lê-lo em diversos dispositivos, e também offline. - - `PDF <../_downloads/pt/CakePHPCookbook.pdf>`_ + - `PDF <../_downloads/pt/CakePHPBook.pdf>`_ - `EPUB <../_downloads/pt/CakePHP.epub>`_ - `Código-fonte Original `_ From cd287989edffc2884e3e29f91ddd745aab14fc6d Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 12 Aug 2024 08:49:05 -0400 Subject: [PATCH 264/337] Remove more cookbook --- en/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/index.rst b/en/index.rst index 7f50e3d67a..093bbf9e9e 100644 --- a/en/index.rst +++ b/en/index.rst @@ -5,7 +5,7 @@ CakePHP 5 is a web development framework running on PHP |phpversion| (min. PHP |minphpversion|). Read :doc:`CakePHP at a Glance ` to get an introduction to the fundamentals of CakePHP. -The CakePHP cookbook is an openly developed and community editable documentation +The CakePHP book is an openly developed and community editable documentation project. Notice the pencil icon button fixated against the right wall; it will direct you to the GitHub online editor of the active page, allowing you to contribute any additions, deletions, or corrections to the documentation. @@ -16,7 +16,7 @@ contribute any additions, deletions, or corrections to the documentation. .. image:: /_static/img/read-the-book.jpg - Enjoy the CakePHP cookbook almost anywhere. Available as both a PDF and + Enjoy the CakePHP book almost anywhere. Available as both a PDF and EPUB, you can now read it on more devices, as well as offline. - `PDF <../_downloads/en/CakePHPBook.pdf>`_ @@ -53,5 +53,5 @@ elements in a CakePHP application: validation, and domain logic within your application. .. meta:: - :title lang=en: .. CakePHP Cookbook documentation master file, created by - :keywords lang=en: doc models,documentation master,presentation layer,documentation project,quickstart,original source,sphinx,liking,cookbook,validity,conventions,validation,cakephp,accuracy,storage and retrieval,heart,blog,project hope + :title lang=en: .. CakePHP book documentation master file, created by + :keywords lang=en: doc models,documentation master,presentation layer,documentation project,quickstart,original source,sphinx,liking,book,validity,conventions,validation,cakephp,accuracy,storage and retrieval,heart,blog,project hope From 9b1c849edb5785c55ac7907f2a6a3488f89b2d26 Mon Sep 17 00:00:00 2001 From: Arhell Date: Tue, 13 Aug 2024 01:19:55 +0300 Subject: [PATCH 265/337] Remove more cookbook (es, ja, pt) --- es/index.rst | 4 ++-- ja/index.rst | 4 ++-- pt/index.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/es/index.rst b/es/index.rst index e599339324..3cc7a646a2 100644 --- a/es/index.rst +++ b/es/index.rst @@ -48,5 +48,5 @@ elementos claves en una aplicación de CakePHP: * Los :doc:`modelos `, que son el ingrediente clave en cualquier aplicación. Manejan la validación y la lógica de dominio dentro de tu aplicación. .. meta:: - :title lang=es: .. CakePHP Cookbook archivo de documentación, creado por - :keywords lang=es: documento modelos,master documentación,capa presentación,proyecto documentación,guia de inicio rápido,fuente original,sphinx,liking,cookbook,validez,convenciones,validación,cakephp,exactitud,almacenaje y recuperación,corazón,blog + :title lang=es: .. CakePHP book archivo de documentación, creado por + :keywords lang=es: documento modelos,master documentación,capa presentación,proyecto documentación,guia de inicio rápido,fuente original,sphinx,liking,book,validez,convenciones,validación,cakephp,exactitud,almacenaje y recuperación,corazón,blog diff --git a/ja/index.rst b/ja/index.rst index 77ec99f27b..4cc7efa69b 100644 --- a/ja/index.rst +++ b/ja/index.rst @@ -51,5 +51,5 @@ CakePHP クックブックは、オープンに開発されている、コミュ バリデーションやあなたのアプリケーションのドメインロジックを処理します。 .. meta:: - :title lang=ja: .. CakePHP Cookbook documentation master file, created by - :keywords lang=ja: doc models,documentation master,presentation layer,documentation project,quickstart,original source,sphinx,liking,cookbook,validity,conventions,validation,cakephp,accuracy,storage and retrieval,heart,blog,project hope + :title lang=ja: .. CakePHP book documentation master file, created by + :keywords lang=ja: doc models,documentation master,presentation layer,documentation project,quickstart,original source,sphinx,liking,book,validity,conventions,validation,cakephp,accuracy,storage and retrieval,heart,blog,project hope diff --git a/pt/index.rst b/pt/index.rst index fd8f81e3a9..5e0e698d97 100644 --- a/pt/index.rst +++ b/pt/index.rst @@ -54,5 +54,5 @@ principais elementos existentes em uma aplicação construída com o CakePHP: lidam com a validação e a lógica de domínio em sua aplicação. .. meta:: - :title lang=pt: .. CakePHP Cookbook arquivo mestre de documentação, criado por - :keywords lang=pt: modelo de documentos,documentação principal,camada de apresentação,documentação de projeto,guia rápido,código-fonte original,sphinx,liking,cookbook,validade,convenções,validação,cakephp,precisão,armazenamento e recuperação,coração,blog,projeto + :title lang=pt: .. CakePHP book arquivo mestre de documentação, criado por + :keywords lang=pt: modelo de documentos,documentação principal,camada de apresentação,documentação de projeto,guia rápido,código-fonte original,sphinx,liking,book,validade,convenções,validação,cakephp,precisão,armazenamento e recuperação,coração,blog,projeto From eaebee7879e0fbab13e3d11f7d2b98375e43aad9 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Wed, 21 Aug 2024 12:36:57 +0200 Subject: [PATCH 266/337] add docs related to new events hook --- en/appendices/5-1-migration-guide.rst | 2 ++ en/core-libraries/events.rst | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index dc9f173acd..791f17908b 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -88,6 +88,8 @@ Core - 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 -------- diff --git a/en/core-libraries/events.rst b/en/core-libraries/events.rst index 5aa43ad40f..032d7f18b2 100644 --- a/en/core-libraries/events.rst +++ b/en/core-libraries/events.rst @@ -198,6 +198,30 @@ As you can see in the above code, the ``on()`` function will accept instances of the ``EventListener`` interface. Internally, the event manager will use ``implementedEvents()`` to attach the correct callbacks. +.. versionadded:: 5.1.0 + The ``events`` hook was added to the ``BaseApplication`` as well as the ``BasePlugin`` class + +As of CakePHP 5.1 it is recommended to register event listeners by adding them via the ``events`` hook in your application or plugin class:: + + namespace App; + + use App\Event\UserStatistic; + use Cake\Event\EventManagerInterface; + use Cake\Http\BaseApplication; + + class Application extends BaseApplication + { + // The rest of your Application class + + public function events(EventManagerInterface $eventManager): EventManagerInterface + { + $statistics = new UserStatistic(); + $eventManager->on($statistics); + + return $eventManager; + } + } + Registering Anonymous Listeners ------------------------------- From 59e8aa53f015afe41dc214998c077128382714cf Mon Sep 17 00:00:00 2001 From: Marwan Salim <45453458+MarwanSalim@users.noreply.github.com> Date: Wed, 21 Aug 2024 21:17:11 +0800 Subject: [PATCH 267/337] Update form.rst (#7904) Update the document to reflect that `/` has been removed from the input. Reference: https://github.com/cakephp/cakephp/commit/e0cbb0023a96c1f567807370a6ba6984771b26c2 --- en/views/helpers/form.rst | 50 +++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index f04d057957..d0b6376a1e 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -101,7 +101,7 @@ Output: .. code-block:: html - + .. note:: @@ -377,7 +377,7 @@ methods of FormHelper. By default the ``control()`` method will employ the following widget templates:: 'inputContainer' => '
    {{content}}
    ' - 'input' => '' + 'input' => '' 'requiredClass' => 'required' In case of validation errors it will also use:: @@ -567,11 +567,11 @@ as well as HTML attributes. This subsection will cover the options specific to
    - +
    * ``$options['label']`` - Either a string caption or an array of @@ -591,7 +591,7 @@ as well as HTML attributes. This subsection will cover the options specific to
    - +
    Alternatively, set this key to ``false`` to disable the generation of the @@ -606,7 +606,7 @@ as well as HTML attributes. This subsection will cover the options specific to .. code-block:: html
    - +
    If the label is disabled, and a ``placeholder`` attribute is provided, the @@ -631,7 +631,7 @@ as well as HTML attributes. This subsection will cover the options specific to
    - +
    * ``$options['options']`` - You can provide in here an array containing @@ -830,7 +830,7 @@ Will output: .. code-block:: html - + Creating Textareas ------------------ @@ -987,8 +987,8 @@ methods are described in each method's own section.) .. code-block:: html - - + + This can be disabled by setting ``'hiddenField'`` to ``false``:: @@ -1011,34 +1011,34 @@ methods are described in each method's own section.) .. code-block:: html

    Primary Colors

    - +

    Tertiary Colors

    - + @@ -1612,7 +1612,7 @@ Output: .. code-block:: html - + The value for the input can be any valid datetime string or ``DateTime`` instance. @@ -1624,7 +1624,7 @@ Output: .. code-block:: html - + Creating Date Controls ~~~~~~~~~~~~~~~~~~~~~~ @@ -1646,7 +1646,7 @@ Output: .. code-block:: html - + Creating Time Controls ~~~~~~~~~~~~~~~~~~~~~~ @@ -1668,7 +1668,7 @@ Output: .. code-block:: html - + Creating Month Controls ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1690,7 +1690,7 @@ Will output: .. code-block:: html - + Creating Year Controls ~~~~~~~~~~~~~~~~~~~~~~ @@ -1877,7 +1877,7 @@ the field's required and notBlank validation rules will be used in lieu of the d browser HTML5 required messages. Enabling the option will add the ``onvalid`` and ``oninvalid`` event attributes to your fields, for example:: - + If you want to manually set those events with custom JavaScript, you can set the ``autoSetCustomValidity`` option to ``false`` and use the special ``customValidityMessage`` template variable instead. This @@ -1917,7 +1917,7 @@ relative to *webroot/img*. By default it will use the following widget templates:: - 'inputSubmit' => '' + 'inputSubmit' => '' 'submitContainer' => '
    {{content}}
    ' **Options for Submit** From 8a0fe1c4c730c506f784c4c87f32854585f74d37 Mon Sep 17 00:00:00 2001 From: ADmad Date: Wed, 21 Aug 2024 18:58:31 +0530 Subject: [PATCH 268/337] Remove outdated info about Date and Time classes. (#7902) --- en/core-libraries/time.rst | 95 +++++++------------------------------- 1 file changed, 17 insertions(+), 78 deletions(-) diff --git a/en/core-libraries/time.rst b/en/core-libraries/time.rst index b60b05a09c..00ca458823 100644 --- a/en/core-libraries/time.rst +++ b/en/core-libraries/time.rst @@ -31,19 +31,18 @@ use the ``DateTime`` class:: Under the hood, CakePHP uses `Chronos `_ to power its ``DateTime`` utility. Anything you can do with ``Chronos`` and -PHP's ``DateTime``, you can do with ``DateTime`` and ``Date``. +PHP's ``DateTimeImmutable``, you can do with ``DateTime``. For more details on Chronos please see `the API documentation -`_. +`_. .. start-time Creating DateTime Instances -============================= +=========================== -``DateTime`` are immutable objects that are useful when you want to prevent -accidental changes to data, or when you want to avoid order based dependency -issues. +``DateTime`` are immutable objects as immutability prevents accidental changes +to data, and avoids order based dependency issues. There are a few ways to create ``DateTime`` instances:: @@ -407,85 +406,25 @@ You can also compare a ``DateTime`` instance within a range in the past:: Date ==== -.. php:class: Date - -The immutable ``Date`` class in CakePHP implements a similar API and methods as -:php:class:`Cake\\I18n\\DateTime` does. The main difference between ``DateTime`` -and ``Date`` is that ``Date`` does not track time components. As an example:: - - use Cake\I18n\Date; - - $date = new Date('2021-01-31'); - - $newDate = $date->modify('+2 hours'); - // Outputs '2021-01-31 00:00:00' - echo $newDate->format('Y-m-d H:i:s'); - - $newDate = $date->addHours(36); - // Outputs '2021-01-31 00:00:00' - echo $newDate->format('Y-m-d H:i:s'); - - $newDate = $date->addDays(10); - // Outputs '2021-02-10 00:00:00' - echo $newDate->format('Y-m-d H:i:s'); - - -Attempts to modify the timezone on a ``Date`` instance are also ignored:: - - use Cake\I18n\Date; - $date = new Date('2021-01-31', new \DateTimeZone('America/New_York')); - $newDate = $date->setTimezone(new \DateTimeZone('Europe/Berlin')); - - // Outputs 'America/New_York' - echo $newDate->format('e'); - -.. _mutable-time: - -Mutable Dates and Times -======================= - -.. php:class:: Time .. php:class:: Date -CakePHP uses mutable date and time classes that implement the same interface -as their immutable siblings. Immutable objects are useful when you want to prevent -accidental changes to data, or when you want to avoid order based dependency -issues. Take the following code:: - - use Cake\I18n\Time; - $time = new Time('2015-06-15 08:23:45'); - $time->modify('+2 hours'); - - // This method also modifies the $time instance - $this->someOtherFunction($time); - - // Output here is unknown. - echo $time->format('Y-m-d H:i:s'); - -If the method call was re-ordered, or if ``someOtherFunction`` changed the -output could be unexpected. The mutability of our object creates temporal -coupling. If we were to use immutable objects, we could avoid this issue:: +The immutable ``Date`` class in CakePHP represents calendar dates unaffected by +time and timezones. The ``Date`` class wraps the ``Cake\\Chronos\\ChronosDate`` class. - use Cake\I18n\DateTime; - $time = new DateTime('2015-06-15 08:23:45'); - $time = $time->modify('+2 hours'); - - // This method's modifications don't change $time - $this->someOtherFunction($time); +.. note:: - // Output here is known. - echo $time->format('Y-m-d H:i:s'); + Unlike the ``DateTime`` class, ``Date`` does not extends the ``DateTimeInterface``. + So you cannot cannot directly compare a ``Date`` instance with a ``DateTime`` instance. + But you can do comparisons like ``$dateTime->toNative() > $date->toNative()``. -Immutable dates and times are useful in entities as they prevent -accidental modifications, and force changes to be explicit. Using -immutable objects helps the ORM to more easily track changes, and ensure that -date and datetime columns are persisted correctly:: +Time +==== - // This change will be lost when the article is saved. - $article->updated->modify('+1 hour'); +.. php:class:: Time - // By replacing the time object the property will be saved. - $article->updated = $article->updated->modify('+1 hour'); +The ``Time`` class represents clock times independent of date or time zones +Similar to the ``DateTime`` and ```Date`` classes, the ``Time`` class is also immutable. +It wraps the ``Cake\\Chronos\\ChronosTime`` class. Accepting Localized Request Data ================================ From 34d964f6d62e5afa63039b74964f653e06730dd3 Mon Sep 17 00:00:00 2001 From: Arhell Date: Thu, 22 Aug 2024 00:31:50 +0300 Subject: [PATCH 269/337] Update form.rst (fr, ja) --- fr/views/helpers/form.rst | 40 ++++++++++++++++---------------- ja/views/helpers/form.rst | 48 +++++++++++++++++++-------------------- 2 files changed, 44 insertions(+), 44 deletions(-) diff --git a/fr/views/helpers/form.rst b/fr/views/helpers/form.rst index 2cd319302a..bc4d7863e0 100644 --- a/fr/views/helpers/form.rst +++ b/fr/views/helpers/form.rst @@ -106,7 +106,7 @@ Affichera: .. code-block:: html - + .. note:: @@ -400,7 +400,7 @@ méthodes de FormHelper. Par défaut, la méthode ``control()`` utilisera les templates de widget suivant:: 'inputContainer' => '
    {{content}}
    ' - 'input' => '' + 'input' => '' En cas d'erreurs de validation, elle utilisera également:: @@ -592,11 +592,11 @@ couvrir les options spécifiques de ``FormHelper::control()``.
    - +
    * ``$options['label']`` Soit une chaîne qui sera utilisée comme valeur pour @@ -617,7 +617,7 @@ couvrir les options spécifiques de ``FormHelper::control()``.
    - +
    Vous pouvez définir cette clé à ``false`` pour désactiver l'affichage de @@ -631,7 +631,7 @@ couvrir les options spécifiques de ``FormHelper::control()``. .. code-block:: html
    - +
    Si le label est désactivé et qu'un attribut ``placeholder`` est fourni, @@ -656,7 +656,7 @@ couvrir les options spécifiques de ``FormHelper::control()``.
    - +
    * ``$options['options']`` - Vous pouvez passer à cette option un tableau @@ -845,7 +845,7 @@ Affichera: .. code-block:: html - + Créer des Textareas ------------------- @@ -1000,8 +1000,8 @@ décrites dans les sections dédiées à ces méthodes). .. code-block:: html - - + + Ceci peut être désactivé en définissant l'option ``hiddenField`` à ``false``:: @@ -1025,34 +1025,34 @@ décrites dans les sections dédiées à ces méthodes). .. code-block:: html

    Couleurs primaires

    - +

    Couleurs tertiaires

    - + @@ -1714,7 +1714,7 @@ Affichera: .. code-block:: html - + Créer des Éléments Année ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1950,7 +1950,7 @@ le chemin de l'image sera relatif à *webroot*, sinon, il sera relatif à *webro Par défaut, les templates de widgets utilisés sont:: - 'inputSubmit' => '' + 'inputSubmit' => '' 'submitContainer' => '
    {{content}}
    ' **Options pour les Submit** diff --git a/ja/views/helpers/form.rst b/ja/views/helpers/form.rst index ede8761f4a..b4046a7438 100644 --- a/ja/views/helpers/form.rst +++ b/ja/views/helpers/form.rst @@ -96,7 +96,7 @@ FormHelper は、 *追加* または *編集* のフォームを作成するか .. code-block:: html - + .. note:: @@ -351,7 +351,7 @@ where request data is retained, you need to put ``context`` first:: デフォルトでは、 ``control()`` メソッドは、次のウィジェットテンプレートを使用します。 :: 'inputContainer' => '
    {{content}}
    ' - 'input' => '' + 'input' => '' 検証エラーが発生した場合は、以下も使われます。 :: @@ -526,11 +526,11 @@ HTML 属性を受け付けます。以下は ``FormHelper::control()`` で特有
    - +
    * ``$options['label']`` - 文字列の見出しや :ref:`ラベルのオプション` の配列。 @@ -549,7 +549,7 @@ HTML 属性を受け付けます。以下は ``FormHelper::control()`` で特有
    - +
    あるいは、 ``label`` 要素の出力を無効にするには、このキーに ``false`` を設定します。 @@ -563,7 +563,7 @@ HTML 属性を受け付けます。以下は ``FormHelper::control()`` で特有 .. code-block:: html
    - +
    これに配列を設定すると、 ``label`` 要素の追加オプションが提供されます。 @@ -584,7 +584,7 @@ HTML 属性を受け付けます。以下は ``FormHelper::control()`` で特有
    - +
    * ``$options['options']`` - ここには、アイテムの配列を引数として必要とする ``radio`` や @@ -765,7 +765,7 @@ FormHelper で利用可能なメソッドには、さらに特定のフォーム .. code-block:: html - + テキストエリアの作成 -------------------- @@ -914,8 +914,8 @@ textarea コントロールフィールドを作成します。使用される .. code-block:: html - - + + これは ``'hiddenField'`` を ``false`` とすることで無効にできます。 :: @@ -936,34 +936,34 @@ textarea コントロールフィールドを作成します。使用される .. code-block:: html

    Primary Colors

    - +

    Tertiary Colors

    - + @@ -1622,7 +1622,7 @@ CakePHP が Windows サーバー上にインストールされている場合、 .. code-block:: html - + 日付コントロールの作成 ~~~~~~~~~~~~~~~~~~~~~~ @@ -1663,7 +1663,7 @@ CakePHP が Windows サーバー上にインストールされている場合、 .. code-block:: html - + 時間コントロールの作成 ~~~~~~~~~~~~~~~~~~~~~~ @@ -1722,7 +1722,7 @@ CakePHP が Windows サーバー上にインストールされている場合、 .. code-block:: html - + 月コントロールの作成 ~~~~~~~~~~~~~~~~~~~~ @@ -1743,7 +1743,7 @@ Will output: .. code-block:: html - + 時間コントロールの作成 ~~~~~~~~~~~~~~~~~~~~~~ @@ -1938,7 +1938,7 @@ notBlank バリデーションメッセージに対するエラーメッセー このオプションを有効にすると、フィールドに ``onvalid`` と ``oninvalid`` イベント属性が追加されます。 例えば、 :: - + カスタム Javascript を使用してこれらのイベントを手動で設定したい場合は、 ``autoSetCustomValidity`` オプションを ``false`` に設定して、 @@ -1976,7 +1976,7 @@ Submit 要素の作成 デフォルトで次のウィジェットテンプレートを使用します。 :: - 'inputSubmit' => '' + 'inputSubmit' => '' 'submitContainer' => '
    {{content}}
    ' **Submit のオプション** From 504af6a3e30f1f1990f0b0140f49542802c74dc4 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Wed, 21 Aug 2024 23:11:40 -0400 Subject: [PATCH 270/337] Document changes in cakephp/cakephp#17856 --- en/appendices/5-1-migration-guide.rst | 1 + en/development/testing.rst | 11 ++++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 791f17908b..1d200570f2 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -138,6 +138,7 @@ TestSuite 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 ------- diff --git a/en/development/testing.rst b/en/development/testing.rst index 737865fb7a..59d85cd3f7 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1098,13 +1098,22 @@ to configure the requests you will send to your application under test:: // Set session data $this->session(['Auth.User.id' => 1]); - // Configure headers + // Configure headers and merge with the existing request $this->configRequest([ 'headers' => ['Accept' => 'application/json'] ]); + // Replace the existing request. Added in 5.1.0 + $this->replaceRequest([ + 'headers' => ['Accept' => 'application/json'] + ]); + + The state set by these helper methods is reset in the ``tearDown()`` method. +.. versionadded:: 5.1.0 + ``replaceRequest()`` was added. + Testing Actions Protected by CsrfComponent or SecurityComponent --------------------------------------------------------------- From 78e840c58f35e87ad674710830cbbb55b427da08 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Thu, 22 Aug 2024 21:15:02 +0200 Subject: [PATCH 271/337] fix tutorial entity accessible property not containing all necessary fields (#7910) --- en/tutorials-and-examples/cms/articles-model.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/tutorials-and-examples/cms/articles-model.rst b/en/tutorials-and-examples/cms/articles-model.rst index d9fd3c2036..dc72088515 100644 --- a/en/tutorials-and-examples/cms/articles-model.rst +++ b/en/tutorials-and-examples/cms/articles-model.rst @@ -65,6 +65,7 @@ look like this:: 'created' => true, 'modified' => true, 'users' => true, + 'tags' => true, ]; } From 90c27c806a145519429773596c1f2f33944d7666 Mon Sep 17 00:00:00 2001 From: yosus <5551430+yosus@users.noreply.github.com> Date: Fri, 30 Aug 2024 16:38:29 +0800 Subject: [PATCH 272/337] Update articles-model.rst there is no 'tags' at this point of the tutorial. In the database creation, 'tags' isn't directly linked to 'articles'. --- en/tutorials-and-examples/cms/articles-model.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/articles-model.rst b/en/tutorials-and-examples/cms/articles-model.rst index dc72088515..d9fd3c2036 100644 --- a/en/tutorials-and-examples/cms/articles-model.rst +++ b/en/tutorials-and-examples/cms/articles-model.rst @@ -65,7 +65,6 @@ look like this:: 'created' => true, 'modified' => true, 'users' => true, - 'tags' => true, ]; } From 97f343ea31c00ce82b01bb923d181887ceef649b Mon Sep 17 00:00:00 2001 From: yosus <5551430+yosus@users.noreply.github.com> Date: Fri, 30 Aug 2024 19:23:50 +0800 Subject: [PATCH 273/337] Update articles-model.rst sorry, the bake does create the `tags` field. Updated to reflect what bake actually creates using the cake 5 tutorial. --- en/tutorials-and-examples/cms/articles-model.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/en/tutorials-and-examples/cms/articles-model.rst b/en/tutorials-and-examples/cms/articles-model.rst index d9fd3c2036..e3415640dc 100644 --- a/en/tutorials-and-examples/cms/articles-model.rst +++ b/en/tutorials-and-examples/cms/articles-model.rst @@ -59,12 +59,15 @@ look like this:: class Article extends Entity { protected array $_accessible = [ + 'user_id' => true, 'title' => true, + 'slug' => true, 'body' => true, 'published' => true, 'created' => true, 'modified' => true, - 'users' => true, + 'user' => true, + 'tags' => true, ]; } From 4372b03eead4407a50f1c04e2f8c3a8b51ada622 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 30 Aug 2024 23:22:51 -0400 Subject: [PATCH 274/337] Document changes in cakephp/cakephp#17873 --- en/appendices/5-1-migration-guide.rst | 7 +++++++ en/orm/query-builder.rst | 22 ++++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 1d200570f2..c6d9e51f3a 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -131,6 +131,13 @@ I18n 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. + TestSuite --------- diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 372908f917..6c8f86e789 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -707,6 +707,28 @@ As seen above, the formatters attached to associated query builders are scoped to operate only on the data in the association. CakePHP will ensure that computed values are inserted into the correct entity. +If you want to replace the results of an association finder with +``formatResults`` and your replacement data is an associative array, use +``preserveKeys`` to retain keys when results are mapped to the parent query. For +example:: + + public function findSlugged(SelectQuery $query): SelectQuery + { + return $query->applyOptions(['preserveKeys' => true]) + ->formatResults(function ($results) { + return $results->indexBy(function ($record) { + return Text::slug($record->name); + }); + }); + } + +The ``preserveKeys`` option can be set as a contain option as well. + +.. versionadded:: 5.1.0 + The ``preserveKeys`` option was added. + + + .. _advanced-query-conditions: Advanced Conditions From 97d83e16329bb8d77d487e0a0076a91edfe6e704 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Thu, 5 Sep 2024 19:55:14 -0400 Subject: [PATCH 275/337] Replace checkNotModified with isNotModified (#7914) --- en/controllers/request-response.rst | 12 ++++++------ es/controllers/request-response.rst | 12 ++++++------ fr/controllers/request-response.rst | 12 ++++++------ ja/controllers/request-response.rst | 12 ++++++------ pt/controllers/request-response.rst | 12 ++++++------ 5 files changed, 30 insertions(+), 30 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index eb602193ad..305b2fb33e 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -930,7 +930,7 @@ that uniquely identifies the requested resource, as a checksum does for a file, in order to determine whether it matches a cached resource. To take advantage of this header, you must either call the -``checkNotModified()`` method manually or include the +``isNotModified()`` method manually or include the :doc:`/controllers/components/check-http-cache` in your controller:: public function index() @@ -943,7 +943,7 @@ To take advantage of this header, you must either call the $checksum = md5(json_encode($articles)); $response = $this->response->withEtag($checksum); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } @@ -967,14 +967,14 @@ last time. Setting this header helps CakePHP tell caching clients whether the response was modified or not based on their cache. To take advantage of this header, you must either call the -``checkNotModified()`` method manually or include the +``isNotModified()`` method manually or include the :doc:`/controllers/components/check-http-cache` in your controller:: public function view() { $article = $this->Articles->find()->first(); $response = $this->response->withModified($article->modified); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } $this->response; @@ -998,14 +998,14 @@ header:: Sending Not-Modified Responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. php:method:: checkNotModified(Request $request) +.. php:method:: isNotModified(Request $request) Compares the cache headers for the request object with the cache header from the response and determines whether it can still be considered fresh. If so, deletes the response content, and sends the `304 Not Modified` header:: // In a controller action. - if ($this->response->checkNotModified($this->request)) { + if ($this->response->isNotModified($this->request)) { return $this->response; } diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index ff035b378d..860cf851be 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -860,7 +860,7 @@ directamente. Esto se usa comúnmente con recursos estáticos como imágenes y o El método ``withEtag()`` (llamado etiqueta de entidad) es una cadena que identifica de forma única el recurso solicitado, como lo hace una suma de comprobación para un archivo, para determinar si coincide con un recurso almacenado en caché. -Para aprovechar este encabezado, debe llamar al método ``checkNotModified()`` manualmente o incluir +Para aprovechar este encabezado, debe llamar al método ``isNotModified()`` manualmente o incluir :doc:`/controllers/components/check-http-cache` en su controlador:: public function index() @@ -872,7 +872,7 @@ Para aprovechar este encabezado, debe llamar al método ``checkNotModified()`` m $checksum = md5(json_encode($articles)); $response = $this->response->withEtag($checksum); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } @@ -894,14 +894,14 @@ Además, bajo el modelo de validación de caché HTTP, puede configurar el encab fecha y hora en la que se modificó el recurso por última vez. Configurar este encabezado ayuda a CakePHP a decirle a los clientes de almacenamiento en caché si la respuesta se modificó o no según su caché. -Para aprovechar este encabezado, debe llamar al método ``checkNotModified()`` manualmente o incluir +Para aprovechar este encabezado, debe llamar al método ``isNotModified()`` manualmente o incluir :doc:`/controllers/components/check-http-cache` en su controlador:: public function view() { $article = $this->Articles->find()->first(); $response = $this->response->withModified($article->modified); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } $this->response; @@ -924,14 +924,14 @@ el encabezado ``Vary``:: Envío de respuestas no modificadas ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. php:method:: checkNotModified(Request $request) +.. php:method:: isNotModified(Request $request) Compara los encabezados de la caché del objeto de solicitud con el encabezado de la caché de la respuesta y determina sitodavía se puede considerar nuevo. Si es así, elimina el contenido de la respuesta y envía el encabezado `304 Not Modified`:: // En una acción del controlador. - if ($this->response->checkNotModified($this->request)) { + if ($this->response->isNotModified($this->request)) { return $this->response; } diff --git a/fr/controllers/request-response.rst b/fr/controllers/request-response.rst index 57c605f269..500c4f5317 100644 --- a/fr/controllers/request-response.rst +++ b/fr/controllers/request-response.rst @@ -995,7 +995,7 @@ correspond à une ressource du cache. Pour réellement tirer profit de l'utilisation de cet en-tête, vous devez soit appeler manuellement la méthode -``checkNotModified()`` ou inclure le +``isNotModified()`` ou inclure le :doc:`/controllers/components/request-handling` dans votre controlleur:: public function index() @@ -1008,7 +1008,7 @@ soit appeler manuellement la méthode $checksum = md5(json_encode($articles)); $response = $this->response->withEtag($checksum); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } @@ -1034,14 +1034,14 @@ ressource a été modifiée pour la dernière fois. Définir cet en-tête aide C leur cache. Pour réellement tirer profit de l'utilisation de cet en-tête, vous devez soit -appeler manuellement la méthode ``checkNotModified()`` ou inclure le +appeler manuellement la méthode ``isNotModified()`` ou inclure le :doc:`/controllers/components/request-handling` dans votre controlleur:: public function view() { $article = $this->Articles->find()->first(); $response = $this->response->withModified($article->modified); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } $this->response; @@ -1065,14 +1065,14 @@ ressource. Dans ces circonstances, vous pouvez utiliser l'en-tête ``Vary``:: Envoyer des Réponses Non-Modifiées ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. php:method:: checkNotModified(Request $request) +.. php:method:: isNotModified(Request $request) Compare les en-têtes de cache pour l'objet requêté avec l'en-tête du cache de la réponse et determine s'il peut toujours être considéré comme à jour. Si oui, il supprime le contenu de la réponse et envoie l'en-tête `304 Not Modified`:: // Dans une action de controller. - if ($this->response->checkNotModified($this->request)) { + if ($this->response->isNotModified($this->request)) { return $this->response; } diff --git a/ja/controllers/request-response.rst b/ja/controllers/request-response.rst index 08bb052b9e..6fc5f3ce15 100644 --- a/ja/controllers/request-response.rst +++ b/ja/controllers/request-response.rst @@ -926,7 +926,7 @@ HTTP におけるキャッシュの検証はコンテンツが定期的に変化 リソースが一致するかどうかを調べるためにキャッシュはチェックサムを比較するでしょう。 実際にこのヘッダーを使うメリットを得るためには、手動で -``checkNotModified()`` メソッドを呼び出すかコントローラーに +``isNotModified()`` メソッドを呼び出すかコントローラーに :doc:`/controllers/components/request-handling` を読み込まなければなりません。 :: public function index() @@ -938,7 +938,7 @@ HTTP におけるキャッシュの検証はコンテンツが定期的に変化 $checksum = md5(json_encode($articles)); $response = $this->response->withEtag($checksum); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } @@ -961,14 +961,14 @@ HTTP キャッシュの検証モデルのもとでは、リソースが最後に キャッシュしているクライアントにレスポンスが変更されたのかどうかを返答する手助けとなります。 実際にこのヘッダーを使うメリットを得るためには、 -``checkNotModified()`` メソッドを呼び出すかコントローラーに +``isNotModified()`` メソッドを呼び出すかコントローラーに :doc:`/controllers/components/request-handling` を読み込まなければなりません。 :: public function view() { $article = $this->Articles->find()->first(); $response = $this->response->withModified($article->modified); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } $this->response; @@ -991,13 +991,13 @@ Vary ヘッダー Not-Modified レスポンスの送信 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. php:method:: checkNotModified(Request $request) +.. php:method:: isNotModified(Request $request) リクエストオブジェクトとレスポンスのキャッシュヘッダーを比較し、まだキャッシュが有効かどうかを決定します。 もしまだ有効な場合、レスポンスのコンテンツは削除され `304 Not Modified` ヘッダーが送られます。 :: // コントローラーアクションの中で - if ($this->response->checkNotModified($this->request)) { + if ($this->response->isNotModified($this->request)) { return $this->response; } diff --git a/pt/controllers/request-response.rst b/pt/controllers/request-response.rst index f116307bcf..4e2d2df319 100644 --- a/pt/controllers/request-response.rst +++ b/pt/controllers/request-response.rst @@ -800,14 +800,14 @@ O método ``withEtag()`` (chamado tag de entidade) é uma string que identifica o recurso solicitado, como a soma de verificação de um arquivo, para determinar se ele corresponde a um recurso em cache. -Para tirar proveito desse cabeçalho, você deve chamar o método ``checkNotModified()`` +Para tirar proveito desse cabeçalho, você deve chamar o método ``isNotModified()`` manualmente ou incluir o seguinte :doc:`/controllers/components/request-handling` no seu controlador:: public function index() { $articles = $this->Articles->find('all'); $response = $this->response->withEtag($this->Articles->generateHash($articles)); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } $this->response = $response; @@ -829,7 +829,7 @@ Além disso, no modelo de validação de cache HTTP, você pode definir o cabeç pela última vez. Definir este cabeçalho ajuda o CakePHP a informar aos clientes de armazenamento em cache se a resposta foi modificada ou não com base em seu cache. -Para tirar proveito desse cabeçalho, você deve chamar o método ``checkNotModified()`` +Para tirar proveito desse cabeçalho, você deve chamar o método ``isNotModified()`` manualmente ou incluir o seguinte :doc:`/controllers/components/request-handling` no seu controlador:: @@ -837,7 +837,7 @@ no seu controlador:: { $article = $this->Articles->find()->first(); $response = $this->response->withModified($article->modified); - if ($response->checkNotModified($this->request)) { + if ($response->isNotModified($this->request)) { return $response; } $this->response; @@ -860,14 +860,14 @@ dependendo do navegador. Nessas circunstâncias, você pode usar o cabeçalho `` Enviando Respostas Não Modificadas ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. php:method:: checkNotModified(Request $request) +.. php:method:: isNotModified(Request $request) Compara os cabeçalhos de cache do objeto de solicitação com o cabeçalho de cache da resposta e determina se ele ainda pode ser considerado novo. Nesse caso, exclui o conteúdo da resposta e envia o cabeçalho `304 Not Modified`:: // Em um método do controlador. - if ($this->response->checkNotModified($this->request)) { + if ($this->response->isNotModified($this->request)) { return $this->response; } From 6d90f3c858776c222c69b682e25b915eae01ed78 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 8 Sep 2024 00:36:12 -0400 Subject: [PATCH 276/337] Document changes in cakephp/cakephp#17882 --- en/appendices/5-1-migration-guide.rst | 6 ++++++ en/orm/query-builder.rst | 28 +++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index c6d9e51f3a..7466978631 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -36,6 +36,7 @@ Behavior Changes - 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 ============ @@ -100,6 +101,11 @@ Database 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. Datasource ---------- diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 6c8f86e789..4087a249c8 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -1706,6 +1706,34 @@ You can create ``UNION ALL`` queries using the ``unionAll()`` method:: $unpublished->unionAll($inReview); +Intersections +------------- + +Intersections allow you to combine the result sets of two queries together and +finding results with overlapping results. Intersections are created by composing +one or more select queries together:: + + $inReview = $articles->find() + ->where(['need_review' => true]); + + $unpublished = $articles->find() + ->where(['published' => false]); + + $unpublished->intersect($inReview); + +You can create ``INTERSECT ALL`` queries using the ``intersectAll()`` method:: + + $inReview = $articles->find() + ->where(['need_review' => true]); + + $unpublished = $articles->find() + ->where(['published' => false]); + + $unpublished->intersectAll($inReview); + +.. versionadded:: 5.1.0 + ``intersect()`` and ``intersectAll()`` were added. + Subqueries ---------- From 96f5a939459a73c2d6377022749a7522e7419284 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 9 Sep 2024 13:25:17 -0400 Subject: [PATCH 277/337] Update migration guide for cakephp/cakephp#17891 --- en/appendices/5-1-migration-guide.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 7466978631..335d872d2a 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -46,6 +46,12 @@ 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 ============ From 93828eed16ef3fc1d43c0885a28bab001906e9bf Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 12 Sep 2024 20:24:49 +0530 Subject: [PATCH 278/337] Add info about cakephp/cakephp#17886 --- en/appendices/5-1-migration-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 335d872d2a..5cfbc73b95 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -149,6 +149,9 @@ ORM - Setting the ``preserveKeys`` option on association finder queries. This can be used with ``formatResults()`` to replace association finder results with an associative array. +- The ORM can now map SQLite columns with name containing ``json`` to ``JsonType``. + This currently an opt-in feature which can be enabled by setting the ``ORM.mapJsonTypeForSqlite`` + configure value to ``true`` in your app's bootstrap. TestSuite --------- From a4ff530953f48e945e5a8adb0d8b17fa6435909f Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 12 Sep 2024 20:28:17 +0530 Subject: [PATCH 279/337] update wording --- en/appendices/5-1-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 5cfbc73b95..2a7ad4d0fa 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -151,7 +151,7 @@ ORM associative array. - The ORM can now map SQLite columns with name containing ``json`` to ``JsonType``. This currently an opt-in feature which can be enabled by setting the ``ORM.mapJsonTypeForSqlite`` - configure value to ``true`` in your app's bootstrap. + configure value to ``true`` in your app. TestSuite --------- From 611026b2618c57e579eec67018f065eb6e035e5b Mon Sep 17 00:00:00 2001 From: ADmad Date: Fri, 13 Sep 2024 07:42:26 +0530 Subject: [PATCH 280/337] Update en/appendices/5-1-migration-guide.rst Co-authored-by: othercorey --- en/appendices/5-1-migration-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 2a7ad4d0fa..025a120680 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -149,8 +149,8 @@ ORM - Setting the ``preserveKeys`` option on association finder queries. This can be used with ``formatResults()`` to replace association finder results with an associative array. -- The ORM can now map SQLite columns with name containing ``json`` to ``JsonType``. - This currently an opt-in feature which can be enabled by setting the ``ORM.mapJsonTypeForSqlite`` +- 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 From 01412e832da3323cfcd6236722ff7b96241153ef Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Fri, 13 Sep 2024 15:18:45 +0200 Subject: [PATCH 281/337] mention PHPUnit 11 support --- en/appendices/5-1-migration-guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 025a120680..461b35e2f3 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -156,6 +156,7 @@ ORM 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 From fc9e02744cde0f2fc886607908da46da0f574bcf Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 13 Sep 2024 22:31:39 -0400 Subject: [PATCH 282/337] Update version numbers for 5.1.0 release --- config/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config/conf.py b/config/conf.py index a86ac479c8..212ded93b5 100644 --- a/config/conf.py +++ b/config/conf.py @@ -10,13 +10,13 @@ # built documents. # # The short X.Y version. -version = '5.next' +version = '5.x' # The full version, including alpha/beta/rc tags. -release = '5.next' +release = '5.x' # The search index version. -search_version = '5-next' +search_version = '5-x' # The marketing diplay name for the book. version_name = 'Chiffon' @@ -39,7 +39,7 @@ # The GitHub branch name for this version of the docs # for edit links to point at. -branch = '5.next' +branch = '5.x' # Add any paths that contain custom themes here, relative to this directory. html_theme_path = [] From f442ae98e986a960c60b010c4b23366099910fc0 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 13 Sep 2024 22:43:06 -0400 Subject: [PATCH 283/337] Fix notes --- en/appendices/5-1-migration-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 461b35e2f3..2432069804 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -78,8 +78,8 @@ Console ------- - ``Arguments::getBooleanOption()`` and ``Arguments::getMultipleOption()`` were added. -- ``Arguments::hasArgument()`` and ``getArgument()`` will now raise an exception - if an unknown argument name is provided. This helps prevent mixing up option/argument names. +- ``Arguments::getArgument()`` will now raise an exception if an unknown + argument name is provided. This helps prevent mixing up option/argument names. Controller From c4ae14af192a806776265751d439402ec2c8b612 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 13 Sep 2024 23:04:57 -0400 Subject: [PATCH 284/337] Update content to trigger build --- en/appendices/migration-guides.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/migration-guides.rst b/en/appendices/migration-guides.rst index d371baf803..4c993cde10 100644 --- a/en/appendices/migration-guides.rst +++ b/en/appendices/migration-guides.rst @@ -2,7 +2,7 @@ Migration Guides ################ Migration guides contain information regarding the new features introduced in -each version and the migration path between 4.x and 5.x. +each version and the migration path between 5.x minor releases. .. toctree:: :maxdepth: 1 From d384148d7ad17cdfd8e6cf1a8c56d5af2cf51453 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 13 Sep 2024 23:06:25 -0400 Subject: [PATCH 285/337] Restore 5x deploy action --- .github/workflows/deploy_5.yml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .github/workflows/deploy_5.yml diff --git a/.github/workflows/deploy_5.yml b/.github/workflows/deploy_5.yml new file mode 100644 index 0000000000..3c101e2dda --- /dev/null +++ b/.github/workflows/deploy_5.yml @@ -0,0 +1,28 @@ +--- +name: 'deploy_5.x' + +on: + push: + branches: + - 5.x + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/5.next' }} + +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - name: Cloning repo + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Push to dokku + uses: dokku/github-action@master + with: + git_remote_url: 'ssh://dokku@apps.cakephp.org:22/book-5' + git_push_flags: '-f' + ssh_private_key: ${{ secrets.DOKKU_SSH_PRIVATE_KEY }} From c4cc62d4ac000511553e94d2b6e624c89497a9f3 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Fri, 13 Sep 2024 23:38:37 -0400 Subject: [PATCH 286/337] Remove development version banner --- config/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/config/conf.py b/config/conf.py index 212ded93b5..3f9df238aa 100644 --- a/config/conf.py +++ b/config/conf.py @@ -31,8 +31,8 @@ {'name': '1.2', 'number': '1.2', 'title': '1.2 Book'}, {'name': '1.1', 'number': '1.1', 'title': '1.1 Book'}, ] -# 5.next is pre-release still. -is_prerelease = True +# Enables the 'development version banner' +is_prerelease = False # Languages available. languages = ['en', 'pt_BR', 'es', 'ja', 'fr'] From 37d7d6e0ef10ce46ee0f8bf5276182e3942d9c37 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 15 Sep 2024 00:07:25 +0530 Subject: [PATCH 287/337] Add info about results buffering --- en/appendices/5-1-migration-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index 2432069804..b0362377e1 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -112,6 +112,9 @@ Database 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()`` has been re-added. Datasource ---------- From d9e054b6116715cbd70d4228024968e23c91a404 Mon Sep 17 00:00:00 2001 From: ADmad Date: Sun, 15 Sep 2024 08:19:07 +0530 Subject: [PATCH 288/337] Update en/appendices/5-1-migration-guide.rst Co-authored-by: othercorey --- en/appendices/5-1-migration-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst index b0362377e1..caac02853f 100644 --- a/en/appendices/5-1-migration-guide.rst +++ b/en/appendices/5-1-migration-guide.rst @@ -114,7 +114,7 @@ Database ``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()`` has been re-added. + and ``SelectQuery::isBufferedResultsEnabled()`` have been re-added. Datasource ---------- From 16a21af657cd535b2f899e42de754d5b3b6fc6c8 Mon Sep 17 00:00:00 2001 From: ADmad Date: Mon, 16 Sep 2024 18:47:24 +0530 Subject: [PATCH 289/337] Add example for generating meta tag with CSRF token Also fix formatting --- en/views/helpers/html.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/en/views/helpers/html.rst b/en/views/helpers/html.rst index a432d69a54..db2b022c7e 100644 --- a/en/views/helpers/html.rst +++ b/en/views/helpers/html.rst @@ -149,12 +149,11 @@ csrfToken The current CSRF token .. code-block:: php - Html->meta( + echo $this->Html->meta( 'favicon.ico', '/favicon.ico', ['type' => 'icon'] ); - ?> // Output (line breaks added) // Note: The helper code makes two meta tags to ensure the // icon is downloaded by both newer and older browsers @@ -170,12 +169,11 @@ csrfToken The current CSRF token rel="shortcut icon" /> - Html->meta( + echo $this->Html->meta( 'Comments', '/comments/index.rss', ['type' => 'rss'] ); - ?> // Output (line breaks added) Html->meta( + echo $this->Html->meta( 'keywords', 'enter any meta keyword here' ); - ?> // Output - Html->meta( + echo $this->Html->meta( 'description', 'enter any meta description here' ); - ?> // Output + echo $this->Html->meta('csrfToken'); + // The CsrfProtection middleware must be loaded for your application + + In addition to making predefined meta tags, you can create link elements:: Html->meta([ From 18d1de71eba5e77becc17a9a6a11c47637d23be3 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 24 Sep 2024 22:10:08 -0400 Subject: [PATCH 290/337] Fix search version --- config/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/conf.py b/config/conf.py index 3f9df238aa..fd4d8c7989 100644 --- a/config/conf.py +++ b/config/conf.py @@ -16,7 +16,7 @@ release = '5.x' # The search index version. -search_version = '5-x' +search_version = '5' # The marketing diplay name for the book. version_name = 'Chiffon' From 61c4013ee2d62400004c7ecb614b08935da5e89a Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 3 Oct 2024 19:32:24 +0530 Subject: [PATCH 291/337] Update "Shells" to "Commands" --- en/console-commands/commands.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/console-commands/commands.rst b/en/console-commands/commands.rst index f8830bf7e4..429a048f22 100644 --- a/en/console-commands/commands.rst +++ b/en/console-commands/commands.rst @@ -433,8 +433,8 @@ the ``modified`` column to the current time. Remember, ``exec()`` will take the same string you type into your CLI, so you can include options and arguments in your command string. -Testing Interactive Shells --------------------------- +Testing Interactive Commands +---------------------------- Consoles are often interactive. Testing interactive commands with the ``Cake\TestSuite\ConsoleIntegrationTestTrait`` trait only requires passing the From 7dd23864975bf46f493b4f434e125212635a348b Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Sun, 6 Oct 2024 14:53:13 +0200 Subject: [PATCH 292/337] add more doc for component DI (#7922) * add more doc for component DI * Update en/development/dependency-injection.rst Co-authored-by: ADmad --------- Co-authored-by: ADmad --- en/controllers/components.rst | 7 ++--- en/development/dependency-injection.rst | 41 +++++++++++++++++++++++-- 2 files changed, 41 insertions(+), 7 deletions(-) diff --git a/en/controllers/components.rst b/en/controllers/components.rst index cd5d3b7385..44ec1be50a 100644 --- a/en/controllers/components.rst +++ b/en/controllers/components.rst @@ -147,11 +147,8 @@ in your controller, you could access it like so:: properties they share the same 'namespace'. Be sure to not give a component and a model the same name. -.. warning:: - - Component methods **don't** have access to :doc:`/development/dependency-injection` - like Controller actions have. Use a service class inside your controller actions - instead of a component if you need this functionality. +.. versionchanged:: 5.1.0 + Components are able to use :doc:`/development/dependency-injection` to receive services. .. _creating-a-component: diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst index 132beeeefb..bb307fb4c9 100644 --- a/en/development/dependency-injection.rst +++ b/en/development/dependency-injection.rst @@ -14,10 +14,14 @@ CakePHP will use the :term:`DI container` in the following situations: * Constructing controllers. * Calling actions on your controllers. +* Constructing Components. * Constructing Console Commands. * Constructing Middleware by classname. -A short example would be:: +Controller Example +================== + +:: // In src/Controller/UsersController.php class UsersController extends AppController @@ -45,7 +49,10 @@ database. Because this service is injected into our controller, we can easily swap the implementation out with a mock object or a dummy sub-class when testing. -Here is an example of an injected service inside a command:: +Command Example +=============== + +:: // In src/Command/CheckUsersCommand.php class CheckUsersCommand extends Command @@ -76,6 +83,36 @@ a whole to the Container and add the ``UsersService`` as an argument. With that you can then access that service inside the constructor of the command. +Component Example +================= + +:: + + // In src/Controller/Component/SearchComponent.php + class SearchComponent extends Command + { + public function __construct( + ComponentRegistry $registry, + private UserService $users + ) { + parent::__construct($registry, []); + } + + public function something() + { + $valid = $this->users->check('all'); + } + } + + // In src/Application.php + public function services(ContainerInterface $container): void + { + $container->add(SearchComponent::class) + ->addArgument(ComponentRegistry::class) + ->addArgument(UsersService::class); + $container->add(UsersService::class); + } + Adding Services =============== From ea6bd3fbb11372ea9c426c2fa609df68020aa96a Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 12 Oct 2024 22:40:18 -0400 Subject: [PATCH 293/337] Remove a vestigal reference to RequestHandler Found this after someone contacted me about a potential issue in the docs. --- en/controllers/request-response.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index 523662795d..bb85721d99 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -675,9 +675,8 @@ with content types that are not built into Response, you can map them with $this->response = $this->response->withType('vcf'); Usually, you'll want to map additional content types in your controller's -:php:meth:`~Controller::beforeFilter()` callback, so you can leverage the -automatic view switching features of :php:class:`RequestHandlerComponent` if you -are using it. +:php:meth:`~Controller::beforeFilter()` callback, so you can benefit from +automatic view switching provided by :ref:`controller-viewclasses`. .. _cake-response-file: From 89f1e899223a0840fda302f574a03897de895f0d Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 14 Oct 2024 00:19:48 -0400 Subject: [PATCH 294/337] Expand docs for plugin events Refs cakephp/cakephp#17962 --- en/plugins.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/en/plugins.rst b/en/plugins.rst index 869811525a..c90329120b 100644 --- a/en/plugins.rst +++ b/en/plugins.rst @@ -107,14 +107,17 @@ Plugins offer several hooks that allow a plugin to inject itself into the appropriate parts of your application. The hooks are: * ``bootstrap`` Used to load plugin default configuration files, define - constants and other global functions. + constants and other global functions. The ``bootstrap`` method is passed the + current ``Application`` instance giving you broad access to the DI container + and configuration. * ``routes`` Used to load routes for a plugin. Fired after application routes are loaded. * ``middleware`` Used to add plugin middleware to an application's middleware queue. * ``console`` Used to add console commands to an application's command collection. -* ``services`` Used to register application container services +* ``services`` Used to register application container service. This is a good + opportunity to setup additional objects that need acccess to the container. By default all plugins hooks are enabled. You can disable hooks by using the related options of the ``plugin load`` command: From c895f0f7d9af520f442ef68747f52ac25703d783 Mon Sep 17 00:00:00 2001 From: ADmad Date: Mon, 14 Oct 2024 11:16:23 +0530 Subject: [PATCH 295/337] Update counter-cache.rst (#7927) Update counter-cache.rst Refs cakephp/cakephp#17966 --- en/orm/behaviors/counter-cache.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/en/orm/behaviors/counter-cache.rst b/en/orm/behaviors/counter-cache.rst index 46b0d0a63c..ae87db1142 100644 --- a/en/orm/behaviors/counter-cache.rst +++ b/en/orm/behaviors/counter-cache.rst @@ -131,6 +131,14 @@ then updates the counter of the *previously* associated item. behavior to the ``CommentsTable`` in order to generate ``comment_count`` for Articles table. +.. versionchanged:: 5.1.2 + + As of CakePHP 5.1.2, the counter cache values are updated using a single + query using sub-queries, instead of separate queries, to fetch the count and + update a record. If required you can disable the use of sub-queries by + setting `useSubQuery` key to `false` in the config + `['Articles' => ['comment_count' => ['useSubQuery' => false]]` + Belongs to many Usage ===================== From db0ccec1152d8524c28bd8dac883f318ba09ab38 Mon Sep 17 00:00:00 2001 From: MolbioUnige Date: Thu, 17 Oct 2024 10:12:54 +0200 Subject: [PATCH 296/337] Update validation.rst Rules added through the add method are also checked during deletion --- en/orm/validation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/validation.rst b/en/orm/validation.rst index 46fc44dd8c..6d0eabe940 100644 --- a/en/orm/validation.rst +++ b/en/orm/validation.rst @@ -297,7 +297,7 @@ class:: // In a table class public function buildRules(RulesChecker $rules): RulesChecker { - // Add a rule that is applied for create and update operations + // Add a rule that is applied for create, update and delete operations $rules->add(function ($entity, $options) { // Return a boolean to indicate pass/failure }, 'ruleName'); From ead66f64f4ba3fc1e5e416975031dea7700f7228 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 22 Oct 2024 10:41:03 -0400 Subject: [PATCH 297/337] Give a more complete example for xml view generation (#7933) Fixes #7932 --- en/views/json-and-xml-views.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/en/views/json-and-xml-views.rst b/en/views/json-and-xml-views.rst index 04d7005bcc..e847382e5e 100644 --- a/en/views/json-and-xml-views.rst +++ b/en/views/json-and-xml-views.rst @@ -142,6 +142,13 @@ An example of using ``XmlView`` would be to generate a `sitemap.xml change ``rootNode`` and set attributes. Attributes are defined using the ``@`` prefix:: + use Cake\View\XmlView; + + public function viewClasses(): array + { + return [XmlView::class]; + } + public function sitemap() { $pages = $this->Pages->find()->all(); From 02af4350ad36fca8d86d928480e92dd155c3e243 Mon Sep 17 00:00:00 2001 From: Arhell Date: Wed, 23 Oct 2024 00:18:46 +0300 Subject: [PATCH 298/337] Give a more complete example for xml view generation (es, fr, ja) --- es/views/json-and-xml-views.rst | 7 +++++++ fr/views/json-and-xml-views.rst | 7 +++++++ ja/views/json-and-xml-views.rst | 7 +++++++ 3 files changed, 21 insertions(+) diff --git a/es/views/json-and-xml-views.rst b/es/views/json-and-xml-views.rst index eef756f76d..6d5e9ad52c 100644 --- a/es/views/json-and-xml-views.rst +++ b/es/views/json-and-xml-views.rst @@ -150,6 +150,13 @@ Un ejemplo de uso de ``XmlView`` sería generar un `sitemap.xml que cambie ``rootNode`` y establezca atributos. Los atributos se definen mediante el prefijo ``@``:: + use Cake\View\XmlView; + + public function viewClasses(): array + { + return [XmlView::class]; + } + public function sitemap() { $pages = $this->Pages->find()->all(); diff --git a/fr/views/json-and-xml-views.rst b/fr/views/json-and-xml-views.rst index d8bc35c525..dab41a72b2 100644 --- a/fr/views/json-and-xml-views.rst +++ b/fr/views/json-and-xml-views.rst @@ -153,6 +153,13 @@ Comme exemple d'utilisation de ``XmlView``, on peut imaginer la génération d'u nécessite de changer ``_rootNode`` et de définir des attributs. Les attributs sont définis en utilisant le préfixe ``@``:: + use Cake\View\XmlView; + + public function viewClasses(): array + { + return [XmlView::class]; + } + public function sitemap() { $pages = $this->Pages->find()->all(); diff --git a/ja/views/json-and-xml-views.rst b/ja/views/json-and-xml-views.rst index 2c5bcbbddf..36e8e855e9 100644 --- a/ja/views/json-and-xml-views.rst +++ b/ja/views/json-and-xml-views.rst @@ -142,6 +142,13 @@ XmlView クラスは、XML の生成に使用するオプション（例: ``tags このドキュメントタイプでは ``rootNode`` を変更し属性を設定する必要があります。 属性は ``@`` プレフィックスを使用して定義されます。 :: + use Cake\View\XmlView; + + public function viewClasses(): array + { + return [XmlView::class]; + } + public function sitemap() { $pages = $this->Pages->find()->all(); From 7aa93053a0a5f4d8463eb8a8519476ec8959df24 Mon Sep 17 00:00:00 2001 From: ADmad Date: Fri, 25 Oct 2024 16:49:36 +0530 Subject: [PATCH 299/337] Update form.rst --- en/views/helpers/form.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index d0b6376a1e..1472741556 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -2444,7 +2444,7 @@ a multiple select input for belongs to many associations:: echo $this->Form->control('tags._ids', [ 'type' => 'select', 'multiple' => true, - 'options' => $tagList, + 'options' => $tags, // $tags is the output of $this->Articles->Tags->find('list')->all() in the controller ]); From 5b6567ee614db35caed37e245ab0e16faebd83e9 Mon Sep 17 00:00:00 2001 From: Al <7813306+mehov@users.noreply.github.com> Date: Fri, 25 Oct 2024 15:22:06 +0200 Subject: [PATCH 300/337] Clarify that a primary key is required --- en/orm/associations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/associations.rst b/en/orm/associations.rst index 2b0bd333e6..6c576bb827 100644 --- a/en/orm/associations.rst +++ b/en/orm/associations.rst @@ -510,7 +510,7 @@ example above we would need tables for ``articles``, ``tags`` and ``articles_tags``. The ``articles_tags`` table contains the data that links tags and articles together. The joining table is named after the two tables involved, separated with an underscore by convention. In its simplest form, this -table consists of ``article_id`` and ``tag_id``. +table consists of ``article_id`` and ``tag_id``, as well as `multiple-column ``PRIMARY KEY`` index `_ spanning both of these columns. **belongsToMany** requires a separate join table that includes both *model* names. From e3623ea9afdbdc2e8737b48bb06901ab680df092 Mon Sep 17 00:00:00 2001 From: Kevin Pfeifer Date: Sat, 26 Oct 2024 12:34:18 +0200 Subject: [PATCH 301/337] add docs for Server.terminate event --- en/core-libraries/events.rst | 39 +++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/en/core-libraries/events.rst b/en/core-libraries/events.rst index 032d7f18b2..889f040074 100644 --- a/en/core-libraries/events.rst +++ b/en/core-libraries/events.rst @@ -152,6 +152,43 @@ application. * :ref:`Controller events ` * :ref:`View events ` +``Server.terminate`` +-------------------- + +The ``Server.terminate`` event is triggered after the response has been sent to the +client. This event is useful for performing tasks that should be done after the +response has been sent, such as logging or sending emails. + +You can listen to this event using an event manager instance:: + + use Cake\Event\EventManager; + + EventManager::instance()->on('Server.terminate', function ($event) { + // Perform tasks that should be done after the response has been + // sent to the client. + }); + +Or using the ``events`` hook in your Application/Plugin class:: + + use Cake\Event\EventManagerInterface; + + public function events(EventManagerInterface $eventManager): EventManagerInterface + { + $eventManager->on('Server.terminate', function ($event) { + // Perform tasks that should be done after the response has been + // sent to the client. + }); + + return $eventManager; + } + +.. tip:: + This is called even if an exception is thrown during the request, e.g. on 404 pages. + +.. note:: + The ``Server.terminate`` event only works for PHP-FPM implementations which + support the ``fastcgi_finish_request`` function. + .. _registering-event-listeners: Registering Listeners @@ -204,7 +241,7 @@ of the ``EventListener`` interface. Internally, the event manager will use As of CakePHP 5.1 it is recommended to register event listeners by adding them via the ``events`` hook in your application or plugin class:: namespace App; - + use App\Event\UserStatistic; use Cake\Event\EventManagerInterface; use Cake\Http\BaseApplication; From be95c0a5e1d0bfaf4945f7dea4b592903c66fd6e Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sat, 26 Oct 2024 11:56:19 -0400 Subject: [PATCH 302/337] Streamline wording and remove link that could rot. Refs #7939 --- en/orm/associations.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/en/orm/associations.rst b/en/orm/associations.rst index 6c576bb827..9261c9240f 100644 --- a/en/orm/associations.rst +++ b/en/orm/associations.rst @@ -510,7 +510,8 @@ example above we would need tables for ``articles``, ``tags`` and ``articles_tags``. The ``articles_tags`` table contains the data that links tags and articles together. The joining table is named after the two tables involved, separated with an underscore by convention. In its simplest form, this -table consists of ``article_id`` and ``tag_id``, as well as `multiple-column ``PRIMARY KEY`` index `_ spanning both of these columns. +table consists of ``article_id`` and ``tag_id`` and a multi-column +``PRIMARY KEY`` index spanning both columns. **belongsToMany** requires a separate join table that includes both *model* names. From 71b94a07bdd0821743d598f78fdfb62db6eb85ac Mon Sep 17 00:00:00 2001 From: Mario Rothauer Date: Fri, 1 Nov 2024 09:45:23 +0100 Subject: [PATCH 303/337] Update database-basics.rst --- en/orm/database-basics.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 2b43457b2b..dd971ba8e1 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -589,7 +589,7 @@ the type mapping. During our application bootstrap we should do the following:: use Cake\Database\TypeFactory; - TypeFactory::map('json', \App\Database\Type\JsonType:class); + TypeFactory::map('json', \App\Database\Type\JsonType::class); We then have two ways to use our datatype in our models. From 4a7683faeabbdcbf53e9efe8065e119e41adbb6b Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 4 Nov 2024 12:50:55 -0500 Subject: [PATCH 304/337] Remove duplicate toc entries We don't need an entire page for migration-guide listing when it can be done on the appendices page. --- en/appendices.rst | 1 + en/appendices/migration-guides.rst | 13 ------------- 2 files changed, 1 insertion(+), 13 deletions(-) delete mode 100644 en/appendices/migration-guides.rst diff --git a/en/appendices.rst b/en/appendices.rst index 903e6f29da..3c55fd4c20 100644 --- a/en/appendices.rst +++ b/en/appendices.rst @@ -13,6 +13,7 @@ introduced in each version and the migration path between versions. appendices/5-0-upgrade-guide appendices/5-0-migration-guide appendices/5-1-migration-guide + appendices/phpunit10 Backwards Compatibility Shimming ================================ diff --git a/en/appendices/migration-guides.rst b/en/appendices/migration-guides.rst deleted file mode 100644 index 4c993cde10..0000000000 --- a/en/appendices/migration-guides.rst +++ /dev/null @@ -1,13 +0,0 @@ -Migration Guides -################ - -Migration guides contain information regarding the new features introduced in -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 - ./phpunit10 From 3ca2bf713e770ddd9b701e74b8d6cb01eace5b62 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Mon, 4 Nov 2024 22:29:07 -0500 Subject: [PATCH 305/337] Go the other way instead. Retaining the top-level TOC is more important. --- en/appendices.rst | 12 +++--------- en/appendices/migration-guides.rst | 13 +++++++++++++ 2 files changed, 16 insertions(+), 9 deletions(-) create mode 100644 en/appendices/migration-guides.rst diff --git a/en/appendices.rst b/en/appendices.rst index 3c55fd4c20..d52292082c 100644 --- a/en/appendices.rst +++ b/en/appendices.rst @@ -4,16 +4,10 @@ Appendices Appendices contain information regarding the new features introduced in each version and the migration path between versions. -5.x Migration Guide -=================== - -.. toctree:: - :maxdepth: 1 +Migration Guides +================ - appendices/5-0-upgrade-guide - appendices/5-0-migration-guide - appendices/5-1-migration-guide - appendices/phpunit10 +:doc:`migration-guides` Backwards Compatibility Shimming ================================ diff --git a/en/appendices/migration-guides.rst b/en/appendices/migration-guides.rst new file mode 100644 index 0000000000..4c993cde10 --- /dev/null +++ b/en/appendices/migration-guides.rst @@ -0,0 +1,13 @@ +Migration Guides +################ + +Migration guides contain information regarding the new features introduced in +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 + ./phpunit10 From 8d15afbcfb9113b5c7c2606c31c71435dfab74d9 Mon Sep 17 00:00:00 2001 From: ADmad Date: Tue, 5 Nov 2024 17:51:43 +0530 Subject: [PATCH 306/337] Fix cross model event listener example --- en/development/testing.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index 59d85cd3f7..9f386e6a6b 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1830,11 +1830,15 @@ Expanding on the Orders example, say we have the following tables:: class CartsTable extends Table { - public function implementedEvents(): array + public function initialize() { - return [ - 'Model.Order.afterPlace' => 'removeFromCart' - ]; + // Models don't share the same event manager instance, + // so we need to use the global instance to listen to + // events from other models + \Cake\Event\EventManager::instance()->on( + 'Model.Order.afterPlace', + callable: [$this, 'removeFromCart'] + ); } public function removeFromCart(EventInterface $event): void From f5c54e26dd281a20578c341b07fd7954b74bc685 Mon Sep 17 00:00:00 2001 From: ADmad Date: Tue, 5 Nov 2024 17:56:49 +0530 Subject: [PATCH 307/337] Update references to defunct classes --- en/development/testing.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index 59d85cd3f7..eda7d27765 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -987,8 +987,6 @@ controller code looks like:: class ArticlesController extends AppController { - public $helpers = ['Form', 'Html']; - public function index($short = null) { if ($this->request->is('post')) { @@ -1114,10 +1112,10 @@ The state set by these helper methods is reset in the ``tearDown()`` method. .. versionadded:: 5.1.0 ``replaceRequest()`` was added. -Testing Actions Protected by CsrfComponent or SecurityComponent +Testing Actions Protected by CsrfMiddleware or FormProtectionComponent --------------------------------------------------------------- -When testing actions protected by either SecurityComponent or CsrfComponent you +When testing actions protected by either ``CsrfProtectionMiddleware`` or ``FormProtectionComponent`` you can enable automatic token generation to ensure your tests won't fail due to token mismatches:: @@ -1129,7 +1127,7 @@ token mismatches:: } It is also important to enable debug in tests that use tokens to prevent the -SecurityComponent from thinking the debug token is being used in a non-debug +``FormProtectionComponent`` from thinking the debug token is being used in a non-debug environment. When testing with other methods like ``requireSecure()`` you can use ``configRequest()`` to set the correct environment variables:: From 183e67df6958814d0ce0bdd7ed5d06500c03fb22 Mon Sep 17 00:00:00 2001 From: ADmad Date: Tue, 5 Nov 2024 18:03:25 +0530 Subject: [PATCH 308/337] Fix formatting --- en/development/testing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index eda7d27765..3f64acc774 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1113,7 +1113,7 @@ The state set by these helper methods is reset in the ``tearDown()`` method. ``replaceRequest()`` was added. Testing Actions Protected by CsrfMiddleware or FormProtectionComponent ---------------------------------------------------------------- +---------------------------------------------------------------------- When testing actions protected by either ``CsrfProtectionMiddleware`` or ``FormProtectionComponent`` you can enable automatic token generation to ensure your tests won't fail due to From 8a0c0d90bc4b82948c3981f905e6e7b1267a64d5 Mon Sep 17 00:00:00 2001 From: ADmad Date: Tue, 5 Nov 2024 18:05:05 +0530 Subject: [PATCH 309/337] Fix class name --- en/development/testing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/development/testing.rst b/en/development/testing.rst index 3f64acc774..b5037b611e 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1112,8 +1112,8 @@ The state set by these helper methods is reset in the ``tearDown()`` method. .. versionadded:: 5.1.0 ``replaceRequest()`` was added. -Testing Actions Protected by CsrfMiddleware or FormProtectionComponent ----------------------------------------------------------------------- +Testing Actions Protected by CsrfProtectionMiddleware or FormProtectionComponent +-------------------------------------------------------------------------------- When testing actions protected by either ``CsrfProtectionMiddleware`` or ``FormProtectionComponent`` you can enable automatic token generation to ensure your tests won't fail due to From d1333bd22c146b1c74b9e4838f36de8873313506 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Tue, 5 Nov 2024 11:13:04 -0500 Subject: [PATCH 310/337] Fix link --- en/appendices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/appendices.rst b/en/appendices.rst index d52292082c..ca1ddc4508 100644 --- a/en/appendices.rst +++ b/en/appendices.rst @@ -7,7 +7,7 @@ introduced in each version and the migration path between versions. Migration Guides ================ -:doc:`migration-guides` +:doc:`appendices/migration-guides` Backwards Compatibility Shimming ================================ From a37b28ccb277c74d4530a58dbbe1fdbc8fccf363 Mon Sep 17 00:00:00 2001 From: Ronald CARUCCI Date: Wed, 6 Nov 2024 21:21:27 +0100 Subject: [PATCH 311/337] Update rest page in French for CakePHP 5 --- fr/development/rest.rst | 181 ++++++++++++++++++---------------------- 1 file changed, 79 insertions(+), 102 deletions(-) diff --git a/fr/development/rest.rst b/fr/development/rest.rst index 4e9a83db81..91db7a31bc 100644 --- a/fr/development/rest.rst +++ b/fr/development/rest.rst @@ -7,37 +7,33 @@ Fournir un accès sans entrave à votre API du cœur peut aider à ce que votre plateforme soit acceptée, et permettre les mashups et une intégration facile avec les autres systèmes. -Alors que d'autres solutions existent, REST est un bon moyen de fournir -un accès à la logique que vous avez créée dans votre application. -C'est simple, habituellement basé sur XML (nous parlons de XML simple, rien -de semblable à une enveloppe SOAP), et dépend des headers HTTP pour la -direction. Exposer une API via REST dans CakePHP est simple. +CakePHP propose des méthodes pour exposer les actions de votre controller via +des méthodes HTTP et pour sérialiser les variables de vue en fonction de la +négociation du type de contenu. La négociation du type de contenu permet aux +clients de votre application d’envoyer des requêtes avec des données sérialisées +et de recevoir des réponses avec des données sérialisées via les en-têtes ``Accept`` +et ``Content-Type``, ou des extensions d’URL. Mise en place Simple ==================== -Le moyen le plus rapide pour démarrer avec REST est d'ajouter quelques lignes -pour configurer :ref:`resource routes ` dans votre fichier -config/routes.php. - -Une fois que le router a été configuré pour mapper les requêtes REST vers -certaines actions de controller, nous pouvons continuer et créer la logique -dans nos actions de controller. Un controller basique pourrait ressembler -à ceci:: +Pour commencer à ajouter une API REST à votre application, nous aurons d’abord +besoin d’un controller contenant les actions que nous voulons exposer en tant +qu’API. Un controller de base pourrait ressembler à ceci:: // src/Controller/RecipesController.php + use Cake\View\JsonView; + class RecipesController extends AppController { - - public function initialize(): void + public function viewClasses(): array { - parent::initialize(); - $this->loadComponent('RequestHandler'); + return [JsonView::class]; } public function index() { - $recipes = $this->Recipes->find('all'); + $recipes = $this->Recipes->find('all')->all(); $this->set('recipes', $recipes); $this->viewBuilder()->setOption('serialize', ['recipes']); } @@ -51,6 +47,7 @@ dans nos actions de controller. Un controller basique pourrait ressembler public function add() { + $this->request->allowMethod(['post', 'put']); $recipe = $this->Recipes->newEntity($this->request->getData()); if ($this->Recipes->save($recipe)) { $message = 'Saved'; @@ -66,14 +63,13 @@ dans nos actions de controller. Un controller basique pourrait ressembler public function edit($id) { + $this->request->allowMethod(['patch', 'post', 'put']); $recipe = $this->Recipes->get($id); - if ($this->request->is(['post', 'put'])) { - $recipe = $this->Recipes->patchEntity($recipe, $this->request->getData()); - if ($this->Recipes->save($recipe)) { - $message = 'Saved'; - } else { - $message = 'Error'; - } + $recipe = $this->Recipes->patchEntity($recipe, $this->request->getData()); + if ($this->Recipes->save($recipe)) { + $message = 'Saved'; + } else { + $message = 'Error'; } $this->set([ 'message' => $message, @@ -84,6 +80,7 @@ dans nos actions de controller. Un controller basique pourrait ressembler public function delete($id) { + $this->request->allowMethod(['delete']); $recipe = $this->Recipes->get($id); $message = 'Deleted'; if (!$this->Recipes->delete($recipe)) { @@ -94,83 +91,63 @@ dans nos actions de controller. Un controller basique pourrait ressembler } } -Les controllers RESTful utilisent souvent les extensions parsées pour servir -différentes views basées sur différents types de requête. Puisque nous gérons -les requêtes REST, nous ferons des views XML. Vous pouvez aussi faire des views -JSON en utilisant les :doc:`/views/json-and-xml-views` intégrées à CakePHP. En -utilisant :php:class:`XmlView` intégré, nous pouvons définir une option -``_serialize``. Cette option est utilisée pour définir les -variables de vue que ``XmlView`` doit sérialiser en XML. - -Si nous voulons modifier les données avant qu'elles soient converties en XML, -nous ne devons pas définir l'option ``_serialize``, et à la place -utiliser les fichiers de template. Nous plaçons les vues REST pour notre -RecipesController à l'intérieur de **templates/Recipes/xml**. Nous pouvons -aussi utiliser :php:class:`Xml` pour une sortie XML simple à mettre en place -dans ces vues. Voici à quoi notre vue index pourrait ressembler:: - - // templates/Recipes/xml/index.php - // Faire du formatage et de la manipulation sur le tableau - // $recipes. - $xml = Xml::fromArray(['response' => $recipes]); - echo $xml->asXML(); - -Quand vous servez le type de contenu spécifique en utilisant parseExtensions(), -CakePHP recherche automatiquement un helper de view qui matche le type. -Puisque nous utilisons le XML en type de contenu, il n'y a pas de helper intégré -cependant si vous en créez un, il va être automatiquement chargé pour notre -utilisation dans ces vues. - -Le XML rendu va finir par ressembler à ceci:: - - - - 234 - 2008-06-13 - 2008-06-14 - - 23423 - Billy - Bob - - - 245 - Yummy yummmy - - - ... - - -Créer la logique pour l'action edit est un tout petit peu plus compliqué. -Puisque vous fournissez une API qui sort du XML, c'est un choix naturel de -recevoir le XML en input. Ne vous inquiétez pas, les classes -:php:class:`Cake\\Controller\\Component\\RequestHandler` et -:php:class:`Cake\\Routing\\Router` vous facilitent les choses. Si une requête -POST ou PUT a un type de contenu XML, alors l'input est lancé à travers la -classe :php:class:`Xml` de CakePHP, et la representation en tableau des données -est assigné à `$this->request->data`. Avec cette fonctionnalité, la gestion -de XML et les données POST en parallèle est seamless: aucun changement n'est -nécessaire pour le code du controller ou du model. -Tout ce dont vous avez besoin devrait se trouver dans ``$this->request->getData()``. - -Accepter l'Input dans d'Autres Formats -====================================== - -Typiquement les applications REST ne sortent pas seulement du contenu dans des -formats de données alternatifs, elles acceptent aussi des données dans des -formats différents. Dans CakePHP, :php:class:`RequestHandlerComponent` facilite -ceci. Par défaut, elle va décoder toute donnée d'input JSON/XML entrante pour -des requêtes POST/PUT et fournir la version du tableau de ces données dans -`$this->request->data`. Vous pouvez aussi connecter avec des deserialisers -supplémentaires dans des formats alternatifs si vous avez besoin d'eux en -utilisant :php:meth:`RequestHandler::addInputType()` - -RESTful Routing -=============== - -Le Router de CakePHP fournit une interface pratique pour connecter des routes -pour les ressources RESTful. Consultez la section :ref:`resource-routes` pour -plus d'informations. +Dans notre ``RecipesController``, nous avons plusieurs actions qui définissent la logique +pour créer, modifier, visualiser et supprimer des recettes. Dans chacune de nos actions, +nous utilisons l’option ``serialize`` pour indiquer à CakePHP quelles variables de vue doivent +être sérialisées lors de la création des réponses API. Nous connecterons notre controller aux +URL de l’application avec le :ref:`resource-routes`:: + + // in config/routes.php + $routes->scope('/', function (RouteBuilder $routes): void { + $routes->setExtensions(['json']); + $routes->resources('Recipes'); + }); + +Ces routes permettront aux URL comme ``/recipes.json`` de renvoyer une réponse encodée en JSON. +Les clients pourront également faire une requête à ``/recipes`` avec l’en-tête +``Content-Type: application/json``. + +Encodage des données de réponse +=============================== + +Dans le controlleur ci-dessus, nous définissons une méthode ``viewClasses()``. Cette méthode +définit les vues dont votre controller dispose pour la négociation de contenu. Nous incluons +``JsonView`` de CakePHP qui permet des réponses basées sur JSON. Pour en savoir plus à ce sujet et +sur les vues basées sur XML, consultez :doc:`/views/json-and-xml-views`. Ceci est utilisé par +CakePHP pour sélectionner une classe de vue avec laquelle restituer une réponse REST. + +Ensuite, nous disposons de plusieurs méthodes qui exposent la logique de base pour créer, +modifier, afficher et supprimer des recettes. Dans chacune de nos actions, nous utilisons +l'option ``serialize`` pour indiquer à CakePHP quelles variables de vue doivent être sérialisées +lors des réponses API. + +Si nous souhaitons modifier les données avant qu'elles ne soient converties en JSON, +nous ne devons pas définir l'option de ``serialize``, mais plutôt utiliser des fichiers modèles. +Nous placerions les modèles REST pour notre RecipesController dans **templates/Recipes/json**. + +Voir :ref:`controller-viewclasses` pour plus d'informations sur la fonctionnalité de négociation +de réponse de CakePHP. + +Parsing des corps de requête +============================ + +La création de la logique de l'action de modification nécessite une autre étape. Parce +que nos ressources sont sérialisées au format JSON, il serait ergonomique si nos requêtes +contenaient également la représentation JSON. + +Dans notre classe ``Application``, assurez-vous que les éléments suivants sont présents:: + + $middlewareQueue->add(new BodyParserMiddleware()); + +Ce middleware utilisera l'en-tête ``content-type`` pour détecter le format des données +de requête et analyser les formats activés. Par défaut, seule l'analyse ``JSON`` est activée +par défaut. Vous pouvez activer la prise en charge XML en activant l'option du +constructeur XML. Lorsqu'une requête est effectuée avec un ``Content-Type`` ``application/json``, +CakePHP décodera les données de la requête et mettra à jour la requête afin +que ``$request->getData()`` contienne le corps analysé. + +Vous pouvez également câbler des désérialiseurs supplémentaires pour des formats alternatifs +si vous en avez besoin, en utilisant :php:meth:`BodyParserMiddleware::addParser()`. .. meta:: :title lang=fr: REST From 7998a083b9dd83c485766692efb030e8576440cd Mon Sep 17 00:00:00 2001 From: Ihor Sychevskyi Date: Fri, 8 Nov 2024 22:14:20 +0200 Subject: [PATCH 312/337] Update references to defunct classes (fr, ja, pt) (#7949) --------- Co-authored-by: Mark Story --- fr/development/testing.rst | 10 ++++------ ja/development/testing.rst | 10 ++++------ pt/development/testing.rst | 10 ++++------ 3 files changed, 12 insertions(+), 18 deletions(-) diff --git a/fr/development/testing.rst b/fr/development/testing.rst index 2bd4de489e..07316dc2df 100755 --- a/fr/development/testing.rst +++ b/fr/development/testing.rst @@ -1006,8 +1006,6 @@ correspondant. Le code du controller ressemble à ceci:: class ArticlesController extends AppController { - public $helpers = ['Form', 'Html']; - public function index($short = null) { if ($this->request->is('post')) { @@ -1211,10 +1209,10 @@ l'en-tête d'autorisation directement:: Vous pouvez utiliser la clé ``headers`` dans ``configRequest()`` pour configurer n'importe quelle autre en-tête HTTP dont vous auriez besoin pour cette action. -Tester les Actions Protégées par CsrfComponent ou SecurityComponent -------------------------------------------------------------------- +Tester les Actions Protégées par CsrfProtectionMiddleware ou FormProtectionComponent +------------------------------------------------------------------------------------ -Quand vous testez des actions protégées par CsrfComponent ou SecurityComponent, +Quand vous testez des actions protégées par ``CsrfProtectionMiddleware`` ou ``FormProtectionComponent``, vous pouvez activer la génération automatique de token pour vous assurer que vos tests ne vont pas échoué à cause d'un problème de token:: @@ -1226,7 +1224,7 @@ tests ne vont pas échoué à cause d'un problème de token:: } Il est aussi important d'activer le débogage dans les tests qui utilisent des -tokens pour éviter que le SecurityComponent ne pense que le token de débogage +tokens pour éviter que le ``FormProtectionComponent`` ne pense que le token de débogage est utilisé dans un environnement non-debug. Quand vous faites des tests avec d'autres méthodes comme ``requireSecure()``, vous pouvez utiliser ``configRequest()`` pour définir les bonnes variables d'environnement:: diff --git a/ja/development/testing.rst b/ja/development/testing.rst index 1be3a265ac..1556425fca 100644 --- a/ja/development/testing.rst +++ b/ja/development/testing.rst @@ -886,8 +886,6 @@ CakePHP では特別に ``IntegrationTestTrait`` トレイトを提供してい class ArticlesController extends AppController { - public $helpers = ['Form', 'Html']; - public function index($short = null) { if ($this->request->is('post')) { @@ -1084,10 +1082,10 @@ OAuth2 のようなその他の認証方法をテストしている場合、Auth ``configRequest()`` 内の headers キーは、アクションに必要な追加の HTTP ヘッダーを 設定するために使用されます。 -CsrfComponent や SecurityComponent で保護されたアクションのテスト ------------------------------------------------------------------ +CsrfProtectionMiddleware や FormProtectionComponent で保護されたアクションのテスト +---------------------------------------------------------------------------------- -SecurityComponent または CsrfComponent のいずれかで保護されたアクションをテストする場合、 +``CsrfProtectionMiddleware`` または ``FormProtectionComponent`` のいずれかで保護されたアクションをテストする場合、 テストがトークンのミスマッチで失敗しないように自動トークン生成を有効にすることができます。 :: public function testAdd(): void @@ -1097,7 +1095,7 @@ SecurityComponent または CsrfComponent のいずれかで保護されたア $this->post('/posts/add', ['title' => 'Exciting news!']); } -また、トークンを使用するテストで debug を有効にすることは重要です。SecurityComponent が +また、トークンを使用するテストで debug を有効にすることは重要です。``FormProtectionComponent`` が 「デバッグ用トークンがデバッグ以外の環境で使われている」と考えてしまうのを防ぐためです。 ``requireSecure()`` のような他のメソッドでテストした時は、適切な環境変数をセットするために ``configRequest()`` を利用できます。:: diff --git a/pt/development/testing.rst b/pt/development/testing.rst index 475964031d..b2502d4d71 100644 --- a/pt/development/testing.rst +++ b/pt/development/testing.rst @@ -800,8 +800,6 @@ controlador se parece com:: class ArticlesController extends AppController { - public $helpers = ['Form', 'Html']; - public function index($short = null) { if ($this->request->is('post')) { @@ -1001,10 +999,10 @@ cabeçalho de Autorização diretamente:: A chave de cabeçalhos em ``configRequest()`` pode ser usada para configurar qualquer cabeçalho HTTP adicional necessário para uma ação. -Testando Ações Protegidas por CsrfComponent ou SecurityComponent ----------------------------------------------------------------- +Testando Ações Protegidas por CsrfProtectionMiddleware ou FormProtectionComponent +--------------------------------------------------------------------------------- -Ao testar ações protegidas por SecurityComponent ou CsrfComponent, você pode ativar +Ao testar ações protegidas por ``CsrfProtectionMiddleware`` ou ``FormProtectionComponent``, você pode ativar a geração automática de token para garantir que seus testes não falhem devido a incompatibilidades de token:: @@ -1016,7 +1014,7 @@ incompatibilidades de token:: } Também é importante habilitar a depuração em testes que usam tokens para impedir -que o SecurityComponent pense que o token de depuração está sendo usado em um +que o ``FormProtectionComponent`` pense que o token de depuração está sendo usado em um ambiente sem depuração. Ao testar com outros métodos como ``requireSecure()``, você pode usar ``configRequest()`` para definir as variáveis de ambiente corretas:: From 0e449f8f763b0e6ff4bd21217030dc8c3ae5c1ae Mon Sep 17 00:00:00 2001 From: Corey Taylor Date: Mon, 4 Nov 2024 02:36:42 -0600 Subject: [PATCH 313/337] Upgrade to sphinx 8 --- en/console-commands/option-parsers.rst | 4 +- en/controllers.rst | 8 +- en/controllers/components/form-protection.rst | 4 +- en/controllers/request-response.rst | 46 ++++---- en/core-libraries/caching.rst | 14 +-- en/core-libraries/collections.rst | 2 +- en/core-libraries/form.rst | 2 +- .../global-constants-and-functions.rst | 2 +- en/core-libraries/logging.rst | 6 +- en/core-libraries/number.rst | 4 +- en/core-libraries/security.rst | 2 +- en/core-libraries/text.rst | 2 +- en/core-libraries/xml.rst | 2 +- en/development/configuration.rst | 4 +- en/development/debugging.rst | 4 +- en/development/errors.rst | 8 +- en/development/routing.rst | 4 +- en/development/sessions.rst | 2 +- en/development/testing.rst | 4 +- en/orm/database-basics.rst | 8 +- en/orm/deleting-data.rst | 6 +- en/orm/query-builder.rst | 6 +- en/orm/saving-data.rst | 4 +- .../cms/articles-controller.rst | 2 +- en/views.rst | 2 +- en/views/helpers/form.rst | 26 ++--- en/views/helpers/html.rst | 2 +- en/views/helpers/time.rst | 2 +- es/console-commands/option-parsers.rst | 4 +- es/controllers.rst | 8 +- es/controllers/request-response.rst | 44 ++++---- es/core-libraries/caching.rst | 14 +-- es/core-libraries/logging.rst | 6 +- es/core-libraries/number.rst | 4 +- es/development/debugging.rst | 4 +- es/development/errors.rst | 8 +- es/development/rest.rst | 2 +- es/development/routing.rst | 2 +- es/development/sessions.rst | 2 +- es/orm.rst | 2 +- es/views.rst | 2 +- fr/console-commands/option-parsers.rst | 4 +- fr/controllers.rst | 8 +- fr/controllers/components/form-protection.rst | 4 +- fr/controllers/components/security.rst | 6 +- fr/controllers/request-response.rst | 56 ++++----- fr/core-libraries/caching.rst | 14 +-- fr/core-libraries/form.rst | 2 +- .../global-constants-and-functions.rst | 2 +- fr/core-libraries/hash.rst | 5 +- fr/core-libraries/logging.rst | 6 +- fr/core-libraries/number.rst | 4 +- fr/core-libraries/security.rst | 2 +- fr/core-libraries/validation.rst | 2 +- fr/core-libraries/xml.rst | 2 +- fr/development/debugging.rst | 4 +- fr/development/errors.rst | 8 +- fr/development/rest.rst | 60 +++++----- fr/development/routing.rst | 4 +- fr/development/sessions.rst | 2 +- fr/development/testing.rst | 4 +- fr/orm/database-basics.rst | 6 +- fr/orm/deleting-data.rst | 6 +- fr/orm/query-builder.rst | 6 +- fr/orm/saving-data.rst | 4 +- fr/tutorials-and-examples/blog/part-two.rst | 2 +- .../cms/articles-controller.rst | 2 +- fr/views/helpers/form.rst | 26 ++--- fr/views/helpers/html.rst | 6 +- fr/views/helpers/time.rst | 2 +- fr/views/themes.rst | 2 +- ja/console-commands/option-parsers.rst | 4 +- ja/controllers.rst | 10 +- ja/controllers/components/form-protection.rst | 4 +- ja/controllers/components/security.rst | 8 +- ja/controllers/request-response.rst | 56 ++++----- ja/core-libraries/caching.rst | 12 +- ja/core-libraries/collections.rst | 2 +- ja/core-libraries/form.rst | 2 +- .../global-constants-and-functions.rst | 2 +- ja/core-libraries/logging.rst | 6 +- ja/core-libraries/number.rst | 4 +- ja/core-libraries/security.rst | 2 +- ja/core-libraries/text.rst | 2 +- ja/core-libraries/xml.rst | 2 +- ja/development/debugging.rst | 4 +- ja/development/dispatch-filters.rst | 6 +- ja/development/errors.rst | 10 +- ja/development/rest.rst | 2 +- ja/development/routing.rst | 2 +- ja/development/sessions.rst | 2 +- ja/development/testing.rst | 2 +- ja/orm/database-basics.rst | 8 +- ja/orm/deleting-data.rst | 6 +- ja/orm/query-builder.rst | 6 +- ja/orm/saving-data.rst | 4 +- ja/tutorials-and-examples/blog/part-two.rst | 2 +- .../cms/articles-controller.rst | 2 +- ja/views.rst | 2 +- ja/views/helpers/form.rst | 26 ++--- ja/views/helpers/html.rst | 4 +- ja/views/helpers/time.rst | 2 +- ja/views/themes.rst | 2 +- pt/console-and-shells.rst | 4 +- pt/controllers.rst | 8 +- pt/controllers/components/security.rst | 106 +++++++++--------- pt/controllers/request-response.rst | 38 +++---- pt/core-libraries/caching.rst | 12 +- pt/core-libraries/collections.rst | 2 +- pt/core-libraries/form.rst | 2 +- .../global-constants-and-functions.rst | 2 +- pt/core-libraries/number.rst | 4 +- pt/core-libraries/security.rst | 2 +- pt/development/debugging.rst | 4 +- pt/development/errors.rst | 8 +- pt/development/rest.rst | 2 +- pt/development/routing.rst | 2 +- pt/development/sessions.rst | 2 +- pt/development/testing.rst | 4 +- pt/orm.rst | 2 +- pt/orm/database-basics.rst | 8 +- pt/orm/deleting-data.rst | 6 +- pt/orm/query-builder.rst | 8 +- pt/orm/saving-data.rst | 4 +- pt/views.rst | 2 +- pt/views/themes.rst | 2 +- requirements.txt | 4 +- 127 files changed, 496 insertions(+), 495 deletions(-) diff --git a/en/console-commands/option-parsers.rst b/en/console-commands/option-parsers.rst index ce25c19e99..be19eb79a7 100644 --- a/en/console-commands/option-parsers.rst +++ b/en/console-commands/option-parsers.rst @@ -197,8 +197,8 @@ Building a ConsoleOptionParser from an Array Option parsers can also be defined as arrays. Within the array, you can define keys for ``arguments``, ``options``, ``description`` and ``epilog``. The values for arguments, and options, should follow the format that -:php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` and -:php:func:`Cake\\Console\\ConsoleOptionParser::addOptions()` use. You can also +:php:func:`\\Cake\\Console\\ConsoleOptionParser::addArguments()` and +:php:func:`\\Cake\\Console\\ConsoleOptionParser::addOptions()` use. You can also use ``buildFromArray`` on its own, to build an option parser:: public function getOptionParser() diff --git a/en/controllers.rst b/en/controllers.rst index 4330e32740..1e45f36e8e 100644 --- a/en/controllers.rst +++ b/en/controllers.rst @@ -39,7 +39,7 @@ The App Controller As stated in the introduction, the ``AppController`` class is the parent class to all of your application's controllers. ``AppController`` itself extends the -:php:class:`Cake\\Controller\\Controller` class included in CakePHP. +:php:class:`\\Cake\\Controller\\Controller` class included in CakePHP. ``AppController`` is defined in **src/Controller/AppController.php** as follows:: @@ -77,7 +77,7 @@ Request Flow ============ When a request is made to a CakePHP application, CakePHP's -:php:class:`Cake\\Routing\\Router` and :php:class:`Cake\\Routing\\Dispatcher` +:php:class:`\\Cake\\Routing\\Router` and :php:class:`\\Cake\\Routing\\Dispatcher` classes use :ref:`routes-configuration` to find and create the correct controller instance. The request data is encapsulated in a request object. CakePHP puts all of the important request information into the ``$this->request`` @@ -130,7 +130,7 @@ once a controller action has completed, CakePHP will handle rendering and delivering the View. If for some reason you'd like to skip the default behavior, you can return a -:php:class:`Cake\\Http\\Response` object from the action with the fully +:php:class:`\\Cake\\Http\\Response` object from the action with the fully created response. In order for you to use a controller effectively in your own application, we'll @@ -548,7 +548,7 @@ methods are implemented by your controllers Called during the ``Controller.beforeRender`` event which occurs after controller action logic, but before the view is rendered. This callback is not used often, but may be needed if you are calling - :php:meth:`~Cake\\Controller\\Controller::render()` manually before the end + :php:meth:`\\Cake\\Controller\\Controller::render()` manually before the end of a given action. .. php:method:: afterFilter(EventInterface $event) diff --git a/en/controllers/components/form-protection.rst b/en/controllers/components/form-protection.rst index 3927406401..9ff4acc8ee 100644 --- a/en/controllers/components/form-protection.rst +++ b/en/controllers/components/form-protection.rst @@ -19,8 +19,8 @@ in your ``initialize()`` method. your forms. In addition, you must **not** override any of the fields' "name" attributes. The FormProtection Component looks for certain indicators that are created and managed by the FormHelper (especially those created in - :php:meth:`~Cake\\View\\Helper\\FormHelper::create()` and - :php:meth:`~Cake\\View\\Helper\\FormHelper::end()`). Dynamically altering + :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()` and + :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()`). Dynamically altering the fields that are submitted in a POST request, such as disabling, deleting or creating new fields via JavaScript, is likely to cause the form token validation to fail. diff --git a/en/controllers/request-response.rst b/en/controllers/request-response.rst index bb85721d99..b0a7e8ca50 100644 --- a/en/controllers/request-response.rst +++ b/en/controllers/request-response.rst @@ -133,7 +133,7 @@ Request Body Data .. php:method:: getData($name, $default = null) All POST data normally available through PHP's ``$_POST`` global variable can be -accessed using :php:meth:`Cake\\Http\\ServerRequest::getData()`. For example:: +accessed using :php:meth:`\\Cake\\Http\\ServerRequest::getData()`. For example:: // An input with a name attribute equal to 'title' is accessible at $title = $this->request->getData('title'); @@ -160,7 +160,7 @@ If you want to access all the data parameters you can use File Uploads ------------ -Uploaded files can be accessed through the request body data, using the :php:meth:`Cake\\Http\\ServerRequest::getData()` +Uploaded files can be accessed through the request body data, using the :php:meth:`\\Cake\\Http\\ServerRequest::getData()` method described above. For example, a file from an input element with a name attribute of ``attachment``, can be accessed like this:: @@ -195,11 +195,11 @@ origins, which makes testing file uploads possible. .. php:method:: getUploadedFile($path) Returns the uploaded file at a specific path. The path uses the same dot syntax as the -:php:meth:`Cake\\Http\\ServerRequest::getData()` method:: +:php:meth:`\\Cake\\Http\\ServerRequest::getData()` method:: $attachment = $this->request->getUploadedFile('attachment'); -Unlike :php:meth:`Cake\\Http\\ServerRequest::getData()`, :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` would +Unlike :php:meth:`\\Cake\\Http\\ServerRequest::getData()`, :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` would only return data when an actual file upload exists for the given path, if there is regular, non-file request body data present at the given path, then this method will return ``null``, just like it would for any non-existent path. @@ -244,9 +244,9 @@ replace all possibly existing uploaded files:: .. note:: Uploaded files that have been added to the request via this method, will *not* be available in the request body - data, ie you cannot retrieve them via :php:meth:`Cake\\Http\\ServerRequest::getData()`! If you need them in the - request data (too), then you have to set them via :php:meth:`Cake\\Http\\ServerRequest::withData()` or - :php:meth:`Cake\\Http\\ServerRequest::withParsedBody()`. + data, ie you cannot retrieve them via :php:meth:`\\Cake\\Http\\ServerRequest::getData()`! If you need them in the + request data (too), then you have to set them via :php:meth:`\\Cake\\Http\\ServerRequest::withData()` or + :php:meth:`\\Cake\\Http\\ServerRequest::withParsedBody()`. PUT, PATCH or DELETE Data ------------------------- @@ -341,7 +341,7 @@ conditions, as well as inspect other application specific request criteria:: $isPost = $this->request->is('post'); You can also extend the request detectors that are available, by using -:php:meth:`Cake\\Http\\ServerRequest::addDetector()` to create new kinds of +:php:meth:`\\Cake\\Http\\ServerRequest::addDetector()` to create new kinds of detectors. There are different types of detectors that you can create: * Environment value comparison - Compares a value fetched from :php:func:`env()` @@ -431,9 +431,9 @@ There are several built-in detectors that you can use: 'application/xml' or 'text/xml'. ``ServerRequest`` also includes methods like -:php:meth:`Cake\\Http\\ServerRequest::domain()`, -:php:meth:`Cake\\Http\\ServerRequest::subdomains()` and -:php:meth:`Cake\\Http\\ServerRequest::host()` to make applications that use +:php:meth:`\\Cake\\Http\\ServerRequest::domain()`, +:php:meth:`\\Cake\\Http\\ServerRequest::subdomains()` and +:php:meth:`\\Cake\\Http\\ServerRequest::host()` to make applications that use subdomains simpler. Session Data @@ -602,7 +602,7 @@ Request cookies can be read through a number of methods:: // Get a CookieCollection instance $cookies = $this->request->getCookieCollection() -See the :php:class:`Cake\\Http\\Cookie\\CookieCollection` documentation for how +See the :php:class:`\\Cake\\Http\\Cookie\\CookieCollection` documentation for how to work with cookie collection. @@ -645,7 +645,7 @@ Response .. php:class:: Response -:php:class:`Cake\\Http\\Response` is the default response class in CakePHP. +:php:class:`\\Cake\\Http\\Response` is the default response class in CakePHP. It encapsulates a number of features and functionality for generating HTTP responses in your application. It also assists in testing, as it can be mocked/stubbed allowing you to inspect headers that will be sent. @@ -664,7 +664,7 @@ Dealing with Content Types .. php:method:: withType($contentType = null) You can control the Content-Type of your application's responses with -:php:meth:`Cake\\Http\\Response::withType()`. If your application needs to deal +:php:meth:`\\Cake\\Http\\Response::withType()`. If your application needs to deal with content types that are not built into Response, you can map them with ``setTypeMap()`` as well:: @@ -686,7 +686,7 @@ Sending Files .. php:method:: withFile(string $path, array $options = []) There are times when you want to send files as responses for your requests. -You can accomplish that by using :php:meth:`Cake\\Http\\Response::withFile()`:: +You can accomplish that by using :php:meth:`\\Cake\\Http\\Response::withFile()`:: public function sendFile($id) { @@ -700,8 +700,8 @@ You can accomplish that by using :php:meth:`Cake\\Http\\Response::withFile()`:: As shown in the above example, you must pass the file path to the method. CakePHP will send a proper content type header if it's a known file type listed in `Cake\\Http\\Response::$_mimeTypes`. You can add new types prior to calling -:php:meth:`Cake\\Http\\Response::withFile()` by using the -:php:meth:`Cake\\Http\\Response::withType()` method. +:php:meth:`\\Cake\\Http\\Response::withFile()` by using the +:php:meth:`\\Cake\\Http\\Response::withType()` method. If you want, you can also force a file to be downloaded instead of displayed in the browser by specifying the options:: @@ -749,7 +749,7 @@ Setting Headers .. php:method:: withHeader($header, $value) -Setting headers is done with the :php:meth:`Cake\\Http\\Response::withHeader()` +Setting headers is done with the :php:meth:`\\Cake\\Http\\Response::withHeader()` method. Like all of the PSR-7 interface methods, this method returns a *new* instance with the new header:: @@ -767,7 +767,7 @@ Headers are not sent when set. Instead, they are held until the response is emitted by ``Cake\Http\Server``. You can now use the convenience method -:php:meth:`Cake\\Http\\Response::withLocation()` to directly set or get the +:php:meth:`\\Cake\\Http\\Response::withLocation()` to directly set or get the redirect location header. Setting the Body @@ -833,7 +833,7 @@ Interacting with Browser Caching .. php:method:: withDisabledCache() You sometimes need to force browsers not to cache the results of a controller -action. :php:meth:`Cake\\Http\\Response::withDisabledCache()` is intended for just +action. :php:meth:`\\Cake\\Http\\Response::withDisabledCache()` is intended for just that:: public function index() @@ -850,7 +850,7 @@ that:: .. php:method:: withCache($since, $time = '+1 day') You can also tell clients that you want them to cache responses. By using -:php:meth:`Cake\\Http\\Response::withCache()`:: +:php:meth:`\\Cake\\Http\\Response::withCache()`:: public function index() { @@ -878,7 +878,7 @@ Rather than forcing you to code the logic for caching and for invalidating (refreshing) it once the data has changed, HTTP uses two models, expiration and validation, which usually are much simpler to use. -Apart from using :php:meth:`Cake\\Http\\Response::withCache()`, you can also use +Apart from using :php:meth:`\\Cake\\Http\\Response::withCache()`, you can also use many other methods to fine-tune HTTP cache headers to take advantage of browser or reverse proxy caching. @@ -1040,7 +1040,7 @@ the response content, and sends the `304 Not Modified` header:: Setting Cookies --------------- -Cookies can be added to response using either an array or a :php:class:`Cake\\Http\\Cookie\\Cookie` +Cookies can be added to response using either an array or a :php:class:`\\Cake\\Http\\Cookie\\Cookie` object:: use Cake\Http\Cookie\Cookie; diff --git a/en/core-libraries/caching.rst b/en/core-libraries/caching.rst index 27f787acb9..bacfd60ff1 100644 --- a/en/core-libraries/caching.rst +++ b/en/core-libraries/caching.rst @@ -36,7 +36,7 @@ build your own backend. The built-in caching engines are: operations. Regardless of the CacheEngine you choose to use, your application interacts with -:php:class:`Cake\\Cache\\Cache`. +:php:class:`\\Cake\\Cache\\Cache`. .. _cache-configuration: @@ -110,8 +110,8 @@ You can also configure Cache engines at runtime:: Cache::setConfig('other', $object); The name of these engine configurations ('short' and 'long') are used as the ``$config`` -parameter for :php:meth:`Cake\\Cache\\Cache::write()` and -:php:meth:`Cake\\Cache\\Cache::read()`. When configuring cache engines you can +parameter for :php:meth:`\\Cake\\Cache\\Cache::write()` and +:php:meth:`\\Cake\\Cache\\Cache::read()`. When configuring cache engines you can refer to the class name using the following syntaxes:: // Short name (in App\ or Cake namespaces) @@ -243,8 +243,8 @@ Removing Configured Cache Engines .. php:staticmethod:: drop($key) Once a configuration is created you cannot change it. Instead you should drop -the configuration and re-create it using :php:meth:`Cake\\Cache\\Cache::drop()` and -:php:meth:`Cake\\Cache\\Cache::setConfig()`. Dropping a cache engine will remove +the configuration and re-create it using :php:meth:`\\Cake\\Cache\\Cache::drop()` and +:php:meth:`\\Cake\\Cache\\Cache::setConfig()`. Dropping a cache engine will remove the config and destroy the adapter if it was constructed. Writing to a Cache @@ -488,7 +488,7 @@ Using Cache to Store Common Query Results You can greatly improve the performance of your application by putting results that infrequently change, or that are subject to heavy reads into the cache. A perfect example of this are the results from -:php:meth:`Cake\\ORM\\Table::find()`. The Query object allows you to cache +:php:meth:`\\Cake\\ORM\\Table::find()`. The Query object allows you to cache results using the ``cache()`` method. See the :ref:`caching-query-results` section for more information. @@ -594,7 +594,7 @@ dot syntax:: // ... ]); -Custom Cache engines must extend :php:class:`Cake\\Cache\\CacheEngine` which +Custom Cache engines must extend :php:class:`\\Cake\\Cache\\CacheEngine` which defines a number of abstract methods as well as provides a few initialization methods. diff --git a/en/core-libraries/collections.rst b/en/core-libraries/collections.rst index f7b57deb70..15565b3334 100644 --- a/en/core-libraries/collections.rst +++ b/en/core-libraries/collections.rst @@ -169,7 +169,7 @@ This last example uses ``toList()`` unlike other examples, which is important when we're getting results with possibly duplicate keys. By using ``toList()`` we'll be guaranteed to get all values even if there are duplicate keys. -Unlike :php:meth:`Cake\\Utility\\Hash::extract()` this method only supports the +Unlike :php:meth:`\\Cake\\Utility\\Hash::extract()` this method only supports the ``{*}`` wildcard. All other wildcard and attributes matchers are not supported. .. php:method:: combine($keyPath, $valuePath, $groupPath = null) diff --git a/en/core-libraries/form.rst b/en/core-libraries/form.rst index d6c8d4c48f..a830c34e9f 100644 --- a/en/core-libraries/form.rst +++ b/en/core-libraries/form.rst @@ -53,7 +53,7 @@ In the above example we see the 3 hook methods that forms provide: * ``_buildSchema`` is used to define the schema data that is used by FormHelper to create an HTML form. You can define field type, length, and precision. -* ``validationDefault`` Gets a :php:class:`Cake\\Validation\\Validator` instance +* ``validationDefault`` Gets a :php:class:`\\Cake\\Validation\\Validator` instance that you can attach validators to. * ``_execute`` lets you define the behavior you want to happen when ``execute()`` is called and the data is valid. diff --git a/en/core-libraries/global-constants-and-functions.rst b/en/core-libraries/global-constants-and-functions.rst index 2ff14eb213..63fff1866d 100644 --- a/en/core-libraries/global-constants-and-functions.rst +++ b/en/core-libraries/global-constants-and-functions.rst @@ -105,7 +105,7 @@ aliases for *all* functions listed below. .. php:function:: collection(mixed $items) - Convenience wrapper for instantiating a new :php:class:`Cake\\Collection\\Collection` + Convenience wrapper for instantiating a new :php:class:`\\Cake\\Collection\\Collection` object, wrapping the passed argument. The ``$items`` parameter takes either a ``Traversable`` object or an array. diff --git a/en/core-libraries/logging.rst b/en/core-libraries/logging.rst index 0326d1f264..0c1fff37cb 100644 --- a/en/core-libraries/logging.rst +++ b/en/core-libraries/logging.rst @@ -25,7 +25,7 @@ Logging Configuration Configuring ``Log`` should be done during your application's bootstrap phase. The **config/app.php** file is intended for just this. You can define as many or as few loggers as your application needs. Loggers should be -configured using :php:class:`Cake\\Log\\Log`. An example would be:: +configured using :php:class:`\\Cake\\Log\\Log`. An example would be:: use Cake\Log\Engine\FileLog; use Cake\Log\Log; @@ -97,7 +97,7 @@ Writing to Logs =============== Writing to the log files can be done in two different ways. The first -is to use the static :php:meth:`Cake\\Log\\Log::write()` method:: +is to use the static :php:meth:`\\Cake\\Log\\Log::write()` method:: Log::write('debug', 'Something did not work'); @@ -109,7 +109,7 @@ class using the ``LogTrait``. Calling ``log()`` will internally call $this->log('Something did not work!', 'debug'); All configured log streams are written to sequentially each time -:php:meth:`Cake\\Log\\Log::write()` is called. If you have not configured any +:php:meth:`\\Cake\\Log\\Log::write()` is called. If you have not configured any logging engines ``log()`` will return ``false`` and no log messages will be written. diff --git a/en/core-libraries/number.rst b/en/core-libraries/number.rst index f59429a03f..4cdcba73ee 100644 --- a/en/core-libraries/number.rst +++ b/en/core-libraries/number.rst @@ -109,7 +109,7 @@ Setting the Default Currency .. php:method:: setDefaultCurrency($currency) Setter for the default currency. This removes the need to always pass the -currency to :php:meth:`Cake\\I18n\\Number::currency()` and change all +currency to :php:meth:`\\Cake\\I18n\\Number::currency()` and change all currency outputs by setting other default. If ``$currency`` is set to ``null``, it will clear the currently stored value. @@ -152,7 +152,7 @@ Formatting Percentages | | multiplied by 100. Useful for decimal percentages. | +---------------------+----------------------------------------------------+ -Like :php:meth:`Cake\\I18n\\Number::precision()`, this method formats a number +Like :php:meth:`\\Cake\\I18n\\Number::precision()`, this method formats a number according to the supplied precision (where numbers are rounded to meet the given precision). This method also expresses the number as a percentage and appends the output with a percent sign. :: diff --git a/en/core-libraries/security.rst b/en/core-libraries/security.rst index d1f1524087..dd16880002 100644 --- a/en/core-libraries/security.rst +++ b/en/core-libraries/security.rst @@ -31,7 +31,7 @@ An example use would be:: If you do not supply an HMAC salt, the value of ``Security::getSalt()`` will be used. Encrypted values can be decrypted using -:php:meth:`Cake\\Utility\\Security::decrypt()`. +:php:meth:`\\Cake\\Utility\\Security::decrypt()`. This method should **never** be used to store passwords. diff --git a/en/core-libraries/text.rst b/en/core-libraries/text.rst index a8f2748524..16c60c3a30 100644 --- a/en/core-libraries/text.rst +++ b/en/core-libraries/text.rst @@ -9,7 +9,7 @@ The Text class includes convenience methods for creating and manipulating strings and is normally accessed statically. Example: ``Text::uuid()``. -If you need :php:class:`Cake\\View\\Helper\\TextHelper` functionalities outside +If you need :php:class:`\\Cake\\View\\Helper\\TextHelper` functionalities outside of a ``View``, use the ``Text`` class:: namespace App\Controller; diff --git a/en/core-libraries/xml.rst b/en/core-libraries/xml.rst index f0681b44c7..8debe215c5 100644 --- a/en/core-libraries/xml.rst +++ b/en/core-libraries/xml.rst @@ -72,7 +72,7 @@ can be enabled with the ``loadEntities`` and ``parseHuge`` options respectively. Transforming a XML String in Array ================================== -.. php:staticmethod:: toArray($obj); +.. php:staticmethod:: toArray($obj) Converting XML strings into arrays is simple with the Xml class as well. By default you'll get a SimpleXml object back:: diff --git a/en/development/configuration.rst b/en/development/configuration.rst index 736e00f838..23e54995e2 100644 --- a/en/development/configuration.rst +++ b/en/development/configuration.rst @@ -362,7 +362,7 @@ If ``$key`` is left null, all values in Configure will be returned. .. php:staticmethod:: readOrFail($key) -Reads configuration data just like :php:meth:`Cake\\Core\\Configure::read` +Reads configuration data just like :php:meth:`\\Cake\\Core\\Configure::read()` but expects to find a key/value pair. In case the requested pair does not exist, a :php:class:`RuntimeException` will be thrown:: @@ -402,7 +402,7 @@ combine reading and deleting values in a single operation. .. php:staticmethod:: consumeOrFail($key) -Consumes configuration data just like :php:meth:`Cake\\Core\\Configure::consume` +Consumes configuration data just like :php:meth:`\\Cake\\Core\\Configure::consume()` but expects to find a key/value pair. In case the requested pair does not exist, a :php:class:`RuntimeException` will be thrown:: diff --git a/en/development/debugging.rst b/en/development/debugging.rst index 5a2161a52b..f257a96815 100644 --- a/en/development/debugging.rst +++ b/en/development/debugging.rst @@ -201,7 +201,7 @@ Using Logging to Debug ====================== Logging messages is another good way to debug applications, and you can use -:php:class:`Cake\\Log\\Log` to do logging in your application. All objects that +:php:class:`\\Cake\\Log\\Log` to do logging in your application. All objects that use ``LogTrait`` have an instance method ``log()`` which can be used to log messages:: @@ -209,7 +209,7 @@ to log messages:: The above would write ``Got here`` into the debug log. You can use log entries to help debug methods that involve redirects or complicated loops. You can also -use :php:meth:`Cake\\Log\\Log::write()` to write log messages. This method can be called +use :php:meth:`\\Cake\\Log\\Log::write()` to write log messages. This method can be called statically anywhere in your application one Log has been loaded:: // At the top of the file you want to log in. diff --git a/en/development/errors.rst b/en/development/errors.rst index 04385d0e7c..513af3e595 100644 --- a/en/development/errors.rst +++ b/en/development/errors.rst @@ -27,7 +27,7 @@ options are supported: exceptions. If you choose a custom class you should place the file for that class in **src/Error**. This class needs to implement a ``render()`` method. * ``log`` - bool - When ``true``, exceptions + their stack traces will be - logged to :php:class:`Cake\\Log\\Log`. + logged to :php:class:`\\Cake\\Log\\Log`. * ``skipLog`` - array - An array of exception classnames that should not be logged. This is useful to remove NotFoundExceptions or other common, but uninteresting log messages. @@ -356,7 +356,7 @@ Logging Exceptions Using the built-in exception handling, you can log all the exceptions that are dealt with by ErrorTrap by setting the ``log`` option to ``true`` in your **config/app.php**. Enabling this will log every exception to -:php:class:`Cake\\Log\\Log` and the configured loggers. +:php:class:`\\Cake\\Log\\Log` and the configured loggers. .. note:: @@ -586,8 +586,8 @@ In addition, CakePHP uses the following exceptions: .. php:exception:: PersistenceFailedException :nocontentsentry: - An entity couldn't be saved/deleted while using :php:meth:`Cake\\ORM\\Table::saveOrFail()` or - :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. + An entity couldn't be saved/deleted while using :php:meth:`\\Cake\\ORM\\Table::saveOrFail()` or + :php:meth:`\\Cake\\ORM\\Table::deleteOrFail()`. .. php:namespace:: Cake\Datasource\Exception diff --git a/en/development/routing.rst b/en/development/routing.rst index 3faeffd7e2..c8100e2e08 100644 --- a/en/development/routing.rst +++ b/en/development/routing.rst @@ -638,7 +638,7 @@ the ``$options`` argument:: }); Note the additional route parameters will be added to all the connected routes defined -inside the prefix block. You will need to use all the parameters in the url array to +inside the prefix block. You will need to use all the parameters in the url array to build the route later, if you don't use them you'll get a ``MissingRouteException``. Multi word prefixes are by default converted using dasherize inflection, ie ``MyPrefix`` @@ -1581,7 +1581,7 @@ requests and handle reverse routing. Route classes have a few conventions: * Route classes are expected to be found in the ``Routing\\Route`` namespace of your application or plugin. -* Route classes should extend :php:class:`Cake\\Routing\\Route\\Route`. +* Route classes should extend :php:class:`\\Cake\\Routing\\Route\\Route`. * Route classes should implement one or both of ``match()`` and/or ``parse()``. The ``parse()`` method is used to parse an incoming URL. It should generate an diff --git a/en/development/sessions.rst b/en/development/sessions.rst index b15c464b34..1255557485 100644 --- a/en/development/sessions.rst +++ b/en/development/sessions.rst @@ -326,7 +326,7 @@ something like:: Our class extends the built-in ``DatabaseSession`` so we don't have to duplicate all of its logic and behavior. We wrap each operation with -a :php:class:`Cake\\Cache\\Cache` operation. This lets us fetch sessions from +a :php:class:`\\Cake\\Cache\\Cache` operation. This lets us fetch sessions from the fast cache, and not have to worry about what happens when we fill the cache. In **config/app.php** make the session block look like:: diff --git a/en/development/testing.rst b/en/development/testing.rst index 1a065c12ab..781a6f7065 100644 --- a/en/development/testing.rst +++ b/en/development/testing.rst @@ -1274,8 +1274,8 @@ In order to simulate exactly how the uploaded file objects would be present on a regular request, you not only need to pass them in the request data, but you also need to pass them to the test request configuration via the ``files`` option. It's not technically necessary though unless your code accesses uploaded files via the -:php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` or -:php:meth:`Cake\\Http\\ServerRequest::getUploadedFiles()` methods. +:php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` or +:php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFiles()` methods. Let's assume articles have a teaser image, and a ``Articles hasMany Attachments`` association, the form would look like something like this accordingly, where one diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index dd971ba8e1..1a0732bbbe 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -306,7 +306,7 @@ Accessing Connections .. php:staticmethod:: get($name) Once configured connections can be fetched using -:php:meth:`Cake\\Datasource\\ConnectionManager::get()`. This method will +:php:meth:`\\Cake\\Datasource\\ConnectionManager::get()`. This method will construct and load a connection if it has not been built before, or return the existing known connection:: @@ -384,7 +384,7 @@ binary Maps to the ``BLOB`` or ``BYTEA`` type provided by the database. date Maps to a native ``DATE`` column type. The return value of this column - type is :php:class:`Cake\\I18n\\Date` which emulates the date related + type is :php:class:`\\Cake\\I18n\\Date` which emulates the date related methods of PHP's ``DateTime`` class. datetime See :ref:`datetime-type`. @@ -432,7 +432,7 @@ DateTime Type Maps to a native ``DATETIME`` column type. In PostgreSQL and SQL Server this turns into a ``TIMESTAMP`` type. The default return value of this column type is -:php:class:`Cake\\I18n\\DateTime` which extends `Chronos +:php:class:`\\Cake\\I18n\\DateTime` which extends `Chronos `_ and the native ``DateTimeImmutable``. .. php:method:: setTimezone(string|\DateTimeZone|null $timezone) @@ -970,7 +970,7 @@ Query logging can be enabled when configuring your connection by setting the ``log`` option to ``true``. When query logging is enabled, queries will be logged to -:php:class:`Cake\\Log\\Log` using the 'debug' level, and the 'queriesLog' scope. +:php:class:`\\Cake\\Log\\Log` using the 'debug' level, and the 'queriesLog' scope. You will need to have a logger configured to capture this level & scope. Logging to ``stderr`` can be useful when working on unit tests, and logging to files/syslog can be useful when working with web requests:: diff --git a/en/orm/deleting-data.rst b/en/orm/deleting-data.rst index dfaa0fed07..5f12e3b05f 100644 --- a/en/orm/deleting-data.rst +++ b/en/orm/deleting-data.rst @@ -45,7 +45,7 @@ Cascading Deletes When deleting entities, associated data can also be deleted. If your HasOne and HasMany associations are configured as ``dependent``, delete operations will 'cascade' to those entities as well. By default entities in associated tables -are removed using :php:meth:`Cake\\ORM\\Table::deleteAll()`. You can elect to +are removed using :php:meth:`\\Cake\\ORM\\Table::deleteAll()`. You can elect to have the ORM load related entities, and delete them individually by setting the ``cascadeCallbacks`` option to ``true``. A sample HasMany association with both these options enabled would be:: @@ -106,7 +106,7 @@ Strict Deletes .. php:method:: deleteOrFail($entity, $options = []) Using this method will throw an -:php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` if: +:php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` if: * the entity is new * the entity has no primary key value @@ -122,5 +122,5 @@ If you want to track down the entity that failed to delete, you can use the echo $e->getEntity(); } -As this internally performs a :php:meth:`Cake\\ORM\\Table::delete()` call, all +As this internally performs a :php:meth:`\\Cake\\ORM\\Table::delete()` call, all corresponding delete events will be triggered. diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst index 4087a249c8..0ba97c99e7 100644 --- a/en/orm/query-builder.rst +++ b/en/orm/query-builder.rst @@ -50,7 +50,7 @@ Selecting Rows From A Table } For the remaining examples, assume that ``$articles`` is a -:php:class:`~Cake\\ORM\\Table`. When inside controllers, you can use +:php:class:`\\Cake\\ORM\\Table`. When inside controllers, you can use ``$this->Articles`` instead of ``$articles``. Almost every method in a ``SelectQuery`` object will return the same query, this means @@ -1558,7 +1558,7 @@ method as many times as you need:: ->execute(); Generally, it is easier to insert data using entities and -:php:meth:`~Cake\\ORM\\Table::save()`. By composing a ``SELECT`` and +:php:meth:`\\Cake\\ORM\\Table::save()`. By composing a ``SELECT`` and ``INSERT`` query together, you can create ``INSERT INTO ... SELECT`` style queries:: @@ -1608,7 +1608,7 @@ Instead, create new a query object using ``deleteQuery()``:: ->execute(); Generally, it is easier to delete data using entities and -:php:meth:`~Cake\\ORM\\Table::delete()`. +:php:meth:`\\Cake\\ORM\\Table::delete()`. SQL Injection Prevention ======================== diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst index 322e197678..5dd7887047 100644 --- a/en/orm/saving-data.rst +++ b/en/orm/saving-data.rst @@ -1129,7 +1129,7 @@ Strict Saving .. php:method:: saveOrFail($entity, $options = []) Using this method will throw an -:php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` if: +:php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` if: * the application rules checks failed * the entity contains errors @@ -1152,7 +1152,7 @@ If you want to track down the entity that failed to save, you can use the echo $e->getEntity(); } -As this internally performs a :php:meth:`Cake\\ORM\\Table::save()` call, all +As this internally performs a :php:meth:`\\Cake\\ORM\\Table::save()` call, all corresponding save events will be triggered. Find or Create an Entity diff --git a/en/tutorials-and-examples/cms/articles-controller.rst b/en/tutorials-and-examples/cms/articles-controller.rst index 18add5b372..9d32e517eb 100644 --- a/en/tutorials-and-examples/cms/articles-controller.rst +++ b/en/tutorials-and-examples/cms/articles-controller.rst @@ -227,7 +227,7 @@ Here's what the ``add()`` action does: Every CakePHP request includes a request object which is accessible using ``$this->request``. The request object contains information regarding the request that was just received. We use the -:php:meth:`Cake\\Http\\ServerRequest::is()` method to check that the request +:php:meth:`\\Cake\\Http\\ServerRequest::is()` method to check that the request is a HTTP POST request. Our POST data is available in ``$this->request->getData()``. You can use the diff --git a/en/views.rst b/en/views.rst index 255a4b9f11..eb3380a074 100644 --- a/en/views.rst +++ b/en/views.rst @@ -385,7 +385,7 @@ The ``HtmlHelper`` ties into view blocks, and its ``script()``, ``css()``, and // Rest of the layout follows -The :php:meth:`Cake\\View\\Helper\\HtmlHelper` also allows you to control which +The :php:class:`\\Cake\\View\\Helper\\HtmlHelper` also allows you to control which block the scripts and CSS go to:: // In your view diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 1472741556..464e65617a 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -447,8 +447,8 @@ allowed to be empty. You can disable automatic ``required`` flagging using the To skip browser validation triggering for the whole form you can set option ``'formnovalidate' => true`` for the input button you generate using -:php:meth:`~Cake\\View\\Helper\\FormHelper::submit()` or set ``'novalidate' => -true`` in options for :php:meth:`~Cake\\View\\Helper\\FormHelper::create()`. +:php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` or set ``'novalidate' => +true`` in options for :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()`. For example, let's assume that your Users model includes fields for a *username* (varchar), *password* (varchar), *approved* (datetime) and @@ -512,7 +512,7 @@ format as follows:: .. note:: You should not use ``FormHelper::control()`` to generate submit buttons. Use - :php:meth:`~Cake\\View\\Helper\\FormHelper::submit()` instead. + :php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` instead. Field Naming Conventions ------------------------ @@ -702,8 +702,8 @@ Generating Specific Types of Controls In addition to the generic ``control()`` method, ``FormHelper`` has specific methods for generating a number of different types of controls. These can be used to generate just the control widget itself, and combined with other methods like -:php:meth:`~Cake\\View\\Helper\\FormHelper::label()` and -:php:meth:`~Cake\\View\\Helper\\FormHelper::error()` to generate fully custom +:php:meth:`\\Cake\\View\\Helper\\FormHelper::label()` and +:php:meth:`\\Cake\\View\\Helper\\FormHelper::error()` to generate fully custom form layouts. .. _general-control-options: @@ -1839,7 +1839,7 @@ for the *Ticket* field, your form would output: .. note:: - When using :php:meth:`~Cake\\View\\Helper\\FormHelper::control()`, errors are + When using :php:meth:`\\Cake\\View\\Helper\\FormHelper::control()`, errors are rendered by default, so you don't need to use ``isFieldError()`` or call ``error()`` manually. @@ -2023,7 +2023,7 @@ Closing the Form The ``end()`` method closes and completes a form. Often, ``end()`` will only output a closing form tag, but using ``end()`` is a good practice as it enables FormHelper to insert the hidden form elements that -:php:class:`Cake\\Controller\\Component\\FormProtectionComponent` requires: +:php:class:`\\Cake\\Controller\\Component\\FormProtectionComponent` requires: .. code-block:: php @@ -2111,8 +2111,8 @@ Will output HTML similar to: Since this method generates a ``form`` element, do not use this method in an already opened form. Instead use -:php:meth:`Cake\\View\\Helper\\FormHelper::submit()` -or :php:meth:`Cake\\View\\Helper\\FormHelper::button()` to create buttons +:php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` +or :php:meth:`\\Cake\\View\\Helper\\FormHelper::button()` to create buttons inside opened forms. Creating POST Links @@ -2160,8 +2160,8 @@ new form is being set to a :ref:`view block ` that can be rendered outside of the main form. If all you are looking for is a button to submit your form, then you should -use :php:meth:`Cake\\View\\Helper\\FormHelper::button()` or -:php:meth:`Cake\\View\\Helper\\FormHelper::submit()` instead. +use :php:meth:`\\Cake\\View\\Helper\\FormHelper::button()` or +:php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` instead. .. note:: @@ -2591,13 +2591,13 @@ widget using the magic method:: Working with SecurityComponent ============================== -:php:meth:`Cake\\Controller\\Component\\SecurityComponent` offers several +:php:meth:`\\Cake\\Controller\\Component\\SecurityComponent` offers several features that make your forms safer and more secure. By simply including the ``SecurityComponent`` in your controller, you'll automatically benefit from form tampering-prevention features. As mentioned previously when using SecurityComponent, you should always close -your forms using :php:meth:`~Cake\\View\\Helper\\FormHelper::end()`. This will +your forms using :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()`. This will ensure that the special ``_Token`` inputs are generated. .. php:method:: unlockField($name) diff --git a/en/views/helpers/html.rst b/en/views/helpers/html.rst index db2b022c7e..c7485f4c48 100644 --- a/en/views/helpers/html.rst +++ b/en/views/helpers/html.rst @@ -390,7 +390,7 @@ Will output: Brownies -Also check :php:meth:`Cake\\View\\Helper\\UrlHelper::build()` method +Also check :php:meth:`\\Cake\\View\\Helper\\UrlHelper::build()` method for more examples of different types of URLs. .. php:method:: linkFromPath(string $title, string $path, array $params = [], array $options = []) diff --git a/en/views/helpers/time.rst b/en/views/helpers/time.rst index b1ba1c9d9e..5f50519f3c 100644 --- a/en/views/helpers/time.rst +++ b/en/views/helpers/time.rst @@ -39,7 +39,7 @@ posts using the TimeHelper:: Most of TimeHelper's features are intended as backwards compatible interfaces for applications that are upgrading from older versions of CakePHP. Because the -ORM returns :php:class:`Cake\\I18n\\Time` instances for every ``timestamp`` +ORM returns :php:class:`\\Cake\\I18n\\Time` instances for every ``timestamp`` and ``datetime`` column, you can use the methods there to do most tasks. For example, to read about the accepted formatting strings take a look at the `Cake\\I18n\\Time::i18nFormat() diff --git a/es/console-commands/option-parsers.rst b/es/console-commands/option-parsers.rst index 9c2b96d30b..8de3eb1696 100644 --- a/es/console-commands/option-parsers.rst +++ b/es/console-commands/option-parsers.rst @@ -220,8 +220,8 @@ todo es una matriz:: Dentro de las especificaciones del analizador, puede definir claves para ``arguments``, ``options``, ``description`` y ``epilog``. No se pueden definir ``subcommands`` dentro de un generador de estilos de matriz. Los valores de los -argumentos y las opciones deben seguir el formato :php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` y -:php:func:`Cake\\Console\\ConsoleOptionParser::addOptions( )`. También puede +argumentos y las opciones deben seguir el formato :php:func:`\\Cake\\Console\\ConsoleOptionParser::addArguments()` y +:php:func:`\\Cake\\Console\\ConsoleOptionParser::addOptions( )`. También puede utilizar buildFromArray por sí solo para crear un analizador de opciones:: public function getOptionParser() diff --git a/es/controllers.rst b/es/controllers.rst index 5bdccff12c..fd94294616 100644 --- a/es/controllers.rst +++ b/es/controllers.rst @@ -46,7 +46,7 @@ El App Controller Como se indicó en la introducción, la clase ``AppController`` es clase padre de todos los controladores de tu aplicación. ``AppController`` extiende de la clase -:php:class:`Cake\\Controller\\Controller` que está incluida en CakePHP. +:php:class:`\\Cake\\Controller\\Controller` que está incluida en CakePHP. ``AppController`` se define en **src/Controller/AppController.php** como se muestra a continuación:: @@ -85,7 +85,7 @@ Flujo de solicitud ================== Cuando se realiza una solicitud a una aplicación CakePHP, las clases CakePHP -:php:class:`Cake\\Routing\\Router` y :php:class:`Cake\\Routing\\Dispatcher` +:php:class:`\\Cake\\Routing\\Router` y :php:class:`\\Cake\\Routing\\Dispatcher` usan :ref:`routes-configuration` para encontrar y crear la instancia correcta del controlador. Los datos de la solicitud son encapsulados en un objeto de solicitud. CakePHP pone toda la información importante de la solicitud en la @@ -138,7 +138,7 @@ manualmente. En su lugar, una vez que se ha completado la acción del controlado CakePHP se encargará de renderizar y entregar la vista. Si por algún motivo deseas omitir el comportamiento predeterminado, puedes retornar -un objeto :php:class:`Cake\\Http\\Response` de la acción con la respuesta creada. +un objeto :php:class:`\\Cake\\Http\\Response` de la acción con la respuesta creada. Para que puedas usar un controlador de manera efectiva en tu aplicación, cubriremos algunos de los atributos y métodos principales proporcionados por los @@ -545,7 +545,7 @@ eventos relacionados si los métodos son implementados por tus controladores. Llamado durante el evento ``Controller.beforeRender`` que ocurre después de la lógica de acción del controlador, pero antes de que la vista sea renderizada. Este callback no se usa con frecuencia, pero puede ser necesaria - si estas llamando :php:meth:`~Cake\\Controller\\Controller::render()` de forma + si estas llamando :php:meth:`\\Cake\\Controller\\Controller::render()` de forma manual antes del final de una acción dada. .. php:method:: afterFilter(EventInterface $event) diff --git a/es/controllers/request-response.rst b/es/controllers/request-response.rst index 860cf851be..3d1117f202 100644 --- a/es/controllers/request-response.rst +++ b/es/controllers/request-response.rst @@ -89,7 +89,7 @@ Datos del cuerpo de la solicitud .. php:method:: getData($name, $default = null) Se puede acceder a todos los datos POST normalmente disponibles a través de la variable global ``$_POST`` de PHP usando -:php:meth:`Cake\\Http\\ServerRequest::getData()`. Por ejemplo:: +:php:meth:`\\Cake\\Http\\ServerRequest::getData()`. Por ejemplo:: // Se puede acceder a una entrada con un atributo de nombre 'título' $title = $this->request->getData('title'); @@ -117,7 +117,7 @@ Cargas de archivos ------------------ Se puede acceder a los archivos cargados a través de los datos del cuerpo de la solicitud, utilizando el método -:php:meth:`Cake\\Http\\ServerRequest::getData()` descrito anteriormente. Por ejemplo, se puede acceder a un archivo desde +:php:meth:`\\Cake\\Http\\ServerRequest::getData()` descrito anteriormente. Por ejemplo, se puede acceder a un archivo desde un elemento de entrada con un atributo de nombre ``attachment`` de esta manera:: $attachment = $this->request->getData('attachment'); @@ -149,11 +149,11 @@ archivos. .. php:method:: getUploadedFile($path) Devuelve el archivo cargado en una ruta específica. La ruta utiliza la misma sintaxis de puntos que el método -:php:meth:`Cake\\Http\\ServerRequest::getData()`:: +:php:meth:`\\Cake\\Http\\ServerRequest::getData()`:: $attachment = $this->request->getUploadedFile('attachment'); -A diferencia de :php:meth:`Cake\\Http\\ServerRequest::getData()`, :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` +A diferencia de :php:meth:`\\Cake\\Http\\ServerRequest::getData()`, :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` solo devolvería datos cuando exista una carga de archivo real para la ruta dada, si hay datos regulares del cuerpo de la solicitud que no son archivos presentes en la ruta dada, entonces este método devolverá "nulo", tal como lo haría para cualquier ruta inexistente. @@ -200,9 +200,9 @@ todos los archivos cargados posiblemente existentes:: Los archivos cargados que se agregaron a la solicitud a través de este método *no* estarán disponibles en los datos del cuerpo de la solicitud, es decir, no puede recuperarlos a través de - :php:meth:`Cake\\Http\\ServerRequest::getData()` ! Si los necesita en los datos de la solicitud (también), entonces - debe configurarlos mediante :php:meth:`Cake\\Http\\ServerRequest::withData()` o - :php:meth:`Cake\\Http\ \ServerRequest::withParsedBody()`. + :php:meth:`\\Cake\\Http\\ServerRequest::getData()` ! Si los necesita en los datos de la solicitud (también), entonces + debe configurarlos mediante :php:meth:`\\Cake\\Http\\ServerRequest::withData()` o + :php:meth:`\\Cake\\Http\ \ServerRequest::withParsedBody()`. PUT, PATCH o DELETE Datos ------------------------- @@ -287,7 +287,7 @@ solicitud específicos de la aplicación: $isPost = $this->request->is('post'); También puede ampliar los detectores de solicitudes que están disponibles, utilizando -:php:meth:`Cake\\Http\\ServerRequest::addDetector()` para crear nuevos tipos de detectores. Hay diferentes tipos de +:php:meth:`\\Cake\\Http\\ServerRequest::addDetector()` para crear nuevos tipos de detectores. Hay diferentes tipos de detectores que puedes crear: * Comparación de valores del entorno: compara un valor obtenido de :php:func:`env()` para determinar su igualdad con el @@ -371,8 +371,8 @@ Hay varios detectores integrados que puedes utilizar: * ``is('json')`` Verifique si la solicitud tiene la extensión 'json' y acepte el tipo mime 'application/json'. * ``is('xml')`` Verifique si la solicitud tiene la extensión 'xml' y acepte el tipo mime 'application/xml' o 'text/xml'. -``ServerRequest`` También incluye métodos como :php:meth:`Cake\\Http\\ServerRequest::domain()`, -:php:meth:`Cake\\Http\\ServerRequest::subdomains()` y :php:meth:`Cake\\Http\\ServerRequest::host()` para simplificar las +``ServerRequest`` También incluye métodos como :php:meth:`\\Cake\\Http\\ServerRequest::domain()`, +:php:meth:`\\Cake\\Http\\ServerRequest::subdomains()` y :php:meth:`\\Cake\\Http\\ServerRequest::host()` para simplificar las aplicaciones que utilizan subdominios. Datos de sesión @@ -534,7 +534,7 @@ Las cookies de solicitud se pueden leer a través de varios métodos: // Obtener una instancia de CookieCollection $cookies = $this->request->getCookieCollection() -Consulte la documentación :php:class:`Cake\\Http\\Cookie\\CookieCollection` para saber cómo trabajar con la recopilación +Consulte la documentación :php:class:`\\Cake\\Http\\Cookie\\CookieCollection` para saber cómo trabajar con la recopilación de cookies. Archivos cargados @@ -575,7 +575,7 @@ Respueta (Response) .. php:class:: Response -:php:class:`Cake\\Http\\Response` es la clase de respuesta predeterminada en CakePHP. Encapsula una serie de +:php:class:`\\Cake\\Http\\Response` es la clase de respuesta predeterminada en CakePHP. Encapsula una serie de características y funcionalidades para generar respuestas HTTP en su aplicación. También ayuda en las pruebas, ya que se puede simular o eliminar, lo que le permite inspeccionar los encabezados que se enviarán. @@ -591,7 +591,7 @@ Tratar con tipos de contenido .. php:method:: withType($contentType = null) -Puede controlar el tipo de contenido de las respuestas de su aplicación con :php:meth:`Cake\\Http\\Response::withType()`. +Puede controlar el tipo de contenido de las respuestas de su aplicación con :php:meth:`\\Cake\\Http\\Response::withType()`. Si su aplicación necesita manejar tipos de contenido que no están integrados en Response, también puede asignarlos con ``setTypeMap()``:: @@ -613,7 +613,7 @@ Enviando arhivos .. php:method:: withFile(string $path, array $options = []) Hay ocasiones en las que desea enviar archivos como respuesta a sus solicitudes. Puedes lograrlo usando -:php:meth:`Cake\\Http\\Response::withFile()`:: +:php:meth:`\\Cake\\Http\\Response::withFile()`:: public function sendFile($id) { @@ -625,8 +625,8 @@ Hay ocasiones en las que desea enviar archivos como respuesta a sus solicitudes. Como se muestra en el ejemplo anterior, debe pasar la ruta del archivo al método. CakePHP enviará un encabezado de tipo de contenido adecuado si es un tipo de archivo conocido que figura en `Cake\\Http\\Response::$_mimeTypes`. Puede agregar -nuevos tipos antes de llamar a :php:meth:`Cake\\Http\\Response::withFile()` usando el método -:php:meth:`Cake\\Http\\Response::withType()` . +nuevos tipos antes de llamar a :php:meth:`\\Cake\\Http\\Response::withFile()` usando el método +:php:meth:`\\Cake\\Http\\Response::withType()` . Si lo desea, también puede forzar la descarga de un archivo en lugar de mostrarlo en el navegador especificando las opciones:: @@ -671,7 +671,7 @@ Configuración de encabezados .. php:method:: withHeader($header, $value) -La configuración de los encabezados se realiza con el método :php:meth:`Cake\\Http\\Response::withHeader()`. Como todos +La configuración de los encabezados se realiza con el método :php:meth:`\\Cake\\Http\\Response::withHeader()`. Como todos los métodos de la interfaz PSR-7, este método devuelve una instancia *nueva* con el nuevo encabezado:: // Agregar/reemplazar un encabezado @@ -687,7 +687,7 @@ los métodos de la interfaz PSR-7, este método devuelve una instancia *nueva* c Los encabezados no se envían cuando se configuran. En cambio, se retienen hasta que ``Cake\Http\Server`` emite la respuesta. -Ahora puede utilizar el método conveniente :php:meth:`Cake\\Http\\Response::withLocation()` para configurar u obtener +Ahora puede utilizar el método conveniente :php:meth:`\\Cake\\Http\\Response::withLocation()` para configurar u obtener directamente el encabezado de ubicación de redireccionamiento. Configurando el cuerpo @@ -751,7 +751,7 @@ Interactuar con el almacenamiento en caché del navegador .. php:method:: withDisabledCache() A veces es necesario obligar a los navegadores a no almacenar en caché los resultados de una acción del controlador. -:php:meth:`Cake\\Http\\Response::withDisabledCache()` está destinado precisamente a eso:: +:php:meth:`\\Cake\\Http\\Response::withDisabledCache()` está destinado precisamente a eso:: public function index() { @@ -767,7 +767,7 @@ A veces es necesario obligar a los navegadores a no almacenar en caché los resu .. php:method:: withCache($since, $time = '+1 day') También puede decirles a los clientes que desea que almacenen en caché las respuestas. Usando -:php:meth:`Cake\\Http\\Response::withCache()`:: +:php:meth:`\\Cake\\Http\\Response::withCache()`:: public function index() { @@ -792,7 +792,7 @@ configurando algunos encabezados, como la hora de modificación y la etiqueta de En lugar de obligarlo a codificar la lógica para el almacenamiento en caché y para invalidarla (actualizarla) una vez que los datos han cambiado, HTTP utiliza dos modelos, caducidad y validación, que generalmente son mucho más simples de usar. -Además de usar :php:meth:`Cake\\Http\\Response::withCache()`, también puedes usar muchos otros métodos para ajustar los +Además de usar :php:meth:`\\Cake\\Http\\Response::withCache()`, también puedes usar muchos otros métodos para ajustar los encabezados de caché HTTP para aprovechar el almacenamiento en caché del navegador o del proxy inverso. El encabezado de control de caché @@ -940,7 +940,7 @@ sitodavía se puede considerar nuevo. Si es así, elimina el contenido de la res Configuración de cookies ------------------------ -Las cookies se pueden agregar a la respuesta usando una matriz o un objeto :php:class:`Cake\\Http\\Cookie\\Cookie`:: +Las cookies se pueden agregar a la respuesta usando una matriz o un objeto :php:class:`\\Cake\\Http\\Cookie\\Cookie`:: use Cake\Http\Cookie\Cookie; use DateTime; diff --git a/es/core-libraries/caching.rst b/es/core-libraries/caching.rst index ffa7ea2568..3b857996ba 100644 --- a/es/core-libraries/caching.rst +++ b/es/core-libraries/caching.rst @@ -16,7 +16,7 @@ En CakePHP, el almacenamiento en caché se facilita mediante la clase ``Cache``. - ``Array``: almacena todos los datos en una matriz. Este motor no proporciona almacenamiento persistente y está destinado a su uso en suites de pruebas de aplicaciones. - ``Null``: el motor nulo en realidad no almacena nada y falla en todas las operaciones de lectura. -Independientemente del motor de caché que elijas usar, tu aplicación interactúa con :php:class:`Cake\\Cache\\Cache`. +Independientemente del motor de caché que elijas usar, tu aplicación interactúa con :php:class:`\\Cake\\Cache\\Cache`. .. _cache-configuration: @@ -83,8 +83,8 @@ También puedes configurar los motores de caché en tiempo de ejecución:: Cache::setConfig('otro', $objeto); Los nombres de estas configuraciones de motor ('short' y 'long') se utilizan como el parámetro ``$config`` -para :php:meth:`Cake\\Cache\\Cache::write()` y -:php:meth:`Cake\\Cache\\Cache::read()`. Al configurar los motores de caché, puedes +para :php:meth:`\\Cake\\Cache\\Cache::write()` y +:php:meth:`\\Cake\\Cache\\Cache::read()`. Al configurar los motores de caché, puedes referenciar el nombre de la clase utilizando las siguientes sintaxis:: // Nombre corto (en App\ o en los espacios de nombres de Cake) @@ -203,8 +203,8 @@ Eliminación de Motores de Caché Configurados .. php:staticmethod:: drop($clave) Una vez que se crea una configuración, no puedes cambiarla. En su lugar, debes eliminar -la configuración y volver a crearla usando :php:meth:`Cake\\Cache\\Cache::drop()` y -:php:meth:`Cake\\Cache\\Cache::setConfig()`. Eliminar un motor de caché eliminará +la configuración y volver a crearla usando :php:meth:`\\Cake\\Cache\\Cache::drop()` y +:php:meth:`\\Cake\\Cache\\Cache::setConfig()`. Eliminar un motor de caché eliminará la configuración y destruirá el adaptador si se construyó. Escritura en Caché @@ -443,7 +443,7 @@ Utilizando la Caché para Almacenar Resultados Comunes de Consultas Puedes mejorar significativamente el rendimiento de tu aplicación almacenando en caché los resultados que rara vez cambian o que están sujetos a lecturas frecuentes. Un ejemplo perfecto de esto son los resultados de -:php:meth:`Cake\\ORM\\Table::find()`. El objeto de consulta te permite almacenar en caché +:php:meth:`\\Cake\\ORM\\Table::find()`. El objeto de consulta te permite almacenar en caché los resultados utilizando el método ``cache()``. Consulta la sección :ref:`caching-query-results` para obtener más información. @@ -529,7 +529,7 @@ Puedes proporcionar motores de ``Cache`` personalizados en ``App\Cache\Engine``, // ... ]); -Los motores de caché personalizados deben extender :php:class:`Cake\\Cache\\CacheEngine`, que define varios métodos abstractos y también proporciona algunos métodos de inicialización. +Los motores de caché personalizados deben extender :php:class:`\\Cake\\Cache\\CacheEngine`, que define varios métodos abstractos y también proporciona algunos métodos de inicialización. La API requerida para un CacheEngine es diff --git a/es/core-libraries/logging.rst b/es/core-libraries/logging.rst index fe4f49c4da..88940f22f8 100644 --- a/es/core-libraries/logging.rst +++ b/es/core-libraries/logging.rst @@ -29,7 +29,7 @@ Logging Configuration La configuración de ``Log`` debe realizarse durante la fase de arranque de tu aplicación. El archivo **config/app.php** está diseñado precisamente para esto. Puedes definir tantos ``loggers`` como necesite tu aplicación. Los ``loggers`` deben configurarse utilizando la clase -:php:class:`Cake\\Log\\Log`. Un ejemplo sería:: +:php:class:`\\Cake\\Log\\Log`. Un ejemplo sería:: use Cake\Log\Engine\FileLog; use Cake\Log\Log; @@ -102,7 +102,7 @@ Escribiendo en los archivos de Log =================================== Escribir en los archivos de registro se puede hacer de dos maneras diferentes. La primera es -utilizando el método estático ::php:meth:`Cake\\Log\\Log::write()`:: +utilizando el método estático ::php:meth:`\\Cake\\Log\\Log::write()`:: Log::write('debug', 'Something did not work'); @@ -113,7 +113,7 @@ que utilice el ``LogTrait``. Llamar a``log()`` llamará internamente a``Log::wri $this->log('Something did not work!', 'debug'); Todos los ``log`` configurados se escriben secuencialmente cada vez que se llama a -:php:meth:`Cake\\Log\\Log::write()`. Si no has configurado ningún motor de registro, +:php:meth:`\\Cake\\Log\\Log::write()`. Si no has configurado ningún motor de registro, ``log()`` devolverá "false" y no se escribirán mensajes de registro. Usando marcadores de posición (placeholders) en mensajes diff --git a/es/core-libraries/number.rst b/es/core-libraries/number.rst index 5edea0903e..c1f768281b 100644 --- a/es/core-libraries/number.rst +++ b/es/core-libraries/number.rst @@ -104,7 +104,7 @@ Configurar la Moneda Predeterminada .. php:method:: setDefaultCurrency($currency) Configura la moneda predeterminada. Esto evita la necesidad de pasar siempre la -moneda a :php:meth:`Cake\\I18n\\Number::currency()` y cambiar todas las +moneda a :php:meth:`\\Cake\\I18n\\Number::currency()` y cambiar todas las salidas de moneda configurando otro valor predeterminado. Si ``$currency`` se establece en ``null``, se eliminará el valor almacenado actualmente. @@ -146,7 +146,7 @@ Formato de Porcentajes | | decimales. | +---------------------+----------------------------------------------------+ -Al igual que :php:meth:`Cake\\I18n\\Number::precision()`, este método formatea un número +Al igual que :php:meth:`\\Cake\\I18n\\Number::precision()`, este método formatea un número según la precisión proporcionada (donde los números se redondean para cumplir con la precisión dada). Adicionalmente, también expresa el número como un porcentaje y agrega un signo de porcentaje a la salida. :: diff --git a/es/development/debugging.rst b/es/development/debugging.rst index 8314c84dc2..e5f3c04718 100644 --- a/es/development/debugging.rst +++ b/es/development/debugging.rst @@ -163,7 +163,7 @@ Usando El Registro Para Depurar =============================== Registrar mensajes es otra buena manera de depurar aplicaciones, puedes usar -:php:class:`Cake\\Log\\Log` para hacer registros en tu aplicación. Todos los +:php:class:`\\Cake\\Log\\Log` para hacer registros en tu aplicación. Todos los objetos que usen ``LogTrait`` tienen una instancia del método ``log()`` que puede ser usado para registrar mensajes:: @@ -171,7 +171,7 @@ puede ser usado para registrar mensajes:: Lo anterior escribiría ``Llegó aquí`` en el registro de depuración. Puedes usar entradas de registro para ayudar a los métodos de depuración que involucran redireccionamientos -o búcles complejos. También puedes usar :php:meth:`Cake\\Log\\Log::write()` para +o búcles complejos. También puedes usar :php:meth:`\\Cake\\Log\\Log::write()` para escribir mensajes de registro. Este método puede ser llamado estáticamente en cualquier lugar de tu aplicación que un Log haya sido cargado:: diff --git a/es/development/errors.rst b/es/development/errors.rst index 113fe078b2..c8bd150c3f 100644 --- a/es/development/errors.rst +++ b/es/development/errors.rst @@ -23,7 +23,7 @@ Las siguientes opciones son compatibles: * ``exceptionRenderer`` - string - La clase responsable de representar excepciones no capturadas. Si eliges una clase personalizada, debes colocar el archivo para esa clase en **src/Error**. Esta clase debe implementar un método ``render()``. -* ``log`` - bool - Cuando es ``true``, las excepciones y sus trazas se registrarán en :php:class:`Cake\\Log\\Log`. +* ``log`` - bool - Cuando es ``true``, las excepciones y sus trazas se registrarán en :php:class:`\\Cake\\Log\\Log`. * ``skipLog`` - array - Un array de nombres de clases de excepción que no deben ser registrados. Esto es útil para eliminar mensajes de registro comunes pero poco interesantes, como NotFoundExceptions. * ``extraFatalErrorMemory`` - int - Establece el número de megabytes para aumentar el límite de memoria cuando @@ -293,7 +293,7 @@ Cuando se representa, tu plantilla de vista tendría una variable ``$widget`` es Registro de Excepciones ------------------------ -Usando el manejo de excepciones incorporado, puedes registrar todas las excepciones que son tratadas por ErrorTrap configurando la opción ``log`` en ``true`` en tu **config/app.php**. Al habilitar esto, se registrarán todas las excepciones en :php:class:`Cake\\Log\\Log` y en los registradores configurados. +Usando el manejo de excepciones incorporado, puedes registrar todas las excepciones que son tratadas por ErrorTrap configurando la opción ``log`` en ``true`` en tu **config/app.php**. Al habilitar esto, se registrarán todas las excepciones en :php:class:`\\Cake\\Log\\Log` y en los registradores configurados. .. note:: @@ -519,8 +519,8 @@ Además, CakePHP utiliza las siguientes excepciones: .. php:exception:: PersistenceFailedException :nocontentsentry: - No se pudo guardar/eliminar una entidad al usar :php:meth:`Cake\\ORM\\Table::saveOrFail()` o - :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. + No se pudo guardar/eliminar una entidad al usar :php:meth:`\\Cake\\ORM\\Table::saveOrFail()` o + :php:meth:`\\Cake\\ORM\\Table::deleteOrFail()`. .. php:namespace:: Cake\Datasource\Exception diff --git a/es/development/rest.rst b/es/development/rest.rst index 59f11a72b4..ac206be84a 100644 --- a/es/development/rest.rst +++ b/es/development/rest.rst @@ -140,7 +140,7 @@ El XML procesado terminará pareciéndose a esto:: Crear la lógica para la acción de edición es un poco más complicado, pero no mucho. Ya que se está proporcionando una API que genera XML como salida, es una opción natural recibir XML como entrada. No te preocupes, las clases :php:class:`Cake\\Controller\\Component\\RequestHandler` -y :php:class:`Cake\\Routing\\Router` hacen las cosas mucho más fáciles. Si un POST o +y :php:class:`\\Cake\\Routing\\Router` hacen las cosas mucho más fáciles. Si un POST o una solicitud PUT tiene un tipo de contenido XML, entonces la entrada se ejecuta a través de la clase de CakePHP :php:class:`Xml`, y la representación del arreglo de los datos se asigna a ``$this->request->getData()``. Debido a esta característica, el manejo de datos XML y POST se hace en continuamente en paralelo: no se diff --git a/es/development/routing.rst b/es/development/routing.rst index 686fbd0ce2..3fbfb52bad 100644 --- a/es/development/routing.rst +++ b/es/development/routing.rst @@ -1601,7 +1601,7 @@ las rutas individuales analizan las solicitudes y manejan el enrutamiento invers Las clases de ruta tienen algunas convenciones: * Se espera que las clases de ruta se encuentren en el espacio de nombres ``Routing\\Route`` de tu aplicación o plugin. -* Las clases de ruta deben extender :php:class:`Cake\\Routing\\Route\\Route`. +* Las clases de ruta deben extender :php:class:`\\Cake\\Routing\\Route\\Route`. * Las clases de ruta deben implementar uno o ambos ``match()`` y/o ``parse()``. El método ``parse()`` se utiliza para analizar una URL entrante. Debería generar diff --git a/es/development/sessions.rst b/es/development/sessions.rst index 5f00b789e8..9ded79cf3a 100644 --- a/es/development/sessions.rst +++ b/es/development/sessions.rst @@ -266,7 +266,7 @@ Primero necesitamos crear nuestra clase personalizada y ponerla en **src/Http/Se } Nuestra clase extiende el ``DatabaseSession`` incorporado para no tener que duplicar toda su lógica y comportamiento. Envolvemos -cada operación con una operación de :php:class:`Cake\\Cache\\Cache`. Esto nos permite obtener sesiones de la caché rápida y no +cada operación con una operación de :php:class:`\\Cake\\Cache\\Cache`. Esto nos permite obtener sesiones de la caché rápida y no tener que preocuparnos por lo que sucede cuando llenamos la caché. En **config/app.php** haz que el bloque de sesión se vea así:: 'Session' => [ diff --git a/es/orm.rst b/es/orm.rst index a24fb3a46d..d33918b5d0 100644 --- a/es/orm.rst +++ b/es/orm.rst @@ -50,7 +50,7 @@ adicionales deberiamos agregar las siguientes líneas en **src/Model/Table/Artic } Las clases Table usan una version en CamelCase del nombre de la tabla, con el sufijo ``Table``. -Una vez que tu clase fue creada, puedes obtener una referencia a esta usando :php:class:`~Cake\\ORM\\TableRegistry` como antes:: +Una vez que tu clase fue creada, puedes obtener una referencia a esta usando :php:class:`\\Cake\\ORM\\TableRegistry` como antes:: use Cake\ORM\TableRegistry; diff --git a/es/views.rst b/es/views.rst index 2e0a099e31..313f547b26 100644 --- a/es/views.rst +++ b/es/views.rst @@ -342,7 +342,7 @@ El `HtmlHelper` se integra con bloques de vista, y sus métodos `script()`, `css // El resto del diseño sigue -El :php:meth:`Cake\\View\\Helper\\HtmlHelper` también te permite controlar a qué bloque van los scripts y el CSS:: +El :php:class:`\\Cake\\View\\Helper\\HtmlHelper` también te permite controlar a qué bloque van los scripts y el CSS:: // En tu vista $this->Html->script('carousel', ['block' => 'scriptBottom']); diff --git a/fr/console-commands/option-parsers.rst b/fr/console-commands/option-parsers.rst index 83b0fb7812..e10af3a91d 100644 --- a/fr/console-commands/option-parsers.rst +++ b/fr/console-commands/option-parsers.rst @@ -215,8 +215,8 @@ subcommand parsers easier, as everything is an array:: Inside the parser spec, you can define keys for ``arguments``, ``options``, ``description`` and ``epilog``. You cannot define ``subcommands`` inside an array style builder. The values for arguments, and options, should follow the -format that :php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` and -:php:func:`Cake\\Console\\ConsoleOptionParser::addOptions()` use. You can also +format that :php:func:`\\Cake\\Console\\ConsoleOptionParser::addArguments()` and +:php:func:`\\Cake\\Console\\ConsoleOptionParser::addOptions()` use. You can also use buildFromArray on its own, to build an option parser:: public function getOptionParser() diff --git a/fr/controllers.rst b/fr/controllers.rst index b22004c6b6..9f38fddf07 100644 --- a/fr/controllers.rst +++ b/fr/controllers.rst @@ -41,7 +41,7 @@ Le Controller App Comme indiqué dans l'introduction, la classe ``AppController`` est la classe mère de tous les controllers de votre application. ``AppController`` étend -elle-même la classe :php:class:`Cake\\Controller\\Controller` incluse dans la +elle-même la classe :php:class:`\\Cake\\Controller\\Controller` incluse dans la librairie du cœur de CakePHP. ``AppController`` est définie dans **src/Controller/AppController.php** comme ceci:: @@ -90,7 +90,7 @@ Déroulement d'une Requête ========================= Quand une requête est faîte dans une application CakePHP, les classes -:php:class:`Cake\\Routing\\Router` et :php:class:`Cake\\Routing\\Dispatcher` de +:php:class:`\\Cake\\Routing\\Router` et :php:class:`\\Cake\\Routing\\Dispatcher` de CakePHP utilisent la fonctionnalité :ref:`routes-configuration` pour trouver et créer le bon controller. La requête de données est encapsulée dans un objet request. CakePHP met toutes les informations importantes de la requête dans la @@ -143,7 +143,7 @@ manuellement. Au lieu de ça, une fois qu'une action du controller est terminée CakePHP va gérer le rendu et la livraison de la Vue. Si pour certaines raisons, vous voulez éviter le comportement par défaut, vous -pouvez retourner un objet de :php:class:`Cake\\Http\\Response` de l'action +pouvez retourner un objet de :php:class:`\\Cake\\Http\\Response` de l'action avec la response complètement créée. Afin que vous utilisiez efficacement le controller dans votre propre @@ -491,7 +491,7 @@ events liés si les méthodes sont implémentées dans vos controllers. Cette méthode est appelée pendant l'event ``Controller.beforeRender`` qui se produit après l'action du controller mais avant que la vue ne soit rendue. Ce callback n'est pas souvent utilisé, mais peut-être nécessaire si - vous appelez :php:meth:`~Cake\\Controller\\Controller::render()` manuellement + vous appelez :php:meth:`\\Cake\\Controller\\Controller::render()` manuellement à la fin d'une action donnée. .. php:method:: afterFilter(EventInterface $event) diff --git a/fr/controllers/components/form-protection.rst b/fr/controllers/components/form-protection.rst index e1d2e3f0f3..5a2491ee88 100644 --- a/fr/controllers/components/form-protection.rst +++ b/fr/controllers/components/form-protection.rst @@ -22,8 +22,8 @@ avant ceux-ci dans votre méthode ``initialize()``. réécrire les attributs "name" des champs. Le Component FormProtection observe certains indicateurs créés et gérés par le FormHelper (en particulier ceux qui sont créés dans - :php:meth:`~Cake\\View\\Helper\\FormHelper::create()` et - :php:meth:`~Cake\\View\\Helper\\FormHelper::end()`). L'altération dynamique + :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()` et + :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()`). L'altération dynamique des champs soumis dans une requête POST (par exemple désactiver, supprimer ou créer de nouveaux champs via JavaScript) est susceptible d'entraîner l'échec de validation du jeton de formulaire. diff --git a/fr/controllers/components/security.rst b/fr/controllers/components/security.rst index 36745c3744..43835b184f 100644 --- a/fr/controllers/components/security.rst +++ b/fr/controllers/components/security.rst @@ -34,8 +34,8 @@ avant ces components dans la méthode ``initialize()``. surcharger **aucun** des attributs des champs ' "name". Le component Security regarde certains indicateurs qui sont créés et gérés par le Helper form. (spécialement ceux créés dans - :php:meth:`~Cake\\View\\Helper\\FormHelper::create()`) et - :php:meth:`~Cake\\View\\Helper\\FormHelper::end()`). La modification + :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()`) et + :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()`). La modification dynamique des champs qui lui sont soumis dans une requête POST (ex. désactiver, effacer, créer des nouveaux champs via Javascript) est susceptible de déclencher un black-holing (envoi dans le trou noir) de la @@ -43,7 +43,7 @@ avant ces components dans la méthode ``initialize()``. Vous devez toujours vérifier les méthodes HTTP utilisées avant d'exécuter d'autre code. Vous devez :ref:`vérifier la méthode HTTP ` - ou utiliser :php:meth:`Cake\\Http\\ServerRequest::allowMethod()` pour vous + ou utiliser :php:meth:`\\Cake\\Http\\ServerRequest::allowMethod()` pour vous assurer que la bonne méthode HTTP est utilisée. Gestion des callbacks Blackhole diff --git a/fr/controllers/request-response.rst b/fr/controllers/request-response.rst index 500c4f5317..f36da62093 100644 --- a/fr/controllers/request-response.rst +++ b/fr/controllers/request-response.rst @@ -102,7 +102,7 @@ Données du Corps de la Requête .. php:method:: getData($name, $default = null) Toutes les données POST sont accessibles en utilisant -:php:meth:`Cake\\Http\\ServerRequest::getData()`. Par exemple:: +:php:meth:`\\Cake\\Http\\ServerRequest::getData()`. Par exemple:: // Un input avec un attribut de nom égal à 'title' est accessible via $title = $this->request->getData('title'); @@ -129,7 +129,7 @@ Envoyer des fichiers -------------------- Les fichiers téléchargés sont accessibles via les données du corps de la requête, en utilisant -la méthode :php:meth:`Cake\\Http\\ServerRequest::getData()` décrite ci-dessus. Par exemple, +la méthode :php:meth:`\\Cake\\Http\\ServerRequest::getData()` décrite ci-dessus. Par exemple, un fichier correspondant au nom ``attachment``, peut être accédé comme ceci:: @@ -191,20 +191,20 @@ c'est-à-dire que la valeur ``$attachment`` ressemblerait à quelque chose comme .. tip:: Les fichiers téléchargés sont également accessibles en tant qu'objets séparément des données de requête via les - méthodes :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` et - :php:meth:`Cake\\Http\\ServerRequest::getUploadedFiles()`. Ces méthodes renverront toujours des objets, + méthodes :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` et + :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFiles()`. Ces méthodes renverront toujours des objets, indépendamment de la configuration ``App.uploadedFilesAsObjects``. .. php:method:: getUploadedFile($path) Renvoie le fichier téléchargé à un chemin spécifique. Le chemin utilise la même syntaxe de point (dot) que la -méthode :php:meth:`Cake\\Http\\ServerRequest::getData()`:: +méthode :php:meth:`\\Cake\\Http\\ServerRequest::getData()`:: $attachment = $this->request->getUploadedFile('attachment'); -Contrairement à :php:meth:`Cake\\Http\\ServerRequest::getData()`, -:php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` ne renvoie des données que lorsqu'un téléchargement de fichier +Contrairement à :php:meth:`\\Cake\\Http\\ServerRequest::getData()`, +:php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` ne renvoie des données que lorsqu'un téléchargement de fichier réel existe pour le chemin donné, s'il existe des données de corps de requête régulières, non liées à un fichier, correspondant au chemin donné, alors cette méthode retournera ``null``, comme elle le ferait pour tout chemin inexistant. @@ -251,9 +251,9 @@ remplacer tous les fichiers téléchargés éventuellement existants:: Les fichiers téléchargés qui ont été ajoutés à la demande via cette méthode ne seront *pas* disponibles dans les données du corps de la requête, c'est-à-dire que vous ne pouvez pas les récupérer via - :php:meth:`Cake\\Http\\ServerRequest::getData()`! Si vous en avez besoin également dans les données de la requête, - vous devez les définir via :php:meth:`Cake\\Http\\ServerRequest::withData()` ou - :php:meth:`Cake\\Http\\ServerRequest::withParsedBody()`. + :php:meth:`\\Cake\\Http\\ServerRequest::getData()`! Si vous en avez besoin également dans les données de la requête, + vous devez les définir via :php:meth:`\\Cake\\Http\\ServerRequest::withData()` ou + :php:meth:`\\Cake\\Http\\ServerRequest::withParsedBody()`. Accéder aux Données PUT, PATCH ou DELETE ---------------------------------------- @@ -349,7 +349,7 @@ spécifique à l'application:: $isPost = $this->request->is('post'); Vous pouvez aussi étendre les détecteurs de la requête qui sont disponibles, en -utilisant :php:meth:`Cake\\Http\\ServerRequest::addDetector()` pour créer de +utilisant :php:meth:`\\Cake\\Http\\ServerRequest::addDetector()` pour créer de nouveaux types de détecteurs. Il y a différents types de détecteurs que vous pouvez créer: @@ -439,9 +439,9 @@ Il y a plusieurs détecteurs intégrés que vous pouvez utiliser: accepte le mimetype 'application/xml' ou 'text/xml'. ``ServerRequest`` inclut aussi des méthodes comme -:php:meth:`Cake\\Http\\ServerRequest::domain()`, -:php:meth:`Cake\\Http\\ServerRequest::subdomains()` -et :php:meth:`Cake\\Http\\ServerRequest::host()` qui facilitent la vie des +:php:meth:`\\Cake\\Http\\ServerRequest::domain()`, +:php:meth:`\\Cake\\Http\\ServerRequest::subdomains()` +et :php:meth:`\\Cake\\Http\\ServerRequest::host()` qui facilitent la vie des applications avec sous-domaines. @@ -616,7 +616,7 @@ Les cookies de la requête peuvent être lus à travers plusieurs méthodes:: // Récupère une instance de CookieCollection $cookies = $this->request->getCookieCollection() -Référez-vous à la documentation de :php:class:`Cake\\Http\\Cookie\\CookieCollection` +Référez-vous à la documentation de :php:class:`\\Cake\\Http\\Cookie\\CookieCollection` pour savoir comment travailler avec les collections de cookies. Fichiers uploadés @@ -657,17 +657,17 @@ Response .. php:class:: Response -:php:class:`Cake\\Http\\Response` est la classe de réponse par défaut dans +:php:class:`\\Cake\\Http\\Response` est la classe de réponse par défaut dans CakePHP. Elle encapsule un nombre de fonctionnalités et de caractéristiques pour la génération de réponses HTTP dans votre application. Elle aide aussi à tester des objets factices (mocks/stubs), vous permettant d'inspecter les en-têtes qui vont être envoyés. -:php:class:`Cake\\Http\\ServerRequest`, :php:class:`Cake\\Http\\Response` +:php:class:`\\Cake\\Http\\ServerRequest`, :php:class:`\\Cake\\Http\\Response` consolide un certain nombre de méthodes qu'on pouvait trouver avant dans :php:class:`Controller`, :php:class:`RequestHandlerComponent` et :php:class:`Dispatcher`. Les anciennes méthodes sont dépréciées en faveur de l'utilisation de -:php:class:`Cake\\Http\\Response`. +:php:class:`\\Cake\\Http\\Response`. ``Response`` fournit une interface pour envelopper les tâches de réponse communes liées, telles que: @@ -683,7 +683,7 @@ Gérer les Types de Contenu .. php:method:: withType($contentType = null) Vous pouvez contrôler le Content-Type des réponses de votre application en -utilisant :php:meth:`Cake\\Http\\Response::withType()`. Si votre application a +utilisant :php:meth:`\\Cake\\Http\\Response::withType()`. Si votre application a besoin de gérer les types de contenu qui ne sont pas construits dans Response, vous pouvez faire correspondre ces types avec ``setTypeMap()`` comme ceci:: @@ -706,7 +706,7 @@ Envoyer des fichiers .. php:method:: withFile($path, $options = []) Il y a des moments où vous souhaitez envoyer des fichiers en réponse à vos demandes. -Vous pouvez accomplir cela en utilisant :php:meth:`Cake\\Http\\Response::withFile()`:: +Vous pouvez accomplir cela en utilisant :php:meth:`\\Cake\\Http\\Response::withFile()`:: public function sendFile($id) { @@ -720,8 +720,8 @@ Vous pouvez accomplir cela en utilisant :php:meth:`Cake\\Http\\Response::withFil Comme indiqué dans l'exemple ci-dessus, vous devez transmettre le chemin du fichier à la méthode. CakePHP enverra un en-tête de type de contenu approprié s'il s'agit d'un type de fichier connu répertorié dans `Cake\\Http\\Response::$_mimeTypes`. Vous pouvez ajouter de nouveaux types avant d'appeler -:php:meth:`Cake\\Http\\Response::withFile()` en utilisant la méthode -:php:meth:`Cake\\Http\\Response::withType()`. +:php:meth:`\\Cake\\Http\\Response::withFile()` en utilisant la méthode +:php:meth:`\\Cake\\Http\\Response::withType()`. Si vous le souhaitez, vous pouvez également forcer le téléchargement d'un fichier au lieu de l'afficher dans le navigateur en spécifiant les options:: @@ -778,7 +778,7 @@ Définir les En-têtes .. php:method:: withHeader($header, $value) -La définition de headers se fait avec la méthode :php:meth:`Cake\\Http\\Response::withHeader()`. +La définition de headers se fait avec la méthode :php:meth:`\\Cake\\Http\\Response::withHeader()`. Comme toutes les méthodes de l'interface PSR-7, cette méthode retourne une nouvelle instance avec le nouvel header:: @@ -795,7 +795,7 @@ nouvelle instance avec le nouvel header:: Les headers ne sont pas envoyés dès que vous les définissez. Ils sont stockés jusqu'à ce que la réponse soit émise par ``Cake\Http\Server``. -Vous pouvez maintenant utiliser la méthode :php:meth:`Cake\\Http\\Response::withLocation()` +Vous pouvez maintenant utiliser la méthode :php:meth:`\\Cake\\Http\\Response::withLocation()` pour définir ou obtenir directement le header "redirect location". Définir le Corps de la réponse @@ -863,7 +863,7 @@ Interagir avec le Cache du Navigateur Parfois, vous avez besoin de forcer les navigateurs à ne pas mettre en cache les résultats de l'action d'un controller. -:php:meth:`Cake\\Http\\Response::withDisabledCache()` est justement prévue pour +:php:meth:`\\Cake\\Http\\Response::withDisabledCache()` est justement prévue pour cela:: public function index() @@ -881,7 +881,7 @@ cela:: .. php:method:: withCache($since, $time = '+1 day') Vous pouvez aussi dire aux clients que vous voulez qu'ils mettent en cache -des réponses. En utilisant :php:meth:`Cake\\Http\\Response::withCache()`:: +des réponses. En utilisant :php:meth:`\\Cake\\Http\\Response::withCache()`:: public function index() { @@ -911,7 +911,7 @@ Plutôt que d'avoir à coder la logique de mise en cache et de sa désactivation méthodes, l'expiration et la validation qui sont habituellement beaucoup plus simples à utiliser. -En dehors de l'utilisation de :php:meth:`Cake\\Http\\Response::withCache()`, vous +En dehors de l'utilisation de :php:meth:`\\Cake\\Http\\Response::withCache()`, vous pouvez également utiliser d'autres méthodes pour régler finement les en-têtes de cache HTTP et ainsi tirer profit du cache du navigateur ou du proxy inverse. @@ -1082,7 +1082,7 @@ Définir des Cookies ------------------- Des cookies peuvent être ajoutés aux réponses en utilisant soit un tableau, soit -un objet :php:class:`Cake\\Http\\Cookie\\Cookie`:: +un objet :php:class:`\\Cake\\Http\\Cookie\\Cookie`:: use Cake\Http\Cookie\Cookie; use DateTime; diff --git a/fr/core-libraries/caching.rst b/fr/core-libraries/caching.rst index 297450ad5e..3268a31116 100644 --- a/fr/core-libraries/caching.rst +++ b/fr/core-libraries/caching.rst @@ -44,7 +44,7 @@ votre propre système de mise en cache. Les moteurs de cache intégrés sont: opérations atomiques. Quelque soit le moteur de cache que vous choisirez d'utiliser, votre -application interagit avec :php:class:`Cake\\Cache\\Cache` de manière cohérente. +application interagit avec :php:class:`\\Cake\\Cache\\Cache` de manière cohérente. Cela signifie que vous pouvez aisément permuter les moteurs de cache en fonction de l'évolution de votre application. @@ -133,8 +133,8 @@ Vous pouvez également configurer les moteurs de cache pendant l'exécution:: En insérant le code ci-dessus dans votre **config/app.php** vous aurez deux configurations de cache supplémentaires. Le nom de ces configurations 'short' ou 'long' est utilisé comme paramètre ``$config`` -pour :php:meth:`Cake\\Cache\\Cache::write()` et -:php:meth:`Cake\\Cache\\Cache::read()`. Lors de la configuration des moteurs +pour :php:meth:`\\Cake\\Cache\\Cache::write()` et +:php:meth:`\\Cake\\Cache\\Cache::read()`. Lors de la configuration des moteurs de cache, vous pouvez vous référer au nom de la classe en utilisant les syntaxes suivantes: @@ -189,8 +189,8 @@ Suppression de Configuration de Cache Une fois la configuration créée, vous ne pouvez pas la changer. Au lieu de cela, vous devriez supprimer la configuration et la re-créer à l'aide de -:php:meth:`Cake\\Cache\\Cache::drop()` et -:php:meth:`Cake\\Cache\\Cache::config()`. +:php:meth:`\\Cake\\Cache\\Cache::drop()` et +:php:meth:`\\Cake\\Cache\\Cache::config()`. Supprimer un moteur de cache va supprimer la configuration et détruire l'adaptateur s'il a été construit. @@ -407,7 +407,7 @@ Vous pouvez considérablement améliorer les performances de votre application e mettant dans le cache les résultats qui changent rarement, ou qui sont soumis à de nombreuses lectures. Un exemple parfait serait les résultats de -:php:meth:`Cake\\ORM\\Table::find()`. l'objet Query vous permet de mettre les +:php:meth:`\\Cake\\ORM\\Table::find()`. l'objet Query vous permet de mettre les résultats en cache en utilisant la méthode ``cache``. Voir la section :ref:`mettre les résultats de requête en cache ` pour plus d'information. @@ -518,7 +518,7 @@ notation par points de plugin:: ]); Les moteurs de cache personnalisés doivent étendre -:php:class:`Cake\\Cache\\CacheEngine` qui définit un certain nombre de méthodes +:php:class:`\\Cake\\Cache\\CacheEngine` qui définit un certain nombre de méthodes d'abstraction ainsi que quelques méthodes d'initialisation. L'API requise pour CacheEngine est diff --git a/fr/core-libraries/form.rst b/fr/core-libraries/form.rst index 114fe05405..ef904dfb8b 100644 --- a/fr/core-libraries/form.rst +++ b/fr/core-libraries/form.rst @@ -63,7 +63,7 @@ les formulaires: FormHelper pour créer le formulaire HTML. Vous pouvez définir le type de champ, la longueur et la précision. * ``_buildValidator`` Récupère une instance de - :php:class:`Cake\\Validation\\Validator` à laquelle vous pouvez attacher des + :php:class:`\\Cake\\Validation\\Validator` à laquelle vous pouvez attacher des validateurs. * ``_execute`` vous permet de définir le comportement que vous souhaitez lorsque ``execute()`` est appelée et que les données sont valides. diff --git a/fr/core-libraries/global-constants-and-functions.rst b/fr/core-libraries/global-constants-and-functions.rst index 65839ef73c..df322de615 100644 --- a/fr/core-libraries/global-constants-and-functions.rst +++ b/fr/core-libraries/global-constants-and-functions.rst @@ -95,7 +95,7 @@ la traduction de contenu. .. php:function:: collection(mixed $items) - Vous permet d'instancier un objet :php:class:`Cake\\Collection\\Collection` + Vous permet d'instancier un objet :php:class:`\\Cake\\Collection\\Collection` et wrap l'argument passé. le paramètre ``$items`` accepte soit un objet ``Traversable`` soit un tableau. diff --git a/fr/core-libraries/hash.rst b/fr/core-libraries/hash.rst index 7f65d732b9..1156d3945b 100644 --- a/fr/core-libraries/hash.rst +++ b/fr/core-libraries/hash.rst @@ -526,7 +526,7 @@ Les Types d'Attribut Correspondants ]; */ -.. php:staticmethod:: merge(array $data, array $merge[, array $n]) +.. php:staticmethod:: merge(array $data, array $merge) Cette fonction peut être vue comme un hybride entre le ``array_merge`` et le ``array_merge_recursive`` de PHP. La différence entre les deux est que @@ -580,6 +580,7 @@ Les Types d'Attribut Correspondants */ .. php:staticmethod:: numeric(array $data) + Vérifie pour voir si toutes les valeurs dans le tableau sont numériques:: $data = ['one']; @@ -590,7 +591,7 @@ Les Types d'Attribut Correspondants $res = Hash::numeric($data); // $res est à false -.. php:staticmethod:: dimensions (array $data) +.. php:staticmethod:: dimensions(array $data) Compte les dimensions d'un tableau. Cette méthode va seulement considérer la dimension du premier élément dans le tableau:: diff --git a/fr/core-libraries/logging.rst b/fr/core-libraries/logging.rst index d6a87d8ff1..1e45a2ebba 100755 --- a/fr/core-libraries/logging.rst +++ b/fr/core-libraries/logging.rst @@ -26,7 +26,7 @@ Configuration des flux d'un log (journal) La configuration de ``Log`` doit être faite pendant la phase de bootstrap de votre application. Le fichier **config/app.php** est justement prévu pour ceci. Vous pouvez définir autant de jounaux que votre application nécessite. -Les journaux doivent être configurés en utilisant :php:class:`Cake\\Log\\Log`. +Les journaux doivent être configurés en utilisant :php:class:`\\Cake\\Log\\Log`. Un exemple serait:: use Cake\Log\Engine\FileLog; @@ -106,7 +106,7 @@ Ecrire dans les logs ==================== Ecrire dans les fichiers peut être réalisé de deux façons. La première est -d'utiliser la méthode statique :php:meth:`Cake\\Log\\Log::write()`:: +d'utiliser la méthode statique :php:meth:`\\Cake\\Log\\Log::write()`:: Log::write('debug', 'Quelque chose ne fonctionne pas'); @@ -118,7 +118,7 @@ interne ``Log::write()``:: $this->log("Quelque chose ne fonctionne pas!", 'debug'); Tous les flux de log configurés sont écrits séquentiellement à chaque fois -que :php:meth:`Cake\\Log\\Log::write()` est appelée. Si vous n'avez pas +que :php:meth:`\\Cake\\Log\\Log::write()` est appelée. Si vous n'avez pas configuré de moteurs de log, ``log()`` va retourner false et aucun message de log ne sera écrit. diff --git a/fr/core-libraries/number.rst b/fr/core-libraries/number.rst index 0196c31997..c7f6efbfce 100644 --- a/fr/core-libraries/number.rst +++ b/fr/core-libraries/number.rst @@ -108,7 +108,7 @@ Paramétrage de la Devise par Défaut .. php:method:: defaultCurrency(string $currency) Setter/getter pour la monnaie par défaut. Ceci retire la nécessité de -toujours passer la monnaie à :php:meth:`Cake\\I18n\\Number::currency()` et +toujours passer la monnaie à :php:meth:`\\Cake\\I18n\\Number::currency()` et change toutes les sorties de monnaie en définissant les autres par défaut. Si ``$currency`` est ``false``, cela effacera la valeur actuellement enregistrée. @@ -145,7 +145,7 @@ Formatage Des Pourcentages | | avec décimale. | +---------------------+----------------------------------------------------+ -Comme :php:meth:`Cake\\I18n\\Number::precision()`, cette méthode formate un +Comme :php:meth:`\\Cake\\I18n\\Number::precision()`, cette méthode formate un nombre selon la précision fournie (où les nombres sont arrondis pour parvenir à ce degré de précision). Cette méthode exprime aussi le nombre en tant que pourcentage et ajoute un signe de pourcent à la sortie:: diff --git a/fr/core-libraries/security.rst b/fr/core-libraries/security.rst index b6bf28b38b..8bcd30a362 100644 --- a/fr/core-libraries/security.rst +++ b/fr/core-libraries/security.rst @@ -40,7 +40,7 @@ Un exemple d'utilisation serait:: Si vous ne fournissez pas de sel HMAC, la valeur ``Security.salt`` sera utilisée. Les valeurs chiffrées peuvent être déchiffrées avec -:php:meth:`Cake\\Utility\\Security::decrypt()`. +:php:meth:`\\Cake\\Utility\\Security::decrypt()`. Déchiffre une valeur chiffrée au préalable. Les paramètres ``$key`` et ``$hmacSalt`` doivent correspondre aux valeurs utilisées pour chiffrer ou diff --git a/fr/core-libraries/validation.rst b/fr/core-libraries/validation.rst index 0c13a8eadd..82fb2eb91d 100644 --- a/fr/core-libraries/validation.rst +++ b/fr/core-libraries/validation.rst @@ -498,7 +498,7 @@ les règles pour le mode 'create' mode. Si vous voulez appliquer les règles :php:meth:`~Cake\\ORM\\Table::newEntities()`, :php:meth:`~Cake\\ORM\\Table::patchEntity()`, :php:meth:`~Cake\\ORM\\Table::patchEntities()` or - :php:meth:`~Cake\\ORM\\Table::save()` puisqu'elles ont été créées pour cela. + :php:meth:`\\Cake\\ORM\\Table::save()` puisqu'elles ont été créées pour cela. Valider les Entities ==================== diff --git a/fr/core-libraries/xml.rst b/fr/core-libraries/xml.rst index 06922ec8cb..1f6458900b 100644 --- a/fr/core-libraries/xml.rst +++ b/fr/core-libraries/xml.rst @@ -62,7 +62,7 @@ Si votre entrée est invalide, la classe Xml enverra une Exception:: Transformer une Chaîne de Caractères XML en Tableau =================================================== -.. php:staticmethod:: toArray($obj); +.. php:staticmethod:: toArray($obj) Convertir des chaînes XML en tableaux est aussi facile avec la classe Xml. Par défaut, vous obtiendrez un objet SimpleXml en retour:: diff --git a/fr/development/debugging.rst b/fr/development/debugging.rst index a707f1a0e0..ab32ce6810 100644 --- a/fr/development/debugging.rst +++ b/fr/development/debugging.rst @@ -162,7 +162,7 @@ Utiliser les Logs pour Debugger =============================== Logger des messages est une autre bonne façon de debugger les applications, -et vous pouvez utiliser :php:class:`Cake\\Log\\Log` pour faire le logging dans +et vous pouvez utiliser :php:class:`\\Cake\\Log\\Log` pour faire le logging dans votre application. Tous les objets qui utilisent ``LogTrait`` ont une méthode d'instanciation ``log()`` qui peut être utilisée pour logger les messages:: @@ -171,7 +171,7 @@ d'instanciation ``log()`` qui peut être utilisée pour logger les messages:: Ce qui est au-dessus écrit ``Got here`` dans le log de debug. Vous pouvez utiliser les logs (log entries) pour faciliter le debug des méthodes qui impliquent des redirections ou des boucles compliquées. Vous pouvez aussi -utiliser :php:meth:`Cake\\Log\\Log::write()`` pour écrire les messages de log. +utiliser :php:meth:`\\Cake\\Log\\Log::write()`` pour écrire les messages de log. Cette méthode peut être appelée statiquement partout dans votre application où Log a été chargée:: diff --git a/fr/development/errors.rst b/fr/development/errors.rst index d60bd70e56..926834e59b 100644 --- a/fr/development/errors.rst +++ b/fr/development/errors.rst @@ -31,7 +31,7 @@ pour votre application. Les options proposées sont les suivantes: vous devrez placer le fichier de cette classe dans le dossier **src/Error**. Cette classe doit implémenter une méthode ``render()``. * ``log`` - bool - Si ``true``, les exceptions et leur stack traces seront - loguées vers :php:class:`Cake\\Log\\Log`. + loguées vers :php:class:`\\Cake\\Log\\Log`. * ``skipLog`` - array - Un tableau des noms de classe d'exception qui ne doivent pas être mises dans des fichiers de log. C'est utile pour supprimer les NotFoundExceptions ou toute autre message de log sans intérêt. @@ -497,7 +497,7 @@ Logger des Exceptions Avec la gestion d'erreurs intégrée, vous pouvez faire logger par ErrorHandler toutes les exceptions auxquelles vous aurez affaire en définissant l'option ``log`` à ``true`` dans votre **config/app.php**. Le fait de l'activer va logger -toutes les exceptions dans :php:class:`Cake\\Log\\Log` et les loggers +toutes les exceptions dans :php:class:`\\Cake\\Log\\Log` et les loggers configurés. .. note:: @@ -716,8 +716,8 @@ De plus, CakePHP utilise les exceptions suivantes: .. php:exception:: PersistenceFailedException - Une entity n'a pas pu être sauvegardée / supprimée en utilisant :php:meth:`Cake\\ORM\\Table::saveOrFail()` ou - :php:meth:`Cake\\ORM\\Table::deleteOrFail()` + Une entity n'a pas pu être sauvegardée / supprimée en utilisant :php:meth:`\\Cake\\ORM\\Table::saveOrFail()` ou + :php:meth:`\\Cake\\ORM\\Table::deleteOrFail()` .. php:namespace:: Cake\Datasource\Exception diff --git a/fr/development/rest.rst b/fr/development/rest.rst index 91db7a31bc..4a3f15a507 100644 --- a/fr/development/rest.rst +++ b/fr/development/rest.rst @@ -7,18 +7,18 @@ Fournir un accès sans entrave à votre API du cœur peut aider à ce que votre plateforme soit acceptée, et permettre les mashups et une intégration facile avec les autres systèmes. -CakePHP propose des méthodes pour exposer les actions de votre controller via -des méthodes HTTP et pour sérialiser les variables de vue en fonction de la -négociation du type de contenu. La négociation du type de contenu permet aux -clients de votre application d’envoyer des requêtes avec des données sérialisées +CakePHP propose des méthodes pour exposer les actions de votre controller via +des méthodes HTTP et pour sérialiser les variables de vue en fonction de la +négociation du type de contenu. La négociation du type de contenu permet aux +clients de votre application d’envoyer des requêtes avec des données sérialisées et de recevoir des réponses avec des données sérialisées via les en-têtes ``Accept`` et ``Content-Type``, ou des extensions d’URL. Mise en place Simple ==================== -Pour commencer à ajouter une API REST à votre application, nous aurons d’abord -besoin d’un controller contenant les actions que nous voulons exposer en tant +Pour commencer à ajouter une API REST à votre application, nous aurons d’abord +besoin d’un controller contenant les actions que nous voulons exposer en tant qu’API. Un controller de base pourrait ressembler à ceci:: // src/Controller/RecipesController.php @@ -91,10 +91,10 @@ qu’API. Un controller de base pourrait ressembler à ceci:: } } -Dans notre ``RecipesController``, nous avons plusieurs actions qui définissent la logique -pour créer, modifier, visualiser et supprimer des recettes. Dans chacune de nos actions, -nous utilisons l’option ``serialize`` pour indiquer à CakePHP quelles variables de vue doivent -être sérialisées lors de la création des réponses API. Nous connecterons notre controller aux +Dans notre ``RecipesController``, nous avons plusieurs actions qui définissent la logique +pour créer, modifier, visualiser et supprimer des recettes. Dans chacune de nos actions, +nous utilisons l’option ``serialize`` pour indiquer à CakePHP quelles variables de vue doivent +être sérialisées lors de la création des réponses API. Nous connecterons notre controller aux URL de l’application avec le :ref:`resource-routes`:: // in config/routes.php @@ -103,50 +103,50 @@ URL de l’application avec le :ref:`resource-routes`:: $routes->resources('Recipes'); }); -Ces routes permettront aux URL comme ``/recipes.json`` de renvoyer une réponse encodée en JSON. -Les clients pourront également faire une requête à ``/recipes`` avec l’en-tête +Ces routes permettront aux URL comme ``/recipes.json`` de renvoyer une réponse encodée en JSON. +Les clients pourront également faire une requête à ``/recipes`` avec l’en-tête ``Content-Type: application/json``. Encodage des données de réponse =============================== -Dans le controlleur ci-dessus, nous définissons une méthode ``viewClasses()``. Cette méthode -définit les vues dont votre controller dispose pour la négociation de contenu. Nous incluons -``JsonView`` de CakePHP qui permet des réponses basées sur JSON. Pour en savoir plus à ce sujet et -sur les vues basées sur XML, consultez :doc:`/views/json-and-xml-views`. Ceci est utilisé par +Dans le controlleur ci-dessus, nous définissons une méthode ``viewClasses()``. Cette méthode +définit les vues dont votre controller dispose pour la négociation de contenu. Nous incluons +``JsonView`` de CakePHP qui permet des réponses basées sur JSON. Pour en savoir plus à ce sujet et +sur les vues basées sur XML, consultez :doc:`/views/json-and-xml-views`. Ceci est utilisé par CakePHP pour sélectionner une classe de vue avec laquelle restituer une réponse REST. -Ensuite, nous disposons de plusieurs méthodes qui exposent la logique de base pour créer, -modifier, afficher et supprimer des recettes. Dans chacune de nos actions, nous utilisons -l'option ``serialize`` pour indiquer à CakePHP quelles variables de vue doivent être sérialisées +Ensuite, nous disposons de plusieurs méthodes qui exposent la logique de base pour créer, +modifier, afficher et supprimer des recettes. Dans chacune de nos actions, nous utilisons +l'option ``serialize`` pour indiquer à CakePHP quelles variables de vue doivent être sérialisées lors des réponses API. -Si nous souhaitons modifier les données avant qu'elles ne soient converties en JSON, -nous ne devons pas définir l'option de ``serialize``, mais plutôt utiliser des fichiers modèles. +Si nous souhaitons modifier les données avant qu'elles ne soient converties en JSON, +nous ne devons pas définir l'option de ``serialize``, mais plutôt utiliser des fichiers modèles. Nous placerions les modèles REST pour notre RecipesController dans **templates/Recipes/json**. -Voir :ref:`controller-viewclasses` pour plus d'informations sur la fonctionnalité de négociation +Voir :ref:`controller-viewclasses` pour plus d'informations sur la fonctionnalité de négociation de réponse de CakePHP. Parsing des corps de requête ============================ -La création de la logique de l'action de modification nécessite une autre étape. Parce -que nos ressources sont sérialisées au format JSON, il serait ergonomique si nos requêtes +La création de la logique de l'action de modification nécessite une autre étape. Parce +que nos ressources sont sérialisées au format JSON, il serait ergonomique si nos requêtes contenaient également la représentation JSON. Dans notre classe ``Application``, assurez-vous que les éléments suivants sont présents:: $middlewareQueue->add(new BodyParserMiddleware()); -Ce middleware utilisera l'en-tête ``content-type`` pour détecter le format des données -de requête et analyser les formats activés. Par défaut, seule l'analyse ``JSON`` est activée -par défaut. Vous pouvez activer la prise en charge XML en activant l'option du -constructeur XML. Lorsqu'une requête est effectuée avec un ``Content-Type`` ``application/json``, -CakePHP décodera les données de la requête et mettra à jour la requête afin +Ce middleware utilisera l'en-tête ``content-type`` pour détecter le format des données +de requête et analyser les formats activés. Par défaut, seule l'analyse ``JSON`` est activée +par défaut. Vous pouvez activer la prise en charge XML en activant l'option du +constructeur XML. Lorsqu'une requête est effectuée avec un ``Content-Type`` ``application/json``, +CakePHP décodera les données de la requête et mettra à jour la requête afin que ``$request->getData()`` contienne le corps analysé. -Vous pouvez également câbler des désérialiseurs supplémentaires pour des formats alternatifs +Vous pouvez également câbler des désérialiseurs supplémentaires pour des formats alternatifs si vous en avez besoin, en utilisant :php:meth:`BodyParserMiddleware::addParser()`. .. meta:: diff --git a/fr/development/routing.rst b/fr/development/routing.rst index 68fc6ccdb0..17553ecb1f 100644 --- a/fr/development/routing.rst +++ b/fr/development/routing.rst @@ -1334,7 +1334,7 @@ Générer des URLs ================ .. php:staticmethod:: url($url = null, $full = false) -.. php:staticmethod:: reverse($params, $full = fals +.. php:staticmethod:: reverse($params, $full = false) La génération d'URL ou le routing inversé est une fonctionnalité dans CakePHP qui est utilisée pour vous permettre de changer votre structure d'URL sans avoir à modifier tout votre @@ -1649,7 +1649,7 @@ inversé. Les classes de route suivent quelques conventions: * Les classes de Route doivent se trouver dans le namespace ``Routing\\Route`` de votre application ou plugin. -* Les classes de Route doivent étendre :php:class:`Cake\\Routing\\Route\\Route`. +* Les classes de Route doivent étendre :php:class:`\\Cake\\Routing\\Route\\Route`. * Les classes de Route doivent implémenter au moins un des méthodes ``match()`` et/ou ``parse()``. diff --git a/fr/development/sessions.rst b/fr/development/sessions.rst index 9dd64a941c..11f6d16122 100644 --- a/fr/development/sessions.rst +++ b/fr/development/sessions.rst @@ -309,7 +309,7 @@ devrait ressembler à:: Notre classe étend la classe intégrée ``DatabaseSession`` donc nous ne devons pas dupliquer toute sa logique et son comportement. Nous entourons chaque -opération avec une opération :php:class:`Cake\\Cache\\Cache`. Cela nous permet +opération avec une opération :php:class:`\\Cake\\Cache\\Cache`. Cela nous permet de récupérer les sessions de la mise en cache rapide, et nous évite de nous inquiéter sur ce qui arrive quand nous remplissons le cache. Dans votre **config/app.php**, écrivez un block de session comme ceci:: diff --git a/fr/development/testing.rst b/fr/development/testing.rst index 2bd4de489e..56ffd319fe 100755 --- a/fr/development/testing.rst +++ b/fr/development/testing.rst @@ -1379,8 +1379,8 @@ seraient présents dans une requête normale, vous devez non seulement les passe dans les données de la requête, mais aussi les passer dans la configuration de la requête de test via l'option ``files``. Ce n'est toutefois pas techniquement nécessaire, sauf si votre code accède aux fichiers téléversés via les méthodes -:php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` ou -:php:meth:`Cake\\Http\\ServerRequest::getUploadedFiles()`. +:php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` ou +:php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFiles()`. Supposons que les articles aient une image d'accroche, et une association ``Articles hasMany Attachments``. Le formulaire ressemblerait à quelque chose diff --git a/fr/orm/database-basics.rst b/fr/orm/database-basics.rst index 96d690c848..e196f1047b 100644 --- a/fr/orm/database-basics.rst +++ b/fr/orm/database-basics.rst @@ -301,7 +301,7 @@ Accéder à des Connexions .. php:staticmethod:: get($name) Une fois configurées, les connexions peuvent être récupérées en utilisant -:php:meth:`Cake\\Datasource\\ConnectionManager::get()`. Cette méthode va +:php:meth:`\\Cake\\Datasource\\ConnectionManager::get()`. Cette méthode va construire et charger une connexion si elle n'a pas été déjà construite avant, ou retourner la connexion connue existante:: @@ -390,7 +390,7 @@ binary Correspond au type ``BLOB`` ou ``BYTEA`` fourni par la base de données. date Correspond au type de colonne natif ``DATE``. La valeur de retour de ce - type de colonne est :php:class:`Cake\\I18n\\Date` qui étend la classe + type de colonne est :php:class:`\\Cake\\I18n\\Date` qui étend la classe native ``DateTime``. datetime Consultez :ref:`datetime-type`. @@ -1037,7 +1037,7 @@ log de requêtes à la volée, en utilisant ``enableQueryLogging``:: $connection->enableQueryLogging(false); Quand les logs de requêtes sont activés, les requêtes sont loguées dans -:php:class:`Cake\\Log\\Log` en utilisant le niveau 'debug', et le scope +:php:class:`\\Cake\\Log\\Log` en utilisant le niveau 'debug', et le scope 'queriesLog'. Vous aurez besoin d'avoir un logger configuré pour capter ce niveau et ce scope. Faire des logs vers ``stderr`` peut être utile lorsque vous travaillez sur les tests unitaires, et les logs de fichiers/syslog peuvent être diff --git a/fr/orm/deleting-data.rst b/fr/orm/deleting-data.rst index 439433e629..6308a1657f 100644 --- a/fr/orm/deleting-data.rst +++ b/fr/orm/deleting-data.rst @@ -42,7 +42,7 @@ Quand les entities sont supprimées, les données associées peuvent aussi être supprimées. Si vos associations HasOne et HasMany sont configurées avec ``dependent``, les opérations de suppression se feront aussi en 'cascade' sur leurs entitites. Par défaut, les entities dans les tables associées sont -retirées en utilisant :php:meth:`Cake\\ORM\\Table::deleteAll()`. Vous pouvez +retirées en utilisant :php:meth:`\\Cake\\ORM\\Table::deleteAll()`. Vous pouvez choisir que l'ORM charge les entities liées et les supprime individuellement en configurant l'option ``cascadeCallbacks`` à ``true``. Un exemple d'association HasMany avec ces deux options activées serait:: @@ -89,7 +89,7 @@ Suppressions strictes .. php:method:: deleteOrFail($entity, $options = []) -Utiliser cette méthode lancera une :php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` +Utiliser cette méthode lancera une :php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` si: * l'entity est _new_ (si elle n'a jamais été persistée) @@ -106,5 +106,5 @@ utiliser la méthode :php:meth:`Cake\\ORM\Exception\\PersistenceFailedException: echo $e->getEntity(); } -Puisque cette méthode utilise la méthode :php:meth:`Cake\\ORM\\Table::delete()`, +Puisque cette méthode utilise la méthode :php:meth:`\\Cake\\ORM\\Table::delete()`, tous les événements de ``delete`` seront déclenchés. diff --git a/fr/orm/query-builder.rst b/fr/orm/query-builder.rst index c0e008f675..61d2d56af0 100644 --- a/fr/orm/query-builder.rst +++ b/fr/orm/query-builder.rst @@ -51,7 +51,7 @@ Récupérer les Lignes d'une Table } Pour les exemples restants, imaginez que ``$articles`` est une -:php:class:`~Cake\\ORM\\Table`. Quand vous êtes dans des controllers, vous +:php:class:`\\Cake\\ORM\\Table`. Quand vous êtes dans des controllers, vous pouvez utiliser ``$this->Articles`` plutôt que ``$articles``. Presque toutes les méthodes d'un objet ``Query`` retournent la requête @@ -1498,7 +1498,7 @@ méthode ``values()`` autant de fois que nécessaire:: ->execute(); Généralement, il est plus facile d'insérer des données en utilisant les -entities et :php:meth:`~Cake\\ORM\\Table::save()`. En composant des requêtes +entities et :php:meth:`\\Cake\\ORM\\Table::save()`. En composant des requêtes ``SELECT`` et ``INSERT`` ensemble, vous pouvez créer des requêtes du style ``INSERT INTO ... SELECT``:: @@ -1552,7 +1552,7 @@ requête en utilisant ``query()``:: ->execute(); Généralement, il est plus facile de supprimer les données en utilisant les -entities et :php:meth:`~Cake\\ORM\\Table::delete()`. +entities et :php:meth:`\\Cake\\ORM\\Table::delete()`. Prévention des Injections SQL ============================= diff --git a/fr/orm/saving-data.rst b/fr/orm/saving-data.rst index 0a2b4d606b..3cbe63f5af 100644 --- a/fr/orm/saving-data.rst +++ b/fr/orm/saving-data.rst @@ -1193,7 +1193,7 @@ Strict Saving .. php:method:: saveOrFail($entity, $options = []) L'appel à cette méthode lancera une -:php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` si: +:php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` si: * les règles de validation ont échoué * l'entity contient des erreurs @@ -1218,7 +1218,7 @@ utiliser la méthode :php:meth:`Cake\\ORM\Exception\\PersistenceFailedException: } Dans la mesure où cette méthode utilise la méthode -:php:meth:`Cake\\ORM\\Table::save()`, tous les événements de ``save`` seront +:php:meth:`\\Cake\\ORM\\Table::save()`, tous les événements de ``save`` seront déclenchés. Trouver Ou Créer une Entity diff --git a/fr/tutorials-and-examples/blog/part-two.rst b/fr/tutorials-and-examples/blog/part-two.rst index e0ce294da7..7966124e36 100755 --- a/fr/tutorials-and-examples/blog/part-two.rst +++ b/fr/tutorials-and-examples/blog/part-two.rst @@ -339,7 +339,7 @@ Chaque requête de CakePHP contient un objet ``ServerRequest`` qui est accessibl en utilisant ``$this->request``. Cet objet contient des informations utiles sur la requête qui vient d'être reçue, et permet de contrôler le flux de votre application. Dans ce cas, nous utilisons la méthode -:php:meth:`Cake\\Http\\ServerRequest::is()` pour vérifier que la requête est de +:php:meth:`\\Cake\\Http\\ServerRequest::is()` pour vérifier que la requête est de type POST. Lorsqu'un utilisateur utilise un formulaire pour poster des données dans votre diff --git a/fr/tutorials-and-examples/cms/articles-controller.rst b/fr/tutorials-and-examples/cms/articles-controller.rst index f0ba714d51..a7d0c503f0 100644 --- a/fr/tutorials-and-examples/cms/articles-controller.rst +++ b/fr/tutorials-and-examples/cms/articles-controller.rst @@ -243,7 +243,7 @@ Voici ce que l'action ``add()`` fait: Toutes les requêtes de CakePHP incluent un objet request qui est accessible via ``$this->request``. L'objet request contient des informations à propos de la requête qui vient d'être reçue. Nous utilisons la méthode -:php:meth:`Cake\\Http\\ServerRequest::is()` pour vérifier que la requête possède +:php:meth:`\\Cake\\Http\\ServerRequest::is()` pour vérifier que la requête possède bien le verbe HTTP POST. Les données passées en POST sont disponibles dans ``$this->request->getData()``. diff --git a/fr/views/helpers/form.rst b/fr/views/helpers/form.rst index bc4d7863e0..5b7af01253 100644 --- a/fr/views/helpers/form.rst +++ b/fr/views/helpers/form.rst @@ -471,9 +471,9 @@ vide. Vous pouvez désactiver les ``required`` automatiques en utilisant l'optio Pour empêcher la validation faite par le navigateur pour l'ensemble du formulaire, vous pouvez définir l'option ``'formnovalidate' => true`` pour le bouton input que vous générez en utilisant -:php:meth:`~Cake\\View\\Helper\\FormHelper::submit()` ou définir +:php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` ou définir ``'novalidate' => true`` dans les options pour -:php:meth:`~Cake\\View\\Helper\\FormHelper::create()`. +:php:meth:`\\Cake\\View\\Helper\\FormHelper::create()`. Par exemple, supposons que votre model User intègre les champs pour un *username* (varchar), *password* (varchar), *approved* (datetime) et @@ -536,7 +536,7 @@ données dans un `format CamelCase ``, ne l'utilisez pas à l'intérieur d'un formulaire ouvert. Utilisez plutôt -:php:meth:`Cake\\View\\Helper\\FormHelper::submit()` ou -:php:meth:`Cake\\View\\Helper\\FormHelper::button()` +:php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` ou +:php:meth:`\\Cake\\View\\Helper\\FormHelper::button()` pour créer des boutons à l'intérieur de formulaires ouvert. Créer des liens POST @@ -2200,8 +2200,8 @@ méthode à l'intérieur d'un formulaire existant, vous devez utiliser l'option qui peut être affiché en dehors du formulaire principal. Si vous souhaitez seulement créer un bouton pour soumettre votre formulaire, alors vous -devriez plutôt utiliser :php:meth:`Cake\\View\\Helper\\FormHelper::button()` -ou :php:meth:`Cake\\View\\Helper\\FormHelper::submit()`. +devriez plutôt utiliser :php:meth:`\\Cake\\View\\Helper\\FormHelper::button()` +ou :php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()`. .. note:: @@ -2626,7 +2626,7 @@ widget en utilisant la méthode magique:: Travailler avec SecurityComponent ================================= -:php:meth:`Cake\\Controller\\Component\\SecurityComponent` offre plusieurs +:php:meth:`\\Cake\\Controller\\Component\\SecurityComponent` offre plusieurs fonctionnalités qui rendent vos formulaires plus sûrs et plus sécurisés. En incluant simplement le ``SecurityComponent`` dans votre controller, vous bénéficierez automatiquement des fonctionnalités de prévention @@ -2634,7 +2634,7 @@ contre la falsification de formulaires. Comme mentionné précédemment, lorsque vous utilisez le SecurityComponent, vous devez toujours fermer vos formulaires en utilisant -:php:meth:`~Cake\\View\\Helper\\FormHelper::end()`. Cela assurera que les +:php:meth:`\\Cake\\View\\Helper\\FormHelper::end()`. Cela assurera que les inputs spéciales ``_Token`` soient générées. .. php:method:: unlockField($name) diff --git a/fr/views/helpers/html.rst b/fr/views/helpers/html.rst index 397242a6bb..88dea55f2a 100644 --- a/fr/views/helpers/html.rst +++ b/fr/views/helpers/html.rst @@ -408,7 +408,7 @@ Affichera: Brownies -Regardez aussi la méthode :php:meth:`Cake\\View\\Helper\\UrlHelper::build()` pour +Regardez aussi la méthode :php:meth:`\\Cake\\View\\Helper\\UrlHelper::build()` pour plus d'exemples des différents types d'URLs. Liens vers des Videos et Fichiers Audio @@ -830,7 +830,7 @@ Vous pouvez aussi récupérer le fil d'Ariane en tant que liste Html:: echo $this->Html->getCrumbList(); -Cette méthode utilise :php:meth:`Cake\\View\\Helper\\HtmlHelper::tag()` pour +Cette méthode utilise :php:class:`\\Cake\\View\\Helper\\HtmlHelper::tag()` pour générer la liste et ses éléments. Fonctionne de la même manière que :php:meth:`~Cake\\View\\Helper\\HtmlHelper::getCrumbs()`, il utilise toutes les options que chacun des fils a ajouté. Vous pouvez utiliser le paramètre @@ -854,7 +854,7 @@ spécifiques, vous avez: 'Home' ); -Cette méthode utilise :php:meth:`Cake\\View\\Helper\\HtmlHelper::tag()` pour +Cette méthode utilise :php:class:`\\Cake\\View\\Helper\\HtmlHelper::tag()` pour générer une liste et ses éléments. Fonctionne de la même manière que :php:meth:`~Cake\\View\\Helper\\HtmlHelper::getCrumbs()`, donc elle utilise des options pour lesquelles chaque crumb a été ajouté. Vous pouvez utiliser le diff --git a/fr/views/helpers/time.rst b/fr/views/helpers/time.rst index dcbc762452..b0ddfea2a7 100644 --- a/fr/views/helpers/time.rst +++ b/fr/views/helpers/time.rst @@ -42,7 +42,7 @@ pouvons corriger la date et le temps de nos posts en utilisant le TimeHelper:: La plupart des fonctionnalités de TimeHelper sont des interfaces rétro-compatibles pour les applications qui sont mises à jour à partir des versions anciennes de CakePHP. Comme l'ORM retourne des instances -:php:class:`Cake\\I18n\\Time` pour chaque colonne ``timestamp`` et ``datetime``, +:php:class:`\\Cake\\I18n\\Time` pour chaque colonne ``timestamp`` et ``datetime``, vous pouvez utiliser les méthodes ici pour faire la plupart des tâches. Par exemple, pour en apprendre plus sur les chaines de formatage, jetez un oeil à la méthode `Cake\\I18n\\Time::i18nFormat() diff --git a/fr/views/themes.rst b/fr/views/themes.rst index c22f9da95b..f609262381 100644 --- a/fr/views/themes.rst +++ b/fr/views/themes.rst @@ -54,7 +54,7 @@ Assets du theme Puisque les themes sont des plugins CakePHP standards, ils peuvent inclure tout asset nécessaire dans leur répertoire webroot. Cela permet de packager et distribuer les themes. En développement, les requêtes pour les assets de theme -seront gérées par :php:class:`Cake\\Routing\\Dispatcher`. Pour améliorer les +seront gérées par :php:class:`\\Cake\\Routing\\Dispatcher`. Pour améliorer les performances pour les environnements de production, il est recommandé d':ref:`améliorer les performances de votre application. `. diff --git a/ja/console-commands/option-parsers.rst b/ja/console-commands/option-parsers.rst index ff9c876c86..a38a958e1c 100644 --- a/ja/console-commands/option-parsers.rst +++ b/ja/console-commands/option-parsers.rst @@ -204,8 +204,8 @@ ConsoleOptionParser 上のビルダーメソッドと同様に、addOptions も パーサーの仕様の中では ``arguments``, ``options``, ``description`` そして ``epilog`` のための キーを定義できます。配列形式ビルダーの内部には ``subcommands`` は定義できません。 -引数とオプションの値は、 :php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` や -:php:func:`Cake\\Console\\ConsoleOptionParser::addOptions()` が利用する書式に従ってください。 +引数とオプションの値は、 :php:func:`\\Cake\\Console\\ConsoleOptionParser::addArguments()` や +:php:func:`\\Cake\\Console\\ConsoleOptionParser::addOptions()` が利用する書式に従ってください。 buildFromArray を単独で使ってオプションパーサーを構築することも可能です。 :: public function getOptionParser() diff --git a/ja/controllers.rst b/ja/controllers.rst index 24cd24f7c2..d78a11e353 100644 --- a/ja/controllers.rst +++ b/ja/controllers.rst @@ -34,7 +34,7 @@ AppController 冒頭で述べたように、 ``AppController`` クラスはアプリケーションのすべてのコントローラーの 親クラスとなります。 ``AppController`` はそれ自身、CakePHP のコアライブラリーに含まれる -:php:class:`Cake\\Controller\\Controller` クラスを継承しています。 +:php:class:`\\Cake\\Controller\\Controller` クラスを継承しています。 ``AppController`` は **src/Controller/AppController.php** に次のように定義されます。 :: namespace App\Controller; @@ -70,8 +70,8 @@ AppController リクエストの流れ ================ -CakePHP アプリケーションへのリクエストが生じると、 CakePHP の :php:class:`Cake\\Routing\\Router` -と :php:class:`Cake\\Routing\\Dispatcher` クラスは正しいコントローラーを見つけて、 +CakePHP アプリケーションへのリクエストが生じると、 CakePHP の :php:class:`\\Cake\\Routing\\Router` +と :php:class:`\\Cake\\Routing\\Dispatcher` クラスは正しいコントローラーを見つけて、 インスタンスを作成するために :ref:`routes-configuration` を使用します。 リクエストデータはリクエストオブジェトの中にカプセル化されています。 CakePHP はすべての重要なリクエスト情報を ``$this->request`` プロパティーの中に格納します。 @@ -119,7 +119,7 @@ CakePHP の規約に従うと、手動でビューを描画したり生成した 代わりに、コントローラーのアクションが完了すると、CakePHP はビューの描画と送信をします。 もし何らかの理由でデフォルトの動作をスキップさせたければ、完全にレスポンスを作成して、 -アクションから :php:class:`Cake\\Http\\Response` オブジェクトを返すこともできます。 +アクションから :php:class:`\\Cake\\Http\\Response` オブジェクトを返すこともできます。 アプリケーションでコントローラーを効率的に使うために、CakePHP のコントローラーから提供される いくつかのコアな属性やメソッドを説明しましょう。 @@ -541,7 +541,7 @@ CakePHP のコントローラーはリクエストのライフサイクル周り コントローラーのアクションロジックの後、ビューが描画される前に発動する ``Controller.beforeRender`` イベント中に呼ばれます。 このコールバックはそれほど使われませんが、もしアクション終了前に - :php:meth:`~Cake\\Controller\\Controller::render()` を手動で呼んでいれば + :php:meth:`\\Cake\\Controller\\Controller::render()` を手動で呼んでいれば 必要になるかもしれません。 .. php:method:: afterFilter(EventInterface $event) diff --git a/ja/controllers/components/form-protection.rst b/ja/controllers/components/form-protection.rst index 1bc21b0b38..4b7e57c93c 100644 --- a/ja/controllers/components/form-protection.rst +++ b/ja/controllers/components/form-protection.rst @@ -18,8 +18,8 @@ FormProtectionコンポーネントを使用するときは、**必ず** FormHelperを使用して フォームを作成してください。また、フィールドの「名前」属性を上書き **してはいけません** 。 FormProtection コンポーネントは、FormHelper によって作成・管理される特定の指標を探します。 - （特に :php:meth:`~Cake\\View\\Helper\\FormHelper::create()` と - :php:meth:`~Cake\\View\\Helper\\FormHelper::end()` で作成されたもの） + （特に :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()` と + :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()` で作成されたもの） POST リクエストで送信される動的なフィールド変更 (JavaScriptによる無効化、削除、新規フィールドの作成など) diff --git a/ja/controllers/components/security.rst b/ja/controllers/components/security.rst index 289f037f3f..9937b37978 100644 --- a/ja/controllers/components/security.rst +++ b/ja/controllers/components/security.rst @@ -29,15 +29,15 @@ Security コンポーネントのフォーム保護機能と、 ``startup()`` **使わなければなりません** 。また、フィールドの "name" 属性を **上書きしてはいけません** 。Security コンポーネントは、FormHelper で作成され、 管理されるインジケーターを確認します。(これらは - :php:meth:`~Cake\\View\\Helper\\FormHelper::create()` と - :php:meth:`~Cake\\View\\Helper\\FormHelper::end()` の中で作成されます。) + :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()` と + :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()` の中で作成されます。) 例えば JavaScript で無効化・ 削除・新規作成するなどして POST リクエスト中の投稿された フィールドを動的に差し替えることは、リクエストが破棄されるきっかけになります。 副作用を避けるために、実行前に使用されている HTTP メソッドを常に確認する必要があります。 正しい HTTP メソッドが使用されていることを確認するために、 :ref:`HTTP メソッドをチェックする ` か、 - :php:meth:`Cake\\Http\\ServerRequest::allowMethod()` を使用してください。 + :php:meth:`\\Cake\\Http\\ServerRequest::allowMethod()` を使用してください。 ブラックホールコールバックの処理 ================================ @@ -55,7 +55,7 @@ Security コンポーネントのフォーム保護機能と、 ``startup()`` public function beforeFilter(EventInterface $event) { parent::beforeFilter($event); - + $this->Security->setConfig('blackHoleCallback', 'blackhole'); } diff --git a/ja/controllers/request-response.rst b/ja/controllers/request-response.rst index 6fc5f3ce15..1f73dfbe1a 100644 --- a/ja/controllers/request-response.rst +++ b/ja/controllers/request-response.rst @@ -87,7 +87,7 @@ query プロパティーに直接アクセスするか、エラーが発生し .. php:method:: getData($name, $default = null) -すべての POST データは :php:meth:`Cake\\Http\\ServerRequest::getData()` を使ってアクセスされます。 +すべての POST データは :php:meth:`\\Cake\\Http\\ServerRequest::getData()` を使ってアクセスされます。 フォームデータが ``data`` 接頭辞を含んでいる場合、接頭辞は取り除かれるでしょう。例えば :: // name 属性が 'MyModel[title]' の入力は次のようにアクセスします。 @@ -114,7 +114,7 @@ query プロパティーに直接アクセスするか、エラーが発生し ファイルのアップロード ---------------------- -アップロードしたファイルは、上で説明した :php:meth:`Cake\\Http\\ServerRequest::getData()` +アップロードしたファイルは、上で説明した :php:meth:`\\Cake\\Http\\ServerRequest::getData()` メソッドを使用して、リクエスト内容のデータからアクセスすることができます。 例えば、name属性が ``attachment`` であるinput要素のファイルは、以下のようにアクセスできます。 :: @@ -177,19 +177,19 @@ HTTP環境では、 ``moveTo()`` メソッドはファイルが実際にアッ .. tip:: アップロードされたファイルは、リクエストデータとは別のオブジェクトとして - :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` と - :php:meth:`Cake\\Http\\ServerRequest::getUploadedFiles()` メソッドを使用しています。 + :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` と + :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFiles()` メソッドを使用しています。 これらのメソッドは ``App.uploadedFilesAsObjects`` の設定に関係なく、常にオブジェクトを返します。 .. php:method:: getUploadedFile($path) アップロードされたファイルの特定のパスで返します。 -パスは :php:meth:`Cake\\Http\\ServerRequest::getData()` メソッドと同じドット構文を使用します。 :: +パスは :php:meth:`\\Cake\\Http\\ServerRequest::getData()` メソッドと同じドット構文を使用します。 :: $attachment = $this->request->getUploadedFile('attachment'); -:php:meth:`Cake\\Http\\ServerRequest::getData()` と違って、 :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` +:php:meth:`\\Cake\\Http\\ServerRequest::getData()` と違って、 :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` は、実際にアップロードされたファイルが指定されたパスに存在する場合にのみデータを返します。 通常であれば、ファイルではないリクエストのbodyデータが指定されたパスに存在する場合、このメソッドは ``null`` を返します。 @@ -235,9 +235,9 @@ HTTP環境では、 ``moveTo()`` メソッドはファイルが実際にアッ .. note:: このメソッドでリクエストに追加したアップロードファイルは、リクエスト本文では利用 *できません*。 - すなわち、 :php:meth:`Cake\\Http\\ServerRequest::getData()` を経由して受け取ることはできません！ - リクエストデータに（も）必要な場合は、 :php:meth:`Cake\\Http\\ServerRequest::withData()` か - :php:meth:`Cake\\Http\\ServerRequest::withParsedBody()` を経由して設定する必要があります。 + すなわち、 :php:meth:`\\Cake\\Http\\ServerRequest::getData()` を経由して受け取ることはできません！ + リクエストデータに（も）必要な場合は、 :php:meth:`\\Cake\\Http\\ServerRequest::withData()` か + :php:meth:`\\Cake\\Http\\ServerRequest::withParsedBody()` を経由して設定する必要があります。 PUT、PATCH または DELETE データ ------------------------------- @@ -324,7 +324,7 @@ post 形式でデータを交換することがしばしばあります。 :php: $isPost = $this->request->is('post'); -新しい種類の検出器を作成するために :php:meth:`Cake\\Http\\ServerRequest::addDetector()` +新しい種類の検出器を作成するために :php:meth:`\\Cake\\Http\\ServerRequest::addDetector()` を使用することで利用可能なリクエスト検出器を拡張することができます。4種類の異なる検出器を作成できます。 * 環境変数の比較 - 環境変数の比較、 :php:func:`env()` から取得された値と提供された値が @@ -408,9 +408,9 @@ post 形式でデータを交換することがしばしばあります。 :php: MIME タイプを受付けるかどうかを調べます。 ``ServerRequest`` は、 -:php:meth:`Cake\\Http\\ServerRequest::domain()` 、 -:php:meth:`Cake\\Http\\ServerRequest::subdomains()` 、 -:php:meth:`Cake\\Http\\ServerRequest::host()` +:php:meth:`\\Cake\\Http\\ServerRequest::domain()` 、 +:php:meth:`\\Cake\\Http\\ServerRequest::subdomains()` 、 +:php:meth:`\\Cake\\Http\\ServerRequest::host()` のようにサブドメインでアプリケーションを助けるためのメソッドを含みます。 セッションデータ @@ -575,7 +575,7 @@ Accept ヘッダーの確認 // Get a CookieCollection instance $cookies = $this->request->getCookieCollection() -クッキーコレクションの操作方法については、 :php:class:`Cake\\Http\\Cookie\\CookieCollection` +クッキーコレクションの操作方法については、 :php:class:`\\Cake\\Http\\Cookie\\CookieCollection` のドキュメントをご覧ください。 @@ -617,13 +617,13 @@ URIの操作 .. php:class:: Response -:php:class:`Cake\\Http\\Response` は、CakePHP のデフォルトのレスポンスクラスです。 +:php:class:`\\Cake\\Http\\Response` は、CakePHP のデフォルトのレスポンスクラスです。 いくつかの機能と HTTP レスポンスの生成をカプセル化します。 また送信予定のヘッダーを調べるためにモックやスタブとしてテストの手助けをします。 -:php:class:`Cake\\Http\\ServerRequest` と同様に、 :php:class:`Controller`, +:php:class:`\\Cake\\Http\\ServerRequest` と同様に、 :php:class:`Controller`, :php:class:`RequestHandlerComponent` 及び :php:class:`Dispatcher` に以前あった多くのメソッドを -:php:class:`Cake\\Http\\Response` が統合します。 -古いメソッドは非推奨になり、 :php:class:`Cake\\Http\\Response` の使用を推奨します。 +:php:class:`\\Cake\\Http\\Response` が統合します。 +古いメソッドは非推奨になり、 :php:class:`\\Cake\\Http\\Response` の使用を推奨します。 ``Response`` は次のような共通のレスポンスをラップするためのインターフェイスを提供します。 @@ -637,7 +637,7 @@ URIの操作 .. php:method:: withType($contentType = null) -:php:meth:`Cake\\Http\\Response::withType()` を使用して、アプリケーションのレスポンスの +:php:meth:`\\Cake\\Http\\Response::withType()` を使用して、アプリケーションのレスポンスの コンテンツタイプを制御することができます。アプリケーションが Response に組み込まれていない コンテンツの種類に対処する必要がある場合は、以下のように ``setTypeMap()`` を使って設定することができます。 :: @@ -659,7 +659,7 @@ URIの操作 .. php:method:: withFile($path, $options = []) リクエストに対する応答としてファイルを送信する機会があります。 -:php:meth:`Cake\\Http\\Response::withFile()` を使用してそれを達成することができます。 :: +:php:meth:`\\Cake\\Http\\Response::withFile()` を使用してそれを達成することができます。 :: public function sendFile($id) { @@ -671,8 +671,8 @@ URIの操作 上記の例のようにメソッドにファイルのパスを渡す必要があります。CakePHP は、 `Cake\\Http\\Response::$_mimeTypes` に登録された、よく知られるファイルタイプであれば -正しいコンテンツタイプヘッダーを送ります。 :php:meth:`Cake\\Http\\Response::withFile()` を呼ぶ前に -:php:meth:`Cake\\Http\\Response::withType()` メソッドを使って、新しいタイプを追加できます。 +正しいコンテンツタイプヘッダーを送ります。 :php:meth:`\\Cake\\Http\\Response::withFile()` を呼ぶ前に +:php:meth:`\\Cake\\Http\\Response::withType()` メソッドを使って、新しいタイプを追加できます。 もし、あなたが望むなら、 オプションを明記することによって、ブラウザー上に表示する代わりにファイルを ダウンロードさせることができます。 :: @@ -723,7 +723,7 @@ download .. php:method:: withHeader($header, $value) -ヘッダーの設定は :php:meth:`Cake\\Http\\Response::withHeader()` メソッドで行われます。 +ヘッダーの設定は :php:meth:`\\Cake\\Http\\Response::withHeader()` メソッドで行われます。 すべての PSR-7 インターフェイスのメソッドと同様に、このメソッドは新しいヘッダーを含む *新しい* インスタンスを返します。 :: @@ -740,7 +740,7 @@ download セットされた際、ヘッダーは送られません。これらのヘッダーは、 ``Cake\Http\Server`` によって レスポンスが実際に送られるまで保持されます。 -便利なメソッド :php:meth:`Cake\\Http\\Response::withLocation()` を使うと +便利なメソッド :php:meth:`\\Cake\\Http\\Response::withLocation()` を使うと 直接リダイレクトヘッダーの設定や取得ができます。 ボディーの設定 @@ -807,7 +807,7 @@ download .. php:method:: withDisableCache() 時々、コントローラーアクションの結果をキャッシュしないようにブラウザーに強制する必要がでてきます。 -:php:meth:`Cake\\Http\\Response::withDisableCache()` はそういった目的で使われます。 :: +:php:meth:`\\Cake\\Http\\Response::withDisableCache()` はそういった目的で使われます。 :: public function index() { @@ -823,7 +823,7 @@ download .. php:method:: withCache($since, $time = '+1 day') クライアントにレスポンスをキャッシュして欲しいことを伝えられます。 -:php:meth:`Cake\\Http\\Response::withCache()` を使って:: +:php:meth:`\\Cake\\Http\\Response::withCache()` を使って:: public function index() { @@ -851,7 +851,7 @@ HTTP キャッシュのチューニング HTTP は二つのモデル、expiration と validation を使います。これらは大抵の場合、 自身でキャッシュを管理するよりかなり単純です。 -:php:meth:`Cake\\Http\\Response::withCache()` と独立して、HTTP キャッシュヘッダーを +:php:meth:`\\Cake\\Http\\Response::withCache()` と独立して、HTTP キャッシュヘッダーを チューニングするための様々なメソッドが使えます。この点に関して、ブラウザーやリバースプロキシーの キャッシュよりも有利だと言えます。 @@ -1006,7 +1006,7 @@ Not-Modified レスポンスの送信 クッキーの設定 --------------- -クッキーは、配列または :php:class:`Cake\\Http\\Cookie\\Cookie` オブジェクトを使って +クッキーは、配列または :php:class:`\\Cake\\Http\\Cookie\\Cookie` オブジェクトを使って レスポンスに追加することができます。 :: use Cake\Http\Cookie\Cookie; diff --git a/ja/core-libraries/caching.rst b/ja/core-libraries/caching.rst index 2e636c4cf1..bb3dd8f2ab 100644 --- a/ja/core-libraries/caching.rst +++ b/ja/core-libraries/caching.rst @@ -34,7 +34,7 @@ CakePHP には、いくつかのキャッシュエンジンが用意されてい * ``Null`` nullエンジンは実質何も保存せず、すべての読み込み操作を失敗させます。 あなたが選択したキャッシュエンジンに関わらず、 -アプリケーションは :php:class:`Cake\\Cache\\Cache` とやり取りします。 +アプリケーションは :php:class:`\\Cake\\Cache\\Cache` とやり取りします。 .. _cache-configuration: @@ -105,8 +105,8 @@ DSN を使用するとき、追加のクエリー文字列要素としてパラ $object = new FileEngine($config); Cache::setConfig('other', $object); -これらのエンジン設定の名前 ('short' や 'long') は :php:meth:`Cake\\Cache\\Cache::write()` と -:php:meth:`Cake\\Cache\\Cache::read()` の ``$config`` パラメーターとして使われます。 +これらのエンジン設定の名前 ('short' や 'long') は :php:meth:`\\Cake\\Cache\\Cache::write()` と +:php:meth:`\\Cake\\Cache\\Cache::read()` の ``$config`` パラメーターとして使われます。 キャッシュエンジンを設定する場合は、次の構文を使用してクラス名を参照することができます。 :: // 省略名 (App\ または Cake 名前空間の中) @@ -223,7 +223,7 @@ Redis サーバーが予期せず失敗した場合、 ``redis`` キャッシュ .. php:staticmethod:: drop($key) 一度設定が作成されたら、変更することはできません。代わりに、 -:php:meth:`Cake\\Cache\\Cache::drop()` と :php:meth:`Cake\\Cache\\Cache::config()` +:php:meth:`\\Cake\\Cache\\Cache::drop()` と :php:meth:`\\Cake\\Cache\\Cache::config()` を使用して、設定を削除して再作成する必要があります。キャッシュエンジンを削除すると、設定が削除され、 アダプターが構築されていれば破棄されます。 @@ -464,7 +464,7 @@ Cache クラスは簡単な方法でカウンター値をインクリメント/ まれにしか変更されない、またはキャッシュに大量の読み込みが行われるような結果をキャッシュすることによって、 アプリケーションのパフォーマンスを大幅に向上させることができます。 -この完璧な例は、 :php:meth:`Cake\\ORM\\Table::find()` の結果です。 +この完璧な例は、 :php:meth:`\\Cake\\ORM\\Table::find()` の結果です。 この Query オブジェクトを使用すると、 ``cache()`` メソッドを使用して結果をキャッシュできます。 詳細は、 :ref:`caching-query-results` セクションを参照してください。 @@ -564,7 +564,7 @@ Cache クラスは簡単な方法でカウンター値をインクリメント/ ]); カスタムキャッシュエンジンは、いくつかの抽象メソッドを定義するだけでなく、 -いくつかの初期化メソッドを提供する :php:class:`Cake\\Cache\\CacheEngine` を拡張する必要があります。 +いくつかの初期化メソッドを提供する :php:class:`\\Cake\\Cache\\CacheEngine` を拡張する必要があります。 キャッシュエンジンに必要な API は次のとおりです。 diff --git a/ja/core-libraries/collections.rst b/ja/core-libraries/collections.rst index d604ad8349..f993a9290e 100644 --- a/ja/core-libraries/collections.rst +++ b/ja/core-libraries/collections.rst @@ -163,7 +163,7 @@ おそらく重複したキーで結果を取得する場合に重要になります。 ``toList()`` メソッドを 使用することにより、重複するキーが存在する場合でも、すべての値を取得することが保証されます。 -:php:meth:`Cake\\Utility\\Hash::extract()` とは異なり、このメソッドは +:php:meth:`\\Cake\\Utility\\Hash::extract()` とは異なり、このメソッドは ``{*}`` ワイルドカードのみをサポートしています。 他のすべてのワイルドカードと属性のマッチャはサポートされていません。 diff --git a/ja/core-libraries/form.rst b/ja/core-libraries/form.rst index 84a1c33670..2e073b0b00 100644 --- a/ja/core-libraries/form.rst +++ b/ja/core-libraries/form.rst @@ -54,7 +54,7 @@ * ``_buildSchema`` は FormHelper が HTML フォームを作成する際に使用する スキーマデータを定義するために使います。フィールドの型、長さ、および精度を定義できます。 * ``validationDefault`` はバリデーターを加えることができる - :php:class:`Cake\\Validation\\Validator` のインスタンスを受け取ります。 + :php:class:`\\Cake\\Validation\\Validator` のインスタンスを受け取ります。 * ``_execute`` では ``execute()`` が呼ばれ、データが有効な時に望むふるまいを定義します。 もちろん必要に応じて追加の公開メソッドを定義することもできます。 diff --git a/ja/core-libraries/global-constants-and-functions.rst b/ja/core-libraries/global-constants-and-functions.rst index 0463a2249a..41de3756eb 100644 --- a/ja/core-libraries/global-constants-and-functions.rst +++ b/ja/core-libraries/global-constants-and-functions.rst @@ -85,7 +85,7 @@ CakePHP アプリケーション内の特定のファイルやディレクトリ .. php:function:: collection(mixed $items) - 渡された引数をラップする、新しい :php:class:`Cake\\Collection\\Collection` + 渡された引数をラップする、新しい :php:class:`\\Cake\\Collection\\Collection` オブジェクトをインスタンス化するための簡易ラッパー。 ``$items`` パラメーターは ``Traversable`` オブジェクトまたは配列のいずれかを取ります。 diff --git a/ja/core-libraries/logging.rst b/ja/core-libraries/logging.rst index e6dae37f19..c1001d7ccf 100644 --- a/ja/core-libraries/logging.rst +++ b/ja/core-libraries/logging.rst @@ -21,7 +21,7 @@ View 等) であれば、あなたはデータを記録することができま アプリケーションの起動処理の間に、 ``Log`` の設定は完了しているはずで **config/app.php** は、 これのためです。多かれ少なかれアプリケーションが望むロガーを定義できます。 -ロガーは、 :php:class:`Cake\\Log\\Log` を使い設定する必要があります。一例として:: +ロガーは、 :php:class:`\\Cake\\Log\\Log` を使い設定する必要があります。一例として:: use Cake\Log\Engine\FileLog; use Cake\Log\Log; @@ -264,7 +264,7 @@ Syslog ロギングエンジンのための設定配列は、以下のキーを ================ ログファイルへの書き込みは、２つの方法があります。１つは、 -静的な :php:meth:`Cake\\Log\\Log::write()` メソッドを使用することです。 :: +静的な :php:meth:`\\Cake\\Log\\Log::write()` メソッドを使用することです。 :: Log::write('debug', '何かがうまくいかなかった'); @@ -274,7 +274,7 @@ log() を呼ぶと、内部的に ``Log::write()`` が呼ばれます。 :: // LogTrait を使用した クラス内でこれを実行 $this->log("何かがうまくいかなかった！", 'debug'); -全ての設定されたログストリームは、 :php:meth:`Cake\\Log\\Log::write()` が呼ばれるたびに +全ての設定されたログストリームは、 :php:meth:`\\Cake\\Log\\Log::write()` が呼ばれるたびに 順次書き込まれます。もし設定されていないログアダプターを持っているならば、 ``log()`` は ``false`` を返し何も書き込みません。 diff --git a/ja/core-libraries/number.rst b/ja/core-libraries/number.rst index 533c164e3e..ddec23eace 100644 --- a/ja/core-libraries/number.rst +++ b/ja/core-libraries/number.rst @@ -100,7 +100,7 @@ $currency の値が ``null`` の場合、デフォルト通貨は :php:meth:`Cak .. php:method:: defaultCurrency($currency) -デフォルト通貨のための setter/getter です。これによって、常に :php:meth:`Cake\\I18n\\Number::currency()` に通貨を渡したり、 +デフォルト通貨のための setter/getter です。これによって、常に :php:meth:`\\Cake\\I18n\\Number::currency()` に通貨を渡したり、 他のデフォルトを設定することによって全ての通貨の出力を変更したりする必要がなくなります。 ``$currency`` に ``false`` が設定された場合、現在格納されている値をクリアします。 デフォルトでは、設定されていれば ``intl.default_locale`` を取得し、そうでない場合は 'en_US' を設定します。 @@ -134,7 +134,7 @@ $currency の値が ``null`` の場合、デフォルト通貨は :php:meth:`Cak | | Boolean 値です。少数のパーセンテージに便利です。 | +---------------------+----------------------------------------------------+ -このメソッドは :php:meth:`Cake\\I18n\\Number::precision()` のように、 +このメソッドは :php:meth:`\\Cake\\I18n\\Number::precision()` のように、 与えられた精度に応じて(精度を満たすように丸めて)数値をフォーマットします。 このメソッドはパーセンテージとして数値を表現し、パーセント記号を追加して出力します。 :: diff --git a/ja/core-libraries/security.rst b/ja/core-libraries/security.rst index c9f0059c92..f663988263 100644 --- a/ja/core-libraries/security.rst +++ b/ja/core-libraries/security.rst @@ -36,7 +36,7 @@ $result = Security::encrypt($value, $key); もしあなたが HMAC ソルトを提供しなければ、 ``Security.salt`` の値が利用されます。 -暗号化された値は :php:meth:`Cake\\Utility\\Security::decrypt()` を利用して復号できます。 +暗号化された値は :php:meth:`\\Cake\\Utility\\Security::decrypt()` を利用して復号できます。 すでに暗号化された値を復号します。 ``$key`` と ``$hmacSalt`` のパラメーターは、 暗号化時に利用された各々の値と一致する必要があり、さもなければ復号は失敗します。 diff --git a/ja/core-libraries/text.rst b/ja/core-libraries/text.rst index 74462fa1e7..5cb922f537 100644 --- a/ja/core-libraries/text.rst +++ b/ja/core-libraries/text.rst @@ -7,7 +7,7 @@ Text Text クラスは文字列を作ったり操作したりする便利なメソッドを持っており、通常は static にアクセスします。例: ``Text::uuid()`` -``View`` の外側で :php:class:`Cake\\View\\Helper\\TextHelper` の機能が必要なときは ``Text`` クラスを使ってください。 :: +``View`` の外側で :php:class:`\\Cake\\View\\Helper\\TextHelper` の機能が必要なときは ``Text`` クラスを使ってください。 :: namespace App\Controller; diff --git a/ja/core-libraries/xml.rst b/ja/core-libraries/xml.rst index ad153840a1..ae3f8bb06e 100644 --- a/ja/core-libraries/xml.rst +++ b/ja/core-libraries/xml.rst @@ -62,7 +62,7 @@ DOMDocument を返却します。 XML 文字列を配列に変換する =========================== -.. php:staticmethod:: toArray($obj); +.. php:staticmethod:: toArray($obj) XML テキストを配列に変換するのは、 Xml クラスと同様にシンプルです。 標準で SimpleXml オブジェクトから受け取ります。 :: diff --git a/ja/development/debugging.rst b/ja/development/debugging.rst index 25d6d8853e..634e785301 100644 --- a/ja/development/debugging.rst +++ b/ja/development/debugging.rst @@ -155,7 +155,7 @@ $line 行目の前後 $context 行もあわせて取得します。 :: ====================== アプリケーションをデバッグするもう一つの良い方法はログメッセージです。 -:php:class:`Cake\\Log\\Log` を使うことで、あなたのアプリケーションでログ出力を +:php:class:`\\Cake\\Log\\Log` を使うことで、あなたのアプリケーションでログ出力を させることができます。 ``LogTrait`` を利用するすべてのオブジェクトは、 インスタンスメソッド ``log()`` を持っており、ログメッセージを出力するのに使えます。 :: @@ -163,7 +163,7 @@ $line 行目の前後 $context 行もあわせて取得します。 :: 上記では ``通ったよ`` がデバッグログに出力されます。 ログに出力することで、リダイレクトや複雑なループを含むメソッドをデバッグしやすくなるでしょう。 -また、:php:meth:`Cake\\Log\\Log::write()` を使うことで、ログメッセージを書きだすことも可能です。 +また、:php:meth:`\\Cake\\Log\\Log::write()` を使うことで、ログメッセージを書きだすことも可能です。 このメソッドは Log がロードされているなら static にあなたのアプリケーション内の どこからでも呼び出すことができるのです。 :: diff --git a/ja/development/dispatch-filters.rst b/ja/development/dispatch-filters.rst index 92becbb00b..3d1e9ceab3 100644 --- a/ja/development/dispatch-filters.rst +++ b/ja/development/dispatch-filters.rst @@ -34,7 +34,7 @@ CakePHP はきれいなディスパッチサイクルに使う強固なフィル ================ フィルターは **bootstrap.php** で有効にされます。しかし、リクエストが送信される前に -いつでも簡単に読み込めます。 :php:class:`Cake\\Routing\\DispatcherFactory` を使って、 +いつでも簡単に読み込めます。 :php:class:`\\Cake\\Routing\\DispatcherFactory` を使って、 フィルターをつけたり外したり出来ます。 デフォルトでは、 CakePHP のテンプレートは既定で全てのリクエストに対して有効な 2つのフィルタークラスによってされます。それが、どのように追加されるか見てみましょう。 :: @@ -129,7 +129,7 @@ CakePHP はきれいなディスパッチサイクルに使う強固なフィル ``afterDispatch()`` メソッドを提供します。それらのメソッドはそれぞれ個別に、 コントローラーが実行された時にその前か後に実行されます。両方のメソッドは、 ``$data`` プロパティー内で ``ServerRequest`` と ``Response`` ( -:php:class:`Cake\\Http\\ServerRequest` と :php:class:`Cake\\Http\\Response` +:php:class:`\\Cake\\Http\\ServerRequest` と :php:class:`\\Cake\\Http\\Response` インスタンス) オブジェクトを含む :php:class:`Cake\\Event\\Event` オブジェクトを 受け取ります。 @@ -172,7 +172,7 @@ CakePHP はきれいなディスパッチサイクルに使う強固なフィル このフィルターは１日後に期限が切れるヘッダーをページコントローラーで送るレスポンスに付けて送ります。 もちろんコントローラーでも同じことが出来ます。 これはただのフィルターができることの例一部です。 -実際は、レスポンスを操作する代わりに、 :php:class:`Cake\\Cache\\Cache` でキャッシュして、 +実際は、レスポンスを操作する代わりに、 :php:class:`\\Cake\\Cache\\Cache` でキャッシュして、 ``beforeDispatch()`` をコールバックしてレスポンスを制御できます。 強力なディスパッチャーフィルターはアプリを維持するのを難しくする可能性を持っていますが。 diff --git a/ja/development/errors.rst b/ja/development/errors.rst index 778e5fa788..169c25a3f7 100644 --- a/ja/development/errors.rst +++ b/ja/development/errors.rst @@ -24,8 +24,8 @@ CakePHP は PHP エラーと例外の両方を処理するために ``Cake\Error * ``exceptionRenderer`` - string - キャッチされなかった例外を描画する役目を担うクラス。 もしもカスタムクラスを選択する場合は **src/Error** 中にそのクラスのファイルを置くべきです。 このクラスは ``render()`` メソッドを実装する必要があります。 -* ``log`` - bool - ``true`` の時、 :php:class:`Cake\\Log\\Log` によって例外と - そのスタックトレースが :php:class:`Cake\\Log\\Log` に記録されます。 +* ``log`` - bool - ``true`` の時、 :php:class:`\\Cake\\Log\\Log` によって例外と + そのスタックトレースが :php:class:`\\Cake\\Log\\Log` に記録されます。 * ``skipLog`` - array - ログに記録されるべきではない例外クラス名の配列。 これは NotFoundException や他のありふれた、でもログにはメッセージを残したくない例外を 除外するのに役立ちます。 @@ -435,7 +435,7 @@ logger:: 組み込みの例外処理を使うと、 **config/app.php** 中で ``log`` オプションに ``true`` を設定することで ErrorHandler によって対処されるすべての例外をログに記録することができます。 -これを有効にすることで :php:class:`Cake\\Log\\Log` と設定済みのロガーに各例外の記録が残るでしょう。 +これを有効にすることで :php:class:`\\Cake\\Log\\Log` と設定済みのロガーに各例外の記録が残るでしょう。 .. note:: @@ -643,8 +643,8 @@ HTTP 関連の例外を投げることができます。例:: .. php:exception:: PersistenceFailedException - :php:meth:`Cake\\ORM\\Table::saveOrFail()` や - :php:meth:`Cake\\ORM\\Table::deleteOrFail()` を使用しましたが、 + :php:meth:`\\Cake\\ORM\\Table::saveOrFail()` や + :php:meth:`\\Cake\\ORM\\Table::deleteOrFail()` を使用しましたが、 エンティティーは、保存/削除されませんでした。 .. php:namespace:: Cake\Datasource\Exception diff --git a/ja/development/rest.rst b/ja/development/rest.rst index 4e920a66b5..1650003e1e 100644 --- a/ja/development/rest.rst +++ b/ja/development/rest.rst @@ -136,7 +136,7 @@ CakePHP は自動的にそのタイプに対応するビューヘルパーを探 edit アクションのロジックを作るのは少しだけトリッキーです。XML 出力 の API を提供する場合、 入力も XML で受付けるほうが自然です。心配せずとも、 :php:class:`Cake\\Controller\\Component\\RequestHandler` と -:php:class:`Cake\\Routing\\Router` クラスが取り計らってくれます。 +:php:class:`\\Cake\\Routing\\Router` クラスが取り計らってくれます。 POST もしくは PUT リクエストのコンテンツタイプが XML であれば、入力データは CakePHP の :php:class:`Xml` クラスに渡され、配列に変換され、 ``$this->request->getData()`` に入ります。 この機能によって、XML と POST データの処理はシームレスになるのです。コントローラーもモデルも diff --git a/ja/development/routing.rst b/ja/development/routing.rst index d61a56a6a4..767d68878a 100644 --- a/ja/development/routing.rst +++ b/ja/development/routing.rst @@ -1342,7 +1342,7 @@ Route クラスには、いくつかの規約があります。 * ルートクラスは、アプリケーションやプラグイン内にある ``Routing\\Route`` 名前空間で 見つけられるはずです。 -* ルートクラス :php:class:`Cake\\Routing\\Route` を拡張します。 +* ルートクラス :php:class:`\\Cake\\Routing\\Route` を拡張します。 * ルートクラスは ``match()`` と ``parse()`` の一方もしくは両方を使います。 ``parse()`` メソッドは、受け取った URL をパースするために使用されます。 diff --git a/ja/development/sessions.rst b/ja/development/sessions.rst index 1e54a0f490..bbbdc233ac 100644 --- a/ja/development/sessions.rst +++ b/ja/development/sessions.rst @@ -286,7 +286,7 @@ IO をもたらします。 } このクラスはビルトインの ``DatabaseSession`` を継承しそのロジックや振る舞いを重複して -定義することを避けています。それぞれのオペレーションを :php:class:`Cake\\Cache\\Cache` +定義することを避けています。それぞれのオペレーションを :php:class:`\\Cake\\Cache\\Cache` オペレーションでラップします。これで高速なキャッシュからセッションを取得しつつ、 キャッシュ限度の考慮を不要にしています。このセッションハンドラーを使うのもまた簡単です。 **app.php** のセッションブロックを以下のように設定します。 :: diff --git a/ja/development/testing.rst b/ja/development/testing.rst index 1be3a265ac..759538b582 100644 --- a/ja/development/testing.rst +++ b/ja/development/testing.rst @@ -1235,7 +1235,7 @@ HTTP経由でアップロードされたかどうかをテストするバリデ アップロードされたファイルオブジェクトが通常のリクエストでどのように 存在するかを正確にシミュレートするには、リクエストデータでそれらを 渡すだけでなく、 ``files`` オプションを介してテストリクエスト構成に -渡す必要があります。ただし、コードが :php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` または :php:meth:`Cake\\Http\\ServerRequest::getUploadedFiles()` メソッドを介して +渡す必要があります。ただし、コードが :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` または :php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFiles()` メソッドを介して アップロードされたファイルにアクセスしない限り、技術的には必要ありません。 記事にティザー画像と ``複数の添付ファイル`` の関連付けがあるとして、 diff --git a/ja/orm/database-basics.rst b/ja/orm/database-basics.rst index 4e1b604837..2075616388 100644 --- a/ja/orm/database-basics.rst +++ b/ja/orm/database-basics.rst @@ -273,7 +273,7 @@ BigBoxesTable と、コントローラー BigBoxesController は、全て自動 .. php:staticmethod:: get($name) -一度設定した接続は、 :php:meth:`Cake\\Datasource\\ConnectionManager::get()` を +一度設定した接続は、 :php:meth:`\\Cake\\Datasource\\ConnectionManager::get()` を 使って取り出すことができます。 このメソッドはすでに確立しているコネクションを返すか、もしまだ接続していないのであれば ロードして接続してから返します。 :: @@ -339,13 +339,13 @@ binary データベースによって提供される BLOB 型または BYTEA 型に変換します。 date タイムゾーン情報を持たない DATE 型に変換されます。この型の戻り値は、ネイティブな - ``DateTime`` クラスを拡張した :php:class:`Cake\\I18n\\Date` です。 + ``DateTime`` クラスを拡張した :php:class:`\\Cake\\I18n\\Date` です。 datetime タイムゾーン情報を持たない DATETIME 型に変換されます。 PostgreSQL と SQL Server では、TIMESTAMP 型に変換されます。 この型のデフォルトの戻り値は、組込みの ``DateTime`` クラスと `Chronos `_ を拡張した - :php:class:`Cake\\I18n\\Time` クラスになります。 + :php:class:`\\Cake\\I18n\\Time` クラスになります。 timestamp TIMESTAMP 型に変換します。 time @@ -878,7 +878,7 @@ SQL 文を準備したら、あなたは追加のデータをバインドし、 $connection->enableQueryLogging(false); クエリーログを有効にしていると、 'debug' レベルで 'queriesLog' スコープで -:php:class:`Cake\\Log\\Log` にクエリーをログ出力します。 +:php:class:`\\Cake\\Log\\Log` にクエリーをログ出力します。 あなたはこのレベル・スコープを出力するようにログ設定をする必要があります。 ``stderr`` にログ出力するのはユニットテストの時に便利で、files/syslog に出力するのは Web リクエストの時に便利です。 :: diff --git a/ja/orm/deleting-data.rst b/ja/orm/deleting-data.rst index bbf22e08eb..11f418a710 100644 --- a/ja/orm/deleting-data.rst +++ b/ja/orm/deleting-data.rst @@ -36,7 +36,7 @@ atomic オプションで無効化することも出来ます。 :: エンティティーを削除するとき関連データを削除することもできます。HasOne や HasMany が ``dependent`` として設定されている場合、削除処理はそれらのエンティティーにも連鎖適用されます。 -デフォルトでは、関連テーブル内のエンティティーの削除には :php:meth:`Cake\\ORM\\Table::deleteAll()` +デフォルトでは、関連テーブル内のエンティティーの削除には :php:meth:`\\Cake\\ORM\\Table::deleteAll()` が使用されます。 ``cascadeCallbacks`` オプションを ``true`` に設定することにより、 関連するエンティティーを ORM に読み出させ、それらを個別に削除させるように選択できます。 上記２つのオプションを有効にした HasMany のサンプルは、このようになります。 :: @@ -80,7 +80,7 @@ atomic オプションで無効化することも出来ます。 :: .. php:method:: deleteOrFail($entity, $options = []) このメソッドを使用すると、次の条件で -:php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` を投げます。 +:php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` を投げます。 * エンティティーが新しい場合 * エンティティーが主キーの値を持たない場合 @@ -97,5 +97,5 @@ atomic オプションで無効化することも出来ます。 :: echo $e->getEntity(); } -これは内部的に :php:meth:`Cake\\ORM\\Table::delete()` +これは内部的に :php:meth:`\\Cake\\ORM\\Table::delete()` コールを実行するので、対応するすべての削除イベントがトリガーされます。 diff --git a/ja/orm/query-builder.rst b/ja/orm/query-builder.rst index 654051b4ce..1f2a9b03e3 100644 --- a/ja/orm/query-builder.rst +++ b/ja/orm/query-builder.rst @@ -47,7 +47,7 @@ SQL インジェクション攻撃から守っています。 debug($article->title); } -以降の例では ``$articles`` は :php:class:`~Cake\\ORM\\Table` であると想定します。 +以降の例では ``$articles`` は :php:class:`\\Cake\\ORM\\Table` であると想定します。 なお、コントローラーの中では ``$articles`` の代わりに ``$this->Articles`` を使うことができます。 ``Query`` オブジェクトのほとんどのメソッドが自分自身のクエリーオブジェクトを返します。 @@ -1270,7 +1270,7 @@ join を作成する際には ``join()`` だけでなく、``rightJoin()``、 `` ]) ->execute(); -通常は、エンティティーを使い、 :php:meth:`~Cake\\ORM\\Table::save()` でデータを +通常は、エンティティーを使い、 :php:meth:`\\Cake\\ORM\\Table::save()` でデータを insert するほうが簡単です。また、``SELECT`` と ``INSERT`` を一緒に構築すれば、 ``INSERT INTO ... SELECT`` スタイルのクエリーを作成することができます。 :: @@ -1321,7 +1321,7 @@ update するほうが簡単です。 ->where(['id' => $id]) ->execute(); -通常は、エンティティーを使い、 :php:meth:`~Cake\\ORM\\Table::delete()` でデータを +通常は、エンティティーを使い、 :php:meth:`\\Cake\\ORM\\Table::delete()` でデータを delete するほうが簡単です。 SQL インジェクションを防止する diff --git a/ja/orm/saving-data.rst b/ja/orm/saving-data.rst index 24ede83c00..ecb6e278a1 100644 --- a/ja/orm/saving-data.rst +++ b/ja/orm/saving-data.rst @@ -1098,7 +1098,7 @@ belongsToMany アソシエーションのそれぞれのエンティティーは .. php:method:: saveOrFail($entity, $options = []) このメソッドを使用すると、次の条件で -:php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` を投げます。 +:php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` を投げます。 * アプリケーションルールのチェックに失敗した場合 * エンティティーにエラーが含まれている場合 @@ -1122,7 +1122,7 @@ belongsToMany アソシエーションのそれぞれのエンティティーは echo $e->getEntity(); } -これは内部的に :php:meth:`Cake\\ORM\\Table::save()` +これは内部的に :php:meth:`\\Cake\\ORM\\Table::save()` コールを実行するので、対応するすべての保存イベントはトリガーされます。 複数のエンティティーの保存 diff --git a/ja/tutorials-and-examples/blog/part-two.rst b/ja/tutorials-and-examples/blog/part-two.rst index ad6b742703..7567394d3d 100644 --- a/ja/tutorials-and-examples/blog/part-two.rst +++ b/ja/tutorials-and-examples/blog/part-two.rst @@ -302,7 +302,7 @@ POST なら、Articles モデルを使ってデータの保存を試みます。 すべての CakePHP のリクエストは ``ServerRequest`` オブジェクトに格納されており、 ``$this->request`` でアクセスできます。リクエストオブジェクトには、受信したリクエストに 関するいろんな情報が含まれているので、アプリケーションのフローの制御に利用できます。今回は、 -リクエストが HTTP POST かどうかの確認に :php:meth:`Cake\\Http\\ServerRequest::is()` メソッドを +リクエストが HTTP POST かどうかの確認に :php:meth:`\\Cake\\Http\\ServerRequest::is()` メソッドを 使用しています。 ユーザーがフォームを使ってデータを POST した場合、その情報は、 ``$this->request->getData()`` diff --git a/ja/tutorials-and-examples/cms/articles-controller.rst b/ja/tutorials-and-examples/cms/articles-controller.rst index 9cc46ca734..71a04c7ebd 100644 --- a/ja/tutorials-and-examples/cms/articles-controller.rst +++ b/ja/tutorials-and-examples/cms/articles-controller.rst @@ -228,7 +228,7 @@ view テンプレートの作成 全ての CakePHP のリクエストは、 ``$this->request`` を使用してアクセス可能なリクエストオブジェクトを 含みます。リクエストオブジェクトは、今受信したリクエストに関する情報を含みます。リクエストが HTTP POST -リクエストであることを確認するために :php:meth:`Cake\\Http\\ServerRequest::is()` メソッドを +リクエストであることを確認するために :php:meth:`\\Cake\\Http\\ServerRequest::is()` メソッドを 使用します。 POST データは、 ``$this->request->getData()`` で利用可能です。それがどのような内容かを diff --git a/ja/views.rst b/ja/views.rst index f99e85073f..5b6a7421db 100644 --- a/ja/views.rst +++ b/ja/views.rst @@ -360,7 +360,7 @@ fetch を使うとブロックが存在するかどうかによってブロッ // 残りのレイアウトが続きます -:php:meth:`Cake\\View\\Helper\\HtmlHelper` はスクリプトや CSS が入るブロックを +:php:class:`\\Cake\\View\\Helper\\HtmlHelper` はスクリプトや CSS が入るブロックを 制御することもできます。 :: // ビューファイルの中で diff --git a/ja/views/helpers/form.rst b/ja/views/helpers/form.rst index b4046a7438..d6ed8e3ee2 100644 --- a/ja/views/helpers/form.rst +++ b/ja/views/helpers/form.rst @@ -412,9 +412,9 @@ binary echo $this->Form->control('title', ['required' => false]); フォーム全体のブラウザー検証トリガーをスキップするには、 -:php:meth:`~Cake\\View\\Helper\\FormHelper::submit()` を使って生成する入力ボタンに対して +:php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` を使って生成する入力ボタンに対して ``'formnovalidate' => true`` オプションを設定したり、 -:php:meth:`~Cake\\View\\Helper\\FormHelper::create()` のオプションで +:php:meth:`\\Cake\\View\\Helper\\FormHelper::create()` のオプションで ``'novalidate' => true`` を設定できます。 たとえば、Users モデルに *username* (varchar), *password* (varchar), *approved* (datetime) @@ -475,7 +475,7 @@ UsersController に以下を追加します。 :: .. note:: 送信ボタンを生成するために ``FormHelper::control()`` を使用しないでください。 - 代わりに :php:meth:`~Cake\\View\\Helper\\FormHelper::submit()` を使用してください。 + 代わりに :php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` を使用してください。 フィールドの命名規則 -------------------- @@ -645,8 +645,8 @@ HTML 属性を受け付けます。以下は ``FormHelper::control()`` で特有 コントロールタイプを生成するために個別のメソッドがあります。 これらは、コントロールウィジェットそのものを生成するのに使えますが、 完全に独自のフォームレイアウトを生成するために -:php:meth:`~Cake\\View\\Helper\\FormHelper::label()` や -:php:meth:`~Cake\\View\\Helper\\FormHelper::error()` といった +:php:meth:`\\Cake\\View\\Helper\\FormHelper::label()` や +:php:meth:`\\Cake\\View\\Helper\\FormHelper::error()` といった 他のメソッドを組み合わせることができます。 .. _general-control-options: @@ -1898,7 +1898,7 @@ FormHelper は、フィールドエラーを簡単にチェックしたり、必 .. note:: - :php:meth:`~Cake\\View\\Helper\\FormHelper::control()` を使用している時、 + :php:meth:`\\Cake\\View\\Helper\\FormHelper::control()` を使用している時、 デフォルトではエラーは描画されますので、 ``isFieldError()`` を使用したり、 手動で ``error()`` を呼び出す必要はありません。 @@ -2076,7 +2076,7 @@ submit 入力は、基本的なテキストやイメージが必要な場合に ``end()`` は、フォームを閉じて完成します。 多くの場合、 ``end()`` は終了タグだけを出力しますが、 ``end()`` を使うと、 -FormHelper が :php:class:`Cake\\Controller\\Component\\FormProtectionComponent` に必要な +FormHelper が :php:class:`\\Cake\\Controller\\Component\\FormProtectionComponent` に必要な hidden フォーム要素を挿入できるようになります。 .. code-block:: php @@ -2159,8 +2159,8 @@ POST ボタンの作成 このメソッドは ``form`` 要素を作成します。 なので、開かれたフォームの中でこのメソッドを使用しないでください。 -代わりに :php:meth:`Cake\\View\\Helper\\FormHelper::submit()` または -:php:meth:`Cake\\View\\Helper\\FormHelper::button()` を使用して、 +代わりに :php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` または +:php:meth:`\\Cake\\View\\Helper\\FormHelper::button()` を使用して、 開かれたフォームの中でボタンを作成してください。 POST リンクの作成 @@ -2198,8 +2198,8 @@ HTML リンクを作成しますが、指定した方法 (デフォルトは POS :ref:`ビューブロック ` に設定されるようにする必要があります。 あなたが探しているものがフォームを送信するボタンであれば、代わりに -:php:meth:`Cake\\View\\Helper\\FormHelper::button()` または -:php:meth:`Cake\\View\\Helper\\FormHelper::submit()` を使用してください。 +:php:meth:`\\Cake\\View\\Helper\\FormHelper::button()` または +:php:meth:`\\Cake\\View\\Helper\\FormHelper::submit()` を使用してください。 .. note:: @@ -2616,13 +2616,13 @@ autocomplete ウィジェットが作成されると、 ``text`` と ``label`` SecurityComponent との連携 ========================== -:php:meth:`Cake\\Controller\\Component\\SecurityComponent` には、 +:php:meth:`\\Cake\\Controller\\Component\\SecurityComponent` には、 フォームをより安全で安全にするためのいくつかの機能があります。 コントローラーに ``SecurityComponent`` を含めるだけで、 フォームの改ざん防止機能が自動的に有効になります。 SecurityComponent を利用する際は、前述のようにフォームを閉じる際は、 -必ず :php:meth:`~Cake\\View\\Helper\\FormHelper::end()` を使う必要があります。 +必ず :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()` を使う必要があります。 これにより特別な ``_Token`` 入力が生成されます。 .. php:method:: unlockField($name) diff --git a/ja/views/helpers/html.rst b/ja/views/helpers/html.rst index 84049492f6..ad7d485dfb 100644 --- a/ja/views/helpers/html.rst +++ b/ja/views/helpers/html.rst @@ -403,7 +403,7 @@ HTML リンクを作成するための多目的なメソッドです。 また、さまざまな種類の URL の例については、 -:php:meth:`Cake\\View\\Helper\\UrlHelper::build()` メソッドをチェックしてください。 +:php:meth:`\\Cake\\View\\Helper\\UrlHelper::build()` メソッドをチェックしてください。 動画と音声ファイルのリンク -------------------------- @@ -816,7 +816,7 @@ HTML パラメーターを使用することができ、 特別なオプショ 'Home' ); -このメソッドはリストとその要素を生成するために :php:meth:`Cake\\View\\Helper\\HtmlHelper::tag()` +このメソッドはリストとその要素を生成するために :php:class:`\\Cake\\View\\Helper\\HtmlHelper::tag()` を使います。 :php:meth:`~Cake\\View\\Helper\\HtmlHelper::getCrumbs()` と同様に動作するので、 全てのパンくずに追加されたオプションを使用できます。 ``$startText`` パラメーターを使って、 最初のパンくずのリンクやテキストを提供することができます。 diff --git a/ja/views/helpers/time.rst b/ja/views/helpers/time.rst index ee6fc25240..a1d74e7c38 100644 --- a/ja/views/helpers/time.rst +++ b/ja/views/helpers/time.rst @@ -41,7 +41,7 @@ TimeHelper を使って投稿日時を補正することができます。 :: TimeHelper のほとんどの機能は、古いバージョンの CakePHP からアップグレードしている アプリケーションのための下位互換性のあるインターフェースとして意図されています。 なぜなら、 ORM は ``timestamp`` 型と ``datetime`` 型の列ごとに -:php:class:`Cake\\I18n\\Time` インスタンスを返すので、そのメソッドを使用して +:php:class:`\\Cake\\I18n\\Time` インスタンスを返すので、そのメソッドを使用して ほとんどのタスクを実行できるからです。例えば、受け入れられた書式指定文字列について 読むには、 `Cake\\I18n\\Time::i18nFormat() `_ diff --git a/ja/views/themes.rst b/ja/views/themes.rst index 493e3b447a..e2373c4d92 100644 --- a/ja/views/themes.rst +++ b/ja/views/themes.rst @@ -48,7 +48,7 @@ edit テンプレートを **plugins/Modern/templates/plugin/Cms/Tags/edit.php** テーマは CakePHP の標準のプラグインなので、必要なアセットを webroot ディレクトリーに 含めることができます。これは、テーマの配布と容易なパッケージングを可能にさせます。 -開発中、テーマのアセットへのリクエストは :php:class:`Cake\\Routing\\Dispatcher` +開発中、テーマのアセットへのリクエストは :php:class:`\\Cake\\Routing\\Dispatcher` によってハンドリングされます。プロダクション環境でパフォーマンスを改善するためには、 :ref:`symlink-assets` を推奨します。 diff --git a/pt/console-and-shells.rst b/pt/console-and-shells.rst index f25b6e8281..a7dfa3ff5a 100644 --- a/pt/console-and-shells.rst +++ b/pt/console-and-shells.rst @@ -789,8 +789,8 @@ Dentro da especificação do interpretador, você pode definir as chaves para ``arguments``, ``options``, ``description`` e ``epilog``. Você não pode definir ``subcommands`` dentro de um construtor estilo array. Os valores para os argumentos e opções, devem seguir o formato que -:php:func:`Cake\\Console\\ConsoleOptionParser::addArguments()` e -:php:func:`Cake\\Console\\ConsoleOptionParser::addOptions()` usam. Você também +:php:func:`\\Cake\\Console\\ConsoleOptionParser::addArguments()` e +:php:func:`\\Cake\\Console\\ConsoleOptionParser::addOptions()` usam. Você também pode usar buildFromArray por conta própria, para construir um interpretador de opção:: diff --git a/pt/controllers.rst b/pt/controllers.rst index d44cd86f29..08115a8688 100644 --- a/pt/controllers.rst +++ b/pt/controllers.rst @@ -41,7 +41,7 @@ O App Controller Como mencionado anteriormente, a classe ``AppController`` é a mãe de todos os outros controllers da sua aplicação. A própria ``AppController`` é estendida da -classe :php:class:`Cake\\Controller\\Controller` incluída no CakePHP. +classe :php:class:`\\Cake\\Controller\\Controller` incluída no CakePHP. Assim sendo, ``AppController`` é definida em **src/Controller/AppController.php** como a seguir:: @@ -90,8 +90,8 @@ Fluxo de requisições ==================== Quando uma requisição é feita para uma aplicação CakePHP, a classe -:php:class:`Cake\\Routing\\Router` e a classe -:php:class:`Cake\\Routing\\Dispatcher` usam :ref:`routes-configuration` para +:php:class:`\\Cake\\Routing\\Router` e a classe +:php:class:`\\Cake\\Routing\\Dispatcher` usam :ref:`routes-configuration` para encontrar e criar a instância correta do controller. Os dados da requisição são encapsulados em um objeto de requisição. O CakePHP coloca todas as informações importantes de uma requisição na propriedade ``$this->request``. Veja a seção @@ -478,7 +478,7 @@ inserir lógicas em torno do ciclo de vida de uma requisição: Chamada após a lógica da action de um controller, mas antes da view ser renderizada. Esse callback não é usado frequentemente, mas pode ser necessário se você estiver chamando - :php:meth:`~Cake\\Controller\\Controller::render()` manualmente antes do + :php:meth:`\\Cake\\Controller\\Controller::render()` manualmente antes do final de uma determinada action. .. php:method:: afterFilter() diff --git a/pt/controllers/components/security.rst b/pt/controllers/components/security.rst index fb4d852fd6..a4bba3d9d3 100644 --- a/pt/controllers/components/security.rst +++ b/pt/controllers/components/security.rst @@ -3,7 +3,7 @@ Security (Segurança) .. php:class:: SecurityComponent(ComponentCollection $collection, array $config = []) -O componente de segurança cria uma maneira fácil de integrar maior segurança ao +O componente de segurança cria uma maneira fácil de integrar maior segurança ao seu aplicativo. Ele fornece métodos para várias tarefas, como: * Restringindo quais métodos HTTP seu aplicativo aceita. @@ -11,33 +11,33 @@ seu aplicativo. Ele fornece métodos para várias tarefas, como: * Exigindo que o SSL seja usado. * Limitar a comunicação entre controladores. -Como todos os componentes, ele é ajustado através de vários parâmetros configuráveis. -Todas essas propriedades podem ser definidas diretamente ou através de métodos setter +Como todos os componentes, ele é ajustado através de vários parâmetros configuráveis. +Todas essas propriedades podem ser definidas diretamente ou através de métodos setter com o mesmo nome no ``beforeFilter()`` do seu controlador. -Ao usar o componente de segurança, você obtém automaticamente proteção -contra violação de formulários. Os campos de token oculto são inseridos +Ao usar o componente de segurança, você obtém automaticamente proteção +contra violação de formulários. Os campos de token oculto são inseridos automaticamente nos formulários e verificados pelo componente Security. -Se você estiver usando os recursos de proteção de formulário do componente -Security e outros componentes que processam dados do formulário em seus -retornos de chamada ``startup()``, certifique-se de colocar o Componente +Se você estiver usando os recursos de proteção de formulário do componente +Security e outros componentes que processam dados do formulário em seus +retornos de chamada ``startup()``, certifique-se de colocar o Componente de Segurança antes desses componentes no método ``initialize()``. .. note:: - Ao usar o componente de segurança, você deve usar o FormHelper para criar seus - formulários. Além disso, você não deve substituir nenhum dos atributos "name" dos - campos. O componente de segurança procura determinados indicadores criados e - gerenciados pelo FormHelper (especialmente aqueles criados em - :php:meth:`~Cake\\View\\Helper\\FormHelper::create()` e :php:meth:`~Cake\\View\\Helper\\FormHelper::end()`). - Alterar dinamicamente os campos que são enviados em uma solicitação POST (por exemplo, - desativar, excluir ou criar novos campos via JavaScript) provavelmente fará com + Ao usar o componente de segurança, você deve usar o FormHelper para criar seus + formulários. Além disso, você não deve substituir nenhum dos atributos "name" dos + campos. O componente de segurança procura determinados indicadores criados e + gerenciados pelo FormHelper (especialmente aqueles criados em + :php:meth:`\\Cake\\View\\Helper\\FormHelper::create()` e :php:meth:`\\Cake\\View\\Helper\\FormHelper::end()`). + Alterar dinamicamente os campos que são enviados em uma solicitação POST (por exemplo, + desativar, excluir ou criar novos campos via JavaScript) provavelmente fará com que a solicitação seja enviada como retorno a um blackhole. - - Você sempre deve verificar o método HTTP que está sendo usado antes da execução - para evitar efeitos colaterais. Você deve :ref:`check the HTTP method ` - ou usar :php:meth:`Cake\\Http\\ServerRequest::allowMethod()` para garantir que + + Você sempre deve verificar o método HTTP que está sendo usado antes da execução + para evitar efeitos colaterais. Você deve :ref:`check the HTTP method ` + ou usar :php:meth:`\\Cake\\Http\\ServerRequest::allowMethod()` para garantir que o método HTTP correto seja usado. Como Lidar com Retornos de Chamada Blackhole @@ -45,18 +45,18 @@ Como Lidar com Retornos de Chamada Blackhole .. php:method:: blackHole(Controller $controller, string $error = '', ?SecurityException $exception = null) -Se uma ação for restringida pelo Componente de Segurança, ela será 'ocultada em preto' -como uma solicitação inválida que resultará em um erro 400 por padrão. Você pode configurar -esse comportamento definindo a opção de configuração ``blackHoleCallback`` como uma função +Se uma ação for restringida pelo Componente de Segurança, ela será 'ocultada em preto' +como uma solicitação inválida que resultará em um erro 400 por padrão. Você pode configurar +esse comportamento definindo a opção de configuração ``blackHoleCallback`` como uma função de retorno de chamada no controlador. -Ao configurar um método de retorno de chamada, você pode personalizar como o processo do +Ao configurar um método de retorno de chamada, você pode personalizar como o processo do blackhole funciona:: public function beforeFilter(EventInterface $event) { parent::beforeFilter($event); - + $this->Security->setConfig('blackHoleCallback', 'blackhole'); } @@ -66,11 +66,11 @@ blackhole funciona:: // Reescreva a mensagem de exceção com uma sequência traduzível. $exception->setMessage(__('Please access the requested page through HTTPS')); } - + // Lance novamente a exceção reformulada condicionalmente. throw $exception; - // Como alternativa, lide com o erro, ex.: defina uma mensagem flash e + // Como alternativa, lide com o erro, ex.: defina uma mensagem flash e // redirecione para a versão HTTPS da página solicitada. } @@ -84,16 +84,16 @@ Restringir Ações ao SSL .. php:method:: requireSecure() - Define as ações que requerem uma solicitação protegida por SSL. - Leva qualquer número de argumentos. Pode ser chamado sem argumentos + Define as ações que requerem uma solicitação protegida por SSL. + Leva qualquer número de argumentos. Pode ser chamado sem argumentos para forçar todas as ações a exigir um SSL protegido. .. php:method:: requireAuth() - Define as ações que requerem um token válido gerado pelo Componente de segurança. - Leva qualquer número de argumentos. Pode ser chamado sem argumentos para forçar + Define as ações que requerem um token válido gerado pelo Componente de segurança. + Leva qualquer número de argumentos. Pode ser chamado sem argumentos para forçar todas as ações a exigir uma autenticação válida. - + Restringindo a Comunicação entre Controladores ============================================== @@ -109,39 +109,39 @@ Essas opções de configuração permitem restringir a comunicação entre contr Prevenção de Adulteração de Formulários ======================================= -Por padrão, o ``SecurityComponent`` impede que os usuários adulterem formulários de +Por padrão, o ``SecurityComponent`` impede que os usuários adulterem formulários de maneiras específicas. O `` SecurityComponent`` impedirá o seguinte: * Campos desconhecidos não podem ser adicionados ao formulário. * Os campos não podem ser removidos do formulário. * Os valores nas entradas ocultas não podem ser modificados. -A prevenção desses tipos de adulteração é realizada trabalhando com o ``FormHelper`` e -rastreando quais campos estão em um formulário. Os valores para campos ocultos também -são rastreados. Todos esses dados são combinados e transformados em um hash. Quando um -formulário é enviado, o ``SecurityComponent`` usará os dados do POST para criar a mesma +A prevenção desses tipos de adulteração é realizada trabalhando com o ``FormHelper`` e +rastreando quais campos estão em um formulário. Os valores para campos ocultos também +são rastreados. Todos esses dados são combinados e transformados em um hash. Quando um +formulário é enviado, o ``SecurityComponent`` usará os dados do POST para criar a mesma estrutura e comparar o hash. .. note:: - O SecurityComponent **não** impede que as opções selecionadas sejam adicionadas/alteradas. + O SecurityComponent **não** impede que as opções selecionadas sejam adicionadas/alteradas. Nem impedirá que as opções de rádio sejam adicionadas/alteradas. unlockedFields - Defina para uma lista de campos de formulário a serem excluídos da validação - do POST. Os campos podem ser desbloqueados no Component ou com :php:meth:`FormHelper::unlockField()`. - Os campos que foram desbloqueados não precisam fazer parte do POST e os + Defina para uma lista de campos de formulário a serem excluídos da validação + do POST. Os campos podem ser desbloqueados no Component ou com :php:meth:`FormHelper::unlockField()`. + Os campos que foram desbloqueados não precisam fazer parte do POST e os campos desbloqueados ocultos não têm seus valores verificados. validatePost - Defina como ``false`` para ignorar completamente a validação + Defina como ``false`` para ignorar completamente a validação de solicitações POST, essencialmente desativando a validação de formulário. Uso === -Geralmente, o uso do componente de segurança é feito no ``beforeFilter()`` do -controlador. Você especificaria as restrições de segurança que deseja e o +Geralmente, o uso do componente de segurança é feito no ``beforeFilter()`` do +controlador. Você especificaria as restrições de segurança que deseja e o Componente de Segurança as aplicará em sua inicialização:: namespace App\Controller; @@ -167,7 +167,7 @@ Componente de Segurança as aplicará em sua inicialização:: } } -O exemplo acima forçaria todas as ações que tinham roteamento de +O exemplo acima forçaria todas as ações que tinham roteamento de administrador a exigir solicitações SSL seguras:: namespace App\Controller; @@ -202,9 +202,9 @@ administrador a exigir solicitações SSL seguras:: } } -Este exemplo forçaria todas as ações que tinham roteamento de administrador a -exigir solicitações SSL seguras. Quando a solicitação é ocultada em preto, ele -chama o retorno de chamada ``forceSSL()``, que redirecionará solicitações não +Este exemplo forçaria todas as ações que tinham roteamento de administrador a +exigir solicitações SSL seguras. Quando a solicitação é ocultada em preto, ele +chama o retorno de chamada ``forceSSL()``, que redirecionará solicitações não seguras para proteger solicitações automaticamente. .. _security-csrf: @@ -212,17 +212,17 @@ seguras para proteger solicitações automaticamente. Proteção CSRF ============= -CSRF ou falsificação de solicitação entre sites é uma vulnerabilidade comum em -aplicativos da web. Ele permite que um invasor capture e reproduza uma solicitação -anterior e, às vezes, envie solicitações de dados usando tags ou recursos de imagem +CSRF ou falsificação de solicitação entre sites é uma vulnerabilidade comum em +aplicativos da web. Ele permite que um invasor capture e reproduza uma solicitação +anterior e, às vezes, envie solicitações de dados usando tags ou recursos de imagem em outros domínios. Para habilitar os recursos de proteção CSRF, use :ref:`csrf-middleware`. Desabilitando o Componente de Segurança para Ações Específicas ============================================================== -Pode haver casos em que você deseja desativar todas as verificações de -segurança de uma ação (por exemplo, solicitações AJAX). Você pode "desbloquear" -essas ações listando-as em ``$this->Security->unlockedActions`` em seu ``beforeFilter()``. +Pode haver casos em que você deseja desativar todas as verificações de +segurança de uma ação (por exemplo, solicitações AJAX). Você pode "desbloquear" +essas ações listando-as em ``$this->Security->unlockedActions`` em seu ``beforeFilter()``. A propriedade ``unlockedActions`` **não** afeta outros recursos do ``SecurityComponent``:: namespace App\Controller; diff --git a/pt/controllers/request-response.rst b/pt/controllers/request-response.rst index 4e2d2df319..0001e0335a 100644 --- a/pt/controllers/request-response.rst +++ b/pt/controllers/request-response.rst @@ -91,7 +91,7 @@ Dados do Corpo da Requisição .. php:method:: getData($name, $default = null) -Todos os dados do POST podem ser acessados usando :php:meth:`Cake\\Http\\ServerRequest::getData()`. +Todos os dados do POST podem ser acessados usando :php:meth:`\\Cake\\Http\\ServerRequest::getData()`. Qualquer dado de formulário que contenha um prefixo ``data`` terá esse prefixo de dados removido. Por exemplo:: @@ -195,7 +195,7 @@ de solicitação específicos do aplicativo:: $isPost = $this->request->is('post'); Você também pode estender os detectores de solicitação disponíveis, usando -:php:meth:`Cake\\Http\\ServerRequest::addDetector()` para criar +:php:meth:`\\Cake\\Http\\ServerRequest::addDetector()` para criar novos tipos de detectores. Existem quatro tipos diferentes de detectores que você pode criar: @@ -249,9 +249,9 @@ Alguns exemplos seriam:: ); ``Request`` também inclui métodos como -:php:meth:`Cake\\Http\\ServerRequest::domain()`, -:php:meth:`Cake\\Http\\ServerRequest::subdomains()` e -:php:meth:`Cake\\Http\\ServerRequest::host()` para ajudar aplicativos com subdomínios, +:php:meth:`\\Cake\\Http\\ServerRequest::domain()`, +:php:meth:`\\Cake\\Http\\ServerRequest::subdomains()` e +:php:meth:`\\Cake\\Http\\ServerRequest::host()` para ajudar aplicativos com subdomínios, tenha uma vida um pouco mais fácil. Existem vários detectores embutidos que você pode usar: @@ -441,7 +441,7 @@ Os cookies de solicitação podem ser lidos através de vários métodos:: // Obter uma instância CookieCollection $cookies = $this->request->getCookieCollection() -Consulte a documentação :php:class:`Cake\\Http\\Cookie\\CookieCollection` +Consulte a documentação :php:class:`\\Cake\\Http\\Cookie\\CookieCollection` para saber como trabalhar com a coleção de cookies. Arquivos Enviados @@ -482,14 +482,14 @@ Resposta .. php:class:: Response -:php:class:`Cake\\Http\\Response` é a classe de resposta padrão no CakePHP. +:php:class:`\\Cake\\Http\\Response` é a classe de resposta padrão no CakePHP. Ele encapsula vários recursos e funcionalidades para gerar respostas HTTP em seu aplicativo. Também auxilia nos testes, pois pode ser simulado/esboçado, permitindo que você inspecione os cabeçalhos que serão enviados. Como -:php:class:`Cake\\Http\\ServerRequest`, :php:class:`Cake\\Http\\Response` +:php:class:`\\Cake\\Http\\ServerRequest`, :php:class:`\\Cake\\Http\\Response` consolida uma série de métodos encontrados anteriormente em :php:class:`Controller`, :php:class:`RequestHandlerComponent` e :php:class:`Dispatcher`. Os métodos -antigos são preteridos no uso de :php:class:`Cake\\Http\\Response`. +antigos são preteridos no uso de :php:class:`\\Cake\\Http\\Response`. ``Response`` fornece uma interface para agrupar tarefas comuns relacionadas à resposta, como: @@ -505,7 +505,7 @@ Lidando com Tipos de Conteúdo .. php:method:: withType($contentType = null) Você pode controlar o tipo de conteúdo das respostas do seu aplicativo com -:php:meth:`Cake\\Http\\Response::withType()`. Se seu aplicativo precisar +:php:meth:`\\Cake\\Http\\Response::withType()`. Se seu aplicativo precisar lidar com tipos de conteúdo que não estão embutidos no Response, você pode mapeá-los com ``type()`` também:: @@ -528,7 +528,7 @@ Enviando Arquivos .. php:method:: withFile($path, $options = []) Há momentos em que você deseja enviar arquivos como respostas para suas -solicitações. Você pode fazer isso usando :php:meth:`Cake\\Http\\Response::withFile()`:: +solicitações. Você pode fazer isso usando :php:meth:`\\Cake\\Http\\Response::withFile()`:: public function sendFile($id) { @@ -542,8 +542,8 @@ solicitações. Você pode fazer isso usando :php:meth:`Cake\\Http\\Response::wi Como mostrado no exemplo acima, você deve passar o caminho do arquivo para o método. O CakePHP enviará um cabeçalho de tipo de conteúdo adequado se for um tipo de arquivo conhecido listado em `Cake\\Http\\Response::$_mimeTypes`. -Você pode adicionar novos tipos antes de chamar :php:meth:`Cake\\Http\\Response::withFile()` -usando o método :php:meth:`Cake\\Http\\Response::withType()`. +Você pode adicionar novos tipos antes de chamar :php:meth:`\\Cake\\Http\\Response::withFile()` +usando o método :php:meth:`\\Cake\\Http\\Response::withType()`. Se desejar, você também pode forçar o download de um arquivo em vez de ser exibido no navegador, especificando as opções:: @@ -598,7 +598,7 @@ Definindo Cabeçalhos .. php:method:: withHeader($header, $value) -A configuração dos cabeçalhos é feita com o método :php:meth:`Cake\\Http\\Response::withHeader()`. +A configuração dos cabeçalhos é feita com o método :php:meth:`\\Cake\\Http\\Response::withHeader()`. Como todos os métodos de interface PSR-7, esse método retorna uma instância *new* com o novo cabeçalho:: // Adicionar/substituir um cabeçalho @@ -614,7 +614,7 @@ Como todos os métodos de interface PSR-7, esse método retorna uma instância * Os cabeçalhos não são enviados quando definidos. Em vez disso, eles são mantidos até que a resposta seja emitida por ``Cake\Http\Server``. -Agora você pode usar o método conveniente :php:meth:`Cake\\Http\\Response::withLocation()` +Agora você pode usar o método conveniente :php:meth:`\\Cake\\Http\\Response::withLocation()` para definir diretamente ou obter o cabeçalho do local de redirecionamento. Definindo o Corpo @@ -680,7 +680,7 @@ Interagindo com o Cache do Navegador .. php:method:: withDisabledCache() Às vezes, você precisa forçar os navegadores a não armazenar em cache os resultados -de uma ação do controlador. :php:meth:`Cake\\Http\\Response::withDisabledCache()` +de uma ação do controlador. :php:meth:`\\Cake\\Http\\Response::withDisabledCache()` é destinado apenas para isso:: public function index() @@ -697,7 +697,7 @@ de uma ação do controlador. :php:meth:`Cake\\Http\\Response::withDisabledCache .. php:method:: withCache($since, $time = '+1 day') Você também pode dizer aos clientes que deseja que eles armazenem respostas em cache. -Usando :php:meth:`Cake\\Http\\Response::withCache()`:: +Usando :php:meth:`\\Cake\\Http\\Response::withCache()`:: public function index() { @@ -725,7 +725,7 @@ Em vez de forçar você a codificar a lógica para armazenar em cache e invalid (atualizando) depois que os dados forem alterados, o HTTP usa dois modelos, expiração e validação, que geralmente são muito mais simples de usar. -Além de usar :php:meth:`Cake\\Http\\Response::withCache()`, você também pode usar +Além de usar :php:meth:`\\Cake\\Http\\Response::withCache()`, você também pode usar muitos outros métodos para ajustar os cabeçalhos de cache HTTP para tirar proveito do cache do navegador ou do proxy reverso. @@ -876,7 +876,7 @@ o conteúdo da resposta e envia o cabeçalho `304 Not Modified`:: Configurando Cookies -------------------- -Os cookies podem ser adicionados à resposta usando um array ou um objeto :php:class:`Cake\\Http\\Cookie\\Cookie`:: +Os cookies podem ser adicionados à resposta usando um array ou um objeto :php:class:`\\Cake\\Http\\Cookie\\Cookie`:: use Cake\Http\Cookie\Cookie; use DateTime; diff --git a/pt/core-libraries/caching.rst b/pt/core-libraries/caching.rst index 9f315b8185..9f86714c37 100644 --- a/pt/core-libraries/caching.rst +++ b/pt/core-libraries/caching.rst @@ -37,7 +37,7 @@ seu próprio back-end. Os mecanismos de armazenamento em cache integrados são: * ``Null`` O mecanismo nulo não armazena nada e falha em todas as operações de leitura. Independentemente do CacheEngine que você escolher, seu aplicativo interage com -:php:class:`Cake\\Cache\\Cache`. +:php:class:`\\Cake\\Cache\\Cache`. .. _cache-configuration: @@ -110,7 +110,7 @@ Você também pode configurar os mecanismos de cache em tempo de execução:: Cache::setConfig('other', $object); O nome dessas configurações de mecanismo ('curto' e 'longo') é usado como o parâmetro ``$config`` -para :php:meth:`Cake\\Cache\\Cache::write()` e :php:meth:`Cake\\Cache\\Cache::read()`. Ao configurar +para :php:meth:`\\Cake\\Cache\\Cache::write()` e :php:meth:`\\Cake\\Cache\\Cache::read()`. Ao configurar mecanismos de cache, você pode consultar o nome da classe usando as seguintes sintaxes:: // Nome curto (in App\ or Cake namespaces) @@ -230,8 +230,8 @@ Remoção de Mecanismos de Cache Configurados .. php:staticmethod:: drop($key) Depois que uma configuração é criada, você não pode alterá-la. Em vez disso, você -deve descartar a configuração e recriá-la usando :php:meth:`Cake\\Cache\\Cache::drop()` e -:php:meth:`Cake\\Cache\\Cache::setConfig()`. Descartar um mecanismo de cache +deve descartar a configuração e recriá-la usando :php:meth:`\\Cake\\Cache\\Cache::drop()` e +:php:meth:`\\Cake\\Cache\\Cache::setConfig()`. Descartar um mecanismo de cache removerá a configuração e destruirá o adaptador, se ele tiver sido construído. Gravando em um Cache @@ -448,7 +448,7 @@ Usando o Cache para Armazenar Resultados Comuns de Consulta Você pode melhorar bastante o desempenho do seu aplicativo colocando resultados que raramente mudam ou estão sujeitos a leituras pesadas no cache. Um exemplo -perfeito disso são os resultados de :php:meth:`Cake\\ORM\\Table::find()`. O objeto +perfeito disso são os resultados de :php:meth:`\\Cake\\ORM\\Table::find()`. O objeto Query permite armazenar resultados em cache usando o método ``cache()``. Veja a seção :ref:`caching-query-results` para mais informações. @@ -551,7 +551,7 @@ As configurações de cache dos plugins precisam usar a sintaxe de pontos do plu // ... ]); -Os mecanismos de cache personalizado devem estender :php:class:`Cake\\Cache\\CacheEngine`, +Os mecanismos de cache personalizado devem estender :php:class:`\\Cake\\Cache\\CacheEngine`, que define vários métodos abstratos, além de fornecer alguns métodos de inicialização. A API necessária para um CacheEngine é diff --git a/pt/core-libraries/collections.rst b/pt/core-libraries/collections.rst index 090dee81d6..8c16256c93 100644 --- a/pt/core-libraries/collections.rst +++ b/pt/core-libraries/collections.rst @@ -167,7 +167,7 @@ importante quando estamos obtendo resultados com chaves possivelmente duplicadas Ao usar ``toList()``, garantimos a obtenção de todos os valores, mesmo que haja chaves duplicadas. -Ao contrário de :php:meth:`Cake\\Utility\\Hash::extract()` este método suporta +Ao contrário de :php:meth:`\\Cake\\Utility\\Hash::extract()` este método suporta apenas o curinga ``{*}``. Todos os outros correspondentes de curinga e atributos não são suportados. diff --git a/pt/core-libraries/form.rst b/pt/core-libraries/form.rst index a51d5051c4..f0d06e2c7c 100644 --- a/pt/core-libraries/form.rst +++ b/pt/core-libraries/form.rst @@ -57,7 +57,7 @@ No exemplo acima vemos os 3 métodos hooks que o formulário fornece: * ``_buildSchema`` é usado para definir o esquema de dados usado pelo FormHelper para criar um formulário HTML. Você pode definir o tipo de campo, tamanho, e precisão. -* ``_buildValidator`` Pega uma instância do :php:class:`Cake\\Validation\\Validator` +* ``_buildValidator`` Pega uma instância do :php:class:`\\Cake\\Validation\\Validator` que você pode você juntar com os validadores. * ``_execute`` permite definir o comportamento desejado quando o ``execute()`` é chamado e o dado é válido. diff --git a/pt/core-libraries/global-constants-and-functions.rst b/pt/core-libraries/global-constants-and-functions.rst index ec1507d453..79bb81efe2 100644 --- a/pt/core-libraries/global-constants-and-functions.rst +++ b/pt/core-libraries/global-constants-and-functions.rst @@ -89,7 +89,7 @@ Aqui estão as funções disponíveis globalmente no CakePHP. A maioria delas s .. php:function:: collection(mixed $items) *Wrapper* de conveniência para instanciar um novo objeto - :php:class:`Cake\\Collection\\Collection`, re-passando o devido argumento. + :php:class:`\\Cake\\Collection\\Collection`, re-passando o devido argumento. O parâmetro ``$items`` recebe tanto um objeto ``Traversable`` quanto um *array*. diff --git a/pt/core-libraries/number.rst b/pt/core-libraries/number.rst index c650ea9ef2..a560d63bb6 100644 --- a/pt/core-libraries/number.rst +++ b/pt/core-libraries/number.rst @@ -110,7 +110,7 @@ Definição da moeda padrão .. php:method:: setDefaultCurrency($currency) Atribui a moeda padrão. Isso elimina a necessidade de sempre passar a moeda -para :php:meth:`Cake\\I18n\\Number::currency()` e alterar todas as saídas de +para :php:meth:`\\Cake\\I18n\\Number::currency()` e alterar todas as saídas de moeda definindo outro padrão. Se ``$currency`` atribuído o valor ``null``, ele apagará o valor armazenado no momento. @@ -152,7 +152,7 @@ Formatação de Porcentagens | | multiplicado por 100. Útil para porcentagens decimais. | +---------------------+--------------------------------------------------------+ -Da mesma forma :php:meth:`Cake\\I18n\\Number::precision()`, ste método formata um +Da mesma forma :php:meth:`\\Cake\\I18n\\Number::precision()`, ste método formata um número de acordo com a precisão fornecida (onde os números são arredondados para atender à precisão fornecida). Este método também expressa o número como uma porcentagem e anexa a saída com um sinal de porcentagem. :: diff --git a/pt/core-libraries/security.rst b/pt/core-libraries/security.rst index f1bd39ae1f..c22e48c893 100644 --- a/pt/core-libraries/security.rst +++ b/pt/core-libraries/security.rst @@ -37,7 +37,7 @@ o método de ``hash`` de mão única fornecidos por Se você não fornecer um ``HMAC salt``, o valor em ``Security.salt`` será usado. Os valores criptografados podem ser descriptografados usando -:php:meth:`Cake\\Utility\\Security::decrypt()`. +:php:meth:`\\Cake\\Utility\\Security::decrypt()`. Descriptografando um valor criptografado anteriormente. Os parametros ``$key`` e ``$hmacSalt`` devem corresponder aos valores utilizados para a criptografia senão o processo falhará. diff --git a/pt/development/debugging.rst b/pt/development/debugging.rst index 5d8e4ff57d..827dab7c69 100644 --- a/pt/development/debugging.rst +++ b/pt/development/debugging.rst @@ -147,7 +147,7 @@ Usando Logging para Depuração ============================= Registrar as mensagens é uma outra boa maneira de se depurar aplicações. Para -isto, pode ser usada a classe :php:class:`Cake\\Log\\Log` para fazer o logging +isto, pode ser usada a classe :php:class:`\\Cake\\Log\\Log` para fazer o logging na sua aplicação. Todos os objetos que fazem uso de ``LogTrait`` têm um método de instanciação ``log()`` que pode ser usado para registrar mensagens:: @@ -156,7 +156,7 @@ de instanciação ``log()`` que pode ser usado para registrar mensagens:: O código acima escreverá ``Cheguei aqui`` no arquivo de registros de depuração (debug log). Você pode usar seus registros para auxiliar na depuração de métodos que contêm redirecionamentos e laços complicados. Você poderá usar também -:php:meth:`Cake\\Log\\Log::write()` para escrever mensagens nos registros. Esse +:php:meth:`\\Cake\\Log\\Log::write()` para escrever mensagens nos registros. Esse método pode ser chamado de forma estática em qualquer lugar da sua aplicação, pressupondo-se que Log já esteja carregado:: diff --git a/pt/development/errors.rst b/pt/development/errors.rst index 1eb4584d77..4fa7669f75 100644 --- a/pt/development/errors.rst +++ b/pt/development/errors.rst @@ -16,7 +16,7 @@ personalizar o tratamento de erros para o seu aplicativo. As seguintes opções * ``errorLevel`` - int - O nível de erros que você está interessado em capturar. Use as constantes de erro embutidas no PHP e máscaras de bits para selecionar o nível de erro no qual você precisa. Você pode configurá-lo como ``E_ALL ^ E_USER_DEPRECATED`` para desativar os avisos de depreciação. * ``trace`` - bool - Inclua rastreamentos de pilha para erros nos arquivos de log. Rastreamentos de pilha serão incluídos no log após cada erro. Isso é útil para descobrir onde/quando os erros estão sendo gerados * ``exceptionRenderer`` - string - A classe responsável por renderizar exceções não capturadas. Se você escolher uma classe personalizada, coloque o arquivo dessa classe em **src/Error**. Esta classe precisa implementar o método ``render()``. -* ``log`` - bool - Quando ``true``, as exceções + seus rastreamentos de pilha serão registrados em :php:class:`Cake\\Log\\Log` +* ``log`` - bool - Quando ``true``, as exceções + seus rastreamentos de pilha serão registrados em :php:class:`\\Cake\\Log\\Log` * ``skipLog`` - array - Uma matriz de nomes de classes de exceção que não devem ser registrados. Isso é útil para remover NotFoundExceptions ou outras mensagens de log comuns, mas desinteressantes. * ``extraFatalErrorMemory`` - int - Defina como o número de megabytes para aumentar o limite de memória quando um erro fatal for encontrado. Isso permite que o espaço sobrando complete o registro ou o tratamento de erros. @@ -323,7 +323,7 @@ Logging Exceptions Using the built-in exception handling, you can log all the exceptions that are dealt with by ErrorHandler by setting the ``log`` option to ``true`` in your **config/app.php**. Enabling this will log every exception to -:php:class:`Cake\\Log\\Log` and the configured loggers. +:php:class:`\\Cake\\Log\\Log` and the configured loggers. .. note:: @@ -536,8 +536,8 @@ In addition, CakePHP uses the following exceptions: .. php:exception:: PersistenceFailedException - An entity couldn't be saved/deleted while using :php:meth:`Cake\\ORM\\Table::saveOrFail()` or - :php:meth:`Cake\\ORM\\Table::deleteOrFail()`. + An entity couldn't be saved/deleted while using :php:meth:`\\Cake\\ORM\\Table::saveOrFail()` or + :php:meth:`\\Cake\\ORM\\Table::deleteOrFail()`. .. php:namespace:: Cake\Datasource\Exception diff --git a/pt/development/rest.rst b/pt/development/rest.rst index 0679caf994..249a848685 100644 --- a/pt/development/rest.rst +++ b/pt/development/rest.rst @@ -140,7 +140,7 @@ Criar uma lógica para editar uma action é um pouco mais complicado, mas não m que você está fornecendo uma API que emite XML, é uma escolha natural para receber XML Como entrada. Não se preocupe, o :php:class:`Cake\\Controller\\Component\\RequestHandler` e -:php:class:`Cake\\Routing\\Router` tornam as coisas muito mais fáceis. Se um POST ou +:php:class:`\\Cake\\Routing\\Router` tornam as coisas muito mais fáceis. Se um POST ou A solicitação PUT tem um tipo de conteúdo XML, então a entrada é executada através do CakePHP's :php:class:`Xml`, e a representação da array dos dados é atribuída a ``$this->request->getData()``. Devido a essa característica, lidar com dados XML e POST em diff --git a/pt/development/routing.rst b/pt/development/routing.rst index 64e2045c19..30d3628abc 100644 --- a/pt/development/routing.rst +++ b/pt/development/routing.rst @@ -1188,7 +1188,7 @@ As classes de rota personalizadas permitem estender e alterar como rotas individ manipulam o roteamento reverso. As classes de rota têm algumas convenções: * As classes de rota devem ser encontradas no espaço de nome ``Routing\\Route`` do seu aplicativo ou plugin. -* As classes de rota devem estender :php:class:`Cake\\Routing\\Route`. +* As classes de rota devem estender :php:class:`\\Cake\\Routing\\Route`. * As classes de rota devem implementar os métodos ``match()`` e/ou ``parse()``. O método ``parse()`` é usado para analisar uma URL recebida. Ele deve gerar uma matriz de parâmetros de solicitação diff --git a/pt/development/sessions.rst b/pt/development/sessions.rst index 9f2c515e71..8d32c523c2 100644 --- a/pt/development/sessions.rst +++ b/pt/development/sessions.rst @@ -279,7 +279,7 @@ A classe deve se parecer com:: } Nossa classe estende o ``DatabaseSession`` interno, para que não tenhamos que duplicar -toda a sua lógica e comportamento. Envolvemos cada operação com uma operação :php:class:`Cake\\Cache\\Cache`. +toda a sua lógica e comportamento. Envolvemos cada operação com uma operação :php:class:`\\Cake\\Cache\\Cache`. Isso nos permite buscar sessões no cache rápido e não ter que nos preocupar com o que acontece quando o cache é preenchido. Usar este manipulador de sessões também é fácil. No seu **app.php**, faça com que o bloco de sessões esteja como o seguinte:: diff --git a/pt/development/testing.rst b/pt/development/testing.rst index 475964031d..b1f81fa570 100644 --- a/pt/development/testing.rst +++ b/pt/development/testing.rst @@ -1178,8 +1178,8 @@ presentes num pedido regular, é necessário não só passá-los nos dados do pe mas também passá-los para a configuração do pedido de teste através da opção ``files``. Mas não é tecnicamente necessário, a menos que o seu código aceda aos ficheiros carregados através dos métodos -:php:meth:`Cake\\Http\\ServerRequest::getUploadedFile()` ou -:php:meth:`Cake\\Http\\ServerRequest::getUploadedFiles()`. +:php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFile()` ou +:php:meth:`\\Cake\\Http\\ServerRequest::getUploadedFiles()`. Vamos assumir que os artigos têm uma imagem teaser, e uma associação ``Articles hasMany Attachments``, o formulário pareceria algo parecido com isto diff --git a/pt/orm.rst b/pt/orm.rst index 1a1008bc36..6253148d0d 100644 --- a/pt/orm.rst +++ b/pt/orm.rst @@ -62,7 +62,7 @@ abertura ```_. timestamp Mapeia para o tipo TIMESTAMP. @@ -878,7 +878,7 @@ usando o método ``logQueries``:: $connection->logQueries(false); Quando o log de consultas está habilitado, as consultas serão logadas em -:php:class:`Cake\\Log\\Log` usando o nível 'debug', e o escopo 'queriesLog'. +:php:class:`\\Cake\\Log\\Log` usando o nível 'debug', e o escopo 'queriesLog'. Você precisará ter um logger configurado para capturar esse nível e escopo. Logar no ``stderr`` pode ser útil quando se estiver trabalhando com testes de unidade e logar em arquivos/syslog pode ser útil ao trabalhar com diff --git a/pt/orm/deleting-data.rst b/pt/orm/deleting-data.rst index 45a2788260..e610e7a236 100644 --- a/pt/orm/deleting-data.rst +++ b/pt/orm/deleting-data.rst @@ -39,7 +39,7 @@ Exclusão em Cascata Ao excluir entidades, os dados associados também podem ser excluídos. Se suas associações HasOne e HasMany estão configurados como ``dependent``, as operações de exclusão serão 'cascate' para essas entidades também. Por padrão entidades -em tabelas associadas são removidas usando :php:meth:`Cake\\ORM\\Table::deleteAll()`. +em tabelas associadas são removidas usando :php:meth:`\\Cake\\ORM\\Table::deleteAll()`. Você pode optar que o ORM carregue as entidades relacionadas, para então excluir individualmente, definindo a opção ``cascadeCallbacks`` como ``true``:: @@ -86,7 +86,7 @@ Exclusões Estrita .. php:method:: deleteOrFail($entity, $options = []) Usar esse método lançará uma -:php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` se: +:php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` se: * a entidade é nova * a entidade não tem valor de chave primária @@ -102,5 +102,5 @@ Se você deseja rastrear a entidade que falhou ao salvar, você pode usar o mét echo $e->getEntity(); } -Como isso executa internamente uma chamada ao :php:meth:`Cake\\ORM\\Table::delete()`, todos eventos de exclusão +Como isso executa internamente uma chamada ao :php:meth:`\\Cake\\ORM\\Table::delete()`, todos eventos de exclusão correspondentes serão disparados. diff --git a/pt/orm/query-builder.rst b/pt/orm/query-builder.rst index c13da9cc8d..6c60337fa6 100644 --- a/pt/orm/query-builder.rst +++ b/pt/orm/query-builder.rst @@ -56,7 +56,7 @@ Selecionando Linhas de uma Tabela } Para os exemplos restantes, suponha que ``$articles`` seja um -:php:class:`~Cake\\ORM\\Table`. Quando dentro de controladores, +:php:class:`\\Cake\\ORM\\Table`. Quando dentro de controladores, você pode usar ``$this->Articles`` em vez de ``$articles``. Quase todos os métodos em um objeto ``Query`` retornam a mesma @@ -1296,7 +1296,7 @@ Para inserir várias linhas com apenas uma consulta, você pode encadear o méto ->execute(); Geralmente, é mais fácil inserir dados usando entidades e -:php:meth:`~Cake\\ORM\\Table::save()`. Ao compor uma consulta ``SELECT`` e ``INSERT`` juntas, +:php:meth:`\\Cake\\ORM\\Table::save()`. Ao compor uma consulta ``SELECT`` e ``INSERT`` juntas, você pode criar consultas de estilo ``INSERT INTO ... SELECT`` $select = $articles->find() @@ -1346,10 +1346,10 @@ de exclusão. Em vez disso, crie um novo objeto de consulta usando ``query()``:: ->execute(); Generally, it is easier to delete data using entities and -:php:meth:`~Cake\\ORM\\Table::delete()`. +:php:meth:`\\Cake\\ORM\\Table::delete()`. Geralmente, é mais fácil excluir dados usando entidades -e :php:meth:`~Cake\\ORM\\Table::delete()`. +e :php:meth:`\\Cake\\ORM\\Table::delete()`. Prevenção de SQL Injection ========================== diff --git a/pt/orm/saving-data.rst b/pt/orm/saving-data.rst index 45a792fed5..d782132d81 100644 --- a/pt/orm/saving-data.rst +++ b/pt/orm/saving-data.rst @@ -1147,7 +1147,7 @@ Strict Saving .. php:method:: saveOrFail($entity, $options = []) Usar este método lançará uma -:php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException` se: +:php:exc:`\\Cake\\ORM\\Exception\\PersistenceFailedException` se: * as verificações das regras de validação falharam * a entidade contém erros @@ -1171,7 +1171,7 @@ Se você quiser rastrear a entidade que falhou ao salvar, você pode usar o mét echo $e->getEntity(); } -Como isso executa internamente uma chamada ao :php:meth:`Cake\\ORM\\Table::save()`, +Como isso executa internamente uma chamada ao :php:meth:`\\Cake\\ORM\\Table::save()`, todos eventos de save correspondentes serão disparados. Salvando Várias Entidades diff --git a/pt/views.rst b/pt/views.rst index e117ce10f2..68f5a584a8 100644 --- a/pt/views.rst +++ b/pt/views.rst @@ -371,7 +371,7 @@ O ``HtmlHelper`` se baseia em *view blocks*, e os métodos ``script()``, ``css() // Restante do seu layout abaixo -O :php:meth:`Cake\\View\\Helper\\HtmlHelper` também lhe permite controlar qual *block* o css ou script irá:: +O :php:class:`\\Cake\\View\\Helper\\HtmlHelper` também lhe permite controlar qual *block* o css ou script irá:: // Na sua *view* $this->Html->script('carousel', ['block' => 'scriptBottom']); diff --git a/pt/views/themes.rst b/pt/views/themes.rst index c273a2a1b6..2dccdfc3dc 100644 --- a/pt/views/themes.rst +++ b/pt/views/themes.rst @@ -49,7 +49,7 @@ e simplesmente substituí-los caso a caso na pasta do seu tema. Como os temas são plugins CakePHP padrão, eles podem incluir qualquer ``asset`` necessário em seu diretório webroot. Isso permite uma fácil embalagem e distribuição de temas. Enquanto estiver em desenvolvimento, requisições de ``assets`` do tema serão -manipuladas por: php:class:`Cake\\Routing\\Dispatcher`. Para melhorar o desempenho +manipuladas por: php:class:`\\Cake\\Routing\\Dispatcher`. Para melhorar o desempenho para ambientes de produção, é recomendável que você :ref:`symlink-assets`. Todos os ajudantes internos do CakePHP estão cientes de temas e criará o diff --git a/requirements.txt b/requirements.txt index f6d654ebf0..3bde32076f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ docutils==0.20.1 -sphinx==7.0.1 -sphinxcontrib-phpdomain==0.11.1 +sphinx==8.1.3 +sphinxcontrib-phpdomain==0.12.0 cakephpsphinx>=0.1.58,<1.0 From 8b99967eee9f474434681e0f02e3d54ccdeb4e45 Mon Sep 17 00:00:00 2001 From: Mark Story Date: Sun, 10 Nov 2024 23:53:51 -0500 Subject: [PATCH 314/337] Fix duplicate toc listings Fixes #7951 --- en/controllers/components/form-protection.rst | 4 ++-- en/security.rst | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/en/controllers/components/form-protection.rst b/en/controllers/components/form-protection.rst index 9ff4acc8ee..d81e1027b5 100644 --- a/en/controllers/components/form-protection.rst +++ b/en/controllers/components/form-protection.rst @@ -1,5 +1,5 @@ -FormProtection -############## +Form Protection Component +######################### .. php:class:: FormProtection(ComponentCollection $collection, array $config = []) diff --git a/en/security.rst b/en/security.rst index 9bedc733fe..69d14ffab8 100644 --- a/en/security.rst +++ b/en/security.rst @@ -1,14 +1,14 @@ Security ######## -CakePHP provides you some tools to secure your application. -The following sections cover those tools: +CakePHP provides you some tools to secure your application. In addition to the +:doc:`controllers/components/form-protection`, the following sections cover +additional security features: .. toctree:: :maxdepth: 1 core-libraries/security - Form Protection Middleware CSRF Protection Content Security Policy Security Headers From 5d0813a1b13257c85d7e80496c237db07abef582 Mon Sep 17 00:00:00 2001 From: ADmad Date: Mon, 11 Nov 2024 14:02:39 +0530 Subject: [PATCH 315/337] Update e.g. of DI for commands Refs https://github.com/cakephp/cakephp/pull/17957#issuecomment-2467506533 --- en/development/dependency-injection.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst index bb307fb4c9..2e1c8306ce 100644 --- a/en/development/dependency-injection.rst +++ b/en/development/dependency-injection.rst @@ -55,10 +55,13 @@ Command Example :: // In src/Command/CheckUsersCommand.php + use Cake\Console\CommandFactoryInterface; + class CheckUsersCommand extends Command { - public function __construct(public UsersService $users) + public function __construct(protected UsersService $users, ?CommandFactoryInterface $factory = null) { + parent::__construct($factory); } public function execute(Arguments $args, ConsoleIo $io) @@ -73,7 +76,8 @@ Command Example { $container ->add(CheckUsersCommand::class) - ->addArgument(UsersService::class); + ->addArgument(UsersService::class) + ->addArgument(CommandFactoryInterface::class); $container->add(UsersService::class); } From 673d8aa97732ff455f2ee8a895f9f2a8746663fa Mon Sep 17 00:00:00 2001 From: ADmad Date: Mon, 11 Nov 2024 14:05:17 +0530 Subject: [PATCH 316/337] Fix example --- en/development/dependency-injection.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst index bb307fb4c9..8cec9db107 100644 --- a/en/development/dependency-injection.rst +++ b/en/development/dependency-injection.rst @@ -89,13 +89,13 @@ Component Example :: // In src/Controller/Component/SearchComponent.php - class SearchComponent extends Command + class SearchComponent extends Component { public function __construct( ComponentRegistry $registry, private UserService $users ) { - parent::__construct($registry, []); + parent::__construct($registry); } public function something() From 348ac186ab983652a65b027f31963b61a9b197bb Mon Sep 17 00:00:00 2001 From: ADmad Date: Mon, 11 Nov 2024 14:08:50 +0530 Subject: [PATCH 317/337] Fix example --- en/development/dependency-injection.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/en/development/dependency-injection.rst b/en/development/dependency-injection.rst index 8cec9db107..2b94e5f29d 100644 --- a/en/development/dependency-injection.rst +++ b/en/development/dependency-injection.rst @@ -93,9 +93,10 @@ Component Example { public function __construct( ComponentRegistry $registry, - private UserService $users + private UserService $users, + array $config = [] ) { - parent::__construct($registry); + parent::__construct($registry, $config); } public function something() From c5dbf128710a029e850915821a3868a3265e3678 Mon Sep 17 00:00:00 2001 From: mscherer Date: Mon, 18 Nov 2024 13:53:04 +0100 Subject: [PATCH 318/337] Fix schema type to be adjustable at runtime. --- en/orm/database-basics.rst | 8 +++++--- en/orm/saving-data.rst | 7 +++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 1a0732bbbe..380f7ada41 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -599,14 +599,16 @@ We then have two ways to use our datatype in our models. Overwriting the reflected schema with our custom type will enable CakePHP's database layer to automatically convert JSON data when creating queries. In your -Table's :ref:`getSchema() method ` add the +Table's :ref:`initialize() method ` add the following:: class WidgetsTable extends Table { - public function getSchema(): TableSchemaInterface + public function initialize(array $config): void { - return parent::getSchema()->setColumnType('widget_prefs', 'json'); + parent::initialize($config); + + return $this->getSchema()->setColumnType('widget_prefs', 'json'); } } diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst index 5dd7887047..c6145ec6c4 100644 --- a/en/orm/saving-data.rst +++ b/en/orm/saving-data.rst @@ -1094,12 +1094,11 @@ column Types:: class UsersTable extends Table { - public function getSchema(): TableSchemaInterface + public function initialize(array $config): void { - $schema = parent::getSchema(); - $schema->setColumnType('preferences', 'json'); + parent::initialize($config); - return $schema; + $this->getSchema()->setColumnType('preferences', 'json'); } } From 78010453121b805d1bfbe2d9bffda490d76fcaba Mon Sep 17 00:00:00 2001 From: Mark Scherer Date: Tue, 19 Nov 2024 02:29:13 +0100 Subject: [PATCH 319/337] Dont return method call on void. --- en/orm/database-basics.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/en/orm/database-basics.rst b/en/orm/database-basics.rst index 380f7ada41..d5639e5c85 100644 --- a/en/orm/database-basics.rst +++ b/en/orm/database-basics.rst @@ -476,12 +476,14 @@ Enum Type Maps a `BackedEnum `_ to a string or integer column. To use this type you need to specify which column is associated to which BackedEnum inside the table class:: - use \Cake\Database\Type\EnumType; - use \App\Model\Enum\ArticleStatus; + use App\Model\Enum\ArticleStatus; + use Cake\Database\Type\EnumType; // in src/Model/Table/ArticlesTable.php public function initialize(array $config): void { + parent::initialize($config); + $this->getSchema()->setColumnType('status', EnumType::from(ArticleStatus::class)); } @@ -608,7 +610,7 @@ following:: { parent::initialize($config); - return $this->getSchema()->setColumnType('widget_prefs', 'json'); + $this->getSchema()->setColumnType('widget_prefs', 'json'); } } From 0fac635460f36c3d35b3516ce7678e3d87488924 Mon Sep 17 00:00:00 2001 From: ADmad Date: Thu, 21 Nov 2024 11:55:21 +0530 Subject: [PATCH 320/337] Update references to defunct SecurityComponent --- en/views/helpers/form.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/en/views/helpers/form.rst b/en/views/helpers/form.rst index 464e65617a..3cc3980c8a 100644 --- a/en/views/helpers/form.rst +++ b/en/views/helpers/form.rst @@ -2054,7 +2054,7 @@ Will output: .. note:: If you are using - :php:class:`Cake\\Controller\\Component\\SecurityComponent` in your + :php:class:`Cake\\Controller\\Component\\FormProtectionComponent` in your application you should always end your forms with ``end()``. Creating Standalone Buttons and POST Links @@ -2074,7 +2074,7 @@ Creating POST Buttons Creates a ``