Merge pull request #7979 from cakephp/6.x-patchable

6.x: add docs for patchable changes

Author: markstory

en/appendices/6-0-migration-guide.rst

@@ -20,8 +20,26 @@ Behavior Changes
 Breaking Changes
 ================
 
+Datasource
+----------
+
+- ``Datasource/Paging/PaginatedInterface`` now extends ``IteratorAggregate``
+  instead of ``Traversable``.
+
+ORM
+---
+
+- The ``_accessible`` property inside Entities has been renamed to ``patchable``
+  to better reflect its purpose.
+- ``setAccess`` method has been renamed to ``setPatchable``.
+- ``getAccessible`` method has been renamed to ``getPatchable``.
+- ``isAccessible`` method has been renamed to ``isPatchable``.
+- The ``accessibleFields`` option used in e.g. ORM Queries has been
+  renamed to ``patchableFields``.
+
+Utility
+-------
+
 - The default placeholder format for ``Text::insert()`` has been changed.
   They now use ``{foo}`` instead of ``:foo``. You can get the old
   behavior by using the ``before`` and ``after`` keys of ``$options``.
-- ``Datasource/Paging/PaginatedInterface`` now extends ``IteratorAggregate``
-  instead of ``Traversable``.

en/orm/behaviors/translate.rst

@@ -501,7 +501,7 @@ In your controller, you can marshal the data as normal::
 
 This will result in your article, the french and spanish translations all being
 persisted. You'll need to remember to add ``_translations`` into the
-``$_accessible`` fields of your entity as well.
+``$patchable`` fields of your entity as well.
 
 Validating Translated Entities
 ------------------------------

en/orm/entities.rst

@@ -361,7 +361,7 @@ into an entity allows the user to modify any and all columns. When using
 anonymous entity classes or creating the entity class with the :doc:`/bake`
 CakePHP does not protect against mass-assignment.
 
-The ``_accessible`` property allows you to provide a map of fields and
+The ``patchable`` property allows you to provide a map of fields and
 whether or not they can be mass-assigned. The values ``true`` and ``false``
 indicate whether a field can or cannot be mass-assigned::
 
