updating docs for 5.11

Author: niden

docs/controllers.md

@@ -310,7 +310,26 @@ class InvoicesController extends Controller
 The above parameters will match the route the way it was defined.
 
 ## Events
-Controllers automatically act as listeners for [dispatcher][dispatcher] [events][events], implementing methods with those event names allowing you to implement hook points before/after the actions are executed:
+Controllers automatically act as listeners for [dispatcher][dispatcher] [events][events], implementing methods with those event names allowing you to implement hook points before/after the actions are executed.
+
+Controllers also implement `Phalcon\Events\EventsAwareInterface`, which means you can attach an events manager directly to any controller instance using `setEventsManager()` and retrieve it with `getEventsManager()`:
+
+```php
+<?php
+
+use Phalcon\Events\Manager;
+use Phalcon\Mvc\Controller;
+
+$controller = new InvoicesController();
+
+$eventsManager = new Manager();
+$eventsManager->attach('controller', function ($event, $controller) {
+    // custom listener logic
+});
+
+$controller->setEventsManager($eventsManager);
+```
+
 
 ```php
 <?php

docs/db-models.md

@@ -2332,6 +2332,24 @@ Phalcon's resultsets emulate scrollable cursors. You can get any row just by acc
 
 Storing large query results in memory will consume many resources. You can however instruct Phalcon to fetch data in chunks of rows, thus reducing the need to re-execute the request in many cases. You can achieve that by setting the `orm.resultset_prefetch_records` setup value. This can be done either in `php.ini` or in the model `setup()`. More information about this can be found in the [features](#model-features) section.
 
+You can re-execute the underlying query at any time to update the resultset with fresh data from the database by calling `refresh()`. This is useful in long-running scripts or when you suspect the data may have changed since the resultset was last loaded.
+
+```php
+<?php
+
+use MyApp\Models\Invoices;
+
+$invoices = Invoices::find(['conditions' => 'inv_status = "new"']);
+
+echo count($invoices); // current count
+
+// ... time passes, other processes may have inserted rows ...
+
+$invoices->refresh();
+
+echo count($invoices); // updated count
+```
+
 Note that resultsets can be serialized and stored in a cache backend. [Phalcon\Cache\Cache][cache] can help with that task. However, serializing data causes [Phalcon\Mvc\Model][mvc-model] to retrieve all the data from the database in an array, thus consuming more memory while this process takes place.
 
 ```php
@@ -3820,7 +3838,7 @@ class Invoices extends Model
 ```
 
 ## Model Features
-The ORM has several options that control specific behaviors globally. You can enable or disable these features by adding specific lines to your `php.ini` file or using the `setup` static method on the model. You can enable or disable these features temporarily in your code or permanently.
+The ORM has several options that control specific behaviors globally. You can enable or disable these features by adding specific lines to your `php.ini` file, using the `setup` static method on the model, or using `Phalcon\Support\Settings` for a PHP-level override that does not call `ini_set()`.
 
 ```ini
 phalcon.orm.column_renaming = false
@@ -3890,6 +3908,28 @@ The available options are:
 ; phalcon.db.force_casting = Off
 ```
 
+**Using `Phalcon\Support\Settings`**
+
+`Phalcon\Support\Settings` provides PHP-level overrides for all framework settings. Unlike `ini_set()`, changes made with `Settings::set()` are stored in a static array and never modify the underlying `php.ini` configuration, which prevents settings from one project from leaking into another sharing the same PHP process.
+
+```php
+<?php
+
+use Phalcon\Support\Settings;
+
+// Override a setting at the PHP level
+Settings::set('orm.column_renaming', false);
+Settings::set('orm.events', false);
+
+// Read the effective value (PHP override → php.ini → compiled default)
+var_dump(Settings::get('orm.events')); // bool(false)
+
+// Clear all PHP-level overrides and revert to php.ini / compiled defaults
+Settings::reset();
+```
+
+The `get()` method follows this resolution order: PHP-level override → `ini_get('phalcon.<key>')` → compiled-in default.
+
 !!! warning "WARNING"
 
     `Phalcon\Mvc\Model::assign()` (which is used also when creating/updating/saving model) is always using setters if they exist when data arguments are passed, even when it's required or necessary. This will add some additional overhead to your application. You can change this behavior by adding `phalcon.orm.disable_assign_setters = 1` to your ini file, it will just simply use `$this->property = value`.

docs/encryption-security.md

@@ -478,6 +478,96 @@ $random = new Random();
 echo $random->uuid(); // 1378c906-64bb-4f81-a8d6-4ae1bfcdec22
 ```
 
+## UUID
+[Phalcon\Encryption\Security\Uuid][security-uuid] is a factory that generates UUIDs (Universally Unique Identifiers) for versions 1 through 7 as defined by [RFC 4122][rfc-4122] and [RFC 9562][rfc-9562]. Each version adapter is instantiated once and cached for reuse.
+
+### Namespace Constants
+[Phalcon\Encryption\Security\Uuid\UuidInterface][security-uuid-interface] defines the four standard RFC 4122 namespace UUIDs as constants:
+
+| Constant          | Value                                  | Use                         |
+|-------------------|----------------------------------------|-----------------------------|
+| `NAMESPACE_DNS`   | `6ba7b810-9dad-11d1-80b4-00c04fd430c8` | DNS names                   |
+| `NAMESPACE_URL`   | `6ba7b811-9dad-11d1-80b4-00c04fd430c8` | URLs                        |
+| `NAMESPACE_OID`   | `6ba7b812-9dad-11d1-80b4-00c04fd430c8` | ISO OIDs                    |
+| `NAMESPACE_X500`  | `6ba7b814-9dad-11d1-80b4-00c04fd430c8` | X.500 distinguished names   |
+
+### Methods
+
+```php
+public function v1(): string
+```
+Generates a version 1 (time-based) UUID using a 60-bit UUID timestamp and a random node/clock-sequence.
+
+```php
+public function v3(string $namespaceName, string $name): string
+```
+Generates a version 3 (name-based MD5) UUID. The same namespace + name pair always produces the same UUID.
+
+```php
+public function v4(): string
+```
+Generates a version 4 (random) UUID.
+
+```php
+public function v5(string $namespaceName, string $name): string
+```
+Generates a version 5 (name-based SHA-1) UUID. The same namespace + name pair always produces the same UUID.
+
+```php
+public function v6(): string
+```
+Generates a version 6 (reordered time-based) UUID. Fields are reordered so that UUIDs sort lexicographically in chronological order.
+
+```php
+public function v7(): string
+```
+Generates a version 7 (Unix timestamp + random) UUID per RFC 9562. Monotonically increasing within the same millisecond window.
+
+### Examples
+
+```php
+<?php
+
+use Phalcon\Encryption\Security\Uuid;
+use Phalcon\Encryption\Security\Uuid\UuidInterface;
+
+$uuid = new Uuid();
+
+// Version 1 - time-based
+echo $uuid->v1(); // e.g. 6ba7b810-9dad-11d1-80b4-00c04fd430c8
+
+// Version 3 - name-based MD5 (deterministic)
+echo $uuid->v3(UuidInterface::NAMESPACE_DNS, 'phalcon.io');
+// always: aeb94720-3f71-35d3-9b9c-c0c7a6f55e1c
+
+// Version 4 - random
+echo $uuid->v4(); // e.g. f47ac10b-58cc-4372-a567-0e02b2c3d479
+
+// Version 5 - name-based SHA-1 (deterministic)
+echo $uuid->v5(UuidInterface::NAMESPACE_URL, 'https://phalcon.io');
+// always produces the same UUID for the same input
+
+// Version 6 - reordered time-based (lexicographically sortable)
+echo $uuid->v6();
+
+// Version 7 - Unix ms timestamp + random (lexicographically sortable)
+echo $uuid->v7();
+```
+
+Because each adapter is instantiated lazily and cached, repeated calls to the same `v*()` method reuse the same adapter instance.
+
+```php
+<?php
+
+use Phalcon\Encryption\Security\Uuid;
+
+$uuid = new Uuid();
+
+// The v4 adapter is created once and reused
+$id1 = $uuid->v4();
+$id2 = $uuid->v4();
+```
+
 ## Dependency Injection
 If you use the [Phalcon\Di\FactoryDefault][factorydefault] container, the [Phalcon\Encryption\Security][security] is already registered for you. However, you might want to override the default registration in order to set your own `workFactor()`. Alternatively, if you are not using the [Phalcon\Di\FactoryDefault][factorydefault] and instead are using the [Phalcon\Di\Di][di] the registration is the same. By doing so, you will be able to access your configuration object from controllers, models, views, and any component that implements `Injectable`.
 
@@ -547,10 +637,13 @@ Also in your views (Volt syntax)
 [rainbow-tables]: https://en.wikipedia.org/wiki/Rainbow_table
 [rfc-3548]: https://www.ietf.org/rfc/rfc3548.txt
 [rfc-4122]: https://www.ietf.org/rfc/rfc4122.txt
+[rfc-9562]: https://www.rfc-editor.org/rfc/rfc9562
 [secure-random]: https://ruby-doc.org/stdlib-2.2.2/libdoc/securerandom/rdoc/SecureRandom.html
 [security]: api/phalcon_encryption.md#encryptionsecurity
 [security-exception]: api/phalcon_encryption.md#encryptionsecurityexception
 [security-random]: api/phalcon_encryption.md#encryptionsecurityrandom
+[security-uuid]: api/phalcon_encryption.md#encryptionsecurityuuid
+[security-uuid-interface]: api/phalcon_encryption.md#encryptionsecurityuuiduuidinterface
 [sha1]: https://php.net/manual/en/function.sha1.php
 [wiki-csrf]: https://en.wikipedia.org/wiki/Cross-site_request_forgery
 [di]: di.md

docs/filter-validation.md

@@ -80,10 +80,11 @@ Appends a message to the messages list
 ```php
 public function bind(
     object $entity, 
-    array | object $$data
+    array | object $data,
+    array $whitelist = []
 ): ValidationInterface
 ```
-Assigns the data to an entity. The entity is used to obtain the validation values
+Assigns the data to an entity. The entity is used to obtain the validation values. When `$whitelist` is supplied, only the fields listed in it will be assigned to the entity; all other fields are skipped.
 
 ```php
 public function getEntity(): object
@@ -173,16 +174,35 @@ Adds labels for fields
 ```php
 public function validate(
     array | object $data = null, 
-    object $entity = null
+    object $entity = null,
+    array $whitelist = []
 ): Messages
 ```
-Validate a set of data according to a set of rules
+Validate a set of data according to a set of rules. When `$whitelist` is supplied, only the listed fields are bound to `$entity`; validation itself still runs over all configured fields.
 
 ```php
 public function fails(): bool
 ```
 Verify if the validation has failed or not. Returns `true` when validation fails, `false` when validation succeeds.
 
+```php
+<?php
+
+use Phalcon\Filter\Validation;
+use Phalcon\Filter\Validation\Validator\PresenceOf;
+
+$validation = new Validation();
+$validation->add('name', new PresenceOf(['message' => 'Name is required']));
+
+$validation->validate(['name' => '']);
+
+if ($validation->fails()) {
+    foreach ($validation->getMessages() as $message) {
+        echo $message, PHP_EOL;
+    }
+}
+```
+
 ## Activation
 Validation chains can be initialized in a direct manner by just adding validators to the [Phalcon\Filter\Validation][validation] object. You can put your validations in a separate file for better code reuse and organization.
 
@@ -1876,6 +1896,31 @@ if (count($messages)) {
 }
 ```
 
+## Whitelist
+When validating data that will be applied to an entity (e.g. a model), you can restrict which fields are assigned to the entity by passing a `$whitelist` array. Only the fields listed in the whitelist will be bound; all other incoming fields are ignored. Validators still run over all configured fields regardless of the whitelist.
+
+```php
+<?php
+
+use Phalcon\Filter\Validation;
+use Phalcon\Filter\Validation\Validator\PresenceOf;
+
+$validation = new Validation();
+
+$validation->add('name',  new PresenceOf(['message' => 'Name is required']));
+$validation->add('email', new PresenceOf(['message' => 'Email is required']));
+$validation->add('role',  new PresenceOf(['message' => 'Role is required']));
+
+$entity = new stdClass();
+
+// Only 'name' and 'email' are assigned to $entity even though 'role' is in the data
+$messages = $validation->validate(
+    ['name' => 'Phalcon', 'email' => 'team@phalcon.io', 'role' => 'admin'],
+    $entity,
+    ['name', 'email']
+);
+```
+
 ## Filtering of Data
 Data can be filtered prior to the validation ensuring that malicious or incorrect data is not validated.