diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml index 04e720bf653..0768119d255 100644 --- a/.doctor-rst.yaml +++ b/.doctor-rst.yaml @@ -117,3 +117,4 @@ whitelist: - '.. versionadded:: 3.0' # Doctrine ORM - '.. _`a feature to test applications using Mercure`: https://github.com/symfony/panther#creating-isolated-browsers-to-test-apps-using-mercure-or-websocket' - 'End to End Tests (E2E)' + - '.. versionadded:: 2.2.0' # Panther diff --git a/README.md b/README.md index ed323a8ee83..5c063058c02 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ We love contributors! For more information on how you can contribute, please rea the [Symfony Docs Contributing Guide](https://symfony.com/doc/current/contributing/documentation/overview.html). > [!IMPORTANT] -> Use `5.4` branch as the base of your pull requests, unless you are documenting a -> feature that was introduced *after* Symfony 5.4 (e.g. in Symfony 7.1). +> Use `6.4` branch as the base of your pull requests, unless you are documenting a +> feature that was introduced *after* Symfony 6.4 (e.g. in Symfony 7.2). Build Documentation Locally --------------------------- diff --git a/_build/spelling_word_list.txt b/_build/spelling_word_list.txt deleted file mode 100644 index fa05ce9430e..00000000000 --- a/_build/spelling_word_list.txt +++ /dev/null @@ -1,344 +0,0 @@ -accessor -Akamai -analytics -Ansi -Ansible -async -authenticator -authenticators -autocompleted -autocompletion -autoconfiguration -autoconfigure -autoconfigured -autoconfigures -autoconfiguring -autoload -autoloaded -autoloader -autoloaders -autoloading -autoprefixing -autowire -autowireable -autowired -autowiring -backend -backends -balancer -balancers -bcrypt -benchmarking -Bitbucket -bitmask -bitmasks -bitwise -Blackfire -boolean -booleans -Brasseur -browserslist -buildpack -buildpacks -bundler -cacheable -Caddy -callables -camelCase -casted -changelog -changeset -charset -charsets -checkboxes -classmap -classname -clearers -cloner -cloners -codebase -config -configs -configurator -configurators -contrib -cron -cronjobs -cryptographic -cryptographically -Ctrl -ctype -cURL -customizable -customizations -Cygwin -dataset -datepicker -decrypt -denormalization -denormalize -denormalized -denormalizing -deprecations -deserialization -deserialize -deserialized -deserializing -destructor -dev -dn -DNS -docblock -Dotenv -downloader -Doxygen -DSN -Dunglas -easter -Eberlei -emilie -enctype -entrypoints -enum -env -escaper -escpaer -extensibility -extractable -eZPublish -Fabien -failover -filesystem -filesystems -formatter -formatters -frontend -getter -getters -GitHub -gmail -Gmail -Goutte -grapheme -hardcode -hardcoded -hardcodes -hardcoding -hasser -hassers -headshot -HInclude -hostname -https -iconv -igbinary -incrementing -ini -inlined -inlining -installable -instantiation -interoperable -intl -Intl -invokable -IPv -isser -issers -Jpegoptim -jQuery -js -Karlton -kb -kB -Kévin -Ki -KiB -kibibyte -Kubernetes -Kudu -labelled -latin -Ldap -libketama -licensor -lifecycle -liip -linter -localhost -Loggly -Logplex -lookups -loopback -lorenzo -Luhn -macOS -matcher -matchers -mbstring -mebibyte -memcache -memcached -MiB -michelle -minification -minified -minifier -minifies -minify -minifying -misconfiguration -misconfigured -misgendering -Monolog -mutator -nagle -namespace -namespaced -namespaces -namespacing -natively -nd -netmasks -nginx -normalizer -normalizers -npm -nyholm -OAuth -OPcache -overcomplicate -Packagist -parallelizes -parsers -PHP -PHPUnit -PID -plaintext -polyfill -polyfills -postcss -Potencier -pre -preconfigured -predefines -Predis -preload -preloaded -preloading -prepend -prepended -prepending -prepends -preprocessed -preprocessors -Procfile -profiler -programmatically -prototyped -rebase -reconfiguring -reconnection -redirections -refactorization -regexes -renderer -resolvers -responder -reStructuredText -reusability -runtime -sandboxing -schemas -screencast -semantical -serializable -serializer -sexualized -Silex -sluggable -socio -specificities -SQLite -stacktrace -stacktraces -storages -stringified -stylesheet -stylesheets -subclasses -subdirectories -subdirectory -sublcasses -sublicense -sublincense -subrequests -subtree -superclass -superglobal -superglobals -symfony -Symfony -symlink -symlinks -syntaxes -templating -testability -th -theming -throbber -timestampable -timezones -TLS -tmpfs -tobias -todo -Tomayko -Toolbelt -tooltip -Traversable -triaging -UI -uid -unary -unauthenticate -uncacheable -uncached -uncomment -uncommented -undelete -unhandled -unicode -Unix -unmapped -unminified -unported -unregister -unrendered -unserialize -unserialized -unserializing -unsubmitted -untracked -uploader -URI -validator -validators -variadic -VirtualBox -Vue -webpack -webpacked -webpackJsonp -webserver -whitespace -whitespaces -woh -Wordpress -Xdebug -xkcd -Xliff -XML -XPath -yaml -yay diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst index 2670ec3084a..3dc97d5c0d3 100644 --- a/components/console/helpers/questionhelper.rst +++ b/components/console/helpers/questionhelper.rst @@ -145,6 +145,28 @@ The option which should be selected by default is provided with the third argument of the constructor. The default is ``null``, which means that no option is the default one. +Choice questions display both the choice value and a numeric index, which starts +from 0 by default. The user can type either the numeric index or the choice value +to make a selection: + +.. code-block:: terminal + + Please select your favorite color (defaults to red): + [0] red + [1] blue + [2] yellow + > + +.. tip:: + + To use custom indices, pass an array with custom numeric keys as the choice + values:: + + new ChoiceQuestion('Select a room:', [ + 102 => 'Room Foo', + 213 => 'Room Bar', + ]); + If the user enters an invalid string, an error message is shown and the user is asked to provide the answer another time, until they enter a valid string or reach the maximum number of attempts. The default value for the maximum number diff --git a/console/calling_commands.rst b/console/calling_commands.rst index 349f1357682..dd1f0b12ff9 100644 --- a/console/calling_commands.rst +++ b/console/calling_commands.rst @@ -1,9 +1,9 @@ How to Call Other Commands ========================== -If a command depends on another one being run before it you can call in the -console command itself. This is useful if a command depends on another command -or if you want to create a "meta" command that runs a bunch of other commands +If a command depends on another one being run before it you can call that in the +console command itself. This can be useful +if you want to create a "meta" command that runs a bunch of other commands (for instance, all commands that need to be run when the project's code has changed on the production servers: clearing the cache, generating Doctrine proxies, dumping web assets, ...). diff --git a/contributing/code/core_team.rst b/contributing/code/core_team.rst index efc60894c7c..1b1703e4f93 100644 --- a/contributing/code/core_team.rst +++ b/contributing/code/core_team.rst @@ -13,6 +13,15 @@ This document states the rules that govern the Symfony core team. These rules are effective upon publication of this document and all Symfony Core members must adhere to said rules and protocol. +Role of a Core Team Member +-------------------------- + +In addition to being a regular contributor, core team members are expected to: + +* Review, approve, and merge pull requests; +* Help enforce, improve, and implement Symfony :doc:`processes and policies `; +* Participate in the Symfony Core Team discussions (on Slack and GitHub). + Core Organization ----------------- @@ -34,8 +43,8 @@ The Symfony Core groups, in descending order of priority, are as follows: In addition, there are other groups created to manage specific topics: * **Security Team**: manages the whole security process (triaging reported vulnerabilities, - fixing the reported issues, coordinating the release of security fixes, etc.) - + fixing the reported issues, coordinating the release of security fixes, etc.); +* **Symfony UX Team**: manages the `UX repositories`_; * **Documentation Team**: manages the whole `symfony-docs repository`_. Active Core Members @@ -61,7 +70,6 @@ Active Core Members * **Alexander M. Turek** (`derrabus`_); * **Jérémy Derussé** (`jderusse`_); * **Oskar Stark** (`OskarStark`_); - * **Thomas Calvet** (`fancyweb`_); * **Mathieu Santostefano** (`welcomattic`_); * **Kevin Bond** (`kbond`_); * **Jérôme Tamarelle** (`gromnan`_). @@ -71,6 +79,14 @@ Active Core Members * **Fabien Potencier** (`fabpot`_); * **Jérémy Derussé** (`jderusse`_). +* **Symfony UX Team** (``@symfony/ux`` on GitHub): + + * **Ryan Weaver** (`weaverryan`_); + * **Kevin Bond** (`kbond`_); + * **Simon André** (`smnandre`_); + * **Hugo Alliaume** (`kocal`_); + * **Matheo Daninos** (`webmamba`_). + * **Documentation Team** (``@symfony/team-symfony-docs`` on GitHub): * **Fabien Potencier** (`fabpot`_); @@ -97,7 +113,8 @@ Symfony contributions: * **Tobias Schultze** (`Tobion`_); * **Maxime Steinhausser** (`ogizanagi`_); * **Titouan Galopin** (`tgalopin`_); -* **Michael Cullum** (`michaelcullum`_). +* **Michael Cullum** (`michaelcullum`_); +* **Thomas Calvet** (`fancyweb`_). Core Membership Application ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -131,7 +148,6 @@ Pull Request Voting Policy * Core members can change their votes as many times as they desire during the course of a pull request discussion; - * Core members are not allowed to vote on their own pull requests. Pull Request Merging Policy @@ -140,13 +156,10 @@ Pull Request Merging Policy A pull request **can be merged** if: * It is a :ref:`minor change `; - * Enough time was given for peer reviews; - * It is a bug fix and at least two **Mergers Team** members voted ``+1`` (only one if the submitter is part of the Mergers team) and no Core member voted ``-1`` (via GitHub reviews or as comments). - * It is a new feature and at least two **Mergers Team** members voted ``+1`` (if the submitter is part of the Mergers team, two *other* members) and no Core member voted ``-1`` (via GitHub reviews or as comments). @@ -159,7 +172,24 @@ All code must be committed to the repository through pull requests, except for to the repository. **Mergers** must always use the command-line ``gh`` tool provided by the -**Project Leader** to merge the pull requests. +**Project Leader** to merge pull requests. + +When merging a pull request, the tool asks for a category that should be chosen +following these rules: + +* **Feature**: For new features and deprecations; Pull requests must be merged + in the development branch. +* **Bug**: Only for bug fixes; We are very conservative when it comes to + merging older, but still maintained, branches. Read the :doc:`maintenance` + document for more information. +* **Minor**: For everything that does not change the code or when they don't + need to be listed in the CHANGELOG files: typos, Markdown files, test files, + new or missing translations, etc. +* **Security**: It's the category used for security fixes and should never be + used except by the security team. + +Getting the right category is important as it is used by automated tools to +generate the CHANGELOG files when releasing new versions. Release Policy ~~~~~~~~~~~~~~ @@ -180,6 +210,7 @@ discretion of the **Project Leader**. violations, and minor CSS, JavaScript and HTML modifications. .. _`symfony-docs repository`: https://github.com/symfony/symfony-docs +.. _`UX repositories`: https://github.com/symfony/ux .. _`fabpot`: https://github.com/fabpot/ .. _`webmozart`: https://github.com/webmozart/ .. _`Tobion`: https://github.com/Tobion/ @@ -211,3 +242,6 @@ discretion of the **Project Leader**. .. _`welcomattic`: https://github.com/welcomattic/ .. _`kbond`: https://github.com/kbond/ .. _`gromnan`: https://github.com/gromnan/ +.. _`smnandre`: https://github.com/smnandre/ +.. _`kocal`: https://github.com/kocal/ +.. _`webmamba`: https://github.com/webmamba/ diff --git a/form/without_class.rst b/form/without_class.rst index 436976bdfcc..8b0af7cf23f 100644 --- a/form/without_class.rst +++ b/form/without_class.rst @@ -137,6 +137,7 @@ This can be done by setting the ``constraints`` option in the use Symfony\Component\Form\Extension\Core\Type\TextType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolver; + use Symfony\Component\Validator\Constraints\Collection; use Symfony\Component\Validator\Constraints\Length; use Symfony\Component\Validator\Constraints\NotBlank; @@ -149,17 +150,15 @@ This can be done by setting the ``constraints`` option in the public function configureOptions(OptionsResolver $resolver): void { - $constraints = [ - 'firstName' => new Length(['min' => 3]), - 'lastName' => [ - new NotBlank(), - new Length(['min' => 3]), - ], - ]; - $resolver->setDefaults([ 'data_class' => null, - 'constraints' => $constraints, + 'constraints' => new Collection([ + 'firstName' => new Length(['min' => 3]), + 'lastName' => [ + new NotBlank(), + new Length(['min' => 3]), + ], + ]), ]); } diff --git a/frontend/create_ux_bundle.rst b/frontend/create_ux_bundle.rst index 8faf0f44bb1..8f44a16f62e 100644 --- a/frontend/create_ux_bundle.rst +++ b/frontend/create_ux_bundle.rst @@ -142,21 +142,22 @@ Twig ``stimulus_*`` functions. Each controller has a number of options in ``package.json`` file: -================== ==================================================================================================== -Option Description -================== ==================================================================================================== -enabled Whether the controller should be enabled by default. -main Path to the controller file. -fetch How controller & dependencies are included when the page loads. - Use ``eager`` (default) to make controller & dependencies included in the JavaScript that's - downloaded when the page is loaded. - Use ``lazy`` to make controller & dependencies isolated into a separate file and only downloaded - asynchronously if (and when) the data-controller HTML appears on the page. -autoimport List of files to be imported with the controller. Useful e.g. when there are several CSS styles - depending on the frontend framework used (like Bootstrap 4 or 5, Tailwind CSS...). - The value must be an object with files as keys, and a boolean as value for each file to set - whether the file should be imported. -================== ==================================================================================================== +``enabled``: + Whether the controller should be enabled by default. +``main``: + Path to the controller file. +``fetch``: + How controller & dependencies are included when the page loads. + Use ``eager`` (default) to make controller & dependencies included in the + JavaScript that's downloaded when the page is loaded. + Use ``lazy`` to make controller & dependencies isolated into a separate file + and only downloaded asynchronously if (and when) the data-controller HTML + appears on the page. +``autoimport``: + List of files to be imported with the controller. Useful e.g. when there are + several CSS styles depending on the frontend framework used (like Bootstrap 4 + or 5, Tailwind CSS...). The value must be an object with files as keys, and + a boolean as value for each file to set whether the file should be imported. Specifics for Asset Mapper -------------------------- diff --git a/logging.rst b/logging.rst index c66312f88f9..0ad36031dd5 100644 --- a/logging.rst +++ b/logging.rst @@ -1,9 +1,10 @@ Logging ======= -Symfony comes with a minimalist `PSR-3`_ logger: :class:`Symfony\\Component\\HttpKernel\\Log\\Logger`. -In conformance with `the twelve-factor app methodology`_, it sends messages starting from the -``WARNING`` level to `stderr`_. +Symfony comes with two minimalist `PSR-3`_ loggers: :class:`Symfony\\Component\\HttpKernel\\Log\\Logger` +for the HTTP context and :class:`Symfony\\Component\\Console\\Logger\\ConsoleLogger` for the +CLI context. In conformance with `the twelve-factor app methodology`_, they send messages +starting from the ``WARNING`` level to `stderr`_. The minimal log level can be changed by setting the ``SHELL_VERBOSITY`` environment variable: @@ -17,8 +18,13 @@ The minimal log level can be changed by setting the ``SHELL_VERBOSITY`` environm ========================= ================= The minimum log level, the default output and the log format can also be changed by -passing the appropriate arguments to the constructor of :class:`Symfony\\Component\\HttpKernel\\Log\\Logger`. -To do so, :ref:`override the "logger" service definition `. +passing the appropriate arguments to the constructor of :class:`Symfony\\Component\\HttpKernel\\Log\\Logger` +and :class:`Symfony\\Component\\Console\\Logger\\ConsoleLogger`. + +The :class:`Symfony\\Component\\HttpKernel\\Log\\Logger` class is available through the ``logger`` service. +To pass your configuration, you can :ref:`override the "logger" service definition `. + +For more information about ``ConsoleLogger``, see :doc:`/components/console/logger`. Logging a Message ----------------- diff --git a/mercure.rst b/mercure.rst index f37c40ddee7..42ad9798d3c 100644 --- a/mercure.rst +++ b/mercure.rst @@ -309,6 +309,12 @@ as patterns: } +However, on the client side (i.e. in JavaScript's ``EventSource``), there is no +built-in way to know which topic a certain message originates from. If this (or +any other meta information) is important to you, you need to include it in the +message's data (e.g. by adding a key to the JSON, or a ``data-*`` attribute to +the HTML). + .. tip:: Test if a URI Template matches a URL using `the online debugger`_ diff --git a/messenger.rst b/messenger.rst index 18b59de7db6..97829327d03 100644 --- a/messenger.rst +++ b/messenger.rst @@ -1567,12 +1567,6 @@ DSN by using the ``table_name`` option: Or, to create the table yourself, set the ``auto_setup`` option to ``false`` and :ref:`generate a migration `. -.. warning:: - - The datetime property of the messages stored in the database uses the - timezone of the current system. This may cause issues if multiple machines - with different timezone configuration use the same storage. - The transport has a number of options: ``table_name`` (default: ``messenger_messages``) diff --git a/rate_limiter.rst b/rate_limiter.rst index e08d4576b95..6c158ee52d0 100644 --- a/rate_limiter.rst +++ b/rate_limiter.rst @@ -16,8 +16,9 @@ time, but you can use them for your own features too. By definition, the Symfony rate limiters require Symfony to be booted in a PHP process. This makes them not useful to protect against `DoS attacks`_. Such protections must consume the least resources possible. Consider - using `Apache mod_ratelimit`_, `NGINX rate limiting`_ or proxies (like - AWS or Cloudflare) to prevent your server from being overwhelmed. + using `Apache mod_ratelimit`_, `NGINX rate limiting`_, + `Caddy HTTP rate limit module`_ (also supported by FrankenPHP) + or proxies (like AWS or Cloudflare) to prevent your server from being overwhelmed. .. _rate-limiter-policies: @@ -536,6 +537,7 @@ you can use a specific :ref:`named lock ` via the .. _`DoS attacks`: https://cheatsheetseries.owasp.org/cheatsheets/Denial_of_Service_Cheat_Sheet.html .. _`Apache mod_ratelimit`: https://httpd.apache.org/docs/current/mod/mod_ratelimit.html .. _`NGINX rate limiting`: https://www.nginx.com/blog/rate-limiting-nginx/ +.. _`Caddy HTTP rate limit module`: https://github.com/mholt/caddy-ratelimit .. _`token bucket algorithm`: https://en.wikipedia.org/wiki/Token_bucket .. _`PHP date relative formats`: https://www.php.net/manual/en/datetime.formats.php#datetime.formats.relative .. _`Race conditions`: https://en.wikipedia.org/wiki/Race_condition diff --git a/reference/configuration/doctrine.rst b/reference/configuration/doctrine.rst index cd1852710e7..272ad6b6804 100644 --- a/reference/configuration/doctrine.rst +++ b/reference/configuration/doctrine.rst @@ -483,12 +483,12 @@ set up the connection using environment variables for the certificate paths: server_version: '8.0.31' driver: 'pdo_mysql' options: - # SSL private key (PDO::MYSQL_ATTR_SSL_KEY) - 1007: '%env(MYSQL_SSL_KEY)%' - # SSL certificate (PDO::MYSQL_ATTR_SSL_CERT) - 1008: '%env(MYSQL_SSL_CERT)%' - # SSL CA authority (PDO::MYSQL_ATTR_SSL_CA) - 1009: '%env(MYSQL_SSL_CA)%' + # SSL private key + !php/const 'PDO::MYSQL_ATTR_SSL_KEY': '%env(MYSQL_SSL_KEY)%' + # SSL certificate + !php/const 'PDO::MYSQL_ATTR_SSL_CERT': '%env(MYSQL_SSL_CERT)%' + # SSL CA authority + !php/const 'PDO::MYSQL_ATTR_SSL_CA': '%env(MYSQL_SSL_CA)%' .. code-block:: xml diff --git a/reference/constraints/Cidr.rst b/reference/constraints/Cidr.rst index 32d9236853a..78a5b6c7167 100644 --- a/reference/constraints/Cidr.rst +++ b/reference/constraints/Cidr.rst @@ -126,6 +126,14 @@ Parameter Description This determines exactly *how* the CIDR notation is validated and can take one of :ref:`IP version ranges `. +.. note:: + + The IP range checks (e.g., ``*_private``, ``*_reserved``) validate only the + IP address, not the entire netmask. To improve validation, you can set the + ``{{ min }}`` value for the netmask. For example, the range ``9.0.0.0/6`` is + 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. diff --git a/routing.rst b/routing.rst index ef3287dd1be..df1f861c554 100644 --- a/routing.rst +++ b/routing.rst @@ -2802,6 +2802,12 @@ argument of :method:`Symfony\\Component\\HttpFoundation\\UriSigner::sign`:: The feature to add an expiration date for a signed URI was introduced in Symfony 7.1. +.. note:: + + The generated URI hashes may include the ``/`` and ``+`` characters, which + can cause issues with certain clients. If you encounter this problem, replace + them using the following: ``strtr($hash, ['/' => '_', '+' => '-'])``. + Troubleshooting --------------- diff --git a/scheduler.rst b/scheduler.rst index eb018ca01dd..ddc40aa4952 100644 --- a/scheduler.rst +++ b/scheduler.rst @@ -455,6 +455,11 @@ The attribute takes more parameters to customize the trigger:: // defines the timezone to use #[AsCronTask('0 0 * * *', timezone: 'Africa/Malabo')] + // when applying this attribute to a Symfony console command, you can pass + // arguments and options to the command using the 'arguments' option: + #[AsCronTask('0 0 * * *', arguments: 'some_argument --some-option --another-option=some_value')] + class MyCommand extends Command + .. _scheduler-attributes-periodic-task: ``AsPeriodicTask`` Example @@ -499,6 +504,11 @@ The ``#[AsPeriodicTask]`` attribute takes many parameters to customize the trigg } } + // when applying this attribute to a Symfony console command, you can pass + // arguments and options to the command using the 'arguments' option: + #[AsPeriodicTask(frequency: '1 day', arguments: 'some_argument --some-option --another-option=some_value')] + class MyCommand extends Command + Managing Scheduled Messages --------------------------- diff --git a/security.rst b/security.rst index d684ba09ba7..7a551885ee4 100644 --- a/security.rst +++ b/security.rst @@ -1016,7 +1016,7 @@ be ``authenticate``:
{# ... the login fields #} - +
diff --git a/serializer/custom_normalizer.rst b/serializer/custom_normalizer.rst index 10092c6baa7..7435474c05c 100644 --- a/serializer/custom_normalizer.rst +++ b/serializer/custom_normalizer.rst @@ -3,7 +3,7 @@ How to Create your Custom Normalizer The :doc:`Serializer component ` uses normalizers to transform any data into an array. The component provides several -ref:`built-in normalizers ` but you may +:ref:`built-in normalizers ` but you may need to create your own normalizer to transform an unsupported data structure. diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index d8520ad05b4..9c4db187d51 100644 --- a/setup/upgrade_major.rst +++ b/setup/upgrade_major.rst @@ -160,20 +160,40 @@ starting with ``symfony/`` to the new major version: "...": "...", } -At the bottom of your ``composer.json`` file, in the ``extra`` block you can -find a data setting for the Symfony version. Make sure to also upgrade -this one. For instance, update it to ``7.0.*`` to upgrade to Symfony 7.0: +A more efficient way to handle Symfony dependency updates is by setting the +``extra.symfony.require`` configuration option in your ``composer.json`` file. +In Symfony applications using :doc:`Symfony Flex `, this setting +restricts Symfony packages to a single specific version, improving both +dependency management and Composer update performance: .. code-block:: diff - "extra": { - "symfony": { - "allow-contrib": false, - - "require": "6.4.*" - + "require": "7.0.*" - } + { + "...": "...", + + "require": { + - "symfony/cache": "7.0.*", + + "symfony/cache": "*", + - "symfony/config": "7.0.*", + + "symfony/config": "*", + - "symfony/console": "7.0.*", + + "symfony/console": "*", + "...": "...", + }, + "...": "...", + + + "extra": { + + "symfony": { + + "require": "7.0.*" + + } + + } } +.. warning:: + + Tools like `dependabot`_ may ignore this setting and upgrade Symfony + dependencies. For more details, see this `GitHub issue about dependabot`_. + .. tip:: If a more recent minor version is available (e.g. ``6.4``) you can use that @@ -336,3 +356,5 @@ Classes in the ``vendor/`` directory are always ignored. .. _`PHP CS Fixer`: https://github.com/friendsofphp/php-cs-fixer .. _`Rector`: https://github.com/rectorphp/rector .. _`maintained Symfony versions`: https://symfony.com/releases +.. _`dependabot`: https://docs.github.com/en/code-security/dependabot +.. _`GitHub issue about dependabot`: https://github.com/dependabot/dependabot-core/issues/4631 diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst index acd76c342b9..58935bf5352 100644 --- a/setup/web_server_configuration.rst +++ b/setup/web_server_configuration.rst @@ -207,6 +207,9 @@ When using Caddy on the server, you can use a configuration like this: # otherwise, use PHP-FPM (replace "unix//var/..." with "127.0.0.1:9000" when using TCP) php_fastcgi unix//var/run/php/php8.3-fpm.sock { + # only fall back to root index.php aka front controller. + try_files {path} index.php + # optionally set the value of the environment variables used in the application # env APP_ENV "prod" # env APP_SECRET "" diff --git a/testing/end_to_end.rst b/testing/end_to_end.rst index d59f243f998..8a624ae884e 100644 --- a/testing/end_to_end.rst +++ b/testing/end_to_end.rst @@ -111,12 +111,12 @@ Here is an example of a snippet that uses Panther to test an application:: $client->clickLink('Getting started'); // wait for an element to be present in the DOM, even if hidden - $crawler = $client->waitFor('#installing-the-framework'); + $crawler = $client->waitFor('#bootstrapping-the-core-library'); // you can also wait for an element to be visible - $crawler = $client->waitForVisibility('#installing-the-framework'); + $crawler = $client->waitForVisibility('#bootstrapping-the-core-library'); // get the text of an element thanks to the query selector syntax - echo $crawler->filter('#installing-the-framework')->text(); + echo $crawler->filter('div:has(> #bootstrapping-the-core-library)')->text(); // take a screenshot of the current page $client->takeScreenshot('screen.png'); @@ -305,13 +305,13 @@ faster. Two alternative clients are available: * The second leverages :class:`Symfony\\Component\\BrowserKit\\HttpBrowser`. It is an intermediate between Symfony's kernel and Panther's test clients. ``HttpBrowser`` sends real HTTP requests using the - :doc:`HttpClient component `. It is fast and is able to browse + :doc:`HttpClient component `. It is fast and can browse any webpage, not only the ones of the application under test. However, HttpBrowser doesn't support JavaScript and other advanced features because it is entirely written in PHP. This one can be used in any PHP application. -Because all clients implement the exact same API, you can switch from one to +Because all clients implement the same API, you can switch from one to another just by calling the appropriate factory method, resulting in a good trade-off for every single test case: if JavaScript is needed or not, if an authentication against an external SSO has to be done, etc. @@ -355,10 +355,10 @@ Testing Real-Time Applications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Panther provides a convenient way to test applications with real-time -capabilities which use `Mercure`_, `WebSocket`_ and similar technologies. +capabilities that use `Mercure`_, `WebSocket`_ and similar technologies. The ``PantherTestCase::createAdditionalPantherClient()`` method can create -additional, isolated browsers which can interact with other ones. For instance, +additional, isolated browsers that can interact with other ones. For instance, this can be useful to test a chat application having several users connected simultaneously:: @@ -451,6 +451,22 @@ To use a proxy server, you have to set the ``PANTHER_CHROME_ARGUMENTS``: # .env.test PANTHER_CHROME_ARGUMENTS='--proxy-server=socks://127.0.0.1:9050' +Using Selenium With the Built-In Web Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to use `Selenium Grid`_ with the built-in web server, you need to +configure the Panther client as follows:: + + $client = Client::createPantherClient( + options: [ + 'browser' => PantherTestCase::SELENIUM, + ], + managerOptions: [ + 'host' => 'http://selenium-hub:4444', // the host of the Selenium Server (Grid) + 'capabilities' => DesiredCapabilities::firefox(), // the capabilities of the browser + ], + ); + Accepting Self-Signed SSL Certificates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -597,6 +613,13 @@ behavior: Toggle the browser's dev tools (default ``enabled``, useful to debug) ``PANTHER_ERROR_SCREENSHOT_ATTACH`` Add screenshots mentioned above to test output in junit attachment format +``PANTHER_NO_REDUCED_MOTION`` + Disable non-essential movement in the browser (e.g. animations) + +.. versionadded:: 2.2.0 + + The support for the ``PANTHER_NO_REDUCED_MOTION`` env var was added + in Panther 2.2.0. Chrome Specific Environment Variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -604,7 +627,8 @@ Chrome Specific Environment Variables ``PANTHER_NO_SANDBOX`` Disable `Chrome's sandboxing`_ (unsafe, but allows to use Panther in containers) ``PANTHER_CHROME_ARGUMENTS`` - Customize Chrome arguments. You need to set ``PANTHER_NO_HEADLESS`` to fully customize + Customize Chrome arguments. You need to set ``PANTHER_NO_HEADLESS`` to ``1`` + to fully customize ``PANTHER_CHROME_BINARY`` To use another ``google-chrome`` binary @@ -616,12 +640,33 @@ Firefox Specific Environment Variables ``PANTHER_FIREFOX_BINARY`` To use another ``firefox`` binary +Changing the Size of the Browser Window +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's possible to control the size of the browser window. This also controls the +size of the screenshots. + +This is how you would do it with Chrome:: + + $client = Client::createChromeClient(null, ['--window-size=1500,4000']); + +You can achieve the same thing by setting the ``PANTHER_CHROME_ARGUMENTS`` env +var to ``--window-size=1500,4000``. + +On Firefox, here is how you would do it:: + + use Facebook\WebDriver\WebDriverDimension; + + $client = Client::createFirefoxClient(); + $size = new WebDriverDimension(1500, 4000); + $client->manage()->window()->setSize($size); + .. _panther_interactive-mode: Interactive Mode ---------------- -Panther can make a pause in your tests suites after a failure. +Panther can make a pause in your test suites after a failure. Thanks to this break time, you can investigate the encountered problem through the web browser. To enable this mode, you need the ``--debug`` PHPUnit option without the headless mode: @@ -709,7 +754,7 @@ Here is a minimal ``.travis.yaml`` file to run Panther tests: language: php addons: - # If you don't use Chrome, or Firefox, remove the corresponding line + # If you don't use Chrome or Firefox, remove the corresponding line chrome: stable firefox: latest @@ -788,7 +833,7 @@ The following features are not currently supported: * Updating existing documents (browsers are mostly used to consume data, not to create webpages) * Setting form values using the multidimensional PHP array syntax * Methods returning an instance of ``\DOMElement`` (because this library uses ``WebDriverElement`` internally) -* Selecting invalid choices in select +* Selecting invalid choices in the select Also, there is a known issue if you are using Bootstrap 5. It implements a scrolling effect which tends to mislead Panther. To fix this, we advise you to @@ -875,3 +920,4 @@ documentation: .. _`LiipFunctionalTestBundle`: https://github.com/liip/LiipFunctionalTestBundle .. _`PHP built-in server`: https://www.php.net/manual/en/features.commandline.webserver.php .. _`Functional Testing tutorial`: https://symfonycasts.com/screencast/last-stack/testing +.. _`Selenium Grid`: https://www.selenium.dev/documentation/grid/ diff --git a/translation.rst b/translation.rst index 96736dfd53a..2300f9ef2f6 100644 --- a/translation.rst +++ b/translation.rst @@ -145,7 +145,7 @@ different formats: .. code-block:: yaml # translations/messages.fr.yaml - Symfony is great: J'aime Symfony + Symfony is great: Symfony est génial .. code-block:: xml @@ -156,7 +156,7 @@ different formats: Symfony is great - J'aime Symfony + Symfony est génial @@ -166,14 +166,14 @@ different formats: // translations/messages.fr.php return [ - 'Symfony is great' => "J'aime Symfony", + 'Symfony is great' => 'Symfony est génial', ]; You can find more information on where these files :ref:`should be located `. Now, if the language of the user's locale is French (e.g. ``fr_FR`` or ``fr_BE``), -the message will be translated into ``J'aime Symfony``. You can also translate +the message will be translated into ``Symfony est génial``. You can also translate the message inside your :ref:`templates `. .. _translation-real-vs-keyword-messages: @@ -1192,7 +1192,7 @@ for the ``fr`` locale: Symfony is great - J'aime Symfony + Symfony est génial @@ -1201,13 +1201,13 @@ for the ``fr`` locale: .. code-block:: yaml # translations/messages.fr.yaml - Symfony is great: J'aime Symfony + Symfony is great: Symfony est génial .. code-block:: php // translations/messages.fr.php return [ - 'Symfony is great' => 'J\'aime Symfony', + 'Symfony is great' => 'Symfony est génial', ]; and for the ``en`` locale: @@ -1250,7 +1250,7 @@ To inspect all messages in the ``fr`` locale for the application, run: --------- ------------------ ---------------------- ------------------------------- State Id Message Preview (fr) Fallback Message Preview (en) --------- ------------------ ---------------------- ------------------------------- - unused Symfony is great J'aime Symfony Symfony is great + unused Symfony is great Symfony est génial Symfony is great --------- ------------------ ---------------------- ------------------------------- It shows you a table with the result when translating the message in the ``fr`` @@ -1270,7 +1270,7 @@ output: --------- ------------------ ---------------------- ------------------------------- State Id Message Preview (fr) Fallback Message Preview (en) --------- ------------------ ---------------------- ------------------------------- - Symfony is great J'aime Symfony Symfony is great + Symfony is great Symfony est génial Symfony is great --------- ------------------ ---------------------- ------------------------------- The state is empty which means the message is translated in the ``fr`` locale diff --git a/validation/custom_constraint.rst b/validation/custom_constraint.rst index ebf196e2b9b..40d19e0caa0 100644 --- a/validation/custom_constraint.rst +++ b/validation/custom_constraint.rst @@ -495,7 +495,7 @@ A class constraint validator must be applied to the class itself: use App\Validator as AcmeAssert; - #[AcmeAssert\ProtocolClass] + #[AcmeAssert\ConfirmedPaymentReceipt] class AcmeEntity { // ...