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 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..74c55a8f0f 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 generate``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 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 24c46a1f14..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 having 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. @@ -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: