diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml index 19e4f9140d3..cf29e3ea3c8 100644 --- a/.doctor-rst.yaml +++ b/.doctor-rst.yaml @@ -28,6 +28,7 @@ rules: ignored_namespaces: - '/^Acme/' - '/^Shared/' + - '/^Symfony/' ignored_paths: - '/^config\//' - '/^example\.com\//' @@ -91,16 +92,16 @@ rules: yaml_instead_of_yml_suffix: ~ versionadded_directive_major_version: - major_version: 7 + major_version: 8 versionadded_directive_min_version: - min_version: '7.0' + min_version: '8.0' deprecated_directive_major_version: - major_version: 7 + major_version: 8 deprecated_directive_min_version: - min_version: '7.0' + min_version: '8.0' exclude_rule_for_file: - path: configuration/multiple_kernels.rst diff --git a/best_practices.rst b/best_practices.rst index 8c797ca42f9..563c90250e5 100644 --- a/best_practices.rst +++ b/best_practices.rst @@ -201,7 +201,7 @@ most services will be configured automatically. However, in some edge cases you'll need to configure services (or parts of them) manually. YAML is the format recommended configuring services because it's friendly to -newcomers and concise, but Symfony also supports XML and PHP configuration. +newcomers and concise, but Symfony also supports PHP configuration. Use Attributes to Define the Doctrine Entity Mapping ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -238,7 +238,7 @@ Use Attributes to Configure Routing, Caching, and Security Using attributes for routing, caching, and security simplifies configuration. You don't need to browse several files created with different -formats (YAML, XML, PHP): all the configuration is just where you require it, +formats (YAML, PHP): all the configuration is just where you require it, and it only uses one format. Use Dependency Injection to Get Services diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index 34bf24308ef..c52035d6446 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -427,21 +427,6 @@ The end user can provide values in any configuration file: parameters: acme_blog.author.email: 'fabien@example.com' - .. code-block:: xml - - - - - - fabien@example.com - - - - .. code-block:: php // config/services.php diff --git a/bundles/configuration.rst b/bundles/configuration.rst index dedfada2ea2..a2f1083230c 100644 --- a/bundles/configuration.rst +++ b/bundles/configuration.rst @@ -20,23 +20,6 @@ as integration of other related components: framework: form: true - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -162,23 +145,6 @@ can add some configuration that looks like this: client_id: 123 client_secret: your_secret - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/packages/acme_social.php @@ -228,7 +194,7 @@ First things first, you have to create an extension class as explained in Whenever a user includes the ``acme_social`` key (which is the DI alias) in a configuration file, the configuration under it is added to an array of configurations and passed to the ``load()`` method of your extension (Symfony -automatically converts XML and YAML to an array). +automatically converts the configuration to an array). For the configuration example in the previous section, the array passed to your ``load()`` method will look like this:: @@ -304,7 +270,7 @@ The ``Configuration`` class to handle the sample configuration looks like:: .. seealso:: The ``Configuration`` class can be much more complicated than shown here, - supporting "prototype" nodes, advanced validation, XML-specific normalization + supporting "prototype" nodes, advanced validation, plural/singular normalization and advanced merging. You can read more about this in :doc:`the Config component documentation `. You can also see it in action by checking out some core Configuration @@ -331,24 +297,18 @@ in the ``Configuration`` class to validate, normalize and merge all the configuration arrays together. Now, you can use the ``$config`` variable to modify a service provided by your bundle. -For example, imagine your bundle has the following example config: - -.. code-block:: xml - - - - - - - - - - - +For example, imagine your bundle has the following example config:: + + // src/Resources/config/services.php + namespace Symfony\Component\DependencyInjection\Loader\Configurator; + + use Acme\SocialBundle\TwitterClient; + + return function (ContainerConfigurator $container) { + $container->services() + ->set('acme_social.twitter_client', TwitterClient::class) + ->args([abstract_arg('client_id'), abstract_arg('client_secret')]); + }; In your extension, you can load this and dynamically set its arguments:: @@ -356,12 +316,12 @@ In your extension, you can load this and dynamically set its arguments:: namespace Acme\SocialBundle\DependencyInjection; use Symfony\Component\Config\FileLocator; - use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; + use Symfony\Component\DependencyInjection\Loader\PhpFileLoader; public function load(array $configs, ContainerBuilder $container): void { - $loader = new XmlFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config')); - $loader->load('services.xml'); + $loader = new PhpFileLoader($container, new FileLocator(dirname(__DIR__).'/Resources/config')); + $loader->load('services.php'); $configuration = new Configuration(); $config = $this->processConfiguration($configuration, $configs); @@ -401,7 +361,7 @@ In your extension, you can load this and dynamically set its arguments:: Using the Config component is fully optional. The ``load()`` method gets an array of configuration values. You can instead parse these arrays yourself (e.g. by overriding configurations and using :phpfunction:`isset` to check - for the existence of a value). Be aware that it'll be very hard to support XML:: + for the existence of a value):: public function load(array $configs, ContainerBuilder $container): void { @@ -435,105 +395,6 @@ have something different, your ``Extension`` class must override the :method:`Extension::getConfiguration() ` method and return an instance of your ``Configuration``. -Supporting XML --------------- - -Symfony allows people to provide the configuration in three different formats: -Yaml, XML and PHP. Both Yaml and PHP use the same syntax and are supported by -default when using the Config component. Supporting XML requires you to do some -more things. But when sharing your bundle with others, it is recommended that -you follow these steps. - -Make your Config Tree ready for XML -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Config component provides some methods by default to allow it to correctly -process XML configuration. See ":ref:`component-config-normalization`" of the -component documentation. However, you can do some optional things as well, this -will improve the experience of using XML configuration: - -Choosing an XML Namespace -~~~~~~~~~~~~~~~~~~~~~~~~~ - -In XML, the `XML namespace`_ is used to determine which elements belong to the -configuration of a specific bundle. The namespace is returned from the -:method:`Extension::getNamespace() ` -method. By convention, the namespace is a URL (it doesn't have to be a valid -URL nor does it need to exist). By default, the namespace for a bundle is -``http://example.org/schema/dic/DI_ALIAS``, where ``DI_ALIAS`` is the DI alias of -the extension. You might want to change this to a more professional URL:: - - // src/DependencyInjection/AcmeHelloExtension.php - namespace Acme\HelloBundle\DependencyInjection; - - // ... - class AcmeHelloExtension extends Extension - { - // ... - - public function getNamespace(): string - { - return 'http://acme_company.com/schema/dic/hello'; - } - } - -Providing an XML Schema -~~~~~~~~~~~~~~~~~~~~~~~ - -XML has a very useful feature called `XML schema`_. This allows you to -describe all possible elements and attributes and their values in an XML Schema -Definition (an XSD file). This XSD file is used by IDEs for auto completion and -it is used by the Config component to validate the elements. - -In order to use the schema, the XML configuration file must provide an -``xsi:schemaLocation`` attribute pointing to the XSD file for a certain XML -namespace. This location always starts with the XML namespace. This XML -namespace is then replaced with the XSD validation base path returned from -:method:`Extension::getXsdValidationBasePath() ` -method. This namespace is then followed by the rest of the path from the base -path to the file itself. - -By convention, the XSD file lives in ``config/schema/`` directory, but you -can place it anywhere you like. You should return this path as the base path:: - - // src/DependencyInjection/AcmeHelloExtension.php - namespace Acme\HelloBundle\DependencyInjection; - - // ... - class AcmeHelloExtension extends Extension - { - // ... - - public function getXsdValidationBasePath(): string - { - return __DIR__.'/../config/schema'; - } - } - -Assuming the XSD file is called ``hello-1.0.xsd``, the schema location will be -``https://acme_company.com/schema/dic/hello/hello-1.0.xsd``: - -.. code-block:: xml - - - - - - - - - - - .. _`FrameworkBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php .. _`TwigBundle Configuration`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php -.. _`XML namespace`: https://en.wikipedia.org/wiki/XML_namespace -.. _`XML schema`: https://en.wikipedia.org/wiki/XML_schema .. _`snake case`: https://en.wikipedia.org/wiki/Snake_case diff --git a/bundles/extension.rst b/bundles/extension.rst index d2792efc477..e49831686fe 100644 --- a/bundles/extension.rst +++ b/bundles/extension.rst @@ -33,8 +33,8 @@ method to load service definitions from configuration files:: { public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void { - // load an XML, PHP or YAML file - $container->import('../config/services.xml'); + // load a PHP or YAML file + $container->import('../config/services.php'); // you can also add or replace parameters and services $container->parameters() @@ -143,25 +143,25 @@ container. In the ``load()`` method, you can use PHP code to register service definitions, but it is more common if you put these definitions in a configuration file -(using the YAML, XML or PHP format). +(using the YAML or PHP format). -For instance, assume you have a file called ``services.xml`` in the +For instance, assume you have a file called ``services.php`` in the ``config/`` directory of your bundle, your ``load()`` method looks like:: use Symfony\Component\Config\FileLocator; - use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; + use Symfony\Component\DependencyInjection\Loader\PhpFileLoader; // ... public function load(array $configs, ContainerBuilder $container): void { - $loader = new XmlFileLoader( + $loader = new PhpFileLoader( $container, new FileLocator(__DIR__.'/../../config') ); - $loader->load('services.xml'); + $loader->load('services.php'); } -The other available loaders are ``YamlFileLoader`` and ``PhpFileLoader``. +The other available loader is ``YamlFileLoader``. Using Configuration to Change the Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -169,40 +169,3 @@ Using Configuration to Change the Services The Extension is also the class that handles the configuration for that particular bundle (e.g. the configuration in ``config/packages/.yaml``). To read more about it, see the ":doc:`/bundles/configuration`" article. - -Adding Classes to Compile -------------------------- - -Bundles can hint Symfony about which of their classes contain annotations so -they are compiled when generating the application cache to improve the overall -performance. Define the list of annotated classes to compile in the -``addAnnotatedClassesToCompile()`` method:: - - public function load(array $configs, ContainerBuilder $container): void - { - // ... - - $this->addAnnotatedClassesToCompile([ - // you can define the fully qualified class names... - 'Acme\\BlogBundle\\Controller\\AuthorController', - // ... but glob patterns are also supported: - 'Acme\\BlogBundle\\Form\\**', - - // ... - ]); - } - -.. note:: - - If some class extends from other classes, all its parents are automatically - included in the list of classes to compile. - -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. - -.. 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 - these classes from the ``classes.php`` file. diff --git a/bundles/prepend_extension.rst b/bundles/prepend_extension.rst index 5def05e4a19..377b46be165 100644 --- a/bundles/prepend_extension.rst +++ b/bundles/prepend_extension.rst @@ -108,32 +108,6 @@ registered and the ``entity_manager_name`` setting for ``acme_hello`` is set to # ... use_acme_goodbye: false - .. code-block:: xml - - - - - - - non_default - - - - - - - - .. code-block:: php // config/packages/acme_something.php @@ -181,12 +155,6 @@ method:: The ``prependExtension()`` method, like ``prepend()``, is called only at compile time. -.. versionadded:: 7.1 - - Starting from Symfony 7.1, calling the :method:`Symfony\\Component\\DependencyInjection\\Loader\\Configurator\\ContainerConfigurator::import` - method inside ``prependExtension()`` will prepend the given configuration. - In previous Symfony versions, this method appended the configuration. - Alternatively, you can use the ``prepend`` parameter of the :method:`Symfony\\Component\\DependencyInjection\\Loader\\Configurator\\ContainerConfigurator::extension` method:: @@ -209,12 +177,6 @@ method:: } } -.. versionadded:: 7.1 - - The ``prepend`` parameter of the - :method:`Symfony\\Component\\DependencyInjection\\Loader\\Configurator\\ContainerConfigurator::extension` - method was added in Symfony 7.1. - More than one Bundle using PrependExtensionInterface ---------------------------------------------------- diff --git a/cache.rst b/cache.rst index 9ed49840580..dd649c8e45c 100644 --- a/cache.rst +++ b/cache.rst @@ -61,26 +61,6 @@ adapter (template) they use by using the ``app`` and ``system`` key like: app: cache.adapter.filesystem system: cache.adapter.system - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/packages/cache.php @@ -134,30 +114,6 @@ Some of these adapters could be configured via shortcuts. default_memcached_provider: 'memcached://localhost' default_pdo_provider: 'pgsql:host=localhost' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/cache.php @@ -176,10 +132,6 @@ Some of these adapters could be configured via shortcuts. ; }; -.. versionadded:: 7.1 - - Using a DSN as the provider for the PDO adapter was introduced in Symfony 7.1. - .. _cache-create-pools: Creating Custom (Namespaced) Pools @@ -223,44 +175,6 @@ You can also create more customized pools: adapter: foobar.cache default_lifetime: 60 - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/cache.php @@ -343,39 +257,6 @@ with either :class:`Symfony\\Contracts\\Cache\\CacheInterface` or tags: - { name: 'cache.pool', namespace: 'my_custom_namespace' } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // config/services.php - namespace Symfony\Component\DependencyInjection\Loader\Configurator; - - return function(ContainerConfigurator $container): void { - $container->services() - // ... - - ->set('app.cache.adapter.redis') - ->parent('cache.adapter.redis') - ->tag('cache.pool', ['namespace' => 'my_custom_namespace']) - ; - }; - Custom Provider Options ----------------------- @@ -405,39 +286,6 @@ and use that when configuring the pool. - 'redis://localhost' - { retry_interval: 2, timeout: 10 } - .. code-block:: xml - - - - - - - - - - - - - - redis://localhost - - 2 - 10 - - - - - .. code-block:: php // config/packages/cache.php @@ -497,30 +345,6 @@ Symfony stores the item automatically in all the missing pools. - cache.adapter.apcu - {name: cache.adapter.redis, provider: 'redis://user:password@example.com'} - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/cache.php @@ -593,28 +417,6 @@ to enable this feature. This could be added by using the following configuration adapter: cache.adapter.redis_tag_aware tags: true - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/cache.php @@ -646,29 +448,6 @@ achieved by specifying the adapter. tag_pool: adapter: cache.adapter.apcu - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/cache.php @@ -791,32 +570,6 @@ Then, register the ``SodiumMarshaller`` service using this key: #- ['%env(base64:CACHE_DECRYPTION_KEY)%', '%env(base64:OLD_CACHE_DECRYPTION_KEY)%'] - '@.inner' - .. code-block:: xml - - - - - - - - - - - env(base64:CACHE_DECRYPTION_KEY) - - - - - - - - .. code-block:: php // config/packages/cache.php @@ -923,32 +676,6 @@ a message bus to compute values in a worker: routing: 'Symfony\Component\Cache\Messenger\EarlyExpirationMessage': async_bus - .. code-block:: xml - - - - - - - - - - - %env(MESSENGER_TRANSPORT_DSN)% - - - - - - - .. code-block:: php // config/framework/framework.php diff --git a/components/browser_kit.rst b/components/browser_kit.rst index 42d9d07af1c..e1a8aea0257 100644 --- a/components/browser_kit.rst +++ b/components/browser_kit.rst @@ -335,6 +335,16 @@ history:: // go forward to documentation page $crawler = $client->forward(); + // check if the history position is on the first page + if (!$client->getHistory()->isFirstPage()) { + $crawler = $client->back(); + } + + // check if the history position is on the last page + if (!$client->getHistory()->isLastPage()) { + $crawler = $client->forward(); + } + You can delete the client's history with the ``restart()`` method. This will also delete all the cookies:: diff --git a/components/cache.rst b/components/cache.rst index 44ba8b5c151..80024e6a65d 100644 --- a/components/cache.rst +++ b/components/cache.rst @@ -87,10 +87,6 @@ generate and return the value:: Creating Sub-Namespaces ----------------------- -.. versionadded:: 7.3 - - Cache sub-namespaces were introduced in Symfony 7.3. - Sometimes you need to create context-dependent variations of data that should be cached. For example, the data used to render a dashboard page may be expensive to generate and unique per user, so you can't cache the same data for everyone. @@ -286,12 +282,6 @@ function from the `Igbinary extension`_:: There are other *marshallers* that can encrypt or compress the data before storing it. -.. versionadded:: 7.2 - - In Symfony versions prior to 7.2, the ``igbinary_serialize()`` function was - used by default when the Igbinary extension was installed. Starting from - Symfony 7.2, you have to enable Igbinary support explicitly. - Advanced Usage -------------- diff --git a/components/cache/adapters/array_cache_adapter.rst b/components/cache/adapters/array_cache_adapter.rst index 08f8276db3d..abee5a5486a 100644 --- a/components/cache/adapters/array_cache_adapter.rst +++ b/components/cache/adapters/array_cache_adapter.rst @@ -31,7 +31,3 @@ method:: // lifetimes in tests) $clock = null, ); - -.. versionadded:: 7.2 - - The optional ``$clock`` argument was introduced in Symfony 7.2. diff --git a/components/cache/adapters/couchbasebucket_adapter.rst b/components/cache/adapters/couchbasebucket_adapter.rst deleted file mode 100644 index 29c9e26f83c..00000000000 --- a/components/cache/adapters/couchbasebucket_adapter.rst +++ /dev/null @@ -1,144 +0,0 @@ -Couchbase Bucket Cache Adapter -============================== - -.. deprecated:: 7.1 - - The ``CouchbaseBucketAdapter`` is deprecated since Symfony 7.1, use the - :doc:`CouchbaseCollectionAdapter ` - instead. - -This adapter stores the values in-memory using one (or more) `Couchbase server`_ -instances. Unlike the :doc:`APCu adapter `, and similarly to the -:doc:`Memcached adapter `, it is not limited to the current server's -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. - -.. 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 - less than 3.0 of the `Couchbase PHP extension`_ is required for this adapter. - -This adapter expects a `Couchbase Bucket`_ instance to be passed as the first -parameter. A namespace and default cache lifetime can optionally be passed as -the second and third parameters:: - - use Symfony\Component\Cache\Adapter\CouchbaseBucketAdapter; - - $cache = new CouchbaseBucketAdapter( - // the client object that sets options and adds the server instance(s) - $client, - - // the name of bucket - $bucket, - - // a string prefixed to the keys of the items stored in this cache - $namespace, - - // 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 - $defaultLifetime - ); - -Configure the Connection ------------------------- - -The :method:`Symfony\\Component\\Cache\\Adapter\\CouchbaseBucketAdapter::createConnection` -helper method allows creating and configuring a `Couchbase Bucket`_ class instance using a -`Data Source Name (DSN)`_ or an array of DSNs:: - - use Symfony\Component\Cache\Adapter\CouchbaseBucketAdapter; - - // pass a single DSN string to register a single server with the client - $client = CouchbaseBucketAdapter::createConnection( - 'couchbase://localhost' - // the DSN can include config options (pass them as a query string): - // 'couchbase://localhost:11210?operationTimeout=10' - // 'couchbase://localhost:11210?operationTimeout=10&configTimeout=20' - ); - - // pass an array of DSN strings to register multiple servers with the client - $client = CouchbaseBucketAdapter::createConnection([ - 'couchbase://10.0.0.100', - 'couchbase://10.0.0.101', - 'couchbase://10.0.0.102', - // etc... - ]); - - // a single DSN can define multiple servers using the following syntax: - // host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':' - $client = CouchbaseBucketAdapter::createConnection( - 'couchbase:?host[localhost]&host[localhost:12345]' - ); - -Configure the Options ---------------------- - -The :method:`Symfony\\Component\\Cache\\Adapter\\CouchbaseBucketAdapter::createConnection` -helper method also accepts an array of options as its second argument. The -expected format is an associative array of ``key => value`` pairs representing -option names and their respective values:: - - use Symfony\Component\Cache\Adapter\CouchbaseBucketAdapter; - - $client = CouchbaseBucketAdapter::createConnection( - // a DSN string or an array of DSN strings - [], - - // associative array of configuration options - [ - 'username' => 'xxxxxx', - 'password' => 'yyyyyy', - 'configTimeout' => '100', - ] - ); - -Available Options -~~~~~~~~~~~~~~~~~ - -``username`` (type: ``string``) - Username for connection ``CouchbaseCluster``. - -``password`` (type: ``string``) - Password of connection ``CouchbaseCluster``. - -``operationTimeout`` (type: ``int``, default: ``2500000``) - The operation timeout (in microseconds) is the maximum amount of time the library will - wait for an operation to receive a response before invoking its callback with a failure status. - -``configTimeout`` (type: ``int``, default: ``5000000``) - How long (in microseconds) the client will wait to obtain the initial configuration. - -``configNodeTimeout`` (type: ``int``, default: ``2000000``) - Per-node configuration timeout (in microseconds). - -``viewTimeout`` (type: ``int``, default: ``75000000``) - The I/O timeout (in microseconds) for HTTP requests to Couchbase Views API. - -``httpTimeout`` (type: ``int``, default: ``75000000``) - The I/O timeout (in microseconds) for HTTP queries (management API). - -``configDelay`` (type: ``int``, default: ``10000``) - Config refresh throttling - Modify the amount of time (in microseconds) before the configuration error threshold will forcefully be set to its maximum number forcing a configuration refresh. - -``htconfigIdleTimeout`` (type: ``int``, default: ``4294967295``) - Idling/Persistence for HTTP bootstrap (in microseconds). - -``durabilityInterval`` (type: ``int``, default: ``100000``) - The time (in microseconds) the client will wait between repeated probes to a given server. - -``durabilityTimeout`` (type: ``int``, default: ``5000000``) - The time (in microseconds) the client will spend sending repeated probes to a given key's vBucket masters and replicas before they are deemed not to have satisfied the durability requirements. - -.. tip:: - - Reference the `Couchbase Bucket`_ extension's `predefined constants`_ documentation - for additional information about the available options. - -.. _`Couchbase PHP extension`: https://docs.couchbase.com/sdk-api/couchbase-php-client-2.6.0/files/couchbase.html -.. _`predefined constants`: https://docs.couchbase.com/sdk-api/couchbase-php-client-2.6.0/classes/Couchbase.Bucket.html -.. _`Couchbase server`: https://couchbase.com/ -.. _`Couchbase Bucket`: https://docs.couchbase.com/sdk-api/couchbase-php-client-2.6.0/classes/Couchbase.Bucket.html -.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name diff --git a/components/cache/adapters/redis_adapter.rst b/components/cache/adapters/redis_adapter.rst index a031cbbe992..80c92fc33a9 100644 --- a/components/cache/adapters/redis_adapter.rst +++ b/components/cache/adapters/redis_adapter.rst @@ -48,10 +48,6 @@ as the second and third parameters:: ?MarshallerInterface $marshaller = null ); -.. versionadded:: 7.3 - - Support for ``Relay\Cluster`` was introduced in Symfony 7.3. - Configure the Connection ------------------------ @@ -66,11 +62,6 @@ helper method allows creating and configuring the Redis client class instance us 'redis://localhost' ); -.. versionadded:: 7.3 - - Starting in Symfony 7.3, when using Valkey servers you can use the - ``valkey[s]:`` scheme instead of the ``redis[s]:`` one in your DSNs. - The DSN can specify either an IP/host (and an optional port) or a socket path, as well as a password and a database index. To enable TLS for connections, the scheme ``redis`` must be replaced by ``rediss`` (the second ``s`` means "secure"). @@ -249,15 +240,6 @@ Available Options ], ]; -.. versionadded:: 7.1 - - The option ``sentinel_master`` as an alias for ``redis_sentinel`` was introduced - in Symfony 7.1. - -.. versionadded:: 7.3 - - The ``relay_cluster_context`` option was introduced in Symfony 7.3. - .. note:: When using the `Predis`_ library some additional Predis-specific options are available. diff --git a/components/clock.rst b/components/clock.rst index c4ac88e9092..3f4d6d9d665 100644 --- a/components/clock.rst +++ b/components/clock.rst @@ -240,10 +240,6 @@ timestamps:: // (for high precision sub-second datetimes) are also supported $dateOfFirstMoonLanding = DatePoint::createFromTimestamp(-14182940); -.. versionadded:: 7.1 - - The ``createFromTimestamp()`` method was introduced in Symfony 7.1. - .. note:: In addition ``DatePoint`` offers stricter return types and provides consistent @@ -261,17 +257,21 @@ timestamps:: This feature polyfills PHP 8.4's behavior on the topic, as microseconds manipulation is not available in previous versions of PHP. -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\Clock\\DatePoint::setMicrosecond` and - :method:`Symfony\\Component\\Clock\\DatePoint::getMicrosecond` methods were - introduced in Symfony 7.1. - Storing DatePoints in the Database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you :doc:`use Doctrine ` to work with databases, consider using the -``date_point`` Doctrine type, which converts to/from ``DatePoint`` objects automatically:: +new Doctrine types: + +======================= ====================== ===== +DatePoint Doctrine type Extends Doctrine type Class +======================= ====================== ===== +``date_point`` ``datetime_immutable`` :class:`Symfony\\Bridge\\Doctrine\\Types\\DatePointType` +``day_point`` ``date_immutable`` :class:`Symfony\\Bridge\\Doctrine\\Types\\DayPointType` +``time_point`` ``time_immutable`` :class:`Symfony\\Bridge\\Doctrine\\Types\\TimePointType` +======================= ====================== ===== + +They convert to/from ``DatePoint`` objects automatically:: // src/Entity/Product.php namespace App\Entity; @@ -282,7 +282,7 @@ If you :doc:`use Doctrine ` to work with databases, consider using th #[ORM\Entity] class Product { - // if you don't define the Doctrine type explicitly, Symfony will autodetect it: + // if you don't define the Doctrine type explicitly, Symfony will autodetect 'date_point': #[ORM\Column] private DatePoint $createdAt; @@ -290,12 +290,14 @@ If you :doc:`use Doctrine ` to work with databases, consider using th #[ORM\Column(type: 'date_point')] private DatePoint $updatedAt; - // ... - } + #[ORM\Column(type: 'day_point')] + public DatePoint $birthday; -.. versionadded:: 7.3 + #[ORM\Column(type: 'time_point')] + public DatePoint $openAt; - The ``DatePointType`` was introduced in Symfony 7.3. + // ... + } .. _clock_writing-tests: diff --git a/components/config/caching.rst b/components/config/caching.rst index 80e23a4fdfb..fa6aaad987a 100644 --- a/components/config/caching.rst +++ b/components/config/caching.rst @@ -65,7 +65,3 @@ You can explicitly define the absolute path to the meta file:: // the third optional argument indicates the absolute path to the meta file $userMatcherCache = new ConfigCache($cachePath, true, '/my/absolute/path/to/cache.meta'); - -.. versionadded:: 7.1 - - The argument to customize the meta file path was introduced in Symfony 7.1. diff --git a/components/config/definition.rst b/components/config/definition.rst index 2b1841bc24a..41833d1cb17 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -92,10 +92,6 @@ reflect the real structure of the configuration values:: ->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 @@ -120,10 +116,6 @@ 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 ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -201,10 +193,6 @@ the cases of the enum:: When using a backed enum, the values provided to the node will be cast to one of the enum cases if possible. -.. versionadded:: 7.3 - - The ``enumFqcn()`` method was introduced in Symfony 7.3. - Array Nodes ~~~~~~~~~~~ @@ -281,9 +269,9 @@ Before defining the children of an array node, you can provide options like: A basic prototyped array configuration can be defined as follows:: $node - ->fixXmlConfig('driver') ->children() - ->arrayNode('drivers') + // the arguments are the plural and singular variants of the option name + ->arrayNode('drivers', 'driver') ->scalarPrototype()->end() ->end() ->end() @@ -312,9 +300,8 @@ The processed configuration is:: A more complex example would be to define a prototyped array with children:: $node - ->fixXmlConfig('connection') ->children() - ->arrayNode('connections') + ->arrayNode('connections', 'connection') ->arrayPrototype() ->children() ->scalarNode('table')->end() @@ -385,9 +372,8 @@ the Symfony Config component treats arrays as lists by default. In order to maintain the array keys use the ``useAttributeAsKey()`` method:: $node - ->fixXmlConfig('connection') ->children() - ->arrayNode('connections') + ->arrayNode('connections', 'connection') ->useAttributeAsKey('name') ->arrayPrototype() ->children() @@ -566,10 +552,6 @@ A few placeholders are available to customize the URL: The placeholders will be replaced when printing the configuration tree with the ``config:dump-reference`` command. -.. versionadded:: 7.3 - - The ``docUrl()`` method was introduced in Symfony 7.3. - Optional Sections ----------------- @@ -734,14 +716,14 @@ normalization would make both of these ``auto_connect``. ``foo-bar_moo`` or if it already exists. Another difference between YAML and XML is in the way arrays of values may -be represented. In YAML you may have: +be represented. In YAML you may have an option called ``extensions`` (in plural): .. code-block:: yaml twig: extensions: ['twig.extension.foo', 'twig.extension.bar'] -and in XML: +and in XML you have a list of options called ``extension`` (in singular): .. code-block:: xml @@ -750,33 +732,18 @@ and in XML: twig.extension.bar -This difference can be removed in normalization by pluralizing the key used -in XML. You can specify that you want a key to be pluralized in this way -with ``fixXmlConfig()``:: +This difference can be removed in normalization by defining the singular variant +of the option name using the second argument of the ``arrayNode()`` method:: $rootNode - ->fixXmlConfig('extension') ->children() - ->arrayNode('extensions') + ->arrayNode('extensions', 'extension') ->scalarPrototype()->end() ->end() ->end() ; -If it is an irregular pluralization you can specify the plural to use as -a second argument:: - - $rootNode - ->fixXmlConfig('child', 'children') - ->children() - ->arrayNode('children') - // ... - ->end() - ->end() - ; - -As well as fixing this, ``fixXmlConfig()`` ensures that single XML elements -are still turned into an array. So you may have: +This ensures that single XML elements are still turned into an array. So you may have: .. code-block:: xml @@ -791,7 +758,7 @@ and sometimes only: By default, ``connection`` would be an array in the first case and a string in the second, making it difficult to validate. You can ensure it is always -an array with ``fixXmlConfig()``. +an array with the second argument of ``arrayNode()``. You can further control the normalization process if you need to. For example, you may want to allow a string to be set and used as a particular key or @@ -877,10 +844,6 @@ 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 ----------------------------------- diff --git a/components/console.rst b/components/console.rst index 14817240206..5284d06c588 100644 --- a/components/console.rst +++ b/components/console.rst @@ -43,10 +43,10 @@ First, you need to create a PHP script to define the console application:: $application->run(); Then, you can register the commands using -:method:`Symfony\\Component\\Console\\Application::add`:: +:method:`Symfony\\Component\\Console\\Application::addCommand`:: // ... - $application->add(new GenerateAdminCommand()); + $application->addCommand(new GenerateAdminCommand()); You can also register inline commands and define their behavior thanks to the ``Command::setCode()`` method:: diff --git a/components/console/helpers/cursor.rst b/components/console/helpers/cursor.rst index 63045f178ad..afe0afe30a8 100644 --- a/components/console/helpers/cursor.rst +++ b/components/console/helpers/cursor.rst @@ -22,12 +22,10 @@ of the output: { // ... - public function __invoke(OutputInterface $output): int + public function __invoke(Cursor $cursor, OutputInterface $output): int { // ... - $cursor = new Cursor($output); - // moves the cursor to a specific column (1st argument) and // row (2nd argument) position $cursor->moveToPosition(7, 11); diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index cf9bacdeb9c..fa02cc7234b 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -132,10 +132,6 @@ precision (default ``1``) of the result:: Helper::formatTime(172799, 4); // 1 d, 23 h, 59 min, 59 s Helper::formatTime(172799.056, 5); // 1 d, 23 h, 59 min, 59 s, 56 ms -.. versionadded:: 7.3 - - Support for formatting up to milliseconds was introduced in Symfony 7.3. - Formatting Memory ----------------- diff --git a/components/console/helpers/progressindicator.rst b/components/console/helpers/progressindicator.rst index 0defe7c83fd..da93eb7a056 100644 --- a/components/console/helpers/progressindicator.rst +++ b/components/console/helpers/progressindicator.rst @@ -103,7 +103,7 @@ Once the progress finishes, it displays a special finished indicator (which defa to ✔). You can replace it with your own:: $progressIndicator = new ProgressIndicator($output, finishedIndicatorValue: '🎉'); - + try { /* do something */ $progressIndicator->finish('Finished'); @@ -121,11 +121,6 @@ The progress indicator will now look like this: - Processing... 🎉 Finished -.. versionadded:: 7.2 - - The ``finishedIndicator`` parameter for the constructor was introduced in Symfony 7.2. - The ``finishedIndicator`` parameter for method ``finish()`` was introduced in Symfony 7.2. - Customize Placeholders ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst index a0126ee5a71..acfdf3e518d 100644 --- a/components/console/helpers/questionhelper.rst +++ b/components/console/helpers/questionhelper.rst @@ -324,6 +324,59 @@ the response to a question should allow multiline answers by passing ``true`` to Multiline questions stop reading user input after receiving an end-of-transmission control character (``Ctrl-D`` on Unix systems or ``Ctrl-Z`` on Windows). +Setting a Timeout for User Input +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes, commands can hang if a user takes too long to respond. For example, +if interactive questions are used inside an open database transaction, a delayed +response could leave the transaction open for too long. + +You can prevent this by setting a maximum time limit for input using the +:method:`Symfony\\Component\\Console\\Question\\Question::setTimeout` method. +If the user doesn't respond within the specified timeout, a +:class:`Symfony\\Component\\Console\\Exception\\MissingInputException` will be thrown:: + + use Symfony\Component\Console\Exception\MissingInputException; + use Symfony\Component\Console\Question\Question; + + // ... + public function __invoke(InputInterface $input, OutputInterface $output): int + { + // ... + $helper = new QuestionHelper(); + + $question = new Question('Please enter your answer'); + $question->setTimeout(30); // 30 seconds + + try { + $answer = $helper->ask($input, $output, $question); + // ... do something with the answer + } catch (MissingInputException $exception) { + $output->writeln('No input received within timeout period.'); + // ... handle timeout + } + + return Command::SUCCESS; + } + +.. note:: + + The timeout only applies to interactive input streams. For non-interactive + streams (such as pipes or files), the timeout is ignored and the question + behaves normally. + +You can also use timeouts with other question types such as +:class:`Symfony\\Component\\Console\\Question\\ConfirmationQuestion` and +:class:`Symfony\\Component\\Console\\Question\\ChoiceQuestion`:: + + use Symfony\Component\Console\Question\ConfirmationQuestion; + + // ... + $question = new ConfirmationQuestion('Do you want to continue?', false); + $question->setTimeout(10); // 10 seconds + + $continue = $helper->ask($input, $output, $question); + Hiding the User's Response ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index e36b1570b70..8fd9ba48486 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -290,10 +290,6 @@ This outputs: | 960-425-059-0 | The Lord of the Rings | J. R. R. Tolkien | | 80-902734-1-6 | And Then There Were None | Agatha Christie | -.. versionadded:: 7.3 - - The ``markdown`` style was introduced in Symfony 7.3. - Making a Custom Table Style ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/components/console/helpers/tree.rst b/components/console/helpers/tree.rst index 5e08e684e51..36314bab440 100644 --- a/components/console/helpers/tree.rst +++ b/components/console/helpers/tree.rst @@ -5,10 +5,6 @@ The Tree Helper allows you to build and display tree structures in the console. It's commonly used to render directory hierarchies, but you can also use it to render any tree-like content, such us organizational charts, product category trees, taxonomies, etc. -.. versionadded:: 7.3 - - The ``TreeHelper`` class was introduced in Symfony 7.3. - Rendering a Tree ---------------- diff --git a/components/console/single_command_tool.rst b/components/console/single_command_tool.rst index 9c6b06537e2..d6b99b2c38e 100644 --- a/components/console/single_command_tool.rst +++ b/components/console/single_command_tool.rst @@ -36,7 +36,7 @@ You can still register a command as usual:: $application = new Application('echo', '1.0.0'); $command = new DefaultCommand(); - $application->add($command); + $application->addCommand($command); $application->setDefaultCommand($command->getName(), true); $application->run(); diff --git a/components/console/usage.rst b/components/console/usage.rst index 591994948b8..20ed0e99abc 100644 --- a/components/console/usage.rst +++ b/components/console/usage.rst @@ -72,10 +72,6 @@ You can suppress output with: $ php application.php list --quiet $ php application.php list -q -.. versionadded:: 7.2 - - The ``--silent`` option was introduced in Symfony 7.2. - You can get more verbose messages (if this is supported for a command) with: diff --git a/components/css_selector.rst b/components/css_selector.rst index 1331a11e616..01e264dbbd1 100644 --- a/components/css_selector.rst +++ b/components/css_selector.rst @@ -94,10 +94,6 @@ Pseudo-classes are partially supported: ``li:first-of-type``) but not with the ``*`` selector). * Supported: ``*:only-of-type``, ``*:scope``, ``*:is`` and ``*:where``. -.. versionadded:: 7.1 - - The support for ``*:is`` and ``*:where`` was introduced in Symfony 7.1. - Learn more ---------- diff --git a/components/dependency_injection.rst b/components/dependency_injection.rst index d146f553a0c..3ae645aa289 100644 --- a/components/dependency_injection.rst +++ b/components/dependency_injection.rst @@ -210,22 +210,22 @@ Setting up the Container with Configuration Files ------------------------------------------------- As well as setting up the services using PHP as above you can also use -configuration files. This allows you to use XML or YAML to write the definitions +configuration files. This allows you to use YAML or PHP to write the definitions for the services rather than using PHP to define the services as in the above examples. In anything but the smallest applications it makes sense to organize the service definitions by moving them into one or more configuration files. To do this you also need to install :doc:`the Config component `. -Loading an XML config file:: +Loading a PHP config file:: use Symfony\Component\Config\FileLocator; use Symfony\Component\DependencyInjection\ContainerBuilder; - use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; + use Symfony\Component\DependencyInjection\Loader\PhpFileLoader; $container = new ContainerBuilder(); - $loader = new XmlFileLoader($container, new FileLocator(__DIR__)); - $loader->load('services.xml'); + $loader = new PhpFileLoader($container, new FileLocator(__DIR__)); + $loader->load('services.php'); Loading a YAML config file:: @@ -242,15 +242,6 @@ Loading a YAML config file:: If you want to load YAML config files then you will also need to install :doc:`the Yaml component `. -.. tip:: - - If your application uses unconventional file extensions (for example, your - XML files have a ``.config`` extension) you can pass the file type as the - second optional parameter of the ``load()`` method:: - - // ... - $loader->load('services.config', 'xml'); - If you *do* want to use PHP to create the services then you can move this into a separate config file and load it in a similar way:: @@ -282,32 +273,6 @@ config files: calls: - [setMailer, ['@mailer']] - .. code-block:: xml - - - - - - sendmail - - - - - %mailer.transport% - - - - - - - - - - .. code-block:: php namespace Symfony\Component\DependencyInjection\Loader\Configurator; diff --git a/components/dependency_injection/_imports-parameters-note.rst.inc b/components/dependency_injection/_imports-parameters-note.rst.inc index 1389ca78fe3..41b523afddd 100644 --- a/components/dependency_injection/_imports-parameters-note.rst.inc +++ b/components/dependency_injection/_imports-parameters-note.rst.inc @@ -12,20 +12,6 @@ imports: - { resource: '%kernel.project_dir%/somefile.yaml' } - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/services.php diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst index c79281b5c27..763d409ab54 100644 --- a/components/dependency_injection/compilation.rst +++ b/components/dependency_injection/compilation.rst @@ -57,17 +57,17 @@ A very simple extension may just load configuration files into the container:: use Symfony\Component\Config\FileLocator; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Extension\ExtensionInterface; - use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; + use Symfony\Component\DependencyInjection\Loader\PhpFileLoader; class AcmeDemoExtension implements ExtensionInterface { public function load(array $configs, ContainerBuilder $container): void { - $loader = new XmlFileLoader( + $loader = new PhpFileLoader( $container, new FileLocator(__DIR__.'/../Resources/config') ); - $loader->load('services.xml'); + $loader->load('services.php'); } // ... @@ -170,45 +170,6 @@ you could access the config value this way:: // ... } -There are a further two methods you must implement. One to return the XML -namespace so that the relevant parts of an XML config file are passed to -the extension. The other to specify the base path to XSD files to validate -the XML configuration:: - - public function getXsdValidationBasePath(): string - { - return __DIR__.'/../Resources/config/'; - } - - public function getNamespace(): string - { - return 'http://www.example.com/symfony/schema/'; - } - -.. note:: - - XSD validation is optional, returning ``false`` from the ``getXsdValidationBasePath()`` - method will disable it. - -The XML version of the config would then look like this: - -.. code-block:: xml - - - - - fooValue - barValue - - - .. note:: In the Symfony full-stack Framework there is a base Extension class @@ -240,14 +201,14 @@ file but also load a secondary one only if a certain parameter is set:: $processor = new Processor(); $config = $processor->processConfiguration($configuration, $configs); - $loader = new XmlFileLoader( + $loader = new PhpFileLoader( $container, new FileLocator(__DIR__.'/../Resources/config') ); - $loader->load('services.xml'); + $loader->load('services.php'); if ($config['advanced']) { - $loader->load('advanced.xml'); + $loader->load('advanced.php'); } } @@ -256,7 +217,7 @@ about not using them anymore. This helps with the migration across major version of an extension. Deprecation is only possible when using PHP to configure the extension, not when -using XML or YAML. Use the ``ContainerBuilder::deprecateParameter()`` method to +using YAML. Use the ``ContainerBuilder::deprecateParameter()`` method to provide the deprecation details:: public function load(array $configs, ContainerBuilder $containerBuilder) diff --git a/components/expression_language.rst b/components/expression_language.rst index b0dd10b0f42..41a9675f5c7 100644 --- a/components/expression_language.rst +++ b/components/expression_language.rst @@ -128,11 +128,6 @@ This is how you can use these flags:: // does not throw a SyntaxError because the unknown variables and functions are ignored $expressionLanguage->lint('unknown_var + unknown_function()', [], Parser::IGNORE_UNKNOWN_VARIABLES | Parser::IGNORE_UNKNOWN_FUNCTIONS); -.. versionadded:: 7.1 - - The support for flags in the ``parse()`` and ``lint()`` methods - was introduced in Symfony 7.1. - Passing in Variables -------------------- diff --git a/components/filesystem.rst b/components/filesystem.rst index 4eae6aaad27..a8ec9ebd876 100644 --- a/components/filesystem.rst +++ b/components/filesystem.rst @@ -316,10 +316,6 @@ creates them before appending the contents. ``readFile`` ~~~~~~~~~~~~ -.. versionadded:: 7.1 - - The ``readFile()`` method was introduced in Symfony 7.1. - :method:`Symfony\\Component\\Filesystem\\Filesystem::readFile` returns all the contents of a file as a string. Unlike the :phpfunction:`file_get_contents` function from PHP, it throws an exception when the given file path is not readable and diff --git a/components/form.rst b/components/form.rst index 44f407e4c8e..751349b17f1 100644 --- a/components/form.rst +++ b/components/form.rst @@ -134,11 +134,6 @@ The following snippet adds CSRF protection to the form factory:: ->addExtension(new CsrfExtension($csrfManager)) ->getFormFactory(); -.. versionadded:: 7.2 - - Support for passing requests to the constructor of the ``RequestStack`` - class was introduced in Symfony 7.2. - Internally, this extension will automatically add a hidden field to every form (called ``_token`` by default) whose value is automatically generated by the CSRF generator and validated when binding the form. diff --git a/components/http_foundation.rst b/components/http_foundation.rst index 1cb87aafb24..15da88c8561 100644 --- a/components/http_foundation.rst +++ b/components/http_foundation.rst @@ -376,11 +376,6 @@ anonymized depending on the IP address format:: $anonymousIpv6 = IpUtils::anonymize($ipv6, 3, 10); // $anonymousIpv6 = '2a01:198:603::' -.. versionadded:: 7.2 - - The ``v4Bytes`` and ``v6Bytes`` parameters of the ``anonymize()`` method - were introduced in Symfony 7.2. - Check If an IP Belongs to a CIDR Subnet ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -459,11 +454,6 @@ You can use them individually or combine them using the // ... } -.. versionadded:: 7.1 - - The ``HeaderRequestMatcher`` and ``QueryParameterRequestMatcher`` were - introduced in Symfony 7.1. - Accessing other Data ~~~~~~~~~~~~~~~~~~~~ @@ -721,10 +711,6 @@ a PHP callable:: // disables FastCGI buffering in nginx only for this response $response->headers->set('X-Accel-Buffering', 'no'); -.. versionadded:: 7.3 - - Support for using string iterables was introduced in Symfony 7.3. - Streaming a JSON Response ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -906,11 +892,6 @@ and that will be automatically deleted after the response is sent:: $response = new BinaryFileResponse($file); -.. versionadded:: 7.1 - - The support for ``\SplTempFileObject`` in ``BinaryFileResponse`` - was introduced in Symfony 7.1. - If the size of the served file is unknown (e.g. because it's being generated on the fly, or because a PHP stream filter is registered on it, etc.), you can pass a ``Stream`` instance to ``BinaryFileResponse``. This will disable ``Range`` and ``Content-Length`` diff --git a/components/http_kernel.rst b/components/http_kernel.rst index 62d1e92d89b..1e7b2109fbb 100644 --- a/components/http_kernel.rst +++ b/components/http_kernel.rst @@ -525,12 +525,6 @@ The :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent` exposes the method, which you can use to determine if the kernel is currently terminating at the moment the exception was thrown. -.. versionadded:: 7.1 - - The - :method:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent::isKernelTerminating` - method was introduced in Symfony 7.1. - .. note:: When setting a response for the ``kernel.exception`` event, the propagation @@ -639,7 +633,7 @@ else that can be used to create a working example:: $routes->add('hello', new Route('/hello/{name}', [ '_controller' => function (Request $request): Response { return new Response( - sprintf("Hello %s", $request->get('name')) + sprintf("Hello %s", $request->attributes->get('name')) ); }] )); diff --git a/components/intl.rst b/components/intl.rst index ba3cbdcb959..f86b9e1ce3a 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -202,6 +202,12 @@ numeric country codes:: $exists = Countries::numericCodeExists('250'); // => true +.. note:: + + When the ``SYMFONY_INTL_WITH_USER_ASSIGNED`` environment variable is set, + the Symfony Intl component will also recognize user-assigned codes: ``XK``, ``XKK``, and ``983``. + This allows applications to handle these codes, which is useful for supporting regions that need to use them. + Locales ~~~~~~~ @@ -301,6 +307,47 @@ to catching the exception, you can also check if a given currency code is valid: $isValidCurrency = Currencies::exists($currencyCode); +By default, the previous currency methods return all currencies, including +those that are no longer in use. Symfony provides several methods to filter +currencies so you can work only with those that are actually valid and in use +for a given country. + +These methods use ICU metadata (``tender``, ``from`` and ``to`` dates) to +determine whether a currency is `legal tender`_ and/or active at a specific +point in time:: + + use Symfony\Component\Intl\Currencies; + + // get the list of today's legal and active currencies for a country + $codes = Currencies::forCountry('FR'); + // ['EUR'] + + // include non-legal currencies too, and check them at a given date + $codesAll = Currencies::forCountry( + 'ES', + legalTender: null, + active: true, + date: new \DateTimeImmutable('1982-01-01') + ); + // ['ESP', 'ESB'] + + // check if a currency is valid today for a country + $isOk = Currencies::isValidInCountry('CH', 'CHF'); + // true + + // check if a currency is valid in any country on a specific date + $isGlobal = Currencies::isValidInAnyCountry( + 'USD', + legalTender: true, + active: true, + date: new \DateTimeImmutable('2005-01-01') + ); + // true + +Note that some currencies (especially non-legal-tender ones) do not have validity +ranges defined. In such cases, a ``RuntimeException`` will be thrown. In addition, +an ``InvalidArgumentException`` will be thrown if the specified currency is invalid. + .. _component-intl-timezones: Timezones @@ -419,6 +466,7 @@ Learn more .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 .. _`ISO 3166-1 alpha-3`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3 .. _`ISO 3166-1 numeric`: https://en.wikipedia.org/wiki/ISO_3166-1_numeric +.. _`legal tender`: https://en.wikipedia.org/wiki/Legal_tender .. _`UTC/GMT time offsets`: https://en.wikipedia.org/wiki/List_of_UTC_time_offsets .. _`daylight saving time (DST)`: https://en.wikipedia.org/wiki/Daylight_saving_time .. _`ISO 639-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_639-1 diff --git a/components/json_path.rst b/components/json_path.rst index 9db8e48885e..b63934a7c50 100644 --- a/components/json_path.rst +++ b/components/json_path.rst @@ -1,11 +1,6 @@ The JsonPath Component ====================== -.. versionadded:: 7.3 - - The JsonPath component was introduced in Symfony 7.3 as an - :doc:`experimental feature `. - The JsonPath component lets you query and extract data from JSON structures. It implements the `RFC 9535 – JSONPath`_ standard, allowing you to navigate complex JSON data. diff --git a/components/ldap.rst b/components/ldap.rst index e52a341986c..64a9099e1a4 100644 --- a/components/ldap.rst +++ b/components/ldap.rst @@ -83,10 +83,6 @@ for binding to an LDAP server using `SASL`_:: After binding to the LDAP server, you can use the :method:`Symfony\\Component\\Ldap\\Ldap::whoami` method to get the distinguished name (DN) of the authenticated and authorized user. -.. versionadded:: 7.2 - - The ``saslBind()`` and ``whoami()`` methods were introduced in Symfony 7.2. - Once bound (or if you enabled anonymous authentication on your LDAP server), you may query the LDAP server using the :method:`Symfony\\Component\\Ldap\\Ldap::query` method:: diff --git a/components/lock.rst b/components/lock.rst index a2ad15d52e0..b89ed02ae57 100644 --- a/components/lock.rst +++ b/components/lock.rst @@ -128,6 +128,10 @@ example, the kernel will automatically release semaphores acquired by the store (see :ref:`lock stores ` for supported stores), an exception will be thrown when the application tries to serialize the key. +Locks can be serialized using both the native PHP serialization system +and its :phpfunction:`serialize` function, or using the Serializer +component. + .. _lock-blocking-locks: Blocking Locks @@ -391,6 +395,7 @@ Store Scope Blocking Ex ========================================================== ====== ======== ======== ======= ============= :ref:`DoctrineDbalPostgreSqlStore ` remote yes no yes no :ref:`DoctrineDbalStore ` remote retry yes no yes +:ref:`DynamoDbStore ` remote retry yes no yes :ref:`FlockStore ` local yes no yes no :ref:`MemcachedStore ` remote retry yes no yes :ref:`MongoDbStore ` remote retry yes no yes @@ -411,10 +416,6 @@ the lock in a non-blocking way until the lock is acquired. * ``InMemoryStore`` (``LOCK_DSN=in-memory``), which saves locks in memory during a process; * ``NullStore`` (``LOCK_DSN=null``) which doesn't persist anything. -.. versionadded:: 7.2 - - The :class:`Symfony\\Component\\Lock\\Store\\NullStore` was introduced in Symfony 7.2. - .. _lock-store-flock: FlockStore @@ -627,10 +628,6 @@ and expects a TTL to avoid stalled locks:: $store = new RedisStore($redis); -.. versionadded:: 7.3 - - Support for ``Relay\Cluster`` was introduced in Symfony 7.3. - .. _lock-store-semaphore: SemaphoreStore @@ -706,6 +703,32 @@ PHP process is terminated:: Zookeeper does not require a TTL as the nodes used for locking are ephemeral and die when the PHP process is terminated. +.. _lock-store-dynamodb: + +DynamoDbStore +~~~~~~~~~~~~~ + +The DynamoDbStore saves locks on a Amazon DynamoDB table. Install it by running: + +.. code-block:: terminal + + $ composer require symfony/amazon-dynamo-db-lock + +It requires a `DynamoDbClient`_ instance or a `Data Source Name (DSN)`_. +This store does not support blocking, and expects a TTL to avoid stalled locks:: + + use Symfony\Component\Lock\Bridge\DynamoDb\Store\DynamoDbStore; + + // a DynamoDbClient instance or DSN + $dynamoDbClientOrDSN = 'dynamodb://default/lock'; + $store = new DynamoDbStore($dynamoDbClientOrDSN); + +The table where values are stored is created automatically on the first call to +the :method:`Symfony\\Component\\Lock\\Bridge\\DynamoDb\\DynamoDbStore::save` method. +You can also create this table explicitly by calling the +:method:`Symfony\\Component\\Lock\\Bridge\\DynamoDb\\DynamoDbStore::createTable` method in +your code. + Reliability ----------- @@ -1057,3 +1080,4 @@ are still running. .. _`readers-writer lock`: https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock .. _`priority policy`: https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock#Priority_policies .. _`PCNTL`: https://www.php.net/manual/book.pcntl.php +.. _`DynamoDbClient`: https://async-aws.com/clients/dynamodb.html diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 6c90592db26..354749bdab5 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -316,10 +316,6 @@ correctly. To validate the types of the options, call } } -.. versionadded:: 7.3 - - Defining type unions with the ``|`` syntax was introduced in Symfony 7.3. - You can pass any type for which an ``is_()`` function is defined in PHP. You may also pass fully qualified class or interface names (which is checked using ``instanceof``). Additionally, you can validate all items in an array @@ -686,16 +682,6 @@ default value:: ], ]); -.. deprecated:: 7.3 - - Defining nested options via :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDefault` - is deprecated since Symfony 7.3. Use the :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setOptions` - method instead, which also allows defining default values for prototyped options. - -.. versionadded:: 7.3 - - The ``setOptions()`` method was introduced in Symfony 7.3. - Nested options also support required options, validation (type, value) and normalization of their values. If the default value of a nested option depends on another option defined in the parent level, add a second ``Options`` argument diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index e7334a3e658..0e2b9b68f31 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -566,9 +566,9 @@ Clock Mocking The :class:`Symfony\\Bridge\\PhpUnit\\ClockMock` class provided by this bridge allows you to mock the PHP's built-in time functions ``time()``, ``microtime()``, -``sleep()``, ``usleep()``, ``gmdate()``, and ``hrtime()``. Additionally the -function ``date()`` is mocked so it uses the mocked time if no timestamp is -specified. +``sleep()``, ``usleep()``, ``gmdate()``, ``hrtime()``, and ``strtotime()``. +Additionally the function ``date()`` is mocked so it uses the mocked time if no +timestamp is specified. Other functions with an optional timestamp parameter that defaults to ``time()`` will still use the system time instead of the mocked time. This means that you diff --git a/components/process.rst b/components/process.rst index 9c25c931510..f5a96bb7791 100644 --- a/components/process.rst +++ b/components/process.rst @@ -527,11 +527,6 @@ method. The given signals won't be propagated to the child process:: $process = new Process(['find', '/', '-name', 'rabbit']); $process->setIgnoredSignals([SIGKILL, SIGUSR1]); -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\Process\\Process::setIgnoredSignals` - method was introduced in Symfony 7.1. - Process Pid ----------- diff --git a/components/property_info.rst b/components/property_info.rst index 865a36c5941..e3a68b925f8 100644 --- a/components/property_info.rst +++ b/components/property_info.rst @@ -198,11 +198,6 @@ can provide the full documentation block for a property as a string:: It can span multiple lines. */ -.. versionadded:: 7.1 - - The :class:`Symfony\\Component\\PropertyInfo\\PropertyDocBlockExtractorInterface` - interface was introduced in Symfony 7.1. - .. _property-info-description: Description Information @@ -435,11 +430,6 @@ library is present:: $phpDocExtractor->getLongDescription($class, $property); $phpDocExtractor->getDocBlock($class, $property); -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor::getDocBlock` - method was introduced in Symfony 7.1. - PhpStanExtractor ~~~~~~~~~~~~~~~~ @@ -476,12 +466,6 @@ information from annotations of properties and methods, such as ``@var``, $phpStanExtractor->getShortDescription($class, 'bar'); $phpStanExtractor->getLongDescription($class, 'bar'); -.. versionadded:: 7.3 - - The :method:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpStanExtractor::getShortDescription` - and :method:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpStanExtractor::getLongDescription` - methods were introduced in Symfony 7.3. - SerializerExtractor ~~~~~~~~~~~~~~~~~~~ @@ -592,10 +576,6 @@ service by defining it as a service with one or more of the following (it checks if a property can be initialized through the constructor). * ``property_info.constructor_extractor`` if it provides type information from the constructor argument. - .. versionadded:: 7.3 - - The ``property_info.constructor_extractor`` tag was introduced in Symfony 7.3. - .. _`PSR-1`: https://www.php-fig.org/psr/psr-1/ .. _`phpDocumentor Reflection`: https://github.com/phpDocumentor/ReflectionDocBlock .. _`phpdocumentor/reflection-docblock`: https://packagist.org/packages/phpdocumentor/reflection-docblock diff --git a/components/runtime.rst b/components/runtime.rst index 770ea102563..15b8724cddf 100644 --- a/components/runtime.rst +++ b/components/runtime.rst @@ -302,11 +302,14 @@ Using Options ~~~~~~~~~~~~~ Some behavior of the Runtimes can be modified through runtime options. They -can be set using the ``APP_RUNTIME_OPTIONS`` environment variable:: +can be set using the ``APP_RUNTIME_OPTIONS`` environment variable as an array +or a JSON encoded string:: $_SERVER['APP_RUNTIME_OPTIONS'] = [ 'project_dir' => '/var/task', ]; + // same configuration using JSON: + // $_SERVER['APP_RUNTIME_OPTIONS'] = '{"project_dir":"\/var\/task"}'; require_once dirname(__DIR__).'/vendor/autoload_runtime.php'; diff --git a/components/type_info.rst b/components/type_info.rst index 817c7f1d61a..ee7681ffb7a 100644 --- a/components/type_info.rst +++ b/components/type_info.rst @@ -46,10 +46,6 @@ You can also use a generic method that detects the type automatically:: Type::fromValue('...'); // same as Type::string() Type::fromValue(false); // same as Type::false() -.. versionadded:: 7.3 - - The ``fromValue()`` method was introduced in Symfony 7.3. - Resolvers ~~~~~~~~~ @@ -163,11 +159,6 @@ Checking if a type **accepts a value**:: $type->accepts(123); // true $type->accepts('z'); // true -.. versionadded:: 7.3 - - The :method:`Symfony\\Component\\TypeInfo\\Type::accepts` - method was introduced in Symfony 7.3. - Using callables for **complex checks**:: class Foo diff --git a/components/uid.rst b/components/uid.rst index b4083765436..a4b6e2df01a 100644 --- a/components/uid.rst +++ b/components/uid.rst @@ -120,7 +120,7 @@ sortable (like :ref:`ULIDs `). It's more efficient for database indexing **UUID v7** (UNIX timestamp) Generates time-ordered UUIDs based on a high-resolution Unix Epoch timestamp -source (the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded) +source (the number of microseconds since midnight 1 Jan 1970 UTC, leap seconds excluded) (`read the UUIDv7 spec `__). It's recommended to use this version over UUIDv1 and UUIDv6 because it provides better entropy (and a more strict chronological order of UUID generation):: @@ -154,8 +154,42 @@ following methods to create a ``Uuid`` object from it:: $uuid = Uuid::fromBase58('TuetYWNHhmuSQ3xPoVLv9M'); $uuid = Uuid::fromRfc4122('d9e7a184-5d5b-11ea-a62a-3499710062d0'); -You can also use the ``UuidFactory`` to generate UUIDs. First, you may -configure the behavior of the factory using configuration files:: +You can also use the ``UuidFactory`` to generate UUIDs. Inject the factory in +your services and use it as follows: + + namespace App\Service; + + use Symfony\Component\Uid\Factory\UuidFactory; + + class FooService + { + public function __construct( + private UuidFactory $uuidFactory, + ) { + } + + public function generate(): void + { + $uuid = $this->uuidFactory->create(); + + $randomBasedUuid = $this->uuidFactory->randomBased()->create(); + // $namespace can be omitted if a default namespace is configured in the factory (see below) + $nameBasedUuid = $this->uuidFactory->nameBased($namespace)->create($name); + // $node can be omitted if a default node is configured in the factory (see below) + $timestampBased = $this->uuidFactory->timeBased($node)->create(); + + // ... + } + } + +By default, this factory generates the folllowing UUIDs: + +* Default and time-based UUIDs: UUIDv7 +* Name-based UUIDs: UUIDv5 +* Random-based UUIDs: UUIDv4 +* Time-based node and UUID namespace: ``null`` + +You can configure these default values:: .. configuration-block:: @@ -164,34 +198,12 @@ configure the behavior of the factory using configuration files:: # config/packages/uid.yaml framework: uid: - default_uuid_version: 7 - name_based_uuid_version: 5 + default_uuid_version: 6 + name_based_uuid_version: 3 name_based_uuid_namespace: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 - time_based_uuid_version: 7 + time_based_uuid_version: 6 time_based_uuid_node: 121212121212 - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/uid.php @@ -205,42 +217,15 @@ configure the behavior of the factory using configuration files:: $container->extension('framework', [ 'uid' => [ - 'default_uuid_version' => 7, - 'name_based_uuid_version' => 5, + 'default_uuid_version' => 6, + 'name_based_uuid_version' => 3, 'name_based_uuid_namespace' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8', - 'time_based_uuid_version' => 7, + 'time_based_uuid_version' => 6, 'time_based_uuid_node' => 121212121212, ], ]); }; -Then, you can inject the factory in your services and use it to generate UUIDs based -on the configuration you defined:: - - namespace App\Service; - - use Symfony\Component\Uid\Factory\UuidFactory; - - class FooService - { - public function __construct( - private UuidFactory $uuidFactory, - ) { - } - - public function generate(): void - { - // This creates a UUID of the version given in the configuration file (v7 by default) - $uuid = $this->uuidFactory->create(); - - $nameBasedUuid = $this->uuidFactory->nameBased(/** ... */); - $randomBasedUuid = $this->uuidFactory->randomBased(); - $timestampBased = $this->uuidFactory->timeBased(); - - // ... - } - } - Converting UUIDs ~~~~~~~~~~~~~~~~ @@ -255,10 +240,6 @@ Use these methods to transform the UUID object into different bases:: $uuid->toHex(); // string(34) "0xd9e7a1845d5b11eaa62a3499710062d0" $uuid->toString(); // string(36) "d9e7a184-5d5b-11ea-a62a-3499710062d0" -.. versionadded:: 7.1 - - The ``toString()`` method was introduced in Symfony 7.1. - You can also convert some UUID versions to others:: // convert V1 to V6 or V7 @@ -272,13 +253,6 @@ You can also convert some UUID versions to others:: $uuid->toV7(); // returns a Symfony\Component\Uid\UuidV7 instance -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\Uid\\UuidV1::toV6`, - :method:`Symfony\\Component\\Uid\\UuidV1::toV7` and - :method:`Symfony\\Component\\Uid\\UuidV6::toV7` - methods were introduced in Symfony 7.1. - Working with UUIDs ~~~~~~~~~~~~~~~~~~ @@ -336,11 +310,6 @@ The following constants are available: You can also use the ``Uuid::FORMAT_ALL`` constant to accept any UUID format. By default, only the RFC 4122 format is accepted. -.. versionadded:: 7.2 - - The ``$format`` parameter of the :method:`Symfony\\Component\\Uid\\Uuid::isValid` - method and the related constants were introduced in Symfony 7.2. - Storing UUIDs in Databases ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -429,6 +398,65 @@ of the UUID parameters:: } } +Testing UUIDs +~~~~~~~~~~~~~ + +Many UUID versions include random or time-dependent parts, which makes them +hard to use in tests. The :class:`Symfony\\Component\\Uid\\Factory\\MockUuidFactory` +class allows you to control the UUIDs generated during your tests, making them +predictable and reproducible. + +First, make sure that your service generates UUID values using the +:class:`Symfony\\Component\\Uid\\Factory\\UuidFactory`:: + + use Symfony\Component\Uid\Factory\UuidFactory; + use Symfony\Component\Uid\Uuid; + + class UserService + { + public function __construct( + private UuidFactory $uuidFactory + ){ + } + + public function createUserId(): string + { + return $this->uuidFactory->create()->toRfc4122(); + } + } + +Then, in your tests, you can use ``MockUuidFactory`` to define a sequence of the +UUIDs that will be returned each time you generate one:: + + use PHPUnit\Framework\TestCase; + use Symfony\Component\Uid\Factory\MockUuidFactory; + use Symfony\Component\Uid\UuidV4; + + class UserServiceTest extends TestCase + { + public function testCreateUserId(): void + { + $factory = new MockUuidFactory([ + UuidV4::fromString('11111111-1111-4111-8111-111111111111'), + UuidV4::fromString('22222222-2222-4222-8222-222222222222'), + ]); + + $service = new UserService($factory); + + $this->assertSame('11111111-1111-4111-8111-111111111111', $service->createUserId()); + $this->assertSame('22222222-2222-4222-8222-222222222222', $service->createUserId()); + } + } + +In addition to the ``create()`` method, the ``MockUuidFactory`` also works for +the ``randomBased()``, ``timeBased()``, and ``nameBased()`` methods. You can even +mix different UUID versions in the same sequence. + +.. note:: + + ``MockUuidFactory`` throws an exception if the sequence is exhausted or the + available UUID types don't match the requested type. + .. _ulid: ULIDs @@ -634,25 +662,6 @@ configuration in your application before using these commands: Symfony\Component\Uid\Command\InspectUlidCommand: ~ Symfony\Component\Uid\Command\InspectUuidCommand: ~ - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/components/var_dumper.rst b/components/var_dumper.rst index c6966a692af..01dbbdec15e 100644 --- a/components/var_dumper.rst +++ b/components/var_dumper.rst @@ -124,21 +124,6 @@ the :ref:`dump_destination option ` of the debug: dump_destination: "tcp://%env(VAR_DUMPER_SERVER)%" - .. code-block:: xml - - - - - - - .. code-block:: php // config/packages/debug.php diff --git a/components/var_exporter.rst b/components/var_exporter.rst index c7ec9cd90d0..031e285d0c5 100644 --- a/components/var_exporter.rst +++ b/components/var_exporter.rst @@ -207,169 +207,5 @@ pattern, which also works with abstract classes, internal classes, and interface Use this mechanism only when native lazy objects cannot be leveraged (otherwise you'll get a deprecation notice). -Legacy Creation of Lazy Objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When using a PHP version earlier than 8.4, native lazy objects are not available. -In these cases, the VarExporter component provides two traits that help you -implement lazy-loading mechanisms in your classes. - -.. _var-exporter_ghost-objects: - -LazyGhostTrait -.............. - -.. deprecated:: 7.3 - - ``LazyGhostTrait`` is deprecated since Symfony 7.3. Use PHP 8.4's native lazy - objects instead. Note that using the trait with PHP versions earlier than 8.4 - does not trigger a deprecation, to ease the transition. - -Ghost objects are empty objects, which see their properties populated the first -time any method is called. Thanks to :class:`Symfony\\Component\\VarExporter\\LazyGhostTrait`, -the implementation of the lazy mechanism is eased. The ``MyLazyObject::populateHash()`` -method will be called only when the object is actually used and needs to be -initialized:: - - namespace App\Hash; - - use Symfony\Component\VarExporter\LazyGhostTrait; - - class HashProcessor - { - use LazyGhostTrait; - - // This property may require a heavy computation to have its value - public readonly string $hash; - - public function __construct() - { - self::createLazyGhost(initializer: $this->populateHash(...), instance: $this); - } - - private function populateHash(array $data): void - { - // Compute $this->hash value with the passed data - } - } - -:class:`Symfony\\Component\\VarExporter\\LazyGhostTrait` also allows to -convert non-lazy classes to lazy ones:: - - namespace App\Hash; - - use Symfony\Component\VarExporter\LazyGhostTrait; - - class HashProcessor - { - public readonly string $hash; - - public function __construct(array $data) - { - $this->populateHash($data); - } - - private function populateHash(array $data): void - { - // ... - } - - public function validateHash(): bool - { - // ... - } - } - - class LazyHashProcessor extends HashProcessor - { - use LazyGhostTrait; - } - - $processor = LazyHashProcessor::createLazyGhost(initializer: function (HashProcessor $instance): void { - // Do any operation you need here: call setters, getters, methods to validate the hash, etc. - $data = /** Retrieve required data to compute the hash */; - $instance->__construct(...$data); - $instance->validateHash(); - }); - -While you never query ``$processor->hash`` value, heavy methods will never be -triggered. But still, the ``$processor`` object exists and can be used in your -code, passed to methods, functions, etc. - -Ghost objects unfortunately can't work with abstract classes or internal PHP -classes. Nevertheless, the VarExporter component covers this need with the help -of :ref:`Virtual Proxies `. - -.. _var-exporter_virtual-proxies: - -LazyProxyTrait -.............. - -.. deprecated:: 7.3 - - ``LazyProxyTrait`` is deprecated since Symfony 7.3. Use PHP 8.4's native lazy - objects instead. Note that using the trait with PHP versions earlier than 8.4 - does not trigger a deprecation, to ease the transition. - -The purpose of virtual proxies in the same one as -:ref:`ghost objects `, but their internal behavior is -totally different. Where ghost objects requires to extend a base class, virtual -proxies take advantage of the **Liskov Substitution principle**. This principle -describes that if two objects are implementing the same interface, you can swap -between the different implementations without breaking your application. This is -what virtual proxies take advantage of. To use virtual proxies, you may use -:class:`Symfony\\Component\\VarExporter\\ProxyHelper` to generate proxy's class -code:: - - namespace App\Hash; - - use Symfony\Component\VarExporter\ProxyHelper; - - interface ProcessorInterface - { - public function getHash(): bool; - } - - abstract class AbstractProcessor implements ProcessorInterface - { - protected string $hash; - - public function getHash(): bool - { - return $this->hash; - } - } - - class HashProcessor extends AbstractProcessor - { - public function __construct(array $data) - { - $this->populateHash($data); - } - - private function populateHash(array $data): void - { - // ... - } - } - - $proxyCode = ProxyHelper::generateLazyProxy(new \ReflectionClass(AbstractProcessor::class)); - // $proxyCode contains the actual proxy and the reference to LazyProxyTrait. - // In production env, this should be dumped into a file to avoid calling eval(). - eval('class HashProcessorProxy'.$proxyCode); - - $processor = HashProcessorProxy::createLazyProxy(initializer: function (): ProcessorInterface { - $data = /** Retrieve required data to compute the hash */; - $instance = new HashProcessor(...$data); - - // Do any operation you need here: call setters, getters, methods to validate the hash, etc. - - return $instance; - }); - -Just like ghost objects, while you never query ``$processor->hash``, its value -will not be computed. The main difference with ghost objects is that this time, -a proxy of an abstract class was created. This also works with internal PHP class. - .. _`OPcache`: https://www.php.net/opcache .. _`PSR-2`: https://www.php-fig.org/psr/psr-2/ diff --git a/components/yaml.rst b/components/yaml.rst index 5616656aae2..761d68e63c5 100644 --- a/components/yaml.rst +++ b/components/yaml.rst @@ -366,11 +366,6 @@ giving the enumeration FQCN:: $parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT); // $parameters = ['bar' => ['foo', 'bar']]; -.. versionadded:: 7.1 - - The support for using the enum FQCN without specifying a case - was introduced in Symfony 7.1. - Parsing and Dumping of Binary Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -428,10 +423,6 @@ use the ``DUMP_NULL_AS_EMPTY`` flag to dump null values as empty strings:: $dumped = Yaml::dump(['foo' => null], 2, 4, Yaml::DUMP_NULL_AS_EMPTY); // foo: -.. versionadded:: 7.3 - - The ``DUMP_NULL_AS_EMPTY`` flag was introduced in Symfony 7.3. - Dumping Numeric Keys as Strings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -461,10 +452,6 @@ if they are reserved words or contain newlines and spaces). Use the ], 2, 4, Yaml::DUMP_FORCE_DOUBLE_QUOTES_ON_VALUES); // "foo": "bar", "some foo": "some bar", "x": 3.14, "y": true, "z": null -.. versionadded:: 7.3 - - The ``Yaml::DUMP_FORCE_DOUBLE_QUOTES_ON_VALUES`` flag was introduced in Symfony 7.3. - Dumping Collection of Maps ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -492,10 +479,6 @@ use the ``Yaml::DUMP_COMPACT_NESTED_MAPPING`` flag: - name: Jupiter distance: 778500000 -.. versionadded:: 7.3 - - The ``Yaml::DUMP_COMPACT_NESTED_MAPPING`` flag was introduced in Symfony 7.3. - Syntax Validation ~~~~~~~~~~~~~~~~~ diff --git a/configuration.rst b/configuration.rst index a2f6958d174..812dd42b67f 100644 --- a/configuration.rst +++ b/configuration.rst @@ -53,7 +53,7 @@ Configuration Formats ~~~~~~~~~~~~~~~~~~~~~ Unlike other frameworks, Symfony doesn't impose a specific format on you to -configure your applications, but lets you choose between YAML, XML and PHP. +configure your applications, but lets you choose between YAML and PHP. Throughout the Symfony documentation, all configuration examples will be shown in these three formats. @@ -66,20 +66,9 @@ readable. These are the main advantages and disadvantages of each format: * **YAML**: simple, clean and readable, but not all IDEs support autocompletion and validation for it. :doc:`Learn the YAML syntax `; -* **XML**: autocompleted/validated by most IDEs and is parsed natively by PHP, - but sometimes it generates configuration considered too verbose. `Learn the XML syntax`_; * **PHP**: very powerful and it allows you to create dynamic configuration with - arrays or a :ref:`ConfigBuilder `. - -.. note:: - - By default Symfony loads the configuration files defined in YAML and PHP - formats. If you define configuration in XML format, update the - :method:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait::configureContainer` - and/or - :method:`Symfony\\Bundle\\FrameworkBundle\\Kernel\\MicroKernelTrait::configureRoutes` - methods in the ``src/Kernel.php`` file to add support for the ``.xml`` file - extension. + arrays, and benefits from auto completion and static analysis using + array shapes. Importing Configuration Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -100,37 +89,12 @@ configuration files, even if they use a different format: - { resource: '/etc/myapp/*.yaml' } # ignore_errors: not_found silently discards errors if the loaded file doesn't exist - - { resource: 'my_config_file.xml', ignore_errors: not_found } + - { resource: 'my_config_file.php', ignore_errors: not_found } # ignore_errors: true silently discards all errors (including invalid code and not found) - - { resource: 'my_other_config_file.xml', ignore_errors: true } + - { resource: 'my_other_config_file.php', ignore_errors: true } # ... - .. code-block:: xml - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -191,49 +155,6 @@ reusable configuration value. By convention, parameters are defined under the # ... - .. code-block:: xml - - - - - - - - something@example.com - - - true - - true - - - - en - es - fr - - - - VGhpcyBpcyBhIEJlbGwgY2hhciAH - - - GLOBAL_CONSTANT - App\Entity\BlogPost::MAX_ITEMS - - - App\Enum\PostState::Published - - - - - .. code-block:: php // config/services.php @@ -267,27 +188,6 @@ reusable configuration value. By convention, parameters are defined under the // ... -.. warning:: - - By default and when using XML configuration, the values between ```` - tags are not trimmed. This means that the value of the following parameter will be - ``'\n something@example.com\n'``: - - .. code-block:: xml - - - something@example.com - - - If you want to trim the value of your parameter, use the ``trim`` attribute. - When using it, the value of the following parameter will be ``something@example.com``: - - .. code-block:: xml - - - something@example.com - - Once defined, you can reference this parameter value from any other configuration file using a special syntax: wrap the parameter name in two ``%`` (e.g. ``%app.admin_email%``): @@ -301,24 +201,6 @@ configuration file using a special syntax: wrap the parameter name in two ``%`` # any string surrounded by two % is replaced by that parameter value email_address: '%app.admin_email%' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/some_package.php @@ -331,7 +213,7 @@ configuration file using a special syntax: wrap the parameter name in two ``%`` 'email_address' => param('app.admin_email'), // ... but if you prefer it, you can also pass the name as a string - // surrounded by two % (same as in YAML and XML formats) and Symfony will + // surrounded by two % (same as in YAML format) and Symfony will // replace it by that parameter value 'email_address' => '%app.admin_email%', ]); @@ -352,13 +234,6 @@ configuration file using a special syntax: wrap the parameter name in two ``%`` # Parsed as 'https://symfony.com/?foo=%s&bar=%d' url_pattern: 'https://symfony.com/?foo=%%s&bar=%%d' - .. code-block:: xml - - - - http://symfony.com/?foo=%%s&bar=%%d - - .. code-block:: php // config/services.php @@ -392,10 +267,6 @@ If a non-empty parameter is ``null``, an empty string ``''``, or an empty array Symfony will throw an exception. This validation is **not** made at compile time but when attempting to retrieve the value of the parameter. -.. versionadded:: 7.2 - - Validating non-empty parameters was introduced in Symfony 7.2. - .. seealso:: Later in this article you can read how to @@ -483,33 +354,6 @@ files directly in the ``config/packages/`` directory. # ... when@test: *webpack_prod - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -630,23 +474,6 @@ This example shows how you could configure the application secret using an env v secret: '%env(APP_SECRET)%' # ... - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -697,26 +524,6 @@ To do so, define a parameter with the same name as the env var using this syntax # ... - .. code-block:: xml - - - - - - - - some_secret - - - - - .. code-block:: php // config/packages/framework.php @@ -984,11 +791,6 @@ to learn more about this. If you need to know the path to the ``.env`` file that Symfony is using, you can read the ``SYMFONY_DOTENV_PATH`` environment variable in your application. -.. versionadded:: 7.1 - - The ``SYMFONY_DOTENV_PATH`` environment variable was introduced in Symfony - 7.1. - .. _configuration-secrets: Encrypting Environment Variables (Secrets) @@ -1178,26 +980,6 @@ doesn't work for parameters: arguments: $contentsDir: '%app.contents_dir%' - .. code-block:: xml - - - - - - - ... - - - - - %app.contents_dir% - - - - .. code-block:: php // config/services.php @@ -1235,26 +1017,6 @@ whenever a service/controller defines a ``$projectDir`` argument, use this: # ... - .. code-block:: xml - - - - - - - - - %kernel.project_dir% - - - - - - .. code-block:: php // config/services.php @@ -1302,52 +1064,6 @@ parameters at once by type-hinting any of its constructor arguments with the } } -.. _config-config-builder: - -Using PHP ConfigBuilders ------------------------- - -Writing PHP config is sometimes difficult because you end up with large nested -arrays and you have no autocompletion help from your favorite IDE. A way to -address this is to use "ConfigBuilders". They are objects that will help you -build these arrays. - -Symfony generates the ConfigBuilder classes automatically in the -:ref:`kernel build directory ` for all the -bundles installed in your application. By convention they all live in the -namespace ``Symfony\Config``:: - - // config/packages/security.php - use Symfony\Config\SecurityConfig; - - return static function (SecurityConfig $security): void { - $security->firewall('main') - ->pattern('^/*') - ->lazy(true) - ->security(false); - - $security - ->roleHierarchy('ROLE_ADMIN', ['ROLE_USER']) - ->roleHierarchy('ROLE_SUPER_ADMIN', ['ROLE_ADMIN', 'ROLE_ALLOWED_TO_SWITCH']) - ->accessControl() - ->path('^/user') - ->roles('ROLE_USER'); - - $security->accessControl(['path' => '^/admin', 'roles' => 'ROLE_ADMIN']); - }; - -.. note:: - - Only root classes in the namespace ``Symfony\Config`` are ConfigBuilders. - Nested configs (e.g. ``\Symfony\Config\Framework\CacheConfig``) are regular - PHP objects which aren't autowired when using them as an argument type. - -.. note:: - - In order to get ConfigBuilders autocompletion in your IDE/editor, make sure - to not exclude the directory where these classes are generated (by default, - in ``var/cache/dev/Symfony/Config/``). - Keep Going! ----------- @@ -1369,7 +1085,6 @@ And all the other topics related to configuration: configuration/* -.. _`Learn the XML syntax`: https://en.wikipedia.org/wiki/XML .. _`environment variables`: https://en.wikipedia.org/wiki/Environment_variable .. _`symbolic links`: https://en.wikipedia.org/wiki/Symbolic_link .. _`utilities to manage env vars`: https://symfony.com/doc/current/cloud/env.html diff --git a/configuration/env_var_processors.rst b/configuration/env_var_processors.rst index 53281cf2a68..502f6ae0c2d 100644 --- a/configuration/env_var_processors.rst +++ b/configuration/env_var_processors.rst @@ -21,23 +21,6 @@ processor to turn the value of the ``HTTP_PORT`` env var into an integer: router: http_port: '%env(int:HTTP_PORT)%' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -71,25 +54,6 @@ Symfony provides the following env var processors: framework: secret: '%env(string:SECRET)%' - .. code-block:: xml - - - - - - - some_secret - - - - - .. code-block:: php // config/packages/framework.php @@ -118,25 +82,6 @@ Symfony provides the following env var processors: framework: http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%' - .. code-block:: xml - - - - - - - true - - - - - .. code-block:: php // config/packages/framework.php @@ -162,24 +107,6 @@ Symfony provides the following env var processors: parameters: safe_for_production: '%env(not:APP_DEBUG)%' - .. code-block:: xml - - - - - - - %env(not:APP_DEBUG)% - - - - .. code-block:: php // config/services.php @@ -205,27 +132,6 @@ Symfony provides the following env var processors: access_control: - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' } - .. code-block:: xml - - - - - - - Symfony\Component\HttpFoundation\Request::METHOD_HEAD - - - - - - - .. code-block:: php // config/packages/security.php @@ -255,24 +161,6 @@ Symfony provides the following env var processors: env(ALLOWED_LANGUAGES): '["en","de","es"]' app_allowed_languages: '%env(json:ALLOWED_LANGUAGES)%' - .. code-block:: xml - - - - - - - ["en","de","es"] - %env(json:ALLOWED_LANGUAGES)% - - - .. code-block:: php // config/packages/framework.php @@ -301,23 +189,6 @@ Symfony provides the following env var processors: sentry: dsn: '%env(resolve:SENTRY_DSN)%' - .. code-block:: xml - - - - - - - 10.0.0.1 - http://%sentry_host%/project - - - - - .. code-block:: php // config/packages/sentry.php @@ -339,24 +210,6 @@ Symfony provides the following env var processors: env(ALLOWED_LANGUAGES): "en,de,es" app_allowed_languages: '%env(csv:ALLOWED_LANGUAGES)%' - .. code-block:: xml - - - - - - - en,de,es - %env(csv:ALLOWED_LANGUAGES)% - - - .. code-block:: php // config/packages/framework.php @@ -385,30 +238,6 @@ Symfony provides the following env var processors: class: RedisCluster arguments: [null, "%env(shuffle:csv:REDIS_NODES)%"] - .. code-block:: xml - - - - - - - redis://127.0.0.1:6380,redis://127.0.0.1:6381 - - - - - null - %env(shuffle:csv:REDIS_NODES)% - - - - .. code-block:: php // config/services.php @@ -432,25 +261,6 @@ Symfony provides the following env var processors: google: auth: '%env(file:AUTH_FILE)%' - .. code-block:: xml - - - - - - - ../config/auth.json - - - - - .. code-block:: php // config/packages/framework.php @@ -473,25 +283,6 @@ Symfony provides the following env var processors: app: auth: '%env(require:PHP_FILE)%' - .. code-block:: xml - - - - - - - ../config/.runtime-evaluated.php - - - - - .. code-block:: php // config/packages/framework.php @@ -515,25 +306,6 @@ Symfony provides the following env var processors: google: auth: '%env(trim:file:AUTH_FILE)%' - .. code-block:: xml - - - - - - - ../config/auth.json - - - - - .. code-block:: php // config/packages/framework.php @@ -556,24 +328,6 @@ Symfony provides the following env var processors: database_password: '%env(key:database_password:json:file:SECRETS_FILE)%' # if SECRETS_FILE contents are: {"database_password": "secret"} it returns "secret" - .. code-block:: xml - - - - - - - /opt/application/.secrets.json - %env(key:database_password:json:file:SECRETS_FILE)% - - - .. code-block:: php // config/services.php @@ -594,24 +348,6 @@ Symfony provides the following env var processors: private_key: '%env(default:raw_key:file:PRIVATE_KEY)%' raw_key: '%env(PRIVATE_KEY)%' - .. code-block:: xml - - - - - - - %env(default:raw_key:file:PRIVATE_KEY)% - %env(PRIVATE_KEY)% - - - .. code-block:: php // config/services.php @@ -647,28 +383,6 @@ Symfony provides the following env var processors: $password: '%env(string:key:pass:url:DATABASE_URL)%' $database_name: '%env(key:path:url:DATABASE_URL)%' - .. code-block:: xml - - - - - - - - - %env(string:key:host:url:DATABASE_URL)% - %env(int:key:port:url:DATABASE_URL)% - %env(string:key:user:url:DATABASE_URL)% - %env(string:key:pass:url:DATABASE_URL)% - %env(key:path:url:DATABASE_URL)% - - - - .. code-block:: php // config/services.php @@ -713,25 +427,6 @@ Symfony provides the following env var processors: $serverVersion: '%env(string:key:serverVersion:query_string:DATABASE_URL)%' $charset: '%env(string:key:charset:query_string:DATABASE_URL)%' - .. code-block:: xml - - - - - - - - - %env(string:key:serverVersion:query_string:DATABASE_URL)% - %env(string:key:charset:query_string:DATABASE_URL)% - - - - .. code-block:: php // config/services.php @@ -767,23 +462,6 @@ Symfony provides the following env var processors: parameters: suit: '%env(enum:App\Enum\Suit:CARD_SUIT)%' - .. code-block:: xml - - - - - - - %env(enum:App\Enum\Suit:CARD_SUIT)% - - - .. code-block:: php // config/services.php @@ -804,23 +482,6 @@ Symfony provides the following env var processors: parameters: typed_env: '%env(defined:FOO)%' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/services.php @@ -842,24 +503,6 @@ Symfony provides the following env var processors: env(DATABASE_URL): 'mysql://db_user:foo@b$r@127.0.0.1:3306/db_name' encoded_database_url: '%env(urlencode:DATABASE_URL)%' - .. code-block:: xml - - - - - - - mysql://db_user:foo@b$r@127.0.0.1:3306/db_name - %env(urlencode:DATABASE_URL)% - - - .. code-block:: php // config/packages/framework.php @@ -873,10 +516,6 @@ Symfony provides the following env var processors: $container->setParameter('encoded_database_url', '%env(urlencode:DATABASE_URL)%'); }; - .. versionadded:: 7.1 - - The ``env(urlencode:...)`` env var processor was introduced in Symfony 7.1. - It is also possible to combine any number of processors: .. configuration-block:: @@ -893,29 +532,6 @@ It is also possible to combine any number of processors: # 4. JSON-decodes the content of the file and returns it auth: '%env(json:file:resolve:AUTH_FILE)%' - .. code-block:: xml - - - - - - - %kernel.project_dir%/config/auth.json - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/configuration/front_controllers_and_kernel.rst b/configuration/front_controllers_and_kernel.rst index b55f66afc33..428aa13e871 100644 --- a/configuration/front_controllers_and_kernel.rst +++ b/configuration/front_controllers_and_kernel.rst @@ -166,21 +166,6 @@ parameter used, for example, to turn Twig's debug mode on: twig: debug: '%kernel.debug%' - .. code-block:: xml - - - - - - - - .. code-block:: php // config/packages/twig.php diff --git a/configuration/micro_kernel_trait.rst b/configuration/micro_kernel_trait.rst index 542532ee1af..947abefc807 100644 --- a/configuration/micro_kernel_trait.rst +++ b/configuration/micro_kernel_trait.rst @@ -310,11 +310,6 @@ Now it looks like this:: } -.. versionadded:: 7.3 - - The ``wdt.php`` and ``profiler.php`` files were introduced in Symfony 7.3. - Previously, you had to import ``wdt.xml`` and ``profiler.xml`` - Before continuing, run this command to add support for the new dependencies: .. code-block:: terminal @@ -362,21 +357,6 @@ because the configuration started to get bigger: secret: S0ME_SECRET profiler: { only_exceptions: false } - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/framework.php diff --git a/configuration/override_dir_structure.rst b/configuration/override_dir_structure.rst index e5dff35b6d0..44bc0af04ee 100644 --- a/configuration/override_dir_structure.rst +++ b/configuration/override_dir_structure.rst @@ -118,6 +118,13 @@ named ``APP_CACHE_DIR`` whose value is the full path of the cache folder. its own cached configuration files, and so each needs its own directory to store those cache files. +In case you have multiple frontend servers using the same shared filesystem, you +can make use of the :method:`Symfony\\Component\\HttpKernel\\Kernel::getShareDir` method to +get a shared directory for cache and shared data. The shared directory can be set +by overriding an environment variable named ``APP_SHARE_DIR`` whose value is the full +path of the shared folder. This directory is also accessible as a container parameter +named ``%kernel.share_dir%``. + .. _override-logs-dir: Override the Log Directory @@ -166,24 +173,6 @@ for multiple directories): # ... default_path: "%kernel.project_dir%/resources/views" - .. code-block:: xml - - - - - - - %kernel.project_dir%/resources/views - - - - .. code-block:: php // config/packages/twig.php @@ -210,26 +199,6 @@ configuration option to define your own translations directory (use :ref:`framew # ... default_path: "%kernel.project_dir%/i18n" - .. code-block:: xml - - - - - - - - %kernel.project_dir%/i18n - - - - - .. code-block:: php // config/packages/translation.php diff --git a/configuration/secrets.rst b/configuration/secrets.rst index 285b89d521e..5e91c82a611 100644 --- a/configuration/secrets.rst +++ b/configuration/secrets.rst @@ -114,26 +114,6 @@ If you stored a ``DATABASE_PASSWORD`` secret, you can reference it by: # ... # ... - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/doctrine.php @@ -178,10 +158,6 @@ you to reveal a single secret's value. my secret -.. versionadded:: 7.1 - - The ``secrets:reveal`` command was introduced in Symfony 7.1. - Remove Secrets -------------- @@ -301,25 +277,6 @@ The secrets system is enabled by default and some of its behavior can be configu #local_dotenv_file: '%kernel.project_dir%/.env.%kernel.environment%.local' #decryption_env_var: 'base64:default::SYMFONY_DECRYPTION_SECRET' - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/configuration/using_parameters_in_dic.rst b/configuration/using_parameters_in_dic.rst index 3cac5d5049c..1036d404d8f 100644 --- a/configuration/using_parameters_in_dic.rst +++ b/configuration/using_parameters_in_dic.rst @@ -44,31 +44,6 @@ Now, examine the results to see this closely: # The Configurator does not know anything about # "%kernel.debug%" being a parameter. - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php $container->loadFromExtension('my_bundle', [ diff --git a/console.rst b/console.rst index eda37db0e0f..31a2f1034df 100644 --- a/console.rst +++ b/console.rst @@ -142,22 +142,22 @@ attribute. For example, you may want a command to create a user:: } } -.. versionadded:: 7.3 - - Support for invokable commands that don't extend the base ``Command`` class - was introduced in Symfony 7.3 - If you can't use PHP attributes, register the command as a service and :doc:`tag it ` with the ``console.command`` tag. If you're using the :ref:`default services.yaml configuration `, this is already done for you, thanks to :ref:`autoconfiguration `. -You can also use ``#[AsCommand]`` to add a description and longer help text for the command:: +You can also use ``#[AsCommand]`` to add a description, usage exampless, and +longer help text for the command:: #[AsCommand( name: 'app:create-user', - description: 'Creates a new user.', // the command description shown when running "php bin/console list" - help: 'This command allows you to create a user...', // the command help shown when running the command with the "--help" option + // this short description is shown when running "php bin/console list" + description: 'Creates a new user.', + // this is shown when running the command with the "--help" option + help: 'This command allows you to create a user...', + // this allows you to show one or more usage examples (no need to add the command name) + usages: ['bob', 'alice --as-admin'], )] class CreateUserCommand { @@ -207,6 +207,30 @@ After configuring and registering the command, you can run it in the terminal: As you might expect, this command will do nothing as you didn't write any logic yet. Add your own logic inside the ``__invoke()`` method. +.. _command-aliases: + +Command Aliases +~~~~~~~~~~~~~~~ + +You can define alternative names (aliases) for a command directly in its name +using a pipe (``|``) separator. The first name in the list becomes the actual +command name; the others are aliases that can also be used to run the command:: + + // src/Command/CreateUserCommand.php + namespace App\Command; + + use Symfony\Component\Console\Attribute\AsCommand; + use Symfony\Component\Console\Command\Command; + + #[AsCommand( + name: 'app:create-user|app:add-user|app:new-user', + description: 'Creates a new user.', + )] + class CreateUserCommand extends Command + { + // ... + } + Console Output -------------- diff --git a/console/commands_as_services.rst b/console/commands_as_services.rst index ed5b99f9cb4..da8e664ba80 100644 --- a/console/commands_as_services.rst +++ b/console/commands_as_services.rst @@ -78,24 +78,6 @@ Or set the ``command`` attribute on the ``console.command`` tag in your service tags: - { name: 'console.command', command: 'app:sunshine' } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/console/hide_commands.rst b/console/hide_commands.rst index 4ab9d3a6dad..f7f7139290d 100644 --- a/console/hide_commands.rst +++ b/console/hide_commands.rst @@ -22,8 +22,21 @@ the ``hidden`` property of the ``AsCommand`` attribute:: // ... } -Hidden commands behave the same as normal commands but they are no longer displayed -in command listings, so end-users are not aware of their existence. +You can also define a command as hidden using the pipe (``|``) syntax of +:ref:`command aliases `. To do this, use the command name as one +of the aliases and leave the main command name (the part before the ``|``) empty:: + + // src/Command/LegacyCommand.php + namespace App\Command; + + use Symfony\Component\Console\Attribute\AsCommand; + use Symfony\Component\Console\Command\Command; + + #[AsCommand(name: '|app:legacy')] + class LegacyCommand extends Command + { + // ... + } .. note:: diff --git a/console/input.rst b/console/input.rst index d5b6e4881bb..609764d3aeb 100644 --- a/console/input.rst +++ b/console/input.rst @@ -342,11 +342,6 @@ command without having to worry about the number of arguments or options:: // ... } -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\Console\\Input\\ArgvInput::getRawTokens` - method was introduced in Symfony 7.1. - Adding Argument/Option Value Completion --------------------------------------- @@ -454,10 +449,6 @@ The Console component adds some predefined options to all commands: * ``--ansi|--no-ansi``: whether to force of disable coloring the output * ``--profile``: enables the Symfony profiler -.. versionadded:: 7.2 - - The ``--silent`` option was introduced in Symfony 7.2. - When using the ``FrameworkBundle``, two more options are predefined: * ``--env|-e``: sets the Kernel configuration environment (defaults to ``APP_ENV``) diff --git a/console/lockable_trait.rst b/console/lockable_trait.rst index 005c6c03047..492c569cfd9 100644 --- a/console/lockable_trait.rst +++ b/console/lockable_trait.rst @@ -65,8 +65,4 @@ a ``$lockFactory`` property with your own lock factory:: // ... } -.. versionadded:: 7.1 - - The ``$lockFactory`` property was introduced in Symfony 7.1. - .. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science) diff --git a/console/style.rst b/console/style.rst index 709f9bac344..2b3cc5a86d3 100644 --- a/console/style.rst +++ b/console/style.rst @@ -181,11 +181,6 @@ Content Methods ], ]); -.. versionadded:: 7.3 - - The ``SymfonyStyle::tree()`` and the ``SymfonyStyle::createTree()`` methods - were introduced in Symfony 7.3. - :method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::createTree` Creates an instance of :class:`Symfony\\Component\\Console\\Helper\\TreeHelper` styled according to the Symfony Style Guide, which allows you to use diff --git a/console/verbosity.rst b/console/verbosity.rst index 3afd085d773..39fc6f4f3f9 100644 --- a/console/verbosity.rst +++ b/console/verbosity.rst @@ -26,10 +26,6 @@ messages, but you can control their verbosity with the ``-q`` and ``-v`` options # display all messages (useful to debug errors) $ php bin/console some-command -vvv -.. versionadded:: 7.2 - - The ``--silent`` option was introduced in Symfony 7.2. - The verbosity level can also be controlled globally for all commands with the ``SHELL_VERBOSITY`` environment variable (the ``-q`` and ``-v`` options still have more precedence over the value of ``SHELL_VERBOSITY``): @@ -82,10 +78,6 @@ level. For example:: } } -.. versionadded:: 7.2 - - The ``isSilent()`` method was introduced in Symfony 7.2. - When the silent or quiet level are used, all output is suppressed as the default :method:`Symfony\\Component\\Console\\Output\\Output::write` method returns without actually printing. diff --git a/contributing/code/pull_requests.rst b/contributing/code/pull_requests.rst index ee20a0ddd42..f9952967362 100644 --- a/contributing/code/pull_requests.rst +++ b/contributing/code/pull_requests.rst @@ -31,7 +31,7 @@ Before working on Symfony, setup a friendly environment with the following software: * Git; -* PHP version 8.2 or above. +* PHP version 8.4 or above. Configure Git ~~~~~~~~~~~~~ diff --git a/contributing/code/reproducer.rst b/contributing/code/reproducer.rst index c2208b70b09..bc08a353498 100644 --- a/contributing/code/reproducer.rst +++ b/contributing/code/reproducer.rst @@ -70,11 +70,11 @@ to a route definition. Then, after creating your project: see if the bug appears or not. #. If you can see the bug, you're done and you can already share the code with us. #. If you can't see the bug, you must keep making small changes. For example, if - your original route was defined using XML, forget about the previous route - and define the route using XML instead. Or maybe your application - registers some event listeners and that's where the real bug is. In that case, - add an event listener that's similar to your real app to see if you can find - the bug. + your original route was defined in a YAML or PHP file in the ``config/`` folder, + forget about the previous route and define the route using the same pattern. + Or maybe your application registers some event listeners and that's where the + real bug is. In that case, add an event listener that's similar to your real + app to see if you can find the bug. In short, the idea is to keep adding small and incremental changes to a new project until you can reproduce the bug. diff --git a/contributing/code/tests.rst b/contributing/code/tests.rst index 014a0ad0006..ae5e8696d9e 100644 --- a/contributing/code/tests.rst +++ b/contributing/code/tests.rst @@ -64,6 +64,17 @@ what's going on and if the tests are broken because of the new code. On Windows, install the `Cmder`_, `ConEmu`_, `ANSICON`_ or `Mintty`_ free applications to see colored test results. +Testing Generated Code +---------------------- + +Some tests generate code on the fly and verify that it matches the expected +output stored in a file. To regenerate those files, run the tests with the +environment variable ``TEST_GENERATE_FIXTURES`` set to ``1``: + +.. code-block:: terminal + + $ TEST_GENERATE_FIXTURES=1 php ./phpunit src/Symfony/Component/Config/Tests/Builder/GeneratedConfigTest.php + .. _`install Composer`: https://getcomposer.org/download/ .. _Cmder: https://cmder.app/ .. _ConEmu: https://conemu.github.io/ diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 3318df50841..86f43b233c4 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -243,39 +243,39 @@ If you are documenting a brand new feature, a change or a deprecation that's been made in Symfony, you should precede your description of the change with the corresponding directive and a short description: -For a new feature or a behavior change use the ``.. versionadded:: 7.x`` +For a new feature or a behavior change use the ``.. versionadded:: 8.x`` directive: .. code-block:: rst - .. versionadded:: 7.2 + .. versionadded:: 8.2 - ... ... ... was introduced in Symfony 7.2. + ... ... ... was introduced in Symfony 8.2. If you are documenting a behavior change, it may be helpful to *briefly* describe how the behavior has changed: .. code-block:: rst - .. versionadded:: 7.2 + .. versionadded:: 8.2 - ... ... ... was introduced in Symfony 7.2. Prior to this, + ... ... ... was introduced in Symfony 8.2. Prior to this, ... ... ... ... ... ... ... ... . -For a deprecation use the ``.. deprecated:: 7.x`` directive: +For a deprecation use the ``.. deprecated:: 8.x`` directive: .. code-block:: rst - .. deprecated:: 7.2 + .. deprecated:: 8.2 - ... ... ... was deprecated in Symfony 7.2. + ... ... ... was deprecated in Symfony 8.2. -Whenever a new major version of Symfony is released (e.g. 8.0, 9.0, etc), a new +Whenever a new major version of Symfony is released (e.g. 9.0, 10.0, etc), a new branch of the documentation is created from the ``x.4`` branch of the previous major version. At this point, all the ``versionadded`` and ``deprecated`` tags for Symfony versions that have a lower major version will be removed. For -example, if Symfony 8.0 were released today, 7.0 to 7.4 ``versionadded`` and -``deprecated`` tags would be removed from the new ``8.0`` branch. +example, if Symfony 9.0 were released today, 8.0 to 8.4 ``versionadded`` and +``deprecated`` tags would be removed from the new ``9.0`` branch. .. _`reStructuredText`: https://docutils.sourceforge.io/rst.html .. _`Docs Builder`: https://github.com/symfony-tools/docs-builder diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 2d4870d221e..7fddcd43981 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -88,8 +88,8 @@ Configuration examples should show all supported formats using :ref:`configuration blocks `. The supported formats (and their orders) are: -* **Configuration** (including services): YAML, XML, PHP -* **Routing**: Attributes, YAML, XML, PHP +* **Configuration** (including services): YAML, PHP +* **Routing**: Attributes, YAML, PHP * **Validation**: Attributes, YAML, XML, PHP * **Doctrine Mapping**: Attributes, YAML, XML, PHP * **Translation**: XML, YAML, PHP diff --git a/controller.rst b/controller.rst index a3b14416f31..e515cae15de 100644 --- a/controller.rst +++ b/controller.rst @@ -373,10 +373,6 @@ The ``MapQueryParameter`` attribute supports the following argument types: * ``string`` * Objects that extend :class:`Symfony\\Component\\Uid\\AbstractUid` -.. versionadded:: 7.3 - - Support for ``AbstractUid`` objects was introduced in Symfony 7.3. - ``#[MapQueryParameter]`` can take an optional argument called ``filter``. You can use the `Validate Filters`_ constants defined in PHP:: @@ -473,10 +469,6 @@ set the ``key`` option in the ``#[MapQueryString]`` attribute:: // ... } -.. versionadded:: 7.3 - - The ``key`` option of ``#[MapQueryString]`` was introduced in Symfony 7.3. - If you need a valid DTO even when the request query string is empty, set a default value for your controller arguments:: @@ -618,10 +610,6 @@ using the ``type`` option of the attribute:: // ... } -.. versionadded:: 7.1 - - The ``type`` option of ``#[MapRequestPayload]`` was introduced in Symfony 7.1. - .. _controller_map-uploaded-file: Mapping Uploaded Files @@ -718,10 +706,6 @@ there are constraint violations: )] UploadedFile $document -.. versionadded:: 7.1 - - The ``#[MapUploadedFile]`` attribute was introduced in Symfony 7.1. - Managing the Session -------------------- @@ -951,6 +935,75 @@ This way, browsers can start downloading the assets immediately; like the ``sendEarlyHints()`` method also returns the ``Response`` object, which you must use to create the full response sent from the controller action. +Decoupling Controllers from Symfony +----------------------------------- + +Extending the :ref:`AbstractController base class ` +simplifies controller development and is **recommended for most applications**. +However, some advanced users prefer to fully decouple your controllers from Symfony +(for example, to improve testability or to follow a more framework-agnostic design) +Symfony provides tools to help you do that. + +To decouple controllers, Symfony exposes all the helpers from ``AbstractController`` +through another class called :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\ControllerHelper`, +where each helper is available as a public method:: + + use Symfony\Bundle\FrameworkBundle\Controller\ControllerHelper; + use Symfony\Component\DependencyInjection\Attribute\AutowireMethodOf; + use Symfony\Component\HttpFoundation\Response; + + class MyController + { + public function __construct( + #[AutowireMethodOf(ControllerHelper::class)] + private \Closure $render, + #[AutowireMethodOf(ControllerHelper::class)] + private \Closure $redirectToRoute, + ) { + } + + public function showProduct(int $id): Response + { + if (!$id) { + return ($this->redirectToRoute)('product_list'); + } + + return ($this->render)('product/show.html.twig', ['product_id' => $id]); + } + } + +You can inject the entire ``ControllerHelper`` class if you prefer, but using the +:ref:`AutowireMethodOf ` attribute as in the previous example, +lets you inject only the exact helpers you need, making your code more efficient. + +Since ``#[AutowireMethodOf]`` also works with interfaces, you can define interfaces +for these helper methods:: + + interface RenderInterface + { + // this is the signature of the render() helper + public function __invoke(string $view, array $parameters = [], ?Response $response = null): Response; + } + +Then, update your controller to use the interface instead of a closure:: + + use Symfony\Bundle\FrameworkBundle\Controller\ControllerHelper; + use Symfony\Component\DependencyInjection\Attribute\AutowireMethodOf; + + class MyController + { + public function __construct( + #[AutowireMethodOf(ControllerHelper::class)] + private RenderInterface $render, + ) { + } + + // ... + } + +Using interfaces like in the previous example provides full static analysis and +autocompletion benefits with no extra boilerplate code. + Final Thoughts -------------- diff --git a/controller/error_pages.rst b/controller/error_pages.rst index 06087837437..7fb7043de82 100644 --- a/controller/error_pages.rst +++ b/controller/error_pages.rst @@ -158,20 +158,6 @@ automatically when installing ``symfony/framework-bundle``): type: php prefix: /_error - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/routes/framework.php @@ -192,11 +178,6 @@ need to replace ``http://localhost/`` by the host used in your local setup): * ``http://localhost/_error/{statusCode}`` for HTML * ``http://localhost/_error/{statusCode}.{format}`` for any other format -.. versionadded:: 7.3 - - The ``errors.php`` file was introduced in Symfony 7.3. - Previously, you had to import ``errors.xml`` - .. _overriding-non-html-error-output: Overriding Error output for non-HTML formats @@ -261,21 +242,6 @@ configuration option to point to it: framework: error_controller: App\Controller\ErrorController::show - .. code-block:: xml - - - - - - - App\Controller\ErrorController::show - - - - .. code-block:: php // config/packages/framework.php @@ -346,10 +312,6 @@ time and again, you can have just one (or several) listeners deal with them. Dumping Error Pages as Static HTML Files ---------------------------------------- -.. versionadded:: 7.3 - - The feature to dump error pages into static HTML files was introduced in Symfony 7.3. - If an error occurs before reaching your Symfony application, web servers display their own default error pages instead of your custom ones. Dumping your application's error pages to static HTML ensures users always see your defined pages and improves diff --git a/controller/service.rst b/controller/service.rst index 8f843e9d4ef..54a742d7cd4 100644 --- a/controller/service.rst +++ b/controller/service.rst @@ -25,11 +25,6 @@ its methods. This is the simplest and recommended way to register controllers as services when not extending the base controller class. -.. versionadded:: 7.3 - - The feature to register controllers as services when using the ``#[Route]`` - attribute was introduced in Symfony 7.3. - Using the ``#[AsController]`` Attribute --------------------------------------- @@ -148,19 +143,6 @@ a service like: ``App\Controller\HelloController::index``: controller: App\Controller\HelloController::index methods: GET - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/routes.php @@ -209,21 +191,6 @@ which is a common practice when following the `ADR pattern`_ path: /hello/{name} controller: App\Controller\HelloController - .. code-block:: xml - - - - - - - App\Controller\HelloController - - - - .. code-block:: php use App\Controller\HelloController; diff --git a/controller/upload_file.rst b/controller/upload_file.rst index 793cd26dd65..88b8855d4d8 100644 --- a/controller/upload_file.rst +++ b/controller/upload_file.rst @@ -196,10 +196,6 @@ There are some important things to consider in the code of the above controller: the **webkitRelativePath** as provided by the browser. Otherwise this value will be identical to ``getClientOriginalName()``. -.. versionadded:: 7.1 - - The ``getClientOriginalPath()`` method was introduced in Symfony 7.1. - You can use the following code to link to the PDF brochure of a product: .. code-block:: html+twig @@ -289,21 +285,6 @@ Then, define a service for this class: arguments: $targetDirectory: '%brochures_directory%' - .. code-block:: xml - - - - - - - - %brochures_directory% - - - .. code-block:: php // config/services.php diff --git a/controller/value_resolver.rst b/controller/value_resolver.rst index 835edcfbff9..35f199826a9 100644 --- a/controller/value_resolver.rst +++ b/controller/value_resolver.rst @@ -362,27 +362,6 @@ but you can set it yourself to change its ``priority`` or ``name`` attributes. name: booking_id priority: 150 - .. code-block:: xml - - - - - - - - - - - - controller.argument_value_resolver - - - - - .. code-block:: php // config/services.php diff --git a/create_framework/routing.rst b/create_framework/routing.rst index 71e3a8250e1..1632f2628b3 100644 --- a/create_framework/routing.rst +++ b/create_framework/routing.rst @@ -74,7 +74,7 @@ of default values for route attributes (``['name' => 'World']``). Read the :doc:`Routing documentation ` to learn more about its many features like URL generation, attribute requirements, HTTP - method enforcement, loaders for YAML or XML files, dumpers to PHP or + method enforcement, loaders for YAML or PHP files, dumpers to PHP or Apache rewrite rules for enhanced performance and much more. Based on the information stored in the ``RouteCollection`` instance, a diff --git a/deployment/proxies.rst b/deployment/proxies.rst index 4dad6f95fb1..016ef136412 100644 --- a/deployment/proxies.rst +++ b/deployment/proxies.rst @@ -44,36 +44,6 @@ using the following configuration options: # or, if your proxy instead uses the "Forwarded" header trusted_headers: ['forwarded'] - .. code-block:: xml - - - - - - - - 192.0.0.1,10.0.0.0/8 - - private_ranges - - - x-forwarded-for - x-forwarded-host - x-forwarded-proto - x-forwarded-port - x-forwarded-prefix - - - forwarded - - - .. code-block:: php // config/packages/framework.php @@ -92,16 +62,6 @@ using the following configuration options: ; }; -.. versionadded:: 7.1 - - ``private_ranges`` as a shortcut for private IP address ranges for the - ``trusted_proxies`` option was introduced in Symfony 7.1. - -.. versionadded:: 7.2 - - Support for the ``SYMFONY_TRUSTED_PROXIES`` and ``SYMFONY_TRUSTED_HEADERS`` - environment variables was introduced in Symfony 7.2. - .. danger:: Enabling the ``Request::HEADER_X_FORWARDED_HOST`` option exposes the @@ -159,10 +119,6 @@ In this case, you'll need to - *very carefully* - trust *all* proxies. # runtime by the IpUtils::PRIVATE_SUBNETS constant # trusted_proxies: '127.0.0.1,PRIVATE_SUBNETS' -.. versionadded:: 7.2 - - The support for the ``'PRIVATE_SUBNETS'`` string was introduced in Symfony 7.2. - That's it! It's critical that you prevent traffic from all non-trusted sources. If you allow outside traffic, they could "spoof" their true IP address and other information. diff --git a/doctrine.rst b/doctrine.rst index 6a1438322fa..52bfbd353d5 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -712,10 +712,6 @@ The ``{slug:product}`` syntax maps the route parameter named ``slug`` to the controller argument named ``$product``. It also hints the resolver to look up the corresponding ``Product`` object from the database using the slug. -.. versionadded:: 7.1 - - Route parameter mapping was introduced in Symfony 7.1. - You can also configure the mapping explicitly for any controller argument using the ``MapEntity`` attribute. You can even control the behavior of the ``EntityValueResolver`` by using the `MapEntity options`_ :: @@ -768,10 +764,6 @@ In that case, update the type of your controller argument:: ): Response { } -.. versionadded:: 7.1 - - The mapping of the lists of entities was introduced in Symfony 7.1. - This can also be used to help resolve multiple arguments:: #[Route('/product/{id}/comments/{comment_id}')] @@ -819,11 +811,6 @@ resolved automatically:: // ... } -.. versionadded:: 7.3 - - Support for target entity resolution in the ``EntityValueResolver`` was - introduced Symfony 7.3 - MapEntity Options ~~~~~~~~~~~~~~~~~ @@ -888,10 +875,6 @@ control behavior: ): Response { } -.. versionadded:: 7.1 - - The ``message`` option was introduced in Symfony 7.1. - Updating an Object ------------------ diff --git a/doctrine/custom_dql_functions.rst b/doctrine/custom_dql_functions.rst index e5b21819f58..dfb13d5ca0f 100644 --- a/doctrine/custom_dql_functions.rst +++ b/doctrine/custom_dql_functions.rst @@ -23,30 +23,6 @@ In Symfony, you can register your custom DQL functions as follows: datetime_functions: test_datetime: App\DQL\DatetimeFunction - .. code-block:: xml - - - - - - - - - App\DQL\StringFunction - App\DQL\SecondStringFunction - App\DQL\NumericFunction - App\DQL\DatetimeFunction - - - - - .. code-block:: php // config/packages/doctrine.php @@ -89,34 +65,6 @@ In Symfony, you can register your custom DQL functions as follows: datetime_functions: test_datetime: App\DQL\DatetimeFunction - .. code-block:: xml - - - - - - - - - - - - - - App\DQL\DatetimeFunction - - - - - - - .. code-block:: php // config/packages/doctrine.php diff --git a/doctrine/dbal.rst b/doctrine/dbal.rst index 4f47b61eb61..fd6f748401d 100644 --- a/doctrine/dbal.rst +++ b/doctrine/dbal.rst @@ -78,25 +78,6 @@ mapping types, read Doctrine's `Custom Mapping Types`_ section of their document custom_first: App\Type\CustomFirst custom_second: App\Type\CustomSecond - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/doctrine.php @@ -130,24 +111,6 @@ mapping type: mapping_types: enum: string - .. code-block:: xml - - - - - - - string - - - - .. code-block:: php // config/packages/doctrine.php diff --git a/doctrine/events.rst b/doctrine/events.rst index accf424083a..0cd4803ccc7 100644 --- a/doctrine/events.rst +++ b/doctrine/events.rst @@ -177,39 +177,6 @@ with the ``doctrine.orm.entity_listener`` tag as follows: # configure a custom method name with the 'method' option # method: 'checkUserChanges' - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -324,30 +291,6 @@ listener in the Symfony application by creating a new service for it and # you can also restrict listeners to a specific Doctrine connection connection: 'default' - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/doctrine/multiple_entity_managers.rst b/doctrine/multiple_entity_managers.rst index 1a56c55ddad..3d295b9939f 100644 --- a/doctrine/multiple_entity_managers.rst +++ b/doctrine/multiple_entity_managers.rst @@ -55,53 +55,6 @@ The following configuration code shows how you can configure two entity managers prefix: 'App\Entity\Customer' alias: Customer - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/doctrine.php diff --git a/doctrine/resolve_target_entity.rst b/doctrine/resolve_target_entity.rst index 1495f475628..1e281f52b62 100644 --- a/doctrine/resolve_target_entity.rst +++ b/doctrine/resolve_target_entity.rst @@ -15,11 +15,6 @@ This makes it possible to define relationships between entities without creating hard dependencies. This feature also works with the ``EntityValueResolver`` :ref:`as explained in the main Doctrine article `. -.. versionadded:: 7.3 - - Support for target entity resolution in the ``EntityValueResolver`` was - introduced Symfony 7.3 - Background ---------- @@ -107,26 +102,6 @@ how to replace the interface with the concrete class: resolve_target_entities: App\Model\InvoiceSubjectInterface: App\Entity\Customer - .. code-block:: xml - - - - - - - - - App\Entity\Customer - - - - .. code-block:: php // config/packages/doctrine.php diff --git a/emoji.rst b/emoji.rst index 69f2a850217..2755ded8b1e 100644 --- a/emoji.rst +++ b/emoji.rst @@ -1,10 +1,6 @@ Working with Emojis =================== -.. versionadded:: 7.1 - - The emoji component was introduced in Symfony 7.1. - Symfony provides several utilities to work with emoji characters and sequences from the `Unicode CLDR dataset`_. They are available via the Emoji component, which you must first install in your application: diff --git a/event_dispatcher.rst b/event_dispatcher.rst index 13a3bbb0297..0a47922ffeb 100644 --- a/event_dispatcher.rst +++ b/event_dispatcher.rst @@ -71,22 +71,6 @@ notify Symfony that it is an event listener by using a special "tag": App\EventListener\ExceptionListener: tags: [kernel.event_listener] - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -210,6 +194,12 @@ can also be applied to methods directly:: // ... } + #[AsEventListener] + public function onMultipleCustomEvent(CustomEvent|AnotherCustomEvent $event): void + { + // ... + } + #[AsEventListener(event: 'foo', priority: 42)] public function onFoo(): void { @@ -477,23 +467,6 @@ First, define some token configuration as parameters: client1: pass1 client2: pass2 - .. code-block:: xml - - - - - - - - pass1 - pass2 - - - - .. code-block:: php // config/services.php diff --git a/form/bootstrap4.rst b/form/bootstrap4.rst index eef016aa58a..620a3b78ed8 100644 --- a/form/bootstrap4.rst +++ b/form/bootstrap4.rst @@ -34,24 +34,6 @@ configuration: twig: form_themes: ['bootstrap_4_layout.html.twig'] - .. code-block:: xml - - - - - - - bootstrap_4_layout.html.twig - - - - .. code-block:: php // config/packages/twig.php diff --git a/form/bootstrap5.rst b/form/bootstrap5.rst index db098a1ba09..deb21c23fe2 100644 --- a/form/bootstrap5.rst +++ b/form/bootstrap5.rst @@ -34,24 +34,6 @@ configuration: twig: form_themes: ['bootstrap_5_layout.html.twig'] - .. code-block:: xml - - - - - - - bootstrap_5_layout.html.twig - - - - .. code-block:: php // config/packages/twig.php diff --git a/form/create_custom_field_type.rst b/form/create_custom_field_type.rst index 0d92a967fa0..3fb0ed7edee 100644 --- a/form/create_custom_field_type.rst +++ b/form/create_custom_field_type.rst @@ -376,24 +376,6 @@ add this new template at the end of the list (each theme overrides all the previ - '...' - 'form/custom_types.html.twig' - .. code-block:: xml - - - - - - - ... - form/custom_types.html.twig - - - .. code-block:: php // config/packages/twig.php diff --git a/form/form_customization.rst b/form/form_customization.rst index dc09aefe77d..2b42343a7fd 100644 --- a/form/form_customization.rst +++ b/form/form_customization.rst @@ -131,10 +131,6 @@ fields, so you no longer have to deal with form themes: {% endfor %} -.. versionadded:: 7.3 - - The ``field_id()`` helper was introduced in Symfony 7.3. - Form Rendering Variables ------------------------ diff --git a/form/form_themes.rst b/form/form_themes.rst index 8b82982edaa..58aa4b7251f 100644 --- a/form/form_themes.rst +++ b/form/form_themes.rst @@ -67,23 +67,6 @@ want to use another theme for all the forms of your app, configure it in the form_themes: ['bootstrap_5_horizontal_layout.html.twig'] # ... - .. code-block:: xml - - - - - - - bootstrap_5_horizontal_layout.html.twig - - - - .. code-block:: php // config/packages/twig.php @@ -494,23 +477,6 @@ you want to apply the theme globally to all forms, define the form_themes: ['form/my_theme.html.twig'] # ... - .. code-block:: xml - - - - - - - form/my_theme.html.twig - - - - .. code-block:: php // config/packages/twig.php diff --git a/form/type_guesser.rst b/form/type_guesser.rst index 106eb4e7742..59fdfffe37f 100644 --- a/form/type_guesser.rst +++ b/form/type_guesser.rst @@ -191,22 +191,6 @@ and tag it with ``form.type_guesser``: App\Form\TypeGuesser\PhpDocTypeGuesser: tags: [form.type_guesser] - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/forms.rst b/forms.rst index 83065d7524b..95ca6cccb09 100644 --- a/forms.rst +++ b/forms.rst @@ -339,24 +339,6 @@ can set this option to generate forms compatible with the Bootstrap 5 CSS framew twig: form_themes: ['bootstrap_5_layout.html.twig'] - .. code-block:: xml - - - - - - - bootstrap_5_layout.html.twig - - - - .. code-block:: php // config/packages/twig.php @@ -513,7 +495,8 @@ object. - NotBlank: ~ dueDate: - NotBlank: ~ - - Type: \DateTimeInterface + - Type: + type: \DateTimeInterface .. code-block:: xml @@ -530,7 +513,9 @@ object. - \DateTimeInterface + + + @@ -776,6 +761,10 @@ to the ``form()`` or the ``form_start()`` helper functions: ``DELETE`` request. The :ref:`http_method_override ` option must be enabled for this to work. + For security, you can restrict which HTTP methods can be overridden using the + :ref:`allowed_http_method_override ` + option. + Changing the Form Name ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/frontend/asset_mapper.rst b/frontend/asset_mapper.rst index 912f645bf6a..f887675b5a7 100644 --- a/frontend/asset_mapper.rst +++ b/frontend/asset_mapper.rst @@ -157,10 +157,6 @@ The ``debug:asset-map`` command provides several options to filter results: # you can also combine all filters (e.g. find bold web fonts in your own asset dirs) $ php bin/console debug:asset-map bold --no-vendor --ext=woff2 -.. versionadded:: 7.2 - - The options to filter ``debug:asset-map`` results were introduced in Symfony 7.2. - .. _importmaps-javascript: Importmaps & Writing JavaScript @@ -220,10 +216,6 @@ to add any `npm package`_: Add the ``--dry-run`` option to simulate package installation without actually making any changes (e.g. ``php bin/console importmap:require bootstrap --dry-run``) - .. versionadded:: 7.3 - - The ``--dry-run`` option was introduced in Symfony 7.3. - This adds the ``bootstrap`` package to your ``importmap.php`` file:: // importmap.php @@ -767,10 +759,6 @@ Symfony will add a ``Link`` header in the response to preload the CSS files. Pre-Compressing Assets ---------------------- -.. versionadded:: 7.3 - - Support for pre-compressing assets was introduced in Symfony 7.3. - Although most web servers (Caddy, Nginx, Apache, FrankenPHP) and services like Cloudflare provide asset compression features, AssetMapper also allows you to compress all your assets before serving them. diff --git a/frontend/custom_version_strategy.rst b/frontend/custom_version_strategy.rst index 1a0dca3e393..8a20c6acfaa 100644 --- a/frontend/custom_version_strategy.rst +++ b/frontend/custom_version_strategy.rst @@ -105,23 +105,6 @@ After creating the strategy PHP class, register it as a Symfony service. - "%kernel.project_dir%/busters.json" - "%%s?version=%%s" - .. code-block:: xml - - - - - - - %kernel.project_dir%/busters.json - %%s?version=%%s - - - - .. code-block:: php // config/services.php @@ -155,21 +138,6 @@ the :ref:`version_strategy ` option: assets: version_strategy: 'App\Asset\VersionStrategy\GulpBusterVersionStrategy' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/html_sanitizer.rst b/html_sanitizer.rst index 8e641c3672d..99eaa0b75c1 100644 --- a/html_sanitizer.rst +++ b/html_sanitizer.rst @@ -168,26 +168,6 @@ You can do this by defining a new HTML sanitizer in the configuration: block_elements: - h1 - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -281,30 +261,6 @@ Safe elements allow_safe_elements: true allow_static_elements: true - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -358,45 +314,6 @@ attributes from the `W3C Standard Proposal`_ are allowed. # allow the
element with no attributes div: [] - .. code-block:: xml - - - - - - - - - - - - class - data-attr - - - - - src - - - - - * - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -464,28 +381,6 @@ This can also be used to remove elements from the allow list. # remove
and its children drop_elements: ['figure'] - .. code-block:: xml - - - - - - - - - div - - - figure - - - - .. code-block:: php // config/packages/framework.php @@ -538,32 +433,6 @@ on all elements allowed *before this setting*. # allow "data-attr" on all elements currently allowed data-attr: '*' - .. code-block:: xml - - - - - - - - - - iframe - - - - - * - - - - - .. code-block:: php // config/packages/framework.php @@ -619,37 +488,6 @@ This option allows you to disallow attributes that were allowed before. # disallows "style' on any allowed element style: '*' - .. code-block:: xml - - - - - - - - - - * - - - - - section - - - - - * - - - - - .. code-block:: php // config/packages/framework.php @@ -707,26 +545,6 @@ element (even if the original one didn't contain a ``rel`` attribute): a: rel: noopener noreferrer - .. code-block:: xml - - - - - - - - - noopener noreferrer - - - - - .. code-block:: php // config/packages/framework.php @@ -785,41 +603,6 @@ URLs of ```` elements: # whether to allow relative links (i.e. URLs without scheme and host) allow_relative_links: true - .. code-block:: xml - - - - - - - - - - - http - https - mailto - - - symfony.com - - - - .. code-block:: php // config/packages/framework.php @@ -905,41 +688,6 @@ the HTML sanitizer: ``src``, ``href``, ``lowsrc``, ``background`` and ``ping``. # whether to allow relative URLs (i.e. URLs without scheme and host) allow_relative_medias: true - .. code-block:: xml - - - - - - - - - - - http - https - mailto - - - symfony.com - - - - .. code-block:: php // config/packages/framework.php @@ -1012,27 +760,6 @@ increase or decrease this limit: # inputs longer (in characters) than this value will be truncated max_input_length: 30000 # default: 20000 - .. code-block:: xml - - - - - - - - - - 20000 - - - - - .. code-block:: php // config/packages/framework.php @@ -1088,27 +815,6 @@ to enable it for an HTML sanitizer: #without_attribute_sanitizers: # - App\Sanitizer\CustomAttributeSanitizer - .. code-block:: xml - - - - - - - - App\Sanitizer\CustomAttributeSanitizer - - - Symfony\Component\HtmlSanitizer\Visitor\AttributeSanitizer\UrlAttributeSanitizer - - - - .. code-block:: php // config/packages/framework.php diff --git a/http_cache.rst b/http_cache.rst index 02bcd2d9cd9..a1ff144411d 100644 --- a/http_cache.rst +++ b/http_cache.rst @@ -79,26 +79,6 @@ Use the ``framework.http_cache`` option to enable the proxy for the framework: http_cache: true - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/http_cache/cache_invalidation.rst b/http_cache/cache_invalidation.rst index 394c79aed42..712023c18e9 100644 --- a/http_cache/cache_invalidation.rst +++ b/http_cache/cache_invalidation.rst @@ -114,24 +114,6 @@ Then, register the class as a service that :doc:`decorates - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/http_cache/esi.rst b/http_cache/esi.rst index 588cad424cd..28cfa411d5c 100644 --- a/http_cache/esi.rst +++ b/http_cache/esi.rst @@ -63,24 +63,6 @@ First, to use ESI, be sure to enable it in your application configuration: # ... esi: true - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -225,24 +207,6 @@ that must be enabled in your configuration: # ... fragments: { path: /_fragment } - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/http_cache/ssi.rst b/http_cache/ssi.rst index 8b280bf75a6..feb205d4e03 100644 --- a/http_cache/ssi.rst +++ b/http_cache/ssi.rst @@ -52,23 +52,6 @@ First, to use SSI, be sure to enable it in your application configuration: framework: ssi: { enabled: true } - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/http_client.rst b/http_client.rst index a1c8f09bc1d..e571c41b4bf 100644 --- a/http_client.rst +++ b/http_client.rst @@ -99,24 +99,6 @@ You can configure the global options using the ``default_options`` option: default_options: max_redirects: 7 - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -157,11 +139,6 @@ brings most of the available options with type-hinted getters and setters:: ->toArray() ); -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\HttpClient\\HttpOptions::setHeader` - method was introduced in Symfony 7.1. - Some options are described in this guide: * `Authentication`_ @@ -189,24 +166,6 @@ This option cannot be overridden per request: max_host_connections: 10 # ... - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -257,39 +216,6 @@ autoconfigure the HTTP client based on the requested URL: Authorization: 'token %env(GITHUB_API_TOKEN)%' # ... - .. code-block:: xml - - - - - - - - - - application/vnd.github.v3+json - token %env(GITHUB_API_TOKEN)% - - - - - application/vnd.github.v3+json - token %env(GITHUB_API_TOKEN)% - - - - - .. code-block:: php // config/packages/framework.php @@ -426,33 +352,6 @@ each request (which overrides any global authentication): # Microsoft NTLM authentication auth_ntlm: 'the-username:the-password' - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -540,26 +439,6 @@ Use the ``headers`` option to define the default headers added to all requests: headers: 'User-Agent': 'My Fancy App' - .. code-block:: xml - - - - - - - - - My Fancy App - - - - - .. code-block:: php // config/packages/framework.php @@ -740,6 +619,8 @@ making a request. Use the ``max_redirects`` setting to configure this behavior 'max_redirects' => 0, ]); +.. _http-client-retry-failed-requests: + Retry Failed Requests ~~~~~~~~~~~~~~~~~~~~~ @@ -955,26 +836,6 @@ of your application: vars: - secret: 'secret-token' - .. code-block:: xml - - - - - - - - - secret-token - - - - - .. code-block:: php // config/packages/framework.php @@ -1005,9 +866,13 @@ Enabling cURL Support ~~~~~~~~~~~~~~~~~~~~~ This component can make HTTP requests using native PHP streams and the -``amphp/http-client`` and cURL libraries. Although they are interchangeable and -provide the same features, including concurrent requests, HTTP/2 is only supported -when using cURL or ``amphp/http-client``. +``amphp/http-client`` (version 5.3.2 or higher) and cURL libraries. Although they +are interchangeable and provide the same features, including concurrent requests, +HTTP/2 is only supported when using cURL or ``amphp/http-client``. + +.. versionadded:: 8.0 + + Symfony started requiring ``amphp/http-client`` version 5.3.2 or higher in Symfony 8.0. .. note:: @@ -1107,24 +972,6 @@ To force HTTP/2 for ``http`` URLs, you need to enable it explicitly via the default_options: http_version: '2.0' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1486,41 +1333,23 @@ in the foreach loop:: } } +.. _http-client_caching: + Caching Requests and Responses ------------------------------ This component provides a :class:`Symfony\\Component\\HttpClient\\CachingHttpClient` -decorator that allows caching responses and serving them from the local storage -for next requests. The implementation leverages the -:class:`Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache` class under the hood -so that the :doc:`HttpKernel component ` needs to be -installed in your application:: - - use Symfony\Component\HttpClient\CachingHttpClient; - use Symfony\Component\HttpClient\HttpClient; - use Symfony\Component\HttpKernel\HttpCache\Store; - - $store = new Store('/path/to/cache/storage/'); - $client = HttpClient::create(); - $client = new CachingHttpClient($client, $store); - - // this won't hit the network if the resource is already in the cache - $response = $client->request('GET', 'https://example.com/cacheable-resource'); +decorator that enables caching of HTTP responses and serving them from cache +storage on subsequent requests, as described in `RFC 9111`_. -:class:`Symfony\\Component\\HttpClient\\CachingHttpClient` accepts a third argument -to set the options of the :class:`Symfony\\Component\\HttpKernel\\HttpCache\\HttpCache`. - -Limit the Number of Requests ----------------------------- +Internally, it relies on a :class:`tag aware cache `, +so the :doc:`Cache component ` must be installed in your application. -This component provides a :class:`Symfony\\Component\\HttpClient\\ThrottlingHttpClient` -decorator that allows to limit the number of requests within a certain period, -potentially delaying calls based on the rate limiting policy. +.. tip:: -The implementation leverages the -:class:`Symfony\\Component\\RateLimiter\\LimiterInterface` class under the hood -so the :doc:`Rate Limiter component ` needs to be -installed in your application:: + The caching mechanism is asynchronous. The response must be fully consumed + (for example, by calling ``getContent()`` or using a stream) for it to be + stored in the cache. .. configuration-block:: @@ -1532,14 +1361,14 @@ installed in your application:: scoped_clients: example.client: base_uri: 'https://example.com' - rate_limiter: 'http_example_limiter' + caching: + cache_pool: example_cache_pool - rate_limiter: - # Don't send more than 10 requests in 5 seconds - http_example_limiter: - policy: 'token_bucket' - limit: 10 - rate: { interval: '5 seconds', amount: 10 } + cache: + pools: + example_cache_pool: + adapter: cache.adapter.redis_tag_aware + tags: true .. code-block:: xml @@ -1556,22 +1385,88 @@ installed in your application:: + > + + - - - - - - + + + + .. code-block:: php + + // config/packages/framework.php + use Symfony\Config\FrameworkConfig; + + return static function (FrameworkConfig $framework): void { + $framework->httpClient()->scopedClient('example.client') + ->baseUri('https://example.com') + ->caching() + ->cachePool('example_cache_pool') + // ... + ; + + $framework->cache() + ->pool('example_cache_pool') + ->adapter('cache.adapter.redis_tag_aware') + ->tags(true) + ; + }; + + .. code-block:: php-standalone + + use Symfony\Component\Cache\Adapter\FilesystemTagAwareAdapter; + use Symfony\Component\HttpClient\CachingHttpClient; + use Symfony\Component\HttpClient\HttpClient; + + $cache = new FilesystemTagAwareAdapter(); + + $client = HttpClient::createForBaseUri('https://example.com'); + $cachingClient = new CachingHttpClient($client, $cache); + +.. tip:: + + It is strongly recommended to configure a + :ref:`retry strategy ` to gracefully + handle temporary cache inconsistencies or validation failures. + +Limit the Number of Requests +---------------------------- + +This component provides a :class:`Symfony\\Component\\HttpClient\\ThrottlingHttpClient` +decorator that allows to limit the number of requests within a certain period, +potentially delaying calls based on the rate limiting policy. + +The implementation leverages the +:class:`Symfony\\Component\\RateLimiter\\LimiterInterface` class under the hood +so the :doc:`Rate Limiter component ` needs to be +installed in your application:: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/framework.yaml + framework: + http_client: + scoped_clients: + example.client: + base_uri: 'https://example.com' + rate_limiter: 'http_example_limiter' + + rate_limiter: + # Don't send more than 10 requests in 5 seconds + http_example_limiter: + policy: 'token_bucket' + limit: 10 + rate: { interval: '5 seconds', amount: 10 } + .. code-block:: php // config/packages/framework.php @@ -1613,11 +1508,6 @@ installed in your application:: $client = HttpClient::createForBaseUri('https://example.com'); $throttlingClient = new ThrottlingHttpClient($client, $limiter); -.. versionadded:: 7.1 - - The :class:`Symfony\\Component\\HttpClient\\ThrottlingHttpClient` was - introduced in Symfony 7.1. - Consuming Server-Sent Events ---------------------------- @@ -1789,6 +1679,24 @@ You can also pass a set of default options to your client thanks to the // ... +.. _auto-upgrade-http-version: + +You can use the ``auto_upgrade_http_version`` option to control whether the HTTP +protocol version is automatically upgraded:: + + $client = (new Psr18Client()) + ->withOptions([ + // set to false to always use the HTTP version defined in your request; + // set to true to allow the server to upgrade the HTTP version in its response + 'auto_upgrade_http_version' => false + // ... + ]); + +.. note:: + + The ``auto_upgrade_http_version`` option is ignored for HTTP/1.0 requests, + which always keep that protocol version. + HTTPlug ~~~~~~~ @@ -1890,6 +1798,10 @@ You can also pass a set of default options to your client thanks to the // ... + +See the :ref:`auto_upgrade_http_version ` option for +details about how the HTTP protocol version selection works. + Native PHP Streams ~~~~~~~~~~~~~~~~~~ @@ -2066,11 +1978,6 @@ snapshots in files:: $response = MockResponse::fromFile('tests/fixtures/response.xml'); -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\HttpClient\\Response\\MockResponse::fromFile` - method was introduced in Symfony 7.1. - Another way of using :class:`Symfony\\Component\\HttpClient\\MockHttpClient` is to pass a callback that generates the responses dynamically when it's called:: @@ -2185,35 +2092,6 @@ Then configure Symfony to use your callback: http_client: mock_response_factory: App\Tests\MockClientCallback - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -2253,11 +2131,6 @@ directly from a file:: $response = JsonMockResponse::fromFile('tests/fixtures/response.json'); -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\HttpClient\\Response\\JsonMockResponse::fromFile` - method was introduced in Symfony 7.1. - Testing Request Data ~~~~~~~~~~~~~~~~~~~~ @@ -2494,5 +2367,6 @@ body:: .. _`idempotent method`: https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods .. _`SSRF`: https://portswigger.net/web-security/ssrf .. _`RFC 6570`: https://www.rfc-editor.org/rfc/rfc6570 +.. _`RFC 9111`: https://www.rfc-editor.org/rfc/rfc9111 .. _`HAR`: https://w3c.github.io/web-performance/specs/HAR/Overview.html .. _`the Cookie HTTP request header`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cookie diff --git a/lock.rst b/lock.rst index 5bb072cdf73..941ee7b0b6e 100644 --- a/lock.rst +++ b/lock.rst @@ -61,6 +61,7 @@ this behavior by using the ``lock`` key like: lock: 'sqlsrv:server=127.0.0.1;Database=app' lock: 'oci:host=127.0.0.1;dbname=app' lock: 'mongodb://127.0.0.1/app?collection=lock' + lock: 'dynamodb://127.0.0.1/lock' lock: '%env(LOCK_DSN)%' # using an existing service lock: 'snc_redis.default' @@ -70,68 +71,6 @@ this behavior by using the ``lock`` key like: invoice: ['semaphore', 'redis://r2.docker'] report: 'semaphore' - .. code-block:: xml - - - - - - - - flock - - flock:///path/to/file - - semaphore - - memcached://m1.docker - - memcached://m1.docker - memcached://m2.docker - - redis://r1.docker - - redis://r1.docker - redis://r2.docker - - zookeeper://z1.docker - - zookeeper://z1.docker,z2.docker - - zookeeper://localhost01,localhost02:2181 - - sqlite:///%kernel.project_dir%/var/lock.db - - mysql:host=127.0.0.1;dbname=app - - pgsql:host=127.0.0.1;dbname=app - - pgsql+advisory:host=127.0.0.1;dbname=app - - sqlsrv:server=127.0.0.1;Database=app - - oci:host=127.0.0.1;dbname=app - - mongodb://127.0.0.1/app?collection=lock - - %env(LOCK_DSN)% - - - snc_redis.default - - - semaphore - redis://r2.docker - semaphore - - - - .. code-block:: php // config/packages/lock.php @@ -157,6 +96,7 @@ this behavior by using the ``lock`` key like: ->resource('default', ['sqlsrv:server=127.0.0.1;Database=app']) ->resource('default', ['oci:host=127.0.0.1;dbname=app']) ->resource('default', ['mongodb://127.0.0.1/app?collection=lock']) + ->resource('default', ['dynamodb://127.0.0.1/lock']) ->resource('default', [env('LOCK_DSN')]) // using an existing service ->resource('default', ['snc_redis.default']) @@ -167,10 +107,6 @@ this behavior by using the ``lock`` key like: ; }; -.. versionadded:: 7.2 - - The option to use an existing service as the lock/semaphore was introduced in Symfony 7.2. - Locking a Resource ------------------ @@ -259,26 +195,6 @@ provides :ref:`named lock `: invoice: ['semaphore', 'redis://r2.docker'] report: 'semaphore' - .. code-block:: xml - - - - - - - - semaphore - redis://r2.docker - semaphore - - - - .. code-block:: php // config/packages/lock.php @@ -315,7 +231,7 @@ For example, to inject the ``invoice`` package defined earlier:: When :ref:`dealing with multiple implementations of the same type ` the ``#[Target]`` attribute helps you select which one to inject. Symfony creates -a target called ``lock.`` + "lock name" + ``.factory``. +a target with the same name as the lock. For example, to select the ``invoice`` lock defined earlier:: @@ -325,7 +241,7 @@ For example, to select the ``invoice`` lock defined earlier:: class SomeService { public function __construct( - #[Target('lock.invoice.factory')] private LockFactory $lockFactory + #[Target('invoice')] private LockFactory $lockFactory ): void { // ... } diff --git a/logging.rst b/logging.rst index 98a380b82a9..9ab0410bdea 100644 --- a/logging.rst +++ b/logging.rst @@ -133,31 +133,6 @@ to write logs using the :phpfunction:`syslog` function: # log error-level messages and higher level: error - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -199,32 +174,6 @@ which they are defined: type: syslog priority: 10 # called first - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -282,41 +231,6 @@ one of the messages reaches an ``action_level``. Take this example: type: syslog level: error - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -389,30 +303,6 @@ option of your handler to ``rotating_file``: # defaults to zero, which means infinite files max_files: 10 - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -479,5 +369,5 @@ Learn more .. _`Monolog`: https://github.com/Seldaek/monolog .. _`LoggerInterface`: https://github.com/php-fig/log/blob/master/src/LoggerInterface.php .. _`logrotate`: https://github.com/logrotate/logrotate -.. _`Monolog Configuration`: https://github.com/symfony/monolog-bundle/blob/3.x/src/DependencyInjection/Configuration.php +.. _`Monolog Configuration`: https://github.com/symfony/monolog-bundle/blob/4.x/src/DependencyInjection/Configuration.php .. _`STDERR PHP stream`: https://www.php.net/manual/en/features.commandline.io-streams.php diff --git a/logging/channels_handlers.rst b/logging/channels_handlers.rst index 3cac1d01ba5..38b59b93341 100644 --- a/logging/channels_handlers.rst +++ b/logging/channels_handlers.rst @@ -45,36 +45,6 @@ from the ``security`` channel. The following example does that only in the # ... # channels: ['!security'] - .. code-block:: xml - - - - - - - - - security - - - - - - - - - !security - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -141,24 +111,6 @@ You can also configure additional channels without the need to tag your services monolog: channels: ['foo', 'bar', 'foo_bar'] - .. code-block:: xml - - - - - - foo - bar - foo_bar - - - .. code-block:: php // config/packages/monolog.php diff --git a/logging/formatter.rst b/logging/formatter.rst index 6f2bfc7906c..e285fa65a55 100644 --- a/logging/formatter.rst +++ b/logging/formatter.rst @@ -21,28 +21,6 @@ configure your handler to use it: level: debug formatter: 'monolog.formatter.json' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php (and/or config/packages/dev/monolog.php) diff --git a/logging/handlers.rst b/logging/handlers.rst index eb2b1ac2c9c..5ed31f0745d 100644 --- a/logging/handlers.rst +++ b/logging/handlers.rst @@ -28,33 +28,6 @@ To use it, declare it as a service: $bubble: true $elasticsearchVersion: '1.0.0' - .. code-block:: xml - - - - - - - - - - - http://127.0.0.1:9200 - monolog - - Monolog\Level::Debug - true - 1.0.0 - - - - .. code-block:: php // config/services.php @@ -91,27 +64,6 @@ each log, an HTTP request will be made to push the log to Elasticsearch: type: service id: Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -145,32 +97,6 @@ even better performance and fault tolerance, a proper `ELK stack`_ is recommende type: service id: Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php diff --git a/logging/monolog_console.rst b/logging/monolog_console.rst index 4d007abe854..e4f34688bdb 100644 --- a/logging/monolog_console.rst +++ b/logging/monolog_console.rst @@ -92,29 +92,6 @@ The Monolog console handler is enabled by default: # verbosity_levels: # VERBOSITY_NORMAL: NOTICE - .. code-block:: xml - - - - - - - - - - - !event - !doctrine - !console - - - - - .. code-block:: php // config/packages/dev/monolog.php diff --git a/logging/monolog_email.rst b/logging/monolog_email.rst index d52629e0797..a218deb0ffa 100644 --- a/logging/monolog_email.rst +++ b/logging/monolog_email.rst @@ -41,57 +41,6 @@ it is broken down. formatter: monolog.formatter.html content_type: text/html - .. code-block:: xml - - - - - - - - - - - - error@example.com - - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -161,16 +110,6 @@ You can adjust the time period using the ``time`` option: time: 10 handler: symfony_mailer - .. code-block:: xml - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -225,61 +164,6 @@ get logged on the server as well as the emails being sent: formatter: monolog.formatter.html content_type: text/html - .. code-block:: xml - - - - - - - - - - - - - - - error@example.com - - - - - - - .. code-block:: php // config/packages/prod/monolog.php diff --git a/logging/monolog_exclude_http_codes.rst b/logging/monolog_exclude_http_codes.rst index ee9fb16c01c..d2d2a0afb52 100644 --- a/logging/monolog_exclude_http_codes.rst +++ b/logging/monolog_exclude_http_codes.rst @@ -18,29 +18,6 @@ logging these HTTP codes based on the MonologBundle configuration: handler: ... excluded_http_codes: [403, 404, { 400: ['^/foo', '^/bar'] }] - .. code-block:: xml - - - - - - - - - ^/foo - ^/bar - - - - - - .. code-block:: php // config/packages/prod/monolog.php diff --git a/logging/processors.rst b/logging/processors.rst index 17044f229e0..719eedc968b 100644 --- a/logging/processors.rst +++ b/logging/processors.rst @@ -69,31 +69,6 @@ information: tags: - { name: monolog.processor } - .. code-block:: xml - - - - - - - - - [%%datetime%%] [%%extra.token%%] %%channel%%.%%level_name%%: %%message%% %%context%% %%extra%% - - - - - - - - .. code-block:: php // config/services.php @@ -123,29 +98,6 @@ Finally, set the formatter to be used on whatever handler you want: level: debug formatter: monolog.formatter.session_request - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/prod/monolog.php @@ -235,25 +187,6 @@ the ``monolog.processor`` tag: tags: - { name: monolog.processor, handler: main } - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -279,25 +212,6 @@ to the ``monolog.processor`` tag to only apply a processor for the given channel tags: - { name: monolog.processor, channel: 'app' } - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/mailer.rst b/mailer.rst index a2bbe55953c..241f710da08 100644 --- a/mailer.rst +++ b/mailer.rst @@ -35,22 +35,6 @@ over SMTP by configuring the DSN in your ``.env`` file (the ``user``, mailer: dsn: '%env(MAILER_DSN)%' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/mailer.php @@ -97,40 +81,29 @@ Using a 3rd Party Transport Instead of using your own SMTP server or sendmail binary, you can send emails via a third-party provider: -===================== =============================================== =============== -Service Install with Webhook support -===================== =============================================== =============== -`AhaSend`_ ``composer require symfony/aha-send-mailer`` yes +===================== =================================================== =============== +Service Install with Webhook support +===================== =================================================== =============== +`AhaSend`_ ``composer require symfony/aha-send-mailer`` yes `Amazon SES`_ ``composer require symfony/amazon-mailer`` `Azure`_ ``composer require symfony/azure-mailer`` -`Brevo`_ ``composer require symfony/brevo-mailer`` yes +`Brevo`_ ``composer require symfony/brevo-mailer`` yes `Infobip`_ ``composer require symfony/infobip-mailer`` -`Mailgun`_ ``composer require symfony/mailgun-mailer`` yes -`Mailjet`_ ``composer require symfony/mailjet-mailer`` yes -`Mailomat`_ ``composer require symfony/mailomat-mailer`` yes +`Mailgun`_ ``composer require symfony/mailgun-mailer`` yes +`Mailjet`_ ``composer require symfony/mailjet-mailer`` yes +`Mailomat`_ ``composer require symfony/mailomat-mailer`` yes `MailPace`_ ``composer require symfony/mail-pace-mailer`` -`MailerSend`_ ``composer require symfony/mailer-send-mailer`` yes -`Mailtrap`_ ``composer require symfony/mailtrap-mailer`` yes -`Mandrill`_ ``composer require symfony/mailchimp-mailer`` yes +`MailerSend`_ ``composer require symfony/mailer-send-mailer`` yes +`Mailtrap`_ ``composer require symfony/mailtrap-mailer`` yes +`Mandrill`_ ``composer require symfony/mailchimp-mailer`` yes +`Microsoft Graph`_ ``composer require symfony/microsoft-graph-mailer`` `Postal`_ ``composer require symfony/postal-mailer`` -`Postmark`_ ``composer require symfony/postmark-mailer`` yes -`Resend`_ ``composer require symfony/resend-mailer`` yes +`Postmark`_ ``composer require symfony/postmark-mailer`` yes +`Resend`_ ``composer require symfony/resend-mailer`` yes `Scaleway`_ ``composer require symfony/scaleway-mailer`` -`SendGrid`_ ``composer require symfony/sendgrid-mailer`` yes -`Sweego`_ ``composer require symfony/sweego-mailer`` yes -===================== =============================================== =============== - -.. versionadded:: 7.1 - - The Azure and Resend integrations were introduced in Symfony 7.1. - -.. versionadded:: 7.2 - - The Mailomat, Mailtrap, Postal and Sweego integrations were introduced in Symfony 7.2. - -.. versionadded:: 7.3 - - The AhaSend integration was introduced in Symfony 7.3. +`SendGrid`_ ``composer require symfony/sendgrid-mailer`` yes +`Sweego`_ ``composer require symfony/sweego-mailer`` yes +===================== =================================================== =============== .. note:: @@ -177,83 +150,90 @@ transport, but you can force to use one: This table shows the full list of available DSN formats for each third party provider: -+------------------------+---------------------------------------------------------+ -| Provider | Formats | -+========================+=========================================================+ -| `AhaSend`_ | - SMTP ``ahasend+smtp://USERNAME:PASSWORD@default`` | -| | - HTTP n/a | -| | - API ``ahasend+api://KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Amazon SES`_ | - SMTP ``ses+smtp://USERNAME:PASSWORD@default`` | -| | - HTTP ``ses+https://ACCESS_KEY:SECRET_KEY@default`` | -| | - API ``ses+api://ACCESS_KEY:SECRET_KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Azure`_ | - API ``azure+api://ACS_RESOURCE_NAME:KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Brevo`_ | - SMTP ``brevo+smtp://USERNAME:PASSWORD@default`` | -| | - HTTP n/a | -| | - API ``brevo+api://KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Google Gmail`_ | - SMTP ``gmail+smtp://USERNAME:APP-PASSWORD@default`` | -| | - HTTP n/a | -| | - API n/a | -+------------------------+---------------------------------------------------------+ -| `Infobip`_ | - SMTP ``infobip+smtp://KEY@default`` | -| | - HTTP n/a | -| | - API ``infobip+api://KEY@BASE_URL`` | -+------------------------+---------------------------------------------------------+ -| `Mandrill`_ | - SMTP ``mandrill+smtp://USERNAME:PASSWORD@default`` | -| | - HTTP ``mandrill+https://KEY@default`` | -| | - API ``mandrill+api://KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `MailerSend`_ | - SMTP ``mailersend+smtp://KEY@default`` | -| | - HTTP n/a | -| | - API ``mailersend+api://KEY@BASE_URL`` | -+------------------------+---------------------------------------------------------+ -| `Mailgun`_ | - SMTP ``mailgun+smtp://USERNAME:PASSWORD@default`` | -| | - HTTP ``mailgun+https://KEY:DOMAIN@default`` | -| | - API ``mailgun+api://KEY:DOMAIN@default`` | -+------------------------+---------------------------------------------------------+ -| `Mailjet`_ | - SMTP ``mailjet+smtp://ACCESS_KEY:SECRET_KEY@default`` | -| | - HTTP n/a | -| | - API ``mailjet+api://ACCESS_KEY:SECRET_KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Mailomat`_ | - SMTP ``mailomat+smtp://USERNAME:PASSWORD@default`` | -| | - HTTP n/a | -| | - API ``mailomat+api://KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `MailPace`_ | - SMTP ``mailpace+api://API_TOKEN@default`` | -| | - HTTP n/a | -| | - API ``mailpace+api://API_TOKEN@default`` | -+------------------------+---------------------------------------------------------+ -| `Mailtrap`_ | - SMTP ``mailtrap+smtp://PASSWORD@default`` | -| | - HTTP n/a | -| | - API ``mailtrap+api://API_TOKEN@default`` | -+------------------------+---------------------------------------------------------+ -| `Postal`_ | - SMTP n/a | -| | - HTTP n/a | -| | - API ``postal+api://API_KEY@BASE_URL`` | -+------------------------+---------------------------------------------------------+ -| `Postmark`_ | - SMTP ``postmark+smtp://ID@default`` | -| | - HTTP n/a | -| | - API ``postmark+api://KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Resend`_ | - SMTP ``resend+smtp://resend:API_KEY@default`` | -| | - HTTP n/a | -| | - API ``resend+api://API_KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Scaleway`_ | - SMTP ``scaleway+smtp://PROJECT_ID:API_KEY@default`` | -| | - HTTP n/a | -| | - API ``scaleway+api://PROJECT_ID:API_KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Sendgrid`_ | - SMTP ``sendgrid+smtp://KEY@default`` | -| | - HTTP n/a | -| | - API ``sendgrid+api://KEY@default`` | -+------------------------+---------------------------------------------------------+ -| `Sweego`_ | - SMTP ``sweego+smtp://LOGIN:PASSWORD@HOST:PORT`` | -| | - HTTP n/a | -| | - API ``sweego+api://API_KEY@default`` | -+------------------------+---------------------------------------------------------+ ++------------------------+-------------------------------------------------------------------------------------------+ +| Provider | Formats | ++========================+===========================================================================================+ +| `AhaSend`_ | - SMTP ``ahasend+smtp://USERNAME:PASSWORD@default`` | +| | - HTTP n/a | +| | - API ``ahasend+api://KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Amazon SES`_ | - SMTP ``ses+smtp://USERNAME:PASSWORD@default`` | +| | - HTTP ``ses+https://ACCESS_KEY:SECRET_KEY@default`` | +| | - API ``ses+api://ACCESS_KEY:SECRET_KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Azure`_ | - SMTP n/a | +| | - HTTP n/a | +| | - API ``azure+api://ACS_RESOURCE_NAME:KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Brevo`_ | - SMTP ``brevo+smtp://USERNAME:PASSWORD@default`` | +| | - HTTP n/a | +| | - API ``brevo+api://KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Google Gmail`_ | - SMTP ``gmail+smtp://USERNAME:APP-PASSWORD@default`` | +| | - HTTP n/a | +| | - API n/a | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Infobip`_ | - SMTP ``infobip+smtp://KEY@default`` | +| | - HTTP n/a | +| | - API ``infobip+api://KEY@BASE_URL`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Mandrill`_ | - SMTP ``mandrill+smtp://USERNAME:PASSWORD@default`` | +| | - HTTP ``mandrill+https://KEY@default`` | +| | - API ``mandrill+api://KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `MailerSend`_ | - SMTP ``mailersend+smtp://KEY@default`` | +| | - HTTP n/a | +| | - API ``mailersend+api://KEY@BASE_URL`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Mailgun`_ | - SMTP ``mailgun+smtp://USERNAME:PASSWORD@default`` | +| | - HTTP ``mailgun+https://KEY:DOMAIN@default`` | +| | - API ``mailgun+api://KEY:DOMAIN@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Mailjet`_ | - SMTP ``mailjet+smtp://ACCESS_KEY:SECRET_KEY@default`` | +| | - HTTP n/a | +| | - API ``mailjet+api://ACCESS_KEY:SECRET_KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Mailomat`_ | - SMTP ``mailomat+smtp://USERNAME:PASSWORD@default`` | +| | - HTTP n/a | +| | - API ``mailomat+api://KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `MailPace`_ | - SMTP ``mailpace+api://API_TOKEN@default`` | +| | - HTTP n/a | +| | - API ``mailpace+api://API_TOKEN@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Mailtrap`_ | - SMTP ``mailtrap+smtp://PASSWORD@default`` | +| | - HTTP n/a | +| | - API (Live) ``mailtrap+api://API_TOKEN@default`` | +| | - API (Sandbox) ``mailtrap+sandbox://API_TOKEN@default/?inboxId=INBOX_ID`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Microsoft Graph`_ | - SMTP n/a | +| | - HTTP n/a | +| | - API ``microsoftgraph+api://CLIENT_APP_ID:CLIENT_APP_SECRET@default?tenantId=TENANT_ID`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Postal`_ | - SMTP n/a | +| | - HTTP n/a | +| | - API ``postal+api://API_KEY@BASE_URL`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Postmark`_ | - SMTP ``postmark+smtp://ID@default`` | +| | - HTTP n/a | +| | - API ``postmark+api://KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Resend`_ | - SMTP ``resend+smtp://resend:API_KEY@default`` | +| | - HTTP n/a | +| | - API ``resend+api://API_KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Scaleway`_ | - SMTP ``scaleway+smtp://PROJECT_ID:API_KEY@default`` | +| | - HTTP n/a | +| | - API ``scaleway+api://PROJECT_ID:API_KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Sendgrid`_ | - SMTP ``sendgrid+smtp://KEY@default`` | +| | - HTTP n/a | +| | - API ``sendgrid+api://KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ +| `Sweego`_ | - SMTP ``sweego+smtp://LOGIN:PASSWORD@HOST:PORT`` | +| | - HTTP n/a | +| | - API ``sweego+api://API_KEY@default`` | ++------------------------+-------------------------------------------------------------------------------------------+ .. warning:: @@ -341,10 +321,6 @@ the retry period by setting the ``retry_period`` option in the DSN: MAILER_DSN="failover(postmark+api://ID@default sendgrid+smtp://KEY@default)?retry_period=15" -.. versionadded:: 7.3 - - The ``retry_period`` option was introduced in Symfony 7.3. - Load Balancing ~~~~~~~~~~~~~~ @@ -372,10 +348,6 @@ the retry period by setting the ``retry_period`` option in the DSN: MAILER_DSN="roundrobin(postmark+api://ID@default sendgrid+smtp://KEY@default)?retry_period=15" -.. versionadded:: 7.3 - - The ``retry_period`` option was introduced in Symfony 7.3. - TLS Peer Verification ~~~~~~~~~~~~~~~~~~~~~ @@ -399,10 +371,6 @@ may be specified as SHA1 or MD5 hash:: Disabling Automatic TLS ~~~~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 7.1 - - The option to disable automatic TLS was introduced in Symfony 7.1. - By default, the Mailer component will use encryption when the OpenSSL extension is enabled and the SMTP server supports ``STARTTLS``. This behavior can be turned off by calling ``setAutoTls(false)`` on the ``EsmtpTransport`` instance, or by @@ -438,17 +406,9 @@ with the SMTP server. This setting only applies when using the ``smtp://`` protocol. -.. versionadded:: 7.3 - - The ``require_tls`` option was introduced in Symfony 7.3. - Binding to IPv4 or IPv6 ~~~~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 7.3 - - The option to bind to IPv4, or IPv6, or a specific IP address was introduced in Symfony 7.3. - By default, the underlying ``SocketStream`` will bind to IPv4 or IPv6 based on the available interfaces. You can enforce binding to a specific protocol or IP address by using the ``source_ip`` option. To bind to IPv4, use:: @@ -634,11 +594,6 @@ both strings or address objects:: :ref:`configure emails globally ` to set the same ``From`` email to all messages. -.. versionadded:: 7.2 - - Support for non-ASCII email addresses (e.g. ``jânë.dœ@ëxãmplę.com``) - was introduced in Symfony 7.2. - .. note:: The local part of the address (what goes before the ``@``) can include UTF-8 @@ -819,32 +774,6 @@ and headers. Bcc: 'baz@example.com' X-Custom-Header: 'foobar' - .. code-block:: xml - - - - - - - - - - fabien@example.com - foo@example.com - bar@example.com - - Fabien <fabien@example.com> - baz@example.com - foobar - - - - .. code-block:: php // config/packages/mailer.php @@ -1074,24 +1003,6 @@ image files as usual. First, to simplify things, define a Twig namespace called # point this wherever your images live '%kernel.project_dir%/assets/images': images - .. code-block:: xml - - - - - - - - - %kernel.project_dir%/assets/images - - - .. code-block:: php // config/packages/twig.php @@ -1123,10 +1034,6 @@ This behavior can be overridden by passing a custom file name as the third argum ACME Logo -.. versionadded:: 7.3 - - The third argument of ``email.image()`` was introduced in Symfony 7.3. - .. _mailer-inline-css: Inlining CSS Styles @@ -1195,24 +1102,6 @@ called ``styles`` that points to the directory where ``email.css`` lives: # point this wherever your css files live '%kernel.project_dir%/assets/styles': styles - .. code-block:: xml - - - - - - - - - %kernel.project_dir%/assets/styles - - - .. code-block:: php // config/packages/twig.php @@ -1452,34 +1341,6 @@ minimizes repetition and centralizes your configuration for DKIM and S/MIME sign certificate: '%kernel.project_dir%/var/certificates/smime.crt' passphrase: '' - .. code-block:: xml - - - - - - - - - - file://%kernel.project_dir%/var/certificates/dkim.pem - symfony.com - s1 - - - %kernel.project_dir%/var/certificates/smime.pem - %kernel.project_dir%/var/certificates/smime.crt - - - - - - .. code-block:: php // config/packages/mailer.php @@ -1500,10 +1361,6 @@ minimizes repetition and centralizes your configuration for DKIM and S/MIME sign ; }; -.. versionadded:: 7.3 - - Global message signing was introduced in Symfony 7.3. - Encrypting Messages ~~~~~~~~~~~~~~~~~~~ @@ -1561,27 +1418,6 @@ encrypter that automatically applies to all outgoing messages: smime_encrypter: repository: App\Security\LocalFileCertificateRepository - .. code-block:: xml - - - - - - - - - - App\Security\LocalFileCertificateRepository - - - - - .. code-block:: php // config/packages/mailer.php @@ -1621,10 +1457,6 @@ return the file path to the certificate associated with the given email address: } } -.. versionadded:: 7.3 - - Global message encryption configuration was introduced in Symfony 7.3. - .. _multiple-email-transports: Multiple Email Transports @@ -1645,26 +1477,6 @@ This can be configured by replacing the ``dsn`` configuration entry with a main: '%env(MAILER_DSN)%' alternative: '%env(MAILER_DSN_IMPORTANT)%' - .. code-block:: xml - - - - - - - - - %env(MAILER_DSN)% - %env(MAILER_DSN_IMPORTANT)% - - - - .. code-block:: php // config/packages/mailer.php @@ -1717,28 +1529,6 @@ you have a transport called ``async``, you can route the message there: routing: 'Symfony\Component\Mailer\Messenger\SendEmailMessage': async - .. code-block:: xml - - - - - - - - %env(MESSENGER_TRANSPORT_DSN)% - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -1794,26 +1584,6 @@ disable asynchronous delivery. mailer: message_bus: app.another_bus - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/mailer.php @@ -2082,23 +1852,6 @@ the mailer configuration file (e.g. in the ``dev`` or ``test`` environments): mailer: dsn: 'null://null' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/mailer.php @@ -2132,27 +1885,6 @@ a specific address, instead of the *real* address: envelope: recipients: ['youremail@example.com'] - .. code-block:: xml - - - - - - - - - - youremail@example.com - - - - - .. code-block:: php // config/packages/mailer.php @@ -2185,30 +1917,6 @@ address(es) defined in ``recipients``, as with all other emails: # you can also use regular expression to define allowed recipients - 'internal-.*@example.(com|fr)' - .. code-block:: xml - - - - - - - - - - youremail@example.com - internal@example.com - - internal-.*@example.(com|fr) - - - - - .. code-block:: php // config/packages/mailer.php @@ -2231,10 +1939,6 @@ With this configuration, all emails will be sent to ``youremail@example.com``. Additionally, emails sent to ``internal@example.com``, ``internal-monitoring@example.fr``, etc., will also be delivered to those addresses. -.. versionadded:: 7.1 - - The ``allowed_recipients`` option was introduced in Symfony 7.1. - Write a Functional Test ~~~~~~~~~~~~~~~~~~~~~~~ @@ -2294,6 +1998,7 @@ the :class:`Symfony\\Bundle\\FrameworkBundle\\Test\\MailerAssertionsTrait`:: .. _`Markdown syntax`: https://commonmark.org/ .. _`Mailomat`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Mailer/Bridge/Mailomat/README.md .. _`MailPace`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Mailer/Bridge/MailPace/README.md +.. _`Microsoft Graph`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Mailer/Bridge/MicrosoftGraph/README.md .. _`OpenSSL PHP extension`: https://www.php.net/manual/en/book.openssl.php .. _`PEM encoded`: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail .. _`Postal`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Mailer/Bridge/Postal/README.md diff --git a/mercure.rst b/mercure.rst index 5a34fe7e4bb..274314d4915 100644 --- a/mercure.rst +++ b/mercure.rst @@ -142,31 +142,6 @@ MercureBundle provides a more advanced configuration: factory: 'My\Factory' value: 'my.jwt' - .. code-block:: xml - - - - - - - https://example.com/foo1 - https://example.com/foo2 - https://example.com/bar1 - https://example.com/bar2 - - - - .. code-block:: php // config/packages/mercure.php @@ -552,19 +527,6 @@ Then, reference this service in the bundle configuration: jwt: provider: App\Mercure\MyTokenProvider - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/packages/mercure.php diff --git a/messenger.rst b/messenger.rst index 0bd57cfdf5b..a535b077c2d 100644 --- a/messenger.rst +++ b/messenger.rst @@ -151,32 +151,6 @@ that uses this configuration: # dsn: "%env(MESSENGER_TRANSPORT_DSN)%" # options: [] - .. code-block:: xml - - - - - - - - %env(MESSENGER_TRANSPORT_DSN)% - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -232,28 +206,6 @@ you can configure them to be sent to a transport: # async is whatever name you gave your transport above 'App\Message\SmsNotification': async - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -266,23 +218,19 @@ you can configure them to be sent to a transport: ; }; -.. versionadded:: 7.2 - - The ``#[AsMessage]`` attribute was introduced in Symfony 7.2. - Thanks to this, the ``App\Message\SmsNotification`` will be sent to the ``async`` transport and its handler(s) will *not* be called immediately. Any messages not matched under ``routing`` will still be handled immediately, i.e. synchronously. .. note:: - If you configure routing with both YAML/XML/PHP configuration files and + If you configure routing with both YAML/PHP configuration files and PHP attributes, the configuration always takes precedence over the class attribute. This behavior allows you to override routing on a per-environment basis. .. note:: - When configuring the routing in separate YAML/XML/PHP files, you can use a partial + When configuring the routing in separate YAML/PHP files, you can use a partial PHP namespace like ``'App\Message\*'`` to match all the messages within the matching namespace. The only requirement is that the ``'*'`` wildcard has to be placed at the end of the namespace. @@ -334,35 +282,6 @@ to multiple transports: 'My\Message\ToBeSentToTwoSenders': [async, audit] - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -468,31 +387,6 @@ transport and "sending" messages there to be handled immediately: routing: App\Message\SmsNotification: sync - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -539,9 +433,17 @@ command with the ``--all`` option: $ php bin/console messenger:consume --all -.. versionadded:: 7.1 +When using ``--all``, you can exclude specific receivers using the ``--exclude-receivers`` +option (shortcut ``-eq``): + +.. code-block:: terminal + + $ php bin/console messenger:consume --all --exclude-receivers=async_priority_low --exclude-receivers=failed + +.. note:: - The ``--all`` option was introduced in Symfony 7.1. + The ``--exclude-receivers`` option can only be used together with ``--all``. + Also, you cannot exclude all receivers. Messages that take a long time to process may be redelivered prematurely because some transports assume that an unacknowledged message is lost. To prevent this @@ -557,10 +459,6 @@ the message from being redelivered until the worker completes processing it: This option is only available for the following transports: Beanstalkd, AmazonSQS, Doctrine and Redis. -.. versionadded:: 7.2 - - The ``--keepalive`` option was introduced in Symfony 7.2. - .. tip:: In a development environment and if you're using the Symfony CLI tool, @@ -648,41 +546,6 @@ different messages to them. For example: 'App\Message\SmsNotification': async_priority_low 'App\Message\NewUserWelcomeEmail': async_priority_high - .. code-block:: xml - - - - - - - - - - - Queue - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -757,10 +620,6 @@ of some or all transports: $ php bin/console messenger:stats --format=json $ php bin/console messenger:stats my_transport_name other_transport_name --format=json -.. versionadded:: 7.2 - - The ``format`` option was introduced in Symfony 7.2. - .. note:: In order for this command to work, the configured transport's receiver must implement @@ -863,27 +722,6 @@ configuration option: - SIGINT - SIGUSR1 - .. code-block:: xml - - - - - - - - - SIGTERM - SIGINT - SIGUSR1 - - - - .. code-block:: php // config/packages/messenger.php @@ -894,12 +732,6 @@ configuration option: ->stopWorkerOnSignals(['SIGTERM', 'SIGINT', 'SIGUSR1']); }; -.. versionadded:: 7.3 - - Support for signals plain names in configuration was introduced in Symfony 7.3. - Previously, you had to use the numeric values of signals as defined by the - ``pcntl`` extension's `predefined constants`_. - In some cases the ``SIGTERM`` signal is sent by Supervisor itself (e.g. stopping a Docker container having Supervisor as its entrypoint). In these cases you need to add a ``stopwaitsecs`` key to the program configuration (with a value @@ -1041,27 +873,6 @@ by setting its ``rate_limiter`` option: async: rate_limiter: your_rate_limiter_name - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -1117,27 +928,6 @@ this is configurable for each transport: # implements Symfony\Component\Messenger\Retry\RetryStrategyInterface # service: null - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -1166,10 +956,6 @@ this is configurable for each transport: ; }; -.. versionadded:: 7.1 - - The ``jitter`` option was introduced in Symfony 7.1. - .. tip:: Symfony triggers a :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageRetriedEvent` @@ -1207,11 +993,6 @@ You can define a custom retry delay in milliseconds (e.g., to use the value from the ``Retry-After`` header in an HTTP response) by setting the ``retryDelay`` argument in the constructor of the ``RecoverableMessageHandlingException``. -.. versionadded:: 7.2 - - The ``retryDelay`` argument and the ``getRetryDelay()`` method were introduced - in Symfony 7.2. - .. _messenger-failure-transport: Saving & Retrying Failed Messages @@ -1235,28 +1016,6 @@ be discarded. To avoid this happening, you can instead configure a ``failure_tra failed: 'doctrine://default?queue_name=failed' - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -1319,16 +1078,6 @@ If the message fails again, it will be re-sent back to the failure transport due to the normal :ref:`retry rules `. Once the max retry has been hit, the message will be discarded permanently. -.. versionadded:: 7.2 - - The option to skip a message in the ``messenger:failed:retry`` command was - introduced in Symfony 7.2 - -.. versionadded:: 7.3 - - The option to filter by a message class in the ``messenger:failed:remove`` command was - introduced in Symfony 7.3 - Multiple Failed Transports ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1360,33 +1109,6 @@ override the failure transport for only specific transports: failed_default: 'doctrine://default?queue_name=failed_default' failed_high_priority: 'doctrine://default?queue_name=failed_high_priority' - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -1458,27 +1180,6 @@ options. Options can be passed to the transport via a DSN string or configuratio options: auto_setup: false - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -1650,10 +1351,6 @@ The transport has a number of options: ``exchange[type]`` (default: ``fanout``) Type of exchange -.. versionadded:: 7.3 - - Empty string support for ``exchange[name]`` was introduced in Symfony 7.3. - You can also configure AMQP-specific settings on your message by adding :class:`Symfony\\Component\\Messenger\\Bridge\\Amqp\\Transport\\AmqpStamp` to your Envelope:: @@ -1760,10 +1457,6 @@ in the table. The Doctrine transport supports the ``--keepalive`` option by periodically updating the ``delivered_at`` timestamp to prevent the message from being redelivered. -.. versionadded:: 7.3 - - Keepalive support was introduced in Symfony 7.3. - Beanstalkd Transport ~~~~~~~~~~~~~~~~~~~~ @@ -1790,10 +1483,6 @@ The transport has a number of options: When set to ``true``, rejected messages are placed into a "buried" state in Beanstalkd instead of being deleted. - .. versionadded:: 7.3 - - The ``bury_on_reject`` option was introduced in Symfony 7.3. - ``timeout`` (default: ``0``) Message reservation timeout - in seconds. 0 will cause the server to immediately return either a response or a TransportException will be thrown. @@ -1808,10 +1497,6 @@ The transport has a number of options: The Beanstalkd transport supports the ``--keepalive`` option by using Beanstalkd's ``touch`` command to periodically reset the job's ``ttr``. -.. versionadded:: 7.2 - - Keepalive support was introduced in Symfony 7.2. - The Beanstalkd transport lets you set the priority of the messages being dispatched. Use the :class:`Symfony\\Component\\Messenger\\Bridge\\Beanstalkd\\Transport\\BeanstalkdPriorityStamp` and pass a number to specify the priority (default = ``1024``; lower numbers mean higher priority):: @@ -1825,10 +1510,6 @@ and pass a number to specify the priority (default = ``1024``; lower numbers mea new BeanstalkdPriorityStamp(0), ]); -.. versionadded:: 7.3 - - ``BeanstalkdPriorityStamp`` support was introduced in Symfony 7.3. - .. _messenger-redis-transport: Redis Transport @@ -1931,10 +1612,6 @@ under the transport in ``messenger.yaml``: ``redis_sentinel`` (default: ``null``) An alias of the ``sentinel_master`` option - .. versionadded:: 7.1 - - The ``redis_sentinel`` option was introduced in Symfony 7.1. - ``ssl`` (default: ``null``) Map of `SSL context options`_ for the TLS channel. This is useful for example to change the requirements for the TLS channel in tests: @@ -1978,10 +1655,6 @@ under the transport in ``messenger.yaml``: The Redis transport supports the ``--keepalive`` option by using Redis's ``XCLAIM`` command to periodically reset the message's idle time to zero. -.. versionadded:: 7.3 - - Keepalive support was introduced in Symfony 7.3. - In Memory Transport ~~~~~~~~~~~~~~~~~~~ @@ -2000,25 +1673,6 @@ override it in the ``test`` environment to use this transport: transports: async_priority_normal: 'in-memory://' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/test/messenger.php @@ -2115,6 +1769,10 @@ The transport has a number of options: ``debug`` (default: ``false``) If ``true`` it logs all HTTP requests and responses (it impacts performance) +``delete_on_rejection`` (default: ``true``) + If set to ``false``, the message will not be deleted when rejected. Instead, + its visibility will be changed so that SQS can handle retries + ``endpoint`` (default: ``https://sqs.eu-west-1.amazonaws.com``) Absolute URL to the SQS service @@ -2133,6 +1791,10 @@ The transport has a number of options: ``region`` (default: ``eu-west-1``) Name of the AWS region +``retry_delay`` (default: ``0``) + Used only when ``delete_on_rejection`` is ``false``. Defines the visibility + timeout (in seconds) that SQS should apply when a message is rejected + ``secret_key`` AWS secret key (must be urlencoded) @@ -2145,10 +1807,6 @@ The transport has a number of options: ``wait_time`` (default: ``20``) `Long polling`_ duration in seconds -.. versionadded:: 7.3 - - The ``queue_attributes`` and ``queue_tags`` options were introduced in Symfony 7.3. - .. note:: The ``wait_time`` parameter defines the maximum duration Amazon SQS should @@ -2184,10 +1842,6 @@ The transport has a number of options: The SQS transport supports the ``--keepalive`` option by using the ``ChangeMessageVisibility`` action to periodically update the ``VisibilityTimeout`` of the message. -.. versionadded:: 7.2 - - Keepalive support was introduced in Symfony 7.2. - Serializing Messages ~~~~~~~~~~~~~~~~~~~~ @@ -2214,31 +1868,6 @@ this globally (or for each transport) to a service that implements dsn: # ... serializer: messenger.transport.symfony_serializer - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -2282,11 +1911,6 @@ This interface is implemented by the following transports: AmazonSqs, Amqp, and If you need to close a Doctrine connection, you can do so :ref:`using middleware `. -.. versionadded:: 7.3 - - The ``CloseableTransportInterface`` and its ``close()`` method were introduced - in Symfony 7.3. - Running Commands And External Processes --------------------------------------- @@ -2379,16 +2003,74 @@ If you want to use shell features such as redirections or pipes, use the static For more information, read the documentation about :ref:`using features from the OS shell `. -.. versionadded:: 7.3 - - The ``RunProcessMessage::fromShellCommandline()`` method was introduced in Symfony 7.3. - Once handled, the handler will return a :class:`Symfony\\Component\\Process\\Messenger\\RunProcessContext` which contains many useful information such as the exit code or the output of the process. You can refer to the page dedicated on :ref:`handler results ` for more information. +Securing Messages with Signatures +--------------------------------- + +When messages are sent to message queues, there is a potential security risk +if an attacker injects forged payloads into the queue. Although message queues +should be properly secured to prevent unauthorized access, Symfony adds an extra +layer of protection by supporting message signing. + +This is particularly important for handlers that execute commands or processes, +which is why the ``RunProcessHandler`` has message signing **enabled by default**. + +Enabling Message Signing +~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable message signing for your handler, set the ``sign`` option to ``true``: + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/MessageHandler/SmsNotificationHandler.php + namespace App\MessageHandler; + + use App\Message\SmsNotification; + use Symfony\Component\Messenger\Attribute\AsMessageHandler; + + #[AsMessageHandler(sign: true)] + class SmsNotificationHandler + { + public function __invoke(SmsNotification $message): void + { + // ... handle message + } + } + + .. code-block:: yaml + + # config/services.yaml + services: + App\MessageHandler\SmsNotificationHandler: + tags: + - { name: messenger.message_handler, sign: true } + + .. code-block:: php + + // config/services.php + use App\MessageHandler\SmsNotificationHandler; + + $container->register(SmsNotificationHandler::class) + ->addTag('messenger.message_handler', ['sign' => true]); + +When signing is enabled: + +1. Messages are signed using an HMAC signature computed with your application's + secret key (``kernel.secret`` parameter). +2. The signature is added to the message headers (``Body-Sign`` and ``Sign-Algo``) + when the message is sent to a transport. +3. When the message is received and decoded, the signature is automatically verified. +4. If the signature is missing or invalid, an + :class:`Symfony\\Component\\Messenger\\Exception\\InvalidMessageSignatureException` + is thrown, and the message will not be handled. + Pinging A Webservice -------------------- @@ -2534,10 +2216,6 @@ to the existing ones:: $this->handle(new SomeMessage($data), [new SomeStamp(), new AnotherStamp()]); -.. versionadded:: 7.3 - - The ``$stamps`` parameter of the ``handle()`` method was introduced in Symfony 7.3. - Customizing Handlers -------------------- @@ -2585,24 +2263,6 @@ with ``messenger.message_handler``. # only needed if can't be guessed by type-hint handles: App\Message\SmsNotification - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -2635,6 +2295,11 @@ Possible options to configure with tags are: Defines the order in which the handler is executed when multiple handlers can process the same message; those with higher priority run first. +``sign`` + Whether messages handled by this handler should be cryptographically signed + to prevent tampering. When enabled, messages are signed using HMAC with the + application's secret key. Default: ``false``. + .. _handler-subscriber-options: Handling Multiple Messages @@ -2853,31 +2518,6 @@ Then, make sure to "route" your message to *both* transports: # ... 'App\Message\UploadedImage': [image_transport, async_priority_normal] - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -3062,36 +2702,6 @@ and a different instance will be created per bus. - 'App\Middleware\MyMiddleware' - 'App\Middleware\AnotherMiddleware' - .. code-block:: xml - - - - - - - - - - - - - messenger.bus.default - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -3156,37 +2766,6 @@ may want to use: # or pass a different entity manager to any #- doctrine_transaction: ['custom'] - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -3232,28 +2811,6 @@ to configure the validation groups. - router_context - validation - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -3275,6 +2832,7 @@ In addition to middleware, Messenger also dispatches several events. You can of the process. For each, the event class is the event name: * :class:`Symfony\\Component\\Messenger\\Event\\SendMessageToTransportsEvent` +* :class:`Symfony\\Component\\Messenger\\Event\\MessageSentToTransportsEvent` * :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageFailedEvent` * :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageHandledEvent` * :class:`Symfony\\Component\\Messenger\\Event\\WorkerMessageReceivedEvent` @@ -3284,6 +2842,12 @@ of the process. For each, the event class is the event name: * :class:`Symfony\\Component\\Messenger\\Event\\WorkerStartedEvent` * :class:`Symfony\\Component\\Messenger\\Event\\WorkerStoppedEvent` +.. note:: + + The ``MessageSentToTransportsEvent`` event is dispatched **only** after a + message was sent to at least one transport. If the message was sent to + multiple transports, the event is dispatched only once. + Additional Handler Arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3388,27 +2952,6 @@ transports: dsn: '%env(MY_TRANSPORT_DSN)%' serializer: 'App\Messenger\Serializer\MessageWithTokenDecoder' - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -3473,40 +3016,6 @@ an **event bus**. The event bus could have zero or more subscribers. middleware: - validation - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php @@ -3561,22 +3070,6 @@ you can restrict each handler to a specific bus using the ``messenger.message_ha App\MessageHandler\SomeCommandHandler: tags: [{ name: messenger.message_handler, bus: command.bus }] - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -3612,32 +3105,6 @@ you can determine the message bus based on an implemented interface: tags: - { name: messenger.message_handler, bus: query.bus } - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -3764,5 +3231,4 @@ Learn more .. _`high connection churn`: https://www.rabbitmq.com/connections.html#high-connection-churn .. _`article about CQRS`: https://martinfowler.com/bliki/CQRS.html .. _`SSL context options`: https://php.net/context.ssl -.. _`predefined constants`: https://www.php.net/pcntl.constants .. _`SQS CreateQueue API`: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_CreateQueue.html diff --git a/messenger/custom-transport.rst b/messenger/custom-transport.rst index 7d1698126d1..3afd9d914f1 100644 --- a/messenger/custom-transport.rst +++ b/messenger/custom-transport.rst @@ -146,22 +146,6 @@ Otherwise, add the following: Your\Transport\YourTransportFactory: tags: [messenger.transport_factory] - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -186,25 +170,6 @@ named transport using your own DSN: transports: yours: 'my-transport://...' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/messenger.php diff --git a/notifier.rst b/notifier.rst index 49a1c2d533b..83d75e9b25f 100644 --- a/notifier.rst +++ b/notifier.rst @@ -38,10 +38,6 @@ The notifier component supports the following channels: * :ref:`Desktop channel ` displays desktop notifications on the same host machine. -.. versionadded:: 7.2 - - The ``Desktop`` channel was introduced in Symfony 7.2. - .. _notifier-sms-channel: SMS Channel @@ -159,9 +155,6 @@ Service `Sendinblue`_ **Install**: ``composer require symfony/sendinblue-notifier`` \ **DSN**: ``sendinblue://API_KEY@default?sender=PHONE`` \ **Webhook support**: No -`Sms77`_ **Install**: ``composer require symfony/sms77-notifier`` \ - **DSN**: ``sms77://API_KEY@default?from=FROM`` \ - **Webhook support**: No `SimpleTextin`_ **Install**: ``composer require symfony/simple-textin-notifier`` \ **DSN**: ``simpletextin://API_KEY@default?from=FROM`` \ **Webhook support**: No @@ -229,26 +222,6 @@ Service via webhooks. See the :doc:`Webhook documentation ` for more details. -.. versionadded:: 7.1 - - The ``Smsbox``, ``SmsSluzba``, ``SMSense``, ``LOX24`` and ``Unifonic`` - integrations were introduced in Symfony 7.1. - -.. versionadded:: 7.2 - - The ``Primotexto``, ``Sipgate`` and ``Sweego`` integrations were introduced in Symfony 7.2. - -.. versionadded:: 7.3 - - Webhook support for the ``Brevo`` integration was introduced in Symfony 7.3. - The extra properties in ``SentMessage`` for ``AllMySms`` and ``OvhCloud`` - providers were introduced in Symfony 7.3 too. - -.. deprecated:: 7.1 - - The `Sms77`_ integration is deprecated since - Symfony 7.1, use the `Seven.io`_ integration instead. - To enable a texter, add the correct DSN in your ``.env`` file and configure the ``texter_transports``: @@ -267,27 +240,6 @@ configure the ``texter_transports``: texter_transports: twilio: '%env(TWILIO_DSN)%' - .. code-block:: xml - - - - - - - - - %env(TWILIO_DSN)% - - - - - .. code-block:: php // config/packages/notifier.php @@ -406,23 +358,6 @@ Service **DSN**: ``zulip://EMAIL:TOKEN@HOST?channel=CHANNEL`` ====================================== ===================================================================================== -.. versionadded:: 7.1 - - The ``Bluesky`` integration was introduced in Symfony 7.1. - -.. versionadded:: 7.2 - - The ``LINE Bot`` integration was introduced in Symfony 7.2. - -.. deprecated:: 7.2 - - The ``Gitter`` integration was removed in Symfony 7.2 because that service - no longer provides an API. - -.. versionadded:: 7.3 - - The ``Matrix`` integration was introduced in Symfony 7.3. - .. warning:: By default, if you have the :doc:`Messenger component ` installed, @@ -456,27 +391,6 @@ Chatters are configured using the ``chatter_transports`` setting: chatter_transports: slack: '%env(SLACK_DSN)%' - .. code-block:: xml - - - - - - - - - %env(SLACK_DSN)% - - - - - .. code-block:: php // config/packages/notifier.php @@ -552,29 +466,6 @@ notification emails: envelope: sender: 'notifications@example.com' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/mailer.php @@ -628,10 +519,6 @@ Service To enable a texter, add the correct DSN in your ``.env`` file and configure the ``texter_transports``: -.. versionadded:: 7.1 - - The `Pushy`_ integration was introduced in Symfony 7.1. - .. code-block:: bash # .env @@ -647,27 +534,6 @@ configure the ``texter_transports``: texter_transports: expo: '%env(EXPO_DSN)%' - .. code-block:: xml - - - - - - - - - %env(EXPO_DSN)% - - - - - .. code-block:: php // config/packages/notifier.php @@ -694,10 +560,6 @@ Provider Install DSN `JoliNotif`_ ``composer require symfony/joli-notif-notifier`` ``jolinotif://default`` =============== ================================================ ============================================================================== -.. versionadded:: 7.2 - - The JoliNotif bridge was introduced in Symfony 7.2. - If you are using :ref:`Symfony Flex `, installing that package will also create the necessary environment variable and configuration. Otherwise, you'll need to add the following manually: @@ -721,27 +583,6 @@ need to add the following manually: texter_transports: jolinotif: '%env(JOLINOTIF)%' - .. code-block:: xml - - - - - - - - - %env(JOLINOTIF)% - - - - - .. code-block:: php // config/packages/notifier.php @@ -819,35 +660,6 @@ transport: # Send notifications to the next scheduled transport calculated by round robin roundrobin: '%env(SLACK_DSN)% && %env(TELEGRAM_DSN)%' - .. code-block:: xml - - - - - - - - - - %env(SLACK_DSN)% || %env(TELEGRAM_DSN)% - - - - - - - - .. code-block:: php // config/packages/notifier.php @@ -953,39 +765,6 @@ specify what channels should be used for specific levels (using medium: ['browser'] low: ['browser'] - .. code-block:: xml - - - - - - - - - - - - sms - chat/slack - email - - - chat/slack - - - browser - browser - - - - - .. code-block:: php // config/packages/notifier.php @@ -1132,19 +911,6 @@ typical alert levels, which you can implement immediately using: notifier.flash_message_importance_mapper: class: Symfony\Component\Notifier\FlashMessage\BootstrapFlashMessageImportanceMapper - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/services.php @@ -1324,12 +1090,10 @@ is dispatched. Listeners receive a .. _`SMSFactor`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/SmsFactor/README.md .. _`Sendberry`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Sendberry/README.md .. _`Sendinblue`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Sendinblue/README.md -.. _`Seven.io`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Sevenio/README.md .. _`SimpleTextin`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/SimpleTextin/README.md .. _`Sinch`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Sinch/README.md .. _`Sipgate`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Sipgate/README.md .. _`Slack`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Slack/README.md -.. _`Sms77`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Sms77/README.md .. _`SmsBiuras`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/SmsBiuras/README.md .. _`Smsbox`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Smsbox/README.md .. _`Smsapi`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Notifier/Bridge/Smsapi/README.md diff --git a/object_mapper.rst b/object_mapper.rst index 625466ffefc..7e23e120995 100644 --- a/object_mapper.rst +++ b/object_mapper.rst @@ -1,11 +1,6 @@ Object Mapper ============= -.. versionadded:: 7.3 - - The ObjectMapper component was introduced in Symfony 7.3 as an - :doc:`experimental feature `. - This component transforms one object into another, simplifying tasks such as converting DTOs (Data Transfer Objects) into entities or vice versa. It can also be helpful when decoupling API input/output from internal models, particularly @@ -429,6 +424,29 @@ And the related target object must define the ``createFromLegacy()`` method:: } } +Mapping Collections +------------------- + +By default, ObjectMapper does not map arrays or traversable collections. To map +each item in a collection (for example, mapping an array of DTOs to an array of +entities), you **must** explicitly use the ``MapCollection`` transformer: + +Example:: + + use Symfony\Component\ObjectMapper\Attribute\Map; + use Symfony\Component\ObjectMapper\Transform\MapCollection; + + class ProductListInput + { + #[Map(transform: new MapCollection())] + /** @var ProductInput[] */ + public array $products; + } + +With this configuration, ObjectMapper maps each item in the ``products`` array +according to the usual mapping rules. Without ``transform: new MapCollection()``, +the array is left unchanged. + Mapping Multiple Targets ------------------------ @@ -590,6 +608,47 @@ Using it in practice:: // $employeeDto->manager->name === 'Alice' // $employeeDto->manager->manager === $employeeDto +Decorating the ObjectMapper +--------------------------- + +The ``object_mapper`` service can be decorated to add custom logic or manage +state around the mapping process. + +You can use the :class:`Symfony\\Component\\ObjectMapper\\ObjectMapperAwareInterface` +to enable the decorated service to access the outermost decorator. If the +decorated service implements this interface, the decorator can pass itself to +it. This allows underlying services, like the ``ObjectMapper``, to call the +decorator's ``map()`` method during recursive mapping, ensuring that the +decorator's state is used consistently throughout the process. + +Here's an example of a decorator that preserves object identity across calls. +It uses the ``AsDecorator`` attribute to automatically configure itself as a +decorator of the ``object_mapper`` service:: + + // src/ObjectMapper/StatefulObjectMapper.php + namespace App\ObjectMapper; + + use Symfony\Component\DependencyInjection\Attribute\AsDecorator; + use Symfony\Component\ObjectMapper\ObjectMapperAwareInterface; + use Symfony\Component\ObjectMapper\ObjectMapperInterface; + + #[AsDecorator(decorates: ObjectMapperInterface::class)] + final class StatefulObjectMapper implements ObjectMapperInterface + { + public function __construct(private ObjectMapperInterface $decorated) + { + // pass this decorator to the decorated service if it's aware + if ($this->decorated instanceof ObjectMapperAwareInterface) { + $this->decorated = $this->decorated->withObjectMapper($this); + } + } + + public function map(object $source, object|string|null $target = null): object + { + return $this->decorated->map($source, $target); + } + } + .. _objectmapper-custom-mapping-logic: Custom Mapping Logic diff --git a/page_creation.rst b/page_creation.rst index 0e2fd78e180..c4aa0cfc856 100644 --- a/page_creation.rst +++ b/page_creation.rst @@ -87,7 +87,7 @@ try it out by going to: http://localhost:8000/lucky/number Symfony recommends defining routes as attributes to have the controller code and its route configuration at the same location. However, if you prefer, you can - :doc:`define routes in separate files ` using YAML, XML and PHP formats. + :doc:`define routes in separate files ` using the YAML or PHP formats. If you see a lucky number being printed back to you, congratulations! But before you run off to play the lottery, check out how this works. Remember the two steps @@ -125,11 +125,11 @@ You should see your ``app_lucky_number`` route in the list: .. code-block:: terminal - ---------------- ------- ------- ----- -------------- - Name Method Scheme Host Path - ---------------- ------- ------- ----- -------------- - app_lucky_number ANY ANY ANY /lucky/number - ---------------- ------- ------- ----- -------------- + ---------------- ------- -------------- + Name Method Path + ---------------- ------- -------------- + app_lucky_number ANY /lucky/number + ---------------- ------- -------------- You will also see debugging routes besides ``app_lucky_number`` -- more on the debugging routes in the next section. diff --git a/performance.rst b/performance.rst index 828333f338b..e1676edddb2 100644 --- a/performance.rst +++ b/performance.rst @@ -62,20 +62,6 @@ container into a single file, which could improve performance when using # ... .container.dumper.inline_factories: true - .. code-block:: xml - - - - - - - - true - - - .. code-block:: php // config/services.php @@ -242,20 +228,6 @@ in performance, you can stop generating the file as follows: # ... debug.container.dump: false - .. code-block:: xml - - - - - - - - false - - - .. code-block:: php // config/services.php @@ -365,10 +337,6 @@ method does, which stops an event and then restarts it immediately:: // Gets the last event period: // $event->getLastPeriod(); -.. versionadded:: 7.2 - - The ``getLastPeriod()`` method was introduced in Symfony 7.2. - Profiling Sections .................. @@ -395,10 +363,6 @@ know their names, as follows:: echo (string) $event; } -.. versionadded:: 7.2 - - The ``Stopwatch::ROOT`` constant as a shortcut for ``__root__`` was introduced in Symfony 7.2. - Learn more ---------- diff --git a/profiler.rst b/profiler.rst index 7fc97c8ee33..0946d619269 100644 --- a/profiler.rst +++ b/profiler.rst @@ -163,20 +163,6 @@ create an alias pointing to the existing ``profiler`` service: services: Symfony\Component\HttpKernel\Profiler\Profiler: '@profiler' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/services_dev.php @@ -230,22 +216,6 @@ toolbar to be refreshed after each AJAX request by enabling ``ajax_replace`` in toolbar: ajax_replace: true - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/web_profiler.php @@ -561,28 +531,6 @@ you'll need to configure the data collector explicitly: # optional priority (positive or negative integer; default = 0) # priority: 300 - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/quick_tour/the_architecture.rst b/quick_tour/the_architecture.rst index 3b66570b3d3..c942c917a01 100644 --- a/quick_tour/the_architecture.rst +++ b/quick_tour/the_architecture.rst @@ -243,29 +243,6 @@ using the special ``when@`` keyword: router: strict_requirements: null - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/rate_limiter.rst b/rate_limiter.rst index 4a072dbac89..f933204eb22 100644 --- a/rate_limiter.rst +++ b/rate_limiter.rst @@ -143,39 +143,6 @@ enforce different levels of service (free or paid): limit: 5000 rate: { interval: '15 minutes', amount: 500 } - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/rate_limiter.php @@ -222,11 +189,6 @@ prevents that number from being higher than 5,000). find them with a :doc:`tagged iterator ` or :doc:`locator `. - .. versionadded:: 7.1 - - The automatic addition of the ``rate_limiter`` tag was introduced - in Symfony 7.1. - Rate Limiting in Action ----------------------- @@ -262,7 +224,7 @@ argument named ``$anonymousApiLimiter``:: When :ref:`dealing with multiple implementations of the same type ` the ``#[Target]`` attribute helps you select which one to inject. Symfony creates -a target called "rate limiter name" + ``.limiter`` suffix. +a target with the same name as the rate limiter. For example, to select the ``anonymous_api`` limiter defined earlier, use ``anonymous_api.limiter`` as the target:: @@ -273,19 +235,13 @@ For example, to select the ``anonymous_api`` limiter defined earlier, use class ApiController extends AbstractController { public function index( - #[Target('anonymous_api.limiter')] RateLimiterFactoryInterface $rateLimiter + #[Target('anonymous_api')] RateLimiterFactoryInterface $rateLimiter ): Response { // ... } } -.. versionadded:: 7.3 - - :class:`Symfony\\Component\\RateLimiter\\RateLimiterFactoryInterface` was - added and should now be used for autowiring instead of - :class:`Symfony\\Component\\RateLimiter\\RateLimiterFactory`. - Using the Rate Limiter Service ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -462,33 +418,6 @@ You can use the ``cache_pool`` option to override the cache used by a specific l # use the "cache.anonymous_rate_limiter" cache pool cache_pool: 'cache.anonymous_rate_limiter' - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/rate_limiter.php @@ -541,41 +470,6 @@ at all): # or don't use any lock mechanism lock_factory: null - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/rate_limiter.php @@ -594,19 +488,9 @@ at all): ; }; -.. versionadded:: 7.3 - - Before Symfony 7.3, configuring a rate limiter and using the default configured - lock factory (``lock.factory``) failed if the Symfony Lock component was not - installed in the application. - Compound Rate Limiter --------------------- -.. versionadded:: 7.3 - - Support for configuring compound rate limiters was introduced in Symfony 7.3. - You can configure multiple rate limiters to work together: .. configuration-block:: @@ -628,42 +512,6 @@ You can configure multiple rate limiters to work together: policy: 'compound' limiters: [two_per_minute, five_per_hour] - .. code-block:: xml - - - - - - - - - - - - - two_per_minute - five_per_hour - - - - - .. code-block:: php // config/packages/rate_limiter.php diff --git a/reference/attributes.rst b/reference/attributes.rst index 968c7df1568..76fdf1477e4 100644 --- a/reference/attributes.rst +++ b/reference/attributes.rst @@ -39,17 +39,10 @@ Dependency Injection * :ref:`AutowireServiceClosure ` * :ref:`Exclude ` * :ref:`Lazy ` -* :ref:`TaggedIterator ` -* :ref:`TaggedLocator ` * :ref:`Target ` * :ref:`When ` * :ref:`WhenNot ` -.. deprecated:: 7.1 - - The :class:`Symfony\\Component\\DependencyInjection\\Attribute\\TaggedIterator` - and :class:`Symfony\\Component\\DependencyInjection\\Attribute\\TaggedLocator` - attributes were deprecated in Symfony 7.1. EventDispatcher ~~~~~~~~~~~~~~~ diff --git a/reference/configuration/debug.rst b/reference/configuration/debug.rst index 6ca05b49bd7..70d47775b5d 100644 --- a/reference/configuration/debug.rst +++ b/reference/configuration/debug.rst @@ -17,12 +17,6 @@ key in your application configuration. # environment variables with their actual values $ php bin/console debug:config --resolve-env debug -.. note:: - - When using XML, you must use the ``http://symfony.com/schema/dic/debug`` - namespace and the related XSD schema is available at: - ``https://symfony.com/schema/dic/debug/debug-1.0.xsd`` - .. _configuration-debug-dump_destination: dump_destination @@ -45,20 +39,6 @@ Typically, you would set this to ``php://stderr``: debug: dump_destination: php://stderr - .. code-block:: xml - - - - - - - - .. code-block:: php // config/packages/debug.php diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index 6a45dfefcb5..b662a5798b3 100644 --- a/reference/configuration/doctrine.rst +++ b/reference/configuration/doctrine.rst @@ -14,19 +14,13 @@ configuration. # displays the actual config values used by your application $ php bin/console debug:config doctrine -.. note:: - - When using XML, you must use the ``http://symfony.com/schema/dic/doctrine`` - namespace and the related XSD schema is available at: - ``https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd`` - .. _`reference-dbal-configuration`: Doctrine DBAL Configuration --------------------------- DoctrineBundle supports all parameters that default Doctrine drivers -accept, converted to the XML or YAML naming standards that Symfony +accept, converted to the YAML or PHP naming standards that Symfony enforces. See the Doctrine `DBAL documentation`_ for more information. The following block shows all possible configuration keys: @@ -63,43 +57,6 @@ The following block shows all possible configuration keys: types: custom: App\DBAL\MyCustomType - .. code-block:: xml - - - - - - - - bar - string - App\DBAL\MyCustomType - - - - .. code-block:: php use Symfony\Config\DoctrineConfig; @@ -554,22 +511,6 @@ directory instead: type: xml dir: SomeResources/config/doctrine - .. code-block:: xml - - - - - - - - - - - .. code-block:: php use Symfony\Config\DoctrineConfig; @@ -608,28 +549,6 @@ namespace in the ``src/Entity`` directory and gives them an ``App`` alias prefix: App\Entity alias: App - .. code-block:: xml - - - - - - - - - - - .. code-block:: php use Symfony\Config\DoctrineConfig; @@ -703,30 +622,6 @@ set up the connection using environment variables for the certificate paths: # SSL CA authority !php/const 'PDO::MYSQL_ATTR_SSL_CA': '%env(MYSQL_SSL_CA)%' - .. code-block:: xml - - - - - - - - %env(MYSQL_SSL_KEY)% - %env(MYSQL_SSL_CERT)% - %env(MYSQL_SSL_CA)% - - - - .. code-block:: php // config/packages/doctrine.php diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 5eef19de7f2..f652c863b49 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -13,50 +13,6 @@ configured under the ``framework`` key in your application configuration. # displays the actual config values used by your application $ php bin/console debug:config framework -.. note:: - - When using XML, you must use the ``http://symfony.com/schema/dic/symfony`` - namespace and the related XSD schema is available at: - ``https://symfony.com/schema/dic/symfony/symfony-1.0.xsd`` - -annotations -~~~~~~~~~~~ - -.. _reference-annotations-cache: - -cache -..... - -**type**: ``string`` **default**: ``php_array`` - -This option can be one of the following values: - -php_array - Use a PHP array to cache annotations in memory -file - Use the filesystem to cache annotations -none - Disable the caching of annotations - -debug -..... - -**type**: ``boolean`` **default**: ``%kernel.debug%`` - -Whether to enable debug mode for caching. If enabled, the cache will -automatically update when the original file is changed (both with code and -annotation changes). For performance reasons, it is recommended to disable -debug mode in production, which will happen automatically if you use the -default value. - -file_cache_dir -.............. - -**type**: ``string`` **default**: ``%kernel.cache_dir%/annotations`` - -The directory to store cache files for annotations, in case -``annotations.cache`` is set to ``'file'``. - .. _reference-assets: assets @@ -84,22 +40,6 @@ This option allows you to prepend a base path to the URLs generated for assets: assets: base_path: '/images' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -137,22 +77,6 @@ collection each time it generates an asset's path: base_urls: - 'http://cdn.example.com/' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -209,34 +133,6 @@ package: # this package uses the global manifest (the default file is used) base_path: '/images' - .. code-block:: xml - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -301,7 +197,7 @@ to inject the ``foo_package`` package defined earlier:: When :ref:`dealing with multiple implementations of the same type ` the ``#[Target]`` attribute helps you select which one to inject. Symfony creates -a target called "asset package name" + ``.package`` suffix. +a target with the same name as the asset package. For example, to select the ``foo_package`` package defined earlier:: @@ -311,7 +207,7 @@ For example, to select the ``foo_package`` package defined earlier:: class SomeService { public function __construct( - #[Target('foo_package.package')] private PackageInterface $package + #[Target('foo_package')] private PackageInterface $package ): void { // ... } @@ -336,26 +232,6 @@ You can group assets into packages, to specify different base URLs for them: avatars: base_urls: 'http://static_cdn.example.com/avatars' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -427,22 +303,6 @@ Now, activate the ``version`` option: assets: version: 'v2' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -543,34 +403,6 @@ individually for each asset package: # this package inherits the default strategy base_path: '/images' - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -701,29 +533,6 @@ To configure a Redis cache pool with a default lifetime of 1 hour, do the follow adapter: cache.adapter.redis default_lifetime: 3600 - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -870,22 +679,6 @@ can also :ref:`disable CSRF protection on individual forms - - - - - - - .. code-block:: php // config/packages/framework.php @@ -907,10 +700,6 @@ stateless_token_ids The list of CSRF token ids that will use :ref:`stateless CSRF protection `. -.. versionadded:: 7.2 - - The ``stateless_token_ids`` option was introduced in Symfony 7.2. - check_header ............ @@ -922,10 +711,6 @@ this to ``2`` (the value of the ``CHECK_ONLY_HEADER`` constant on the :class:`Symfony\\Component\\Security\\Csrf\\SameOriginCsrfTokenManager` class) to check only the header and ignore the cookie. -.. versionadded:: 7.2 - - The ``check_header`` option was introduced in Symfony 7.2. - cookie_name ........... @@ -934,10 +719,6 @@ cookie_name The name of the cookie (and HTTP header) to use for the double-submit when using :ref:`stateless CSRF protection `. -.. versionadded:: 7.2 - - The ``cookie_name`` option was introduced in Symfony 7.2. - .. _config-framework-default_locale: default_locale @@ -976,23 +757,6 @@ performance a bit: framework: enabled_locales: ['en', 'es'] - .. code-block:: xml - - - - - - - en - es - - - .. code-block:: php // config/packages/translation.php @@ -1077,22 +841,6 @@ You can also set ``esi`` to ``true`` to enable it: framework: esi: true - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1124,28 +872,6 @@ and HTTP status code applied to the exceptions that match the given exception cl status_code: 422 log_channel: 'custom_channel' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/exceptions.php @@ -1160,10 +886,6 @@ and HTTP status code applied to the exceptions that match the given exception cl ; }; -.. versionadded:: 7.3 - - The ``log_channel`` option was introduced in Symfony 7.3. - The order in which you configure exceptions is important because Symfony will use the configuration of the first exception that matches ``instanceof``: @@ -1223,11 +945,6 @@ The attributes can also be added to interfaces directly:: { } -.. versionadded:: 7.1 - - Support to use ``#[WithHttpStatus]`` and ``#[WithLogLevel]`` attributes - on interfaces was introduced in Symfony 7.1. - .. _reference-framework-form: form @@ -1464,26 +1181,6 @@ This service can be configured using ``framework.http_client.default_options``: headers: { 'X-Powered-By': 'ACME App' } max_redirects: 7 - .. code-block:: xml - - - - - - - - - ACME App - - - - - .. code-block:: php // config/packages/framework.php @@ -1528,24 +1225,6 @@ these options and can define a few others: auth_bearer: secret_bearer_token # ... - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1656,6 +1335,72 @@ If this option is a boolean value, the response is buffered when the value is returned value is ``true`` (the closure receives as argument an array with the response headers). +caching +....... + +**type**: ``array`` + +This option configures the behavior of the :ref:`HTTP client caching `, +including which types of requests to cache and how many times. The behavior is +defined with the following options: + +* :ref:`cache_pool ` +* :ref:`shared ` +* :ref:`max_ttl ` + +.. code-block:: yaml + + # config/packages/framework.yaml + framework: + # ... + http_client: + # ... + default_options: + caching: + cache_pool: cache.app + shared: true + max_ttl: 86400 + + scoped_clients: + my_api.client: + # ... + caching: + cache_pool: my_taggable_pool + +.. _reference-http-client-caching-cache-pool: + +cache_pool +"""""""""" + +**type**: ``string`` + +The service ID of the cache pool used to store the cached responses. The service +must implement the :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface`. + +By default, it uses an instance of :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter` +wrapping the ``cache.app`` pool. + +.. _reference-http-client-caching-shared: + +shared +"""""" + +**type**: ``boolean`` **default**: ``true`` + +If ``true``, it uses a `shared cache`_ so cached responses can be reused across +users. Set it to ``false`` to use a `private cache`_. + +.. _reference-http-client-caching-max-ttl: + +max_ttl +""""""" + +**type**: ``integer`` **default**: ``null`` + +The maximum time-to-live (in seconds) for cached responses. By default, responses +are cached for as long as the TTL specified by the server. When this option is +set, server-provided TTLs are capped to this value. + cafile ...... @@ -1813,10 +1558,6 @@ The service ID of the rate limiter used to limit the number of HTTP requests within a certain period. The service must implement the :class:`Symfony\\Component\\RateLimiter\\LimiterInterface`. -.. versionadded:: 7.1 - - The ``rate_limiter`` option was introduced in Symfony 7.1. - resolve ....... @@ -2034,6 +1775,62 @@ named ``kernel.http_method_override``. $request = Request::createFromGlobals(); // ... +.. _configuration-framework-allowed_http_method_override: + +allowed_http_method_override +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``null`` + +This option controls which HTTP methods can be overridden via the ``_method`` +request parameter or the ``X-HTTP-METHOD-OVERRIDE`` header when +:ref:`http_method_override ` is enabled. + +When set to ``null`` (the default), all HTTP methods can be overridden. When set +to an empty array (``[]``), HTTP method overriding is completely disabled. When +set to a specific list of methods, only those methods will be allowed as overrides: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/framework.yaml + framework: + http_method_override: true + # Only allow PUT, PATCH, and DELETE to be overridden + allowed_http_method_override: ['PUT', 'PATCH', 'DELETE'] + + .. code-block:: php + + // config/packages/framework.php + use Symfony\Config\FrameworkConfig; + + return static function (FrameworkConfig $framework): void { + $framework + ->httpMethodOverride(true) + ->allowedHttpMethodOverride(['PUT', 'PATCH', 'DELETE']) + ; + }; + +This security feature is useful for hardening your application by explicitly +defining which methods can be tunneled through POST requests. For example, if +your application only needs to override POST requests to PUT and DELETE, you +can restrict the allowed methods accordingly. + +You can also configure this programmatically using the +:method:`Request::setAllowedHttpMethodOverride ` +method:: + + // public/index.php + + // ... + $kernel = new CacheKernel($kernel); + + Request::enableHttpMethodParameterOverride(); + Request::setAllowedHttpMethodOverride(['PUT', 'PATCH', 'DELETE']); + $request = Request::createFromGlobals(); + // ... + .. _reference-framework-ide: ide @@ -2065,20 +1862,6 @@ doubling them to prevent Symfony from interpreting them as container parameters) framework: ide: 'myide://open?url=file://%%f&line=%%l' - .. code-block:: xml - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -2174,24 +1957,6 @@ the name as key and DSN or service id as value: framework: lock: '%env(LOCK_DSN)%' - .. code-block:: xml - - - - - - - - %env(LOCK_DSN)% - - - - .. code-block:: php // config/packages/lock.php @@ -2250,26 +2015,6 @@ the `SMTP session`_. This value overrides any other recipient set in the code. envelope: recipients: ['admin@symfony.com', 'lead@symfony.com'] - .. code-block:: xml - - - - - - - - admin@symfony.com - lead@symfony.com - - - - - .. code-block:: php // config/packages/mailer.php @@ -2384,27 +2129,6 @@ This option also accepts a map of PHP errors to log levels: !php/const \E_ERROR: !php/const Psr\Log\LogLevel::CRITICAL !php/const \E_CORE_ERROR: !php/const Psr\Log\LogLevel::CRITICAL - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -2456,21 +2180,6 @@ Combine it with the ``collect`` option to enable/disable the profiler on demand: request and has value of ``true``, ``yes``, ``on`` or ``1``, the request data will be collected. -.. _collect_serializer_data: - -collect_serializer_data -....................... - -**type**: ``boolean`` **default**: ``false`` - -When this option is ``true``, all normalizers and encoders are -decorated by traceable implementations that collect profiling information about them. - -.. deprecated:: 7.3 - - Setting the ``collect_serializer_data`` option to ``false`` is deprecated - since Symfony 7.3. - .. _profiler-dsn: dsn @@ -2574,16 +2283,15 @@ enabled with_constructor_extractor .......................... -**type**: ``boolean`` **default**: ``false`` +**type**: ``boolean`` **default**: ``true`` Configures the ``property_info`` service to extract property information from the constructor arguments using the :ref:`ConstructorExtractor `. -.. versionadded:: 7.3 +.. versionadded:: 8.0 - The ``with_constructor_extractor`` option was introduced in Symfony 7.3. - It's required to set a value for it because its default value will change - from ``false`` to ``true`` in Symfony 8.0. + The default value of the ``with_constructor_extractor`` option was changed + to ``true`` in Symfony 8.0. rate_limiter ~~~~~~~~~~~~ @@ -2644,28 +2352,6 @@ To configure a ``jsonp`` format: formats: jsonp: 'application/javascript' - .. code-block:: xml - - - - - - - - - - application/javascript - - - - - .. code-block:: php // config/packages/framework.php @@ -2679,19 +2365,6 @@ To configure a ``jsonp`` format: router ~~~~~~ -cache_dir -......... - -**type**: ``string`` **default**: ``%kernel.cache_dir%`` - -The directory where routing information will be cached. Can be set to -``~`` (``null``) to disable route caching. - -.. deprecated:: 7.1 - - Setting the ``cache_dir`` option is deprecated since Symfony 7.1. The routes - are now always cached in the ``%kernel.build_dir%`` directory. - default_uri ........... @@ -2869,24 +2542,6 @@ the name as key and DSN or service id as value: framework: semaphore: '%env(SEMAPHORE_DSN)%' - .. code-block:: xml - - - - - - - - %env(SEMAPHORE_DSN)% - - - - .. code-block:: php // config/packages/semaphore.php @@ -3018,22 +2673,6 @@ Unlike the other session options, ``cache_limiter`` is set as a regular session.storage.options: cache_limiter: 0 - .. code-block:: xml - - - - - - - - 0 - - - - .. code-block:: php // config/services.php @@ -3141,22 +2780,6 @@ Whether to enable the session support in the framework. session: enabled: true - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -3200,11 +2823,6 @@ chance that the GC process will start on each request. If not set, Symfony will use the value of the `session.gc_probability`_ directive in the ``php.ini`` configuration file. -.. versionadded:: 7.2 - - Relying on ``php.ini``'s directive as default for ``gc_probability`` was - introduced in Symfony 7.2. - .. _config-framework-session-handler-id: handler_id @@ -3233,26 +2851,6 @@ and also to configure the session handler with a DSN: handler_id: '%env(DATABASE_URL)%' handler_id: 'file://%kernel.project_dir%/var/sessions' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -3330,22 +2928,6 @@ If ``null``, ``php.ini``'s `session.save_path`_ directive will be relied on: session: save_path: ~ - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -3356,39 +2938,6 @@ If ``null``, ``php.ini``'s `session.save_path`_ directive will be relied on: ->savePath(null); }; -sid_bits_per_character -...................... - -**type**: ``integer`` - -This determines the number of bits in the encoded session ID character. The possible -values are ``4`` (0-9, a-f), ``5`` (0-9, a-v), and ``6`` (0-9, a-z, A-Z, "-", ","). -The more bits results in stronger session ID. ``5`` is recommended value for -most environments. - -If not set, ``php.ini``'s `session.sid_bits_per_character`_ directive will be relied on. - -.. deprecated:: 7.2 - - The ``sid_bits_per_character`` option was deprecated in Symfony 7.2. No alternative - is provided as PHP 8.4 has deprecated the related option. - -sid_length -.......... - -**type**: ``integer`` - -This determines the length of session ID string, which can be an integer between -``22`` and ``256`` (both inclusive), ``32`` being the recommended value. Longer -session IDs are harder to guess. - -If not set, ``php.ini``'s `session.sid_length`_ directive will be relied on. - -.. deprecated:: 7.2 - - The ``sid_length`` option was deprecated in Symfony 7.2. No alternative is - provided as PHP 8.4 has deprecated the related option. - .. _storage_id: storage_factory_id @@ -3536,11 +3085,6 @@ trust_x_sendfile_type_header **type**: ``boolean`` **default**: ``%env(bool:default::SYMFONY_TRUST_X_SENDFILE_TYPE_HEADER)%`` -.. versionadded:: 7.2 - - In Symfony 7.2, the default value of this option was changed from ``false`` to the - value stored in the ``SYMFONY_TRUST_X_SENDFILE_TYPE_HEADER`` environment variable. - ``X-Sendfile`` is a special HTTP header that tells web servers to replace the response contents by the file that is defined in that header. This improves performance because files are no longer served by your application but directly @@ -3568,11 +3112,6 @@ trusted_hosts **type**: ``array`` | ``string`` **default**: ``['%env(default::SYMFONY_TRUSTED_HOSTS)%']`` -.. versionadded:: 7.2 - - In Symfony 7.2, the default value of this option was changed from ``[]`` to the - value stored in the ``SYMFONY_TRUSTED_HOSTS`` environment variable. - A lot of different attacks have been discovered relying on inconsistencies in handling the ``Host`` header by various software (web servers, reverse proxies, web frameworks, etc.). Basically, every time the framework is @@ -3600,24 +3139,6 @@ the application won't respond and the user will receive a 400 response. framework: trusted_hosts: ['^example\.com$', '^example\.org$'] - .. code-block:: xml - - - - - - - ^example\.com$ - ^example\.org$ - - - - .. code-block:: php // config/packages/framework.php @@ -3679,29 +3200,6 @@ Defines the Doctrine entities that will be introspected to add 'App\Entity\': [] 'Foo\': ['Foo\Some\Entity', 'Foo\Another\Entity'] - .. code-block:: xml - - - - - - - - - - - Foo\Some\Entity - Foo\Another\Entity - - - - - .. code-block:: php // config/packages/framework.php @@ -3728,10 +3226,6 @@ locale. Set this option to ``true`` to disable translation of validation message This is useful to avoid "missing translation" errors in applications that use only a single language. -.. versionadded:: 7.3 - - The ``disable_translation`` option was introduced in Symfony 7.3. - .. _reference-validation-email_validation_mode: email_validation_mode @@ -3789,26 +3283,6 @@ the component will look for additional validation files: paths: - "%kernel.project_dir%/config/validation/" - .. code-block:: xml - - - - - - - - - %kernel.project_dir%/config/validation/ - - - - - .. code-block:: php // config/packages/framework.php @@ -3903,26 +3377,6 @@ A list of workflows to be created by the framework extension: my_workflow: # ... - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/workflow.php @@ -4064,8 +3518,6 @@ to know their differences. .. _`session.gc_divisor`: https://www.php.net/manual/en/session.configuration.php#ini.session.gc-divisor .. _`session.gc_probability`: https://www.php.net/manual/en/session.configuration.php#ini.session.gc-probability .. _`session.gc_maxlifetime`: https://www.php.net/manual/en/session.configuration.php#ini.session.gc-maxlifetime -.. _`session.sid_length`: https://www.php.net/manual/en/session.configuration.php#ini.session.sid-length -.. _`session.sid_bits_per_character`: https://www.php.net/manual/en/session.configuration.php#ini.session.sid-bits-per-character .. _`session.save_path`: https://www.php.net/manual/en/session.configuration.php#ini.session.save-path .. _`session.use_cookies`: https://www.php.net/manual/en/session.configuration.php#ini.session.use-cookies .. _`Microsoft NTLM authentication protocol`: https://docs.microsoft.com/en-us/windows/win32/secauthn/microsoft-ntlm @@ -4073,3 +3525,5 @@ to know their differences. .. _`Link HTTP header`: https://tools.ietf.org/html/rfc5988 .. _`SMTP session`: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#SMTP_transport_example .. _`PHP attributes`: https://www.php.net/manual/en/language.attributes.overview.php +.. _`shared cache`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#shared_cache +.. _`private cache`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#private_caches diff --git a/reference/configuration/kernel.rst b/reference/configuration/kernel.rst index b7596182906..4bca061199d 100644 --- a/reference/configuration/kernel.rst +++ b/reference/configuration/kernel.rst @@ -138,20 +138,6 @@ achieve a strict reproducible build: # ... kernel.container_build_time: '1234567890' - .. code-block:: xml - - - - - - - - 1234567890 - - - .. code-block:: php // config/services.php @@ -347,6 +333,17 @@ servers support it, and you have to use a long-running web server like `FrankenP This parameter stores the value of :ref:`the framework.secret parameter `. +``kernel.share_dir`` +-------------------- + +**type**: ``string`` **default**: ``$this->getCacheDir()`` + +This parameter stores the absolute path of the shared cache directory of your Symfony +application. The default value is the current cache directory. + +This value is also exposed via the :method:`Symfony\\Component\\HttpKernel\\Kernel::getShareDir` +method of the kernel class, which you can override to return a different value. + ``kernel.trust_x_sendfile_type_header`` --------------------------------------- diff --git a/reference/configuration/monolog.rst b/reference/configuration/monolog.rst index 3e1ffab21a8..d7259303a9d 100644 --- a/reference/configuration/monolog.rst +++ b/reference/configuration/monolog.rst @@ -13,12 +13,6 @@ in your application configuration. # displays the actual config values used by your application $ php bin/console debug:config monolog -.. note:: - - When using XML, you must use the ``http://symfony.com/schema/dic/monolog`` - namespace and the related XSD schema is available at: - ``https://symfony.com/schema/dic/monolog/monolog-1.0.xsd`` - .. tip:: For a full list of handler types and related configuration options, see @@ -30,4 +24,4 @@ in your application configuration. messages in the profiler. The profiler uses the name "debug" so it is reserved and cannot be used in the configuration. -.. _`Monolog Configuration`: https://github.com/symfony/monolog-bundle/blob/3.x/src/DependencyInjection/Configuration.php +.. _`Monolog Configuration`: https://github.com/symfony/monolog-bundle/blob/4.x/src/DependencyInjection/Configuration.php diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst index 9a61cc5c62b..f5382376cc0 100644 --- a/reference/configuration/security.rst +++ b/reference/configuration/security.rst @@ -13,18 +13,10 @@ key in your application configuration. # displays the actual config values used by your application $ php bin/console debug:config security -.. note:: - - When using XML, you must use the ``http://symfony.com/schema/dic/security`` - namespace and the related XSD schema is available at: - ``https://symfony.com/schema/dic/services/services-1.0.xsd`` - **Basic Options**: * `access_denied_url`_ -* `erase_credentials`_ * `expose_security_errors`_ -* `hide_user_not_found`_ (deprecated) * `session_fixation_strategy`_ **Advanced Options**: @@ -46,41 +38,11 @@ access_denied_url Defines the URL where the user is redirected after a ``403`` HTTP error (unless you define a custom access denial handler). Example: ``/no-permission`` -erase_credentials ------------------ - -**type**: ``boolean`` **default**: ``true`` - -If ``true``, the ``eraseCredentials()`` method of the user object is called -after authentication:: - - use Symfony\Component\Security\Core\User\UserInterface; - - class User implements UserInterface - { - // ... - - public function eraseCredentials(): void - { - // If you store any temporary, sensitive data on the user, clear it here - // $this->plainPassword = null; - } - } - -.. deprecated:: 7.3 - - Since Symfony 7.3, ``eraseCredentials()`` methods are deprecated and are - not called if they have the ``#[\Deprecated]`` attribute. - expose_security_errors ---------------------- **type**: ``string`` **default**: ``'none'`` -.. versionadded:: 7.3 - - The ``expose_security_errors`` option was introduced in Symfony 7.3 - User enumeration is a common security issue where attackers infer valid usernames based on error messages. For example, a message like "This user does not exist" shown by your login form reveals whether a username exists. @@ -95,24 +57,6 @@ option can be one of the following: accounts) but only for users who provided the correct password; * ``'all'``: shows all security-related exceptions. -hide_user_not_found -------------------- - -**type**: ``boolean`` **default**: ``true`` - -.. deprecated:: 7.3 - - The ``hide_user_not_found`` option was deprecated in favor of the - ``expose_security_errors`` option in Symfony 7.3. - -If ``true``, when a user is not found a generic exception of type -:class:`Symfony\\Component\\Security\\Core\\Exception\\BadCredentialsException` -is thrown with the message "Bad credentials". - -If ``false``, the exception thrown is of type -:class:`Symfony\\Component\\Security\\Core\\Exception\\UserNotFoundException` -and it includes the given not found user identifier. - session_fixation_strategy ------------------------- @@ -164,30 +108,6 @@ application: # the rest of options depend on the authentication mechanism # ... - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -425,30 +345,6 @@ user logs out: path: null domain: example.com - .. code-block:: xml - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -496,29 +392,6 @@ It's also possible to use ``*`` as a wildcard for all directives: - cookies - storage - .. code-block:: xml - - - - - - - - - - - - cookies - storage - - - - - .. code-block:: php // config/packages/security.php @@ -649,27 +522,6 @@ The security configuration should be: username_path: security.credentials.login password_path: security.credentials.password - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -771,32 +623,6 @@ X.509 Authentication credentials: SSL_CLIENT_S_DN user_identifier: emailAddress - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -862,26 +688,6 @@ Remote User Authentication provider: your_user_provider user: REMOTE_USER - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -941,28 +747,6 @@ multiple firewalls, the "context" could actually be shared: # ... context: my_context - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -1008,25 +792,6 @@ the session must not be used when authenticating users: # ... stateless: true - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -1060,25 +825,6 @@ session only if the application actually accesses the User object, (e.g. calling # ... lazy: true - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -1117,27 +863,6 @@ Firewalls can configure a list of required badges that must be present on the au # ... required_badges: ['CsrfTokenBadge', 'My\Badge'] - .. code-block:: xml - - - - - - - - - CsrfTokenBadge - My\Badge - - - - .. code-block:: php // config/packages/security.php diff --git a/reference/configuration/twig.rst b/reference/configuration/twig.rst index 360309fef8f..6aede0b2ae6 100644 --- a/reference/configuration/twig.rst +++ b/reference/configuration/twig.rst @@ -13,12 +13,6 @@ under the ``twig`` key in your application configuration. # displays the actual config values used by your application $ php bin/console debug:config twig -.. note:: - - When using XML, you must use the ``http://symfony.com/schema/dic/twig`` - namespace and the related XSD schema is available at: - ``https://symfony.com/schema/dic/twig/twig-1.0.xsd`` - auto_reload ~~~~~~~~~~~ @@ -54,20 +48,6 @@ called to determine the default escaping applied to the template. If the service defined in ``autoescape_service`` is invocable (i.e. it defines the `__invoke() PHP magic method`_) you can omit this option. -base_template_class -~~~~~~~~~~~~~~~~~~~ - -**type**: ``string`` **default**: ``Twig\Template`` - -.. deprecated:: 7.1 - - The ``base_template_class`` option is deprecated since Symfony 7.1. - -Twig templates are compiled into PHP classes before using them to render -contents. This option defines the base class from which all the template classes -extend. Using a custom base template is discouraged because it will make your -application harder to maintain. - cache ~~~~~ @@ -87,12 +67,6 @@ Set this option to ``false`` to disable Twig template compilation. However, this is not recommended, not even in the ``dev`` environment, because the ``auto_reload`` option ensures that cached templates which have changed get compiled again. -.. versionadded:: 7.3 - - Support for using ``true`` as a value was introduced in Symfony 7.3. It also - became the default value for this option, replacing the explicit path - ``%kernel.cache_dir%/twig``. - charset ~~~~~~~ @@ -183,24 +157,6 @@ The value of this option can be a regular expression, a glob, or a string: file_name_pattern: ['*.twig', 'specific_file.html'] # ... - .. code-block:: xml - - - - - - - *.twig - specific_file.html - - - - .. code-block:: php // config/packages/twig.php @@ -234,24 +190,6 @@ all the forms of the application: form_themes: ['bootstrap_5_layout.html.twig', 'form/my_theme.html.twig'] # ... - .. code-block:: xml - - - - - - - bootstrap_5_layout.html.twig - form/my_theme.html.twig - - - - .. code-block:: php // config/packages/twig.php @@ -366,23 +304,6 @@ the directory defined in the :ref:`default_path option - - - - - email/default/templates - backend/templates - - - .. code-block:: php // config/packages/twig.php diff --git a/reference/configuration/web_profiler.rst b/reference/configuration/web_profiler.rst index c3b57d37c55..7c6085827fd 100644 --- a/reference/configuration/web_profiler.rst +++ b/reference/configuration/web_profiler.rst @@ -14,12 +14,6 @@ under the ``web_profiler`` key in your application configuration. # displays the actual config values used by your application $ php bin/console debug:config web_profiler -.. note:: - - When using XML, you must use the ``http://symfony.com/schema/dic/webprofiler`` - namespace and the related XSD schema is available at: - ``https://symfony.com/schema/dic/webprofiler/webprofiler-1.0.xsd`` - .. warning:: The web debug toolbar is not available for responses of type ``StreamedResponse``. @@ -67,7 +61,3 @@ ajax_replace If you set this option to ``true``, the toolbar is replaced on AJAX requests. This only works in combination with an enabled toolbar. - -.. versionadded:: 7.3 - - The ``ajax_replace`` configuration option was introduced in Symfony 7.3. diff --git a/reference/constraints/All.rst b/reference/constraints/All.rst index 43ff4d6ac9d..127b005a01c 100644 --- a/reference/constraints/All.rst +++ b/reference/constraints/All.rst @@ -41,9 +41,10 @@ entry in that array: properties: favoriteColors: - All: - - NotBlank: ~ - - Length: - min: 5 + constraints: + - NotBlank: ~ + - Length: + min: 5 .. code-block:: xml diff --git a/reference/constraints/AtLeastOneOf.rst b/reference/constraints/AtLeastOneOf.rst index fecbe617f5a..c4be1657dfc 100644 --- a/reference/constraints/AtLeastOneOf.rst +++ b/reference/constraints/AtLeastOneOf.rst @@ -53,7 +53,8 @@ The following constraints ensure that: properties: password: - AtLeastOneOf: - - Regex: '/#/' + - Regex: + pattern: '/#/' - Length: min: 10 grades: @@ -61,7 +62,9 @@ The following constraints ensure that: - Count: min: 3 - All: - - GreaterThanOrEqual: 5 + constraints: + - GreaterThanOrEqual: + value: 5 .. code-block:: xml @@ -93,7 +96,7 @@ The following constraints ensure that: diff --git a/reference/constraints/Bic.rst b/reference/constraints/Bic.rst index 6cde4a11bac..5b2be9ed738 100644 --- a/reference/constraints/Bic.rst +++ b/reference/constraints/Bic.rst @@ -132,8 +132,4 @@ as constants in the :class:`Symfony\\Component\\Validator\\Constraints\\Bic` cla * ``Bic::VALIDATION_MODE_STRICT`` validates the given value without any modification; * ``Bic::VALIDATION_MODE_CASE_INSENSITIVE`` converts the given value to uppercase before validating it. -.. versionadded:: 7.2 - - The ``mode`` option was introduced in Symfony 7.2. - .. _`Business Identifier Code (BIC)`: https://en.wikipedia.org/wiki/Business_Identifier_Code diff --git a/reference/constraints/Callback.rst b/reference/constraints/Callback.rst index 017b9435cff..197312f1812 100644 --- a/reference/constraints/Callback.rst +++ b/reference/constraints/Callback.rst @@ -50,7 +50,8 @@ Configuration # config/validator/validation.yaml App\Entity\Author: constraints: - - Callback: validate + - Callback: + callback: validate .. code-block:: xml @@ -61,7 +62,9 @@ Configuration xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - validate + + + @@ -177,7 +180,8 @@ You can then use the following configuration to invoke this validator: # config/validator/validation.yaml App\Entity\Author: constraints: - - Callback: [Acme\Validator, validate] + - Callback: + callback: [Acme\Validator, validate] .. code-block:: xml @@ -189,8 +193,10 @@ You can then use the following configuration to invoke this validator: - Acme\Validator - validate + diff --git a/reference/constraints/Charset.rst b/reference/constraints/Charset.rst index 084f24cdf76..d7af01a9dad 100644 --- a/reference/constraints/Charset.rst +++ b/reference/constraints/Charset.rst @@ -1,10 +1,6 @@ Charset ======= -.. versionadded:: 7.1 - - The ``Charset`` constraint was introduced in Symfony 7.1. - Validates that a string (or an object implementing the ``Stringable`` PHP interface) is encoded in a given charset. @@ -41,7 +37,8 @@ class uses UTF-8, you could do the following: App\Entity\FileDTO: properties: content: - - Charset: 'UTF-8' + - Charset: + charset: 'UTF-8' .. code-block:: xml diff --git a/reference/constraints/Choice.rst b/reference/constraints/Choice.rst index 6378ed67cfb..ffc0f248c5b 100644 --- a/reference/constraints/Choice.rst +++ b/reference/constraints/Choice.rst @@ -34,7 +34,7 @@ If your valid choice list is simple, you can pass them in directly via the { public const GENRES = ['fiction', 'non-fiction']; - #[Assert\Choice(['New York', 'Berlin', 'Tokyo'])] + #[Assert\Choice(choices: ['New York', 'Berlin', 'Tokyo'])] protected string $city; #[Assert\Choice(choices: Author::GENRES, message: 'Choose a valid genre.')] @@ -47,7 +47,8 @@ If your valid choice list is simple, you can pass them in directly via the App\Entity\Author: properties: city: - - Choice: [New York, Berlin, Tokyo] + - Choice: + choices: [New York, Berlin, Tokyo] genre: - Choice: choices: [fiction, non-fiction] @@ -64,9 +65,11 @@ If your valid choice list is simple, you can pass them in directly via the - New York - Berlin - Tokyo + @@ -97,7 +100,7 @@ If your valid choice list is simple, you can pass them in directly via the { $metadata->addPropertyConstraint( 'city', - new Assert\Choice(['New York', 'Berlin', 'Tokyo']) + new Assert\Choice(choices: ['New York', 'Berlin', 'Tokyo']) ); $metadata->addPropertyConstraint('genre', new Assert\Choice( diff --git a/reference/constraints/Cidr.rst b/reference/constraints/Cidr.rst index 78a5b6c7167..75f3b04aba1 100644 --- a/reference/constraints/Cidr.rst +++ b/reference/constraints/Cidr.rst @@ -134,8 +134,4 @@ of :ref:`IP version ranges `. considered ``*_public``, but it also includes the ``10.0.0.0/8`` range, which is categorized as ``*_private``. -.. versionadded:: 7.1 - - The support of all IP version ranges was introduced in Symfony 7.1. - .. _`CIDR`: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing diff --git a/reference/constraints/Compound.rst b/reference/constraints/Compound.rst index 67e3f41233d..07a292aacb2 100644 --- a/reference/constraints/Compound.rst +++ b/reference/constraints/Compound.rst @@ -141,11 +141,6 @@ Validation groups and payload can be passed via constructor: } } -.. versionadded:: 7.2 - - Support for passing validation groups and the payload to the constructor - of the ``Compound`` class was introduced in Symfony 7.2. - Options ------- diff --git a/reference/constraints/DateTime.rst b/reference/constraints/DateTime.rst index ffcfbf55dda..73bf7592f04 100644 --- a/reference/constraints/DateTime.rst +++ b/reference/constraints/DateTime.rst @@ -107,8 +107,4 @@ Parameter Description ``{{ format }}`` The date format defined in ``format`` ================ ============================================================== -.. versionadded:: 7.3 - - The ``{{ format }}`` parameter was introduced in Symfony 7.3. - .. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/DivisibleBy.rst b/reference/constraints/DivisibleBy.rst index 23b36023cff..9685f46fe82 100644 --- a/reference/constraints/DivisibleBy.rst +++ b/reference/constraints/DivisibleBy.rst @@ -49,7 +49,8 @@ The following constraints ensure that: App\Entity\Item: properties: weight: - - DivisibleBy: 0.25 + - DivisibleBy: + value: 0.25 quantity: - DivisibleBy: value: 5 @@ -65,7 +66,7 @@ The following constraints ensure that: - 0.25 + diff --git a/reference/constraints/EqualTo.rst b/reference/constraints/EqualTo.rst index fdc402b1a97..d0b9c2b2c75 100644 --- a/reference/constraints/EqualTo.rst +++ b/reference/constraints/EqualTo.rst @@ -48,7 +48,8 @@ and that the ``age`` is ``20``, you could do the following: App\Entity\Person: properties: firstName: - - EqualTo: Mary + - EqualTo: + value: Mary age: - EqualTo: value: 20 @@ -64,7 +65,7 @@ and that the ``age`` is ``20``, you could do the following: - Mary + diff --git a/reference/constraints/File.rst b/reference/constraints/File.rst index 62efa6cc08e..8c2c64de326 100644 --- a/reference/constraints/File.rst +++ b/reference/constraints/File.rst @@ -237,6 +237,8 @@ Parameter Description ``{{ suffix }}`` Suffix for the used file size unit (see above) ================ ============================================================= +.. _reference-constraints-file-mime-types: + ``mimeTypes`` ~~~~~~~~~~~~~ @@ -295,10 +297,6 @@ Can be one of the following constants of the length of the string in graphemes, i.e. even emojis and ZWJ sequences of composed emojis count as 1 character. -.. versionadded:: 7.3 - - The ``filenameCountUnit`` option was introduced in Symfony 7.3. - ``filenameTooLongMessage`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -340,10 +338,6 @@ Parameter Description ``{{ name }}`` The current (invalid) value ================= ============================================================ -.. versionadded:: 7.3 - - The ``filenameCharset`` and ``filenameCharsetMessage`` options were introduced in Symfony 7.3. - ``extensionsMessage`` ~~~~~~~~~~~~~~~~~~~~~ diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst index d1b79028acd..c8b72851068 100644 --- a/reference/constraints/GreaterThan.rst +++ b/reference/constraints/GreaterThan.rst @@ -46,7 +46,8 @@ The following constraints ensure that: App\Entity\Person: properties: siblings: - - GreaterThan: 5 + - GreaterThan: + value: 5 age: - GreaterThan: value: 18 @@ -62,7 +63,7 @@ The following constraints ensure that: - 5 + @@ -182,7 +183,8 @@ dates. If you want to fix the timezone, append it to the date string: App\Entity\Order: properties: deliveryDate: - - GreaterThan: today UTC + - GreaterThan: + value: today UTC .. code-block:: xml @@ -194,7 +196,9 @@ dates. If you want to fix the timezone, append it to the date string: - today UTC + + + @@ -242,7 +246,8 @@ current time: App\Entity\Order: properties: deliveryDate: - - GreaterThan: +5 hours + - GreaterThan: + value: +5 hours .. code-block:: xml @@ -254,7 +259,9 @@ current time: - +5 hours + + + diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index 63c2ade6197..39eb81e917b 100644 --- a/reference/constraints/GreaterThanOrEqual.rst +++ b/reference/constraints/GreaterThanOrEqual.rst @@ -45,7 +45,8 @@ The following constraints ensure that: App\Entity\Person: properties: siblings: - - GreaterThanOrEqual: 5 + - GreaterThanOrEqual: + value: 5 age: - GreaterThanOrEqual: value: 18 @@ -61,7 +62,7 @@ The following constraints ensure that: - 5 + @@ -122,7 +123,8 @@ that a date must at least be the current day: App\Entity\Order: properties: deliveryDate: - - GreaterThanOrEqual: today + - GreaterThanOrEqual: + value: today .. code-block:: xml @@ -134,7 +136,9 @@ that a date must at least be the current day: - today + + + @@ -181,7 +185,8 @@ dates. If you want to fix the timezone, append it to the date string: App\Entity\Order: properties: deliveryDate: - - GreaterThanOrEqual: today UTC + - GreaterThanOrEqual: + value: today UTC .. code-block:: xml @@ -193,7 +198,9 @@ dates. If you want to fix the timezone, append it to the date string: - today UTC + + + @@ -241,7 +248,8 @@ current time: App\Entity\Order: properties: deliveryDate: - - GreaterThanOrEqual: +5 hours + - GreaterThanOrEqual: + value: +5 hours .. code-block:: xml @@ -253,7 +261,9 @@ current time: - +5 hours + + + diff --git a/reference/constraints/IdenticalTo.rst b/reference/constraints/IdenticalTo.rst index f8844f90a72..024ad7ad2a1 100644 --- a/reference/constraints/IdenticalTo.rst +++ b/reference/constraints/IdenticalTo.rst @@ -51,7 +51,8 @@ The following constraints ensure that: App\Entity\Person: properties: firstName: - - IdenticalTo: Mary + - IdenticalTo: + value: Mary age: - IdenticalTo: value: 20 @@ -67,7 +68,7 @@ The following constraints ensure that: - Mary + diff --git a/reference/constraints/Image.rst b/reference/constraints/Image.rst index 7160ff95190..06fb6f92505 100644 --- a/reference/constraints/Image.rst +++ b/reference/constraints/Image.rst @@ -210,10 +210,6 @@ add several other options. If this option is false, the image cannot be landscape oriented. -.. versionadded:: 7.3 - - The ``allowLandscape`` option support for SVG files was introduced in Symfony 7.3. - ``allowLandscapeMessage`` ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -238,10 +234,6 @@ Parameter Description If this option is false, the image cannot be portrait oriented. -.. versionadded:: 7.3 - - The ``allowPortrait`` option support for SVG files was introduced in Symfony 7.3. - ``allowPortraitMessage`` ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -268,10 +260,6 @@ If this option is false, the image cannot be a square. If you want to force a square image, then leave this option as its default ``true`` value and set `allowLandscape`_ and `allowPortrait`_ both to ``false``. -.. versionadded:: 7.3 - - The ``allowSquare`` option support for SVG files was introduced in Symfony 7.3. - ``allowSquareMessage`` ~~~~~~~~~~~~~~~~~~~~~~ @@ -370,10 +358,6 @@ Parameter Description If set, the aspect ratio (``width / height``) of the image file must be less than or equal to this value. -.. versionadded:: 7.3 - - The ``maxRatio`` option support for SVG files was introduced in Symfony 7.3. - ``maxRatioMessage`` ~~~~~~~~~~~~~~~~~~~ @@ -493,10 +477,6 @@ Parameter Description If set, the aspect ratio (``width / height``) of the image file must be greater than or equal to this value. -.. versionadded:: 7.3 - - The ``minRatio`` option support for SVG files was introduced in Symfony 7.3. - ``minRatioMessage`` ~~~~~~~~~~~~~~~~~~~ diff --git a/reference/constraints/Ip.rst b/reference/constraints/Ip.rst index 20cd4400c0a..8257fabbb92 100644 --- a/reference/constraints/Ip.rst +++ b/reference/constraints/Ip.rst @@ -119,8 +119,3 @@ Only private ``4_private`` ``6_private`` ``all_private`` Only reserved ``4_reserved`` ``6_reserved`` ``all_reserved`` Only public ``4_public`` ``6_public`` ``all_public`` ==================== =================== =================== ================== - -.. versionadded:: 7.1 - - The ``*_no_public``, ``*_reserved`` and ``*_public`` ranges were introduced - in Symfony 7.1. diff --git a/reference/constraints/Length.rst b/reference/constraints/Length.rst index c1a8575070b..037237c144b 100644 --- a/reference/constraints/Length.rst +++ b/reference/constraints/Length.rst @@ -201,6 +201,8 @@ You can use the following parameters in this message: Parameter Description ====================== ============================================================ ``{{ limit }}`` The expected maximum length +``{{ min }}`` The expected minimum length +``{{ max }}`` The expected maximum length ``{{ value }}`` The current (invalid) value ``{{ value_length }}`` The current value's length ====================== ============================================================ @@ -233,6 +235,8 @@ You can use the following parameters in this message: Parameter Description ====================== ============================================================ ``{{ limit }}`` The expected minimum length +``{{ min }}`` The expected minimum length +``{{ max }}`` The expected maximum length ``{{ value }}`` The current (invalid) value ``{{ value_length }}`` The current value's length ====================== ============================================================ diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index 3d23bcda445..859d7bae83f 100644 --- a/reference/constraints/LessThan.rst +++ b/reference/constraints/LessThan.rst @@ -46,7 +46,8 @@ The following constraints ensure that: App\Entity\Person: properties: siblings: - - LessThan: 5 + - LessThan: + value: 5 age: - LessThan: value: 80 @@ -62,7 +63,7 @@ The following constraints ensure that: - 5 + @@ -123,7 +124,8 @@ that a date must be in the past like this: App\Entity\Person: properties: dateOfBirth: - - LessThan: today + - LessThan: + value: today .. code-block:: xml @@ -135,7 +137,9 @@ that a date must be in the past like this: - today + + + @@ -182,7 +186,8 @@ dates. If you want to fix the timezone, append it to the date string: App\Entity\Person: properties: dateOfBirth: - - LessThan: today UTC + - LessThan: + value: today UTC .. code-block:: xml @@ -194,7 +199,9 @@ dates. If you want to fix the timezone, append it to the date string: - today UTC + + + @@ -241,7 +248,8 @@ can check that a person must be at least 18 years old like this: App\Entity\Person: properties: dateOfBirth: - - LessThan: -18 years + - LessThan: + value: -18 years .. code-block:: xml @@ -253,7 +261,9 @@ can check that a person must be at least 18 years old like this: - -18 years + + + diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index ac66c62d7d0..40bdbebc739 100644 --- a/reference/constraints/LessThanOrEqual.rst +++ b/reference/constraints/LessThanOrEqual.rst @@ -45,7 +45,8 @@ The following constraints ensure that: App\Entity\Person: properties: siblings: - - LessThanOrEqual: 5 + - LessThanOrEqual: + value: 5 age: - LessThanOrEqual: value: 80 @@ -61,7 +62,7 @@ The following constraints ensure that: - 5 + @@ -122,7 +123,8 @@ that a date must be today or in the past like this: App\Entity\Person: properties: dateOfBirth: - - LessThanOrEqual: today + - LessThanOrEqual: + value: today .. code-block:: xml @@ -134,7 +136,9 @@ that a date must be today or in the past like this: - today + + + @@ -181,7 +185,8 @@ dates. If you want to fix the timezone, append it to the date string: App\Entity\Person: properties: dateOfBirth: - - LessThanOrEqual: today UTC + - LessThanOrEqual: + value: today UTC .. code-block:: xml @@ -193,7 +198,9 @@ dates. If you want to fix the timezone, append it to the date string: - today UTC + + + @@ -240,7 +247,8 @@ can check that a person must be at least 18 years old like this: App\Entity\Person: properties: dateOfBirth: - - LessThanOrEqual: -18 years + - LessThanOrEqual: + value: -18 years .. code-block:: xml @@ -252,7 +260,9 @@ can check that a person must be at least 18 years old like this: - -18 years + + + diff --git a/reference/constraints/MacAddress.rst b/reference/constraints/MacAddress.rst index 9a282ddf118..4fbf62a06d9 100644 --- a/reference/constraints/MacAddress.rst +++ b/reference/constraints/MacAddress.rst @@ -1,10 +1,6 @@ MacAddress ========== -.. versionadded:: 7.1 - - The ``MacAddress`` constraint was introduced in Symfony 7.1. - This constraint ensures that the given value is a valid `MAC address`_ (internally it uses the ``FILTER_VALIDATE_MAC`` option of the :phpfunction:`filter_var` PHP function). @@ -110,10 +106,6 @@ Parameter Description **type**: ``string`` **default**: ``all`` -.. versionadded:: 7.1 - - The ``type`` option was introduced in Symfony 7.1. - This option defines the kind of MAC addresses that are allowed. There are a lot of different possible values based on your needs: diff --git a/reference/constraints/Negative.rst b/reference/constraints/Negative.rst index 0d043ee8f6e..b47806f5291 100644 --- a/reference/constraints/Negative.rst +++ b/reference/constraints/Negative.rst @@ -50,7 +50,7 @@ The following constraint ensures that the ``withdraw`` of a bank account - + diff --git a/reference/constraints/NegativeOrZero.rst b/reference/constraints/NegativeOrZero.rst index 5f221950528..f6d94af84ee 100644 --- a/reference/constraints/NegativeOrZero.rst +++ b/reference/constraints/NegativeOrZero.rst @@ -49,7 +49,7 @@ is a negative number or equal to zero: - + diff --git a/reference/constraints/NotCompromisedPassword.rst b/reference/constraints/NotCompromisedPassword.rst index 6641f9d8cb2..b2ae775b0ce 100644 --- a/reference/constraints/NotCompromisedPassword.rst +++ b/reference/constraints/NotCompromisedPassword.rst @@ -49,7 +49,7 @@ The following constraint ensures that the ``rawPassword`` property of the - + diff --git a/reference/constraints/NotEqualTo.rst b/reference/constraints/NotEqualTo.rst index dd3f633b4a1..ce8ecb7dea5 100644 --- a/reference/constraints/NotEqualTo.rst +++ b/reference/constraints/NotEqualTo.rst @@ -50,7 +50,8 @@ the following: App\Entity\Person: properties: firstName: - - NotEqualTo: Mary + - NotEqualTo: + value: Mary age: - NotEqualTo: value: 15 @@ -66,7 +67,7 @@ the following: - Mary + diff --git a/reference/constraints/NotIdenticalTo.rst b/reference/constraints/NotIdenticalTo.rst index b2c20027292..a45731fa2e3 100644 --- a/reference/constraints/NotIdenticalTo.rst +++ b/reference/constraints/NotIdenticalTo.rst @@ -51,7 +51,8 @@ The following constraints ensure that: App\Entity\Person: properties: firstName: - - NotIdenticalTo: Mary + - NotIdenticalTo: + value: Mary age: - NotIdenticalTo: value: 15 @@ -67,7 +68,7 @@ The following constraints ensure that: - Mary + diff --git a/reference/constraints/PasswordStrength.rst b/reference/constraints/PasswordStrength.rst index 0b242cacf08..f4b43273c7b 100644 --- a/reference/constraints/PasswordStrength.rst +++ b/reference/constraints/PasswordStrength.rst @@ -53,7 +53,7 @@ By default, the minimum required score is ``2``. - + @@ -132,10 +132,6 @@ The default message supplied when the password does not reach the minimum requir Customizing the Password Strength Estimation -------------------------------------------- -.. versionadded:: 7.2 - - The feature to customize the password strength estimation was introduced in Symfony 7.2. - By default, this constraint calculates the strength of a password based on its length and the number of unique characters used. You can get the calculated password strength (e.g. to display it in the user interface) using the following @@ -180,23 +176,6 @@ service to use your own estimator: Symfony\Component\Validator\Constraints\PasswordStrengthValidator: arguments: [!closure '@custom_password_strength_estimator'] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/reference/constraints/Positive.rst b/reference/constraints/Positive.rst index b43fdde67d8..84c3bc11099 100644 --- a/reference/constraints/Positive.rst +++ b/reference/constraints/Positive.rst @@ -50,7 +50,7 @@ positive number (greater than zero): - + diff --git a/reference/constraints/PositiveOrZero.rst b/reference/constraints/PositiveOrZero.rst index 4aa8420993c..f3c54c85394 100644 --- a/reference/constraints/PositiveOrZero.rst +++ b/reference/constraints/PositiveOrZero.rst @@ -49,7 +49,7 @@ is positive or zero: - + diff --git a/reference/constraints/Regex.rst b/reference/constraints/Regex.rst index e3b4d4711b2..1b48eba1dff 100644 --- a/reference/constraints/Regex.rst +++ b/reference/constraints/Regex.rst @@ -38,7 +38,8 @@ more word characters at the beginning of your string: App\Entity\Author: properties: description: - - Regex: '/^\w+/' + - Regex: + pattern: '/^\w+/' .. code-block:: xml diff --git a/reference/constraints/Sequentially.rst b/reference/constraints/Sequentially.rst index 6d0be1863d0..afb45a72d09 100644 --- a/reference/constraints/Sequentially.rst +++ b/reference/constraints/Sequentially.rst @@ -68,9 +68,11 @@ You can validate each of these constraints sequentially to solve these issues: address: - Sequentially: - NotNull: ~ - - Type: string + - Type: + value: string - Length: { min: 10 } - - Regex: !php/const App\Localization\Place::ADDRESS_REGEX + - Regex: + pattern: !php/const App\Localization\Place::ADDRESS_REGEX - App\Validator\Constraints\Geolocalizable: ~ .. code-block:: xml @@ -85,7 +87,9 @@ You can validate each of these constraints sequentially to solve these issues: - string + + + diff --git a/reference/constraints/Traverse.rst b/reference/constraints/Traverse.rst index 56d400fb964..d0e1254884d 100644 --- a/reference/constraints/Traverse.rst +++ b/reference/constraints/Traverse.rst @@ -167,7 +167,8 @@ disable validating: # config/validator/validation.yaml App\Entity\BookCollection: constraints: - - Traverse: false + - Traverse: + traverse: false .. code-block:: xml @@ -178,7 +179,9 @@ disable validating: xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - false + + + diff --git a/reference/constraints/Twig.rst b/reference/constraints/Twig.rst index e38b4507d7a..cc2ba1f0e60 100644 --- a/reference/constraints/Twig.rst +++ b/reference/constraints/Twig.rst @@ -1,10 +1,6 @@ Twig Constraint =============== -.. versionadded:: 7.3 - - The ``Twig`` constraint was introduced in Symfony 7.3. - Validates that a given string contains valid :ref:`Twig syntax `. This is particularly useful when template content is user-generated or configurable, and you want to ensure it can be rendered by the Twig engine. diff --git a/reference/constraints/Type.rst b/reference/constraints/Type.rst index b49536dff8b..a217e64a675 100644 --- a/reference/constraints/Type.rst +++ b/reference/constraints/Type.rst @@ -58,10 +58,12 @@ The following example checks if ``emailAddress`` is an instance of ``Symfony\Com App\Entity\Author: properties: emailAddress: - - Type: Symfony\Component\Mime\Address + - Type: + type: Symfony\Component\Mime\Address firstName: - - Type: string + - Type: + type: string age: - Type: @@ -217,11 +219,6 @@ Also, you can use ``ctype_*()`` functions from corresponding Make sure that the proper :phpfunction:`locale ` is set before using one of these. -.. versionadded:: 7.1 - - The ``list`` and ``associative_array`` types were introduced in Symfony - 7.1. - Finally, you can use aggregated functions: * ``number``: ``is_int || is_float && !is_nan`` diff --git a/reference/constraints/Ulid.rst b/reference/constraints/Ulid.rst index 4094bab98f5..3fba5cc334b 100644 --- a/reference/constraints/Ulid.rst +++ b/reference/constraints/Ulid.rst @@ -84,10 +84,6 @@ The format of the ULID to validate. The following formats are available: * ``Ulid::FORMAT_BASE_58``: The ULID is encoded in `base58`_ * ``Ulid::FORMAT_RFC4122``: The ULID is encoded in the `RFC 4122 format`_ -.. versionadded:: 7.2 - - The ``format`` option was introduced in Symfony 7.2. - .. include:: /reference/constraints/_groups-option.rst.inc ``message`` diff --git a/reference/constraints/Unique.rst b/reference/constraints/Unique.rst index 9ce84139cd5..113586c76c0 100644 --- a/reference/constraints/Unique.rst +++ b/reference/constraints/Unique.rst @@ -175,10 +175,6 @@ collection:: **type**: ``string`` **default**: ``null`` -.. versionadded:: 7.2 - - The ``errorPath`` option was introduced in Symfony 7.2. - If a validation error occurs, the error message is, by default, bound to the first element in the collection. Use this option to bind the error message to a specific field within the first item of the collection. @@ -225,8 +221,4 @@ By default, this constraint stops at the first violation. If this option is set to ``false``, validation continues on all elements and returns all detected :class:`Symfony\\Component\\Validator\\ConstraintViolation` objects. -.. versionadded:: 7.3 - - The ``stopOnFirstError`` option was introduced in Symfony 7.3. - .. _`PHP callable`: https://www.php.net/callable diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst index 219ce4ed4ef..1ba0bcd27f6 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -56,7 +56,8 @@ between all of the rows in your user table: # config/validator/validation.yaml App\Entity\User: constraints: - - Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity: email + - Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity: + fields: email properties: email: - Email: ~ diff --git a/reference/constraints/Url.rst b/reference/constraints/Url.rst index c3fac520f96..3891ce5586c 100644 --- a/reference/constraints/Url.rst +++ b/reference/constraints/Url.rst @@ -165,7 +165,7 @@ Parameter Description ``protocols`` ~~~~~~~~~~~~~ -**type**: ``array`` **default**: ``['http', 'https']`` +**type**: ``array|string`` **default**: ``['http', 'https']`` The protocols considered to be valid for the URL. For example, if you also consider the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing @@ -237,6 +237,12 @@ the ``ftp://`` type URLs to be valid, redefine the ``protocols`` array, listing } } +The value of this option can also be an asterisk (``*``) to allow all protocols:: + + // allows all protocols whose names are RFC 3986 compliant + // (e.g. 'https://', 'git+ssh://', 'file://', 'custom://') + protocols: '*' + ``relativeProtocol`` ~~~~~~~~~~~~~~~~~~~~ @@ -311,16 +317,7 @@ also relative URLs that contain no protocol (e.g. ``//example.com``). ``requireTld`` ~~~~~~~~~~~~~~ -**type**: ``boolean`` **default**: ``false`` - -.. versionadded:: 7.1 - - The ``requireTld`` option was introduced in Symfony 7.1. - -.. deprecated:: 7.1 - - Not setting the ``requireTld`` option is deprecated since Symfony 7.1 - and will default to ``true`` in Symfony 8.0. +**type**: ``boolean`` **default**: ``true`` By default, URLs like ``https://aaa`` or ``https://foobar`` are considered valid because they are technically correct according to the `URL spec`_. If you set this option @@ -338,10 +335,6 @@ name): e.g. ``https://example.com`` will be valid but ``https://example`` won't. **type**: ``string`` **default**: ``This URL does not contain a TLD.`` -.. versionadded:: 7.1 - - The ``tldMessage`` option was introduced in Symfony 7.1. - This message is shown if the ``requireTld`` option is set to ``true`` and the URL does not contain at least one TLD. diff --git a/reference/constraints/Video.rst b/reference/constraints/Video.rst new file mode 100644 index 00000000000..88aef89c71d --- /dev/null +++ b/reference/constraints/Video.rst @@ -0,0 +1,316 @@ +Video +===== + +Validates that a file is a valid video that meets certain constraints (width, height, +aspect ratio, etc.). It extends the :doc:`File ` constraint +and adds video-specific validation options. + +========== =================================================================== +Applies to :ref:`property or method ` +Class :class:`Symfony\\Component\\Validator\\Constraints\\Video` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\VideoValidator` +========== =================================================================== + +Basic Usage +----------- + +This constraint is most commonly used on a property that stores a video file as a +:class:`Symfony\\Component\\HttpFoundation\\File\\File` object. For example, suppose +you're creating a video platform and want to validate uploaded video files:: + + // src/Entity/VideoContent.php + namespace App\Entity; + + use Symfony\Component\HttpFoundation\File\File; + use Symfony\Component\Validator\Constraints as Assert; + + class VideoContent + { + #[Assert\Video( + maxWidth: 1920, + maxHeight: 1080, + maxSize: '100M', + mimeTypes: ['video/mp4', 'video/webm'], + )] + private File $videoFile; + } + +.. warning:: + + This constraint requires the ``ffprobe`` binary to be installed and accessible + on your system. The constraint uses ``ffprobe`` to extract video metadata. + You can install it as part of the `FFmpeg package`_. + +Options +------- + +``allowedCodecs`` +~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``['h264', 'hevc', 'h265', 'vp9', 'av1', 'mpeg4', 'mpeg2video']`` + +Defines which `video codecs`_ are allowed. If the video uses a codec not in this +list, validation will fail:: + + // src/Entity/VideoContent.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class VideoContent + { + #[Assert\Video( + allowedCodecs: ['h264', 'hevc'], + )] + private $videoFile; + } + +``allowedContainers`` +~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``array`` **default**: ``['mp4', 'mov', 'mkv', 'webm', 'avi']`` + +Defines which `video container formats`_ are allowed:: + + // src/Entity/VideoContent.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class VideoContent + { + #[Assert\Video( + allowedContainers: ['mp4', 'webm'], + )] + private $videoFile; + } + +``allowLandscape`` +~~~~~~~~~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``true`` + +If set to ``false``, the video cannot be landscape oriented (i.e., the width +cannot be greater than the height). + +``allowPortrait`` +~~~~~~~~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``true`` + +If set to ``false``, the video cannot be portrait oriented (i.e., the width +cannot be less than the height). + +``allowSquare`` +~~~~~~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``true`` + +If set to ``false``, the video cannot be a square (i.e., the width and height +cannot be equal). + +``maxHeight`` +~~~~~~~~~~~~~ + +**type**: ``integer`` + +If set, the height of the video file must be less than or equal to this value +in pixels. + +``maxPixels`` +~~~~~~~~~~~~~ + +**type**: ``integer`` | ``float`` + +If set, the total number of pixels (``width * height``) of the video file must be less +than or equal to this value. + +``maxRatio`` +~~~~~~~~~~~~ + +**type**: ``integer`` | ``float`` + +If set, the aspect ratio (``width / height``) of the video file must be less +than or equal to this value. For example, a square video has a ratio of 1, +a 16:9 video has a ratio of 1.78, and a 4:3 video has a ratio of 1.33. + +``maxWidth`` +~~~~~~~~~~~~ + +**type**: ``integer`` + +If set, the width of the video file must be less than or equal to this value +in pixels. + +``mimeTypes`` +~~~~~~~~~~~~~ + +**type**: ``array`` or ``string`` **default**: ``video/*`` + +See the :ref:`File mimeTypes option ` for a +description of this option and a list of common video MIME types. + +``minHeight`` +~~~~~~~~~~~~~ + +**type**: ``integer`` + +If set, the height of the video file must be greater than or equal to this +value in pixels. + +``minPixels`` +~~~~~~~~~~~~~ + +**type**: ``integer`` | ``float`` + +If set, the total number of pixels (``width * height``) of the video file must be greater +than or equal to this value. + +``minRatio`` +~~~~~~~~~~~~ + +**type**: ``integer`` | ``float`` + +If set, the aspect ratio (``width / height``) of the video file must be greater +than or equal to this value. + +``minWidth`` +~~~~~~~~~~~~ + +**type**: ``integer`` + +If set, the width of the video file must be greater than or equal to this value +in pixels. + +.. include:: /reference/constraints/_groups-option.rst.inc + +.. include:: /reference/constraints/_payload-option.rst.inc + +Messages +-------- + +``allowLandscapeMessage`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video is landscape oriented ({{ width }}x{{ height }}px). Landscape oriented videos are not allowed.`` + +The message displayed if the video is landscape oriented and landscape videos +are not allowed. + +``allowPortraitMessage`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video is portrait oriented ({{ width }}x{{ height }}px). Portrait oriented videos are not allowed.`` + +The message displayed if the video is portrait oriented and portrait videos are not allowed. + +``allowSquareMessage`` +~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video is square ({{ width }}x{{ height }}px). Square videos are not allowed.`` + +The message displayed if the video is square and square videos are not allowed. + +``corruptedMessage`` +~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video file is corrupted.`` + +The message displayed if the video file is corrupted and cannot be read by ``ffprobe``. + +``maxHeightMessage`` +~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video height is too big ({{ height }}px). Allowed maximum height is {{ max_height }}px.`` + +The message displayed if the height of the video exceeds ``maxHeight``. + +``maxPixelsMessage`` +~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video has too many pixels ({{ pixels }} pixels). Maximum amount expected is {{ max_pixels }} pixels.`` + +The message displayed if the total number of pixels of the video exceeds ``maxPixels``. + +``maxRatioMessage`` +~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video ratio is too big ({{ ratio }}). Allowed maximum ratio is {{ max_ratio }}.`` + +The message displayed if the aspect ratio of the video exceeds ``maxRatio``. + +``maxWidthMessage`` +~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video width is too big ({{ width }}px). Allowed maximum width is {{ max_width }}px.`` + +The message displayed if the width of the video exceeds ``maxWidth``. + +``mimeTypesMessage`` +~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``This file is not a valid video.`` + +The message displayed if the media type of the video is not a valid media type +per the ``mimeTypes`` option. + +``minHeightMessage`` +~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video height is too small ({{ height }}px). Minimum height expected is {{ min_height }}px.`` + +The message displayed if the height of the video is less than ``minHeight``. + +``minPixelsMessage`` +~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video has too few pixels ({{ pixels }} pixels). Minimum amount expected is {{ min_pixels }} pixels.`` + +The message displayed if the total number of pixels of the video is less than ``minPixels``. + +``minRatioMessage`` +~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video ratio is too small ({{ ratio }}). Minimum ratio expected is {{ min_ratio }}.`` + +The message displayed if the aspect ratio of the video is less than ``minRatio``. + +``minWidthMessage`` +~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video width is too small ({{ width }}px). Minimum width expected is {{ min_width }}px.`` + +The message displayed if the width of the video is less than ``minWidth``. + +``multipleVideoStreamsMessage`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The video contains multiple streams. Only one stream is allowed.`` + +The message displayed if the video file contains multiple video streams. + +``sizeNotDetectedMessage`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The size of the video could not be detected.`` + +The message displayed if ``ffprobe`` cannot detect the dimensions of the video. + +``unsupportedCodecMessage`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``Unsupported video codec "{{ codec }}".`` + +The message displayed if the video uses a codec that is not in the ``allowedCodecs`` list. + +``unsupportedContainerMessage`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``Unsupported video container "{{ container }}".`` + +The message displayed if the video uses a container format that is not in the +``allowedContainers`` list. + +.. _`FFmpeg package`: https://ffmpeg.org/ +.. _`video codecs`: https://en.wikipedia.org/wiki/Comparison_of_video_codecs +.. _`video container formats`: https://en.wikipedia.org/wiki/Comparison_of_video_container_formats diff --git a/reference/constraints/Week.rst b/reference/constraints/Week.rst index b3c1b0ca122..485a11ca8f4 100644 --- a/reference/constraints/Week.rst +++ b/reference/constraints/Week.rst @@ -1,10 +1,6 @@ Week ==== -.. versionadded:: 7.2 - - The ``Week`` constraint was introduced in Symfony 7.2. - Validates that a given string (or an object implementing the ``Stringable`` PHP interface) represents a valid week number according to the `ISO-8601`_ standard (e.g. ``2025-W01``). diff --git a/reference/constraints/When.rst b/reference/constraints/When.rst index 4b2e8eb7590..a47a4dc3f1c 100644 --- a/reference/constraints/When.rst +++ b/reference/constraints/When.rst @@ -85,7 +85,8 @@ One way to accomplish this is with the When constraint: App\Model\Discount: properties: value: - - GreaterThan: 0 + - GreaterThan: + value: 0 - When: expression: "this.getType() == 'percent'" constraints: @@ -106,7 +107,9 @@ One way to accomplish this is with the When constraint: xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - 0 + + + Delete {% endif %} +Symfony also provides the ``access_decision()`` and ``access_decision_for_user()`` +Twig functions to check authorization and to retrieve the reasons for denying +permission in :ref:`your custom security voters `: + +.. code-block:: html+twig + + {% set voter_decision = access_decision('post_edit', post) %} + {% if voter_decision.isGranted() %} + {# ... #} + {% else %} + {# before showing voter messages to end users, make sure it's safe to do so #} +

{{ voter_decision.message }}

+ {% endif %} + + {% set voter_decision = access_decision('post_edit', post, anotherUser) %} + {% if voter_decision.isGranted() %} + {# ... #} + {% else %} +

The {{ anotherUser.name }} user doesn't have sufficient permission:

+ {# before showing voter messages to end users, make sure it's safe to do so #} +

{{ voter_decision.message }}

+ {% endif %} + .. _security-isgrantedforuser: Securing other Services @@ -2594,10 +2229,36 @@ want to include extra details only for users that have a ``ROLE_SALES_ADMIN`` ro is unavailable (e.g., in a CLI context such as a message queue or cron job), you can use the ``isGrantedForUser()`` method to explicitly set the target user. - .. versionadded:: 7.3 +You can also use the ``getAccessDecision()`` and ``getAccessDecisionForUser()`` +methods to check authorization and get to retrieve the reasons for denying +permission in :ref:`your custom security voters `:: - The :method:`Symfony\\Bundle\\SecurityBundle\\Security::isGrantedForUser` - method was introduced in Symfony 7.3. + // src/SalesReport/SalesReportManager.php + + // ... + use Symfony\Bundle\SecurityBundle\Security; + + class SalesReportManager + { + public function __construct( + private Security $security, + ) { + } + + public function generateReport(): void + { + $voterDecision = $this->security->getAccessDecision('ROLE_SALES_ADMIN'); + if ($voterDecision->isGranted('ROLE_SALES_ADMIN')) { + // ... + } else { + // do something with $voterDecision->getMessage() + } + + // ... + } + + // ... + } If you're using the :ref:`default services.yaml configuration `, Symfony will automatically pass the ``security.helper`` to your service @@ -2634,31 +2295,6 @@ the login page): # but require authentication for all other admin routes - { path: ^/admin, roles: ROLE_ADMIN } - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -2713,11 +2349,6 @@ anonymous users access by checking if there is no user set on the token:: } } -.. versionadded:: 7.3 - - The ``$vote`` argument of the ``voteOnAttribute()`` method was introduced - in Symfony 7.3. - Setting Individual User Permissions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2809,11 +2440,6 @@ Two strategies are supported: return $data; } -.. versionadded:: 7.3 - - Support for hashing passwords with ``crc32c`` in session serialization was - introduced in Symfony 7.3. - If you're having problems authenticating, it could be that you *are* authenticating successfully, but you immediately lose authentication after the first redirect. @@ -2863,26 +2489,6 @@ for these events. - name: kernel.event_subscriber dispatcher: security.event_dispatcher.main - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -3023,3 +2629,4 @@ Authorization (Denying Access) .. _`Login CSRF attacks`: https://en.wikipedia.org/wiki/Cross-site_request_forgery#Forging_login_requests .. _`PHP date relative formats`: https://www.php.net/manual/en/datetime.formats.php#datetime.formats.relative .. _`Oauth2-client`: https://github.com/thephpleague/oauth2-client +.. _`Mermaid CLI`: https://github.com/mermaid-js/mermaid-cli diff --git a/security/access_control.rst b/security/access_control.rst index 8e62e8a84c7..3bece6b7210 100644 --- a/security/access_control.rst +++ b/security/access_control.rst @@ -62,48 +62,6 @@ Take the following ``access_control`` entries as an example: - { attributes: {'_route': 'admin'}, roles: ROLE_ADMIN } - { route: 'admin', roles: ROLE_ADMIN } - .. code-block:: xml - - - - - - - 10.0.0.1, 10.0.0.2 - - - - - - - - - - - - - 127.0.0.1 - ::1 - %env(TRUSTED_IPS)% - - - - - - - - admin - - - - - .. code-block:: php // config/packages/security.php @@ -292,31 +250,6 @@ pattern so that it is only accessible by requests from the local server itself: - { path: '^/internal', roles: PUBLIC_ACCESS, ips: [127.0.0.1, ::1, 192.168.0.1/24] } - { path: '^/internal', roles: ROLE_NO_ACCESS } - .. code-block:: xml - - - - - - - - - - - 127.0.0.1 - ::1 - - - - - - .. code-block:: php // config/packages/security.php @@ -383,28 +316,6 @@ key: roles: 'ROLE_ADMIN' allow_if: "'127.0.0.1' == request.getClientIp() or request.headers.has('X-Secure-Access')" - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -462,27 +373,6 @@ access those URLs via a specific port. This could be useful for example for access_control: - { path: ^/cart/checkout, roles: PUBLIC_ACCESS, port: 8080 } - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -516,27 +406,6 @@ the user will be redirected to ``https``: access_control: - { path: ^/cart/checkout, roles: PUBLIC_ACCESS, requires_channel: https } - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/access_denied_handler.rst b/security/access_denied_handler.rst index 37490e3120b..94c77479441 100644 --- a/security/access_denied_handler.rst +++ b/security/access_denied_handler.rst @@ -64,25 +64,6 @@ Now, configure this service ID as the entry point for the firewall: # ... entry_point: App\Security\AuthenticationEntryPoint - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -140,25 +121,6 @@ configure it under your firewall: # ... access_denied_handler: App\Security\AccessDeniedHandler - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/access_token.rst b/security/access_token.rst index 2c070f72e92..4992189e57b 100644 --- a/security/access_token.rst +++ b/security/access_token.rst @@ -39,25 +39,6 @@ digital signature, etc.). access_token: token_handler: App\Security\AccessTokenHandler - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -164,31 +145,6 @@ You can also create a custom extractor. The class must implement # or provide the service ID of a custom extractor token_extractors: 'App\Security\CustomTokenExtractor' - .. code-block:: xml - - - - - - - - - - request_body - - - App\Security\CustomTokenExtractor - - - - - .. code-block:: php // config/packages/security.php @@ -226,28 +182,6 @@ important**: the first in the list is called first. - 'header' - 'App\Security\CustomTokenExtractor' - .. code-block:: xml - - - - - - - - - header - App\Security\CustomTokenExtractor - - - - - .. code-block:: php // config/packages/security.php @@ -301,27 +235,6 @@ and configure the service ID as the ``success_handler``: token_handler: App\Security\AccessTokenHandler success_handler: App\Security\Authentication\AuthenticationSuccessHandler - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -377,27 +290,6 @@ and retrieve the user info: token_handler: oidc_user_info: https://www.example.com/realms/demo/protocol/openid-connect/userinfo - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -437,31 +329,6 @@ Next, configure the ``base_uri`` and ``discovery`` options: cache: id: cache.app - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -478,10 +345,6 @@ Next, configure the ``base_uri`` and ``discovery`` options: ; }; -.. versionadded:: 7.3 - - Support for OpenID Connect Discovery was introduced in Symfony 7.3. - Following the `OpenID Connect Specification`_, the ``sub`` claim is used as user identifier by default. To use another claim, specify it using the ``claim`` option: @@ -499,29 +362,6 @@ identifier by default. To use another claim, specify it using the ``claim`` opti claim: email base_uri: https://www.example.com/realms/demo/protocol/openid-connect/userinfo - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -554,29 +394,6 @@ specify the service name via the ``client`` option: oidc_user_info: client: oidc.client - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -644,41 +461,6 @@ it, and retrieves the user information from it. Optionally, the token can be enc algorithms: ['ECDH-ES', 'A128GCM'] keyset: '{"keys": [...]}' # Encryption private keyset - .. code-block:: xml - - - - - - - - - - - - - - - ES256 - RS256 - https://oidc.example.com - - ECDH-ES - A128GCM - - - - - - - - .. code-block:: php // config/packages/security.php @@ -708,15 +490,6 @@ it, and retrieves the user information from it. Optionally, the token can be enc ; }; -.. versionadded:: 7.1 - - The support of multiple algorithms to sign the JWS was introduced in Symfony 7.1. - In previous versions, only the ``ES256`` algorithm was supported. - -.. versionadded:: 7.3 - - Support for encryption algorithms to decrypt JWEs was introduced in Symfony 7.3. - To enable `OpenID Connect Discovery`_, the ``OidcTokenHandler`` requires the ``symfony/cache`` package to store the OIDC configuration in the cache. If you haven't installed it yet, run the following command: @@ -748,34 +521,6 @@ from the OpenID Connect Discovery), and configure the ``discovery`` option: cache: id: cache.app - .. code-block:: xml - - - - - - - - - - - ES256 - RS256 - https://oidc.example.com - - - - - - - - .. code-block:: php // config/packages/security.php @@ -817,33 +562,6 @@ configuration: audience: 'api-example' issuers: ['https://oidc.example.com'] - .. code-block:: xml - - - - - - - - - - - ES256 - RS256 - https://oidc.example.com - - - - - - - .. code-block:: php // config/packages/security.php @@ -877,12 +595,82 @@ create your own User from the claims, you must } } -Using CAS 2.0 -------------- +Configuring Multiple OIDC Discovery Endpoints +............................................. -.. versionadded:: 7.1 +The ``OidcTokenHandler`` supports multiple OIDC discovery endpoints, allowing it +to validate tokens from different identity providers: - The support for CAS token handlers was introduced in Symfony 7.1. +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/security.yaml + security: + firewalls: + main: + access_token: + token_handler: + oidc: + algorithms: ['ES256', 'RS256'] + audience: 'api-example' + issuers: ['https://oidc1.example.com', 'https://oidc2.example.com'] + discovery: + base_uri: + - https://idp1.example.com/realms/demo/ + - https://idp2.example.com/realms/demo/ + cache: + id: cache.app + + .. code-block:: php + + // config/packages/security.php + use Symfony\Config\SecurityConfig; + + return static function (SecurityConfig $security) { + $security->firewall('main') + ->accessToken() + ->tokenHandler() + ->oidc() + ->algorithms(['ES256', 'RS256']) + ->audience('api-example') + ->issuers(['https://oidc1.example.com', 'https://oidc2.example.com']) + ->discovery() + ->baseUri([ + 'https://idp1.example.com/realms/demo/', + 'https://idp2.example.com/realms/demo/', + ]) + ->cache(['id' => 'cache.app']) + ; + }; + +The token handler fetches the JWK sets from all configured discovery endpoints +and builds a combined JWK set for token validation. This lets your application +accept and validate tokens from multiple identity providers within a single firewall. + +Creating a OIDC token from the command line +------------------------------------------- + +The ``security:oidc:generate-token`` command helps you generate JWTs. It's mostly +useful when developing or testing applications that use OIDC authentication: + +.. code-block:: terminal + + # generate a token using the default configuration + $ php bin/console security:oidc:generate-token john.doe@example.com + + # specify the firewall, algorithm, and issuer if multiple are available + $ php bin/console security:oidc:generate-token john.doe@example.com \ + --firewall="api" \ + --algorithm="HS256" \ + --issuer="https://example.com" + +.. note:: + + The JWK used for signing must have the appropriate `key operation flags`_ set. + +Using CAS 2.0 +------------- `Central Authentication Service (CAS)`_ is an enterprise multilingual single sign-on solution and identity provider for the web and attempts to be a @@ -914,29 +702,6 @@ You can configure a ``cas`` token handler as follows: cas: validation_url: https://www.example.com/cas/validate - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -969,29 +734,6 @@ specify the service name via the ``http_client`` option: validation_url: https://www.example.com/cas/validate http_client: cas.client - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -1024,29 +766,6 @@ By default the token handler will read the validation URL XML response with validation_url: https://www.example.com/cas/validate prefix: cas-example - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -1099,3 +818,4 @@ for :ref:`stateless firewalls `. .. _`OpenID Connect Discovery`: https://openid.net/specs/openid-connect-discovery-1_0.html .. _`RFC6750`: https://datatracker.ietf.org/doc/html/rfc6750 .. _`SAML2 (XML structures)`: https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html +.. _`key operation flags`: https://www.iana.org/assignments/jose/jose.xhtml#web-key-operations diff --git a/security/csrf.rst b/security/csrf.rst index 295a43fd9ff..14834c2476b 100644 --- a/security/csrf.rst +++ b/security/csrf.rst @@ -61,23 +61,6 @@ for more information): # ... csrf_protection: ~ - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -135,25 +118,6 @@ Globally, you can configure it under the ``framework.form`` option: enabled: true field_name: 'custom_token_name' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -321,14 +285,26 @@ array, the attribute is ignored for that request, and no CSRF validation occurs: // ... delete the object } -.. versionadded:: 7.1 +You can also choose where the CSRF token is read from using the ``tokenSource`` +parameter. This is a bitfield that allows you to combine different sources: - The :class:`Symfony\\Component\\Security\\Http\\Attribute\\IsCsrfTokenValid` - attribute was introduced in Symfony 7.1. +* ``IsCsrfTokenValid::SOURCE_PAYLOAD`` (default): request payload (POST body / json) +* ``IsCsrfTokenValid::SOURCE_QUERY``: query string +* ``IsCsrfTokenValid::SOURCE_HEADER``: request header -.. versionadded:: 7.3 +Example:: - The ``methods`` parameter was introduced in Symfony 7.3. + #[IsCsrfTokenValid( + 'delete-item', + tokenKey: 'token', + tokenSource: IsCsrfTokenValid::SOURCE_PAYLOAD | IsCsrfTokenValid::SOURCE_QUERY + )] + public function delete(Post $post): Response + { + // ... delete the object + } + +The token is checked against each selected source, and validation fails if none match. CSRF Tokens and Compression Side-Channel Attacks ------------------------------------------------ @@ -344,10 +320,6 @@ and used to scramble it. Stateless CSRF Tokens --------------------- -.. versionadded:: 7.2 - - Stateless anti-CSRF protection was introduced in Symfony 7.2. - Traditionally, CSRF tokens are stateful, meaning they're stored in the session. However, some token IDs can be declared as stateless using the ``stateless_token_ids`` option. Stateless CSRF tokens are enabled by default @@ -363,27 +335,6 @@ in applications using :ref:`Symfony Flex `. csrf_protection: stateless_token_ids: ['submit', 'authenticate', 'logout'] - .. code-block:: xml - - - - - - - - submit - authenticate - logout - - - - .. code-block:: php // config/packages/csrf.php @@ -431,25 +382,6 @@ own services), and it sets ``submit`` as their default token identifier: csrf_protection: token_id: 'submit' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/csrf.php diff --git a/security/custom_authenticator.rst b/security/custom_authenticator.rst index 462ec21521c..ae7078cadd2 100644 --- a/security/custom_authenticator.rst +++ b/security/custom_authenticator.rst @@ -118,27 +118,6 @@ should review it: custom_authenticators: - App\Security\ApiKeyAuthenticator - .. code-block:: xml - - - - - - - - - - App\Security\ApiKeyAuthenticator - - - - .. code-block:: php // config/packages/security.php @@ -289,10 +268,6 @@ lowercasing identifiers helps treat values like "john.doe", "John.Doe", or If needed, you can pass a normalizer as the third argument to ``UserBadge``. This callable receives the ``$userIdentifier`` and must return a string. -.. versionadded:: 7.3 - - Support for user identifier normalizers was introduced in Symfony 7.3. - The example below uses a normalizer that converts usernames to a normalized, ASCII-only, lowercase format:: diff --git a/security/entry_point.rst b/security/entry_point.rst index cfbef00ff88..530692d61cb 100644 --- a/security/entry_point.rst +++ b/security/entry_point.rst @@ -30,33 +30,6 @@ You can configure this using the ``entry_point`` setting: # configure the form authentication as the entry point for unauthenticated users entry_point: form_login - .. code-block:: xml - - - - - - - - - - - - - App\Security\SocialConnectAuthenticator - - - - .. code-block:: php // config/packages/security.php @@ -118,34 +91,6 @@ split the configuration into two separate firewalls: - { path: '^/api', roles: ROLE_API_USER } - { path: '^/', roles: ROLE_USER } - .. code-block:: xml - - - - - - - - - App\Security\ApiTokenAuthenticator - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/expressions.rst b/security/expressions.rst index a4ec02c7b84..83b785999c4 100644 --- a/security/expressions.rst +++ b/security/expressions.rst @@ -228,11 +228,6 @@ returns an array of values that will be injected into the closure:: } } -.. versionadded:: 7.3 - - The support for closures in the ``#[IsGranted]`` attribute was introduced - in Symfony 7.3 and requires PHP 8.5. - Learn more ---------- diff --git a/security/firewall_restriction.rst b/security/firewall_restriction.rst index be0237c0e39..1637fd79ab7 100644 --- a/security/firewall_restriction.rst +++ b/security/firewall_restriction.rst @@ -38,26 +38,6 @@ if the request path matches the configured ``pattern``. pattern: ^/admin # ... - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -97,26 +77,6 @@ only initialize if the host from the request matches against the configuration. host: ^admin\.example\.com$ # ... - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -157,26 +117,6 @@ the provided HTTP methods. methods: [GET, POST] # ... - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -215,26 +155,6 @@ If the above options don't fit your needs you can configure any service implemen request_matcher: App\Security\CustomRequestMatcher # ... - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/force_https.rst b/security/force_https.rst index 03d5230ca50..9e8bd60de9a 100644 --- a/security/force_https.rst +++ b/security/force_https.rst @@ -25,27 +25,6 @@ access control: # catch all other URLs - { path: '^/', roles: PUBLIC_ACCESS, requires_channel: https } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/form_login.rst b/security/form_login.rst index 2b5eba96340..1ae00479575 100644 --- a/security/form_login.rst +++ b/security/form_login.rst @@ -39,27 +39,6 @@ a relative/absolute URL or a Symfony route name: # ... default_target_path: after_login_route_name - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -96,28 +75,6 @@ previously requested URL and always redirect to the default page: # ... always_use_default_target_path: true - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -184,28 +141,6 @@ parameter is included in the request, you may use the value of the # ... use_referer: true - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -251,28 +186,6 @@ option to define a new target via a relative/absolute URL or a Symfony route nam # ... failure_path: login_failure_route_name - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -327,29 +240,6 @@ redirects can be customized using the ``target_path_parameter`` and target_path_parameter: go_to failure_path_parameter: back_to - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/impersonating_user.rst b/security/impersonating_user.rst index 6f22e7aace6..5625f930bb0 100644 --- a/security/impersonating_user.rst +++ b/security/impersonating_user.rst @@ -27,28 +27,6 @@ listener: # ... switch_user: true - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -93,26 +71,6 @@ as the value to the current URL: # ... switch_user: { parameter: X-Switch-User } - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -211,27 +169,6 @@ also adjust the query parameter name via the ``parameter`` setting: # ... switch_user: { role: ROLE_ADMIN, parameter: _want_to_be_this_user } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -269,27 +206,6 @@ This feature allows you to control the redirection target route via ``target_rou # ... switch_user: { target_route: app_user_dashboard } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -325,27 +241,6 @@ be called): # ... switch_user: { role: CAN_SWITCH_USER } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/ldap.rst b/security/ldap.rst index c4c3646122b..e5676e04745 100644 --- a/security/ldap.rst +++ b/security/ldap.rst @@ -78,33 +78,6 @@ An LDAP client can be configured using the built-in protocol_version: 3 referrals: false - .. code-block:: xml - - - - - - - - - - - - - my-server - 389 - tls - - 3 - false - - - - - - .. code-block:: php // config/services.php @@ -154,30 +127,6 @@ use the ``ldap`` user provider. uid_key: uid extra_fields: ['email'] - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -270,10 +219,6 @@ Symfony provides ``Symfony\Component\Ldap\Security\MemberOfRoles``, a concrete implementation of the interface that fetches roles from the ``ismemberof`` attribute. -.. versionadded:: 7.3 - - The ``role_fetcher`` configuration option was introduced in Symfony 7.3. - uid_key ....... @@ -392,26 +337,6 @@ Configuration example for form login service: Symfony\Component\Ldap\Ldap dn_string: 'uid={user_identifier},dc=example,dc=com' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -444,28 +369,6 @@ Configuration example for HTTP Basic service: Symfony\Component\Ldap\Ldap dn_string: 'uid={user_identifier},dc=example,dc=com' - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -502,30 +405,6 @@ Configuration example for form login and query_string search_dn: '...' search_password: 'the-raw-password' - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/login_link.rst b/security/login_link.rst index 57d353278c2..c71a02b1a03 100644 --- a/security/login_link.rst +++ b/security/login_link.rst @@ -35,27 +35,6 @@ and ``signature_properties`` (explained below): check_route: login_check signature_properties: ['id'] - .. code-block:: xml - - - - - - - - - id - - - - - .. code-block:: php // config/packages/security.php @@ -106,19 +85,6 @@ intercept requests to this route: login_check: path: /login_check - .. code-block:: xml - - - - - - - - - .. code-block:: php // config/routes.php @@ -338,28 +304,6 @@ seconds). You can customize this using the ``lifetime`` option: # lifetime in seconds lifetime: 300 - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -423,28 +367,6 @@ You can add more properties to the ``hash`` by using the check_route: login_check signature_properties: [id, email] - .. code-block:: xml - - - - - - - - - id - email - - - - - .. code-block:: php // config/packages/security.php @@ -493,30 +415,6 @@ cache. Enable this support by setting the ``max_uses`` option: # optionally, configure the cache pool #used_link_cache: 'cache.redis' - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -568,28 +466,6 @@ the authenticator only handle HTTP POST methods: check_post_only: true max_uses: 1 - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -713,30 +589,6 @@ Then, configure this service ID as the ``success_handler``: max_uses: 1 success_handler: App\Security\Authentication\AuthenticationSuccessHandler - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/passwords.rst b/security/passwords.rst index 7f05bc3acb9..e22c0d2a727 100644 --- a/security/passwords.rst +++ b/security/passwords.rst @@ -35,35 +35,6 @@ optionally some *algorithm options*: algorithm: 'auto' cost: 15 - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -256,6 +227,60 @@ You can customize the reset password bundle's behavior by updating the ``reset_password.yaml`` file. For more information on the configuration, check out the `SymfonyCastsResetPasswordBundle`_ guide. +Injecting a Specific Password Hasher +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In some cases, you may define a password hasher in your configuration that is +not tied to a user class. For example, you might use a separate hasher for +password recovery codes or API tokens. + +With the following configuration: + +.. code-block:: yaml + + # config/packages/security.yaml + security: + password_hashers: + recovery_code: 'auto' + + firewalls: + main: + # ... + +You can inject the ``recovery_code`` password hasher into any service. However, +you can't rely on standard autowiring, as Symfony doesn't know which specific +hasher to provide. + +Instead, use the ``#[Target]`` attribute to explicitly request the hasher by +its configuration key:: + + // src/Controller/HomepageController.php + namespace App\Controller; + + use Symfony\Component\DependencyInjection\Attribute\Target; + use Symfony\Component\PasswordHasher\PasswordHasherInterface; + + class HomepageController extends AbstractController + { + public function __construct( + #[Target('recovery_code')] + private readonly PasswordHasherInterface $passwordHasher, + ) { + } + + #[Route('/')] + public function index(): Response + { + $plaintextToken = 'some-secret-token'; + + // Note: use hash(), not hashPassword(), as we are not using a UserInterface object + $hashedToken = $this->passwordHasher->hash($plaintextToken); + } + } + +When injecting a specific hasher by its name, you should type-hint the generic +:class:`Symfony\\Component\\PasswordHasher\\PasswordHasherInterface`. + .. _security-password-migration: Password Migration @@ -299,40 +324,6 @@ on the new hasher to point to the old, legacy hasher(s): - bcrypt # uses the "bcrypt" hasher with the default options - legacy # uses the "legacy" hasher configured above - .. code-block:: xml - - - - - - - - - - - - - - bcrypt - - - legacy - - - - .. code-block:: php // config/packages/security.php @@ -532,27 +523,6 @@ cost. This can be done with named hashers: algorithm: auto cost: 15 - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -629,26 +599,6 @@ you must register a service for it in order to use it as a named hasher: app_hasher: id: 'App\Security\Hasher\MyCustomPasswordHasher' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -846,27 +796,6 @@ Now, define a password hasher using the ``id`` setting: # the service ID of your custom hasher (the FQCN using the default services.yaml) id: 'App\Security\Hasher\MyCustomPasswordHasher' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/remember_me.rst b/security/remember_me.rst index 2fd0f7e8d1e..f62fde81d9e 100644 --- a/security/remember_me.rst +++ b/security/remember_me.rst @@ -26,37 +26,6 @@ the session lasts using a cookie with the ``remember_me`` firewall option: # following line to always enable it. #always_remember_me: true - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -77,12 +46,6 @@ the session lasts using a cookie with the ``remember_me`` firewall option: ; }; -.. versionadded:: 7.2 - - The ``secret`` option is no longer required starting from Symfony 7.2. By - default, ``%kernel.secret%`` is used, which is defined using the - ``APP_SECRET`` environment variable. - After enabling the ``remember_me`` system in the configuration, there are a couple more things to do before remember me works correctly: @@ -176,31 +139,6 @@ allow users to opt-out. In these cases, you can use the # ... always_remember_me: true - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -337,32 +275,6 @@ are fetched from the user object using the # ... signature_properties: ['password', 'updatedAt'] - .. code-block:: xml - - - - - - - - - - - - - password - updatedAt - - - - - .. code-block:: php // config/packages/security.php @@ -420,31 +332,6 @@ You can enable the doctrine token provider using the ``doctrine`` setting: token_provider: doctrine: true - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -507,31 +394,6 @@ Then, configure the service ID of your custom token provider as ``service``: token_provider: service: App\Security\RememberMe\CustomTokenProvider - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/user_checkers.rst b/security/user_checkers.rst index cf38aafa57e..7c385ddedb3 100644 --- a/security/user_checkers.rst +++ b/security/user_checkers.rst @@ -59,10 +59,6 @@ displayed to the user:: } } -.. versionadded:: 7.2 - - The ``token`` argument for the ``checkPostAuth()`` method was introduced in Symfony 7.2. - Enabling the Custom User Checker -------------------------------- @@ -87,28 +83,6 @@ is the service id of your user checker: user_checker: App\Security\UserChecker # ... - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -155,29 +129,6 @@ order in which user checkers are called:: tags: - { name: security.user_checker.api, priority: 5 } - .. code-block:: xml - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -218,33 +169,6 @@ Once your checker services are tagged, next you will need configure your firewal user_checker: security.user_checker.chain.main # ... - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/user_providers.rst b/security/user_providers.rst index 73b723faaaf..9bd87648baa 100644 --- a/security/user_providers.rst +++ b/security/user_providers.rst @@ -45,32 +45,6 @@ the user provider uses :doc:`Doctrine ` to retrieve them. # ... - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -140,27 +114,6 @@ To finish this, remove the ``property`` key from the user provider in # ... - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -210,30 +163,6 @@ After setting up hashing, you can configure all the user information in # ... - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -297,47 +226,6 @@ providers until the user is found: chain: providers: ['legacy_users', 'users', 'backend_users'] - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - backend_users - legacy_users - users - - - - - .. code-block:: php // config/packages/security.php @@ -467,27 +355,6 @@ the user provider by adding it in ``security.yaml``: your_custom_user_provider: id: App\Security\UserProvider - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/security/voters.rst b/security/voters.rst index 3543eae86c0..ea3f14665cb 100644 --- a/security/voters.rst +++ b/security/voters.rst @@ -49,11 +49,6 @@ which makes creating a voter even easier:: abstract protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null): bool; } -.. versionadded:: 7.3 - - The ``$vote`` argument of the ``voteOnAttribute()`` method was introduced - in Symfony 7.3. - .. _how-to-use-the-voter-in-a-controller: Setup: Checking for Access in a Controller @@ -124,6 +119,8 @@ calls out to the "voter" system. Right now, no voters will vote on whether or no the user can "view" or "edit" a ``Post``. But you can create your *own* voter that decides this using whatever logic you want. +.. _creating-the-custom-voter: + Creating the custom Voter ------------------------- @@ -210,6 +207,13 @@ would look like this:: } } +.. tip:: + + Votes define an ``$extraData`` property that you can use to store any data + that you might need later:: + + $vote->extraData['key'] = 'value'; // values can be of any type + That's it! The voter is done! Next, :ref:`configure it `. To recap, here's what's expected from the two abstract methods: @@ -433,24 +437,6 @@ security configuration: strategy: unanimous allow_if_all_abstain: false - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -480,23 +466,6 @@ option to use a custom service (your service must implement the strategy_service: App\Security\MyCustomAccessDecisionStrategy # ... - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/security.php @@ -510,6 +479,56 @@ option to use a custom service (your service must implement the ; }; +When creating custom decision strategies, you can store additional data in votes +to be used later when making a decision. For example, if not all votes should +have the same weight, you could store a ``score`` value for each vote:: + + // src/Security/PostVoter.php + namespace App\Security; + + use App\Entity\Post; + use App\Entity\User; + use Symfony\Component\Security\Core\Authentication\Token\TokenInterface; + use Symfony\Component\Security\Core\Authorization\Voter\Vote; + use Symfony\Component\Security\Core\Authorization\Voter\Voter; + + class PostVoter extends Voter + { + // ... + + protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null): bool + { + // ... + $vote->extraData['score'] = 10; + + // ... + } + } + +Then, access that value when counting votes to make a decision:: + + // src/Security/MyCustomAccessDecisionStrategy.php + use Symfony\Component\Security\Core\Authorization\Strategy\AccessDecisionStrategyInterface; + + class MyCustomAccessDecisionStrategy implements AccessDecisionStrategyInterface + { + public function decide(\Traversable $results, $accessDecision = null): bool + { + $score = 0; + + foreach ($results as $key => $result) { + $vote = $accessDecision->votes[$key]; + if (array_key_exists('score', $vote->extraData)) { + $score += $vote->extraData['score']; + } else { + $score += $vote->result; + } + } + + // ... + } + } + Custom Access Decision Manager ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -527,23 +546,6 @@ must implement the :class:`Symfony\\Component\\Security\\Core\\Authorization\\Ac service: App\Security\MyCustomAccessDecisionManager # ... - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/security.php diff --git a/serializer.rst b/serializer.rst index 0fb8f3039c0..35d4c364ffc 100644 --- a/serializer.rst +++ b/serializer.rst @@ -317,26 +317,6 @@ instance to disallow extra fields while deserializing: default_context: allow_extra_attributes: false - .. code-block:: xml - - - - - - - - - false - - - - - .. code-block:: php // config/packages/serializer.php @@ -1228,24 +1208,6 @@ setting the ``name_converter`` setting to serializer: name_converter: 'serializer.name_converter.camel_case_to_snake_case' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/serializer.php @@ -1289,24 +1251,6 @@ setting the ``name_converter`` setting to serializer: name_converter: 'serializer.name_converter.snake_case_to_camel_case' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/serializer.php @@ -1329,10 +1273,6 @@ setting the ``name_converter`` setting to ]; $serializer = new Serializer($normalizers, $encoders); -.. versionadded:: 7.2 - - The snake_case to CamelCase converter was introduced in Symfony 7.2. - .. _serializer-built-in-normalizers: Serializer Normalizers @@ -1377,10 +1317,6 @@ normalizers (in order of priority): context option ``DateTimeNormalizer::CAST_KEY`` to ``int`` or ``float``. - .. versionadded:: 7.1 - - The ``DateTimeNormalizer::CAST_KEY`` context option was introduced in Symfony 7.1. - :class:`Symfony\\Component\\Serializer\\Normalizer\\ConstraintViolationListNormalizer` This normalizer converts objects that implement :class:`Symfony\\Component\\Validator\\ConstraintViolationListInterface` @@ -1420,10 +1356,6 @@ normalizers (in order of priority): This normalizer converts between :phpclass:`BcMath\\Number` or :phpclass:`GMP` objects and strings or integers. -.. versionadded:: 7.3 - - The ``NumberNormalizer`` was introduced in Symfony 7.3. - :class:`Symfony\\Component\\Serializer\\Normalizer\\DataUriNormalizer` This normalizer converts between :phpclass:`SplFileInfo` objects and a `data URI`_ string (``data:...``) such that files can be embedded into @@ -1476,7 +1408,7 @@ normalizers (in order of priority): to read and write in the object. This allows it to access properties directly or using getters, setters, hassers, issers, canners, adders and removers. Names are generated by removing the ``get``, ``set``, - ``has``, ``is``, ``add`` or ``remove`` prefix from the method name and + ``has``, ``is``, ``can``, ``add`` or ``remove`` prefix from the method name and transforming the first letter to lowercase (e.g. ``getFirstName()`` -> ``firstName``). @@ -1512,28 +1444,6 @@ like: # register the normalizer with a high priority (called earlier) - { name: 'serializer.normalizer', priority: 500 } - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1599,10 +1509,6 @@ like: Named Serializers ----------------- -.. versionadded:: 7.2 - - Named serializers were introduced in Symfony 7.2. - Sometimes, you may need multiple configurations for the serializer, such as different default contexts, name converters, or sets of normalizers and encoders, depending on the use case. For example, when your application communicates with @@ -1627,39 +1533,6 @@ the ``named_serializers`` option: default_context: enable_max_depth: false - .. code-block:: xml - - - - - - - - - - - true - - - - - - false - - - - - - - .. code-block:: php // config/packages/serializer.php @@ -1725,32 +1598,6 @@ or :ref:`serializer.encoder ` tags: # add this normalizer to all serializers, including the default one - serializer.normalizer: { serializer: '*' } - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1771,13 +1618,6 @@ or :ref:`serializer.encoder ` tags: ; }; -.. versionadded:: 7.3 - - Before Symfony 7.3, named serializer normalizers were added automatically - to the default serializer, so you had to set their ``autoconfigure`` - option to ``false`` to disable them. As of Symfony 7.3, they are no longer - registered by default. - When the ``serializer`` attribute is not set, the service is registered only with the default serializer. @@ -1805,30 +1645,6 @@ named serializer by setting the ``include_built_in_normalizers`` and include_built_in_normalizers: false include_built_in_encoders: true - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/packages/serializer.php @@ -2471,10 +2287,6 @@ Now it deserializes like this: $invoiceLine = $serializer->deserialize('{"invoiceItem":{...},...}', InvoiceLine::class, 'json'); // $invoiceLine contains new InvoiceLine(new Product(...)) -.. versionadded:: 7.3 - - The ``defaultType`` parameter was added in Symfony 7.3. - .. _serializer-unwrapping-denormalizer: Deserializing Input Partially (Unwrapping) @@ -2536,10 +2348,6 @@ setting the serializer context option Handling Boolean Values ~~~~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 7.1 - - The ``AbstractNormalizer::FILTER_BOOL`` context option was introduced in Symfony 7.1. - PHP considers many different values as true or false. For example, the strings ``true``, ``1``, and ``yes`` are considered true, while ``false``, ``0``, and ``no`` are considered false. diff --git a/serializer/custom_name_converter.rst b/serializer/custom_name_converter.rst index 49dafb02cc4..8fd6f419eec 100644 --- a/serializer/custom_name_converter.rst +++ b/serializer/custom_name_converter.rst @@ -43,19 +43,6 @@ A custom name converter can handle such cases:: } } -.. versionadded:: 7.1 - - Accessing the current class name, format and context via - :method:`Symfony\\Component\\Serializer\\NameConverter\\NameConverterInterface::normalize` - and :method:`Symfony\\Component\\Serializer\\NameConverter\\NameConverterInterface::denormalize` - was introduced in Symfony 7.1. - -.. note:: - - You can also implement - :class:`Symfony\\Component\\Serializer\\NameConverter\\AdvancedNameConverterInterface` - to access the current class name, format and context. - Then, configure the serializer to use your name converter: .. configuration-block:: @@ -68,25 +55,6 @@ Then, configure the serializer to use your name converter: # pass the service ID of your name converter name_converter: 'App\Serializer\OrgPrefixNameConverter' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/serializer.php diff --git a/serializer/custom_normalizer.rst b/serializer/custom_normalizer.rst index 9e3b6c94544..21c0c00791c 100644 --- a/serializer/custom_normalizer.rst +++ b/serializer/custom_normalizer.rst @@ -86,27 +86,6 @@ If you're not using ``autoconfigure``, you have to tag the service with # register the normalizer with a high priority (called earlier) - { name: 'serializer.normalizer', priority: 500 } - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/serializer/encoders.rst b/serializer/encoders.rst index 3d75d9073cf..8d3a53cab3a 100644 --- a/serializer/encoders.rst +++ b/serializer/encoders.rst @@ -64,13 +64,6 @@ are available to customize the behavior of the encoder: Sets the field enclosure (one character only). ``csv_end_of_line`` (default: ``\n``) Sets the character(s) used to mark the end of each line in the CSV file. -``csv_escape_char`` (default: empty string) - - .. deprecated:: 7.2 - - The ``csv_escape_char`` option was deprecated in Symfony 7.2. - - Sets the escape character (at most one character). ``csv_key_separator`` (default: ``.``) Sets the separator for array's keys during its flattening ``csv_headers`` (default: ``[]``, inferred from input data's keys) @@ -205,16 +198,15 @@ These are the options available on the :ref:`serializer context &]/``) A regular expression pattern to determine if a value should be wrapped in a CDATA section. +``cdata_wrapping_name_pattern`` (default: ``false``) + A regular expression pattern that defines the names of fields whose values + should always be wrapped in a CDATA section, even if their contents don't + require it. Example: ``'/(firstname|lastname)/'`` ``ignore_empty_attributes`` (default: ``false``) If set to true, ignores all attributes with empty values in the generated XML - -.. versionadded:: 7.1 - - The ``cdata_wrapping_pattern`` option was introduced in Symfony 7.1. - -.. versionadded:: 7.3 - - The ``ignore_empty_attributes`` option was introduced in Symfony 7.3. +``preserve_numeric_keys`` (default: ``false``) + If set to true, it keeps numeric array indexes (e.g. ````) + instead of collapsing them into ```` nodes. Example with a custom ``context``:: @@ -246,6 +238,45 @@ Example with a custom ``context``:: // 2019-10-24 // +Example with ``preserve_numeric_keys``:: + + use Symfony\Component\Serializer\Encoder\XmlEncoder; + + $data = [ + 'person' => [ + ['firstname' => 'Benjamin', 'lastname' => 'Alexandre'], + ['firstname' => 'Damien', 'lastname' => 'Clay'], + ], + ]; + + $xmlEncoder->encode($data, 'xml', ['preserve_numeric_keys' => false]); + // outputs: + // + // + // Benjamin + // Alexandre + // + // + // Damien + // Clay + // + // + + $xmlEncoder->encode($data, 'xml', ['preserve_numeric_keys' => true]); + // outputs: + // + // + // + // Benjamin + // Alexandre + // + // + // Damien + // Clay + // + // + // + The ``YamlEncoder`` ------------------- @@ -331,24 +362,6 @@ to register your class as a service and tag it with App\Serializer\NeonEncoder: tags: ['serializer.encoder'] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/serializer/streaming_json.rst b/serializer/streaming_json.rst index 3fd44824bc6..aa17b7ebfc7 100644 --- a/serializer/streaming_json.rst +++ b/serializer/streaming_json.rst @@ -1,11 +1,6 @@ Streaming JSON ============== -.. versionadded:: 7.3 - - The JsonStreamer component was introduced in Symfony 7.3 as an - :doc:`experimental feature `. - Symfony can encode PHP data structures to JSON streams and decode JSON streams back into PHP data structures. @@ -541,6 +536,12 @@ When callables are not enough, you can use a service implementing the The ``getStreamValueType()`` method must return the value's type as it will appear in the JSON stream. +.. tip:: + + The ``$options`` argument of the ``transform()`` method includes a special + option called ``_current_object`` which gives access to the object holding + the current property (or ``null`` if there's none). + To use this transformer in a class, configure the ``#[ValueTransformer]`` attribute:: // src/Dto/Dog.php diff --git a/service_container.rst b/service_container.rst index 8b86d06a833..8c65ea9eec8 100644 --- a/service_container.rst +++ b/service_container.rst @@ -168,31 +168,6 @@ each time you ask for it. # ... - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -240,21 +215,6 @@ each time you ask for it. - '../src/AnotherDirectory/' - '../src/SomeFile.php' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/services.php @@ -319,10 +279,6 @@ environment, you can use the ``#[WhenNot]`` attribute:: // ... } -.. versionadded:: 7.2 - - The ``#[WhenNot]`` attribute was introduced in Symfony 7.2. - .. _services-constructor-injection: Injecting Services/Config into a Service @@ -421,54 +377,6 @@ as arguments of other services: first: !php/const true second: 'Foo' - .. code-block:: xml - - - - - - - - - Foo - 7 - 3.14 - - Foo - - true - - - E_ALL - PDO::FETCH_NUM - Symfony\Component\HttpKernel\Kernel::VERSION - App\Config\SomeEnum::SomeCase - - - - - - VGhpcyBpcyBhIEJlbGwgY2hhciAH - - - - true - Foo - - - - - - - .. code-block:: php // config/services.php @@ -639,32 +547,6 @@ pass here. No problem! In your configuration, you can explicitly set this argume arguments: $adminEmail: 'manager@example.com' - .. code-block:: xml - - - - - - - - - - - - - - - manager@example.com - - - - .. code-block:: php // config/services.php @@ -704,8 +586,7 @@ all their types (string, boolean, array, binary and PHP constant parameters). However, there is another type of parameter related to services. In YAML config, any string which starts with ``@`` is considered as the ID of a service, instead -of a regular string. In XML config, use the ``type="service"`` type for the -parameter and in PHP config use the ``service()`` function: +of a regular string. In PHP config use the ``service()`` function: .. configuration-block:: @@ -723,22 +604,6 @@ parameter and in PHP config use the ``service()`` function: # the following example would be parsed as the string '@securepassword' # - '@@securepassword' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -824,25 +689,6 @@ But, you can control this and pass in a different logger: # and not just the *string* 'monolog.logger.request' $logger: '@monolog.logger.request' - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -956,26 +802,6 @@ Our configuration looks like this: $logger: '@monolog.logger.request' $generateMessageHash: !closure '@App\Hash\MessageHashGenerator' - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1032,43 +858,6 @@ You can also use the ``bind`` keyword to bind specific arguments by name or type # ... - .. code-block:: xml - - - - - - - - manager@example.com - - - - - manager@example.com - - - - - - - - .. code-block:: php // config/services.php @@ -1133,24 +922,6 @@ the name of the argument and some short description about its purpose: # ... - .. code-block:: xml - - - - - - - - should be defined by Pass - - - - - - .. code-block:: php // config/services.php @@ -1230,10 +1001,6 @@ application to production (e.g. in your continuous integration server): # the command will fail if any of those environment variables are missing $ php bin/console lint:container --resolve-env-vars -.. versionadded:: 7.2 - - The ``--resolve-env-vars`` option was introduced in Symfony 7.2. - Performing those checks whenever the container is compiled can hurt performance. That's why they are implemented in :doc:`compiler passes ` called ``CheckTypeDeclarationsPass`` and ``CheckAliasValidityPass``, which are @@ -1241,10 +1008,6 @@ disabled by default and enabled only when executing the ``lint:container`` comma If you don't mind the performance loss, you can enable these compiler passes in your application. -.. versionadded:: 7.1 - - The ``CheckAliasValidityPass`` compiler pass was introduced in Symfony 7.1. - .. _container-public: Public Versus Private Services @@ -1273,23 +1036,6 @@ setting: App\Service\PublicService: public: true - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1343,22 +1089,6 @@ key. For example, the default Symfony configuration contains this: resource: '../src/' exclude: '../src/{DependencyInjection,Entity,Kernel.php}' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1417,23 +1147,6 @@ for classes under the same namespace: resource: '../src/Domain/*' # ... - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1509,34 +1222,6 @@ admin email. In this case, each needs to have a unique service id: # the site_update_manager.superadmin will be used App\Service\SiteUpdateManager: '@site_update_manager.superadmin' - .. code-block:: xml - - - - - - - - - - - - superadmin@example.com - - - - - - contact@example.com - - - - - - .. code-block:: php // config/services.php @@ -1674,27 +1359,6 @@ an adapter for a functional interface through configuration: class: App\Service\MessageFormatterInterface from_callable: [!service {class: 'App\Service\MessageUtils'}, 'format'] - .. code-block:: xml - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/alias_private.rst b/service_container/alias_private.rst index 22bf649d861..b0425469f05 100644 --- a/service_container/alias_private.rst +++ b/service_container/alias_private.rst @@ -35,19 +35,6 @@ You can also control the ``public`` option on a service-by-service basis: App\Service\Foo: public: true - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/services.php @@ -133,22 +120,6 @@ services. alias: App\Mail\PhpMailer public: true - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -203,10 +174,6 @@ The ``#[AsAlias]`` attribute can also be limited to one or more specific // ... } -.. versionadded:: 7.3 - - The ``when`` argument of the ``#[AsAlias]`` attribute was introduced in Symfony 7.3. - .. tip:: When using ``#[AsAlias]`` attribute, you may omit passing ``id`` argument @@ -251,27 +218,6 @@ or you decided not to maintain it anymore), you can deprecate its definition: version: '1.2' message: 'The "%alias_id%" alias is deprecated. Do not use it anymore.' - .. code-block:: xml - - - - - - - - - - - - The "%alias_id%" service alias is deprecated. Don't use it anymore. - - - - - .. code-block:: php $container @@ -317,24 +263,6 @@ The following example shows how to inject an anonymous service into another serv - !service class: App\AnonymousBar - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -368,24 +296,6 @@ Using an anonymous service as a factory looks like this: App\Foo: factory: [ !service { class: App\FooFactory }, 'constructFoo' ] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -418,21 +328,6 @@ or you decided not to maintain it anymore), you can deprecate its definition: version: '2.8' message: The "%service_id%" service is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0. - .. code-block:: xml - - - - - - - - The "%service_id%" service is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0. - - - - .. code-block:: php // config/services.php diff --git a/service_container/autowiring.rst b/service_container/autowiring.rst index 7d7aff64271..6ff0c9c67d6 100644 --- a/service_container/autowiring.rst +++ b/service_container/autowiring.rst @@ -80,25 +80,6 @@ both services: App\Util\Rot13Transformer: autowire: true - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -215,22 +196,6 @@ adding a service alias: # an App\Util\Rot13Transformer type-hint is detected App\Util\Rot13Transformer: '@app.rot13.transformer' - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -321,22 +286,6 @@ To fix that, add an :ref:`alias `: # an App\Util\TransformerInterface type-hint is detected App\Util\TransformerInterface: '@App\Util\Rot13Transformer' - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -476,30 +425,6 @@ the injection:: # $transformer: '@App\Util\UppercaseTransformer' # ... - .. code-block:: xml - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -794,11 +719,6 @@ by using the property name as method name:: } } -.. versionadded:: 7.1 - - The :class:`Symfony\\Component\\DependencyInjection\\Attribute\\AutowireMethodOf` - attribute was introduced in Symfony 7.1. - .. _autowiring-calls: Autowiring other Methods (e.g. Setters and Public Typed Properties) @@ -865,10 +785,6 @@ typed properties: Autowiring Anonymous Services Inline ------------------------------------ -.. versionadded:: 7.1 - - The ``#[AutowireInline]`` attribute was added in Symfony 7.1. - Similar to how anonymous services can be defined inline in configuration files, the :class:`Symfony\\Component\\DependencyInjection\\Attribute\\AutowireInline` attribute allows you to declare anonymous services inline, directly next to their diff --git a/service_container/calls.rst b/service_container/calls.rst index cb364b59489..67777e25728 100644 --- a/service_container/calls.rst +++ b/service_container/calls.rst @@ -40,25 +40,6 @@ To configure the container to call the ``setLogger`` method, use the ``calls`` k calls: - setLogger: ['@logger'] - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -112,25 +93,6 @@ The configuration to tell the container it should do so would be like: calls: - withLogger: !returns_clone ['@logger'] - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/configurators.rst b/service_container/configurators.rst index 7817a383761..460aa65d1d5 100644 --- a/service_container/configurators.rst +++ b/service_container/configurators.rst @@ -136,28 +136,6 @@ all the classes are already loaded as services. All you need to do is specify th App\Mail\GreetingCardManager: configurator: ['@App\Mail\EmailConfigurator', 'configure'] - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -206,28 +184,6 @@ Services can be configured via invokable configurators (replacing the App\Mail\GreetingCardManager: configurator: '@App\Mail\EmailConfigurator' - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/debug.rst b/service_container/debug.rst index 9e3e28a5343..0a7898108fb 100644 --- a/service_container/debug.rst +++ b/service_container/debug.rst @@ -51,9 +51,3 @@ its id: .. code-block:: terminal $ php bin/console debug:container App\Service\Mailer - -.. deprecated:: 7.3 - - Starting in Symfony 7.3, this command displays the service arguments by default. - In earlier Symfony versions, you needed to use the ``--show-arguments`` option, - which is now deprecated. diff --git a/service_container/definitions.rst b/service_container/definitions.rst index a2a50591668..6240f56e126 100644 --- a/service_container/definitions.rst +++ b/service_container/definitions.rst @@ -6,7 +6,7 @@ build a service. They are not the actual services used by your applications. The container will create the actual class instances based on the configuration in the definition. -Normally, you would use YAML, XML or PHP to describe the service definitions. +Normally, you would use YAML or PHP to describe the service definitions. But if you're doing advanced things with the service container, like working with a :doc:`Compiler Pass ` or creating a :doc:`Dependency Injection Extension `, you may need to diff --git a/service_container/expression_language.rst b/service_container/expression_language.rst index 41c538db468..88a6dd0fa27 100644 --- a/service_container/expression_language.rst +++ b/service_container/expression_language.rst @@ -27,26 +27,6 @@ to another service: ``App\Mailer``. One way to do this is with an expression: # when using double-quoted strings, the backslash needs to be escaped twice (see https://yaml.org/spec/1.2/spec.html#id2787109) # arguments: ["@=service('App\\\\Mail\\\\MailerConfiguration').getMailerMethod()"] - .. code-block:: xml - - - - - - - - - - - - service('App\\Mail\\MailerConfiguration').getMailerMethod() - - - - .. code-block:: php // config/services.php @@ -89,22 +69,6 @@ via a ``container`` variable. Here's another example: # the '@=' prefix is required when using expressions for arguments in YAML files arguments: ["@=container.hasParameter('some_param') ? parameter('some_param') : 'default_value'"] - .. code-block:: xml - - - - - - - - container.hasParameter('some_param') ? parameter('some_param') : 'default_value' - - - - .. code-block:: php // config/services.php diff --git a/service_container/factories.rst b/service_container/factories.rst index 9864287d57a..4ecde32af5e 100644 --- a/service_container/factories.rst +++ b/service_container/factories.rst @@ -49,23 +49,6 @@ create its object: # the first argument is the class and the second argument is the static method factory: ['App\Email\NewsletterManagerStaticFactory', 'createNewsletterManager'] - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -132,22 +115,6 @@ You can omit the class on the factory declaration: arguments: $sender: 'fabien@symfony.com' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -201,21 +168,6 @@ as the factory class: arguments: $sender: 'fabien@symfony.com' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/services.php @@ -253,29 +205,6 @@ Configuration of the service container then looks like this: App\Email\NewsletterManager: factory: ['@App\Email\NewsletterManagerFactory', 'createNewsletterManager'] - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -335,25 +264,6 @@ method name: class: App\Email\NewsletterManager factory: '@App\Email\InvokableNewsletterManagerFactory' - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -393,29 +303,6 @@ e.g. change the service based on a parameter: arguments: - '@App\Email\NewsletterManagerFactory' - .. code-block:: xml - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -467,25 +354,6 @@ previous examples takes the ``templating`` service as an argument: factory: ['@App\Email\NewsletterManagerFactory', createNewsletterManager] arguments: ['@templating'] - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/import.rst b/service_container/import.rst index 47af34d3a34..ab1a846045c 100644 --- a/service_container/import.rst +++ b/service_container/import.rst @@ -4,7 +4,7 @@ How to Import Configuration Files/Resources .. tip:: In this section, service configuration files are referred to as *resources*. - While most configuration resources are files (e.g. YAML, XML, PHP), Symfony is + While most configuration resources are files (e.g. YAML, PHP), Symfony is able to load configuration from anywhere (e.g. a database or even via an external web service). @@ -38,24 +38,6 @@ decided to move some configuration to a new file: services: # ... some services - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services/mailer.php @@ -85,30 +67,6 @@ a relative or absolute path to the imported file: # ... - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -173,33 +131,6 @@ from auto-registering classes that are defined manually elsewhere: - '../src/Mailer/' - '../src/SpecificClass.php' - .. code-block:: xml - - - - - - - - - - - - - - - - ../src/Mailer/ - ../src/SpecificClass.php - - - - - - .. code-block:: php // config/services.php @@ -246,34 +177,6 @@ same file. These later definitions will override the auto-registered ones: App\Mailer\MyMailer: arguments: ['%env(MAILER_DSN)%'] - .. code-block:: xml - - - - - - - - - - - - - - - - - - %env(MAILER_DSN)% - - - - - - .. code-block:: php // config/services.php @@ -329,57 +232,6 @@ can override the auto-discovered ones. # definitions here override anything from the imports above # consider keeping most definitions inside imported files - .. code-block:: xml - - - - - - - - - - ../../src/Mailer/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services/autodiscovery.php diff --git a/service_container/injection_types.rst b/service_container/injection_types.rst index 91c2a562d81..48c87e02389 100644 --- a/service_container/injection_types.rst +++ b/service_container/injection_types.rst @@ -44,24 +44,6 @@ service container configuration: App\Mail\NewsletterManager: arguments: ['@mailer'] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -147,26 +129,6 @@ In order to use this type of injection, don't forget to configure it: calls: - withMailer: !returns_clone ['@mailer'] - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -246,26 +208,6 @@ that accepts the dependency:: calls: - setMailer: ['@mailer'] - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -330,24 +272,6 @@ Another possibility is setting public fields of the class directly:: properties: mailer: '@mailer' - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/lazy_services.rst b/service_container/lazy_services.rst index abb3c2cca7f..0959e18ebd1 100644 --- a/service_container/lazy_services.rst +++ b/service_container/lazy_services.rst @@ -42,20 +42,6 @@ You can mark the service as ``lazy`` by manipulating its definition: App\Twig\AppExtension: lazy: true - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/services.php @@ -138,10 +124,6 @@ It defines an optional parameter used to define interfaces for proxy and interse ) { } -.. versionadded:: 7.1 - - The ``#[Lazy]`` attribute was introduced in Symfony 7.1. - Interface Proxifying -------------------- @@ -165,24 +147,6 @@ specific interfaces. tags: - { name: 'proxy', interface: 'Twig\Extension\ExtensionInterface' } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/optional_dependencies.rst b/service_container/optional_dependencies.rst index bc8f03cf7e0..ec77a95777f 100644 --- a/service_container/optional_dependencies.rst +++ b/service_container/optional_dependencies.rst @@ -13,24 +13,6 @@ if the service does not exist: .. configuration-block:: - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -69,24 +51,6 @@ call if the service exists and remove the method call if it does not: calls: - setLogger: ['@?logger'] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/parent_services.rst b/service_container/parent_services.rst index b82222c43af..8112c224f3c 100644 --- a/service_container/parent_services.rst +++ b/service_container/parent_services.rst @@ -78,37 +78,6 @@ avoid duplicated service definitions: # ... - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -184,39 +153,6 @@ the child class: arguments: index_0: '@doctrine.custom_entity_manager' - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/service_closures.rst b/service_container/service_closures.rst index 88b0ab64002..73aed59bdd3 100644 --- a/service_container/service_closures.rst +++ b/service_container/service_closures.rst @@ -59,26 +59,6 @@ argument of type ``service_closure``: # the shortcut also works for optional dependencies # arguments: ['@>?mailer'] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -97,10 +77,6 @@ argument of type ``service_closure``: // ->args([service_closure('mailer')->ignoreOnInvalid()]); }; -.. versionadded:: 7.3 - - The ``@>`` shortcut syntax for YAML was introduced in Symfony 7.3. - .. seealso:: Service closures can be injected :ref:`by using autowiring ` diff --git a/service_container/service_decoration.rst b/service_container/service_decoration.rst index 7b5e8edbcc2..81399eb4b49 100644 --- a/service_container/service_decoration.rst +++ b/service_container/service_decoration.rst @@ -16,23 +16,6 @@ When overriding an existing definition, the original service is lost: App\Mailer: class: App\NewMailer - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -84,26 +67,6 @@ but keeps a reference of the old one as ``.inner``: # but that service is still available as ".inner" decorates: App\Mailer - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -123,6 +86,11 @@ but keeps a reference of the old one as ``.inner``: ->decorate(Mailer::class); }; +.. tip:: + + You can apply multiple ``#[AsDecorator]`` attributes to the same class to + decorate multiple services with it. + The ``decorates`` option tells the container that the ``App\DecoratingMailer`` service replaces the ``App\Mailer`` service. If you're using the :ref:`default services.yaml configuration `, @@ -170,26 +138,6 @@ automatically changed to ``'.inner'``): # pass the old service as an argument arguments: ['@.inner'] - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -238,40 +186,6 @@ name via the ``decoration_inner_name`` option: decoration_inner_name: 'App\Mailer.original' arguments: ['@App\Mailer.original'] - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -364,28 +278,6 @@ the ``decoration_priority`` option. Its value is an integer that defaults to decoration_priority: 1 arguments: ['@.inner'] - .. code-block:: xml - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -443,35 +335,6 @@ ordered services, each one decorating the next: - Bar: ~ - Foo: ~ - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -526,32 +389,6 @@ advanced example of composition: - Bar: ~ - Foo: ~ - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -605,15 +442,6 @@ The result will be:: Baz: ~ # ... - .. code-block:: xml - - - - - - - - .. code-block:: php // ... @@ -667,24 +495,6 @@ Three different behaviors are available: decoration_on_invalid: ignore arguments: ['@.inner'] - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/service_subscribers_locators.rst b/service_container/service_subscribers_locators.rst index 9026478cf33..f9f39a70abf 100644 --- a/service_container/service_subscribers_locators.rst +++ b/service_container/service_subscribers_locators.rst @@ -135,11 +135,6 @@ count and iterate over the services of the locator:: // do something with the service, the service id or both } -.. versionadded:: 7.1 - - The :class:`Symfony\\Contracts\\Service\\ServiceCollectionInterface` was - introduced in Symfony 7.1. - Including Services ------------------ @@ -226,23 +221,6 @@ service type to a service. tags: - { name: 'container.service_subscriber', key: 'logger', id: 'monolog.logger.event' } - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -307,14 +285,6 @@ This is done by having ``getSubscribedServices()`` return an array of ]; } -.. deprecated:: 7.1 - - The :class:`Symfony\\Component\\DependencyInjection\\Attribute\\TaggedIterator` - and :class:`Symfony\\Component\\DependencyInjection\\Attribute\\TaggedLocator` - attributes were deprecated in Symfony 7.1 in favor of - :class:`Symfony\\Component\\DependencyInjection\\Attribute\\AutowireIterator` - and :class:`Symfony\\Component\\DependencyInjection\\Attribute\\AutowireLocator`. - .. note:: The above example requires using ``3.2`` version or newer of ``symfony/service-contracts``. @@ -459,7 +429,7 @@ some services into it via a service locator:: } } -Symfony allows you to inject the service locator using YAML/XML/PHP configuration +Symfony allows you to inject the service locator using YAML or PHP configuration or directly via PHP attributes: .. configuration-block:: @@ -492,24 +462,6 @@ or directly via PHP attributes: App\FooCommand: '@app.command_handler.foo' App\BarCommand: '@app.command_handler.bar' - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -555,31 +507,6 @@ other services. To do so, create a new service definition using the # add the following tag to the service definition: # tags: ['container.service_locator'] - .. code-block:: xml - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -634,23 +561,6 @@ Now you can inject the service locator in any other services: App\CommandBus: arguments: ['@app.command_handler_locator'] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -739,31 +649,6 @@ to index the services: # inject all services tagged with app.handler as first argument arguments: [!tagged_locator { tag: 'app.handler', index_by: 'key' }] - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -848,25 +733,6 @@ get the value used to index the services: # inject all services tagged with app.handler as first argument arguments: [!tagged_locator { tag: 'app.handler', default_index_method: 'getLocatorKey' }] - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -937,11 +803,6 @@ services based on type-hinted helper methods:: } } -.. versionadded:: 7.1 - - The ``ServiceMethodsSubscriberTrait`` was introduced in Symfony 7.1. - In previous Symfony versions it was called ``ServiceSubscriberTrait``. - This allows you to create helper traits like RouterAware, LoggerAware, etc... and compose your services with them:: diff --git a/service_container/shared.rst b/service_container/shared.rst index 4e79ae28116..fa3aae90278 100644 --- a/service_container/shared.rst +++ b/service_container/shared.rst @@ -32,13 +32,6 @@ in your service definition: shared: false # ... - .. code-block:: xml - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/synthetic_services.rst b/service_container/synthetic_services.rst index 09b195db02c..9f60bb7ddaf 100644 --- a/service_container/synthetic_services.rst +++ b/service_container/synthetic_services.rst @@ -41,23 +41,6 @@ configuration: app.synthetic_service: synthetic: true - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php diff --git a/service_container/tags.rst b/service_container/tags.rst index 3444569a604..0814f242c59 100644 --- a/service_container/tags.rst +++ b/service_container/tags.rst @@ -14,22 +14,6 @@ example: App\Twig\AppExtension: tags: ['twig.extension'] - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -81,20 +65,6 @@ If you want to apply tags automatically for your own services, use the tags: ['app.custom_tag'] # ... - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -317,20 +287,6 @@ Then, define the chain as a service: services: App\Mail\TransportChain: ~ - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/services.php @@ -364,28 +320,6 @@ For example, you may add the following transports as services: MailerSendmailTransport: tags: ['app.mail_transport'] - .. code-block:: xml - - - - - - - - %mailer_host% - - - - - - - - - - .. code-block:: php // config/services.php @@ -523,33 +457,6 @@ To answer this, change the service declaration: tags: - { name: 'app.mail_transport', alias: ['sendmail', 'anotherAlias']} - .. code-block:: xml - - - - - - - - %mailer_host% - - - - - - - - sendmail - anotherAlias - - - - - - .. code-block:: php // config/services.php @@ -571,7 +478,7 @@ To answer this, change the service declaration: .. tip:: The ``name`` attribute is used by default to define the name of the tag. - If you want to add a ``name`` attribute to some tag in XML or YAML formats, + If you want to add a ``name`` attribute to some tag in YAML format, you need to use this special syntax: .. configuration-block:: @@ -588,26 +495,6 @@ To answer this, change the service declaration: # this is a tag called 'app.mail_transport' with two attributes ('name' and 'alias') - app.mail_transport: { name: 'arbitrary-value', alias: 'smtp' } - .. code-block:: xml - - - - - - - - %mailer_host% - - - - app.mail_transport - - - - .. tip:: In YAML format, you may provide the tag as a simple string as long as @@ -682,7 +569,7 @@ all services tagged with ``app.handler`` into its constructor argument:: } } -Symfony allows you to inject the services using YAML/XML/PHP configuration or +Symfony allows you to inject the services using YAML or PHP configuration or directly via PHP attributes: .. configuration-block:: @@ -719,31 +606,6 @@ directly via PHP attributes: arguments: - !tagged_iterator app.handler - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -809,32 +671,6 @@ iterator, add the ``exclude`` option: arguments: - !tagged_iterator { tag: app.handler, exclude: ['App\Handler\Three'] } - .. code-block:: xml - - - - - - - - - - - - - - - - - App\Handler\Three - - - - - .. code-block:: php // config/services.php @@ -892,32 +728,6 @@ disabled by setting the ``exclude_self`` option to ``false``: arguments: - !tagged_iterator { tag: app.handler, exclude: ['App\Handler\Three'], exclude_self: false } - .. code-block:: xml - - - - - - - - - - - - - - - - - App\Handler\Three - - - - - .. code-block:: php // config/services.php @@ -960,22 +770,6 @@ the number, the earlier the tagged service will be located in the collection: tags: - { name: 'app.handler', priority: 20 } - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1037,28 +831,11 @@ you can define it in the configuration of the collecting service: arguments: - !tagged_iterator { tag: app.handler, default_priority_method: getPriority } - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/services.php namespace Symfony\Component\DependencyInjection\Loader\Configurator; - use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument; - return function (ContainerConfigurator $container): void { $services = $container->services(); @@ -1117,30 +894,6 @@ to index the services: App\HandlerCollection: arguments: [!tagged_iterator { tag: 'app.handler', index_by: 'key' }] - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1148,7 +901,6 @@ to index the services: use App\Handler\One; use App\Handler\Two; - use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument; return function (ContainerConfigurator $container): void { $services = $container->services(); @@ -1225,34 +977,12 @@ get the value used to index the services: App\HandlerCollection: arguments: [!tagged_iterator { tag: 'app.handler', default_index_method: 'getIndex' }] - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php // config/services.php namespace Symfony\Component\DependencyInjection\Loader\Configurator; use App\HandlerCollection; - use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument; return function (ContainerConfigurator $container) { $services = $container->services(); @@ -1309,9 +1039,4 @@ same service under different indexes:: // ... } -.. versionadded:: 7.3 - - The feature to apply the ``#[AsTaggedItem]`` attribute multiple times was - introduced in Symfony 7.3. - .. _`PHP constructor promotion`: https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion diff --git a/session.rst b/session.rst index 9fec0e46441..e787fa216f2 100644 --- a/session.rst +++ b/session.rst @@ -301,32 +301,6 @@ configuration ` in cookie_samesite: lax storage_factory_id: session.storage.factory.native - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -384,24 +358,6 @@ session metadata files: handler_id: 'session.handler.native_file' save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -436,11 +392,6 @@ Check out the Symfony config reference to learn more about the other available ``session.auto_start = 1`` This directive should be turned off in ``php.ini``, in the web server directives or in ``.htaccess``. -.. deprecated:: 7.2 - - The ``sid_length`` and ``sid_bits_per_character`` options were deprecated - in Symfony 7.2 and will be ignored in Symfony 8.0. - The session cookie is also available in :ref:`the Response object `. This is useful to get that cookie in the CLI context or when using PHP runners like Roadrunner or Swoole. @@ -523,11 +474,6 @@ Alternatively, you can configure these settings by passing ``gc_probability``, or to the :method:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\NativeSessionStorage::setOptions` method. -.. versionadded:: 7.2 - - Using the ``php.ini`` directive as the default value for ``gc_probability`` - was introduced in Symfony 7.2. - .. _session-database: Store Sessions in a Database @@ -592,46 +538,6 @@ a Symfony service for the connection to the Redis server: # - auth: # - ['%env(REDIS_USER)%','%env(REDIS_PASSWORD)%'] - .. code-block:: xml - - - - - - - - - %env(REDIS_HOST)% - %env(int:REDIS_PORT)% - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -670,24 +576,6 @@ configuration option to tell Symfony to use this service as the session handler: session: handler_id: Symfony\Component\HttpFoundation\Session\Storage\Handler\RedisSessionHandler - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -745,31 +633,6 @@ To use it, first register a new handler service with your database credentials: # - 'mysql:dbname=mydatabase; host=myhost; port=myport' # - { db_username: myuser, db_password: mypassword } - .. code-block:: xml - - - - - - - - %env(DATABASE_URL)% - - - - - - - .. code-block:: php // config/services.php @@ -808,25 +671,6 @@ configuration option to tell Symfony to use this service as the session handler: # ... handler_id: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -860,26 +704,6 @@ passed to the ``PdoSessionHandler`` service: - '%env(DATABASE_URL)%' - { db_table: 'customer_session', db_id_col: 'guid' } - .. code-block:: xml - - - - - - - - %env(DATABASE_URL)% - - customer_session - guid - - - - - .. code-block:: php // config/services.php @@ -1055,28 +879,6 @@ the MongoDB connection as argument, and the required parameters: - '@doctrine_mongodb.odm.default_connection' - { database: '%env(MONGODB_DB)%', collection: 'sessions' } - .. code-block:: xml - - - - - - - - doctrine_mongodb.odm.default_connection - - %env('MONGODB_DB')% - sessions - - - - - .. code-block:: php // config/services.php @@ -1108,25 +910,6 @@ configuration option to tell Symfony to use this service as the session handler: # ... handler_id: Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1174,28 +957,6 @@ configure these values with the second argument passed to the id_field: '_guid' expiry_field: 'eol' - .. code-block:: xml - - - - - - - - doctrine_mongodb.odm.default_connection - - %env('MONGODB_DB')% - sessions - _guid - eol - - - - - .. code-block:: php // config/services.php @@ -1288,18 +1049,6 @@ You need to pass the TTL in the options array of the session handler you are usi - '@Redis' - { 'ttl': 600 } - .. code-block:: xml - - - - - - - 600 - - - - .. code-block:: php // config/services.php @@ -1338,23 +1087,6 @@ has to return an integer which will be used as TTL. # Inject whatever dependencies you need to be able to resolve a TTL for the current session - '@security' - .. code-block:: xml - - - - - - - - - - - - - - - - .. code-block:: php // config/services.php @@ -1455,25 +1187,6 @@ via some "Change Locale" route & controller), or create a route with the # uncomment the next line if you are not using autoconfigure # tags: [kernel.event_subscriber] - .. code-block:: xml - - - - - - - - %kernel.default_locale% - - - - - - - .. code-block:: php // config/services.php @@ -1584,21 +1297,6 @@ Symfony to use your session handler instead of the default one: # ... handler_id: App\Session\CustomSessionHandler - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1683,25 +1381,6 @@ Then, register the ``SodiumMarshaller`` service using this key: - ['%env(file:resolve:SESSION_DECRYPTION_FILE)%'] - '@.inner' - .. code-block:: xml - - - - - - - - env(file:resolve:SESSION_DECRYPTION_FILE) - - - - - - .. code-block:: php // config/services.php @@ -1792,23 +1471,6 @@ for the ``handler_id``: storage_factory_id: session.storage.factory.php_bridge handler_id: ~ - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1852,23 +1514,6 @@ the example below: storage_factory_id: session.storage.factory.php_bridge handler_id: session.handler.native_file - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/framework.php diff --git a/setup.rst b/setup.rst index a7fa8c66826..3d18a9b9388 100644 --- a/setup.rst +++ b/setup.rst @@ -14,7 +14,7 @@ Technical Requirements Before creating your first Symfony application you must: -* Install PHP 8.2 or higher and these PHP extensions (which are installed and +* Install PHP 8.4 or higher and these PHP extensions (which are installed and enabled by default in most PHP 8 installations): `Ctype`_, `iconv`_, `PCRE`_, `Session`_, `SimpleXML`_, and `Tokenizer`_; * `Install Composer`_, which is used to install PHP packages. @@ -48,10 +48,10 @@ application: .. code-block:: terminal # run this if you are building a traditional web application - $ symfony new my_project_directory --version="7.3.x" --webapp + $ symfony new my_project_directory --version="8.0.x" --webapp # run this if you are building a microservice, console application or API - $ symfony new my_project_directory --version="7.3.x" + $ symfony new my_project_directory --version="8.0.x" The only difference between these two commands is the number of packages installed by default. The ``--webapp`` option installs extra packages to give @@ -63,12 +63,12 @@ Symfony application using Composer: .. code-block:: terminal # run this if you are building a traditional web application - $ composer create-project symfony/skeleton:"7.3.x" my_project_directory + $ composer create-project symfony/skeleton:"8.0.x" my_project_directory $ cd my_project_directory $ composer require webapp # run this if you are building a microservice, console application or API - $ composer create-project symfony/skeleton:"7.3.x" my_project_directory + $ composer create-project symfony/skeleton:"8.0.x" my_project_directory No matter which command you run to create the Symfony application. All of them will create a new ``my_project_directory/`` directory, download some dependencies diff --git a/string.rst b/string.rst index 026ef587dca..c4e681d495f 100644 --- a/string.rst +++ b/string.rst @@ -237,19 +237,6 @@ Methods to Change Case // other cases can be achieved by chaining methods, e.g. : u('Foo: Bar-baz.')->camel()->upper(); // 'FOOBARBAZ' -.. versionadded:: 7.1 - - The ``localeLower()``, ``localeUpper()`` and ``localeTitle()`` methods were - introduced in Symfony 7.1. - -.. versionadded:: 7.2 - - The ``kebab()`` method was introduced in Symfony 7.2. - -.. versionadded:: 7.3 - - The ``pascal()`` method was introduced in Symfony 7.3. - The methods of all string classes are case-sensitive by default. You can perform case-insensitive operations with the ``ignoreCase()`` method:: @@ -415,10 +402,6 @@ Methods to Join, Split, Truncate and Reverse // returns up to the last complete word that fits in the given length, surpassing it if needed u('Lorem ipsum dolor sit amet')->truncate(8, cut: TruncateMode::WordAfter); // 'Lorem ipsum' -.. versionadded:: 7.2 - - The ``TruncateMode`` parameter for truncate function was introduced in Symfony 7.2. - :: // breaks the string into lines of the given length @@ -678,10 +661,6 @@ Symfony also provides inflectors for other languages:: $result = $inflector->singularize('aviones'); // ['avión'] $result = $inflector->pluralize('miércoles'); // ['miércoles'] -.. versionadded:: 7.2 - - The ``SpanishInflector`` class was introduced in Symfony 7.2. - .. note:: Symfony provides an :class:`Symfony\\Component\\String\\Inflector\\InflectorInterface` diff --git a/templates.rst b/templates.rst index a7e122d83db..b4ab002a887 100644 --- a/templates.rst +++ b/templates.rst @@ -230,24 +230,6 @@ Consider the following routing configuration: path: /article/{slug} controller: App\Controller\BlogController::show - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/routes.php @@ -416,24 +398,6 @@ inside the main Twig configuration file: globals: ga_tracking: 'UA-xxxxx-x' - .. code-block:: xml - - - - - - - - UA-xxxxx-x - - - .. code-block:: php // config/packages/twig.php @@ -474,24 +438,6 @@ in container parameters `: # the value is the service's id uuid: '@App\Generator\UuidGenerator' - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/twig.php @@ -661,10 +607,6 @@ a block to render:: } } -.. versionadded:: 7.2 - - The ``#[Template]`` attribute's ``block`` argument was introduced in Symfony 7.2. - Rendering a Template in Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -743,43 +685,6 @@ provided by Symfony: Content-Type: 'text/html' foo: 'bar' - .. code-block:: xml - - - - - - - - static/privacy.html.twig - - - 200 - - - 86400 - 86400 - - - true - - - - ACME - dark - - - - - text/html - - - - .. code-block:: php // config/routes.php @@ -817,10 +722,6 @@ provided by Symfony: ; }; -.. versionadded:: 7.2 - - The ``headers`` option was introduced in Symfony 7.2. - Checking if a Template Exists ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -873,15 +774,6 @@ errors. It's useful to run it before deploying your application to production # you can also excludes directories $ php bin/console lint:twig templates/ --excludes=data_collector --excludes=dev_tool -.. versionadded:: 7.1 - - The option to exclude directories was introduced in Symfony 7.1. - -.. versionadded:: 7.3 - - Before Symfony 7.3, the ``--show-deprecations`` option only displayed the - first deprecation found, so you had to run the command repeatedly. - When running the linter inside `GitHub Actions`_, the output is automatically adapted to the format required by GitHub, but you can force that format too: @@ -1090,23 +982,6 @@ template fragments. Configure that special URL in the ``fragments`` option: # ... fragments: { path: /_fragment } - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1163,23 +1038,6 @@ default content rendering some template: fragments: hinclude_default_template: hinclude.html.twig - .. code-block:: xml - - - - - - - - - - - .. code-block:: php // config/packages/framework.php @@ -1409,25 +1267,6 @@ the ``value`` is the Twig namespace, which is explained later: 'email/default/templates': ~ 'backend/templates': ~ - .. code-block:: xml - - - - - - - - email/default/templates - backend/templates - - - .. code-block:: php // config/packages/twig.php @@ -1467,23 +1306,6 @@ configuration to define a namespace for each template directory: 'email/default/templates': 'email' 'backend/templates': 'admin' - .. code-block:: xml - - - - - - - email/default/templates - backend/templates - - - .. code-block:: php // config/packages/twig.php @@ -1598,13 +1420,6 @@ If you want to create a function instead of a filter, use the Along with custom filters and functions, you can also register `global variables`_. -.. versionadded:: 7.3 - - Support for the ``#[AsTwigFilter]``, ``#[AsTwigFunction]`` and ``#[AsTwigTest]`` - attributes was introduced in Symfony 7.3. Previously, you had to extend the - ``AbstractExtension`` class, and override the ``getFilters()`` and ``getFunctions()`` - methods. - If you're using the :ref:`default services.yaml configuration `, the :ref:`service autoconfiguration ` feature will enable this class as a Twig extension. Otherwise, you need to define a service manually diff --git a/testing.rst b/testing.rst index a0f8b1c6a18..9dca2338aca 100644 --- a/testing.rst +++ b/testing.rst @@ -170,21 +170,6 @@ code to production: twig: strict_variables: true - .. code-block:: xml - - - - - - - - .. code-block:: php // config/packages/test/twig.php @@ -994,11 +979,11 @@ However, Symfony provides useful shortcut methods for the most common cases: Response Assertions ................... -``assertResponseIsSuccessful(string $message = '', bool $verbose = true)`` +``assertResponseIsSuccessful(string $message = '', ?bool $verbose = null)`` Asserts that the response was successful (HTTP status is 2xx). -``assertResponseStatusCodeSame(int $expectedCode, string $message = '', bool $verbose = true)`` +``assertResponseStatusCodeSame(int $expectedCode, string $message = '', ?bool $verbose = null)`` Asserts a specific HTTP status code. -``assertResponseRedirects(?string $expectedLocation = null, ?int $expectedCode = null, string $message = '', bool $verbose = true)`` +``assertResponseRedirects(?string $expectedLocation = null, ?int $expectedCode = null, string $message = '', ?bool $verbose = null)`` Asserts the response is a redirect response (optionally, you can check the target location and status code). The excepted location can be either an absolute or a relative path. @@ -1016,12 +1001,16 @@ Response Assertions Asserts the response format returned by the :method:`Symfony\\Component\\HttpFoundation\\Response::getFormat` method is the same as the expected value. -``assertResponseIsUnprocessable(string $message = '', bool $verbose = true)`` +``assertResponseIsUnprocessable(string $message = '', bool ?$verbose = null)`` Asserts the response is unprocessable (HTTP status is 422) -.. versionadded:: 7.1 +By default, these assert methods provide detailed error messages when they fail. +You can control the verbosity level using the optional ``verbose`` argument in +each assert method. To set this verbosity level globally, use the +``setBrowserKitAssertionsAsVerbose()`` method from the +:class:`Symfony\\Bundle\\FrameworkBundle\\Test\\BrowserKitAssertionsTrait`:: - The ``$verbose`` parameters were introduced in Symfony 7.1. + BrowserKitAssertionsTrait::setBrowserKitAssertionsAsVerbose(false); Request Assertions .................. @@ -1041,6 +1030,10 @@ Browser Assertions ``assertBrowserCookieValueSame(string $name, string $expectedValue, string $path = '/', ?string $domain = null, string $message = '')`` Asserts the given cookie in the test Client is set to the expected value. +``assertBrowserHistoryIsOnFirstPage(string $message = '')``/``assertBrowserHistoryIsNotOnFirstPage(string $message = '')`` + Asserts that the browser history is (not) on the first page. +``assertBrowserHistoryIsOnLastPage(string $message = '')``/``assertBrowserHistoryIsNotOnLastPage(string $message = '')`` + Asserts that the browser history is (not) on the last page. ``assertThatForClient(Constraint $constraint, string $message = '')`` Asserts the given Constraint in the Client. Useful for using your custom asserts in the same way as built-in asserts (i.e. without passing the Client as argument):: @@ -1113,8 +1106,8 @@ Mailer Assertions ``assertEmailHeaderSame(RawMessage $email, string $headerName, string $expectedValue, string $message = '')``/``assertEmailHeaderNotSame(RawMessage $email, string $headerName, string $expectedValue, string $message = '')`` Asserts that the given email does (not) have the expected header set to the expected value. -``assertEmailAddressContains(RawMessage $email, string $headerName, string $expectedValue, string $message = '')`` - Asserts that the given address header equals the expected e-mail +``assertEmailAddressContains(RawMessage $email, string $headerName, string $expectedValue, string $message = '')``/``assertEmailAddressNotContains(RawMessage $email, string $headerName, string $expectedValue, string $message = '')`` + Asserts that the given address header does (not) equal the expected e-mail address. This assertion normalizes addresses like ``Jane Smith `` into ``jane@example.com``. ``assertEmailSubjectContains(RawMessage $email, string $expectedValue, string $message = '')``/``assertEmailSubjectNotContains(RawMessage $email, string $expectedValue, string $message = '')`` diff --git a/testing/profiling.rst b/testing/profiling.rst index 085cd100c2d..59fa76cfb3e 100644 --- a/testing/profiling.rst +++ b/testing/profiling.rst @@ -24,23 +24,6 @@ tests significantly. That's why Symfony disables it by default: framework: profiler: { enabled: true, collect: false } - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/test/web_profiler.php diff --git a/translation.rst b/translation.rst index 47f9124a5f2..fa0c592593d 100644 --- a/translation.rst +++ b/translation.rst @@ -77,25 +77,6 @@ are located: translator: default_path: '%kernel.project_dir%/translations' - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/translation.php @@ -343,6 +324,20 @@ Templates are now much simpler because you can pass translatable objects to the There's also a :ref:`function called t() `, available both in Twig and PHP, as a shortcut to create translatable objects. +Non-Translatable Messages +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In some cases, you may want to explicitly prevent a message from being +translated. You can ensure this behavior by using the +:class:`Symfony\\Component\\Translation\\StaticMessage` class:: + + use Symfony\Component\Translation\StaticMessage; + + $message = new StaticMessage('This message will never be translated.'); + +This can be useful when rendering user-defined content or other strings +that must remain exactly as given. + .. _translation-in-templates: Translations in Templates @@ -425,10 +420,6 @@ You can also specify the message domain and pass some additional variables: Global Translation Parameters ----------------------------- -.. versionadded:: 7.3 - - The global translation parameters feature was introduced in Symfony 7.3. - If the content of a translation parameter is repeated across multiple translation messages (e.g. a company name, or a version number), you can define it as a global translation parameter. This helps you avoid repeating the same @@ -450,31 +441,6 @@ of your main configuration file using either ``%...%`` or ``{...}`` syntax: '{app_version}': '1.2.3' '{url}': { message: 'url', parameters: { scheme: 'https://' }, domain: 'global' } - .. code-block:: xml - - - - - - - - - - My application - - - https:// - - - - - .. code-block:: php // config/packages/translator.php @@ -570,10 +536,6 @@ to spot untranslated strings: # when using the --no-fill option, the --prefix option is ignored $ php bin/console translation:extract --force --no-fill fr -.. versionadded:: 7.2 - - The ``--no-fill`` option was introduced in Symfony 7.2. - .. _translation-resource-locations: Translation Resource/File Names and Locations @@ -648,25 +610,6 @@ if you're generating translations with specialized programs or teams. paths: - '%kernel.project_dir%/custom/path/to/translations' - .. code-block:: xml - - - - - - - - %kernel.project_dir%/custom/path/to/translations - - - - .. code-block:: php // config/packages/translation.php @@ -770,31 +713,6 @@ configure the ``providers`` option: domains: ['messages'] locales: ['en', 'fr'] - .. code-block:: xml - - - - - - - - - messages - - en - fr - - - - - - .. code-block:: php # config/packages/translation.php @@ -993,21 +911,6 @@ A better policy is to include the locale in the URL using the requirements: _locale: en|fr|de - .. code-block:: xml - - - - - - - controller="App\Controller\ContactController::index"> - en|fr|de - - - .. code-block:: php // config/routes.php @@ -1054,21 +957,6 @@ the framework: framework: default_locale: en - .. code-block:: xml - - - - - - - - .. code-block:: php // config/packages/translation.php @@ -1102,10 +990,6 @@ match between them, Symfony will try to find a partial match based on the langua If there's no perfect or partial match, this method returns the first locale passed as argument (that's why the order of the passed locales is important). -.. versionadded:: 7.1 - - The feature to match locales partially was introduced in Symfony 7.1. - .. _translation-fallback: Fallback Translation Locales @@ -1139,26 +1023,6 @@ checks translation resources for several locales: fallbacks: ['en'] # ... - .. code-block:: xml - - - - - - - - en - - - - - .. code-block:: php // config/packages/translation.php @@ -1517,10 +1381,6 @@ to check that the translation contents are also correct: # checks the contents of the translation catalogues for Italian (it) and Japanese (ja) locales $ php bin/console lint:translations --locale=it --locale=ja -.. versionadded:: 7.2 - - The ``lint:translations`` command was introduced in Symfony 7.2. - Pseudo-localization translator ------------------------------ @@ -1584,37 +1444,6 @@ it in the translator configuration: # also translate the contents of these HTML attributes localizable_html_attributes: ['title'] - .. code-block:: xml - - - - - - - - - - - - - - title - - - - - .. code-block:: php // config/packages/translation.php diff --git a/validation/custom_constraint.rst b/validation/custom_constraint.rst index fa05085dcf2..95d6213093c 100644 --- a/validation/custom_constraint.rst +++ b/validation/custom_constraint.rst @@ -664,7 +664,3 @@ class to check precisely which of the constraints failed to pass:: } } -.. versionadded:: 7.2 - - The :class:`Symfony\\Component\\Validator\\Test\\CompoundConstraintTestCase` - class was introduced in Symfony 7.2. diff --git a/validation/raw_values.rst b/validation/raw_values.rst index 9c900ff2b36..4fecb7c44ee 100644 --- a/validation/raw_values.rst +++ b/validation/raw_values.rst @@ -75,7 +75,7 @@ Validation of arrays is possible using the ``Collection`` constraint:: ]), 'email' => new Assert\Email(), 'simple' => new Assert\Length(['min' => 102]), - 'eye_color' => new Assert\Choice([3, 4]), + 'eye_color' => new Assert\Choice(choices: [3, 4]), 'file' => new Assert\File(), 'password' => new Assert\Length(['min' => 60]), 'tags' => new Assert\Optional([ diff --git a/validation/translations.rst b/validation/translations.rst index db2cd518eb7..37defea81fc 100644 --- a/validation/translations.rst +++ b/validation/translations.rst @@ -169,25 +169,6 @@ The default translation domain can be changed globally using the validation: translation_domain: validation_errors - .. code-block:: xml - - - - - - - - - - .. code-block:: php // config/packages/validator.php diff --git a/web_link.rst b/web_link.rst index 2f2f96d106b..c4fbeacbeb6 100644 --- a/web_link.rst +++ b/web_link.rst @@ -201,6 +201,26 @@ You can also add links to the HTTP response directly from controllers and servic are also defined as constants in the :class:`Symfony\\Component\\WebLink\\Link` class (e.g. ``Link::REL_PRELOAD``, ``Link::REL_PRECONNECT``, etc.). +Parsing Link Headers +-------------------- + +Some third-party APIs provide resources such as pagination URLs using the +``Link`` HTTP header. The WebLink component provides the +:class:`Symfony\\Component\\WebLink\\HttpHeaderParser` utility class to parse +those headers and transform them into :class:`Symfony\\Component\\WebLink\\Link` +instances:: + + use Symfony\Component\WebLink\HttpHeaderParser; + + $parser = new HttpHeaderParser(); + // get the value of the Link header from the Request + $linkHeader = '; rel="prerender",; rel="dns-prefetch"; pr="0.7",; rel="preload"; as="script"'; + + $links = $parser->parse($linkHeader)->getLinks(); + $links[0]->getRels(); // ['prerender'] + $links[1]->getAttributes(); // ['pr' => '0.7'] + $links[2]->getHref(); // '/baz.js' + .. _`WebLink`: https://github.com/symfony/web-link .. _`HTTP/2 Server Push`: https://tools.ietf.org/html/rfc7540#section-8.2 .. _`Resource Hints`: https://www.w3.org/TR/resource-hints/ diff --git a/webhook.rst b/webhook.rst index d27a6e6d906..77c04b22f94 100644 --- a/webhook.rst +++ b/webhook.rst @@ -42,19 +42,6 @@ Sendgrid ``mailer.webhook.request_parser.sendgrid`` Sweego ``mailer.webhook.request_parser.sweego`` ============== ============================================ -.. versionadded:: 7.1 - - The support for ``Resend`` and ``MailerSend`` were introduced in Symfony 7.1. - -.. versionadded:: 7.2 - - The ``Mandrill``, ``Mailomat``, ``Mailtrap``, and ``Sweego`` integrations were introduced in - Symfony 7.2. - -.. versionadded:: 7.3 - - The ``AhaSend`` integration was introduced in Symfony 7.3. - .. note:: Install the third-party mailer provider you want to use as described in the @@ -76,26 +63,6 @@ component routing: service: 'mailer.webhook.request_parser.mailgun' secret: '%env(MAILER_MAILGUN_SECRET)%' - .. code-block:: xml - - - - - - - - mailer.webhook.request_parser.mailgun - %env(MAILER_MAILGUN_SECRET)% - - - - - .. code-block:: php // config/packages/framework.php @@ -175,9 +142,10 @@ Currently, the following third-party SMS transports support webhooks: ============ ========================================== SMS service Parser service name ============ ========================================== -Twilio ``notifier.webhook.request_parser.twilio`` +LOX24 ``notifier.webhook.request_parser.lox24`` Smsbox ``notifier.webhook.request_parser.smsbox`` Sweego ``notifier.webhook.request_parser.sweego`` +Twilio ``notifier.webhook.request_parser.twilio`` Vonage ``notifier.webhook.request_parser.vonage`` ============ ========================================== diff --git a/workflow.rst b/workflow.rst index 2a3d1d908ef..f1c7a610abd 100644 --- a/workflow.rst +++ b/workflow.rst @@ -76,50 +76,6 @@ follows: from: reviewed to: rejected - .. code-block:: xml - - - - - - - - - - - currentPlace - - App\Entity\BlogPost - draft - - - draft - reviewed - rejected - published - - - draft - reviewed - - - reviewed - published - - - reviewed - rejected - - - - - .. code-block:: php // config/packages/workflow.php @@ -178,11 +134,6 @@ follows: that are used in the workflow. Symfony will automatically extract the places from the transitions. - .. versionadded:: 7.1 - - The support for omitting the ``places`` option was introduced in - Symfony 7.1. - The configured property will be used via its implemented getter/setter methods by the marking store:: // src/Entity/BlogPost.php @@ -294,6 +245,320 @@ what actions are allowed on a blog post:: // See a specific available transition for the post in the current state $transition = $workflow->getEnabledTransition($post, 'publish'); +Using Enums as Workflow Places +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using a state machine, you can use PHP backend enums as places in your +workflows. First, define your enum with backed values:: + + // src/Enumeration/BlogPostStatus.php + namespace App\Enumeration; + + enum BlogPostStatus: string + { + case Draft = 'draft'; + case Reviewed = 'reviewed'; + case Published = 'published'; + case Rejected = 'rejected'; + } + +Then configure the workflow using the enum cases as places, initial marking, +and transitions: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/workflow.yaml + framework: + workflows: + blog_publishing: + type: 'workflow' + marking_store: + type: 'method' + property: 'status' + supports: + - App\Entity\BlogPost + initial_marking: !php/enum App\Enumeration\BlogPostStatus::Draft + places: !php/enum App\Enumeration\BlogPostStatus + transitions: + to_review: + from: !php/enum App\Enumeration\BlogPostStatus::Draft + to: !php/enum App\Enumeration\BlogPostStatus::Reviewed + publish: + from: !php/enum App\Enumeration\BlogPostStatus::Reviewed + to: !php/enum App\Enumeration\BlogPostStatus::Published + reject: + from: !php/enum App\Enumeration\BlogPostStatus::Reviewed + to: !php/enum App\Enumeration\BlogPostStatus::Rejected + + .. code-block:: php + + // config/packages/workflow.php + use App\Entity\BlogPost; + use App\Enumeration\BlogPostStatus; + use Symfony\Config\FrameworkConfig; + + return static function (FrameworkConfig $framework): void { + $blogPublishing = $framework->workflows()->workflows('blog_publishing'); + $blogPublishing + ->type('workflow') + ->supports([BlogPost::class]) + ->initialMarking([BlogPostStatus::Draft]); + + $blogPublishing->markingStore() + ->type('method') + ->property('status'); + + $blogPublishing->places(BlogPostStatus::cases()); + + $blogPublishing->transition() + ->name('to_review') + ->from(BlogPostStatus::Draft) + ->to([BlogPostStatus::Reviewed]); + + $blogPublishing->transition() + ->name('publish') + ->from([BlogPostStatus::Reviewed]) + ->to([BlogPostStatus::Published]); + + $blogPublishing->transition() + ->name('reject') + ->from([BlogPostStatus::Reviewed]) + ->to([BlogPostStatus::Rejected]); + }; + +The component will now transparently cast the enum to its backing value +when needed and vice-versa when working with your objects:: + + // src/Entity/BlogPost.php + namespace App\Entity; + + class BlogPost + { + private BlogPostStatus $status; + + public function getStatus(): BlogPostStatus + { + return $this->status; + } + + public function setStatus(BlogPostStatus $status): void + { + $this->status = $status; + } + } + +.. tip:: + + You can also use `glob patterns`_ of PHP constants and enums to list the places: + + .. configuration-block:: + + .. code-block:: yaml + + # config/packages/workflow.yaml + framework: + workflows: + my_workflow_name: + # with constants: + places: 'App\Workflow\MyWorkflow::PLACE_*' + + # with enums: + places: !php/enum App\Workflow\Places + + # ... + + .. code-block:: php + + // config/packages/workflow.php + use App\Entity\BlogPost; + use App\Enumeration\BlogPostStatus; + use Symfony\Config\FrameworkConfig; + + return static function (FrameworkConfig $framework): void { + $blogPublishing = $framework->workflows()->workflows('my_workflow_name'); + + // with constants: + $blogPublishing->places('App\Workflow\MyWorkflow::PLACE_*'); + + // with enums: + $blogPublishing->places(BlogPostStatus::cases()); + + // ... + }; + +Using Weighted Transitions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A key feature of workflows (as opposed to state machines) is that an object can +be in multiple places simultaneously. For example, when building a product, you +might assemble several components in parallel. However, in the previous example, +each place could only record whether the object was there or not, like a binary flag. + +**Weighted transitions** introduce multiplicity: a place can now track how many +times an object is in that place. Technically, weighted transitions allow you to +define transitions where multiple tokens (instances) are consumed from or produced +to places. This is useful for modeling complex workflows such as manufacturing +processes, resource allocation, or any scenario where multiple instances of something +need to be produced or consumed. + +For example, imagine a table-making workflow where you need to create 4 legs, 1 top, +and track the process with a stopwatch. You can use weighted transitions to model this: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/workflow.yaml + framework: + workflows: + make_table: + type: 'workflow' + marking_store: + type: 'method' + property: 'marking' + supports: + - App\Entity\TableProject + initial_marking: init + places: + - init + - prepare_leg + - prepare_top + - stopwatch_running + - leg_created + - top_created + - finished + transitions: + start: + from: init + to: + - place: prepare_leg + weight: 4 + - place: prepare_top + weight: 1 + - place: stopwatch_running + weight: 1 + build_leg: + from: prepare_leg + to: leg_created + build_top: + from: prepare_top + to: top_created + join: + from: + - place: leg_created + weight: 4 + - top_created # weight defaults to 1 + - stopwatch_running + to: finished + + .. code-block:: php + + // config/packages/workflow.php + use App\Entity\TableProject; + use Symfony\Config\FrameworkConfig; + + return static function (FrameworkConfig $framework): void { + $makeTable = $framework->workflows()->workflows('make_table'); + $makeTable + ->type('workflow') + ->supports([TableProject::class]) + ->initialMarking(['init']); + + $makeTable->markingStore() + ->type('method') + ->property('marking'); + + $makeTable->place()->name('init'); + $makeTable->place()->name('prepare_leg'); + $makeTable->place()->name('prepare_top'); + $makeTable->place()->name('stopwatch_running'); + $makeTable->place()->name('leg_created'); + $makeTable->place()->name('top_created'); + $makeTable->place()->name('finished'); + + $makeTable->transition() + ->name('start') + ->from(['init']) + ->to([ + ['place' => 'prepare_leg', 'weight' => 4], + ['place' => 'prepare_top', 'weight' => 1], + ['place' => 'stopwatch_running', 'weight' => 1], + ]); + + $makeTable->transition() + ->name('build_leg') + ->from(['prepare_leg']) + ->to(['leg_created']); + + $makeTable->transition() + ->name('build_top') + ->from(['prepare_top']) + ->to(['top_created']); + + $makeTable->transition() + ->name('join') + ->from([ + ['place' => 'leg_created', 'weight' => 4], + 'top_created', // weight defaults to 1 + 'stopwatch_running', + ]) + ->to(['finished']); + }; + +In this example, when the ``start`` transition is applied, it creates 4 tokens in +the ``prepare_leg`` place, 1 token in ``prepare_top``, and 1 token in +``stopwatch_running``. Then, the ``build_leg`` transition must be applied 4 times +(once for each token), and the ``build_top`` transition once. Finally, the ``join`` +transition can only be applied when all 4 legs are created, the top is created, +and the stopwatch is still running. + +Weighted transitions can also be defined programmatically using the +:class:`Symfony\\Component\\Workflow\\Arc` class:: + + use Symfony\Component\Workflow\Arc; + use Symfony\Component\Workflow\Definition; + use Symfony\Component\Workflow\Transition; + use Symfony\Component\Workflow\Workflow; + + $definition = new Definition( + ['init', 'prepare_leg', 'prepare_top', 'stopwatch_running', 'leg_created', 'top_created', 'finished'], + [ + new Transition('start', 'init', [ + new Arc('prepare_leg', 4), + new Arc('prepare_top', 1), + 'stopwatch_running', // defaults to weight 1 + ]), + new Transition('build_leg', 'prepare_leg', 'leg_created'), + new Transition('build_top', 'prepare_top', 'top_created'), + new Transition('join', [ + new Arc('leg_created', 4), + 'top_created', + 'stopwatch_running', + ], 'finished'), + ] + ); + + $workflow = new Workflow($definition); + $workflow->apply($subject, 'start'); + + // Build each leg (4 times) + $workflow->apply($subject, 'build_leg'); + $workflow->apply($subject, 'build_leg'); + $workflow->apply($subject, 'build_leg'); + $workflow->apply($subject, 'build_leg'); + + // Build the top + $workflow->apply($subject, 'build_top'); + + // Now we can join all parts + $workflow->apply($subject, 'join'); + +The ``Arc`` class takes two parameters: the place name and the weight (which must be +greater than or equal to 1). When a place is specified as a simple string instead of +an ``Arc`` object, it defaults to a weight of 1. + Using a multiple state marking store ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -390,11 +655,6 @@ To get the enabled transition of a Workflow, you can use :method:`Symfony\\Component\\Workflow\\WorkflowInterface::getEnabledTransition` method. -.. versionadded:: 7.1 - - The :method:`Symfony\\Component\\Workflow\\WorkflowInterface::getEnabledTransition` - method was introduced in Symfony 7.1. - .. tip:: If you want to retrieve all workflows, for documentation purposes for example, @@ -410,10 +670,6 @@ method. Learn more about :ref:`tag attributes ` and :ref:`storing workflow metadata `. - .. versionadded:: 7.1 - - The attached configuration to the tag was introduced in Symfony 7.1. - .. tip:: You can find the list of available workflow services with the @@ -614,10 +870,6 @@ workflow leaves a place:: You can also use this method in your custom events via the :class:`Symfony\\Component\\Workflow\\Event\\EventNameTrait`. - .. versionadded:: 7.1 - - The ``getName()`` method was introduced in Symfony 7.1. - If some listeners update the context during a transition, you can retrieve it via the marking:: @@ -727,30 +979,6 @@ to :ref:`Guard events `, which are always fired: # ... - .. code-block:: xml - - - - - - - - workflow.leave - workflow.completed - - - - - - - - - .. code-block:: php // config/packages/workflow.php @@ -882,49 +1110,6 @@ transition. The value of this option is any valid expression created with the from: reviewed to: rejected - .. code-block:: xml - - - - - - - - - - - - - is_granted("ROLE_REVIEWER") - draft - reviewed - - - - - is_authenticated - reviewed - published - - - - - is_granted("ROLE_ADMIN") and subject.isStatusReviewed() - reviewed - rejected - - - - - - - .. code-block:: php // config/packages/workflow.php @@ -1047,24 +1232,6 @@ it: marking_store: service: 'App\Workflow\MarkingStore\BlogPostMarkingStore' - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php // config/packages/workflow.php @@ -1180,47 +1347,6 @@ be only the title of the workflow or very complex objects: hour_limit: 20 explanation: 'You can not publish after 8 PM.' - .. code-block:: xml - - - - - - - - Blog Publishing Workflow - - - - - 500 - - - - - draft - review - - 0.5 - - - - reviewed - published - - 20 - You can not publish after 8 PM. - - - - - - .. code-block:: php // config/packages/workflow.php @@ -1392,24 +1518,6 @@ After implementing your validator, configure your workflow to use it: definition_validators: - App\Workflow\Validator\BlogPublishingValidator - .. code-block:: xml - - - - - - - - App\Workflow\Validator\BlogPublishingValidator - - - - .. code-block:: php // config/packages/workflow.php @@ -1429,10 +1537,6 @@ After implementing your validator, configure your workflow to use it: The ``BlogPublishingValidator`` will be executed during container compilation to validate the workflow definition. -.. versionadded:: 7.3 - - Support for workflow definition validators was introduced in Symfony 7.3. - Learn more ---------- @@ -1441,3 +1545,5 @@ Learn more /workflow/workflow-and-state-machine /workflow/dumping-workflows + +.. _`glob patterns`: https://php.net/glob diff --git a/workflow/dumping-workflows.rst b/workflow/dumping-workflows.rst index 8262fefd6c1..971cf6abec4 100644 --- a/workflow/dumping-workflows.rst +++ b/workflow/dumping-workflows.rst @@ -161,104 +161,6 @@ Below is the configuration for the pull request state machine with styling added from: closed to: review - .. code-block:: xml - - - - - - - - - method - currentPlace - - - App\Entity\PullRequest - - start - - start - coding - test - - - Human review - - - merged - - - DeepSkyBlue - - - - - start - - test - - - - coding - test - review - - test - - - Turquoise - - - - - test - - review - - - Orange - - - - - review - - coding - - - - review - - merged - - - Accept PR - - - - - review - - closed - - - - closed - - review - - - - - - - .. code-block:: php // config/packages/workflow.php diff --git a/workflow/workflow-and-state-machine.rst b/workflow/workflow-and-state-machine.rst index 3a034b97357..3992e7cfa2f 100644 --- a/workflow/workflow-and-state-machine.rst +++ b/workflow/workflow-and-state-machine.rst @@ -115,82 +115,6 @@ Below is the configuration for the pull request state machine. from: closed to: review - .. code-block:: xml - - - - - - - - start - - - - - App\Entity\PullRequest - - start - coding - test - review - merged - closed - - - start - - test - - - - coding - test - review - - test - - - - test - - review - - - - review - - coding - - - - review - - merged - - - - review - - closed - - - - closed - - review - - - - - - - .. code-block:: php // config/packages/workflow.php @@ -258,11 +182,6 @@ Below is the configuration for the pull request state machine. that are used in the workflow. Symfony will automatically extract the places from the transitions. - .. versionadded:: 7.1 - - The support for omitting the ``places`` option was introduced in - Symfony 7.1. - Symfony automatically creates a service for each workflow (:class:`Symfony\\Component\\Workflow\\Workflow`) or state machine (:class:`Symfony\\Component\\Workflow\\StateMachine`) you have defined in your configuration. You can use the workflow inside a class by using