Add PHP 8 type hints to event and validation callback examples (#8208)

* Add PHP 8 type hints to event listener and validation callback examples.

Add EventInterface parameter types and void return types to event
listener callbacks in the Events System documentation. Add typed
parameters (mixed $value, array $context) and return types to
validation callback examples.

* Fix broken BelongsToMany through example in associations docs.

Fix invalid valueField 'studentFirstName' to 'first_name' matching
actual database column conventions. Fix indentation of find()
arguments. Add context comment clarifying where the code runs.

Author: dereuromark

docs/en/core-libraries/events.md

@@ -165,9 +165,10 @@ response has been sent, such as logging or sending emails.
 You can listen to this event using an event manager instance:
 
 ``` php
+use Cake\Event\EventInterface;
 use Cake\Event\EventManager;
 
-EventManager::instance()->on('Server.terminate', function ($event) {
+EventManager::instance()->on('Server.terminate', function (EventInterface $event) {
     // Perform tasks that should be done after the response has been
     // sent to the client.
 });
@@ -176,11 +177,12 @@ EventManager::instance()->on('Server.terminate', function ($event) {
 Or using the `events` hook in your Application/Plugin class:
 
 ``` php
+use Cake\Event\EventInterface;
 use Cake\Event\EventManagerInterface;
 
 public function events(EventManagerInterface $eventManager): EventManagerInterface
 {
-    $eventManager->on('Server.terminate', function ($event) {
+    $eventManager->on('Server.terminate', function (EventInterface $event) {
         // Perform tasks that should be done after the response has been
         // sent to the client.
     });
@@ -209,14 +211,15 @@ and the `afterExecute` event also contains the `exitCode` which is returned by t
 You can listen to this event using an event manager instance:
 
 ``` php
+use Cake\Event\EventInterface;
 use Cake\Event\EventManager;
 
-EventManager::instance()->on('Command.beforeExecute', function ($event, $args) {
+EventManager::instance()->on('Command.beforeExecute', function (EventInterface $event, $args) {
     $command = $event->getSubject();
     // Do stuff here
 });
 
-EventManager::instance()->on('Command.afterExecute', function ($event, $args, $result) {
+EventManager::instance()->on('Command.afterExecute', function (EventInterface $event, $args, $result) {
     $command = $event->getSubject();
     // Do stuff here
 });
@@ -225,16 +228,17 @@ EventManager::instance()->on('Command.afterExecute', function ($event, $args, $r
 Or using the `events` hook in your Application/Plugin class:
 
 ``` php
+use Cake\Event\EventInterface;
 use Cake\Event\EventManagerInterface;
 
 public function events(EventManagerInterface $eventManager): EventManagerInterface
 {
-    $eventManager->on('Command.beforeExecute', function ($event, $args) {
+    $eventManager->on('Command.beforeExecute', function (EventInterface $event, $args) {
         $command = $event->getSubject();
         // Do stuff here
     });
 
-    $eventManager->on('Command.afterExecute', function ($event, $args, $result) {
+    $eventManager->on('Command.afterExecute', function (EventInterface $event, $args, $result) {
         $command = $event->getSubject();
         // Do stuff here
     });
@@ -262,6 +266,7 @@ as necessary. Our `UserStatistics` listener might start out like:
 ``` php
 namespace App\Event;
 
+use Cake\Event\EventInterface;
 use Cake\Event\EventListenerInterface;
 
 class UserStatistic implements EventListenerInterface
@@ -275,7 +280,7 @@ class UserStatistic implements EventListenerInterface
         ];
     }
 
-    public function updateBuyStatistic($event)
+    public function updateBuyStatistic(EventInterface $event): void
     {
         // Code to update statistics
     }
@@ -325,10 +330,11 @@ wanted to put any orders into the log files, we could use a simple anonymous
 function to do so:
 
 ``` php
+use Cake\Event\EventInterface;
 use Cake\Log\Log;
 
 // From within a controller, or during application bootstrap.
-$this->Orders->getEventManager()->on('Order.afterPlace', function ($event) {
+$this->Orders->getEventManager()->on('Order.afterPlace', function (EventInterface $event) {
     Log::write(
         'info',
         'A new order was placed with id: ' . $event->getSubject()->id,
@@ -360,12 +366,13 @@ a more direct approach and only listen to the event you really need:
 // You can create the following before the
 // save operation, ie. config/bootstrap.php
 use Cake\Datasource\FactoryLocator;
+use Cake\Event\EventInterface;
 // If sending emails
 use Cake\Mailer\Email;
 
 FactoryLocator::get('Table')->get('ThirdPartyPlugin.Feedbacks')
     ->getEventManager()
-    ->on('Model.afterSave', function($event, $entity)
+    ->on('Model.afterSave', function(EventInterface $event, $entity)
     {
         // For example we can send an email to the admin
         $email = new Email('default');
@@ -533,13 +540,13 @@ In order to stop events you can either return `false` in your callbacks or
 call the `stopPropagation()` method on the event object:
 
 ``` php
-public function doSomething($event)
+public function doSomething(EventInterface $event)
 {
     // ...
     return false; // Stops the event
 }
 
-public function updateBuyStatistic($event)
+public function updateBuyStatistic(EventInterface $event): void
 {
     // ...
     $event->stopPropagation();
@@ -585,7 +592,7 @@ directly or returning the value in the callback itself:
 
 ``` php
 // A listener callback
-public function doSomething($event)
+public function doSomething(EventInterface $event)
 {
     // ...
     $alteredData = $event->getData('order') + $moreData;
@@ -594,7 +601,7 @@ public function doSomething($event)
 }
 
 // Another listener callback
-public function doSomethingElse($event)
+public function doSomethingElse(EventInterface $event): void
 {
     // ...
     $event->setResult(['order' => $alteredData] + $this->result());
@@ -634,7 +641,7 @@ $this->getEventManager()->on('My.event', [$this, 'doSomething']);
 $this->getEventManager()->off('My.event', [$this, 'doSomething']);
 
 // Attaching an anonymous function.
-$myFunction = function ($event) { ... };
+$myFunction = function (EventInterface $event) { ... };
 $this->getEventManager()->on('My.event', $myFunction);
 
 // Detaching the anonymous function

docs/en/core-libraries/validation.md

@@ -175,7 +175,7 @@ $validator->add('title', 'custom', [
 // Use a closure
 $extra = 'Some additional value needed inside the closure';
 $validator->add('title', 'custom', [
-    'rule' => function ($value, $context) use ($extra) {
+    'rule' => function (mixed $value, array $context) use ($extra) {
         // Custom logic that returns true/false
     },
     'message' => 'The title is not valid',
@@ -225,7 +225,7 @@ overwritten by the ones returned from the validation rule method:
 
 ``` php
 $validator->add('length', 'custom', [
-    'rule' => function ($value, $context) {
+    'rule' => function (mixed $value, array $context) {
         if (!$value) {
             return false;
         }
@@ -259,7 +259,7 @@ not a particular rule should be applied:
 ``` php
 $validator->add('picture', 'file', [
     'rule' => ['mimeType', ['image/jpeg', 'image/png']],
-    'on' => function ($context) {
+    'on' => function (array $context): bool {
         return !empty($context['data']['show_profile_picture']);
     }
 ]);
@@ -282,7 +282,7 @@ determines whether or not the rule should be applied. For example, a field is
 sometimes allowed to be empty:
 
 ``` php
-$validator->allowEmptyString('tax', 'This field is required', function ($context) {
+$validator->allowEmptyString('tax', 'This field is required', function (array $context): bool {
     return !$context['data']['is_taxable'];
 });
 ```
@@ -291,7 +291,7 @@ Likewise, a field can be required to be populated when certain conditions are
 met:
 
 ``` php
-$validator->notEmptyString('email_frequency', 'This field is required', function ($context) {
+$validator->notEmptyString('email_frequency', 'This field is required', function (array $context): bool {
     return !empty($context['data']['wants_newsletter']);
 });
 ```
@@ -303,7 +303,7 @@ Further it's also possible to require a field to be present under certain
 conditions only:
 
 ``` php
-$validator->requirePresence('full_name', function ($context) {
+$validator->requirePresence('full_name', function (array $context): bool {
     if (isset($context['data']['action'])) {
         return $context['data']['action'] === 'subscribe';
     }

docs/en/orm/associations.md

@@ -727,10 +727,12 @@ such as a where condition by designating the through table name before the field
 you are filtering on:
 
 ``` php
-$query = $this->find(
-        'list',
-        valueField: 'studentFirstName', order: 'students.id',
-    )
+// In a StudentsTable method or controller action.
+$query = $this->Students->find(
+    'list',
+    valueField: 'first_name',
+    order: 'Students.id',
+)
     ->contain(['Courses'])
     ->matching('Courses')
     ->where(['CoursesMemberships.grade' => 'B']);