@@ -371,7 +371,7 @@ indicate whether a field can or cannot be mass-assigned::
 
     class Article extends Entity
     {
-        protected array $_accessible = [
+        protected array $patchable = [
             'title' => true,
             'body' => true
         ];
@@ -386,7 +386,7 @@ fallback behavior if a field is not specifically named::
 
     class Article extends Entity
     {
-        protected array $_accessible = [
+        protected array $patchable = [
             'title' => true,
             'body' => true,
             '*' => false,
@@ -408,14 +408,14 @@ protect itself against mass assignment::
 Modifying the Guarded Fields at Runtime
 ---------------------------------------
 
-You can modify the list of guarded fields at runtime using the ``setAccess()``
+You can modify the list of guarded fields at runtime using the ``setPatchable()``
 method::
 
     // Make user_id accessible.
-    $article->setAccess('user_id', true);
+    $article->setPatchable('user_id', true);
 
     // Make title guarded.
-    $article->setAccess('title', false);
+    $article->setPatchable('title', false);
 
 .. note::
 

en/orm/saving-data.rst

@@ -139,7 +139,7 @@ one or many entities from request data. You can convert a single entity using::
 
     If you are using newEntity() and the resulting entities are missing some or
     all of the data they were passed, double check that the columns you want to
-    set are listed in the ``$_accessible`` property of your entity. See :ref:`entities-mass-assignment`.
+    set are listed in the ``$patchable`` property of your entity. See :ref:`entities-mass-assignment`.
 
 The request data should follow the structure of your entities. For example if
 you have an article, which belonged to a user, and had many comments, your
@@ -365,8 +365,8 @@ Changing Accessible Fields
 --------------------------
 
 It's also possible to allow ``newEntity()`` to write into non accessible fields.
-For example, ``id`` is usually absent from the ``_accessible`` property.  In
-such case, you can use the ``accessibleFields`` option. It could be useful to
+For example, ``id`` is usually absent from the ``patchable`` property.  In
+such case, you can use the ``patchableFields`` option. It could be useful to
 keep ids of associated entities::
 
     // In a controller
@@ -377,7 +377,7 @@ keep ids of associated entities::
             'Tags', 'Comments' => [
                 'associated' => [
                     'Users' => [
-                        'accessibleFields' => ['id' => true],
+                        'patchableFields' => ['id' => true],
                     ],
                 ],
             ],
@@ -391,7 +391,7 @@ concerned entity.
 
     If you are using newEntity() and the resulting entities are missing some or
     all of the data they were passed, double check that the columns you want to
-    set are listed in the ``$_accessible`` property of your entity. See
+    set are listed in the ``$patchable`` property of your entity. See
     :ref:`entities-mass-assignment`.
 
 Merging Request Data Into Entities
@@ -482,7 +482,7 @@ an important caveat:
 If a Product belongsToMany Tag::
 
     // in the Product Entity
-    protected array $_accessible = [
+    protected array $patchable = [
         // .. other properties
        'tags' => true,
     ];

en/tutorials-and-examples/cms/articles-model.rst

@@ -58,7 +58,7 @@ look like this::
 
     class Article extends Entity
     {
-        protected array $_accessible = [
+        protected array $patchable = [
             'user_id' => true,
             'title' => true,
             'slug' => true,
@@ -71,7 +71,7 @@ look like this::
         ];
     }
 
-Right now, our entity is quite slim; we've only set up the ``_accessible``
+Right now, our entity is quite slim; we've only set up the ``patchable``
 property, which controls how properties can be modified by
 :ref:`entities-mass-assignment`.
 

en/tutorials-and-examples/cms/authorization.rst

@@ -225,7 +225,7 @@ Next we'll update the ``edit`` action. Replace the edit method with the followin
         if ($this->request->is(['post', 'put'])) {
             $this->Articles->patchEntity($article, $this->request->getData(), [
                 // Added: Disable modification of user_id.
-                'accessibleFields' => ['user_id' => false]
+                'patchableFields' => ['user_id' => false]
             ]);
             if ($this->Articles->save($article)) {
                 $this->Flash->success(__('Your article has been updated.'));

en/tutorials-and-examples/cms/tags-and-users.rst

@@ -336,7 +336,7 @@ can add a virtual/computed field to the entity. In
     use Cake\Collection\Collection;
 
     // Update the accessible property to contain `tag_string`
-    protected array $_accessible = [
+    protected array $patchable = [
         //other fields...
         'tag_string' => true
     ];

en/views/helpers/form.rst

@@ -1563,7 +1563,7 @@ to your form's view template file::
     is displayed, the value inside will be empty.
 
 To prevent the ``submittedfile`` from being over-written as blank, remove it
-from ``$_accessible``.  Alternatively, you can unset the index by using
+from ``$patchable``.  Alternatively, you can unset the index by using
 ``beforeMarshal``::
 
     public function beforeMarshal(\Cake\Event\EventInterface $event, \ArrayObject $data, \ArrayObject $options)

es/tutorials-and-examples/blog-auth-example/auth.rst

@@ -157,7 +157,7 @@ archivo de la entidad **src/Model/Entity/User.php** y añade lo siguiente::
     class User extends Entity
     {
         // Make all fields mass assignable except for primary key field "id".
-        protected array $_accessible = [
+        protected array $patchable = [
             '*' => true,
             'id' => false
         ];

es/tutorials-and-examples/cms/database.rst

@@ -208,7 +208,7 @@ archivo completo debería verse así::
 
     class Article extends Entity
     {
-        protected array $_accessible = [
+        protected array $patchable = [
             'title' => true,
             'body' => true,
             'published' => true,
@@ -219,7 +219,7 @@ archivo completo debería verse así::
     }
 
 Nuestra entidad es bastante delgada en este momento, y solo hemos configurado
-la propiedad ``_accessible`` que controla cómo las propiedades pueden ser
+la propiedad ``patchable`` que controla cómo las propiedades pueden ser
 modificadas por `entities-mass-assignment`.
 
 No podemos hacer mucho con nuestros modelos en este momento, así que a continuación