[Mailer] feat(mailer): Add AhaSend Mailer doc

Author: farhadhf

.doctor-rst.yaml

@@ -23,6 +23,8 @@ rules:
     forbidden_directives:
         directives:
             - '.. index::'
+            - directive: '.. caution::'
+              replacements: ['.. warning::', '.. danger::']
     indention: ~
     lowercase_as_in_use_statements: ~
     max_blank_lines:
@@ -46,6 +48,7 @@ rules:
     no_namespace_after_use_statements: ~
     no_php_open_tag_in_code_block_php_directive: ~
     no_space_before_self_xml_closing_tag: ~
+    non_static_phpunit_assertions: ~
     only_backslashes_in_namespace_in_php_code_block: ~
     only_backslashes_in_use_statements_in_php_code_block: ~
     ordered_use_statements: ~
@@ -99,7 +102,6 @@ whitelist:
         - '#. The most important config file is ``app/config/services.yml``, which now is'
         - 'The bin/console Command'
         - '.. _`LDAP injection`: http://projects.webappsec.org/w/page/13246947/LDAP%20Injection'
-        - '.. versionadded:: 2.7.2' # Doctrine
         - '.. versionadded:: 2.8.0' # Doctrine
         - '.. versionadded:: 1.9.0' # Encore
         - '.. versionadded:: 1.18' # Flex in setup/upgrade_minor.rst

.github/workflows/ci.yaml

@@ -73,7 +73,7 @@ jobs:
                     key: ${{ runner.os }}-doctor-rst-${{ steps.extract_base_branch.outputs.branch }}
 
             -   name: "Run DOCtor-RST"
-                uses: docker://oskarstark/doctor-rst:1.62.3
+                uses: docker://oskarstark/doctor-rst:1.64.0
                 with:
                     args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache
 

_build/redirection_map

@@ -525,8 +525,7 @@
 /testing/functional_tests_assertions /testing#testing-application-assertions
 /components https://symfony.com/components
 /components/index https://symfony.com/components
-/serializer/normalizers /components/serializer#normalizers
-/components/serializer#component-serializer-attributes-groups-annotations /components/serializer#component-serializer-attributes-groups-attributes
+/serializer/normalizers /serializer#serializer-built-in-normalizers
 /logging/monolog_regex_based_excludes /logging/monolog_exclude_http_codes
 /security/named_encoders /security/named_hashers
 /components/inflector /string#inflector
@@ -572,3 +571,5 @@
 /doctrine/registration_form /security#security-make-registration-form
 /form/form_dependencies /form/create_custom_field_type
 /doctrine/reverse_engineering /doctrine#doctrine-adding-mapping
+/components/serializer /serializer
+/serializer/custom_encoder /serializer/encoders#serializer-custom-encoder

_images/components/serializer/serializer_workflow.svg renamed to _images/serializer/serializer_workflow.svg

@@ -3,7 +3,7 @@
 The Bundle System
 =================
 
-.. caution::
+.. warning::
 
     In Symfony versions prior to 4.0, it was recommended to organize your own
     application code using bundles. This is :ref:`no longer recommended <best-practice-no-application-bundles>` and bundles
@@ -58,7 +58,7 @@ Start by creating a new class called ``AcmeBlogBundle``::
     {
     }
 
-.. caution::
+.. warning::
 
     If your bundle must be compatible with previous Symfony versions you have to
     extend from the :class:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle` instead.
@@ -118,7 +118,7 @@ to be adjusted if needed:
 
 .. _bundles-legacy-directory-structure:
 
-.. caution::
+.. warning::
 
     The recommended bundle structure was changed in Symfony 5, read the
     `Symfony 4.4 bundle documentation`_ for information about the old

_images/sources/components/serializer/serializer_workflow.dia renamed to _images/sources/serializer/serializer_workflow.dia

@@ -246,7 +246,7 @@ with Symfony Flex to install a specific Symfony version:
     # recommended to have a better output and faster download time)
     composer update --prefer-dist --no-progress
 
-.. caution::
+.. warning::
 
     If you want to cache your Composer dependencies, **do not** cache the
     ``vendor/`` directory as this has side-effects. Instead cache

bundles.rst

@@ -200,7 +200,7 @@ Patterns are transformed into the actual class namespaces using the classmap
 generated by Composer. Therefore, before using these patterns, you must generate
 the full classmap executing the ``dump-autoload`` command of Composer.
 
-.. caution::
+.. warning::
 
     This technique can't be used when the classes to compile use the ``__DIR__``
     or ``__FILE__`` constants, because their values will change when loading

bundles/best_practices.rst

@@ -19,7 +19,7 @@ For example, to override the ``templates/registration/confirmed.html.twig``
 template from the AcmeUserBundle, create this template:
 ``<your-project>/templates/bundles/AcmeUserBundle/registration/confirmed.html.twig``
 
-.. caution::
+.. warning::
 
     If you add a template in a new location, you *may* need to clear your
     cache (``php bin/console cache:clear``), even if you are in debug mode.

bundles/extension.rst

@@ -829,7 +829,7 @@ Then, register the ``SodiumMarshaller`` service using this key:
             //->addArgument(['env(base64:CACHE_DECRYPTION_KEY)', 'env(base64:OLD_CACHE_DECRYPTION_KEY)'])
             ->addArgument(new Reference('.inner'));
 
-.. caution::
+.. danger::
 
     This will encrypt the values of the cache items, but not the cache keys. Be
     careful not to leak sensitive data in the keys.

bundles/override.rst

@@ -5,7 +5,7 @@ This adapter is a high-performance, shared memory cache. It can *significantly*
 increase an application's performance, as its cache contents are stored in shared
 memory, a component appreciably faster than many others, such as the filesystem.
 
-.. caution::
+.. warning::
 
     **Requirement:** The `APCu extension`_ must be installed and active to use
     this adapter.
@@ -30,7 +30,7 @@ and cache items version string as constructor arguments::
         $version = null
     );
 
-.. caution::
+.. warning::
 
     Use of this adapter is discouraged in write/delete heavy workloads, as these
     operations cause memory fragmentation that results in significantly degraded performance.

cache.rst

@@ -14,7 +14,7 @@ shared memory; you can store contents independent of your PHP environment.
 The ability to utilize a cluster of servers to provide redundancy and/or fail-over
 is also available.
 
-.. caution::
+.. warning::
 
     **Requirements:** The `Couchbase PHP extension`_ as well as a `Couchbase server`_
     must be installed, active, and running to use this adapter. Version ``2.6`` or

components/cache/adapters/apcu_adapter.rst

@@ -8,7 +8,7 @@ shared memory; you can store contents independent of your PHP environment.
 The ability to utilize a cluster of servers to provide redundancy and/or fail-over
 is also available.
 
-.. caution::
+.. warning::
 
     **Requirements:** The `Couchbase PHP extension`_ as well as a `Couchbase server`_
     must be installed, active, and running to use this adapter. Version ``3.0`` or

components/cache/adapters/couchbasebucket_adapter.rst

@@ -33,7 +33,7 @@ and cache root path as constructor parameters::
         $directory = null
     );
 
-.. caution::
+.. warning::
 
     The overhead of filesystem IO often makes this adapter one of the *slower*
     choices. If throughput is paramount, the in-memory adapters

components/cache/adapters/couchbasecollection_adapter.rst

@@ -8,7 +8,7 @@ shared memory; you can store contents independent of your PHP environment.
 The ability to utilize a cluster of servers to provide redundancy and/or fail-over
 is also available.
 
-.. caution::
+.. warning::
 
     **Requirements:** The `Memcached PHP extension`_ as well as a `Memcached server`_
     must be installed, active, and running to use this adapter. Version ``2.2`` or
@@ -256,7 +256,7 @@ Available Options
     executed in a "fire-and-forget" manner; no attempt to ensure the operation
     has been received or acted on will be made once the client has executed it.
 
-    .. caution::
+    .. warning::
 
         Not all library operations are tested in this mode. Mixed TCP and UDP
         servers are not allowed.

components/cache/adapters/filesystem_adapter.rst

@@ -28,7 +28,7 @@ file similar to the following::
     handles file includes, this adapter has the potential to be much faster than other
     filesystem-based caches.
 
-.. caution::
+.. warning::
 
     While it supports updates and because it is using OPcache as a backend, this adapter is
     better suited for append-mostly needs. Using it in other scenarios might lead to

components/cache/adapters/memcached_adapter.rst

@@ -15,7 +15,7 @@ Unlike the :doc:`APCu adapter </components/cache/adapters/apcu_adapter>`, and si
 shared memory; you can store contents independent of your PHP environment. The ability
 to utilize a cluster of servers to provide redundancy and/or fail-over is also available.
 
-.. caution::
+.. warning::
 
     **Requirements:** At least one `Redis server`_ must be installed and running to use this
     adapter. Additionally, this adapter requires a compatible extension or library that implements
@@ -38,7 +38,13 @@ as the second and third parameters::
         // the default lifetime (in seconds) for cache items that do not define their
         // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
         // until RedisAdapter::clear() is invoked or the server(s) are purged)
-        $defaultLifetime = 0
+        $defaultLifetime = 0,
+
+        // $marshaller (optional) An instance of MarshallerInterface to control the serialization
+        // and deserialization of cache items. By default, native PHP serialization is used.
+        // This can be useful for compressing data, applying custom serialization logic, or
+        // optimizing the size and performance of cached items
+        ?MarshallerInterface $marshaller = null
     );
 
 Configure the Connection
@@ -266,6 +272,80 @@ performance when using tag-based invalidation::
 
 Read more about this topic in the official `Redis LRU Cache Documentation`_.
 
+Working with Marshaller
+-----------------------
+
+TagAwareMarshaller for Tag-Based Caching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Optimizes caching for tag-based retrieval, allowing efficient management of related items::
+
+    $marshaller = new TagAwareMarshaller();
+
+    $cache = new RedisAdapter($redis, 'tagged_namespace', 3600, $marshaller);
+
+    $item = $cache->getItem('tagged_key');
+    $item->set(['value' => 'some_data', 'tags' => ['tag1', 'tag2']]);
+    $cache->save($item);
+
+SodiumMarshaller for Encrypted Caching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Encrypts cached data using Sodium for enhanced security::
+
+    $encryptionKeys = [sodium_crypto_box_keypair()];
+    $marshaller = new SodiumMarshaller($encryptionKeys);
+
+    $cache = new RedisAdapter($redis, 'secure_namespace', 3600, $marshaller);
+
+    $item = $cache->getItem('secure_key');
+    $item->set('confidential_data');
+    $cache->save($item);
+
+DefaultMarshaller with igbinary Serialization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Uses ``igbinary` for faster and more efficient serialization when available::
+
+    $marshaller = new DefaultMarshaller(true);
+
+    $cache = new RedisAdapter($redis, 'optimized_namespace', 3600, $marshaller);
+
+    $item = $cache->getItem('optimized_key');
+    $item->set(['data' => 'optimized_data']);
+    $cache->save($item);
+
+DefaultMarshaller with Exception on Failure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Throws an exception if serialization fails, facilitating error handling::
+
+    $marshaller = new DefaultMarshaller(false, true);
+
+    $cache = new RedisAdapter($redis, 'error_namespace', 3600, $marshaller);
+
+    try {
+        $item = $cache->getItem('error_key');
+        $item->set('data');
+        $cache->save($item);
+    } catch (\ValueError $e) {
+        echo 'Serialization failed: '.$e->getMessage();
+    }
+
+SodiumMarshaller with Key Rotation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Supports key rotation, ensuring secure decryption with both old and new keys::
+
+    $keys = [sodium_crypto_box_keypair(), sodium_crypto_box_keypair()];
+    $marshaller = new SodiumMarshaller($keys);
+
+    $cache = new RedisAdapter($redis, 'rotated_namespace', 3600, $marshaller);
+
+    $item = $cache->getItem('rotated_key');
+    $item->set('data_to_encrypt');
+    $cache->save($item);
+
 .. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name
 .. _`Redis server`: https://redis.io/
 .. _`Redis`: https://github.com/phpredis/phpredis

components/cache/adapters/php_files_adapter.rst

@@ -129,18 +129,18 @@ is expired or not, by modifying the clock's time::
             $validUntil = new DateTimeImmutable('2022-11-16 15:25:00');
 
             // $validUntil is in the future, so it is not expired
-            static::assertFalse($expirationChecker->isExpired($validUntil));
+            $this->assertFalse($expirationChecker->isExpired($validUntil));
 
             // Clock sleeps for 10 minutes, so now is '2022-11-16 15:30:00'
             $clock->sleep(600); // Instantly changes time as if we waited for 10 minutes (600 seconds)
 
             // modify the clock, accepts all formats supported by DateTimeImmutable::modify()
-            static::assertTrue($expirationChecker->isExpired($validUntil));
+            $this->assertTrue($expirationChecker->isExpired($validUntil));
 
             $clock->modify('2022-11-16 15:00:00');
 
             // $validUntil is in the future again, so it is no longer expired
-            static::assertFalse($expirationChecker->isExpired($validUntil));
+            $this->assertFalse($expirationChecker->isExpired($validUntil));
         }
     }
 

components/cache/adapters/redis_adapter.rst

@@ -83,9 +83,19 @@ reflect the real structure of the configuration values::
             ->scalarNode('default_connection')
                 ->defaultValue('mysql')
             ->end()
+            ->stringNode('username')
+                ->defaultValue('root')
+            ->end()
+            ->stringNode('password')
+                ->defaultValue('root')
+            ->end()
         ->end()
     ;
 
+.. versionadded:: 7.2
+
+    The ``stringNode()`` method was introduced in Symfony 7.2.
+
 The root node itself is an array node, and has children, like the boolean
 node ``auto_connect`` and the scalar node ``default_connection``. In general:
 after defining a node, a call to ``end()`` takes you one step up in the
@@ -100,6 +110,7 @@ node definition. Node types are available for:
 * scalar (generic type that includes booleans, strings, integers, floats
   and ``null``)
 * boolean
+* string
 * integer
 * float
 * enum (similar to scalar, but it only allows a finite set of values)
@@ -109,6 +120,10 @@ node definition. Node types are available for:
 and are created with ``node($name, $type)`` or their associated shortcut
 ``xxxxNode($name)`` method.
 
+.. versionadded:: 7.2
+
+    Support for the ``string`` type was introduced in Symfony 7.2.
+
 Numeric Node Constraints
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -670,7 +685,7 @@ The separator used in keys is typically ``_`` in YAML and ``-`` in XML.
 For example, ``auto_connect`` in YAML and ``auto-connect`` in XML. The
 normalization would make both of these ``auto_connect``.
 
-.. caution::
+.. warning::
 
     The target key will not be altered if it's mixed like
     ``foo-bar_moo`` or if it already exists.
@@ -800,6 +815,7 @@ A validation rule always has an "if" part. You can specify this part in
 the following ways:
 
 - ``ifTrue()``
+- ``ifFalse()``
 - ``ifString()``
 - ``ifNull()``
 - ``ifEmpty()``
@@ -818,6 +834,10 @@ A validation rule also requires a "then" part:
 Usually, "then" is a closure. Its return value will be used as a new value
 for the node, instead of the node's original value.
 
+.. versionadded:: 7.3
+
+    The ``ifFalse()`` method was introduced in Symfony 7.3.
+
 Configuring the Node Path Separator
 -----------------------------------
 
@@ -889,7 +909,7 @@ Otherwise the result is a clean array of configuration values::
         $configs
     );
 
-.. caution::
+.. warning::
 
     When processing the configuration tree, the processor assumes that the top
     level array key (which matches the extension name) is already stripped off.

components/clock.rst

@@ -52,7 +52,7 @@ This will print the following to the command line:
 
     Hello World
 
-.. caution::
+.. warning::
 
     This feature has a limitation: you cannot pass any argument or option to
     the default command because they are ignored.