diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml index ac51116da5b..0768119d255 100644 --- a/.doctor-rst.yaml +++ b/.doctor-rst.yaml @@ -1,9 +1,5 @@ rules: american_english: ~ - argument_variable_must_match_type: - arguments: - - { type: 'ContainerBuilder', name: 'container' } - - { type: 'ContainerConfigurator', name: 'container' } avoid_repetetive_words: ~ blank_line_after_anchor: ~ blank_line_after_directive: ~ @@ -12,8 +8,12 @@ rules: correct_code_block_directive_based_on_the_content: ~ deprecated_directive_should_have_version: ~ ensure_bash_prompt_before_composer_command: ~ + ensure_correct_format_for_phpfunction: ~ ensure_exactly_one_space_before_directive_type: ~ ensure_exactly_one_space_between_link_definition_and_link: ~ + ensure_explicit_nullable_types: ~ + ensure_github_directive_start_with_prefix: + prefix: 'Symfony' ensure_link_bottom: ~ ensure_link_definition_contains_valid_url: ~ ensure_order_of_code_blocks_in_configuration_block: ~ @@ -23,17 +23,21 @@ rules: forbidden_directives: directives: - '.. index::' + - directive: '.. caution::' + replacements: ['.. warning::', '.. danger::'] indention: ~ lowercase_as_in_use_statements: ~ max_blank_lines: max: 2 max_colons: ~ no_app_console: ~ + no_attribute_redundant_parenthesis: ~ no_blank_line_after_filepath_in_php_code_block: ~ no_blank_line_after_filepath_in_twig_code_block: ~ no_blank_line_after_filepath_in_xml_code_block: ~ no_blank_line_after_filepath_in_yaml_code_block: ~ no_brackets_in_method_directive: ~ + no_broken_ref_directive: ~ no_composer_req: ~ no_directive_after_shorthand: ~ no_duplicate_use_statements: ~ @@ -44,6 +48,7 @@ rules: no_namespace_after_use_statements: ~ no_php_open_tag_in_code_block_php_directive: ~ no_space_before_self_xml_closing_tag: ~ + non_static_phpunit_assertions: ~ only_backslashes_in_namespace_in_php_code_block: ~ only_backslashes_in_use_statements_in_php_code_block: ~ ordered_use_statements: ~ @@ -92,13 +97,12 @@ whitelist: regex: - '/``.yml``/' - '/(.*)\.orm\.yml/' # currently DoctrineBundle only supports .yml - - /docker-compose\.yml/ lines: - 'in config files, so the old ``app/config/config_dev.yml`` goes to' - '#. The most important config file is ``app/config/services.yml``, which now is' - 'The bin/console Command' - '.. _`LDAP injection`: http://projects.webappsec.org/w/page/13246947/LDAP%20Injection' - - '.. versionadded:: 2.7.2' # Doctrine + - '.. versionadded:: 2.8.0' # Doctrine - '.. versionadded:: 1.9.0' # Encore - '.. versionadded:: 1.18' # Flex in setup/upgrade_minor.rst - '.. versionadded:: 1.0.0' # Encore @@ -109,5 +113,8 @@ whitelist: - '.. versionadded:: 0.2' # MercureBundle - '.. versionadded:: 3.6' # MonologBundle - '.. versionadded:: 3.8' # MonologBundle + - '.. versionadded:: 3.5' # Monolog + - '.. 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/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 17cec7af7c3..f32043e4523 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,6 +4,6 @@ If your pull request fixes a BUG, use the oldest maintained branch that contains the bug (see https://symfony.com/releases for the list of maintained branches). If your pull request documents a NEW FEATURE, use the same Symfony branch where -the feature was introduced (and `6.x` for features of unreleased versions). +the feature was introduced (and `7.x` for features of unreleased versions). --> diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index af2ea3a28a7..061b0bb85b0 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -21,12 +21,12 @@ jobs: steps: - name: "Checkout" - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: "Set-up PHP" uses: shivammathur/setup-php@v2 with: - php-version: 8.1 + php-version: 8.2 coverage: none tools: "composer:v2" @@ -57,7 +57,7 @@ jobs: steps: - name: "Checkout" - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: "Create cache dir" run: mkdir .cache @@ -73,71 +73,74 @@ jobs: key: ${{ runner.os }}-doctor-rst-${{ steps.extract_base_branch.outputs.branch }} - name: "Run DOCtor-RST" - uses: docker://oskarstark/doctor-rst:1.54.0 + uses: docker://oskarstark/doctor-rst:1.64.0 with: args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache symfony-code-block-checker: name: Code Blocks + runs-on: ubuntu-latest + continue-on-error: true + steps: - - name: Checkout code - uses: actions/checkout@v3 - with: - path: 'docs' - - - name: Set-up PHP - uses: shivammathur/setup-php@v2 - with: - php-version: 8.1 - coverage: none - - - name: Fetch branch from where the PR started - working-directory: docs - run: git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/* - - - name: Find modified files - id: find-files - working-directory: docs - run: echo "files=$(git diff --name-only origin/${{ github.base_ref }} HEAD | grep ".rst" | tr '\n' ' ')" >> $GITHUB_OUTPUT - - - name: Get composer cache directory - id: composercache - working-directory: docs/_build - run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT - - - name: Cache dependencies - if: ${{ steps.find-files.outputs.files }} - uses: actions/cache@v3 - with: - path: ${{ steps.composercache.outputs.dir }} - key: ${{ runner.os }}-composer-codeBlocks-${{ hashFiles('_checker/composer.lock', '_sf_app/composer.lock') }} - restore-keys: ${{ runner.os }}-composer-codeBlocks- - - - name: Install dependencies - if: ${{ steps.find-files.outputs.files }} - run: composer create-project symfony-tools/code-block-checker:@dev _checker - - - name: Install test application - if: ${{ steps.find-files.outputs.files }} - run: | - git clone -b ${{ github.base_ref }} --depth 5 --single-branch https://github.com/symfony-tools/symfony-application.git _sf_app - cd _sf_app - composer update - - - name: Generate baseline - if: ${{ steps.find-files.outputs.files }} - working-directory: docs - run: | - CURRENT=$(git rev-parse HEAD) - git checkout -m ${{ github.base_ref }} - ../_checker/code-block-checker.php verify:docs `pwd` ${{ steps.find-files.outputs.files }} --generate-baseline=baseline.json --symfony-application=`realpath ../_sf_app` - git checkout -m $CURRENT - cat baseline.json - - - name: Verify examples - if: ${{ steps.find-files.outputs.files }} - working-directory: docs - run: | - ../_checker/code-block-checker.php verify:docs `pwd` ${{ steps.find-files.outputs.files }} --baseline=baseline.json --output-format=github --symfony-application=`realpath ../_sf_app` + - name: Checkout code + uses: actions/checkout@v4 + with: + path: 'docs' + + - name: Set-up PHP + uses: shivammathur/setup-php@v2 + with: + php-version: 8.2 + coverage: none + + - name: Fetch branch from where the PR started + working-directory: docs + run: git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/* + + - name: Find modified files + id: find-files + working-directory: docs + run: echo "files=$(git diff --name-only origin/${{ github.base_ref }} HEAD | grep ".rst" | tr '\n' ' ')" >> $GITHUB_OUTPUT + + - name: Get composer cache directory + id: composercache + working-directory: docs/_build + run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT + + - name: Cache dependencies + if: ${{ steps.find-files.outputs.files }} + uses: actions/cache@v3 + with: + path: ${{ steps.composercache.outputs.dir }} + key: ${{ runner.os }}-composer-codeBlocks-${{ hashFiles('_checker/composer.lock', '_sf_app/composer.lock') }} + restore-keys: ${{ runner.os }}-composer-codeBlocks- + + - name: Install dependencies + if: ${{ steps.find-files.outputs.files }} + run: composer create-project symfony-tools/code-block-checker:@dev _checker + + - name: Install test application + if: ${{ steps.find-files.outputs.files }} + run: | + git clone -b ${{ github.base_ref }} --depth 5 --single-branch https://github.com/symfony-tools/symfony-application.git _sf_app + cd _sf_app + composer update + + - name: Generate baseline + if: ${{ steps.find-files.outputs.files }} + working-directory: docs + run: | + CURRENT=$(git rev-parse HEAD) + git checkout -m ${{ github.base_ref }} + ../_checker/code-block-checker.php verify:docs `pwd` ${{ steps.find-files.outputs.files }} --generate-baseline=baseline.json --symfony-application=`realpath ../_sf_app` + git checkout -m $CURRENT + cat baseline.json + + - name: Verify examples + if: ${{ steps.find-files.outputs.files }} + working-directory: docs + run: | + ../_checker/code-block-checker.php verify:docs `pwd` ${{ steps.find-files.outputs.files }} --baseline=baseline.json --output-format=github --symfony-application=`realpath ../_sf_app` diff --git a/README.md b/README.md index 17b6ea8ac74..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 6.3). +> 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/build.php b/_build/build.php index be2fb062a77..5298abe779a 100755 --- a/_build/build.php +++ b/_build/build.php @@ -20,7 +20,7 @@ $outputDir = __DIR__.'/output'; $buildConfig = (new BuildConfig()) - ->setSymfonyVersion('5.4') + ->setSymfonyVersion('7.1') ->setContentDir(__DIR__.'/..') ->setOutputDir($outputDir) ->setImagesDir(__DIR__.'/output/_images') diff --git a/_build/redirection_map b/_build/redirection_map index 3b845d59ffe..1701f4a8f70 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -525,11 +525,10 @@ /testing/functional_tests_assertions /testing#testing-application-assertions /components https://symfony.com/components /components/index https://symfony.com/components -/serializer/normalizers /components/serializer#normalizers -/components/serializer#component-serializer-attributes-groups-annotations /components/serializer#component-serializer-attributes-groups-attributes +/serializer/normalizers /serializer#serializer-built-in-normalizers /logging/monolog_regex_based_excludes /logging/monolog_exclude_http_codes /security/named_encoders /security/named_hashers -/components/inflector /components/string#inflector +/components/inflector /string#inflector /security/experimental_authenticators /security /security/user_provider /security/user_providers /security/reset_password /security/passwords#reset-password @@ -566,3 +565,11 @@ /messenger/handler_results /messenger#messenger-getting-handler-results /messenger/dispatch_after_current_bus /messenger#messenger-transactional-messages /messenger/multiple_buses /messenger#messenger-multiple-buses +/frontend/encore/server-data /frontend/server-data +/components/string /string +/testing/http_authentication /testing#testing_logging_in_users +/doctrine/registration_form /security#security-make-registration-form +/form/form_dependencies /form/create_custom_field_type +/doctrine/reverse_engineering /doctrine#doctrine-adding-mapping +/components/serializer /serializer +/serializer/custom_encoder /serializer/encoders#serializer-custom-encoder 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/_images/components/messenger/basic_cycle.png b/_images/components/messenger/basic_cycle.png new file mode 100644 index 00000000000..a0558968cbb Binary files /dev/null and b/_images/components/messenger/basic_cycle.png differ diff --git a/_images/components/scheduler/generate_consume.png b/_images/components/scheduler/generate_consume.png new file mode 100644 index 00000000000..269281266a5 Binary files /dev/null and b/_images/components/scheduler/generate_consume.png differ diff --git a/_images/components/scheduler/scheduler_cycle.png b/_images/components/scheduler/scheduler_cycle.png new file mode 100644 index 00000000000..18addb37d91 Binary files /dev/null and b/_images/components/scheduler/scheduler_cycle.png differ diff --git a/_images/components/serializer/serializer_workflow.svg b/_images/serializer/serializer_workflow.svg similarity index 100% rename from _images/components/serializer/serializer_workflow.svg rename to _images/serializer/serializer_workflow.svg diff --git a/_images/sources/components/serializer/serializer_workflow.dia b/_images/sources/serializer/serializer_workflow.dia similarity index 100% rename from _images/sources/components/serializer/serializer_workflow.dia rename to _images/sources/serializer/serializer_workflow.dia diff --git a/best_practices.rst b/best_practices.rst index 6541ac3ed02..2c393cae9c6 100644 --- a/best_practices.rst +++ b/best_practices.rst @@ -51,6 +51,7 @@ self-explanatory and not coupled to Symfony: │ └─ console ├─ config/ │ ├─ packages/ + │ ├─ routes/ │ └─ services.yaml ├─ migrations/ ├─ public/ @@ -108,6 +109,10 @@ Define these options as :ref:`parameters ` in the :ref:`environment ` in the ``config/services_dev.yaml`` and ``config/services_prod.yaml`` files. +Unless the application configuration is reused multiple times and needs +rigid validation, do *not* use the :doc:`Config component ` +to define the options. + Use Short and Prefixed Parameter Names ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -155,6 +160,8 @@ values is that it's complicated to redefine their values in your tests. Business Logic -------------- +.. _best-practice-no-application-bundles: + Don't Create any Bundle to Organize your Application Logic ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -376,17 +383,15 @@ inside the ``#[Security]`` attribute. Web Assets ---------- -Use Webpack Encore to Process Web Assets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _use-webpack-encore-to-process-web-assets: -Web assets are things like CSS, JavaScript, and image files that make the -frontend of your site look and work great. `Webpack`_ is the leading JavaScript -module bundler that compiles, transforms and packages assets for usage in a browser. +Use AssetMapper to Manage Web Assets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:doc:`Webpack Encore ` is a JavaScript library that gets rid of most -of Webpack complexity without hiding any of its features or distorting its usage -and philosophy. It was created for Symfony applications, but it works -for any application using any technology. +Web assets are the CSS, JavaScript, and image files that make the frontend of +your site look and work great. :doc:`AssetMapper ` lets +you write modern JavaScript and CSS without the complexity of using a bundler +such as `Webpack`_ (directly or via :doc:`Webpack Encore `). Tests ----- diff --git a/bundles.rst b/bundles.rst index efef039f775..878bee3af4a 100644 --- a/bundles.rst +++ b/bundles.rst @@ -3,10 +3,10 @@ The Bundle System ================= -.. caution:: +.. warning:: In Symfony versions prior to 4.0, it was recommended to organize your own - application code using bundles. This is no longer recommended and bundles + application code using bundles. This is :ref:`no longer recommended ` and bundles should only be used to share code and features between multiple applications. A bundle is similar to a plugin in other software, but even better. The core @@ -22,12 +22,15 @@ file:: return [ // 'all' means that the bundle is enabled for any Symfony environment Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true], - Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true], - Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true], - Symfony\Bundle\MonologBundle\MonologBundle::class => ['all' => true], - Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true], + // ... + + // this bundle is enabled only in 'dev' + Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true], + // ... + // this bundle is enabled only in 'dev' and 'test', so you can't use it in 'prod' Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true], + // ... ]; .. tip:: @@ -40,32 +43,32 @@ Creating a Bundle ----------------- This section creates and enables a new bundle to show there are only a few steps required. -The new bundle is called AcmeTestBundle, where the ``Acme`` portion is an example +The new bundle is called AcmeBlogBundle, where the ``Acme`` portion is an example name that should be replaced by some "vendor" name that represents you or your -organization (e.g. AbcTestBundle for some company named ``Abc``). +organization (e.g. AbcBlogBundle for some company named ``Abc``). -Start by creating a new class called ``AcmeTestBundle``:: +Start by creating a new class called ``AcmeBlogBundle``:: - // src/AcmeTestBundle.php - namespace Acme\TestBundle; + // src/AcmeBlogBundle.php + namespace Acme\BlogBundle; use Symfony\Component\HttpKernel\Bundle\AbstractBundle; - class AcmeTestBundle extends AbstractBundle + class AcmeBlogBundle extends AbstractBundle { } -.. caution:: +.. warning:: If your bundle must be compatible with previous Symfony versions you have to extend from the :class:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle` instead. .. tip:: - The name AcmeTestBundle follows the standard + The name AcmeBlogBundle follows the standard :ref:`Bundle naming conventions `. You could - also choose to shorten the name of the bundle to simply TestBundle by naming - this class TestBundle (and naming the file ``TestBundle.php``). + also choose to shorten the name of the bundle to simply BlogBundle by naming + this class BlogBundle (and naming the file ``BlogBundle.php``). This empty class is the only piece you need to create the new bundle. Though commonly empty, this class is powerful and can be used to customize the behavior @@ -74,10 +77,12 @@ of the bundle. Now that you've created the bundle, enable it:: // config/bundles.php return [ // ... - Acme\TestBundle\AcmeTestBundle::class => ['all' => true], + Acme\BlogBundle\AcmeBlogBundle::class => ['all' => true], ]; -And while it doesn't do anything yet, AcmeTestBundle is now ready to be used. +And while it doesn't do anything yet, AcmeBlogBundle is now ready to be used. + +.. _bundles-directory-structure: Bundle Directory Structure -------------------------- @@ -86,32 +91,34 @@ The directory structure of a bundle is meant to help to keep code consistent between all Symfony bundles. It follows a set of conventions, but is flexible to be adjusted if needed: -``src/`` - Contains all PHP classes related to the bundle logic (e.g. ``Controller/RandomController.php``). +``assets/`` + Contains the web asset sources like JavaScript and TypeScript files, CSS and + Sass files, but also images and other assets related to the bundle that are + not in ``public/`` (e.g. Stimulus controllers). ``config/`` - Houses configuration, including routing configuration (e.g. ``routing.yaml``). - -``templates/`` - Holds templates organized by controller name (e.g. ``random/index.html.twig``). - -``translations/`` - Holds translations organized by domain and locale (e.g. ``AcmeTestBundle.en.xlf``). + Houses configuration, including routing configuration (e.g. ``routes.php``). ``public/`` Contains web assets (images, compiled CSS and JavaScript files, etc.) and is copied or symbolically linked into the project ``public/`` directory via the ``assets:install`` console command. -``assets/`` - Contains the web asset sources (JavaScript and TypeScript files, CSS and Sass - files, etc.), images and other assets related to the bundle that are not in - ``public/`` (e.g. Stimulus controllers) +``src/`` + Contains all PHP classes related to the bundle logic (e.g. ``Controller/CategoryController.php``). + +``templates/`` + Holds templates organized by controller name (e.g. ``category/show.html.twig``). ``tests/`` Holds all tests for the bundle. -.. caution:: +``translations/`` + Holds translations organized by domain and locale (e.g. ``AcmeBlogBundle.en.xlf``). + +.. _bundles-legacy-directory-structure: + +.. warning:: The recommended bundle structure was changed in Symfony 5, read the `Symfony 4.4 bundle documentation`_ for information about the old @@ -121,7 +128,7 @@ to be adjusted if needed: new structure. Override the ``Bundle::getPath()`` method to change to the old structure:: - class AcmeTestBundle extends AbstractBundle + class AcmeBlogBundle extends AbstractBundle { public function getPath(): string { @@ -140,12 +147,12 @@ to be adjusted if needed: { "autoload": { "psr-4": { - "Acme\\TestBundle\\": "src/" + "Acme\\BlogBundle\\": "src/" } }, "autoload-dev": { "psr-4": { - "Acme\\TestBundle\\Tests\\": "tests/" + "Acme\\BlogBundle\\Tests\\": "tests/" } } } diff --git a/bundles/best_practices.rst b/bundles/best_practices.rst index a0915fbeaf4..376984388db 100644 --- a/bundles/best_practices.rst +++ b/bundles/best_practices.rst @@ -78,16 +78,22 @@ The following is the recommended directory structure of an AcmeBlogBundle: ├── LICENSE └── README.md -This directory structure requires to configure the bundle path to its root -directory as follows:: +.. note:: + + This directory structure is used by default when your bundle class extends + the recommended :class:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle`. + If your bundle extends the :class:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle` + class, you have to override the ``getPath()`` method as follows:: + + use Symfony\Component\HttpKernel\Bundle\Bundle; - class AcmeBlogBundle extends Bundle - { - public function getPath(): string + class AcmeBlogBundle extends Bundle { - return \dirname(__DIR__); + public function getPath(): string + { + return \dirname(__DIR__); + } } - } **The following files are mandatory**, because they ensure a structure convention that automated tools can rely on: @@ -240,7 +246,7 @@ with Symfony Flex to install a specific Symfony version: # recommended to have a better output and faster download time) composer update --prefer-dist --no-progress -.. caution:: +.. warning:: If you want to cache your Composer dependencies, **do not** cache the ``vendor/`` directory as this has side-effects. Instead cache @@ -292,7 +298,7 @@ following standardized instructions in your ``README.md`` file. Open a command console, enter your project directory and execute: ```console - $ composer require + composer require ``` Applications that don't use Symfony Flex @@ -304,7 +310,7 @@ following standardized instructions in your ``README.md`` file. following command to download the latest stable version of this bundle: ```console - $ composer require + composer require ``` ### Step 2: Enable the Bundle @@ -333,9 +339,9 @@ following standardized instructions in your ``README.md`` file. Open a command console, enter your project directory and execute: - .. code-block:: bash + .. code-block:: terminal - $ composer require + composer require Applications that don't use Symfony Flex ---------------------------------------- @@ -348,7 +354,7 @@ following standardized instructions in your ``README.md`` file. .. code-block:: terminal - $ composer require + composer require Step 2: Enable the Bundle ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/bundles/configuration.rst b/bundles/configuration.rst index a6a21023de6..dedfada2ea2 100644 --- a/bundles/configuration.rst +++ b/bundles/configuration.rst @@ -46,11 +46,110 @@ as integration of other related components: $framework->form()->enabled(true); }; +There are two different ways of creating friendly configuration for a bundle: + +#. :ref:`Using the main bundle class `: + this is recommended for new bundles and for bundles following the + :ref:`recommended directory structure `; +#. :ref:`Using the Bundle extension class `: + this was the traditional way of doing it, but nowadays it's only recommended for + bundles following the :ref:`legacy directory structure `. + +.. _using-the-bundle-class: +.. _bundle-friendly-config-bundle-class: + +Using the AbstractBundle Class +------------------------------ + +In bundles extending the :class:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle` +class, you can add all the logic related to processing the configuration in that class:: + + // src/AcmeSocialBundle.php + namespace Acme\SocialBundle; + + use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator; + use Symfony\Component\DependencyInjection\ContainerBuilder; + use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; + use Symfony\Component\HttpKernel\Bundle\AbstractBundle; + + class AcmeSocialBundle extends AbstractBundle + { + public function configure(DefinitionConfigurator $definition): void + { + $definition->rootNode() + ->children() + ->arrayNode('twitter') + ->children() + ->integerNode('client_id')->end() + ->scalarNode('client_secret')->end() + ->end() + ->end() // twitter + ->end() + ; + } + + public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void + { + // the "$config" variable is already merged and processed so you can + // use it directly to configure the service container (when defining an + // extension class, you also have to do this merging and processing) + $container->services() + ->get('acme_social.twitter_client') + ->arg(0, $config['twitter']['client_id']) + ->arg(1, $config['twitter']['client_secret']) + ; + } + } + +.. note:: + + The ``configure()`` and ``loadExtension()`` methods are called only at compile time. + +.. tip:: + + The ``AbstractBundle::configure()`` method also allows to import the + configuration definition from one or more files:: + + // src/AcmeSocialBundle.php + namespace Acme\SocialBundle; + + // ... + class AcmeSocialBundle extends AbstractBundle + { + public function configure(DefinitionConfigurator $definition): void + { + $definition->import('../config/definition.php'); + // you can also use glob patterns + //$definition->import('../config/definition/*.php'); + } + + // ... + } + + .. code-block:: php + + // config/definition.php + use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator; + + return static function (DefinitionConfigurator $definition): void { + $definition->rootNode() + ->children() + ->scalarNode('foo')->defaultValue('bar')->end() + ->end() + ; + }; + +.. _bundle-friendly-config-extension: + Using the Bundle Extension -------------------------- +This is the traditional way of creating friendly configuration for bundles. For new +bundles it's recommended to :ref:`use the main bundle class `, +but the traditional way of creating an extension class still works. + Imagine you are creating a new bundle - AcmeSocialBundle - which provides -integration with Twitter. To make your bundle configurable to the user, you +integration with X/Twitter. To make your bundle configurable to the user, you can add some configuration that looks like this: .. configuration-block:: @@ -110,7 +209,7 @@ load correct services and parameters inside an "Extension" class. If a bundle provides an Extension class, then you should *not* generally override any service container parameters from that bundle. The idea - is that if an Extension class is present, every setting that should be + is that if an extension class is present, every setting that should be configurable should be present in the configuration made available by that class. In other words, the extension class defines all the public configuration settings for which backward compatibility will be maintained. @@ -175,7 +274,7 @@ of your bundle's configuration. The ``Configuration`` class to handle the sample configuration looks like:: - // src/Acme/SocialBundle/DependencyInjection/Configuration.php + // src/DependencyInjection/Configuration.php namespace Acme\SocialBundle\DependencyInjection; use Symfony\Component\Config\Definition\Builder\TreeBuilder; @@ -216,7 +315,7 @@ This class can now be used in your ``load()`` method to merge configurations and force validation (e.g. if an additional option was passed, an exception will be thrown):: - // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php + // src/DependencyInjection/AcmeSocialExtension.php public function load(array $configs, ContainerBuilder $container): void { $configuration = new Configuration(); @@ -236,7 +335,7 @@ For example, imagine your bundle has the following example config: .. code-block:: xml - + - + @@ -253,8 +352,8 @@ For example, imagine your bundle has the following example config: In your extension, you can load this and dynamically set its arguments:: - // src/Acme/SocialBundle/DependencyInjection/AcmeSocialExtension.php - // ... + // src/DependencyInjection/AcmeSocialExtension.php + namespace Acme\SocialBundle\DependencyInjection; use Symfony\Component\Config\FileLocator; use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; @@ -267,7 +366,7 @@ In your extension, you can load this and dynamically set its arguments:: $configuration = new Configuration(); $config = $this->processConfiguration($configuration, $configs); - $definition = $container->getDefinition('acme.social.twitter_client'); + $definition = $container->getDefinition('acme_social.twitter_client'); $definition->replaceArgument(0, $config['twitter']['client_id']); $definition->replaceArgument(1, $config['twitter']['client_secret']); } @@ -279,7 +378,7 @@ In your extension, you can load this and dynamically set its arguments:: :class:`Symfony\\Component\\HttpKernel\\DependencyInjection\\ConfigurableExtension` to do this automatically for you:: - // src/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php + // src/DependencyInjection/HelloExtension.php namespace Acme\HelloBundle\DependencyInjection; use Symfony\Component\DependencyInjection\ContainerBuilder; @@ -315,89 +414,6 @@ In your extension, you can load this and dynamically set its arguments:: // ... now use the flat $config array } -.. _using-the-bundle-class: - -Using the AbstractBundle Class ------------------------------- - -As an alternative, instead of creating an extension and configuration class as -shown in the previous section, you can also extend -:class:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle` to add this -logic to the bundle class directly:: - - // src/AcmeSocialBundle.php - namespace Acme\SocialBundle; - - use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator; - use Symfony\Component\DependencyInjection\ContainerBuilder; - use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; - use Symfony\Component\HttpKernel\Bundle\AbstractBundle; - - class AcmeSocialBundle extends AbstractBundle - { - public function configure(DefinitionConfigurator $definition): void - { - $definition->rootNode() - ->children() - ->arrayNode('twitter') - ->children() - ->integerNode('client_id')->end() - ->scalarNode('client_secret')->end() - ->end() - ->end() // twitter - ->end() - ; - } - - public function loadExtension(array $config, ContainerConfigurator $containerConfigurator, ContainerBuilder $containerBuilder): void - { - // Contrary to the Extension class, the "$config" variable is already merged - // and processed. You can use it directly to configure the service container. - $containerConfigurator->services() - ->get('acme.social.twitter_client') - ->arg(0, $config['twitter']['client_id']) - ->arg(1, $config['twitter']['client_secret']) - ; - } - } - -.. note:: - - The ``configure()`` and ``loadExtension()`` methods are called only at compile time. - -.. tip:: - - The ``AbstractBundle::configure()`` method also allows to import the - configuration definition from one or more files:: - - // src/AcmeSocialBundle.php - - // ... - class AcmeSocialBundle extends AbstractBundle - { - public function configure(DefinitionConfigurator $definition): void - { - $definition->import('../config/definition.php'); - // you can also use glob patterns - //$definition->import('../config/definition/*.php'); - } - - // ... - } - - .. code-block:: php - - // config/definition.php - use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator; - - return static function (DefinitionConfigurator $definition): void { - $definition->rootNode() - ->children() - ->scalarNode('foo')->defaultValue('bar')->end() - ->end() - ; - }; - Modifying the Configuration of Another Bundle --------------------------------------------- @@ -413,7 +429,7 @@ The ``config:dump-reference`` command dumps the default configuration of a bundle in the console using the Yaml format. As long as your bundle's configuration is located in the standard location -(``YourBundle\DependencyInjection\Configuration``) and does not have +(``/src/DependencyInjection/Configuration``) and does not have a constructor, it will work automatically. If you have something different, your ``Extension`` class must override the :method:`Extension::getConfiguration() ` @@ -447,7 +463,8 @@ 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/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php + // src/DependencyInjection/AcmeHelloExtension.php + namespace Acme\HelloBundle\DependencyInjection; // ... class AcmeHelloExtension extends Extension @@ -476,10 +493,11 @@ namespace is then replaced with the XSD validation base path returned from 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 the ``Resources/config/schema/``, but you +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/Acme/HelloBundle/DependencyInjection/AcmeHelloExtension.php + // src/DependencyInjection/AcmeHelloExtension.php + namespace Acme\HelloBundle\DependencyInjection; // ... class AcmeHelloExtension extends Extension @@ -488,7 +506,7 @@ can place it anywhere you like. You should return this path as the base path:: public function getXsdValidationBasePath(): string { - return __DIR__.'/../Resources/config/schema'; + return __DIR__.'/../config/schema'; } } diff --git a/bundles/extension.rst b/bundles/extension.rst index 3c660251403..0537eb00c3e 100644 --- a/bundles/extension.rst +++ b/bundles/extension.rst @@ -6,12 +6,73 @@ file used by the application but in the bundles themselves. This article explains how to create and load service files using the bundle directory structure. +There are two different ways of doing it: + +#. :ref:`Load your services in the main bundle class `: + this is recommended for new bundles and for bundles following the + :ref:`recommended directory structure `; +#. :ref:`Create an extension class to load the service configuration files `: + this was the traditional way of doing it, but nowadays it's only recommended for + bundles following the :ref:`legacy directory structure `. + +.. _bundle-load-services-bundle-class: + +Loading Services Directly in your Bundle Class +---------------------------------------------- + +In bundles extending the :class:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle` +class, you can define the :method:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle::loadExtension` +method to load service definitions from configuration files:: + + // ... + use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; + use Symfony\Component\HttpKernel\Bundle\AbstractBundle; + + class AcmeHelloBundle extends AbstractBundle + { + public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void + { + // load an XML, PHP or YAML file + $container->import('../config/services.xml'); + + // you can also add or replace parameters and services + $container->parameters() + ->set('acme_hello.phrase', $config['phrase']) + ; + + if ($config['scream']) { + $container->services() + ->get('acme_hello.printer') + ->class(ScreamingPrinter::class) + ; + } + } + } + +This method works similar to the ``Extension::load()`` method explained below, +but it uses a new simpler API to define and import service configuration. + +.. note:: + + Contrary to the ``$configs`` parameter in ``Extension::load()``, the + ``$config`` parameter is already merged and processed by the + ``AbstractBundle``. + +.. note:: + + The ``loadExtension()`` is called only at compile time. + +.. _bundle-load-services-extension: + Creating an Extension Class --------------------------- -In order to load service configuration, you have to create a Dependency -Injection (DI) Extension for your bundle. By default, the Extension class must -follow these conventions (but later you'll learn how to skip them if needed): +This is the traditional way of loading service definitions in bundles. For new +bundles it's recommended to :ref:`load your services in the main bundle class `, +but the traditional way of creating an extension class still works. + +A dependency injection extension is defined as a class that follows these +conventions (later you'll learn how to skip them if needed): * It has to live in the ``DependencyInjection`` namespace of the bundle; @@ -20,7 +81,7 @@ follow these conventions (but later you'll learn how to skip them if needed): :class:`Symfony\\Component\\DependencyInjection\\Extension\\Extension` class; * The name is equal to the bundle name with the ``Bundle`` suffix replaced by - ``Extension`` (e.g. the Extension class of the AcmeBundle would be called + ``Extension`` (e.g. the extension class of the AcmeBundle would be called ``AcmeExtension`` and the one for AcmeHelloBundle would be called ``AcmeHelloExtension``). @@ -70,7 +131,7 @@ class name to underscores (e.g. ``AcmeHelloExtension``'s DI alias is ``acme_hello``). Using the ``load()`` Method ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the ``load()`` method, all services and parameters related to this extension will be loaded. This method doesn't get the actual container instance, but a @@ -108,53 +169,6 @@ 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. -Loading Services directly in your Bundle class ----------------------------------------------- - -Alternatively, you can define and load services configuration directly in a -bundle class instead of creating a specific ``Extension`` class. You can do -this by extending from :class:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle` -and defining the :method:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle::loadExtension` -method:: - - // ... - use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; - use Symfony\Component\HttpKernel\Bundle\AbstractBundle; - - class AcmeHelloBundle extends AbstractBundle - { - public function loadExtension(array $config, ContainerConfigurator $containerConfigurator, ContainerBuilder $containerBuilder): void - { - // load an XML, PHP or Yaml file - $containerConfigurator->import('../config/services.xml'); - - // you can also add or replace parameters and services - $containerConfigurator->parameters() - ->set('acme_hello.phrase', $config['phrase']) - ; - - if ($config['scream']) { - $containerConfigurator->services() - ->get('acme_hello.printer') - ->class(ScreamingPrinter::class) - ; - } - } - } - -This method works similar to the ``Extension::load()`` method, but it uses -a new API to define and import service configuration. - -.. note:: - - Contrary to the ``$configs`` parameter in ``Extension::load()``, the - ``$config`` parameter is already merged and processed by the - ``AbstractBundle``. - -.. note:: - - The ``loadExtension()`` is called only at compile time. - Adding Classes to Compile ------------------------- @@ -169,9 +183,9 @@ performance. Define the list of annotated classes to compile in the $this->addAnnotatedClassesToCompile([ // you can define the fully qualified class names... - 'App\\Controller\\DefaultController', + 'Acme\\BlogBundle\\Controller\\AuthorController', // ... but glob patterns are also supported: - '**Bundle\\Controller\\', + 'Acme\\BlogBundle\\Form\\**', // ... ]); @@ -186,7 +200,7 @@ Patterns are transformed into the actual class namespaces using the classmap generated by Composer. Therefore, before using these patterns, you must generate the full classmap executing the ``dump-autoload`` command of Composer. -.. caution:: +.. warning:: This technique can't be used when the classes to compile use the ``__DIR__`` or ``__FILE__`` constants, because their values will change when loading diff --git a/bundles/override.rst b/bundles/override.rst index 36aea69b231..f25bd785373 100644 --- a/bundles/override.rst +++ b/bundles/override.rst @@ -19,7 +19,7 @@ For example, to override the ``templates/registration/confirmed.html.twig`` template from the AcmeUserBundle, create this template: ``/templates/bundles/AcmeUserBundle/registration/confirmed.html.twig`` -.. caution:: +.. warning:: If you add a template in a new location, you *may* need to clear your cache (``php bin/console cache:clear``), even if you are in debug mode. diff --git a/bundles/prepend_extension.rst b/bundles/prepend_extension.rst index 4bd1c7c6a67..e4099d9f81a 100644 --- a/bundles/prepend_extension.rst +++ b/bundles/prepend_extension.rst @@ -154,7 +154,7 @@ registered and the ``entity_manager_name`` setting for ``acme_hello`` is set to Prepending Extension in the Bundle Class ---------------------------------------- -You can also append or prepend extension configuration directly in your +You can also prepend extension configuration directly in your Bundle class if you extend from the :class:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle` class and define the :method:`Symfony\\Component\\HttpKernel\\Bundle\\AbstractBundle::prependExtension` method:: @@ -172,12 +172,7 @@ method:: 'cache' => ['prefix_seed' => 'foo/bar'], ]); - // append - $containerConfigurator->extension('framework', [ - 'cache' => ['prefix_seed' => 'foo/bar'], - ]); - - // append from file + // prepend config from a file $containerConfigurator->import('../config/packages/cache.php'); } } @@ -186,8 +181,14 @@ 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\\ContainerConfigurator::extension` +:method:`Symfony\\Component\\DependencyInjection\\Loader\\Configurator\\ContainerConfigurator::extension` method:: use Symfony\Component\DependencyInjection\ContainerBuilder; @@ -211,7 +212,7 @@ method:: .. versionadded:: 7.1 The ``prepend`` parameter of the - :method:`Symfony\\Component\\DependencyInjection\\Loader\\ContainerConfigurator::extension` + :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 98ec11123fc..833e4d77007 100644 --- a/cache.rst +++ b/cache.rst @@ -133,12 +133,7 @@ Some of these adapters could be configured via shortcuts. default_psr6_provider: 'app.my_psr6_service' default_redis_provider: 'redis://localhost' default_memcached_provider: 'memcached://localhost' - default_pdo_provider: 'app.my_pdo_service' - - services: - app.my_pdo_service: - class: \PDO - arguments: ['pgsql:host=localhost'] + default_pdo_provider: 'pgsql:host=localhost' .. code-block:: xml @@ -159,24 +154,17 @@ Some of these adapters could be configured via shortcuts. default-psr6-provider="app.my_psr6_service" default-redis-provider="redis://localhost" default-memcached-provider="memcached://localhost" - default-pdo-provider="app.my_pdo_service" + default-pdo-provider="pgsql:host=localhost" /> - - - - pgsql:host=localhost - - .. code-block:: php // config/packages/cache.php - use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; use Symfony\Config\FrameworkConfig; - return static function (FrameworkConfig $framework, ContainerConfigurator $container): void { + return static function (FrameworkConfig $framework): void { $framework->cache() // Only used with cache.adapter.filesystem ->directory('%kernel.cache_dir%/pools') @@ -185,15 +173,14 @@ Some of these adapters could be configured via shortcuts. ->defaultPsr6Provider('app.my_psr6_service') ->defaultRedisProvider('redis://localhost') ->defaultMemcachedProvider('memcached://localhost') - ->defaultPdoProvider('app.my_pdo_service') - ; - - $container->services() - ->set('app.my_pdo_service', \PDO::class) - ->args(['pgsql:host=localhost']) + ->defaultPdoProvider('pgsql:host=localhost') ; }; +.. 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 @@ -467,7 +454,6 @@ and use that when configuring the pool. ->adapters(['cache.adapter.redis']) ->provider('app.my_custom_redis_provider'); - $container->register('app.my_custom_redis_provider', \Redis::class) ->setFactory([RedisAdapter::class, 'createConnection']) ->addArgument('redis://localhost') @@ -559,7 +545,7 @@ Using Cache Tags In applications with many cache keys it could be useful to organize the data stored to be able to invalidate the cache more efficiently. One way to achieve that is to use cache tags. One or more tags could be added to the cache item. All items with -the same key could be invalidated with one function call:: +the same tag could be invalidated with one function call:: use Symfony\Contracts\Cache\ItemInterface; use Symfony\Contracts\Cache\TagAwareCacheInterface; @@ -603,8 +589,7 @@ to enable this feature. This could be added by using the following configuration cache: pools: my_cache_pool: - adapter: cache.adapter.redis - tags: true + adapter: cache.adapter.redis_tag_aware .. code-block:: xml @@ -844,7 +829,7 @@ Then, register the ``SodiumMarshaller`` service using this key: //->addArgument(['env(base64:CACHE_DECRYPTION_KEY)', 'env(base64:OLD_CACHE_DECRYPTION_KEY)']) ->addArgument(new Reference('.inner')); -.. caution:: +.. danger:: This will encrypt the values of the cache items, but not the cache keys. Be careful not to leak sensitive data in the keys. @@ -899,7 +884,7 @@ In the following example, the value is requested from a controller:: use App\Cache\CacheComputation; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; use Symfony\Contracts\Cache\CacheInterface; use Symfony\Contracts\Cache\ItemInterface; @@ -909,7 +894,7 @@ In the following example, the value is requested from a controller:: public function index(CacheInterface $asyncCache): Response { // pass to the cache the service method that refreshes the item - $cachedValue = $cache->get('my_value', [CacheComputation::class, 'compute']) + $cachedValue = $asyncCache->get('my_value', [CacheComputation::class, 'compute']) // ... } @@ -927,13 +912,13 @@ a message bus to compute values in a worker: cache: pools: async.cache: - early_expiration_message_bus: async_bus + early_expiration_message_bus: messenger.default_bus messenger: transports: async_bus: '%env(MESSENGER_TRANSPORT_DSN)%' routing: - Symfony\Component\Cache\Messenger\Message\EarlyExpirationMessage: async_bus + 'Symfony\Component\Cache\Messenger\EarlyExpirationMessage': async_bus .. code-block:: xml @@ -949,12 +934,12 @@ a message bus to compute values in a worker: > - + %env(MESSENGER_TRANSPORT_DSN)% - + @@ -971,7 +956,7 @@ a message bus to compute values in a worker: return static function (FrameworkConfig $framework): void { $framework->cache() ->pool('async.cache') - ->earlyExpirationMessageBus('async_bus'); + ->earlyExpirationMessageBus('messenger.default_bus'); $framework->messenger() ->transport('async_bus') diff --git a/components/asset.rst b/components/asset.rst index 5fa966bb85b..d6d3f485859 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -180,16 +180,16 @@ listed in the manifest:: // error: If your JSON file is not on your local filesystem but is accessible over HTTP, -use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\RemoteJsonManifestVersionStrategy` +use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\JsonManifestVersionStrategy` with the :doc:`HttpClient component `:: use Symfony\Component\Asset\Package; - use Symfony\Component\Asset\VersionStrategy\RemoteJsonManifestVersionStrategy; + use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy; use Symfony\Component\HttpClient\HttpClient; $httpClient = HttpClient::create(); $manifestUrl = 'https://cdn.example.com/rev-manifest.json'; - $package = new Package(new RemoteJsonManifestVersionStrategy($manifestUrl, $httpClient)); + $package = new Package(new JsonManifestVersionStrategy($manifestUrl, $httpClient)); Custom Version Strategies ......................... @@ -203,14 +203,14 @@ every day:: class DateVersionStrategy implements VersionStrategyInterface { - private \DateTimeInterface $version; + private string $version; public function __construct() { $this->version = date('Ymd'); } - public function getVersion(string $path): \DateTimeInterface + public function getVersion(string $path): string { return $this->version; } diff --git a/components/cache.rst b/components/cache.rst index 138e770de61..f5a76f2119d 100644 --- a/components/cache.rst +++ b/components/cache.rst @@ -135,7 +135,6 @@ The following cache adapters are available: cache/adapters/* - .. _cache-component-psr6-caching: Generic Caching (PSR-6) diff --git a/components/cache/adapters/apcu_adapter.rst b/components/cache/adapters/apcu_adapter.rst index 99d76ce5d27..f2e92850cd8 100644 --- a/components/cache/adapters/apcu_adapter.rst +++ b/components/cache/adapters/apcu_adapter.rst @@ -5,7 +5,7 @@ This adapter is a high-performance, shared memory cache. It can *significantly* increase an application's performance, as its cache contents are stored in shared memory, a component appreciably faster than many others, such as the filesystem. -.. caution:: +.. warning:: **Requirement:** The `APCu extension`_ must be installed and active to use this adapter. @@ -30,7 +30,7 @@ and cache items version string as constructor arguments:: $version = null ); -.. caution:: +.. warning:: Use of this adapter is discouraged in write/delete heavy workloads, as these operations cause memory fragmentation that results in significantly degraded performance. diff --git a/components/cache/adapters/couchbasebucket_adapter.rst b/components/cache/adapters/couchbasebucket_adapter.rst index 8927a8c53f8..29c9e26f83c 100644 --- a/components/cache/adapters/couchbasebucket_adapter.rst +++ b/components/cache/adapters/couchbasebucket_adapter.rst @@ -14,7 +14,7 @@ shared memory; you can store contents independent of your PHP environment. The ability to utilize a cluster of servers to provide redundancy and/or fail-over is also available. -.. caution:: +.. warning:: **Requirements:** The `Couchbase PHP extension`_ as well as a `Couchbase server`_ must be installed, active, and running to use this adapter. Version ``2.6`` or @@ -41,7 +41,6 @@ the second and third parameters:: $defaultLifetime ); - Configure the Connection ------------------------ @@ -73,7 +72,6 @@ helper method allows creating and configuring a `Couchbase Bucket`_ class instan 'couchbase:?host[localhost]&host[localhost:12345]' ); - Configure the Options --------------------- diff --git a/components/cache/adapters/couchbasecollection_adapter.rst b/components/cache/adapters/couchbasecollection_adapter.rst index cce308a9146..ba78cc46eff 100644 --- a/components/cache/adapters/couchbasecollection_adapter.rst +++ b/components/cache/adapters/couchbasecollection_adapter.rst @@ -8,7 +8,7 @@ shared memory; you can store contents independent of your PHP environment. The ability to utilize a cluster of servers to provide redundancy and/or fail-over is also available. -.. caution:: +.. warning:: **Requirements:** The `Couchbase PHP extension`_ as well as a `Couchbase server`_ must be installed, active, and running to use this adapter. Version ``3.0`` or @@ -32,7 +32,6 @@ the second and third parameters:: $defaultLifetime ); - Configure the Connection ------------------------ @@ -64,7 +63,6 @@ helper method allows creating and configuring a `Couchbase Collection`_ class in 'couchbase:?host[localhost]&host[localhost:12345]' ); - Configure the Options --------------------- diff --git a/components/cache/adapters/filesystem_adapter.rst b/components/cache/adapters/filesystem_adapter.rst index 4c447b3de82..db877454859 100644 --- a/components/cache/adapters/filesystem_adapter.rst +++ b/components/cache/adapters/filesystem_adapter.rst @@ -33,7 +33,7 @@ and cache root path as constructor parameters:: $directory = null ); -.. caution:: +.. warning:: The overhead of filesystem IO often makes this adapter one of the *slower* choices. If throughput is paramount, the in-memory adapters @@ -63,6 +63,5 @@ adapter offers better read performance when using tag-based invalidation:: $cache = new FilesystemTagAwareAdapter(); - .. _`tmpfs`: https://wiki.archlinux.org/index.php/tmpfs .. _`RAM disk solutions`: https://en.wikipedia.org/wiki/List_of_RAM_drive_software diff --git a/components/cache/adapters/memcached_adapter.rst b/components/cache/adapters/memcached_adapter.rst index d68d3e3b9ac..64baf0d4702 100644 --- a/components/cache/adapters/memcached_adapter.rst +++ b/components/cache/adapters/memcached_adapter.rst @@ -8,7 +8,7 @@ shared memory; you can store contents independent of your PHP environment. The ability to utilize a cluster of servers to provide redundancy and/or fail-over is also available. -.. caution:: +.. warning:: **Requirements:** The `Memcached PHP extension`_ as well as a `Memcached server`_ must be installed, active, and running to use this adapter. Version ``2.2`` or @@ -256,7 +256,7 @@ Available Options executed in a "fire-and-forget" manner; no attempt to ensure the operation has been received or acted on will be made once the client has executed it. - .. caution:: + .. warning:: Not all library operations are tested in this mode. Mixed TCP and UDP servers are not allowed. diff --git a/components/cache/adapters/php_files_adapter.rst b/components/cache/adapters/php_files_adapter.rst index efd2cf0e964..6f171f0fede 100644 --- a/components/cache/adapters/php_files_adapter.rst +++ b/components/cache/adapters/php_files_adapter.rst @@ -28,7 +28,7 @@ file similar to the following:: handles file includes, this adapter has the potential to be much faster than other filesystem-based caches. -.. caution:: +.. warning:: While it supports updates and because it is using OPcache as a backend, this adapter is better suited for append-mostly needs. Using it in other scenarios might lead to diff --git a/components/cache/adapters/redis_adapter.rst b/components/cache/adapters/redis_adapter.rst index 1550d419081..3362f4cc2db 100644 --- a/components/cache/adapters/redis_adapter.rst +++ b/components/cache/adapters/redis_adapter.rst @@ -15,7 +15,7 @@ Unlike the :doc:`APCu adapter `, and si shared memory; you can store contents independent of your PHP environment. The ability to utilize a cluster of servers to provide redundancy and/or fail-over is also available. -.. caution:: +.. warning:: **Requirements:** At least one `Redis server`_ must be installed and running to use this adapter. Additionally, this adapter requires a compatible extension or library that implements @@ -38,13 +38,19 @@ as the second and third parameters:: // the default lifetime (in seconds) for cache items that do not define their // own lifetime, with a value 0 causing items to be stored indefinitely (i.e. // until RedisAdapter::clear() is invoked or the server(s) are purged) - $defaultLifetime = 0 + $defaultLifetime = 0, + + // $marshaller (optional) An instance of MarshallerInterface to control the serialization + // and deserialization of cache items. By default, native PHP serialization is used. + // This can be useful for compressing data, applying custom serialization logic, or + // optimizing the size and performance of cached items + ?MarshallerInterface $marshaller = null ); Configure the Connection ------------------------ -The :method:`Symfony\\Component\\Cache\\Adapter\\RedisAdapter::createConnection` +The :method:`Symfony\\Component\\Cache\\Traits\\RedisTrait::createConnection` helper method allows creating and configuring the Redis client class instance using a `Data Source Name (DSN)`_:: @@ -195,7 +201,7 @@ Available Options ``redis_cluster`` (type: ``bool``, default: ``false``) Enables or disables redis cluster. The actual value passed is irrelevant as long as it passes loose comparison - checks: `redis_cluster=1` will suffice. + checks: ``redis_cluster=1`` will suffice. ``redis_sentinel`` (type: ``string``, default: ``null``) Specifies the master name connected to the sentinels. @@ -266,6 +272,80 @@ performance when using tag-based invalidation:: Read more about this topic in the official `Redis LRU Cache Documentation`_. +Working with Marshaller +----------------------- + +TagAwareMarshaller for Tag-Based Caching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Optimizes caching for tag-based retrieval, allowing efficient management of related items:: + + $marshaller = new TagAwareMarshaller(); + + $cache = new RedisAdapter($redis, 'tagged_namespace', 3600, $marshaller); + + $item = $cache->getItem('tagged_key'); + $item->set(['value' => 'some_data', 'tags' => ['tag1', 'tag2']]); + $cache->save($item); + +SodiumMarshaller for Encrypted Caching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Encrypts cached data using Sodium for enhanced security:: + + $encryptionKeys = [sodium_crypto_box_keypair()]; + $marshaller = new SodiumMarshaller($encryptionKeys); + + $cache = new RedisAdapter($redis, 'secure_namespace', 3600, $marshaller); + + $item = $cache->getItem('secure_key'); + $item->set('confidential_data'); + $cache->save($item); + +DefaultMarshaller with igbinary Serialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Uses ``igbinary` for faster and more efficient serialization when available:: + + $marshaller = new DefaultMarshaller(true); + + $cache = new RedisAdapter($redis, 'optimized_namespace', 3600, $marshaller); + + $item = $cache->getItem('optimized_key'); + $item->set(['data' => 'optimized_data']); + $cache->save($item); + +DefaultMarshaller with Exception on Failure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Throws an exception if serialization fails, facilitating error handling:: + + $marshaller = new DefaultMarshaller(false, true); + + $cache = new RedisAdapter($redis, 'error_namespace', 3600, $marshaller); + + try { + $item = $cache->getItem('error_key'); + $item->set('data'); + $cache->save($item); + } catch (\ValueError $e) { + echo 'Serialization failed: '.$e->getMessage(); + } + +SodiumMarshaller with Key Rotation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Supports key rotation, ensuring secure decryption with both old and new keys:: + + $keys = [sodium_crypto_box_keypair(), sodium_crypto_box_keypair()]; + $marshaller = new SodiumMarshaller($keys); + + $cache = new RedisAdapter($redis, 'rotated_namespace', 3600, $marshaller); + + $item = $cache->getItem('rotated_key'); + $item->set('data_to_encrypt'); + $cache->save($item); + .. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name .. _`Redis server`: https://redis.io/ .. _`Redis`: https://github.com/phpredis/phpredis diff --git a/components/cache/cache_items.rst b/components/cache/cache_items.rst index 715dc0c4401..e958125c69d 100644 --- a/components/cache/cache_items.rst +++ b/components/cache/cache_items.rst @@ -12,9 +12,8 @@ Cache Item Keys and Values The **key** of a cache item is a plain string which acts as its identifier, so it must be unique for each cache pool. You can freely choose the keys, but they should only contain letters (A-Z, a-z), numbers (0-9) and the -``_`` and ``.`` symbols. Other common symbols (such as ``{``, ``}``, ``(``, -``)``, ``/``, ``\``, ``@`` and ``:``) are reserved by the PSR-6 standard for future -uses. +``_`` and ``.`` symbols. Other common symbols (such as ``{ } ( ) / \ @ :``) are +reserved by the PSR-6 standard for future uses. The **value** of a cache item can be any data represented by a type which is serializable by PHP, such as basic types (string, integer, float, boolean, null), diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst index e0bc9bd3ba1..e50c2b67633 100644 --- a/components/cache/cache_pools.rst +++ b/components/cache/cache_pools.rst @@ -25,7 +25,6 @@ ready to use in your applications. adapters/* - Using the Cache Contracts ------------------------- diff --git a/components/clock.rst b/components/clock.rst index b803c78e29d..5b20e6000b9 100644 --- a/components/clock.rst +++ b/components/clock.rst @@ -129,18 +129,18 @@ is expired or not, by modifying the clock's time:: $validUntil = new DateTimeImmutable('2022-11-16 15:25:00'); // $validUntil is in the future, so it is not expired - static::assertFalse($expirationChecker->isExpired($validUntil)); + $this->assertFalse($expirationChecker->isExpired($validUntil)); // Clock sleeps for 10 minutes, so now is '2022-11-16 15:30:00' $clock->sleep(600); // Instantly changes time as if we waited for 10 minutes (600 seconds) // modify the clock, accepts all formats supported by DateTimeImmutable::modify() - static::assertTrue($expirationChecker->isExpired($validUntil)); + $this->assertTrue($expirationChecker->isExpired($validUntil)); $clock->modify('2022-11-16 15:00:00'); // $validUntil is in the future again, so it is no longer expired - static::assertFalse($expirationChecker->isExpired($validUntil)); + $this->assertFalse($expirationChecker->isExpired($validUntil)); } } @@ -229,12 +229,44 @@ The constructor also allows setting a timezone or custom referenced date:: $referenceDate = new \DateTimeImmutable(); $relativeDate = new DatePoint('+1month', reference: $referenceDate); +The ``DatePoint`` class also provides a named constructor to create dates from +timestamps:: + + $dateOfFirstCommitToSymfonyProject = DatePoint::createFromTimestamp(1129645656); + // equivalent to: + // $dateOfFirstCommitToSymfonyProject = (new \DateTimeImmutable())->setTimestamp(1129645656); + + // negative timestamps (for dates before January 1, 1970) and float 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 error handling across versions of PHP, thanks to polyfilling `PHP 8.3's behavior`_ on the topic. +``DatePoint`` also allows to set and get the microsecond part of the date and time:: + + $datePoint = new DatePoint(); + $datePoint->setMicrosecond(345); + $microseconds = $datePoint->getMicrosecond(); + +.. note:: + + 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. + .. _clock_writing-tests: Writing Time-Sensitive Tests diff --git a/components/config.rst b/components/config.rst index 579d5b3149d..9de03f1f869 100644 --- a/components/config.rst +++ b/components/config.rst @@ -1,9 +1,17 @@ The Config Component ==================== - The Config component provides several classes to help you find, load, - combine, fill and validate configuration values of any kind, whatever - their source may be (YAML, XML, INI files, or for instance a database). +The Config component provides utilities to define and manage the configuration +options of PHP applications. It allows you to: + +* Define a configuration structure, its validation rules, default values and documentation; +* Support different configuration formats (YAML, XML, INI, etc.); +* Merge multiple configurations from different sources into a single configuration. + +.. note:: + + You don't have to use this component to configure Symfony applications. + Instead, read the docs about :doc:`how to configure Symfony applications `. Installation ------------ diff --git a/components/config/caching.rst b/components/config/caching.rst index 810db48107e..18620c0d8cf 100644 --- a/components/config/caching.rst +++ b/components/config/caching.rst @@ -55,3 +55,17 @@ the cache file itself. This ``.meta`` file contains the serialized resources, whose timestamps are used to determine if the cache is still fresh. When not in debug mode, the cache is considered to be "fresh" as soon as it exists, and therefore no ``.meta`` file will be generated. + +You can explicitly define the absolute path to the meta file:: + + use Symfony\Component\Config\ConfigCache; + use Symfony\Component\Config\Resource\FileResource; + + $cachePath = __DIR__.'/cache/appUserMatcher.php'; + + // 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 63ebcd7cc72..19e4f5fd40c 100644 --- a/components/config/definition.rst +++ b/components/config/definition.rst @@ -81,7 +81,7 @@ reflect the real structure of the configuration values:: ->defaultTrue() ->end() ->scalarNode('default_connection') - ->defaultValue('default') + ->defaultValue('mysql') ->end() ->end() ; @@ -670,7 +670,7 @@ The separator used in keys is typically ``_`` in YAML and ``-`` in XML. For example, ``auto_connect`` in YAML and ``auto-connect`` in XML. The normalization would make both of these ``auto_connect``. -.. caution:: +.. warning:: The target key will not be altered if it's mixed like ``foo-bar_moo`` or if it already exists. @@ -889,7 +889,7 @@ Otherwise the result is a clean array of configuration values:: $configs ); -.. caution:: +.. warning:: When processing the configuration tree, the processor assumes that the top level array key (which matches the extension name) is already stripped off. diff --git a/components/console/changing_default_command.rst b/components/console/changing_default_command.rst index b739e3b39ba..c69995ea395 100644 --- a/components/console/changing_default_command.rst +++ b/components/console/changing_default_command.rst @@ -52,7 +52,7 @@ This will print the following to the command line: Hello World -.. caution:: +.. warning:: This feature has a limitation: you cannot pass any argument or option to the default command because they are ignored. diff --git a/components/console/events.rst b/components/console/events.rst index f0edf2205ac..e550025b7dd 100644 --- a/components/console/events.rst +++ b/components/console/events.rst @@ -14,7 +14,7 @@ the wheel, it uses the Symfony EventDispatcher component to do the work:: $application->setDispatcher($dispatcher); $application->run(); -.. caution:: +.. warning:: Console events are only triggered by the main command being executed. Commands called by the main command will not trigger any event, unless diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index 5e4ae0d91fb..3cb87c4c307 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -64,8 +64,9 @@ block will be formatted with more padding (one blank line above and below the messages and 2 spaces on the left and right). The exact "style" you use in the block is up to you. In this case, you're using -the pre-defined ``error`` style, but there are other styles, or you can create -your own. See :doc:`/console/coloring`. +the pre-defined ``error`` style, but there are other styles (``info``, +``comment``, ``question``), or you can create your own. +See :doc:`/console/coloring`. Print Truncated Messages ------------------------ @@ -87,7 +88,7 @@ And the output will be: This is... -The message is truncated to the given length, then the suffix is appended to end +The message is truncated to the given length, then the suffix is appended to the end of that string. Negative String Length @@ -109,7 +110,7 @@ Custom Suffix By default, the ``...`` suffix is used. If you wish to use a different suffix, pass it as the third argument to the method. -The suffix is always appended, unless truncate length is longer than a message +The suffix is always appended, unless truncated length is longer than a message and a suffix length. If you don't want to use suffix at all, pass an empty string:: diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index 4d524a2008e..19e2d0daef5 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -323,7 +323,7 @@ to display it can be customized:: // the bar width $progressBar->setBarWidth(50); -.. caution:: +.. warning:: For performance reasons, Symfony redraws the screen once every 100ms. If this is too fast or too slow for your application, use the methods diff --git a/components/console/helpers/questionhelper.rst b/components/console/helpers/questionhelper.rst index e33c4ed5fa7..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 @@ -329,7 +351,7 @@ convenient for passwords:: return Command::SUCCESS; } -.. caution:: +.. warning:: When you ask for a hidden response, Symfony will use either a binary, change ``stty`` mode or use another trick to hide the response. If none is available, @@ -392,7 +414,7 @@ method:: return Command::SUCCESS; } -.. caution:: +.. warning:: The normalizer is called first and the returned value is used as the input of the validator. If the answer is invalid, don't throw exceptions in the @@ -540,7 +562,7 @@ This way you can test any user interaction (even complex ones) by passing the ap simulates a user hitting ``ENTER`` after each input, no need for passing an additional input. -.. caution:: +.. warning:: On Windows systems Symfony uses a special binary to implement hidden questions. This means that those questions don't use the default ``Input`` diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index 6d86cbc6130..13bdeb491f0 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -220,7 +220,7 @@ You can also set the style to ``box``:: which outputs: -.. code-block:: text +.. code-block:: terminal ┌───────────────┬──────────────────────────┬──────────────────┐ │ ISBN │ Title │ Author │ @@ -238,7 +238,7 @@ You can also set the style to ``box-double``:: which outputs: -.. code-block:: text +.. code-block:: terminal ╔═══════════════╤══════════════════════════╤══════════════════╗ ║ ISBN │ Title │ Author ║ @@ -449,3 +449,24 @@ This will display the following table in the terminal: | Love | | Symfony | +---------+ + +.. tip:: + + You can create multiple lines using the :method:`Symfony\\Component\\Console\\Helper\\Table::addRows` method:: + + // ... + $table->addRows([ + ['Hello', 'World'], + ['Love', 'Symfony'], + ]); + $table->render(); + // ... + + This will display: + + .. code-block:: terminal + + +-------+---------+ + | Hello | World | + | Love | Symfony | + +-------+---------+ diff --git a/components/console/usage.rst b/components/console/usage.rst index a38b06c2cc4..d7725e8926e 100644 --- a/components/console/usage.rst +++ b/components/console/usage.rst @@ -104,7 +104,7 @@ If you do not provide a console name then it will just output: .. code-block:: text - console tool + Console Tool You can force turning on ANSI output coloring with: diff --git a/components/css_selector.rst b/components/css_selector.rst index c09f80a3cf4..1331a11e616 100644 --- a/components/css_selector.rst +++ b/components/css_selector.rst @@ -92,7 +92,11 @@ Pseudo-classes are partially supported: * Not supported: ``*:first-of-type``, ``*:last-of-type``, ``*:nth-of-type`` and ``*:nth-last-of-type`` (all these work with an element name (e.g. ``li:first-of-type``) but not with the ``*`` selector). -* Supported: ``*:only-of-type``, ``*:scope``. +* 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 79b35bf312e..93e8af711cf 100644 --- a/components/dependency_injection.rst +++ b/components/dependency_injection.rst @@ -178,7 +178,6 @@ You can override this behavior as follows:: // the second argument is optional and defines what to do when the service doesn't exist $newsletterManager = $containerBuilder->get('newsletter_manager', ContainerInterface::EXCEPTION_ON_INVALID_REFERENCE); - These are all the possible behaviors: * ``ContainerInterface::EXCEPTION_ON_INVALID_REFERENCE``: throws an exception diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst index 3787c686982..7f991e85b72 100644 --- a/components/dependency_injection/compilation.rst +++ b/components/dependency_injection/compilation.rst @@ -150,7 +150,7 @@ will look like this:: ], ] -Whilst you can manually manage merging the different files, it is much better +While you can manually manage merging the different files, it is much better to use :doc:`the Config component ` to merge and validate the config values. Using the configuration processing you could access the config value this way:: diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst index ac859efac91..630d301302a 100644 --- a/components/dom_crawler.rst +++ b/components/dom_crawler.rst @@ -267,7 +267,7 @@ The result is an array of values returned by the anonymous function calls. When using nested crawler, beware that ``filterXPath()`` is evaluated in the context of the crawler:: - $crawler->filterXPath('parent')->each(function (Crawler $parentCrawler, $i): avoid { + $crawler->filterXPath('parent')->each(function (Crawler $parentCrawler, $i): void { // DON'T DO THIS: direct child can not be found $subCrawler = $parentCrawler->filterXPath('sub-tag/sub-child-tag'); diff --git a/components/event_dispatcher.rst b/components/event_dispatcher.rst index 9d33ec6869e..8cd676dd5fe 100644 --- a/components/event_dispatcher.rst +++ b/components/event_dispatcher.rst @@ -28,7 +28,7 @@ truly extensible. Take an example from :doc:`the HttpKernel component `. Once a ``Response`` object has been created, it may be useful to allow other elements in the system to modify it (e.g. add some cache headers) before -it's actually used. To make this possible, the Symfony kernel throws an +it's actually used. To make this possible, the Symfony kernel dispatches an event - ``kernel.response``. Here's how it works: * A *listener* (PHP object) tells a central *dispatcher* object that it @@ -69,17 +69,6 @@ An :class:`Symfony\\Contracts\\EventDispatcher\\Event` instance is also created and passed to all of the listeners. As you'll see later, the ``Event`` object itself often contains data about the event being dispatched. -Naming Conventions -.................. - -The unique event name can be any string, but optionally follows a few -naming conventions: - -* Use only lowercase letters, numbers, dots (``.``) and underscores (``_``); -* Prefix names with a namespace followed by a dot (e.g. ``order.*``, ``user.*``); -* End names with a verb that indicates what action has been taken (e.g. - ``order.placed``). - Event Names and Event Objects ............................. @@ -257,7 +246,7 @@ system flexible and decoupled. Creating an Event Class ....................... -Suppose you want to create a new event - ``order.placed`` - that is dispatched +Suppose you want to create a new event that is dispatched each time a customer orders a product with your application. When dispatching this event, you'll pass a custom event instance that has access to the placed order. Start by creating this custom event class and documenting it:: @@ -268,17 +257,12 @@ order. Start by creating this custom event class and documenting it:: use Symfony\Contracts\EventDispatcher\Event; /** - * The order.placed event is dispatched each time an order is created - * in the system. + * This event is dispatched each time an order + * is placed in the system. */ - class OrderPlacedEvent extends Event + final class OrderPlacedEvent extends Event { - public const NAME = 'order.placed'; - - public function __construct( - protected Order $order, - ) { - } + public function __construct(private Order $order) {} public function getOrder(): Order { @@ -288,15 +272,6 @@ order. Start by creating this custom event class and documenting it:: Each listener now has access to the order via the ``getOrder()`` method. -.. note:: - - If you don't need to pass any additional data to the event listeners, you - can also use the default - :class:`Symfony\\Contracts\\EventDispatcher\\Event` class. In such case, - you can document the event and its name in a generic ``StoreEvents`` class, - similar to the :class:`Symfony\\Component\\HttpKernel\\KernelEvents` - class. - Dispatch the Event .................. @@ -314,12 +289,38 @@ of the event to dispatch:: // creates the OrderPlacedEvent and dispatches it $event = new OrderPlacedEvent($order); - $dispatcher->dispatch($event, OrderPlacedEvent::NAME); + $dispatcher->dispatch($event); Notice that the special ``OrderPlacedEvent`` object is created and passed to -the ``dispatch()`` method. Now, any listener to the ``order.placed`` +the ``dispatch()`` method. Now, any listener to the ``OrderPlacedEvent::class`` event will receive the ``OrderPlacedEvent``. +.. note:: + + If you don't need to pass any additional data to the event listeners, you + can also use the default + :class:`Symfony\\Contracts\\EventDispatcher\\Event` class. In such case, + you can document the event and its name in a generic ``StoreEvents`` class, + similar to the :class:`Symfony\\Component\\HttpKernel\\KernelEvents` + class:: + + namespace App\Event; + + class StoreEvents { + + /** + * @Event("Symfony\Contracts\EventDispatcher\Event") + */ + public const ORDER_PLACED = 'order.placed'; + } + + And use the :class:`Symfony\\Contracts\\EventDispatcher\\Event` class to + dispatch the event:: + + use Symfony\Contracts\EventDispatcher\Event; + + $this->eventDispatcher->dispatch(new Event(), StoreEvents::ORDER_PLACED); + .. _event_dispatcher-using-event-subscribers: Using Event Subscribers @@ -336,7 +337,7 @@ events it should subscribe to. It implements the interface, which requires a single static method called :method:`Symfony\\Component\\EventDispatcher\\EventSubscriberInterface::getSubscribedEvents`. Take the following example of a subscriber that subscribes to the -``kernel.response`` and ``order.placed`` events:: +``kernel.response`` and ``OrderPlacedEvent::class`` events:: namespace Acme\Store\Event; @@ -354,7 +355,7 @@ Take the following example of a subscriber that subscribes to the ['onKernelResponsePre', 10], ['onKernelResponsePost', -10], ], - OrderPlacedEvent::NAME => 'onStoreOrder', + OrderPlacedEvent::class => 'onPlacedOrder', ]; } @@ -368,8 +369,9 @@ Take the following example of a subscriber that subscribes to the // ... } - public function onStoreOrder(OrderPlacedEvent $event): void + public function onPlacedOrder(OrderPlacedEvent $event): void { + $order = $event->getOrder(); // ... } } @@ -413,14 +415,14 @@ inside a listener via the use Acme\Store\Event\OrderPlacedEvent; - public function onStoreOrder(OrderPlacedEvent $event): void + public function onPlacedOrder(OrderPlacedEvent $event): void { // ... $event->stopPropagation(); } -Now, any listeners to ``order.placed`` that have not yet been called will +Now, any listeners to ``OrderPlacedEvent::class`` that have not yet been called will *not* be called. It is possible to detect if an event was stopped by using the @@ -474,12 +476,7 @@ with some other dispatchers: Learn More ---------- -.. toctree:: - :maxdepth: 1 - :glob: - - event_dispatcher - +* :doc:`/components/event_dispatcher/generic_event` * :ref:`The kernel.event_listener tag ` * :ref:`The kernel.event_subscriber tag ` diff --git a/components/event_dispatcher/generic_event.rst b/components/event_dispatcher/generic_event.rst index d0d2673db09..41d0a9d66a4 100644 --- a/components/event_dispatcher/generic_event.rst +++ b/components/event_dispatcher/generic_event.rst @@ -99,4 +99,3 @@ Filtering data:: $event['data'] = strtolower($event['data']); } } - diff --git a/components/expression_language.rst b/components/expression_language.rst index 1feae4bd46b..b0dd10b0f42 100644 --- a/components/expression_language.rst +++ b/components/expression_language.rst @@ -14,8 +14,6 @@ Installation .. include:: /components/require_autoload.rst.inc -How can the Expression Engine Help Me? - .. _how-can-the-expression-engine-help-me: How can the Expression Language Help Me? @@ -82,15 +80,58 @@ The main class of the component is Null Coalescing Operator ........................ -This is the same as the PHP `null-coalescing operator`_, which combines -the ternary operator and ``isset()``. It returns the left hand-side if it exists -and it's not ``null``; otherwise it returns the right hand-side. Note that you -can chain multiple coalescing operators. +.. note:: + + This content has been moved to the :ref:`null coalescing operator ` + section of ExpressionLanguage syntax reference page. + +Parsing and Linting Expressions +............................... + +The ExpressionLanguage component provides a way to parse and lint expressions. +The :method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::parse` +method returns a :class:`Symfony\\Component\\ExpressionLanguage\\ParsedExpression` +instance that can be used to inspect and manipulate the expression. The +:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::lint`, on the +other hand, throws a :class:`Symfony\\Component\\ExpressionLanguage\\SyntaxError` +if the expression is not valid:: + + use Symfony\Component\ExpressionLanguage\ExpressionLanguage; + + $expressionLanguage = new ExpressionLanguage(); + + var_dump($expressionLanguage->parse('1 + 2', [])); + // displays the AST nodes of the expression which can be + // inspected and manipulated + + $expressionLanguage->lint('1 + 2', []); // doesn't throw anything + + $expressionLanguage->lint('1 + a', []); + // throws a SyntaxError exception: + // "Variable "a" is not valid around position 5 for expression `1 + a`." -* ``foo ?? 'no'`` -* ``foo.baz ?? 'no'`` -* ``foo[3] ?? 'no'`` -* ``foo.baz ?? foo['baz'] ?? 'no'`` +The behavior of these methods can be configured with some flags defined in the +:class:`Symfony\\Component\\ExpressionLanguage\\Parser` class: + +* ``IGNORE_UNKNOWN_VARIABLES``: don't throw an exception if a variable is not + defined in the expression; +* ``IGNORE_UNKNOWN_FUNCTIONS``: don't throw an exception if a function is not + defined in the expression. + +This is how you can use these flags:: + + use Symfony\Component\ExpressionLanguage\ExpressionLanguage; + use Symfony\Component\ExpressionLanguage\Parser; + + $expressionLanguage = new ExpressionLanguage(); + + // 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 -------------------- @@ -125,13 +166,6 @@ expressions (e.g. the request, the current user, etc.): * :doc:`Variables available in service container expressions `; * :ref:`Variables available in routing expressions `. -.. caution:: - - When using variables in expressions, avoid passing untrusted data into the - array of variables. If you can't avoid that, sanitize non-alphanumeric - characters in untrusted data to prevent malicious users from injecting - control characters and altering the expression. - .. _expression-language-caching: Caching @@ -372,7 +406,7 @@ or by using the second argument of the constructor:: class ExpressionLanguage extends BaseExpressionLanguage { - public function __construct(CacheItemPoolInterface $cache = null, array $providers = []) + public function __construct(?CacheItemPoolInterface $cache = null, array $providers = []) { // prepends the default provider to let users override it array_unshift($providers, new StringExpressionLanguageProvider()); diff --git a/components/filesystem.rst b/components/filesystem.rst index 8cdc2a34884..dabf3f81872 100644 --- a/components/filesystem.rst +++ b/components/filesystem.rst @@ -313,6 +313,22 @@ contents at the end of some file:: If either the file or its containing directory doesn't exist, this method 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 +when passing the path to a directory instead of a file:: + + $contents = $filesystem->readFile('/some/path/to/file.txt'); + +The ``$contents`` variable now stores all the contents of the ``file.txt`` file. + Path Manipulation Utilities --------------------------- diff --git a/components/finder.rst b/components/finder.rst index 516db7cde4e..cecc597ac64 100644 --- a/components/finder.rst +++ b/components/finder.rst @@ -41,7 +41,7 @@ The ``$file`` variable is an instance of :class:`Symfony\\Component\\Finder\\SplFileInfo` which extends PHP's own :phpclass:`SplFileInfo` to provide methods to work with relative paths. -.. caution:: +.. warning:: The ``Finder`` object doesn't reset its internal state automatically. This means that you need to create a new instance if you do not want @@ -127,6 +127,30 @@ If you want to follow `symbolic links`_, use the ``followLinks()`` method:: $finder->files()->followLinks(); +Note that this method follows links but it doesn't resolve them. Consider +the following structure of files of directories: + +.. code-block:: text + + ├── folder1/ + │ ├──file1.txt + │ ├── file2link (symbolic link to folder2/file2.txt file) + │ └── folder3link (symbolic link to folder3/ directory) + ├── folder2/ + │ └── file2.txt + └── folder3/ + └── file3.txt + +If you try to find all files in ``folder1/`` via ``$finder->files()->in('/path/to/folder1/')`` +you'll get the following results: + +* When **not** using the ``followLinks()`` method: ``file1.txt`` and ``file2link`` + (this link is not resolved). The ``folder3link`` doesn't appear in the results + because it's not followed or resolved; +* When using the ``followLinks()`` method: ``file1.txt``, ``file2link`` (this link + is still not resolved) and ``folder3/file3.txt`` (this file appears in the results + because the ``folder1/folder3link`` link was followed). + Version Control Files ~~~~~~~~~~~~~~~~~~~~~ diff --git a/components/form.rst b/components/form.rst index 42a5a00bbae..5e09f38812f 100644 --- a/components/form.rst +++ b/components/form.rst @@ -640,7 +640,7 @@ method: // ... -.. caution:: +.. warning:: The form's ``createView()`` method should be called *after* ``handleRequest()`` is called. Otherwise, when using :doc:`form events `, changes done @@ -749,10 +749,11 @@ method to access the list of errors. It returns a // "firstName" field $errors = $form['firstName']->getErrors(); - // a FormErrorIterator instance in a flattened structure + // a FormErrorIterator instance including child forms in a flattened structure + // use getOrigin() to determine the form causing the error $errors = $form->getErrors(true); - // a FormErrorIterator instance representing the form tree structure + // a FormErrorIterator instance including child forms without flattening the output structure $errors = $form->getErrors(true, false); Clearing Form Errors diff --git a/components/http_foundation.rst b/components/http_foundation.rst index 4e599dfacad..21e9bbfb13e 100644 --- a/components/http_foundation.rst +++ b/components/http_foundation.rst @@ -362,6 +362,24 @@ analysis purposes. Use the ``anonymize()`` method from the $anonymousIpv6 = IpUtils::anonymize($ipv6); // $anonymousIpv6 = '2a01:198:603:10::' +Check If an IP Belongs to a CIDR Subnet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to know if an IP address is included in a CIDR subnet, you can use +the ``checkIp()`` method from :class:`Symfony\\Component\\HttpFoundation\\IpUtils`:: + + use Symfony\Component\HttpFoundation\IpUtils; + + $ipv4 = '192.168.1.56'; + $CIDRv4 = '192.168.1.0/16'; + $isIpInCIDRv4 = IpUtils::checkIp($ipv4, $CIDRv4); + // $isIpInCIDRv4 = true + + $ipv6 = '2001:db8:abcd:1234::1'; + $CIDRv6 = '2001:db8:abcd::/48'; + $isIpInCIDRv6 = IpUtils::checkIp($ipv6, $CIDRv6); + // $isIpInCIDRv6 = true + Check if an IP Belongs to a Private Subnet ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -379,6 +397,54 @@ use the ``isPrivateIp()`` method from the $isPrivate = IpUtils::isPrivateIp($ipv6); // $isPrivate = false +Matching a Request Against a Set of Rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The HttpFoundation component provides some matcher classes that allow you to +check if a given request meets certain conditions (e.g. it comes from some IP +address, it uses a certain HTTP method, etc.): + +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\AttributesRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\ExpressionRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\HeaderRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\HostRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\IpsRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\IsJsonRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\MethodRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\PathRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\PortRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\QueryParameterRequestMatcher` +* :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher\\SchemeRequestMatcher` + +You can use them individually or combine them using the +:class:`Symfony\\Component\\HttpFoundation\\ChainRequestMatcher` class:: + + use Symfony\Component\HttpFoundation\ChainRequestMatcher; + use Symfony\Component\HttpFoundation\RequestMatcher\HostRequestMatcher; + use Symfony\Component\HttpFoundation\RequestMatcher\PathRequestMatcher; + use Symfony\Component\HttpFoundation\RequestMatcher\SchemeRequestMatcher; + + // use only one criteria to match the request + $schemeMatcher = new SchemeRequestMatcher('https'); + if ($schemeMatcher->matches($request)) { + // ... + } + + // use a set of criteria to match the request + $matcher = new ChainRequestMatcher([ + new HostRequestMatcher('example.com'), + new PathRequestMatcher('/admin'), + ]); + + if ($matcher->matches($request)) { + // ... + } + +.. versionadded:: 7.1 + + The ``HeaderRequestMatcher`` and ``QueryParameterRequestMatcher`` were + introduced in Symfony 7.1. + Accessing other Data ~~~~~~~~~~~~~~~~~~~~ @@ -793,6 +859,23 @@ It is possible to delete the file after the response is sent with the :method:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse::deleteFileAfterSend` method. Please note that this will not work when the ``X-Sendfile`` header is set. +Alternatively, ``BinaryFileResponse`` supports instances of ``\SplTempFileObject``. +This is useful when you want to serve a file that has been created in memory +and that will be automatically deleted after the response is sent:: + + use Symfony\Component\HttpFoundation\BinaryFileResponse; + + $file = new \SplTempFileObject(); + $file->fwrite('Hello World'); + $file->rewind(); + + $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`` @@ -860,6 +943,16 @@ The ``JsonResponse`` class sets the ``Content-Type`` header to Only methods that respond to GET requests are vulnerable to XSSI 'JSON Hijacking'. Methods responding to POST requests only remain unaffected. +.. warning:: + + The ``JsonResponse`` constructor exhibits non-standard JSON encoding behavior + and will treat ``null`` as an empty object if passed as a constructor argument, + despite null being a `valid JSON top-level value`_. + + This behavior cannot be changed without backwards-compatibility concerns, but + it's possible to call ``setData`` and pass the value there to opt-out of the + behavior. + JSONP Callback ~~~~~~~~~~~~~~ @@ -949,9 +1042,10 @@ Learn More /session /http_cache/* -.. _nginx: https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/ +.. _nginx: https://mattbrictson.com/blog/accelerated-rails-downloads .. _Apache: https://tn123.org/mod_xsendfile/ .. _`JSON Hijacking`: https://haacked.com/archive/2009/06/25/json-hijacking.aspx/ +.. _`valid JSON top-level value`: https://www.json.org/json-en.html .. _OWASP guidelines: https://cheatsheetseries.owasp.org/cheatsheets/AJAX_Security_Cheat_Sheet.html#always-return-json-with-an-object-on-the-outside .. _RFC 8674: https://tools.ietf.org/html/rfc8674 .. _Doctrine Batch processing: https://www.doctrine-project.org/projects/doctrine-orm/en/2.14/reference/batch-processing.html#iterating-results diff --git a/components/http_kernel.rst b/components/http_kernel.rst index fbc59a85a50..02791b370bc 100644 --- a/components/http_kernel.rst +++ b/components/http_kernel.rst @@ -3,8 +3,8 @@ The HttpKernel Component The HttpKernel component provides a structured process for converting a ``Request`` into a ``Response`` by making use of the EventDispatcher - component. It's flexible enough to create a full-stack framework (Symfony), - a micro-framework (Silex) or an advanced CMS (Drupal). + component. It's flexible enough to create a full-stack framework (Symfony) + or an advanced CMS (Drupal). Installation ------------ @@ -15,8 +15,10 @@ Installation .. include:: /components/require_autoload.rst.inc -The Workflow of a Request -------------------------- +.. _the-workflow-of-a-request: + +The Request-Response Lifecycle +------------------------------ .. seealso:: @@ -26,11 +28,10 @@ The Workflow of a Request :doc:`/event_dispatcher` articles to learn about how to use it to create controllers and define events in Symfony applications. - Every HTTP web interaction begins with a request and ends with a response. Your job as a developer is to create PHP code that reads the request information (e.g. the URL) and creates and returns a response (e.g. an HTML page or JSON string). -This is a simplified overview of the request workflow in Symfony applications: +This is a simplified overview of the request-response lifecycle in Symfony applications: #. The **user** asks for a **resource** in a **browser**; #. The **browser** sends a **request** to the **server**; @@ -67,7 +68,7 @@ that system:: Internally, :method:`HttpKernel::handle() ` - the concrete implementation of :method:`HttpKernelInterface::handle() ` - -defines a workflow that starts with a :class:`Symfony\\Component\\HttpFoundation\\Request` +defines a lifecycle that starts with a :class:`Symfony\\Component\\HttpFoundation\\Request` and ends with a :class:`Symfony\\Component\\HttpFoundation\\Response`. .. raw:: html @@ -76,7 +77,7 @@ and ends with a :class:`Symfony\\Component\\HttpFoundation\\Response`. alt="A flow diagram showing all HTTP Kernel events in the Request-Response lifecycle. Each event is numbered 1 to 8 and described in detail in the following subsections." > -The exact details of this workflow are the key to understanding how the kernel +The exact details of this lifecycle are the key to understanding how the kernel (and the Symfony Framework or any other library that uses the kernel) works. HttpKernel: Driven by Events @@ -397,7 +398,7 @@ return a ``Response``. There is a default listener inside the Symfony Framework for the ``kernel.view`` event. If your controller action returns an array, and you apply the - :ref:`#[Template()] attribute ` to that + :ref:`#[Template] attribute ` to that controller action, then this listener renders a template, passes the array you returned from your controller to that template, and creates a ``Response`` containing the returned content from that template. @@ -470,7 +471,7 @@ you will trigger the ``kernel.terminate`` event where you can perform certain actions that you may have delayed in order to return the response as quickly as possible to the client (e.g. sending emails). -.. caution:: +.. warning:: Internally, the HttpKernel makes use of the :phpfunction:`fastcgi_finish_request` PHP function. This means that at the moment, only the `PHP FPM`_ server @@ -486,8 +487,8 @@ as possible to the client (e.g. sending emails). .. _component-http-kernel-kernel-exception: -Handling Exceptions: the ``kernel.exception`` Event -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +9) Handling Exceptions: the ``kernel.exception`` Event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Typical Purposes**: Handle some type of exception and create an appropriate ``Response`` to return for the exception @@ -716,6 +717,14 @@ look like this:: // ... } +.. note:: + + The default value of the ``_format`` request attribute is ``html``. If your + sub request returns a different format (e.g. ``json``) you can set it by + defining the ``_format`` attribute explicitly on the request:: + + $request->attributes->set('_format', 'json'); + .. _http-kernel-resource-locator: Locating Resources diff --git a/components/intl.rst b/components/intl.rst index bbd088c830e..ba3cbdcb959 100644 --- a/components/intl.rst +++ b/components/intl.rst @@ -28,7 +28,6 @@ This component provides the following ICU data: * `Locales`_ * `Currencies`_ * `Timezones`_ -* `Emoji Transliteration`_ Language and Script Names ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -386,56 +385,16 @@ to catching the exception, you can also check if a given timezone ID is valid:: Emoji Transliteration ~~~~~~~~~~~~~~~~~~~~~ -The ``EmojiTransliterator`` class provides a utility to translate emojis into -their textual representation in all languages based on the `Unicode CLDR dataset`_:: +Symfony provides utilities to translate emojis into their textual representation +in all languages. Read the documentation about :ref:`emoji transliteration ` +to learn more about this feature. - use Symfony\Component\Intl\Transliterator\EmojiTransliterator; - - // describe emojis in English - $transliterator = EmojiTransliterator::create('en'); - $transliterator->transliterate('Menus with 🍕 or 🍝'); - // => 'Menus with pizza or spaghetti' - - // describe emojis in Ukrainian - $transliterator = EmojiTransliterator::create('uk'); - $transliterator->transliterate('Menus with 🍕 or 🍝'); - // => 'Menus with піца or спагеті' - -The ``EmojiTransliterator`` class also provides two extra catalogues: ``github`` -and ``slack`` that converts any emojis to the corresponding short code in those -platforms:: - - use Symfony\Component\Intl\Transliterator\EmojiTransliterator; - - // describe emojis in Slack short code - $transliterator = EmojiTransliterator::create('slack'); - $transliterator->transliterate('Menus with 🥗 or 🧆'); - // => 'Menus with :green_salad: or :falafel:' - - // describe emojis in Github short code - $transliterator = EmojiTransliterator::create('github'); - $transliterator->transliterate('Menus with 🥗 or 🧆'); - // => 'Menus with :green_salad: or :falafel:' - -Furthermore the ``EmojiTransliterator`` provides a special ``strip`` locale -that removes all the emojis from a string:: - - use Symfony\Component\Intl\Transliterator\EmojiTransliterator; - - $transliterator = EmojiTransliterator::create('strip'); - $transliterator->transliterate('🎉Hey!🥳 🎁Happy Birthday!🎁'); - // => 'Hey! Happy Birthday!' - -.. tip:: - - Combine this emoji transliterator with the :ref:`Symfony String slugger ` - to improve the slugs of contents that include emojis (e.g. for URLs). +Disk Space +---------- -The data needed to store the transliteration of all emojis (~5,000) into all -languages take a considerable disk space. If you need to save disk space (e.g. -because you deploy to some service with tight size constraints), run this command -(e.g. as an automated script after ``composer install``) to compress the internal -Symfony emoji data files using the PHP ``zlib`` extension: +If you need to save disk space (e.g. because you deploy to some service with tight size +constraints), run this command (e.g. as an automated script after ``composer install``) to compress the +internal Symfony Intl data files using the PHP ``zlib`` extension: .. code-block:: terminal @@ -464,4 +423,3 @@ Learn more .. _`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 .. _`ISO 639-2 alpha-3 (2T)`: https://en.wikipedia.org/wiki/ISO_639-2 -.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr diff --git a/components/ldap.rst b/components/ldap.rst index 89094fad0b7..f5a142ced9f 100644 --- a/components/ldap.rst +++ b/components/ldap.rst @@ -70,7 +70,7 @@ distinguished name (DN) and the password of a user:: $ldap->bind($dn, $password); -.. caution:: +.. danger:: When the LDAP server allows unauthenticated binds, a blank password will always be valid. diff --git a/components/lock.rst b/components/lock.rst index e600d68ca59..b0240019e8d 100644 --- a/components/lock.rst +++ b/components/lock.rst @@ -105,12 +105,10 @@ to handle the rest of the job:: use App\Lock\RefreshTaxonomy; use Symfony\Component\Lock\Key; - use Symfony\Component\Lock\Lock; $key = new Key('article.'.$article->getId()); - $lock = new Lock( + $lock = $factory->createLockFromKey( $key, - $this->store, 300, // ttl false // autoRelease ); @@ -121,7 +119,7 @@ to handle the rest of the job:: .. note:: Don't forget to set the ``autoRelease`` argument to ``false`` in the - ``Lock`` constructor to avoid releasing the lock when the destructor is + ``Lock`` instantiation to avoid releasing the lock when the destructor is called. Not all stores are compatible with serialization and cross-process locking: for @@ -361,7 +359,7 @@ lose the lock it acquired automatically:: throw new \Exception('Process failed'); } -.. caution:: +.. warning:: A common pitfall might be to use the ``isAcquired()`` method to check if a lock has already been acquired by any process. As you can see in this example @@ -388,20 +386,20 @@ Locks are created and managed in ``Stores``, which are classes that implement The component includes the following built-in store types: -========================================================== ====== ======== ======== ======= -Store Scope Blocking Expiring Sharing -========================================================== ====== ======== ======== ======= -:ref:`FlockStore ` local yes no yes -:ref:`MemcachedStore ` remote no yes no -:ref:`MongoDbStore ` remote no yes no -:ref:`PdoStore ` remote no yes no -:ref:`DoctrineDbalStore ` remote no yes no -:ref:`PostgreSqlStore ` remote yes no yes -:ref:`DoctrineDbalPostgreSqlStore ` remote yes no yes -:ref:`RedisStore ` remote no yes yes -:ref:`SemaphoreStore ` local yes no no -:ref:`ZookeeperStore ` remote no no no -========================================================== ====== ======== ======== ======= +========================================================== ====== ======== ======== ======= ============= +Store Scope Blocking Expiring Sharing Serialization +========================================================== ====== ======== ======== ======= ============= +:ref:`FlockStore ` local yes no yes no +:ref:`MemcachedStore ` remote no yes no yes +:ref:`MongoDbStore ` remote no yes no yes +:ref:`PdoStore ` remote no yes no yes +:ref:`DoctrineDbalStore ` remote no yes no yes +:ref:`PostgreSqlStore ` remote yes no yes no +:ref:`DoctrineDbalPostgreSqlStore ` remote yes no yes no +:ref:`RedisStore ` remote no yes yes yes +:ref:`SemaphoreStore ` local yes no no no +:ref:`ZookeeperStore ` remote no no no no +========================================================== ====== ======== ======== ======= ============= .. tip:: @@ -424,7 +422,7 @@ when the PHP process ends):: // if none is given, sys_get_temp_dir() is used internally. $store = new FlockStore('/var/stores'); -.. caution:: +.. warning:: Beware that some file systems (such as some types of NFS) do not support locking. In those cases, it's better to use a directory on a local disk @@ -665,7 +663,7 @@ the stores:: $store = new CombinedStore($stores, new UnanimousStrategy()); -.. caution:: +.. warning:: In order to get high availability when using the ``ConsensusStrategy``, the minimum cluster size must be three servers. This allows the cluster to keep @@ -717,7 +715,7 @@ the ``Lock``. Every concurrent process must store the ``Lock`` on the same server. Otherwise two different machines may allow two different processes to acquire the same ``Lock``. -.. caution:: +.. warning:: To guarantee that the same server will always be safe, do not use Memcached behind a LoadBalancer, a cluster or round-robin DNS. Even if the main server @@ -756,15 +754,15 @@ Using the above methods, a robust code would be:: $lock->refresh(); } - // Perform the task whose duration MUST be less than 5 minutes + // Perform the task whose duration MUST be less than 5 seconds } -.. caution:: +.. warning:: Choose wisely the lifetime of the ``Lock`` and check whether its remaining time to live is enough to perform the task. -.. caution:: +.. warning:: Storing a ``Lock`` usually takes a few milliseconds, but network conditions may increase that time a lot (up to a few seconds). Take that into account @@ -773,7 +771,7 @@ Using the above methods, a robust code would be:: By design, locks are stored on servers with a defined lifetime. If the date or time of the machine changes, a lock could be released sooner than expected. -.. caution:: +.. warning:: To guarantee that date won't change, the NTP service should be disabled and the date should be updated when the service is stopped. @@ -795,7 +793,7 @@ deployments. Some file systems (such as some types of NFS) do not support locking. -.. caution:: +.. warning:: All concurrent processes must use the same physical file system by running on the same machine and using the same absolute path to the lock directory. @@ -824,7 +822,7 @@ and may disappear by mistake at any time. If the Memcached service or the machine hosting it restarts, every lock would be lost without notifying the running processes. -.. caution:: +.. warning:: To avoid that someone else acquires a lock after a restart, it's recommended to delay service start and wait at least as long as the longest lock TTL. @@ -832,7 +830,7 @@ be lost without notifying the running processes. By default Memcached uses a LRU mechanism to remove old entries when the service needs space to add new items. -.. caution:: +.. warning:: The number of items stored in Memcached must be under control. If it's not possible, LRU should be disabled and Lock should be stored in a dedicated @@ -850,7 +848,7 @@ method uses the Memcached's ``flush()`` method which purges and removes everythi MongoDbStore ~~~~~~~~~~~~ -.. caution:: +.. warning:: The locked resource name is indexed in the ``_id`` field of the lock collection. Beware that an indexed field's value in MongoDB can be @@ -876,7 +874,7 @@ about `Expire Data from Collections by Setting TTL`_ in MongoDB. recommended to set constructor option ``gcProbability`` to ``0.0`` to disable this behavior if you have manually dealt with TTL index creation. -.. caution:: +.. warning:: This store relies on all PHP application and database nodes to have synchronized clocks for lock expiry to occur at the correct time. To ensure @@ -893,12 +891,12 @@ PdoStore The PdoStore relies on the `ACID`_ properties of the SQL engine. -.. caution:: +.. warning:: In a cluster configured with multiple primaries, ensure writes are synchronously propagated to every node, or always use the same node. -.. caution:: +.. warning:: Some SQL engines like MySQL allow to disable the unique constraint check. Ensure that this is not the case ``SET unique_checks=1;``. @@ -907,7 +905,7 @@ In order to purge old locks, this store uses a current datetime to define an expiration date reference. This mechanism relies on all server nodes to have synchronized clocks. -.. caution:: +.. warning:: To ensure locks don't expire prematurely; the TTLs should be set with enough extra time to account for any clock drift between nodes. @@ -936,7 +934,7 @@ and may disappear by mistake at any time. If the Redis service or the machine hosting it restarts, every locks would be lost without notifying the running processes. -.. caution:: +.. warning:: To avoid that someone else acquires a lock after a restart, it's recommended to delay service start and wait at least as long as the longest lock TTL. @@ -964,7 +962,7 @@ The ``CombinedStore`` will be, at best, as reliable as the least reliable of all managed stores. As soon as one managed store returns erroneous information, the ``CombinedStore`` won't be reliable. -.. caution:: +.. warning:: All concurrent processes must use the same configuration, with the same amount of managed stored and the same endpoint. @@ -982,13 +980,13 @@ must run on the same machine, virtual machine or container. Be careful when updating a Kubernetes or Swarm service because for a short period of time, there can be two running containers in parallel. -.. caution:: +.. warning:: All concurrent processes must use the same machine. Before starting a concurrent process on a new machine, check that other processes are stopped on the old one. -.. caution:: +.. warning:: When running on systemd with non-system user and option ``RemoveIPC=yes`` (default value), locks are deleted by systemd when that user logs out. diff --git a/components/messenger.rst b/components/messenger.rst index 7f430b55c90..8d6652fb160 100644 --- a/components/messenger.rst +++ b/components/messenger.rst @@ -162,6 +162,10 @@ Here are some important envelope stamps that are shipped with the Symfony Messen to configure the validation groups used when the validation middleware is enabled. * :class:`Symfony\\Component\\Messenger\\Stamp\\ErrorDetailsStamp`, an internal stamp when a message fails due to an exception in the handler. +* :class:`Symfony\\Component\\Scheduler\\Messenger\\ScheduledStamp`, + a stamp that marks the message as produced by a scheduler. This helps + differentiate it from messages created "manually". You can learn more about it + in the :doc:`Scheduler documentation `. .. note:: diff --git a/components/options_resolver.rst b/components/options_resolver.rst index f70bc20a412..ff25f9e0fc4 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -485,7 +485,7 @@ these options, you can return the desired default value:: } } -.. caution:: +.. warning:: The argument of the callable must be type hinted as ``Options``. Otherwise, the callable itself is considered as the default value of the option. @@ -699,7 +699,7 @@ to the closure to access to them:: } } -.. caution:: +.. warning:: The arguments of the closure must be type hinted as ``OptionsResolver`` and ``Options`` respectively. Otherwise, the closure itself is considered as the @@ -811,7 +811,7 @@ method:: When using an option deprecated by you in your own library, you can pass ``false`` as the second argument of the - :method:`Symfony\\Component\\OptionsResolver\\Options::offsetGet` method + :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::offsetGet` method to not trigger the deprecation warning. .. note:: diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index ba37bc0ecda..5ce4c003a11 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -253,7 +253,7 @@ deprecations but: * forget to mark appropriate tests with the ``@group legacy`` annotations. By using ``SYMFONY_DEPRECATIONS_HELPER=max[self]=0``, deprecations that are -triggered outside the ``vendors`` directory will be accounted for separately, +triggered outside the ``vendor/`` directory will be accounted for separately, while deprecations triggered from a library inside it will not (unless you reach 999999 of these), giving you the best of both worlds. @@ -621,7 +621,7 @@ test:: And that's all! -.. caution:: +.. warning:: Time-based function mocking follows the `PHP namespace resolutions rules`_ so "fully qualified function calls" (e.g ``\time()``) cannot be mocked. diff --git a/components/process.rst b/components/process.rst index 080ddff9d6a..f6c8837d2c3 100644 --- a/components/process.rst +++ b/components/process.rst @@ -10,7 +10,6 @@ Installation $ composer require symfony/process - .. include:: /components/require_autoload.rst.inc Usage @@ -109,6 +108,12 @@ You can configure the options passed to the ``other_options`` argument of // this option allows a subprocess to continue running after the main script exited $process->setOptions(['create_new_console' => true]); +.. warning:: + + Most of the options defined by ``proc_open()`` (such as ``create_new_console`` + and ``suppress_errors``) are only supported on Windows operating systems. + Check out the `PHP documentation for proc_open()`_ before using them. + Using Features From the OS Shell -------------------------------- @@ -506,6 +511,20 @@ When running a program asynchronously, you can send it POSIX signals with the // will send a SIGKILL to the process $process->signal(SIGKILL); +You can make the process ignore signals by using the +:method:`Symfony\\Component\\Process\\Process::setIgnoredSignals` +method. The given signals won't be propagated to the child process:: + + use Symfony\Component\Process\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 ----------- @@ -533,7 +552,7 @@ Use :method:`Symfony\\Component\\Process\\Process::disableOutput` and $process->disableOutput(); $process->run(); -.. caution:: +.. warning:: You cannot enable or disable the output while the process is running. @@ -593,3 +612,4 @@ whether `TTY`_ is supported on the current operating system:: .. _`PHP streams`: https://www.php.net/manual/en/book.stream.php .. _`output_buffering`: https://www.php.net/manual/en/outcontrol.configuration.php .. _`TTY`: https://en.wikipedia.org/wiki/Tty_(unix) +.. _`PHP documentation for proc_open()`: https://www.php.net/manual/en/function.proc-open.php diff --git a/components/property_access.rst b/components/property_access.rst index 052ed38e767..f608640fa9b 100644 --- a/components/property_access.rst +++ b/components/property_access.rst @@ -26,6 +26,8 @@ default configuration:: $propertyAccessor = PropertyAccess::createPropertyAccessor(); +.. _property-access-reading-arrays: + Reading from Arrays ------------------- @@ -112,7 +114,7 @@ To read from properties, use the "dot" notation:: var_dump($propertyAccessor->getValue($person, 'children[0].firstName')); // 'Bar' -.. caution:: +.. warning:: Accessing public properties is the last option used by ``PropertyAccessor``. It tries to access the value using the below methods first before using @@ -249,16 +251,21 @@ The ``getValue()`` method can also use the magic ``__get()`` method:: { return $this->children[$id]; } + + public function __isset($id): bool + { + return isset($this->children[$id]); + } } $person = new Person(); var_dump($propertyAccessor->getValue($person, 'Wouter')); // [...] -.. note:: +.. warning:: - The ``__get()`` method support is enabled by default. - See `Enable other Features`_ if you want to disable it. + When implementing the magic ``__get()`` method, you also need to implement + ``__isset()``. .. _components-property-access-magic-call: @@ -296,7 +303,7 @@ enable this feature by using :class:`Symfony\\Component\\PropertyAccess\\Propert var_dump($propertyAccessor->getValue($person, 'wouter')); // [...] -.. caution:: +.. warning:: The ``__call()`` feature is disabled by default, you can enable it by calling :method:`Symfony\\Component\\PropertyAccess\\PropertyAccessorBuilder::enableMagicCall` diff --git a/components/property_info.rst b/components/property_info.rst index 892cd5345a3..2e1ee42dd3f 100644 --- a/components/property_info.rst +++ b/components/property_info.rst @@ -478,9 +478,9 @@ SerializerExtractor This extractor depends on the `symfony/serializer`_ library. -Using :ref:`groups metadata ` -from the :doc:`Serializer component `, -the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor` +Using :ref:`groups metadata ` from the +:doc:`Serializer component `, the +:class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor` provides list information. This extractor is *not* registered automatically with the ``property_info`` service in the Symfony Framework:: diff --git a/components/runtime.rst b/components/runtime.rst index 94dcb7ae9e5..4eb75de2a75 100644 --- a/components/runtime.rst +++ b/components/runtime.rst @@ -3,7 +3,7 @@ The Runtime Component The Runtime Component decouples the bootstrapping logic from any global state to make sure the application can run with runtimes like `PHP-PM`_, `ReactPHP`_, - `Swoole`_, etc. without any changes. + `Swoole`_, `FrankenPHP`_ etc. without any changes. Installation ------------ @@ -42,7 +42,7 @@ the component. This file runs the following logic: #. At last, the Runtime is used to run the application (i.e. calling ``$kernel->handle(Request::createFromGlobals())->send()``). -.. caution:: +.. warning:: If you use the Composer ``--no-plugins`` option, the ``autoload_runtime.php`` file won't be created. @@ -97,6 +97,23 @@ Use the ``APP_RUNTIME`` environment variable or by specifying the } } +If modifying the runtime class isn't enough, you can create your own runtime template: + +.. code-block:: json + + { + "require": { + "...": "..." + }, + "extra": { + "runtime": { + "autoload_template": "resources/runtime/autoload_runtime.template" + } + } + } + +Symfony provides a `runtime template file`_ that you can use to create your own. + Using the Runtime ----------------- @@ -136,7 +153,7 @@ The following arguments are supported by the ``SymfonyRuntime``: :class:`Symfony\\Component\\Console\\Application` An application for creating CLI applications. -:class:`Symfony\\Component\\Command\\Command` +:class:`Symfony\\Component\\Console\\Command\\Command` For creating one line command CLI applications (using ``Command::setCode()``). @@ -470,5 +487,7 @@ The end user will now be able to create front controller like:: .. _PHP-PM: https://github.com/php-pm/php-pm .. _Swoole: https://openswoole.com/ +.. _FrankenPHP: https://frankenphp.dev/ .. _ReactPHP: https://reactphp.org/ .. _`PSR-15`: https://www.php-fig.org/psr/psr-15/ +.. _`runtime template file`: https://github.com/symfony/symfony/blob/{version}/src/Symfony/Component/Runtime/Internal/autoload_runtime.template diff --git a/components/serializer.rst b/components/serializer.rst deleted file mode 100644 index 17dfeb988d8..00000000000 --- a/components/serializer.rst +++ /dev/null @@ -1,1877 +0,0 @@ -The Serializer Component -======================== - - The Serializer component is meant to be used to turn objects into a - specific format (XML, JSON, YAML, ...) and the other way around. - -In order to do so, the Serializer component follows the following schema. - -.. raw:: html - - - -When (de)serializing objects, the Serializer uses an array as the intermediary -between objects and serialized contents. Encoders will only deal with -turning specific **formats** into **arrays** and vice versa. The same way, -normalizers will deal with turning specific **objects** into **arrays** and -vice versa. The Serializer deals with calling the normalizers and encoders -when serializing objects or deserializing formats. - -Serialization is a complex topic. This component may not cover all your use -cases out of the box, but it can be useful for developing tools to -serialize and deserialize your objects. - -Installation ------------- - -.. code-block:: terminal - - $ composer require symfony/serializer - -.. include:: /components/require_autoload.rst.inc - -To use the ``ObjectNormalizer``, the :doc:`PropertyAccess component ` -must also be installed. - -Usage ------ - -.. seealso:: - - This article explains the philosophy of the Serializer and gets you familiar - with the concepts of normalizers and encoders. The code examples assume - that you use the Serializer as an independent component. If you are using - the Serializer in a Symfony application, read :doc:`/serializer` after you - finish this article. - -To use the Serializer component, set up the -:class:`Symfony\\Component\\Serializer\\Serializer` specifying which encoders -and normalizer are going to be available:: - - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\Encoder\XmlEncoder; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $encoders = [new XmlEncoder(), new JsonEncoder()]; - $normalizers = [new ObjectNormalizer()]; - - $serializer = new Serializer($normalizers, $encoders); - -The preferred normalizer is the -:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`, -but other normalizers are available. All the examples shown below use -the ``ObjectNormalizer``. - -Serializing an Object ---------------------- - -For the sake of this example, assume the following class already -exists in your project:: - - namespace App\Model; - - class Person - { - private int $age; - private string $name; - private bool $sportsperson; - private ?\DateTimeInterface $createdAt; - - // Getters - public function getAge(): int - { - return $this->age; - } - - public function getName(): string - { - return $this->name; - } - - public function getCreatedAt(): ?\DateTimeInterface - { - return $this->createdAt; - } - - // Issers - public function isSportsperson(): bool - { - return $this->sportsperson; - } - - // Setters - public function setAge(int $age): void - { - $this->age = $age; - } - - public function setName(string $name): void - { - $this->name = $name; - } - - public function setSportsperson(bool $sportsperson): void - { - $this->sportsperson = $sportsperson; - } - - public function setCreatedAt(\DateTimeInterface $createdAt = null): void - { - $this->createdAt = $createdAt; - } - } - -Now, if you want to serialize this object into JSON, you only need to -use the Serializer service created before:: - - use App\Model\Person; - - $person = new Person(); - $person->setName('foo'); - $person->setAge(99); - $person->setSportsperson(false); - - $jsonContent = $serializer->serialize($person, 'json'); - - // $jsonContent contains {"name":"foo","age":99,"sportsperson":false,"createdAt":null} - - echo $jsonContent; // or return it in a Response - -The first parameter of the :method:`Symfony\\Component\\Serializer\\Serializer::serialize` -is the object to be serialized and the second is used to choose the proper encoder, -in this case :class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder`. - -Deserializing an Object ------------------------ - -You'll now learn how to do the exact opposite. This time, the information -of the ``Person`` class would be encoded in XML format:: - - use App\Model\Person; - - $data = << - foo - 99 - false - - EOF; - - $person = $serializer->deserialize($data, Person::class, 'xml'); - -In this case, :method:`Symfony\\Component\\Serializer\\Serializer::deserialize` -needs three parameters: - -#. The information to be decoded -#. The name of the class this information will be decoded to -#. The encoder used to convert that information into an array - -By default, additional attributes that are not mapped to the denormalized object -will be ignored by the Serializer component. If you prefer to throw an exception -when this happens, set the ``AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES`` context option to -``false`` and provide an object that implements ``ClassMetadataFactoryInterface`` -when constructing the normalizer:: - - use App\Model\Person; - - $data = << - foo - 99 - Paris - - EOF; - - // $loader is any of the valid loaders explained later in this article - $classMetadataFactory = new ClassMetadataFactory($loader); - $normalizer = new ObjectNormalizer($classMetadataFactory); - $serializer = new Serializer([$normalizer]); - - // this will throw a Symfony\Component\Serializer\Exception\ExtraAttributesException - // because "city" is not an attribute of the Person class - $person = $serializer->deserialize($data, Person::class, 'xml', [ - AbstractNormalizer::ALLOW_EXTRA_ATTRIBUTES => false, - ]); - -Deserializing in an Existing Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The serializer can also be used to update an existing object:: - - // ... - $person = new Person(); - $person->setName('bar'); - $person->setAge(99); - $person->setSportsperson(true); - - $data = << - foo - 69 - - EOF; - - $serializer->deserialize($data, Person::class, 'xml', [AbstractNormalizer::OBJECT_TO_POPULATE => $person]); - // $person = App\Model\Person(name: 'foo', age: '69', sportsperson: true) - -This is a common need when working with an ORM. - -The ``AbstractNormalizer::OBJECT_TO_POPULATE`` is only used for the top level object. If that object -is the root of a tree structure, all child elements that exist in the -normalized data will be re-created with new instances. - -When the ``AbstractObjectNormalizer::DEEP_OBJECT_TO_POPULATE`` option is set to -true, existing children of the root ``OBJECT_TO_POPULATE`` are updated from the -normalized data, instead of the denormalizer re-creating them. Note that -``DEEP_OBJECT_TO_POPULATE`` only works for single child objects, but not for -arrays of objects. Those will still be replaced when present in the normalized -data. - -Context -------- - -Many Serializer features can be configured :ref:`using a context `. - -.. _component-serializer-attributes-groups: - -Attributes Groups ------------------ - -Sometimes, you want to serialize different sets of attributes from your -entities. Groups are a handy way to achieve this need. - -Assume you have the following plain-old-PHP object:: - - namespace Acme; - - class MyObj - { - public string $foo; - - private string $bar; - - public function getBar(): string - { - return $this->bar; - } - - public function setBar($bar): string - { - return $this->bar = $bar; - } - } - -The definition of serialization can be specified using annotations, XML -or YAML. The :class:`Symfony\\Component\\Serializer\\Mapping\\Factory\\ClassMetadataFactory` -that will be used by the normalizer must be aware of the format to use. - -The following code shows how to initialize the :class:`Symfony\\Component\\Serializer\\Mapping\\Factory\\ClassMetadataFactory` -for each format: - -* Attributes in PHP files:: - - use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory; - use Symfony\Component\Serializer\Mapping\Loader\AttributeLoader; - - $classMetadataFactory = new ClassMetadataFactory(new AttributeLoader()); - -* YAML files:: - - use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory; - use Symfony\Component\Serializer\Mapping\Loader\YamlFileLoader; - - $classMetadataFactory = new ClassMetadataFactory(new YamlFileLoader('/path/to/your/definition.yaml')); - -* XML files:: - - use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory; - use Symfony\Component\Serializer\Mapping\Loader\XmlFileLoader; - - $classMetadataFactory = new ClassMetadataFactory(new XmlFileLoader('/path/to/your/definition.xml')); - -.. _component-serializer-attributes-groups-attributes: - -Then, create your groups definition: - -.. configuration-block:: - - .. code-block:: php-attributes - - namespace Acme; - - use Symfony\Component\Serializer\Annotation\Groups; - - class MyObj - { - #[Groups(['group1', 'group2'])] - public string $foo; - - #[Groups(['group4'])] - public string $anotherProperty; - - #[Groups(['group3'])] - public function getBar() // is* methods are also supported - { - return $this->bar; - } - - // ... - } - - .. code-block:: yaml - - Acme\MyObj: - attributes: - foo: - groups: ['group1', 'group2'] - anotherProperty: - groups: ['group4'] - bar: - groups: ['group3'] - - .. code-block:: xml - - - - - - group1 - group2 - - - - group4 - - - - group3 - - - - -You are now able to serialize only attributes in the groups you want:: - - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $obj = new MyObj(); - $obj->foo = 'foo'; - $obj->anotherProperty = 'anotherProperty'; - $obj->setBar('bar'); - - $normalizer = new ObjectNormalizer($classMetadataFactory); - $serializer = new Serializer([$normalizer]); - - $data = $serializer->normalize($obj, null, ['groups' => 'group1']); - // $data = ['foo' => 'foo']; - - $obj2 = $serializer->denormalize( - ['foo' => 'foo', 'anotherProperty' => 'anotherProperty', 'bar' => 'bar'], - 'MyObj', - null, - ['groups' => ['group1', 'group3']] - ); - // $obj2 = MyObj(foo: 'foo', bar: 'bar') - - // To get all groups, use the special value `*` in `groups` - $obj3 = $serializer->denormalize( - ['foo' => 'foo', 'anotherProperty' => 'anotherProperty', 'bar' => 'bar'], - 'MyObj', - null, - ['groups' => ['*']] - ); - // $obj2 = MyObj(foo: 'foo', anotherProperty: 'anotherProperty', bar: 'bar') - -.. _ignoring-attributes-when-serializing: - -Selecting Specific Attributes ------------------------------ - -It is also possible to serialize only a set of specific attributes:: - - use Symfony\Component\Serializer\Normalizer\AbstractNormalizer; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - class User - { - public string $familyName; - public string $givenName; - public Company $company; - } - - class Company - { - public string $name; - public string $address; - } - - $company = new Company(); - $company->name = 'Les-Tilleuls.coop'; - $company->address = 'Lille, France'; - - $user = new User(); - $user->familyName = 'Dunglas'; - $user->givenName = 'Kévin'; - $user->company = $company; - - $serializer = new Serializer([new ObjectNormalizer()]); - - $data = $serializer->normalize($user, null, [AbstractNormalizer::ATTRIBUTES => ['familyName', 'company' => ['name']]]); - // $data = ['familyName' => 'Dunglas', 'company' => ['name' => 'Les-Tilleuls.coop']]; - -Only attributes that are not ignored (see below) are available. -If some serialization groups are set, only attributes allowed by those groups can be used. - -As for groups, attributes can be selected during both the serialization and deserialization processes. - -.. _serializer_ignoring-attributes: - -Ignoring Attributes -------------------- - -All accessible attributes are included by default when serializing objects. -There are two options to ignore some of those attributes. - -Option 1: Using ``#[Ignore]`` Attribute -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. configuration-block:: - - .. code-block:: php-attributes - - namespace App\Model; - - use Symfony\Component\Serializer\Annotation\Ignore; - - class MyClass - { - public string $foo; - - #[Ignore] - public string $bar; - } - - .. code-block:: yaml - - App\Model\MyClass: - attributes: - bar: - ignore: true - - .. code-block:: xml - - - - - - - - -You can now ignore specific attributes during serialization:: - - use App\Model\MyClass; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $obj = new MyClass(); - $obj->foo = 'foo'; - $obj->bar = 'bar'; - - $normalizer = new ObjectNormalizer($classMetadataFactory); - $serializer = new Serializer([$normalizer]); - - $data = $serializer->normalize($obj); - // $data = ['foo' => 'foo']; - -Option 2: Using the Context -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Pass an array with the names of the attributes to ignore using the -``AbstractNormalizer::IGNORED_ATTRIBUTES`` key in the ``context`` of the -serializer method:: - - use Acme\Person; - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\Normalizer\AbstractNormalizer; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $person = new Person(); - $person->setName('foo'); - $person->setAge(99); - - $normalizer = new ObjectNormalizer(); - $encoder = new JsonEncoder(); - - $serializer = new Serializer([$normalizer], [$encoder]); - $serializer->serialize($person, 'json', [AbstractNormalizer::IGNORED_ATTRIBUTES => ['age']]); // Output: {"name":"foo"} - -.. _component-serializer-converting-property-names-when-serializing-and-deserializing: - -Converting Property Names when Serializing and Deserializing ------------------------------------------------------------- - -Sometimes serialized attributes must be named differently than properties -or getter/setter methods of PHP classes. - -The Serializer component provides a handy way to translate or map PHP field -names to serialized names: The Name Converter System. - -Given you have the following object:: - - class Company - { - public string $name; - public string $address; - } - -And in the serialized form, all attributes must be prefixed by ``org_`` like -the following:: - - {"org_name": "Acme Inc.", "org_address": "123 Main Street, Big City"} - -A custom name converter can handle such cases:: - - use Symfony\Component\Serializer\NameConverter\NameConverterInterface; - - class OrgPrefixNameConverter implements NameConverterInterface - { - public function normalize(string $propertyName): string - { - return 'org_'.$propertyName; - } - - public function denormalize(string $propertyName): string - { - // removes 'org_' prefix - return 'org_' === substr($propertyName, 0, 4) ? substr($propertyName, 4) : $propertyName; - } - } - -The custom name converter can be used by passing it as second parameter of any -class extending :class:`Symfony\\Component\\Serializer\\Normalizer\\AbstractNormalizer`, -including :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` -and :class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer`:: - - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $nameConverter = new OrgPrefixNameConverter(); - $normalizer = new ObjectNormalizer(null, $nameConverter); - - $serializer = new Serializer([$normalizer], [new JsonEncoder()]); - - $company = new Company(); - $company->name = 'Acme Inc.'; - $company->address = '123 Main Street, Big City'; - - $json = $serializer->serialize($company, 'json'); - // {"org_name": "Acme Inc.", "org_address": "123 Main Street, Big City"} - $companyCopy = $serializer->deserialize($json, Company::class, 'json'); - // Same data as $company - -.. note:: - - You can also implement - :class:`Symfony\\Component\\Serializer\\NameConverter\\AdvancedNameConverterInterface` - to access the current class name, format and context. - -.. _using-camelized-method-names-for-underscored-attributes: - -CamelCase to snake_case -~~~~~~~~~~~~~~~~~~~~~~~ - -In many formats, it's common to use underscores to separate words (also known -as snake_case). However, in Symfony applications is common to use CamelCase to -name properties (even though the `PSR-1 standard`_ doesn't recommend any -specific case for property names). - -Symfony provides a built-in name converter designed to transform between -snake_case and CamelCased styles during serialization and deserialization -processes:: - - use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - - $normalizer = new ObjectNormalizer(null, new CamelCaseToSnakeCaseNameConverter()); - - class Person - { - public function __construct( - private string $firstName, - ) { - } - - public function getFirstName(): string - { - return $this->firstName; - } - } - - $kevin = new Person('Kévin'); - $normalizer->normalize($kevin); - // ['first_name' => 'Kévin']; - - $anne = $normalizer->denormalize(['first_name' => 'Anne'], 'Person'); - // Person object with firstName: 'Anne' - -.. _serializer_name-conversion: - -Configure name conversion using metadata -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When using this component inside a Symfony application and the class metadata -factory is enabled as explained in the :ref:`Attributes Groups section `, -this is already set up and you only need to provide the configuration. Otherwise:: - - // ... - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\NameConverter\MetadataAwareNameConverter; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $classMetadataFactory = new ClassMetadataFactory(new AttributeLoader()); - - $metadataAwareNameConverter = new MetadataAwareNameConverter($classMetadataFactory); - - $serializer = new Serializer( - [new ObjectNormalizer($classMetadataFactory, $metadataAwareNameConverter)], - ['json' => new JsonEncoder()] - ); - -Now configure your name conversion mapping. Consider an application that -defines a ``Person`` entity with a ``firstName`` property: - -.. configuration-block:: - - .. code-block:: php-attributes - - namespace App\Entity; - - use Symfony\Component\Serializer\Annotation\SerializedName; - - class Person - { - public function __construct( - #[SerializedName('customer_name')] - private string $firstName, - ) { - } - - // ... - } - - .. code-block:: yaml - - App\Entity\Person: - attributes: - firstName: - serialized_name: customer_name - - .. code-block:: xml - - - - - - - - -This custom mapping is used to convert property names when serializing and -deserializing objects:: - - $serialized = $serializer->serialize(new Person('Kévin'), 'json'); - // {"customer_name": "Kévin"} - -Serializing Boolean Attributes ------------------------------- - -If you are using isser methods (methods prefixed by ``is``, like -``App\Model\Person::isSportsperson()``), the Serializer component will -automatically detect and use it to serialize related attributes. - -The ``ObjectNormalizer`` also takes care of methods starting with ``has``, ``get``, -and ``can``. - -Using Callbacks to Serialize Properties with Object Instances -------------------------------------------------------------- - -When serializing, you can set a callback to format a specific object property:: - - use App\Model\Person; - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer; - use Symfony\Component\Serializer\Serializer; - - $encoder = new JsonEncoder(); - - // all callback parameters are optional (you can omit the ones you don't use) - $dateCallback = function (object $innerObject, object $outerObject, string $attributeName, string $format = null, array $context = []): string { - return $innerObject instanceof \DateTime ? $innerObject->format(\DateTime::ISO8601) : ''; - }; - - $defaultContext = [ - AbstractNormalizer::CALLBACKS => [ - 'createdAt' => $dateCallback, - ], - ]; - - $normalizer = new GetSetMethodNormalizer(null, null, null, null, null, $defaultContext); - - $serializer = new Serializer([$normalizer], [$encoder]); - - $person = new Person(); - $person->setName('cordoval'); - $person->setAge(34); - $person->setCreatedAt(new \DateTime('now')); - - $serializer->serialize($person, 'json'); - // Output: {"name":"cordoval", "age": 34, "createdAt": "2014-03-22T09:43:12-0500"} - -.. _component-serializer-normalizers: - -Normalizers ------------ - -Normalizers turn **objects** into **arrays** and vice versa. They implement -:class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizerInterface` for -normalizing (object to array) and -:class:`Symfony\\Component\\Serializer\\Normalizer\\DenormalizerInterface` for -denormalizing (array to object). - -Normalizers are enabled in the serializer passing them as its first argument:: - - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $normalizers = [new ObjectNormalizer()]; - $serializer = new Serializer($normalizers, []); - -Built-in Normalizers -~~~~~~~~~~~~~~~~~~~~ - -The Serializer component provides several built-in normalizers: - -:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer` - This normalizer leverages the :doc:`PropertyAccess Component ` - to read and write in the object. It means that it can access to properties - directly and through getters, setters, hassers, issers, canners, adders and removers. - It supports calling the constructor during the denormalization process. - - Objects are normalized to a map of property names and values (names are - generated by removing the ``get``, ``set``, ``has``, ``is``, ``can``, ``add`` or ``remove`` - prefix from the method name and transforming the first letter to lowercase; e.g. - ``getFirstName()`` -> ``firstName``). - - The ``ObjectNormalizer`` is the most powerful normalizer. It is configured by - default in Symfony applications with the Serializer component enabled. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` - This normalizer reads the content of the class by calling the "getters" - (public methods starting with "get"). It will denormalize data by calling - the constructor and the "setters" (public methods starting with "set"). - - Objects are normalized to a map of property names and values (names are - generated by removing the ``get`` prefix from the method name and transforming - the first letter to lowercase; e.g. ``getFirstName()`` -> ``firstName``). - -:class:`Symfony\\Component\\Serializer\\Normalizer\\PropertyNormalizer` - This normalizer directly reads and writes public properties as well as - **private and protected** properties (from both the class and all of its - parent classes) by using `PHP reflection`_. It supports calling the constructor - during the denormalization process. - - Objects are normalized to a map of property names to property values. - - If you prefer to only normalize certain properties (e.g. only public properties) - set the ``PropertyNormalizer::NORMALIZE_VISIBILITY`` context option and - combine the following values: ``PropertyNormalizer::NORMALIZE_PUBLIC``, - ``PropertyNormalizer::NORMALIZE_PROTECTED`` or ``PropertyNormalizer::NORMALIZE_PRIVATE``. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\JsonSerializableNormalizer` - This normalizer works with classes that implement :phpclass:`JsonSerializable`. - - It will call the :phpmethod:`JsonSerializable::jsonSerialize` method and - then further normalize the result. This means that nested - :phpclass:`JsonSerializable` classes will also be normalized. - - This normalizer is particularly helpful when you want to gradually migrate - from an existing codebase using simple :phpfunction:`json_encode` to the Symfony - Serializer by allowing you to mix which normalizers are used for which classes. - - Unlike with :phpfunction:`json_encode` circular references can be handled. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\DateTimeNormalizer` - This normalizer converts :phpclass:`DateTimeInterface` objects (e.g. - :phpclass:`DateTime` and :phpclass:`DateTimeImmutable`) into strings. - By default, it uses the `RFC3339`_ format. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\DateTimeZoneNormalizer` - This normalizer converts :phpclass:`DateTimeZone` objects into strings that - represent the name of the timezone according to the `list of PHP timezones`_. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\DataUriNormalizer` - This normalizer converts :phpclass:`SplFileInfo` objects into a `data URI`_ - string (``data:...``) such that files can be embedded into serialized data. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\DateIntervalNormalizer` - This normalizer converts :phpclass:`DateInterval` objects into strings. - By default, it uses the ``P%yY%mM%dDT%hH%iM%sS`` format. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\BackedEnumNormalizer` - This normalizer converts a \BackedEnum objects into strings or integers. - - By default, an exception is thrown when data is not a valid backed enumeration. If you - want ``null`` instead, you can set the ``BackedEnumNormalizer::ALLOW_INVALID_VALUES`` option. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\FormErrorNormalizer` - This normalizer works with classes that implement - :class:`Symfony\\Component\\Form\\FormInterface`. - - It will get errors from the form and normalize them into a normalized array. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\ConstraintViolationListNormalizer` - This normalizer converts objects that implement - :class:`Symfony\\Component\\Validator\\ConstraintViolationListInterface` - into a list of errors according to the `RFC 7807`_ standard. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\ProblemNormalizer` - Normalizes errors according to the API Problem spec `RFC 7807`_. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\CustomNormalizer` - Normalizes a PHP object using an object that implements :class:`Symfony\\Component\\Serializer\\Normalizer\\NormalizableInterface`. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\UidNormalizer` - This normalizer converts objects that extend - :class:`Symfony\\Component\\Uid\\AbstractUid` into strings. - The default normalization format for objects that implement :class:`Symfony\\Component\\Uid\\Uuid` - is the `RFC 4122`_ format (example: ``d9e7a184-5d5b-11ea-a62a-3499710062d0``). - The default normalization format for objects that implement :class:`Symfony\\Component\\Uid\\Ulid` - is the Base 32 format (example: ``01E439TP9XJZ9RPFH3T1PYBCR8``). - You can change the string format by setting the serializer context option - ``UidNormalizer::NORMALIZATION_FORMAT_KEY`` to ``UidNormalizer::NORMALIZATION_FORMAT_BASE_58``, - ``UidNormalizer::NORMALIZATION_FORMAT_BASE_32`` or ``UidNormalizer::NORMALIZATION_FORMAT_RFC_4122``. - - Also it can denormalize ``uuid`` or ``ulid`` strings to :class:`Symfony\\Component\\Uid\\Uuid` - or :class:`Symfony\\Component\\Uid\\Ulid`. The format does not matter. - -:class:`Symfony\\Component\\Serializer\\Normalizer\\TranslatableNormalizer` - This normalizer converts objects that implement - :class:`Symfony\\Contracts\\Translation\\TranslatableInterface` into - translated strings, using the - :method:`Symfony\\Contracts\\Translation\\TranslatableInterface::trans` - method. You can define the locale to use to translate the object by - setting the ``TranslatableNormalizer::NORMALIZATION_LOCALE_KEY`` serializer - context option. - -.. note:: - - You can also create your own Normalizer to use another structure. Read more at - :doc:`/serializer/custom_normalizer`. - -Certain normalizers are enabled by default when using the Serializer component -in a Symfony application, additional ones can be enabled by tagging them with -:ref:`serializer.normalizer `. - -Here is an example of how to enable the built-in -:class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer`, a -faster alternative to the -:class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`: - -.. configuration-block:: - - .. code-block:: yaml - - # config/services.yaml - services: - # ... - - get_set_method_normalizer: - class: Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer - tags: [serializer.normalizer] - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // config/services.php - namespace Symfony\Component\DependencyInjection\Loader\Configurator; - - use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer; - - return static function (ContainerConfigurator $container): void { - $container->services() - // ... - ->set('get_set_method_normalizer', GetSetMethodNormalizer::class) - ->tag('serializer.normalizer') - ; - }; - -.. _component-serializer-encoders: - -Encoders --------- - -Encoders turn **arrays** into **formats** and vice versa. They implement -:class:`Symfony\\Component\\Serializer\\Encoder\\EncoderInterface` -for encoding (array to format) and -:class:`Symfony\\Component\\Serializer\\Encoder\\DecoderInterface` for decoding -(format to array). - -You can add new encoders to a Serializer instance by using its second constructor argument:: - - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\Encoder\XmlEncoder; - use Symfony\Component\Serializer\Serializer; - - $encoders = [new XmlEncoder(), new JsonEncoder()]; - $serializer = new Serializer([], $encoders); - -Built-in Encoders -~~~~~~~~~~~~~~~~~ - -The Serializer component provides several built-in encoders: - -:class:`Symfony\\Component\\Serializer\\Encoder\\JsonEncoder` - This class encodes and decodes data in `JSON`_. - -:class:`Symfony\\Component\\Serializer\\Encoder\\XmlEncoder` - This class encodes and decodes data in `XML`_. - -:class:`Symfony\\Component\\Serializer\\Encoder\\YamlEncoder` - This encoder encodes and decodes data in `YAML`_. This encoder requires the - :doc:`Yaml Component `. - -:class:`Symfony\\Component\\Serializer\\Encoder\\CsvEncoder` - This encoder encodes and decodes data in `CSV`_. - -.. note:: - - You can also create your own Encoder to use another structure. Read more at - :doc:`/serializer/custom_encoders`. - -All these encoders are enabled by default when using the Serializer component -in a Symfony application. - -The ``JsonEncoder`` -~~~~~~~~~~~~~~~~~~~ - -The ``JsonEncoder`` encodes to and decodes from JSON strings, based on the PHP -:phpfunction:`json_encode` and :phpfunction:`json_decode` functions. It can be -useful to modify how these functions operate in certain instances by providing -options such as ``JSON_PRESERVE_ZERO_FRACTION``. You can use the serialization -context to pass in these options using the key ``json_encode_options`` or -``json_decode_options`` respectively:: - - $this->serializer->serialize($data, 'json', ['json_encode_options' => \JSON_PRESERVE_ZERO_FRACTION]); - -These are the options available: - -=============================== =========================================================================================================== ================================ -Option Description Default -=============================== ========================================================================================================== ================================ -``json_decode_associative`` If set to true returns the result as an array, returns a nested ``stdClass`` hierarchy otherwise. ``false`` -``json_decode_detailed_errors`` If set to true, exceptions thrown on parsing of JSON are more specific. Requires `seld/jsonlint`_ package. ``false`` -``json_encode_options`` `$flags`_ passed to :phpfunction:`json_decode` function. ``0`` -``json_decode_options`` `$flags`_ passed to :phpfunction:`json_encode` function. ``\JSON_PRESERVE_ZERO_FRACTION`` -``json_decode_recursion_depth`` Sets maximum recursion depth. ``512`` -=============================== ========================================================================================================== ================================ - -The ``CsvEncoder`` -~~~~~~~~~~~~~~~~~~ - -The ``CsvEncoder`` encodes to and decodes from CSV. - -The ``CsvEncoder`` Context Options -.................................. - -The ``encode()`` method defines a third optional parameter called ``context`` -which defines the configuration options for the CsvEncoder an associative array:: - - $csvEncoder->encode($array, 'csv', $context); - -These are the options available: - -======================= ===================================================== ========================== -Option Description Default -======================= ===================================================== ========================== -``csv_delimiter`` Sets the field delimiter separating values (one ``,`` - character only) -``csv_enclosure`` Sets the field enclosure (one character only) ``"`` -``csv_end_of_line`` Sets the character(s) used to mark the end of each ``\n`` - line in the CSV file -``csv_escape_char`` Sets the escape character (at most one character) empty string -``csv_key_separator`` Sets the separator for array's keys during its ``.`` - flattening -``csv_headers`` Sets the order of the header and data columns - E.g.: if ``$data = ['c' => 3, 'a' => 1, 'b' => 2]`` - and ``$options = ['csv_headers' => ['a', 'b', 'c']]`` - then ``serialize($data, 'csv', $options)`` returns - ``a,b,c\n1,2,3`` ``[]``, inferred from input data's keys -``csv_escape_formulas`` Escapes fields containing formulas by prepending them ``false`` - with a ``\t`` character -``as_collection`` Always returns results as a collection, even if only ``true`` - one line is decoded. -``no_headers`` Disables header in the encoded CSV ``false`` -``output_utf8_bom`` Outputs special `UTF-8 BOM`_ along with encoded data ``false`` -======================= ===================================================== ========================== - -The ``XmlEncoder`` -~~~~~~~~~~~~~~~~~~ - -This encoder transforms arrays into XML and vice versa. - -For example, take an object normalized as following:: - - ['foo' => [1, 2], 'bar' => true]; - -The ``XmlEncoder`` will encode this object like that: - -.. code-block:: xml - - - - 1 - 2 - 1 - - -The special ``#`` key can be used to define the data of a node:: - - ['foo' => ['@bar' => 'value', '#' => 'baz']]; - - // is encoded as follows: - // - // - // - // baz - // - // - -Furthermore, keys beginning with ``@`` will be considered attributes, and -the key ``#comment`` can be used for encoding XML comments:: - - $encoder = new XmlEncoder(); - $encoder->encode([ - 'foo' => ['@bar' => 'value'], - 'qux' => ['#comment' => 'A comment'], - ], 'xml'); - // will return: - // - // - // - // - // - -You can pass the context key ``as_collection`` in order to have the results -always as a collection. - -.. note:: - - You may need to add some attributes on the root node:: - - $encoder = new XmlEncoder(); - $encoder->encode([ - '@attribute1' => 'foo', - '@attribute2' => 'bar', - '#' => ['foo' => ['@bar' => 'value', '#' => 'baz']] - ], 'xml'); - - // will return: - // - // - // baz - // - -.. tip:: - - XML comments are ignored by default when decoding contents, but this - behavior can be changed with the optional context key ``XmlEncoder::DECODER_IGNORED_NODE_TYPES``. - - Data with ``#comment`` keys are encoded to XML comments by default. This can be - changed by adding the ``\XML_COMMENT_NODE`` option to the ``XmlEncoder::ENCODER_IGNORED_NODE_TYPES`` - key of the ``$defaultContext`` of the ``XmlEncoder`` constructor or - directly to the ``$context`` argument of the ``encode()`` method:: - - $xmlEncoder->encode($array, 'xml', [XmlEncoder::ENCODER_IGNORED_NODE_TYPES => [\XML_COMMENT_NODE]]); - -The ``XmlEncoder`` Context Options -.................................. - -The ``encode()`` method defines a third optional parameter called ``context`` -which defines the configuration options for the XmlEncoder an associative array:: - - $xmlEncoder->encode($array, 'xml', $context); - -These are the options available: - -============================== ================================================= ========================== -Option Description Default -============================== ================================================= ========================== -``xml_format_output`` If set to true, formats the generated XML with ``false`` - line breaks and indentation -``xml_version`` Sets the XML version attribute ``1.0`` -``xml_encoding`` Sets the XML encoding attribute ``utf-8`` -``xml_standalone`` Adds standalone attribute in the generated XML ``true`` -``xml_type_cast_attributes`` This provides the ability to forget the attribute ``true`` - type casting -``xml_root_node_name`` Sets the root node name ``response`` -``as_collection`` Always returns results as a collection, even if ``false`` - only one line is decoded -``decoder_ignored_node_types`` Array of node types (`DOM XML_* constants`_) ``[\XML_PI_NODE, \XML_COMMENT_NODE]`` - to be ignored while decoding -``encoder_ignored_node_types`` Array of node types (`DOM XML_* constants`_) ``[]`` - to be ignored while encoding -``load_options`` XML loading `options with libxml`_ ``\LIBXML_NONET | \LIBXML_NOBLANKS`` -``save_options`` XML saving `options with libxml`_ ``0`` -``remove_empty_tags`` If set to true, removes all empty tags in the ``false`` - generated XML -============================== ================================================= ========================== - -Example with custom ``context``:: - - use Symfony\Component\Serializer\Encoder\XmlEncoder; - - // create encoder with specified options as new default settings - $xmlEncoder = new XmlEncoder(['xml_format_output' => true]); - - $data = [ - 'id' => 'IDHNQIItNyQ', - 'date' => '2019-10-24', - ]; - - // encode with default context - $xmlEncoder->encode($data, 'xml'); - // outputs: - // - // - // IDHNQIItNyQ - // 2019-10-24 - // - - // encode with modified context - $xmlEncoder->encode($data, 'xml', [ - 'xml_root_node_name' => 'track', - 'encoder_ignored_node_types' => [ - \XML_PI_NODE, // removes XML declaration (the leading xml tag) - ], - ]); - // outputs: - // - // IDHNQIItNyQ - // 2019-10-24 - // - -The ``YamlEncoder`` -~~~~~~~~~~~~~~~~~~~ - -This encoder requires the :doc:`Yaml Component ` and -transforms from and to Yaml. - -The ``YamlEncoder`` Context Options -................................... - -The ``encode()`` method, like other encoder, uses ``context`` to set -configuration options for the YamlEncoder an associative array:: - - $yamlEncoder->encode($array, 'yaml', $context); - -These are the options available: - -=============== ======================================================== ========================== -Option Description Default -=============== ======================================================== ========================== -``yaml_inline`` The level where you switch to inline YAML ``0`` -``yaml_indent`` The level of indentation (used internally) ``0`` -``yaml_flags`` A bit field of ``Yaml::DUMP_*`` / ``PARSE_*`` constants ``0`` - to customize the encoding / decoding YAML string -=============== ======================================================== ========================== - -.. _component-serializer-context-builders: - -Context Builders ----------------- - -Instead of passing plain PHP arrays to the :ref:`serialization context `, -you can use "context builders" to define the context using a fluent interface:: - - use Symfony\Component\Serializer\Context\Encoder\CsvEncoderContextBuilder; - use Symfony\Component\Serializer\Context\Normalizer\ObjectNormalizerContextBuilder; - - $initialContext = [ - 'custom_key' => 'custom_value', - ]; - - $contextBuilder = (new ObjectNormalizerContextBuilder()) - ->withContext($initialContext) - ->withGroups(['group1', 'group2']); - - $contextBuilder = (new CsvEncoderContextBuilder()) - ->withContext($contextBuilder) - ->withDelimiter(';'); - - $serializer->serialize($something, 'csv', $contextBuilder->toArray()); - -.. note:: - - The Serializer component provides a context builder - for each :ref:`normalizer ` - and :ref:`encoder `. - - You can also :doc:`create custom context builders ` - to deal with your context values. - -Skipping ``null`` Values ------------------------- - -By default, the Serializer will preserve properties containing a ``null`` value. -You can change this behavior by setting the ``AbstractObjectNormalizer::SKIP_NULL_VALUES`` context option -to ``true``:: - - $dummy = new class { - public ?string $foo = null; - public string $bar = 'notNull'; - }; - - $normalizer = new ObjectNormalizer(); - $result = $normalizer->normalize($dummy, 'json', [AbstractObjectNormalizer::SKIP_NULL_VALUES => true]); - // ['bar' => 'notNull'] - -Require all Properties ----------------------- - -By default, the Serializer will add ``null`` to nullable properties when the parameters for those are not provided. -You can change this behavior by setting the ``AbstractNormalizer::REQUIRE_ALL_PROPERTIES`` context option -to ``true``:: - - class Dummy - { - public function __construct( - public string $foo, - public ?string $bar, - ) { - } - } - - $data = ['foo' => 'notNull']; - - $normalizer = new ObjectNormalizer(); - $result = $normalizer->denormalize($data, Dummy::class, 'json', [AbstractNormalizer::REQUIRE_ALL_PROPERTIES => true]); - // throws Symfony\Component\Serializer\Exception\MissingConstructorArgumentException - -Skipping Uninitialized Properties ---------------------------------- - -In PHP, typed properties have an ``uninitialized`` state which is different -from the default ``null`` of untyped properties. When you try to access a typed -property before giving it an explicit value, you get an error. - -To avoid the Serializer throwing an error when serializing or normalizing an -object with uninitialized properties, by default the object normalizer catches -these errors and ignores such properties. - -You can disable this behavior by setting the ``AbstractObjectNormalizer::SKIP_UNINITIALIZED_VALUES`` -context option to ``false``:: - - class Dummy { - public string $foo = 'initialized'; - public string $bar; // uninitialized - } - - $normalizer = new ObjectNormalizer(); - $result = $normalizer->normalize(new Dummy(), 'json', [AbstractObjectNormalizer::SKIP_UNINITIALIZED_VALUES => false]); - // throws Symfony\Component\PropertyAccess\Exception\UninitializedPropertyException as normalizer cannot read uninitialized properties - -.. note:: - - Calling ``PropertyNormalizer::normalize`` or ``GetSetMethodNormalizer::normalize`` - with ``AbstractObjectNormalizer::SKIP_UNINITIALIZED_VALUES`` context option set - to ``false`` will throw an ``\Error`` instance if the given object has uninitialized - properties as the normalizer cannot read them (directly or via getter/isser methods). - -.. _component-serializer-handling-circular-references: - -Collecting Type Errors While Denormalizing ------------------------------------------- - -When denormalizing a payload to an object with typed properties, you'll get an -exception if the payload contains properties that don't have the same type as -the object. - -In those situations, use the ``COLLECT_DENORMALIZATION_ERRORS`` option to -collect all exceptions at once, and to get the object partially denormalized:: - - try { - $dto = $serializer->deserialize($request->getContent(), MyDto::class, 'json', [ - DenormalizerInterface::COLLECT_DENORMALIZATION_ERRORS => true, - ]); - } catch (PartialDenormalizationException $e) { - $violations = new ConstraintViolationList(); - /** @var NotNormalizableValueException $exception */ - foreach ($e->getErrors() as $exception) { - $message = sprintf('The type must be one of "%s" ("%s" given).', implode(', ', $exception->getExpectedTypes()), $exception->getCurrentType()); - $parameters = []; - if ($exception->canUseMessageForUser()) { - $parameters['hint'] = $exception->getMessage(); - } - $violations->add(new ConstraintViolation($message, '', $parameters, null, $exception->getPath(), null)); - } - - return $this->json($violations, 400); - } - -Handling Circular References ----------------------------- - -Circular references are common when dealing with entity relations:: - - class Organization - { - private string $name; - private array $members; - - public function setName($name): void - { - $this->name = $name; - } - - public function getName(): string - { - return $this->name; - } - - public function setMembers(array $members): void - { - $this->members = $members; - } - - public function getMembers(): array - { - return $this->members; - } - } - - class Member - { - private string $name; - private Organization $organization; - - public function setName(string $name): void - { - $this->name = $name; - } - - public function getName(): string - { - return $this->name; - } - - public function setOrganization(Organization $organization): void - { - $this->organization = $organization; - } - - public function getOrganization(): Organization - { - return $this->organization; - } - } - -To avoid infinite loops, :class:`Symfony\\Component\\Serializer\\Normalizer\\GetSetMethodNormalizer` -or :class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer` -throw a :class:`Symfony\\Component\\Serializer\\Exception\\CircularReferenceException` -when such a case is encountered:: - - $member = new Member(); - $member->setName('Kévin'); - - $organization = new Organization(); - $organization->setName('Les-Tilleuls.coop'); - $organization->setMembers([$member]); - - $member->setOrganization($organization); - - echo $serializer->serialize($organization, 'json'); // Throws a CircularReferenceException - -The key ``circular_reference_limit`` in the default context sets the number of -times it will serialize the same object before considering it a circular -reference. The default value is ``1``. - -Instead of throwing an exception, circular references can also be handled -by custom callables. This is especially useful when serializing entities -having unique identifiers:: - - $encoder = new JsonEncoder(); - $defaultContext = [ - AbstractNormalizer::CIRCULAR_REFERENCE_HANDLER => function (object $object, string $format, array $context): string { - return $object->getName(); - }, - ]; - $normalizer = new ObjectNormalizer(null, null, null, null, null, null, $defaultContext); - - $serializer = new Serializer([$normalizer], [$encoder]); - var_dump($serializer->serialize($org, 'json')); - // {"name":"Les-Tilleuls.coop","members":[{"name":"K\u00e9vin", organization: "Les-Tilleuls.coop"}]} - -.. _serializer_handling-serialization-depth: - -Handling Serialization Depth ----------------------------- - -The Serializer component is able to detect and limit the serialization depth. -It is especially useful when serializing large trees. Assume the following data -structure:: - - namespace Acme; - - class MyObj - { - public string $foo; - - /** - * @var self - */ - public MyObj $child; - } - - $level1 = new MyObj(); - $level1->foo = 'level1'; - - $level2 = new MyObj(); - $level2->foo = 'level2'; - $level1->child = $level2; - - $level3 = new MyObj(); - $level3->foo = 'level3'; - $level2->child = $level3; - -The serializer can be configured to set a maximum depth for a given property. -Here, we set it to 2 for the ``$child`` property: - -.. configuration-block:: - - .. code-block:: php-attributes - - namespace Acme; - - use Symfony\Component\Serializer\Annotation\MaxDepth; - - class MyObj - { - #[MaxDepth(2)] - public MyObj $child; - - // ... - } - - .. code-block:: yaml - - Acme\MyObj: - attributes: - child: - max_depth: 2 - - .. code-block:: xml - - - - - - - - -The metadata loader corresponding to the chosen format must be configured in -order to use this feature. It is done automatically when using the Serializer component -in a Symfony application. When using the standalone component, refer to -:ref:`the groups documentation ` to -learn how to do that. - -The check is only done if the ``AbstractObjectNormalizer::ENABLE_MAX_DEPTH`` key of the serializer context -is set to ``true``. In the following example, the third level is not serialized -because it is deeper than the configured maximum depth of 2:: - - $result = $serializer->normalize($level1, null, [AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true]); - /* - $result = [ - 'foo' => 'level1', - 'child' => [ - 'foo' => 'level2', - 'child' => [ - 'child' => null, - ], - ], - ]; - */ - -Instead of throwing an exception, a custom callable can be executed when the -maximum depth is reached. This is especially useful when serializing entities -having unique identifiers:: - - use Symfony\Component\Serializer\Annotation\MaxDepth; - use Symfony\Component\Serializer\Mapping\Factory\ClassMetadataFactory; - use Symfony\Component\Serializer\Mapping\Loader\AttributeLoader; - use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - class Foo - { - public int $id; - - #[MaxDepth(1)] - public MyObj $child; - } - - $level1 = new Foo(); - $level1->id = 1; - - $level2 = new Foo(); - $level2->id = 2; - $level1->child = $level2; - - $level3 = new Foo(); - $level3->id = 3; - $level2->child = $level3; - - $classMetadataFactory = new ClassMetadataFactory(new AttributeLoader()); - - // all callback parameters are optional (you can omit the ones you don't use) - $maxDepthHandler = function (object $innerObject, object $outerObject, string $attributeName, string $format = null, array $context = []): string { - return '/foos/'.$innerObject->id; - }; - - $defaultContext = [ - AbstractObjectNormalizer::MAX_DEPTH_HANDLER => $maxDepthHandler, - ]; - $normalizer = new ObjectNormalizer($classMetadataFactory, null, null, null, null, null, $defaultContext); - - $serializer = new Serializer([$normalizer]); - - $result = $serializer->normalize($level1, null, [AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true]); - /* - $result = [ - 'id' => 1, - 'child' => [ - 'id' => 2, - 'child' => '/foos/3', - ], - ]; - */ - -Handling Arrays ---------------- - -The Serializer component is capable of handling arrays of objects as well. -Serializing arrays works just like serializing a single object:: - - use Acme\Person; - - $person1 = new Person(); - $person1->setName('foo'); - $person1->setAge(99); - $person1->setSportsman(false); - - $person2 = new Person(); - $person2->setName('bar'); - $person2->setAge(33); - $person2->setSportsman(true); - - $persons = [$person1, $person2]; - $data = $serializer->serialize($persons, 'json'); - - // $data contains [{"name":"foo","age":99,"sportsman":false},{"name":"bar","age":33,"sportsman":true}] - -If you want to deserialize such a structure, you need to add the -:class:`Symfony\\Component\\Serializer\\Normalizer\\ArrayDenormalizer` -to the set of normalizers. By appending ``[]`` to the type parameter of the -:method:`Symfony\\Component\\Serializer\\Serializer::deserialize` method, -you indicate that you're expecting an array instead of a single object:: - - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\Normalizer\ArrayDenormalizer; - use Symfony\Component\Serializer\Normalizer\GetSetMethodNormalizer; - use Symfony\Component\Serializer\Serializer; - - $serializer = new Serializer( - [new GetSetMethodNormalizer(), new ArrayDenormalizer()], - [new JsonEncoder()] - ); - - $data = ...; // The serialized data from the previous example - $persons = $serializer->deserialize($data, 'Acme\Person[]', 'json'); - -Handling Constructor Arguments ------------------------------- - -If the class constructor defines arguments, as usually happens with -`Value Objects`_, the serializer won't be able to create the object if some -arguments are missing. In those cases, use the ``default_constructor_arguments`` -context option:: - - use Symfony\Component\Serializer\Normalizer\AbstractNormalizer; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - class MyObj - { - public function __construct( - private string $foo, - private string $bar, - ) { - } - } - - $normalizer = new ObjectNormalizer($classMetadataFactory); - $serializer = new Serializer([$normalizer]); - - $data = $serializer->denormalize( - ['foo' => 'Hello'], - 'MyObj', - null, - [AbstractNormalizer::DEFAULT_CONSTRUCTOR_ARGUMENTS => [ - 'MyObj' => ['foo' => '', 'bar' => ''], - ]] - ); - // $data = new MyObj('Hello', ''); - -Recursive Denormalization and Type Safety ------------------------------------------ - -The Serializer component can use the :doc:`PropertyInfo Component ` to denormalize -complex types (objects). The type of the class' property will be guessed using the provided -extractor and used to recursively denormalize the inner data. - -When using this component in a Symfony application, all normalizers are automatically configured to use the registered extractors. -When using the component standalone, an implementation of :class:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface`, -(usually an instance of :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`) must be passed as the 4th -parameter of the ``ObjectNormalizer``:: - - namespace Acme; - - use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor; - use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - class ObjectOuter - { - private ObjectInner $inner; - private \DateTimeInterface $date; - - public function getInner(): ObjectInner - { - return $this->inner; - } - - public function setInner(ObjectInner $inner): void - { - $this->inner = $inner; - } - - public function getDate(): \DateTimeInterface - { - return $this->date; - } - - public function setDate(\DateTimeInterface $date): void - { - $this->date = $date; - } - } - - class ObjectInner - { - public string $foo; - public string $bar; - } - - $normalizer = new ObjectNormalizer(null, null, null, new ReflectionExtractor()); - $serializer = new Serializer([new DateTimeNormalizer(), $normalizer]); - - $obj = $serializer->denormalize( - ['inner' => ['foo' => 'foo', 'bar' => 'bar'], 'date' => '1988/01/21'], - 'Acme\ObjectOuter' - ); - - dump($obj->getInner()->foo); // 'foo' - dump($obj->getInner()->bar); // 'bar' - dump($obj->getDate()->format('Y-m-d')); // '1988-01-21' - -When a ``PropertyTypeExtractor`` is available, the normalizer will also check that the data to denormalize -matches the type of the property (even for primitive types). For instance, if a ``string`` is provided, but -the type of the property is ``int``, an :class:`Symfony\\Component\\Serializer\\Exception\\UnexpectedValueException` -will be thrown. The type enforcement of the properties can be disabled by setting -the serializer context option ``ObjectNormalizer::DISABLE_TYPE_ENFORCEMENT`` -to ``true``. - -.. _serializer_interfaces-and-abstract-classes: - -Serializing Interfaces and Abstract Classes -------------------------------------------- - -When dealing with objects that are fairly similar or share properties, you may -use interfaces or abstract classes. The Serializer component allows you to -serialize and deserialize these objects using a *"discriminator class mapping"*. - -The discriminator is the field (in the serialized string) used to differentiate -between the possible objects. In practice, when using the Serializer component, -pass a :class:`Symfony\\Component\\Serializer\\Mapping\\ClassDiscriminatorResolverInterface` -implementation to the :class:`Symfony\\Component\\Serializer\\Normalizer\\ObjectNormalizer`. - -The Serializer component provides an implementation of ``ClassDiscriminatorResolverInterface`` -called :class:`Symfony\\Component\\Serializer\\Mapping\\ClassDiscriminatorFromClassMetadata` -which uses the class metadata factory and a mapping configuration to serialize -and deserialize objects of the correct class. - -When using this component inside a Symfony application and the class metadata factory is enabled -as explained in the :ref:`Attributes Groups section `, -this is already set up and you only need to provide the configuration. Otherwise:: - - // ... - use Symfony\Component\Serializer\Encoder\JsonEncoder; - use Symfony\Component\Serializer\Mapping\ClassDiscriminatorFromClassMetadata; - use Symfony\Component\Serializer\Mapping\ClassDiscriminatorMapping; - use Symfony\Component\Serializer\Normalizer\ObjectNormalizer; - use Symfony\Component\Serializer\Serializer; - - $classMetadataFactory = new ClassMetadataFactory(new AttributeLoader()); - - $discriminator = new ClassDiscriminatorFromClassMetadata($classMetadataFactory); - - $serializer = new Serializer( - [new ObjectNormalizer($classMetadataFactory, null, null, null, $discriminator)], - ['json' => new JsonEncoder()] - ); - -Now configure your discriminator class mapping. Consider an application that -defines an abstract ``CodeRepository`` class extended by ``GitHubCodeRepository`` -and ``BitBucketCodeRepository`` classes: - -.. configuration-block:: - - .. code-block:: php-attributes - - namespace App; - - use App\BitBucketCodeRepository; - use App\GitHubCodeRepository; - use Symfony\Component\Serializer\Annotation\DiscriminatorMap; - - #[DiscriminatorMap(typeProperty: 'type', mapping: [ - 'github' => GitHubCodeRepository::class, - 'bitbucket' => BitBucketCodeRepository::class, - ])] - abstract class CodeRepository - { - // ... - } - - .. code-block:: yaml - - App\CodeRepository: - discriminator_map: - type_property: type - mapping: - github: 'App\GitHubCodeRepository' - bitbucket: 'App\BitBucketCodeRepository' - - .. code-block:: xml - - - - - - - - - - - -Once configured, the serializer uses the mapping to pick the correct class:: - - $serialized = $serializer->serialize(new GitHubCodeRepository(), 'json'); - // {"type": "github"} - - $repository = $serializer->deserialize($serialized, CodeRepository::class, 'json'); - // instanceof GitHubCodeRepository - -Learn more ----------- - -.. toctree:: - :maxdepth: 1 - :glob: - - /serializer - -.. seealso:: - - Normalizers for the Symfony Serializer Component supporting popular web API formats - (JSON-LD, GraphQL, OpenAPI, HAL, JSON:API) are available as part of the `API Platform`_ project. - -.. seealso:: - - A popular alternative to the Symfony Serializer component is the third-party - library, `JMS serializer`_ (versions before ``v1.12.0`` were released under - the Apache license, so incompatible with GPLv2 projects). - -.. _`PSR-1 standard`: https://www.php-fig.org/psr/psr-1/ -.. _`JMS serializer`: https://github.com/schmittjoh/serializer -.. _RFC3339: https://tools.ietf.org/html/rfc3339#section-5.8 -.. _`options with libxml`: https://www.php.net/manual/en/libxml.constants.php -.. _`DOM XML_* constants`: https://www.php.net/manual/en/dom.constants.php -.. _JSON: https://www.json.org/json-en.html -.. _XML: https://www.w3.org/XML/ -.. _YAML: https://yaml.org/ -.. _CSV: https://tools.ietf.org/html/rfc4180 -.. _`RFC 7807`: https://tools.ietf.org/html/rfc7807 -.. _`UTF-8 BOM`: https://en.wikipedia.org/wiki/Byte_order_mark -.. _`Value Objects`: https://en.wikipedia.org/wiki/Value_object -.. _`API Platform`: https://api-platform.com -.. _`list of PHP timezones`: https://www.php.net/manual/en/timezones.php -.. _`RFC 4122`: https://tools.ietf.org/html/rfc4122 -.. _`PHP reflection`: https://php.net/manual/en/book.reflection.php -.. _`data URI`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs -.. _seld/jsonlint: https://github.com/Seldaek/jsonlint -.. _$flags: https://www.php.net/manual/en/json.constants.php diff --git a/components/type_info.rst b/components/type_info.rst new file mode 100644 index 00000000000..2fd64b9bc5d --- /dev/null +++ b/components/type_info.rst @@ -0,0 +1,86 @@ +The TypeInfo Component +====================== + +The TypeInfo component extracts type information from PHP elements like properties, +arguments and return types. + +This component provides: + +* A powerful ``Type`` definition that can handle unions, intersections, and generics + (and can be extended to support more types in the future); +* A way to get types from PHP elements such as properties, method arguments, + return types, and raw strings. + +.. warning:: + + This component is :doc:`experimental ` and + could be changed at any time without prior notice. + +Installation +------------ + +.. code-block:: terminal + + $ composer require symfony/type-info + +.. include:: /components/require_autoload.rst.inc + +Usage +----- + +This component gives you a :class:`Symfony\\Component\\TypeInfo\\Type` object that +represents the PHP type of anything you built or asked to resolve. + +There are two ways to use this component. First one is to create a type manually thanks +to the :class:`Symfony\\Component\\TypeInfo\\Type` static methods as following:: + + use Symfony\Component\TypeInfo\Type; + + Type::int(); + Type::nullable(Type::string()); + Type::generic(Type::object(Collection::class), Type::int()); + Type::list(Type::bool()); + Type::intersection(Type::object(\Stringable::class), Type::object(\Iterator::class)); + + // Many others are available and can be + // found in Symfony\Component\TypeInfo\TypeFactoryTrait + +The second way of using the component is to use ``TypeInfo`` to resolve a type +based on reflection or a simple string:: + + use Symfony\Component\TypeInfo\Type; + use Symfony\Component\TypeInfo\TypeResolver\TypeResolver; + + // Instantiate a new resolver + $typeResolver = TypeResolver::create(); + + // Then resolve types for any subject + $typeResolver->resolve(new \ReflectionProperty(Dummy::class, 'id')); // returns an "int" Type instance + $typeResolver->resolve('bool'); // returns a "bool" Type instance + + // Types can be instantiated thanks to static factories + $type = Type::list(Type::nullable(Type::bool())); + + // Type instances have several helper methods + + // returns the main type (e.g. in this example it returns an "array" Type instance); + // for nullable types (e.g. string|null) it returns the non-null type (e.g. string) + // and for compound types (e.g. int|string) it throws an exception because both types + // can be considered the main one, so there's no way to pick one + $baseType = $type->getBaseType(); + + // for collections, it returns the type of the item used as the key; + // in this example, the collection is a list, so it returns an "int" Type instance + $keyType = $type->getCollectionKeyType(); + + // you can chain the utility methods (e.g. to introspect the values of the collection) + // the following code will return true + $isValueNullable = $type->getCollectionValueType()->isNullable(); + +Each of these calls will return you a ``Type`` instance that corresponds to the +static method used. You can also resolve types from a string (as shown in the +``bool`` parameter of the previous example) + +.. note:: + + To support raw string resolving, you need to install ``phpstan/phpdoc-parser`` package. diff --git a/components/uid.rst b/components/uid.rst index 26fd32989a9..5077fb4f1c8 100644 --- a/components/uid.rst +++ b/components/uid.rst @@ -27,47 +27,119 @@ Generating UUIDs ~~~~~~~~~~~~~~~~ Use the named constructors of the ``Uuid`` class or any of the specific classes -to create each type of UUID:: +to create each type of UUID: + +**UUID v1** (time-based) + +Generates the UUID using a timestamp and the MAC address of your device +(`read UUIDv1 spec `__). +Both are obtained automatically, so you don't have to pass any constructor argument:: + + use Symfony\Component\Uid\Uuid; + + // $uuid is an instance of Symfony\Component\Uid\UuidV1 + $uuid = Uuid::v1(); + +.. tip:: + + It's recommended to use UUIDv7 instead of UUIDv1 because it provides + better entropy. + +**UUID v2** (DCE security) + +Similar to UUIDv1 but with a very high likelihood of ID collision +(`read UUIDv2 spec `__). +It's part of the authentication mechanism of DCE (Distributed Computing Environment) +and the UUID includes the POSIX UIDs (user/group ID) of the user who generated it. +This UUID variant is **not implemented** by the Uid component. + +**UUID v3** (name-based, MD5) + +Generates UUIDs from names that belong, and are unique within, some given namespace +(`read UUIDv3 spec `__). +This variant is useful to generate deterministic UUIDs from arbitrary strings. +It works by populating the UUID contents with the``md5`` hash of concatenating +the namespace and the name:: + + use Symfony\Component\Uid\Uuid; + + // you can use any of the predefined namespaces... + $namespace = Uuid::fromString(Uuid::NAMESPACE_OID); + // ...or use a random namespace: + // $namespace = Uuid::v4(); + + // $name can be any arbitrary string + // $uuid is an instance of Symfony\Component\Uid\UuidV3 + $uuid = Uuid::v3($namespace, $name); + +These are the default namespaces defined by the standard: + +* ``Uuid::NAMESPACE_DNS`` if you are generating UUIDs for `DNS entries `__ +* ``Uuid::NAMESPACE_URL`` if you are generating UUIDs for `URLs `__ +* ``Uuid::NAMESPACE_OID`` if you are generating UUIDs for `OIDs (object identifiers) `__ +* ``Uuid::NAMESPACE_X500`` if you are generating UUIDs for `X500 DNs (distinguished names) `__ + +**UUID v4** (random) + +Generates a random UUID (`read UUIDv4 spec `__). +Because of its randomness, it ensures uniqueness across distributed systems +without the need for a central coordinating entity. It's privacy-friendly +because it doesn't contain any information about where and when it was generated:: + + use Symfony\Component\Uid\Uuid; + + // $uuid is an instance of Symfony\Component\Uid\UuidV4 + $uuid = Uuid::v4(); + +**UUID v5** (name-based, SHA-1) + +It's the same as UUIDv3 (explained above) but it uses ``sha1`` instead of +``md5`` to hash the given namespace and name (`read UUIDv5 spec `__). +This makes it more secure and less prone to hash collisions. + +.. _uid-uuid-v6: + +**UUID v6** (reordered time-based) + +It rearranges the time-based fields of the UUIDv1 to make it lexicographically +sortable (like :ref:`ULIDs `). It's more efficient for database indexing +(`read UUIDv6 spec `__):: + + use Symfony\Component\Uid\Uuid; + + // $uuid is an instance of Symfony\Component\Uid\UuidV6 + $uuid = Uuid::v6(); + +.. tip:: + + It's recommended to use UUIDv7 instead of UUIDv6 because it provides + better entropy. + +.. _uid-uuid-v7: + +**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) +(`read 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):: use Symfony\Component\Uid\Uuid; - // UUID type 1 generates the UUID using the MAC address of your device and a timestamp. - // Both are obtained automatically, so you don't have to pass any constructor argument. - $uuid = Uuid::v1(); // $uuid is an instance of Symfony\Component\Uid\UuidV1 - - // UUID type 4 generates a random UUID, so you don't have to pass any constructor argument. - $uuid = Uuid::v4(); // $uuid is an instance of Symfony\Component\Uid\UuidV4 - - // UUID type 3 and 5 generate a UUID hashing the given namespace and name. Type 3 uses - // MD5 hashes and Type 5 uses SHA-1. The namespace is another UUID (e.g. a Type 4 UUID) - // and the name is an arbitrary string (e.g. a product name; if it's unique). - $namespace = Uuid::v4(); - $name = $product->getUniqueName(); - - $uuid = Uuid::v3($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV3 - $uuid = Uuid::v5($namespace, $name); // $uuid is an instance of Symfony\Component\Uid\UuidV5 - - // the namespaces defined by RFC 4122 (see https://tools.ietf.org/html/rfc4122#appendix-C) - // are available as PHP constants and as string values - $uuid = Uuid::v3(Uuid::NAMESPACE_DNS, $name); // same as: Uuid::v3('dns', $name); - $uuid = Uuid::v3(Uuid::NAMESPACE_URL, $name); // same as: Uuid::v3('url', $name); - $uuid = Uuid::v3(Uuid::NAMESPACE_OID, $name); // same as: Uuid::v3('oid', $name); - $uuid = Uuid::v3(Uuid::NAMESPACE_X500, $name); // same as: Uuid::v3('x500', $name); - - // UUID type 6 is not yet part of the UUID standard. It's lexicographically sortable - // (like ULIDs) and contains a 60-bit timestamp and 63 extra unique bits. - // It's defined in https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-6 - $uuid = Uuid::v6(); // $uuid is an instance of Symfony\Component\Uid\UuidV6 - - // UUID version 7 features a time-ordered value field derived from the well known - // Unix Epoch timestamp source: the number of seconds since midnight 1 Jan 1970 UTC, leap seconds excluded. - // As well as improved entropy characteristics over versions 1 or 6. + // $uuid is an instance of Symfony\Component\Uid\UuidV7 $uuid = Uuid::v7(); - // UUID version 8 provides an RFC-compatible format for experimental or vendor-specific use cases. - // The only requirement is that the variant and version bits MUST be set as defined in Section 4: - // https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#variant_and_version_fields - // UUIDv8 uniqueness will be implementation-specific and SHOULD NOT be assumed. +**UUID v8** (custom) + +Provides an RFC-compatible format for experimental or vendor-specific use cases +(`read UUIDv8 spec `__). +The only requirement is to set the variant and version bits of the UUID. The rest +of the UUID value is specific to each implementation and no format should be assumed:: + + use Symfony\Component\Uid\Uuid; + + // $uuid is an instance of Symfony\Component\Uid\UuidV8 $uuid = Uuid::v8(); If your UUID value is already generated in another format, use any of the @@ -179,6 +251,31 @@ Use these methods to transform the UUID object into different bases:: $uuid->toBase58(); // string(22) "TuetYWNHhmuSQ3xPoVLv9M" $uuid->toRfc4122(); // string(36) "d9e7a184-5d5b-11ea-a62a-3499710062d0" $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 + $uuid = Uuid::v1(); + + $uuid->toV6(); // returns a Symfony\Component\Uid\UuidV6 instance + $uuid->toV7(); // returns a Symfony\Component\Uid\UuidV7 instance + + // convert V6 to V7 + $uuid = Uuid::v6(); + + $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 ~~~~~~~~~~~~~~~~~~ @@ -264,6 +361,14 @@ entity primary keys:: // ... } +.. warning:: + + Using UUIDs as primary keys is usually not recommended for performance reasons: + indexes are slower and take more space (because UUIDs in binary format take + 128 bits instead of 32/64 bits for auto-incremental integers) and the non-sequential + nature of UUIDs fragments indexes. :ref:`UUID v6 ` and :ref:`UUID v7 ` + are the only variants that solve the fragmentation issue (but the index size issue remains). + When using built-in Doctrine repository methods (e.g. ``findOneBy()``), Doctrine knows how to convert these UUID types to build the SQL query (e.g. ``->findOneBy(['user' => $user->getUuid()])``). However, when using DQL @@ -273,6 +378,7 @@ of the UUID parameters:: // src/Repository/ProductRepository.php // ... + use Doctrine\DBAL\ParameterType; use Symfony\Bridge\Doctrine\Types\UuidType; class ProductRepository extends ServiceEntityRepository @@ -288,7 +394,7 @@ of the UUID parameters:: // alternatively, you can convert it to a value compatible with // the type inferred by Doctrine - ->setParameter('user', $user->getUuid()->toBinary()) + ->setParameter('user', $user->getUuid()->toBinary(), ParameterType::BINARY) ; // ... @@ -441,9 +547,15 @@ entity primary keys:: } // ... - } +.. warning:: + + Using ULIDs as primary keys is usually not recommended for performance reasons. + Although ULIDs don't suffer from index fragmentation issues (because the values + are sequential), their indexes are slower and take more space (because ULIDs + in binary format take 128 bits instead of 32/64 bits for auto-incremental integers). + When using built-in Doctrine repository methods (e.g. ``findOneBy()``), Doctrine knows how to convert these ULID types to build the SQL query (e.g. ``->findOneBy(['user' => $user->getUlid()])``). However, when using DQL diff --git a/components/validator/resources.rst b/components/validator/resources.rst index d9b63a147d5..5b1448dfba1 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -133,7 +133,7 @@ instance. To solve this problem, call the :method:`Symfony\\Component\\Validator\\ValidatorBuilder::setMappingCache` method of the Validator builder and pass your own caching class (which must -implement the PSR-6 interface :class:`Psr\\Cache\\CacheItemPoolInterface`):: +implement the PSR-6 interface ``Psr\Cache\CacheItemPoolInterface``):: use Symfony\Component\Validator\Validation; @@ -171,7 +171,7 @@ You can set this custom implementation using ->setMetadataFactory(new CustomMetadataFactory(...)) ->getValidator(); -.. caution:: +.. warning:: Since you are using a custom metadata factory, you can't configure loaders and caches using the ``add*Mapping()`` methods anymore. You now have to diff --git a/components/var_dumper.rst b/components/var_dumper.rst index 06adc3a0021..3f59ff1b796 100644 --- a/components/var_dumper.rst +++ b/components/var_dumper.rst @@ -170,7 +170,7 @@ Outside a Symfony application, use the :class:`Symfony\\Component\\VarDumper\\Du ]); VarDumper::setHandler(function (mixed $var) use ($cloner, $dumper): ?string { - $dumper->dump($cloner->cloneVar($var)); + return $dumper->dump($cloner->cloneVar($var)); }); .. note:: @@ -387,7 +387,7 @@ then its dump representation:: .. note:: - `#14` is the internal object handle. It allows comparing two + ``#14`` is the internal object handle. It allows comparing two consecutive dumps of the same object. .. code-block:: php @@ -509,7 +509,7 @@ like this:: $cloner = new VarCloner(); $dumper = 'cli' === PHP_SAPI ? new CliDumper() : new HtmlDumper(); - $dumper->dump($cloner->cloneVar($var)); + return $dumper->dump($cloner->cloneVar($var)); }); Cloners @@ -623,7 +623,7 @@ For example, to get a dump as a string in a variable, you can do:: $dumper->dump( $cloner->cloneVar($variable), - function (int $line, int $depth) use (&$output): void { + function (string $line, int $depth) use (&$output): void { // A negative depth means "end of dump" if ($depth >= 0) { // Adds a two spaces indentation to the line diff --git a/components/var_exporter.rst b/components/var_exporter.rst index 634e4be78cb..6aa4279788e 100644 --- a/components/var_exporter.rst +++ b/components/var_exporter.rst @@ -206,9 +206,6 @@ initialized:: class HashProcessor { use LazyGhostTrait; - // Because of how the LazyGhostTrait trait works internally, you - // must add this private property in your class - private int $lazyObjectId; // This property may require a heavy computation to have its value public readonly string $hash; diff --git a/components/workflow.rst b/components/workflow.rst index 12a9c98ab2f..e3da25b3476 100644 --- a/components/workflow.rst +++ b/components/workflow.rst @@ -75,7 +75,7 @@ Here's an example of using the workflow defined above:: Initialization -------------- -If the property of your object is ``null`` and you want to set it with the +If the marking property of your object is ``null`` and you want to set it with the ``initial_marking`` from the configuration, you can call the ``getMarking()`` method to initialize the object property:: @@ -85,41 +85,6 @@ method to initialize the object property:: // initiate workflow $workflow->getMarking($blogPost); -Using The Workflow Registry ---------------------------- - -When you define multiple workflows you may consider using a ``Registry``, -which is an object that stores and provides access to different workflows. -A registry will also help you to decide if a workflow supports the object you -are trying to use it with:: - - use Acme\Entity\BlogPost; - use Acme\Entity\Newsletter; - use Symfony\Component\Workflow\Registry; - use Symfony\Component\Workflow\SupportStrategy\InstanceOfSupportStrategy; - - $blogPostWorkflow = ...; - $newsletterWorkflow = ...; - - $registry = new Registry(); - $registry->addWorkflow($blogPostWorkflow, new InstanceOfSupportStrategy(BlogPost::class)); - $registry->addWorkflow($newsletterWorkflow, new InstanceOfSupportStrategy(Newsletter::class)); - -You can then use the registry to get the workflow for a specific object:: - - $blogPost = new BlogPost(); - $workflow = $registry->get($blogPost); - - // initiate workflow - $workflow->getMarking($blogPost); - -.. caution:: - - Beware that injecting the ``Registry`` into your services is **not** - recommended. Indeed, it prevents some optimization like lazy-loading - from working and could be a performance hog. Instead, you should always - inject the workflow you need. - Learn more ---------- diff --git a/components/yaml.rst b/components/yaml.rst index 627fc4479e0..ea1c1f4af3a 100644 --- a/components/yaml.rst +++ b/components/yaml.rst @@ -355,6 +355,26 @@ and the special ``!php/enum`` syntax to parse them as proper PHP enums:: // the value of the 'foo' key is a string because it missed the `!php/enum` syntax // $parameters = ['foo' => 'FooEnum::Foo', 'bar' => 'foo']; +You can also use ``!php/enum`` to get all the enumeration cases by only +giving the enumeration FQCN:: + + enum FooEnum: string + { + case Foo = 'foo'; + case Bar = 'bar'; + } + + // ... + + $yaml = '{ bar: !php/enum FooEnum }'; + $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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -469,7 +489,7 @@ Add the ``--format`` option to get the output in JSON format: .. code-block:: terminal - $ php lint.php path/to/file.yaml --format json + $ php lint.php path/to/file.yaml --format=json .. tip:: diff --git a/configuration.rst b/configuration.rst index 295f38f62c9..30d9ade5869 100644 --- a/configuration.rst +++ b/configuration.rst @@ -228,7 +228,7 @@ reusable configuration value. By convention, parameters are defined under the App\Entity\BlogPost::MAX_ITEMS - App\Enum\PostState::Published + App\Enum\PostState::Published @@ -267,7 +267,7 @@ reusable configuration value. By convention, parameters are defined under the // ... -.. caution:: +.. 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 @@ -337,7 +337,6 @@ configuration file using a special syntax: wrap the parameter name in two ``%`` ]); }; - .. note:: If some parameter value includes the ``%`` character, you need to escape it @@ -380,7 +379,7 @@ a new ``locale`` parameter is added to the ``config/services.yaml`` file). By convention, parameters whose names start with a dot ``.`` (for example, ``.mailer.transport``), are available only during the container compilation. - They are useful when working with :ref:`Compiler Passes ` + They are useful when working with :doc:`Compiler Passes ` to declare some temporary parameters that won't be available later in the application. .. seealso:: @@ -796,7 +795,7 @@ Use environment variables in values by prefixing variables with ``$``: DB_USER=root DB_PASS=${DB_USER}pass # include the user as a password prefix -.. caution:: +.. warning:: The order is important when some env var depends on the value of other env vars. In the above example, ``DB_PASS`` must be defined after ``DB_USER``. @@ -817,7 +816,7 @@ Embed commands via ``$()`` (not supported on Windows): START_TIME=$(date) -.. caution:: +.. warning:: Using ``$()`` might not work depending on your shell. @@ -859,9 +858,10 @@ the right situation: but the overrides only apply to one environment. *Real* environment variables always win over env vars created by any of the -``.env`` files. This behavior depends on -`variables_order `_ to -contain an ``E`` to expose the ``$_ENV`` superglobal. +``.env`` files. Note that this behavior depends on the +`variables_order `_ +configuration, which must contain an ``E`` to expose the ``$_ENV`` superglobal. +This is the default configuration in PHP. The ``.env`` and ``.env.`` files should be committed to the repository because they are the same for all developers and machines. However, @@ -932,6 +932,49 @@ get the environment variables and will not spend time parsing the ``.env`` files Update your deployment tools/workflow to run the ``dotenv:dump`` command after each deploy to improve the application performance. +Storing Environment Variables In Other Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the environment variables are stored in the ``.env`` file located +at the root of your project. However, you can store them in other files in +multiple ways. + +If you use the :doc:`Runtime component `, the dotenv +path is part of the options you can set in your ``composer.json`` file: + +.. code-block:: json + + { + // ... + "extra": { + // ... + "runtime": { + "dotenv_path": "my/custom/path/to/.env" + } + } + } + +As an alternate option, you can directly invoke the ``Dotenv`` class in your +``bootstrap.php`` file or any other file of your application:: + + use Symfony\Component\Dotenv\Dotenv; + + (new Dotenv())->bootEnv(dirname(__DIR__).'my/custom/path/to/.env'); + +Symfony will then look for the environment variables in that file, but also in +the local and environment-specific files (e.g. ``.*.local`` and +``.*..local``). Read +:ref:`how to override environment variables ` +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) @@ -1064,7 +1107,7 @@ already existing ``.env`` files). # .env (or .env.local) APP_ENV=prod - # .env.prod (or .env.local.prod) - this will fallback on the loaders you defined + # .env.prod (or .env.prod.local) - this will fallback on the loaders you defined APP_ENV= .. _configuration-accessing-parameters: @@ -1267,14 +1310,14 @@ namespace ``Symfony\Config``:: $security->firewall('main') ->pattern('^/*') ->lazy(true) - ->anonymous(); + ->security(false); $security ->roleHierarchy('ROLE_ADMIN', ['ROLE_USER']) ->roleHierarchy('ROLE_SUPER_ADMIN', ['ROLE_ADMIN', 'ROLE_ALLOWED_TO_SWITCH']) ->accessControl() ->path('^/user') - ->role('ROLE_USER'); + ->roles('ROLE_USER'); $security->accessControl(['path' => '^/admin', 'roles' => 'ROLE_ADMIN']); }; diff --git a/configuration/env_var_processors.rst b/configuration/env_var_processors.rst index 6953781e187..2e82104db66 100644 --- a/configuration/env_var_processors.rst +++ b/configuration/env_var_processors.rst @@ -104,8 +104,9 @@ Symfony provides the following env var processors: }; ``env(bool:FOO)`` - Casts ``FOO`` to a bool (``true`` values are ``'true'``, ``'on'``, ``'yes'`` - and all numbers except ``0`` and ``0.0``; everything else is ``false``): + Casts ``FOO`` to a bool (``true`` values are ``'true'``, ``'on'``, ``'yes'``, + all numbers except ``0`` and ``0.0`` and all numeric strings except ``'0'`` + and ``'0.0'``; everything else is ``false``): .. configuration-block:: @@ -686,7 +687,7 @@ Symfony provides the following env var processors: ], ]); - .. caution:: + .. warning:: In order to ease extraction of the resource from the URL, the leading ``/`` is trimmed from the ``path`` component. @@ -741,11 +742,13 @@ Symfony provides the following env var processors: Tries to convert an environment variable to an actual ``\BackedEnum`` value. This processor takes the fully qualified name of the ``\BackedEnum`` as an argument:: - # App\Enum\Environment - enum Environment: string + // App\Enum\Suit.php + enum Suit: string { - case Development = 'dev'; - case Production = 'prod'; + case Clubs = 'clubs'; + case Spades = 'spades'; + case Diamonds = 'diamonds'; + case Hearts = 'hearts'; } .. configuration-block:: @@ -754,7 +757,7 @@ Symfony provides the following env var processors: # config/services.yaml parameters: - typed_env: '%env(enum:App\Enum\Environment:APP_ENV)%' + suit: '%env(enum:App\Enum\Suit:CARD_SUIT)%' .. code-block:: xml @@ -769,14 +772,17 @@ Symfony provides the following env var processors: https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> - %env(enum:App\Enum\Environment:APP_ENV)% + %env(enum:App\Enum\Suit:CARD_SUIT)% .. code-block:: php // config/services.php - $container->setParameter('typed_env', '%env(enum:App\Enum\Environment:APP_ENV)%'); + $container->setParameter('suit', '%env(enum:App\Enum\Suit:CARD_SUIT)%'); + + The value stored in the ``CARD_SUIT`` env var would be a string (e.g. ``'spades'``) + but the application will use the enum value (e.g. ``Suit::Spades``). ``env(defined:NO_FOO)`` Evaluates to ``true`` if the env var exists and its value is not ``''`` diff --git a/configuration/micro_kernel_trait.rst b/configuration/micro_kernel_trait.rst index 26a332e4fdd..b67335514a1 100644 --- a/configuration/micro_kernel_trait.rst +++ b/configuration/micro_kernel_trait.rst @@ -32,7 +32,7 @@ Next, create an ``index.php`` file that defines the kernel class and runs it: use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpKernel\Kernel as BaseKernel; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; require __DIR__.'/vendor/autoload.php'; @@ -120,6 +120,12 @@ Next, create an ``index.php`` file that defines the kernel class and runs it: $response->send(); $kernel->terminate($request, $response); +.. note:: + + In addition to the ``index.php`` file, you'll need to create a directory called + ``config/`` in your project (even if it's empty because you define the configuration + options inside the ``configureContainer()`` method). + That's it! To test it, start the :doc:`Symfony Local Web Server `: @@ -226,6 +232,7 @@ Now it looks like this:: use App\DependencyInjection\AppExtension; use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait; + use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; use Symfony\Component\HttpKernel\Kernel as BaseKernel; use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator; @@ -382,7 +389,7 @@ has one file in it:: use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; class MicroController extends AbstractController { diff --git a/configuration/multiple_kernels.rst b/configuration/multiple_kernels.rst index 4cef8b0d09e..ec8742213b5 100644 --- a/configuration/multiple_kernels.rst +++ b/configuration/multiple_kernels.rst @@ -117,7 +117,9 @@ resources:: // src/Kernel.php namespace Shared; + use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait; use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator; + use Symfony\Component\HttpKernel\Kernel as BaseKernel; use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator; class Kernel extends BaseKernel @@ -227,7 +229,7 @@ but it should typically be added to your web server configuration. # .env APP_ID=api -.. caution:: +.. warning:: The value of this variable must match the application directory within ``apps/`` as it is used in the Kernel to load the specific application @@ -258,6 +260,7 @@ the application ID to run under CLI context:: // bin/console use Shared\Kernel; + use Symfony\Bundle\FrameworkBundle\Console\Application; use Symfony\Component\Console\Input\InputInterface; use Symfony\Component\Console\Input\InputOption; diff --git a/configuration/override_dir_structure.rst b/configuration/override_dir_structure.rst index e76e5917021..e5dff35b6d0 100644 --- a/configuration/override_dir_structure.rst +++ b/configuration/override_dir_structure.rst @@ -74,7 +74,6 @@ Web front-controller:: require_once dirname(__DIR__).'/vendor/autoload_runtime.php'; // ... - .. _override-config-dir: Override the Configuration Directory @@ -112,7 +111,7 @@ In this case you have changed the location of the cache directory to You can also change the cache directory by defining an environment variable named ``APP_CACHE_DIR`` whose value is the full path of the cache folder. -.. caution:: +.. warning:: You should keep the cache directory different for each environment, otherwise some unexpected behavior may happen. Each environment generates diff --git a/configuration/secrets.rst b/configuration/secrets.rst index 653bd92f611..f717456a22c 100644 --- a/configuration/secrets.rst +++ b/configuration/secrets.rst @@ -166,6 +166,22 @@ secrets' values by passing the ``--reveal`` option: DATABASE_PASSWORD "my secret" ------------------- ------------ ------------- +Reveal Existing Secrets +----------------------- + +If you have the **decryption key**, the ``secrets:reveal`` command allows +you to reveal a single secret's value. + +.. code-block:: terminal + + $ php bin/console secrets:reveal DATABASE_PASSWORD + + my secret + +.. versionadded:: 7.1 + + The ``secrets:reveal`` command was introduced in Symfony 7.1. + Remove Secrets -------------- diff --git a/console.rst b/console.rst index 700ed536486..6a3ba70300f 100644 --- a/console.rst +++ b/console.rst @@ -98,6 +98,15 @@ completion (by default, by pressing the Tab key). $ php vendor/bin/phpstan completion --help $ composer completion --help +.. tip:: + + If you are using the :doc:`Symfony local web server + `, it is recommended to use the built-in completion + script that will ensure the right PHP version and configuration are used when + running the Console Completion. Run ``symfony completion --help`` for the + installation instructions for your shell. The Symfony CLI will provide + completion for the ``console`` and ``composer`` commands. + Creating a Command ------------------ @@ -357,7 +366,7 @@ Output sections let you manipulate the Console output in advanced ways, such as are updated independently and :ref:`appending rows to tables ` that have already been rendered. -.. caution:: +.. warning:: Terminals only allow overwriting the visible content, so you must take into account the console height when trying to write/overwrite section contents. @@ -522,13 +531,13 @@ call ``setAutoExit(false)`` on it to get the command result in ``CommandTester`` You can also test a whole console application by using :class:`Symfony\\Component\\Console\\Tester\\ApplicationTester`. -.. caution:: +.. warning:: When testing commands using the ``CommandTester`` class, console events are not dispatched. If you need to test those events, use the :class:`Symfony\\Component\\Console\\Tester\\ApplicationTester` instead. -.. caution:: +.. warning:: When testing commands using the :class:`Symfony\\Component\\Console\\Tester\\ApplicationTester` class, don't forget to disable the auto exit flag:: @@ -538,14 +547,13 @@ call ``setAutoExit(false)`` on it to get the command result in ``CommandTester`` $tester = new ApplicationTester($application); +.. warning:: -.. caution:: - - When testing ``InputOption::VALUE_NONE`` command options, you must pass an - empty value to them:: + When testing ``InputOption::VALUE_NONE`` command options, you must pass ``true`` + to them:: $commandTester = new CommandTester($command); - $commandTester->execute(['--some-option' => '']); + $commandTester->execute(['--some-option' => true]); .. note:: @@ -611,6 +619,13 @@ profile is accessible through the web page of the profiler. terminal supports links). If you run it in debug verbosity (``-vvv``) you'll also see the time and memory consumed by the command. +.. warning:: + + When profiling the ``messenger:consume`` command from the :doc:`Messenger ` + component, add the ``--no-reset`` option to the command or you won't get any + profile. Moreover, consider using the ``--limit`` option to only process a few + messages to make the profile more readable in the profiler. + Learn More ---------- diff --git a/console/calling_commands.rst b/console/calling_commands.rst index c5bfc6e5a72..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, ...). @@ -36,6 +36,9 @@ method):: '--yell' => true, ]); + // disable interactive behavior for the greet command + $greetInput->setInteractive(false); + $returnCode = $this->getApplication()->doRun($greetInput, $output); // ... @@ -57,7 +60,7 @@ method):: ``$this->getApplication()->find('demo:greet')->run()`` will allow proper events to be dispatched for that inner command as well. -.. caution:: +.. warning:: Note that all the commands will run in the same process and some of Symfony's built-in commands may not work well this way. For instance, the ``cache:clear`` diff --git a/console/command_in_controller.rst b/console/command_in_controller.rst index 64475bff103..74af9e17c15 100644 --- a/console/command_in_controller.rst +++ b/console/command_in_controller.rst @@ -11,7 +11,7 @@ service that can be reused in the controller. However, when the command is part of a third-party library, you don't want to modify or duplicate their code. Instead, you can run the command directly from the controller. -.. caution:: +.. warning:: In comparison with a direct call from the console, calling a command from a controller has a slight performance impact because of the request stack diff --git a/console/commands_as_services.rst b/console/commands_as_services.rst index 75aa13d5be8..1393879a1df 100644 --- a/console/commands_as_services.rst +++ b/console/commands_as_services.rst @@ -51,7 +51,7 @@ argument (thanks to autowiring). In other words, you only need to create this class and everything works automatically! You can call the ``app:sunshine`` command and start logging. -.. caution:: +.. warning:: You *do* have access to services in ``configure()``. However, if your command is not :ref:`lazy `, try to avoid doing any @@ -130,7 +130,7 @@ only when the ``app:sunshine`` command is actually called. You don't need to call ``setName()`` for configuring the command when it is lazy. -.. caution:: +.. warning:: Calling the ``list`` command will instantiate all commands, including lazy commands. However, if the command is a ``Symfony\Component\Console\Command\LazyCommand``, then diff --git a/console/input.rst b/console/input.rst index 4d709c18825..98cddd63875 100644 --- a/console/input.rst +++ b/console/input.rst @@ -197,7 +197,7 @@ values after a whitespace or an ``=`` sign (e.g. ``--iterations 5`` or ``--iterations=5``), but short options can only use whitespaces or no separation at all (e.g. ``-i 5`` or ``-i5``). -.. caution:: +.. warning:: While it is possible to separate an option from its value with a whitespace, using this form leads to an ambiguity should the option appear before the @@ -311,6 +311,42 @@ The above code can be simplified as follows because ``false !== null``:: $yell = ($optionValue !== false); $yellLouder = ($optionValue === 'louder'); +Fetching The Raw Command Input +------------------------------ + +Symfony provides a :method:`Symfony\\Component\\Console\\Input\\ArgvInput::getRawTokens` +method to fetch the raw input that was passed to the command. This is useful if +you want to parse the input yourself or when you need to pass the input to another +command without having to worry about the number of arguments or options:: + + // ... + use Symfony\Component\Process\Process; + + protected function execute(InputInterface $input, OutputInterface $output): int + { + // if this command was run as: + // php bin/console app:my-command foo --bar --baz=3 --qux=value1 --qux=value2 + + $tokens = $input->getRawTokens(); + // $tokens = ['app:my-command', 'foo', '--bar', '--baz=3', '--qux=value1', '--qux=value2']; + + // pass true as argument to not include the original command name + $tokens = $input->getRawTokens(true); + // $tokens = ['foo', '--bar', '--baz=3', '--qux=value1', '--qux=value2']; + + // pass the raw input to any other command (from Symfony or the operating system) + $process = new Process(['app:other-command', ...$input->getRawTokens(true)]); + $process->setTty(true); + $process->mustRun(); + + // ... + } + +.. versionadded:: 7.1 + + The :method:`Symfony\\Component\\Console\\Input\\ArgvInput::getRawTokens` + method was introduced in Symfony 7.1. + Adding Argument/Option Value Completion --------------------------------------- diff --git a/console/lockable_trait.rst b/console/lockable_trait.rst index 02f635f5788..0f4a4900e17 100644 --- a/console/lockable_trait.rst +++ b/console/lockable_trait.rst @@ -43,4 +43,28 @@ that adds two convenient methods to lock and release commands:: } } +The LockableTrait will use the ``SemaphoreStore`` if available and will default +to ``FlockStore`` otherwise. You can override this behavior by setting +a ``$lockFactory`` property with your own lock factory:: + + // ... + use Symfony\Component\Console\Command\Command; + use Symfony\Component\Console\Command\LockableTrait; + use Symfony\Component\Lock\LockFactory; + + class UpdateContentsCommand extends Command + { + use LockableTrait; + + public function __construct(private LockFactory $lockFactory) + { + } + + // ... + } + +.. versionadded:: 7.1 + + The ``$lockFactory`` property was introduced in Symfony 7.1. + .. _`locks`: https://en.wikipedia.org/wiki/Lock_(computer_science) diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 89c97cde661..497c70fb01d 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -30,7 +30,7 @@ The second section, "Working on Symfony Code", is targeted at Symfony contributors. This section lists detailed rules that every contributor needs to follow to ensure smooth upgrades for our users. -.. caution:: +.. warning:: :doc:`Experimental Features ` and code marked with the ``@internal`` tags are excluded from our Backward @@ -53,7 +53,7 @@ All interfaces shipped with Symfony can be used in type hints. You can also call any of the methods that they declare. We guarantee that we won't break code that sticks to these rules. -.. caution:: +.. warning:: The exception to this rule are interfaces tagged with ``@internal``. Such interfaces should not be used or implemented. @@ -89,7 +89,7 @@ Using our Classes All classes provided by Symfony may be instantiated and accessed through their public methods and properties. -.. caution:: +.. warning:: Classes, properties and methods that bear the tag ``@internal`` as well as the classes located in the various ``*\Tests\`` namespaces are an @@ -146,7 +146,7 @@ Using our Traits All traits provided by Symfony may be used in your classes. -.. caution:: +.. warning:: The exception to this rule are traits tagged with ``@internal``. Such traits should not be used. @@ -253,6 +253,14 @@ Make public or protected Yes Remove private property Yes **Constructors** Add constructor without mandatory arguments Yes :ref:`[1] ` +:ref:`Add argument without a default value ` No +Add argument with a default value Yes :ref:`[11] ` +Remove argument No :ref:`[3] ` +Add default value to an argument Yes +Remove default value of an argument No +Add type hint to an argument No +Remove type hint of an argument Yes +Change argument type No Remove constructor No Reduce visibility of a public constructor No Reduce visibility of a protected constructor No :ref:`[7] ` @@ -468,6 +476,10 @@ a return type is only possible with a child type. constructors of Attribute classes. Using PHP named arguments might break your code when upgrading to newer Symfony versions. +.. _note-11: + +**[11]** Only optional argument(s) of a constructor at last position may be added. + Making Code Changes in a Backward Compatible Way ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -491,42 +503,42 @@ If that's the case, here is how to do it properly in a minor version: #. Add the argument as a comment in the signature:: // the new argument can be optional - public function say(string $text, /* bool $stripWithespace = true */): void + public function say(string $text, /* bool $stripWhitespace = true */): void { } // or required - public function say(string $text, /* bool $stripWithespace */): void + public function say(string $text, /* bool $stripWhitespace */): void { } #. Document the new argument in a PHPDoc:: /** - * @param bool $stripWithespace + * @param bool $stripWhitespace */ #. Use ``func_num_args`` and ``func_get_arg`` to retrieve the argument in the method:: - $stripWithespace = 2 <= \func_num_args() ? func_get_arg(1) : false; + $stripWhitespace = 2 <= \func_num_args() ? func_get_arg(1) : false; Note that the default value is ``false`` to keep the current behavior. #. If the argument has a default value that will change the current behavior, warn the user:: - trigger_deprecation('symfony/COMPONENT', 'X.Y', 'Not passing the "bool $stripWithespace" argument explicitly is deprecated, its default value will change to X in Z.0.'); + trigger_deprecation('symfony/COMPONENT', 'X.Y', 'Not passing the "bool $stripWhitespace" argument explicitly is deprecated, its default value will change to X in Z.0.'); #. If the argument has no default value, warn the user that is going to be required in the next major version:: if (\func_num_args() < 2) { - trigger_deprecation('symfony/COMPONENT', 'X.Y', 'The "%s()" method will have a new "bool $stripWithespace" argument in version Z.0, not defining it is deprecated.', __METHOD__); + trigger_deprecation('symfony/COMPONENT', 'X.Y', 'The "%s()" method will have a new "bool $stripWhitespace" argument in version Z.0, not defining it is deprecated.', __METHOD__); - $stripWithespace = false; + $stripWhitespace = false; } else { - $stripWithespace = func_get_arg(1); + $stripWhitespace = func_get_arg(1); } #. In the next major version (``X.0``), uncomment the argument, remove the diff --git a/contributing/code/bugs.rst b/contributing/code/bugs.rst index fba68617ee3..b0a46766026 100644 --- a/contributing/code/bugs.rst +++ b/contributing/code/bugs.rst @@ -4,7 +4,7 @@ Reporting a Bug Whenever you find a bug in Symfony, we kindly ask you to report it. It helps us make a better Symfony. -.. caution:: +.. warning:: If you think you've found a security issue, please use the special :doc:`procedure ` instead. diff --git a/contributing/code/core_team.rst b/contributing/code/core_team.rst index 6cef3400384..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,10 +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.) - -* **Recipes Team**: manages the recipes in the main and contrib recipe repositories. - + 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 @@ -52,21 +59,17 @@ Active Core Members * **Nicolas Grekas** (`nicolas-grekas`_); * **Christophe Coevoet** (`stof`_); * **Christian Flothmann** (`xabbuh`_); - * **Tobias Schultze** (`Tobion`_); * **Kévin Dunglas** (`dunglas`_); * **Javier Eguiluz** (`javiereguiluz`_); * **Grégoire Pineau** (`lyrixx`_); * **Ryan Weaver** (`weaverryan`_); * **Robin Chalas** (`chalasr`_); - * **Maxime Steinhausser** (`ogizanagi`_); * **Yonel Ceruto** (`yceruto`_); * **Tobias Nyholm** (`Nyholm`_); * **Wouter De Jong** (`wouterj`_); * **Alexander M. Turek** (`derrabus`_); * **Jérémy Derussé** (`jderusse`_); - * **Titouan Galopin** (`tgalopin`_); * **Oskar Stark** (`OskarStark`_); - * **Thomas Calvet** (`fancyweb`_); * **Mathieu Santostefano** (`welcomattic`_); * **Kevin Bond** (`kbond`_); * **Jérôme Tamarelle** (`gromnan`_). @@ -74,13 +77,15 @@ Active Core Members * **Security Team** (``@symfony/security`` on GitHub): * **Fabien Potencier** (`fabpot`_); - * **Michael Cullum** (`michaelcullum`_); * **Jérémy Derussé** (`jderusse`_). -* **Recipes Team**: +* **Symfony UX Team** (``@symfony/ux`` on GitHub): - * **Fabien Potencier** (`fabpot`_); - * **Tobias Nyholm** (`Nyholm`_). + * **Ryan Weaver** (`weaverryan`_); + * **Kevin Bond** (`kbond`_); + * **Simon André** (`smnandre`_); + * **Hugo Alliaume** (`kocal`_); + * **Matheo Daninos** (`webmamba`_). * **Documentation Team** (``@symfony/team-symfony-docs`` on GitHub): @@ -104,7 +109,12 @@ Symfony contributions: * **Lukas Kahwe Smith** (`lsmith77`_); * **Jules Pietri** (`HeahDude`_); * **Jakub Zalas** (`jakzal`_); -* **Samuel Rozé** (`sroze`_). +* **Samuel Rozé** (`sroze`_); +* **Tobias Schultze** (`Tobion`_); +* **Maxime Steinhausser** (`ogizanagi`_); +* **Titouan Galopin** (`tgalopin`_); +* **Michael Cullum** (`michaelcullum`_); +* **Thomas Calvet** (`fancyweb`_). Core Membership Application ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -138,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 @@ -147,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). @@ -166,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 ~~~~~~~~~~~~~~ @@ -187,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/ @@ -218,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/contributing/code/maintenance.rst b/contributing/code/maintenance.rst index 04740ce8c6e..27e4fd73ea0 100644 --- a/contributing/code/maintenance.rst +++ b/contributing/code/maintenance.rst @@ -67,6 +67,9 @@ issue): * **Adding new deprecations**: After a version reaches stability, new deprecations cannot be added anymore. +* **Adding or updating annotations**: Adding or updating annotations (PHPDoc + annotations for instance) is not allowed; fixing them might be accepted. + Anything not explicitly listed above should be done on the next minor or major version instead. For instance, the following changes are never accepted in a patch version: diff --git a/contributing/code/pull_requests.rst b/contributing/code/pull_requests.rst index 2b33909b6aa..7c9ab2579a5 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 7.2.5 or above. +* PHP version 8.2 or above. Configure Git ~~~~~~~~~~~~~ @@ -527,7 +527,7 @@ before merging. .. _ProGit: https://git-scm.com/book .. _GitHub: https://github.com/join -.. _`GitHub's documentation`: https://help.github.com/github/using-git/ignoring-files +.. _`GitHub's documentation`: https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files .. _Symfony repository: https://github.com/symfony/symfony .. _Symfony releases page: https://symfony.com/releases#maintained-symfony-branches .. _`documentation repository`: https://github.com/symfony/symfony-docs diff --git a/contributing/code/reproducer.rst b/contributing/code/reproducer.rst index 6efae2a8ee8..3392ca87035 100644 --- a/contributing/code/reproducer.rst +++ b/contributing/code/reproducer.rst @@ -2,8 +2,8 @@ Creating a Bug Reproducer ========================= The main Symfony code repository receives thousands of issues reports per year. -Some of those issues are easy to understand and the Symfony Core developers can -fix them without any other information. However, other issues are much harder to +Some of those issues are easy to understand and can +be fixed without any other information. However, other issues are much harder to understand because developers can't reproduce them in their computers. That's when we'll ask you to create a "bug reproducer", which is the minimum amount of code needed to make the bug appear when executed. diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst index 39d96d9e247..ced2568c5f7 100644 --- a/contributing/code/standards.rst +++ b/contributing/code/standards.rst @@ -211,8 +211,8 @@ Naming Conventions * Use `camelCase`_ for PHP variables, function and method names, arguments (e.g. ``$acceptableContentTypes``, ``hasSession()``); -* Use `snake_case`_ for configuration parameters and Twig template variables - (e.g. ``framework.csrf_protection``, ``http_status_code``); +Use `snake_case`_ for configuration parameters, route names and Twig template + variables (e.g. ``framework.csrf_protection``, ``http_status_code``); * Use SCREAMING_SNAKE_CASE for constants (e.g. ``InputArgument::IS_ARRAY``); diff --git a/contributing/code/tests.rst b/contributing/code/tests.rst index 8bffc4aa4bc..08f6bc5df12 100644 --- a/contributing/code/tests.rst +++ b/contributing/code/tests.rst @@ -32,7 +32,7 @@ tests, such as Doctrine, Twig and Monolog. To do so, .. code-block:: terminal - $ COMPOSER_ROOT_VERSION=5.4.x-dev composer update + $ COMPOSER_ROOT_VERSION=7.1.x-dev composer update .. _running: diff --git a/contributing/code_of_conduct/care_team.rst b/contributing/code_of_conduct/care_team.rst index 316131e5e8f..e061c0a0afe 100644 --- a/contributing/code_of_conduct/care_team.rst +++ b/contributing/code_of_conduct/care_team.rst @@ -58,12 +58,3 @@ The :doc:`Symfony project leader ` appoints the CA team with candidates they see fit. The CARE team will consist of at least 3 people. The team should be representing as many demographics as possible, ideally from different employers. - -CARE Team Transparency Reports ------------------------------- - -The CARE team publishes a transparency report at the end of each year: - -* `Symfony Code of Conduct Transparency Report 2018`_. - -.. _`Symfony Code of Conduct Transparency Report 2018`: https://symfony.com/blog/symfony-code-of-conduct-transparency-report-2018 diff --git a/contributing/community/review-comments.rst b/contributing/community/review-comments.rst index 0a048d8fa6e..5b9bc932205 100644 --- a/contributing/community/review-comments.rst +++ b/contributing/community/review-comments.rst @@ -149,7 +149,6 @@ you don't have to use "Please" all the time. But it wouldn't hurt. It may not seem like much, but saying "Thank you" does make others feel more welcome. - Preventing Escalations ---------------------- diff --git a/contributing/community/reviews.rst b/contributing/community/reviews.rst index e3da2dcdb21..06426c03985 100644 --- a/contributing/community/reviews.rst +++ b/contributing/community/reviews.rst @@ -167,7 +167,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps: PR by running the following Git commands. Insert the PR ID (that's the number after the ``#`` in the PR title) for the ```` placeholders: - .. code-block:: text + .. code-block:: terminal $ cd vendor/symfony/symfony $ git fetch origin pull//head:pr @@ -175,7 +175,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps: For example: - .. code-block:: text + .. code-block:: terminal $ git fetch origin pull/15723/head:pr15723 $ git checkout pr15723 diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index d933f3bcead..e81abe92b79 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -16,7 +16,7 @@ source code. If you want to learn more about this format, check out the `reStructuredText Primer`_ tutorial and the `reStructuredText Reference`_. -.. caution:: +.. warning:: If you are familiar with Markdown, be careful as things are sometimes very similar but different: diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 4bc8a818bad..183910e6ac6 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -104,7 +104,7 @@ Fetch all the commits of the upstream branches by executing this command: $ git fetch upstream -The purpose of this step is to allow you work simultaneously on the official +The purpose of this step is to allow you to work simultaneously on the official Symfony repository and on your own fork. You'll see this in action in a moment. **Step 4.** Create a dedicated **new branch** for your changes. Use a short and @@ -185,6 +185,9 @@ changes and push the new changes: $ git push +It's rare, but you might be asked to rebase your pull request to target another +Symfony branch. Read the :ref:`guide on rebasing pull requests `. + **Step 10.** After your pull request is eventually accepted and merged in the Symfony documentation, you will be included in the `Symfony Documentation Contributors`_ list. Moreover, if you happen to have a `SymfonyConnect`_ diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 96875ff5c22..5e195d008fd 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -122,7 +122,7 @@ Example } } -.. caution:: +.. warning:: In YAML you should put a space after ``{`` and before ``}`` (e.g. ``{ _controller: ... }``), but this should not be done in Twig (e.g. ``{'hello' : 'value'}``). @@ -175,7 +175,6 @@ Images and Diagrams alt="Some concise description." > - English Language Standards -------------------------- diff --git a/controller.rst b/controller.rst index bb02c1e8723..c11615d93aa 100644 --- a/controller.rst +++ b/controller.rst @@ -23,7 +23,7 @@ class:: namespace App\Controller; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; class LuckyController { @@ -176,7 +176,8 @@ These are used for rendering templates, sending emails, querying the database an any other "work" you can think of. If you need a service in a controller, type-hint an argument with its class -(or interface) name. Symfony will automatically pass you the service you need:: +(or interface) name and Symfony will inject it automatically. This requires +your :doc:`controller to be registered as a service `:: use Psr\Log\LoggerInterface; use Symfony\Component\HttpFoundation\Response; @@ -371,7 +372,7 @@ attribute, arguments of your controller's action can be automatically fulfilled: // ... public function dashboard( - #[MapQueryParameter(filter: \FILTER_VALIDATE_REGEXP, options: ['regexp' => '/^\w++$/'])] string $firstName, + #[MapQueryParameter(filter: \FILTER_VALIDATE_REGEXP, options: ['regexp' => '/^\w+$/'])] string $firstName, #[MapQueryParameter] string $lastName, #[MapQueryParameter(filter: \FILTER_VALIDATE_INT)] int $age, ): Response @@ -392,7 +393,7 @@ optional validation constraints:: use Symfony\Component\Validator\Constraints as Assert; - class UserDTO + class UserDto { public function __construct( #[Assert\NotBlank] @@ -417,7 +418,7 @@ attribute in your controller:: // ... public function dashboard( - #[MapQueryString] UserDTO $userDto + #[MapQueryString] UserDto $userDto ): Response { // ... @@ -434,7 +435,7 @@ HTTP status to return if the validation fails:: #[MapQueryString( validationGroups: ['strict', 'edit'], validationFailedStatusCode: Response::HTTP_UNPROCESSABLE_ENTITY - )] UserDTO $userDto + )] UserDto $userDto ): Response { // ... @@ -442,6 +443,22 @@ HTTP status to return if the validation fails:: The default status code returned if the validation fails is 404. +If you need a valid DTO even when the request query string is empty, set a +default value for your controller arguments:: + + use App\Model\UserDto; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\HttpKernel\Attribute\MapQueryString; + + // ... + + public function dashboard( + #[MapQueryString] UserDto $userDto = new UserDto() + ): Response + { + // ... + } + .. _controller-mapping-request-payload: Mapping Request Payload @@ -470,7 +487,7 @@ attribute:: // ... public function dashboard( - #[MapRequestPayload] UserDTO $userDto + #[MapRequestPayload] UserDto $userDto ): Response { // ... @@ -485,7 +502,7 @@ your DTO:: serializationContext: ['...'], resolver: App\Resolver\UserDtoResolver )] - UserDTO $userDto + UserDto $userDto ): Response { // ... @@ -503,7 +520,7 @@ the validation fails as well as supported payload formats:: acceptFormat: 'json', validationGroups: ['strict', 'read'], validationFailedStatusCode: Response::HTTP_NOT_FOUND - )] UserDTO $userDto + )] UserDto $userDto ): Response { // ... @@ -523,22 +540,154 @@ Make sure to install `phpstan/phpdoc-parser`_ and `phpdocumentor/type-resolver`_ if you want to map a nested array of specific DTOs:: public function dashboard( - #[MapRequestPayload()] EmployeesDTO $employeesDto + #[MapRequestPayload] EmployeesDto $employeesDto ): Response { // ... } - final class EmployeesDTO + final class EmployeesDto { /** - * @param UserDTO[] $users + * @param UserDto[] $users */ public function __construct( public readonly array $users = [] ) {} } +Instead of returning an array of DTO objects, you can tell Symfony to transform +each DTO object into an array and return something like this: + +.. code-block:: json + + [ + { + "firstName": "John", + "lastName": "Smith", + "age": 28 + }, + { + "firstName": "Jane", + "lastName": "Doe", + "age": 30 + } + ] + +To do so, map the parameter as an array and configure the type of each element +using the ``type`` option of the attribute:: + + public function dashboard( + #[MapRequestPayload(type: UserDto::class)] array $users + ): Response + { + // ... + } + +.. versionadded:: 7.1 + + The ``type`` option of ``#[MapRequestPayload]`` was introduced in Symfony 7.1. + +.. _controller_map-uploaded-file: + +Mapping Uploaded Files +~~~~~~~~~~~~~~~~~~~~~~ + +Symfony provides an attribute called ``#[MapUploadedFile]`` to map one or more +``UploadedFile`` objects to controller arguments:: + + namespace App\Controller; + + use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; + use Symfony\Component\HttpFoundation\File\UploadedFile; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\HttpKernel\Attribute\MapUploadedFile; + use Symfony\Component\Routing\Attribute\Route; + + class UserController extends AbstractController + { + #[Route('/user/picture', methods: ['PUT'])] + public function changePicture( + #[MapUploadedFile] UploadedFile $picture, + ): Response { + // ... + } + } + +In this example, the associated :doc:`argument resolver ` +fetches the ``UploadedFile`` based on the argument name (``$picture``). If no file +is submitted, an ``HttpException`` is thrown. You can change this by making the +controller argument nullable: + +.. code-block:: php-attributes + + #[MapUploadedFile] + ?UploadedFile $document + +The ``#[MapUploadedFile]`` attribute also allows to pass a list of constraints +to apply to the uploaded file:: + + namespace App\Controller; + + use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; + use Symfony\Component\HttpFoundation\File\UploadedFile; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\HttpKernel\Attribute\MapUploadedFile; + use Symfony\Component\Routing\Attribute\Route; + use Symfony\Component\Validator\Constraints as Assert; + + class UserController extends AbstractController + { + #[Route('/user/picture', methods: ['PUT'])] + public function changePicture( + #[MapUploadedFile([ + new Assert\File(mimeTypes: ['image/png', 'image/jpeg']), + new Assert\Image(maxWidth: 3840, maxHeight: 2160), + ])] + UploadedFile $picture, + ): Response { + // ... + } + } + +The validation constraints are checked before injecting the ``UploadedFile`` into +the controller argument. If there's a constraint violation, an ``HttpException`` +is thrown and the controller's action is not executed. + +If you need to upload a collection of files, map them to an array or a variadic +argument. The given constraint will be applied to all files and if any of them +fails, an ``HttpException`` is thrown: + +.. code-block:: php-attributes + + #[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))] + array $documents + + #[MapUploadedFile(new Assert\File(mimeTypes: ['application/pdf']))] + UploadedFile ...$documents + +Use the ``name`` option to rename the uploaded file to a custom value: + +.. code-block:: php-attributes + + #[MapUploadedFile(name: 'something-else')] + UploadedFile $document + +In addition, you can change the status code of the HTTP exception thrown when +there are constraint violations: + +.. code-block:: php-attributes + + #[MapUploadedFile( + constraints: new Assert\File(maxSize: '2M'), + validationFailedStatusCode: Response::HTTP_REQUEST_ENTITY_TOO_LARGE + )] + UploadedFile $document + +.. versionadded:: 7.1 + + The ``#[MapUploadedFile]`` attribute was introduced in Symfony 7.1. + Managing the Session -------------------- @@ -598,7 +747,7 @@ the ``Request`` class:: // retrieves GET and POST variables respectively $request->query->get('page'); - $request->request->get('page'); + $request->getPayload()->get('page'); // retrieves SERVER variables $request->server->get('HTTP_HOST'); @@ -639,6 +788,14 @@ response types. Some of these are mentioned below. To learn more about the ``Request`` and ``Response`` (and different ``Response`` classes), see the :ref:`HttpFoundation component documentation `. +.. note:: + + Technically, a controller can return a value other than a ``Response``. + However, your application is responsible for transforming that value into a + ``Response`` object. This is handled using :doc:`events ` + (specifically the :ref:`kernel.view event `), + an advanced feature you'll learn about later. + Accessing Configuration Values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -731,7 +888,7 @@ method:: use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; use Symfony\Component\WebLink\Link; class HomepageController extends AbstractController @@ -741,7 +898,7 @@ method:: { $response = $this->sendEarlyHints([ new Link(rel: 'preconnect', href: 'https://fonts.google.com'), - (new Link(href: '/style.css'))->withAttribute('as', 'stylesheet'), + (new Link(href: '/style.css'))->withAttribute('as', 'style'), (new Link(href: '/script.js'))->withAttribute('as', 'script'), ]); @@ -756,7 +913,7 @@ Technically, Early Hints are an informational HTTP response with the status code status code and sends its headers immediately. This way, browsers can start downloading the assets immediately; like the -``style.css`` and ``script.js`` files in the above example). The +``style.css`` and ``script.js`` files in the above example. The ``sendEarlyHints()`` method also returns the ``Response`` object, which you must use to create the full response sent from the controller action. @@ -797,6 +954,6 @@ Learn more about Controllers .. _`Early hints`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103 .. _`SAPI`: https://www.php.net/manual/en/function.php-sapi-name.php .. _`FrankenPHP`: https://frankenphp.dev -.. _`Validate Filters`: https://www.php.net/manual/en/filter.filters.validate.php +.. _`Validate Filters`: https://www.php.net/manual/en/filter.constants.php .. _`phpstan/phpdoc-parser`: https://packagist.org/packages/phpstan/phpdoc-parser .. _`phpdocumentor/type-resolver`: https://packagist.org/packages/phpdocumentor/type-resolver diff --git a/controller/error_pages.rst b/controller/error_pages.rst index 52dff49731f..fc36b88779a 100644 --- a/controller/error_pages.rst +++ b/controller/error_pages.rst @@ -216,7 +216,7 @@ contents, create a new Normalizer that supports the ``FlattenException`` input:: class MyCustomProblemNormalizer implements NormalizerInterface { - public function normalize($exception, string $format = null, array $context = []): array + public function normalize($exception, ?string $format = null, array $context = []): array { return [ 'content' => 'This is my custom problem normalizer.', @@ -227,7 +227,7 @@ contents, create a new Normalizer that supports the ``FlattenException`` input:: ]; } - public function supportsNormalization($data, string $format = null, array $context = []): bool + public function supportsNormalization($data, ?string $format = null, array $context = []): bool { return $data instanceof FlattenException; } @@ -319,7 +319,7 @@ error pages. .. note:: - If your listener calls ``setThrowable()`` on the + If your listener calls ``setResponse()`` on the :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent` event, propagation will be stopped and the response will be sent to the client. diff --git a/controller/forwarding.rst b/controller/forwarding.rst index a0e0648517a..8d8be859da5 100644 --- a/controller/forwarding.rst +++ b/controller/forwarding.rst @@ -11,7 +11,7 @@ and calls the defined controller. The ``forward()`` method returns the :class:`Symfony\\Component\\HttpFoundation\\Response` object that is returned from *that* controller:: - public function index($name): Response + public function index(string $name): Response { $response = $this->forward('App\Controller\OtherController::fancy', [ 'name' => $name, diff --git a/controller/service.rst b/controller/service.rst index 33aef36d64d..88af093ff29 100644 --- a/controller/service.rst +++ b/controller/service.rst @@ -25,6 +25,39 @@ in method parameters: resource: '../src/Controller/' tags: ['controller.service_arguments'] +.. note:: + + If you don't use either :doc:`autowiring ` + or :ref:`autoconfiguration ` and you extend the + ``AbstractController``, you'll need to apply other tags and make some method + calls to register your controllers as services: + + .. code-block:: yaml + + # config/services.yaml + + # this extended configuration is only required when not using autowiring/autoconfiguration, + # which is uncommon and not recommended + + abstract_controller.locator: + class: Symfony\Component\DependencyInjection\ServiceLocator + arguments: + - + router: '@router' + request_stack: '@request_stack' + http_kernel: '@http_kernel' + session: '@session' + parameter_bag: '@parameter_bag' + # you can add more services here as you need them (e.g. the `serializer` + # service) and have a look at the AbstractController class to see + # which services are defined in the locator + + App\Controller\: + resource: '../src/Controller/' + tags: ['controller.service_arguments'] + calls: + - [setContainer, ['@abstract_controller.locator']] + If you prefer, you can use the ``#[AsController]`` PHP attribute to automatically apply the ``controller.service_arguments`` tag to your controller services:: @@ -33,7 +66,7 @@ apply the ``controller.service_arguments`` tag to your controller services:: use Symfony\Component\HttpFoundation\Response; use Symfony\Component\HttpKernel\Attribute\AsController; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; #[AsController] class HelloController @@ -62,7 +95,7 @@ a service like: ``App\Controller\HelloController::index``: namespace App\Controller; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; class HelloController { @@ -124,7 +157,7 @@ which is a common practice when following the `ADR pattern`_ namespace App\Controller; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; #[Route('/hello/{name}', name: 'hello')] class Hello diff --git a/controller/upload_file.rst b/controller/upload_file.rst index f50432f5ee3..b3dc2d6ffd0 100644 --- a/controller/upload_file.rst +++ b/controller/upload_file.rst @@ -120,17 +120,22 @@ Finally, you need to update the code of the controller that handles the form:: use App\Entity\Product; use App\Form\ProductType; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; + use Symfony\Component\DependencyInjection\Attribute\Autowire; use Symfony\Component\HttpFoundation\File\Exception\FileException; use Symfony\Component\HttpFoundation\File\UploadedFile; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; use Symfony\Component\String\Slugger\SluggerInterface; class ProductController extends AbstractController { #[Route('/product/new', name: 'app_product_new')] - public function new(Request $request, SluggerInterface $slugger): Response + public function new( + Request $request, + SluggerInterface $slugger, + #[Autowire('%kernel.project_dir%/public/uploads/brochures')] string $brochuresDirectory + ): Response { $product = new Product(); $form = $this->createForm(ProductType::class, $product); @@ -150,10 +155,7 @@ Finally, you need to update the code of the controller that handles the form:: // Move the file to the directory where brochures are stored try { - $brochureFile->move( - $this->getParameter('brochures_directory'), - $newFilename - ); + $brochureFile->move($brochuresDirectory, $newFilename); } catch (FileException $e) { // ... handle exception if something happens during file upload } @@ -174,17 +176,6 @@ Finally, you need to update the code of the controller that handles the form:: } } -Now, create the ``brochures_directory`` parameter that was used in the -controller to specify the directory in which the brochures should be stored: - -.. code-block:: yaml - - # config/services.yaml - - # ... - parameters: - brochures_directory: '%kernel.project_dir%/public/uploads/brochures' - There are some important things to consider in the code of the above controller: #. In Symfony applications, uploaded files are objects of the @@ -230,7 +221,7 @@ You can use the following code to link to the PDF brochure of a product: // ... $product->setBrochureFilename( - new File($this->getParameter('brochures_directory').'/'.$product->getBrochureFilename()) + new File($brochuresDirectory.DIRECTORY_SEPARATOR.$product->getBrochureFilename()) ); Creating an Uploader Service diff --git a/controller/value_resolver.rst b/controller/value_resolver.rst index 811543efe67..dbbea7bcc87 100644 --- a/controller/value_resolver.rst +++ b/controller/value_resolver.rst @@ -98,7 +98,7 @@ Symfony ships with the following value resolvers in the .. tip:: The ``DateTimeInterface`` object is generated with the :doc:`Clock component `. - This. gives your full control over the date and time values the controller + This gives you full control over the date and time values the controller receives when testing your application and using the :class:`Symfony\\Component\\Clock\\MockClock` implementation. @@ -129,7 +129,7 @@ Symfony ships with the following value resolvers in the namespace App\Controller; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; use Symfony\Component\Uid\UuidV4; class DefaultController @@ -175,7 +175,7 @@ In addition, some components, bridges and official bundles provide other value r namespace App\Controller; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; class DefaultController { @@ -191,8 +191,8 @@ In addition, some components, bridges and official bundles provide other value r PSR-7 Objects Resolver: Injects a Symfony HttpFoundation ``Request`` object created from a PSR-7 object - of type :class:`Psr\\Http\\Message\\ServerRequestInterface`, - :class:`Psr\\Http\\Message\\RequestInterface` or :class:`Psr\\Http\\Message\\MessageInterface`. + of type ``Psr\Http\Message\ServerRequestInterface``, + ``Psr\Http\Message\RequestInterface`` or ``Psr\Http\Message\MessageInterface``. It requires installing :doc:`the PSR-7 Bridge ` component. Managing Value Resolvers @@ -220,7 +220,7 @@ lets you do this by "targeting" the resolver you want:: use Symfony\Component\HttpFoundation\Session\SessionInterface; use Symfony\Component\HttpKernel\Attribute\ValueResolver; use Symfony\Component\HttpKernel\Controller\ArgumentResolver\SessionValueResolver; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; class SessionController { diff --git a/create_framework/http_foundation.rst b/create_framework/http_foundation.rst index 53c86ebb8b9..219119164b4 100644 --- a/create_framework/http_foundation.rst +++ b/create_framework/http_foundation.rst @@ -178,7 +178,7 @@ fingertips thanks to a nice and simple API:: // retrieves GET and POST variables respectively $request->query->get('foo'); - $request->request->get('bar', 'default value if bar does not exist'); + $request->getPayload()->get('bar', 'default value if bar does not exist'); // retrieves SERVER variables $request->server->get('HTTP_HOST'); @@ -255,7 +255,7 @@ code in production without a proxy, it becomes trivially easy to abuse your system. That's not the case with the ``getClientIp()`` method as you must explicitly trust your reverse proxies by calling ``setTrustedProxies()``:: - Request::setTrustedProxies(['10.0.0.1']); + Request::setTrustedProxies(['10.0.0.1'], Request::HEADER_X_FORWARDED_FOR); if ($myIp === $request->getClientIp()) { // the client is a known one, so give it some more privilege diff --git a/create_framework/introduction.rst b/create_framework/introduction.rst index d3574de4c94..7a1e6b2ad50 100644 --- a/create_framework/introduction.rst +++ b/create_framework/introduction.rst @@ -29,7 +29,7 @@ a few good reasons to start creating your own framework: * To refactor an old/existing application that needs a good dose of recent web development best practices; -* To prove the world that you can actually create a framework on your own (... +* To prove to the world that you can actually create a framework on your own (... but with little effort). This tutorial will gently guide you through the creation of a web framework, diff --git a/create_framework/separation_of_concerns.rst b/create_framework/separation_of_concerns.rst index e0937fbdf45..5238b3aac42 100644 --- a/create_framework/separation_of_concerns.rst +++ b/create_framework/separation_of_concerns.rst @@ -120,7 +120,7 @@ And move the ``is_leap_year()`` function to its own class too:: class LeapYear { - public function isLeapYear(int $year = null): bool + public function isLeapYear(?int $year = null): bool { if (null === $year) { $year = date('Y'); diff --git a/create_framework/templating.rst b/create_framework/templating.rst index 07d7e38417c..282e75cbc94 100644 --- a/create_framework/templating.rst +++ b/create_framework/templating.rst @@ -146,7 +146,7 @@ framework does not need to be modified in any way, create a new use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing; - function is_leap_year(int $year = null): bool + function is_leap_year(?int $year = null): bool { if (null === $year) { $year = (int)date('Y'); diff --git a/create_framework/unit_testing.rst b/create_framework/unit_testing.rst index 5c783c5279a..32c97a03846 100644 --- a/create_framework/unit_testing.rst +++ b/create_framework/unit_testing.rst @@ -12,7 +12,7 @@ using `PHPUnit`_. At first, install PHPUnit as a development dependency: .. code-block:: terminal - $ composer require --dev phpunit/phpunit + $ composer require --dev phpunit/phpunit:^9.6 Then, create a PHPUnit configuration file in ``example.com/phpunit.xml.dist``: @@ -21,7 +21,7 @@ Then, create a PHPUnit configuration file in ``example.com/phpunit.xml.dist``: 192.0.0.1,10.0.0.0/8 + + private_ranges x-forwarded-for @@ -75,6 +79,8 @@ and what headers your reverse proxy uses to send information: $framework // the IP address (or range) of your proxy ->trustedProxies('192.0.0.1,10.0.0.0/8') + // shortcut for private IP address ranges of your proxy + ->trustedProxies('private_ranges') // trust *all* "X-Forwarded-*" headers (the ! prefix means to not trust those headers) ->trustedHeaders(['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-forwarded-port', 'x-forwarded-prefix']) // or, if your proxy instead uses the "Forwarded" header @@ -82,7 +88,12 @@ and what headers your reverse proxy uses to send information: ; }; -.. caution:: +.. versionadded:: 7.1 + + ``private_ranges`` as a shortcut for private IP address ranges for the + ``trusted_proxies`` option was introduced in Symfony 7.1. + +.. danger:: Enabling the ``Request::HEADER_X_FORWARDED_HOST`` option exposes the application to `HTTP Host header attacks`_. Make sure the proxy really @@ -146,6 +157,35 @@ enough, as it will only trust the node sitting directly above your application ranges of any additional proxy (e.g. `CloudFront IP ranges`_) to the array of trusted proxies. +Reverse proxy in a subpath / subfolder +-------------------------------------- + +If your Symfony application runs behind a reverse proxy and it's served in a +subpath/subfolder, Symfony might generate incorrect URLs that ignore the +subpath/subfolder of the reverse proxy. + +To fix this, you need to pass the subpath/subfolder route prefix of the reverse +proxy to Symfony by setting the ``X-Forwarded-Prefix`` header. The header can +normally be configured in your reverse proxy configuration. Configure +``X-Forwarded-Prefix`` as trusted header to be able to use this feature. + +The ``X-Forwarded-Prefix`` is used by Symfony to prefix the base URL of request +objects, which is used to generate absolute paths and URLs in Symfony applications. +Without the header, the base URL would be only determined based on the configuration +of the web server running Symfony, which leads to incorrect paths/URLs, when the +application is served under a subpath/subfolder by a reverse proxy. + +For example if your Symfony application is directly served under a URL like +``https://symfony.tld/`` and you would like to use a reverse proxy to serve the +application under ``https://public.tld/app/``, you would need to set the +``X-Forwarded-Prefix`` header to ``/app/`` in your reverse proxy configuration. +Without the header, Symfony would generate URLs based on its server base URL +(e.g. ``/my/route``) instead of the correct ``/app/my/route``, which is +required to access the route via the reverse proxy. + +The header can be different for each reverse proxy, so that access via different +reverse proxies served under different subpaths/subfolders can be handled correctly. + Custom Headers When Using a Reverse Proxy ----------------------------------------- @@ -164,8 +204,31 @@ handling the request:: // ... $response = $kernel->handle($request); +Overriding Configuration Behind Hidden SSL Termination +------------------------------------------------------ + +Some cloud setups (like running a Docker container with the "Web App for Containers" +in `Microsoft Azure`_) do SSL termination and contact your web server over HTTP, but +do not change the remote address nor set the ``X-Forwarded-*`` headers. This means +the trusted proxy feature of Symfony can't help you. + +Once you made sure your server is only reachable through the cloud proxy over HTTPS +and not through HTTP, you can override the information your web server sends to PHP. +For Nginx, this could look like this: + +.. code-block:: nginx + + location ~ ^/index\.php$ { + fastcgi_pass 127.0.0.1:9000; + include fastcgi.conf; + # Lie to Symfony about the protocol and port so that it generates the correct HTTPS URLs + fastcgi_param SERVER_PORT "443"; + fastcgi_param HTTPS "on"; + } + .. _`security groups`: https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html .. _`CloudFront`: https://en.wikipedia.org/wiki/Amazon_CloudFront .. _`CloudFront IP ranges`: https://ip-ranges.amazonaws.com/ip-ranges.json .. _`HTTP Host header attacks`: https://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html .. _`nginx realip module`: https://nginx.org/en/docs/http/ngx_http_realip_module.html +.. _`Microsoft Azure`: https://en.wikipedia.org/wiki/Microsoft_Azure diff --git a/doctrine.rst b/doctrine.rst index ecd5a54a37e..171f8a3348a 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -41,7 +41,7 @@ The database connection information is stored as an environment variable called # .env (or override DATABASE_URL in .env.local to avoid committing your changes) # customize this line! - DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?serverVersion=5.7" + DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?serverVersion=8.0.37" # to use mariadb: # Before doctrine/dbal < 3.7 @@ -53,15 +53,15 @@ The database connection information is stored as an environment variable called # DATABASE_URL="sqlite:///%kernel.project_dir%/var/app.db" # to use postgresql: - # DATABASE_URL="postgresql://db_user:db_password@127.0.0.1:5432/db_name?serverVersion=11&charset=utf8" + # DATABASE_URL="postgresql://db_user:db_password@127.0.0.1:5432/db_name?serverVersion=12.19 (Debian 12.19-1.pgdg120+1)&charset=utf8" # to use oracle: # DATABASE_URL="oci8://db_user:db_password@127.0.0.1:1521/db_name" -.. caution:: +.. warning:: If the username, password, host or database name contain any character considered - special in a URI (such as ``+``, ``@``, ``$``, ``#``, ``/``, ``:``, ``*``, ``!``, ``%``), + special in a URI (such as ``: / ? # [ ] @ ! $ & ' ( ) * + , ; =``), you must encode them. See `RFC 3986`_ for the full list of reserved characters. You can use the :phpfunction:`urlencode` function to encode them or the :ref:`urlencode environment variable processor `. @@ -76,7 +76,7 @@ database for you: $ php bin/console doctrine:database:create There are more options in ``config/packages/doctrine.yaml`` that you can configure, -including your ``server_version`` (e.g. 5.7 if you're using MySQL 5.7), which may +including your ``server_version`` (e.g. 8.0.37 if you're using MySQL 8.0.37), which may affect how Doctrine functions. .. tip:: @@ -84,6 +84,8 @@ affect how Doctrine functions. There are many other Doctrine commands. Run ``php bin/console list doctrine`` to see a full list. +.. _doctrine-adding-mapping: + Creating an Entity Class ------------------------ @@ -91,8 +93,6 @@ Suppose you're building an application where products need to be displayed. Without even thinking about Doctrine or databases, you already know that you need a ``Product`` object to represent those products. -.. _doctrine-adding-mapping: - You can use the ``make:entity`` command to create this class and any fields you need. The command will ask you some questions - answer them like done below: @@ -158,23 +158,23 @@ Whoa! You now have a new ``src/Entity/Product.php`` file:: // ... getter and setter methods } -.. note:: +.. tip:: - Starting in v1.44.0 - MakerBundle only supports entities using PHP attributes. + Starting in `MakerBundle`_: v1.57.0 - You can pass either ``--with-uuid`` or + ``--with-ulid`` to ``make:entity``. Leveraging Symfony's :doc:`Uid Component `, + this generates an entity with the ``id`` type as :ref:`Uuid ` + or :ref:`Ulid ` instead of ``int``. .. note:: - Confused why the price is an integer? Don't worry: this is just an example. - But, storing prices as integers (e.g. 100 = $1 USD) can avoid rounding issues. + Starting in v1.44.0 - `MakerBundle`_: only supports entities using PHP attributes. .. note:: - If you are using an SQLite database, you'll see the following error: - *PDOException: SQLSTATE[HY000]: General error: 1 Cannot add a NOT NULL - column with default value NULL*. Add a ``nullable=true`` option to the - ``description`` property to fix the problem. + Confused why the price is an integer? Don't worry: this is just an example. + But, storing prices as integers (e.g. 100 = $1 USD) can avoid rounding issues. -.. caution:: +.. warning:: There is a `limit of 767 bytes for the index key prefix`_ when using InnoDB tables in MySQL 5.6 and earlier versions. String columns with 255 @@ -199,12 +199,12 @@ The ``make:entity`` command is a tool to make life easier. But this is *your* co add/remove fields, add/remove methods or update configuration. Doctrine supports a wide variety of field types, each with their own options. -To see a full list, check out `Doctrine's Mapping Types documentation`_. +Check out the `list of Doctrine mapping types`_ in the Doctrine documentation. If you want to use XML instead of attributes, add ``type: xml`` and ``dir: '%kernel.project_dir%/config/doctrine'`` to the entity mappings in your ``config/packages/doctrine.yaml`` file. -.. caution:: +.. warning:: Be careful not to use reserved SQL keywords as your table or column names (e.g. ``GROUP`` or ``USER``). See Doctrine's `Reserved SQL keywords documentation`_ @@ -226,6 +226,11 @@ already installed: $ php bin/console make:migration +.. tip:: + + Starting in `MakerBundle`_: v1.56.0 - Passing ``--formatted`` to ``make:migration`` + generates a nice and tidy migration file. + If everything worked, you should see something like this: .. code-block:: text @@ -315,6 +320,13 @@ before, execute your migrations: $ php bin/console doctrine:migrations:migrate +.. warning:: + + If you are using an SQLite database, you'll see the following error: + *PDOException: SQLSTATE[HY000]: General error: 1 Cannot add a NOT NULL + column with default value NULL*. Add a ``nullable=true`` option to the + ``description`` property to fix the problem. + This will only execute the *one* new migration file, because DoctrineMigrationsBundle knows that the first migration was already executed earlier. Behind the scenes, it manages a ``migration_versions`` table to track this. @@ -357,7 +369,7 @@ and save it:: use App\Entity\Product; use Doctrine\ORM\EntityManagerInterface; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; class ProductController extends AbstractController { @@ -439,7 +451,7 @@ Consider the following controller code:: use App\Entity\Product; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; use Symfony\Component\Validator\Validator\ValidatorInterface; // ... @@ -449,12 +461,8 @@ Consider the following controller code:: public function createProduct(ValidatorInterface $validator): Response { $product = new Product(); - // This will trigger an error: the column isn't nullable in the database - $product->setName(null); - // This will trigger a type mismatch error: an integer is expected - $product->setPrice('1999'); - // ... + // ... update the product data somehow (e.g. with a form) ... $errors = $validator->validate($product); if (count($errors) > 0) { @@ -507,7 +515,7 @@ be able to go to ``/product/1`` to see your new product:: use App\Entity\Product; use Doctrine\ORM\EntityManagerInterface; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; // ... class ProductController extends AbstractController @@ -540,7 +548,7 @@ and injected by the dependency injection container:: use App\Entity\Product; use App\Repository\ProductRepository; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; // ... class ProductController extends AbstractController @@ -605,6 +613,8 @@ the :ref:`doctrine-queries` section. see the web debug toolbar, install the ``profiler`` :ref:`Symfony pack ` by running this command: ``composer require --dev symfony/profiler-pack``. + For more information, read the :doc:`Symfony profiler documentation `. + .. _doctrine-entity-value-resolver: Automatically Fetching Objects (EntityValueResolver) @@ -623,7 +633,7 @@ automatically! You can simplify the controller to:: use App\Entity\Product; use App\Repository\ProductRepository; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; // ... class ProductController extends AbstractController @@ -639,34 +649,6 @@ automatically! You can simplify the controller to:: That's it! The bundle uses the ``{id}`` from the route to query for the ``Product`` by the ``id`` column. If it's not found, a 404 page is generated. -This behavior is enabled by default on all your controllers. You can -disable it by setting the ``doctrine.orm.controller_resolver.auto_mapping`` -config option to ``false``. - -When disabled, you can enable it individually on the desired controllers by -using the ``MapEntity`` attribute:: - - // src/Controller/ProductController.php - namespace App\Controller; - - use App\Entity\Product; - use Symfony\Bridge\Doctrine\Attribute\MapEntity; - use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; - // ... - - class ProductController extends AbstractController - { - #[Route('/product/{id}')] - public function show( - #[MapEntity] - Product $product - ): Response { - // use the Product! - // ... - } - } - .. tip:: When enabled globally, it's possible to disable the behavior on a specific @@ -712,14 +694,41 @@ Automatic fetching works in these situations: *all* of the wildcards in your route that are actually properties on your entity (non-properties are ignored). -You can control this behavior by actually *adding* the ``MapEntity`` -attribute and using the `MapEntity options`_. +This behavior is enabled by default on all controllers. If you prefer, you can +restrict this feature to only work on route wildcards called ``id`` to look for +entities by primary key. To do so, set the option +``doctrine.orm.controller_resolver.auto_mapping`` to ``false``. + +When ``auto_mapping`` is disabled, you can configure the mapping explicitly for +any controller argument with the ``MapEntity`` attribute. You can even control +the ``EntityValueResolver`` behavior by using the `MapEntity options`_ :: + + // src/Controller/ProductController.php + namespace App\Controller; + + use App\Entity\Product; + use Symfony\Bridge\Doctrine\Attribute\MapEntity; + use Symfony\Component\HttpFoundation\Response; + use Symfony\Component\Routing\Attribute\Route; + // ... + + class ProductController extends AbstractController + { + #[Route('/product/{slug}')] + public function show( + #[MapEntity(mapping: ['slug' => 'slug'])] + Product $product + ): Response { + // use the Product! + // ... + } + } Fetch via an Expression ~~~~~~~~~~~~~~~~~~~~~~~ -If automatic fetching doesn't work, you can write an expression using the -:doc:`ExpressionLanguage component `:: +If automatic fetching doesn't work for your use case, you can write an expression +using the :doc:`ExpressionLanguage component `:: #[Route('/product/{product_id}')] public function show( @@ -732,6 +741,20 @@ In the expression, the ``repository`` variable will be your entity's Repository class and any route wildcards - like ``{product_id}`` are available as variables. +The repository method called in the expression can also return a list of entities. +In that case, update the type of your controller argument:: + + #[Route('/posts_by/{author_id}')] + public function authorPosts( + #[MapEntity(class: Post::class, expr: 'repository.findBy({"author": author_id}, {}, 10)')] + iterable $posts + ): 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}')] @@ -748,13 +771,13 @@ the default convention. If you need to get other information from the request to query the database, you can also access the request in your expression thanks to the ``request`` -variable. Let's say you pass the page limit of a list in a query parameter:: +variable. Let's say you want the first or the last comment of a product depending on a query parameter named ``sort``:: #[Route('/product/{id}/comments')] public function show( Product $product, - #[MapEntity(expr: 'repository.findBy(["product_id" => id], null, request.query.get("limit", 10)')] - iterable $comments + #[MapEntity(expr: 'repository.findOneBy({"product": id}, {"createdAt": request.query.get("sort", "DESC")})')] + Comment $comment ): Response { } @@ -823,6 +846,21 @@ control behavior: ``disabled`` If true, the ``EntityValueResolver`` will not try to replace the argument. +``message`` + An optional custom message displayed when there's a :class:`Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException`, + but **only in the development environment** (you won't see this message in production):: + + #[Route('/product/{product_id}')] + public function show( + #[MapEntity(id: 'product_id', message: 'The product does not exist')] + Product $product + ): Response { + } + +.. versionadded:: 7.1 + + The ``message`` option was introduced in Symfony 7.1. + Updating an Object ------------------ @@ -836,7 +874,7 @@ with any PHP model:: use App\Repository\ProductRepository; use Doctrine\ORM\EntityManagerInterface; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; // ... class ProductController extends AbstractController @@ -1065,17 +1103,15 @@ Learn more doctrine/associations doctrine/events - doctrine/registration_form doctrine/custom_dql_functions doctrine/dbal doctrine/multiple_entity_managers doctrine/resolve_target_entity - doctrine/reverse_engineering testing/database .. _`Doctrine`: https://www.doctrine-project.org/ .. _`RFC 3986`: https://www.ietf.org/rfc/rfc3986.txt -.. _`Doctrine's Mapping Types documentation`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/basic-mapping.html +.. _`list of Doctrine mapping types`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/basic-mapping.html#reference-mapping-types .. _`Query Builder`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/query-builder.html .. _`Doctrine Query Language`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/dql-doctrine-query-language.html .. _`Reserved SQL keywords documentation`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/basic-mapping.html#quoting-reserved-words @@ -1089,3 +1125,4 @@ Learn more .. _`PDO`: https://www.php.net/pdo .. _`available Doctrine extensions`: https://github.com/doctrine-extensions/DoctrineExtensions .. _`StofDoctrineExtensionsBundle`: https://github.com/stof/StofDoctrineExtensionsBundle +.. _`MakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html diff --git a/doctrine/associations.rst b/doctrine/associations.rst index 518a59b70cf..8dd9aa7f36b 100644 --- a/doctrine/associations.rst +++ b/doctrine/associations.rst @@ -79,6 +79,13 @@ This will generate your new entity class:: // ... getters and setters } +.. tip:: + + Starting in `MakerBundle`_: v1.57.0 - You can pass either ``--with-uuid`` or + ``--with-ulid`` to ``make:entity``. Leveraging Symfony's :doc:`Uid Component `, + this generates an entity with the ``id`` type as :ref:`Uuid ` + or :ref:`Ulid ` instead of ``int``. + Mapping the ManyToOne Relationship ---------------------------------- @@ -312,7 +319,7 @@ Now you can see this new code in action! Imagine you're inside a controller:: use App\Entity\Product; use Doctrine\ORM\EntityManagerInterface; use Symfony\Component\HttpFoundation\Response; - use Symfony\Component\Routing\Annotation\Route; + use Symfony\Component\Routing\Attribute\Route; class ProductController extends AbstractController { @@ -605,7 +612,6 @@ that behavior, use the `orphanRemoval`_ option inside ``Category``: #[ORM\OneToMany(targetEntity: Product::class, mappedBy: 'category', orphanRemoval: true)] private array $products; - Thanks to this, if the ``Product`` is removed from the ``Category``, it will be removed from the database entirely. @@ -627,3 +633,4 @@ Doctrine's `Association Mapping Documentation`_. .. _`orphanRemoval`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/working-with-associations.html#orphan-removal .. _`Mastering Doctrine Relations`: https://symfonycasts.com/screencast/doctrine-relations .. _`ArrayCollection`: https://www.doctrine-project.org/projects/doctrine-collections/en/1.6/index.html +.. _`MakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html diff --git a/doctrine/custom_dql_functions.rst b/doctrine/custom_dql_functions.rst index 1b3aa4aa185..e5b21819f58 100644 --- a/doctrine/custom_dql_functions.rst +++ b/doctrine/custom_dql_functions.rst @@ -132,7 +132,7 @@ In Symfony, you can register your custom DQL functions as follows: ->datetimeFunction('test_datetime', DatetimeFunction::class); }; -.. caution:: +.. warning:: DQL functions are instantiated by Doctrine outside of the Symfony :doc:`service container ` so you can't inject services diff --git a/doctrine/dbal.rst b/doctrine/dbal.rst index a400cee0324..4f47b61eb61 100644 --- a/doctrine/dbal.rst +++ b/doctrine/dbal.rst @@ -32,7 +32,7 @@ Then configure the ``DATABASE_URL`` environment variable in ``.env``: # .env (or override DATABASE_URL in .env.local to avoid committing your changes) # customize this line! - DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?serverVersion=5.7" + DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?serverVersion=8.0.37" Further things can be configured in ``config/packages/doctrine.yaml`` - see :ref:`reference-dbal-configuration`. Remove the ``orm`` key in that file diff --git a/doctrine/events.rst b/doctrine/events.rst index 23373d827f4..dcd97126b7c 100644 --- a/doctrine/events.rst +++ b/doctrine/events.rst @@ -391,9 +391,9 @@ listener in the Symfony application by creating a new service for it and ; }; -.. versionadded:: 2.7.2 +.. versionadded:: 2.8.0 - The `AsDoctrineListener`_ attribute was introduced in DoctrineBundle 2.7.2. + The `AsDoctrineListener`_ attribute was introduced in DoctrineBundle 2.8.0. .. tip:: @@ -404,4 +404,4 @@ listener in the Symfony application by creating a new service for it and .. _`lifecycle events`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/events.html#lifecycle-events .. _`official docs about Doctrine events`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/events.html .. _`DoctrineMongoDBBundle documentation`: https://symfony.com/doc/current/bundles/DoctrineMongoDBBundle/index.html -.. _`AsDoctrineListener`: https://github.com/doctrine/DoctrineBundle/blob/2.10.x/Attribute/AsDoctrineListener.php +.. _`AsDoctrineListener`: https://github.com/doctrine/DoctrineBundle/blob/2.12.x/src/Attribute/AsDoctrineListener.php diff --git a/doctrine/multiple_entity_managers.rst b/doctrine/multiple_entity_managers.rst index 014d9e4dccb..1a56c55ddad 100644 --- a/doctrine/multiple_entity_managers.rst +++ b/doctrine/multiple_entity_managers.rst @@ -15,7 +15,7 @@ entities, each with their own database connection strings or separate cache conf advanced and not usually required. Be sure you actually need multiple entity managers before adding in this layer of complexity. -.. caution:: +.. warning:: Entities cannot define associations across different entity managers. If you need that, there are `several alternatives`_ that require some custom setup. @@ -142,7 +142,7 @@ and ``customer``. The ``default`` entity manager manages entities in the entities in ``src/Entity/Customer``. You've also defined two connections, one for each entity manager, but you are free to define the same connection for both. -.. caution:: +.. warning:: When working with multiple connections and entity managers, you should be explicit about which configuration you want. If you *do* omit the name of @@ -251,7 +251,7 @@ The same applies to repository calls:: } } -.. caution:: +.. warning:: One entity can be managed by more than one entity manager. This however results in unexpected behavior when extending from ``ServiceEntityRepository`` diff --git a/doctrine/registration_form.rst b/doctrine/registration_form.rst deleted file mode 100644 index 7063b7157a4..00000000000 --- a/doctrine/registration_form.rst +++ /dev/null @@ -1,15 +0,0 @@ -How to Implement a Registration Form -==================================== - -This article has been removed because it only explained things that are -already explained in other articles. Specifically, to implement a registration -form you must: - -#. :ref:`Define a class to represent users `; -#. :doc:`Create a form ` to ask for the registration information (you can - generate this with the ``make:registration-form`` command provided by the `MakerBundle`_); -#. Create :doc:`a controller ` to :ref:`process the form `; -#. :ref:`Protect some parts of your application ` so that - only registered users can access to them. - -.. _`MakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html diff --git a/doctrine/reverse_engineering.rst b/doctrine/reverse_engineering.rst deleted file mode 100644 index 35c8e729c2d..00000000000 --- a/doctrine/reverse_engineering.rst +++ /dev/null @@ -1,15 +0,0 @@ -How to Generate Entities from an Existing Database -================================================== - -.. caution:: - - The ``doctrine:mapping:import`` command used to generate Doctrine entities - from existing databases was deprecated by Doctrine in 2019 and there's no - replacement for it. - - Instead, you can use the ``make:entity`` command from `Symfony Maker Bundle`_ - to help you generate the code of your Doctrine entities. This command - requires manual supervision because it doesn't generate entities from - existing databases. - -.. _`Symfony Maker Bundle`: https://symfony.com/bundles/SymfonyMakerBundle/current/index.html diff --git a/emoji.rst b/emoji.rst new file mode 100644 index 00000000000..551497f0c76 --- /dev/null +++ b/emoji.rst @@ -0,0 +1,173 @@ +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: + +.. _installation: + +.. code-block:: terminal + + $ composer require symfony/emoji + +.. include:: /components/require_autoload.rst.inc + +The data needed to store the transliteration of all emojis (~5,000) into all +languages take a considerable disk space. + +If you need to save disk space (e.g. because you deploy to some service with tight +size constraints), run this command (e.g. as an automated script after ``composer install``) +to compress the internal Symfony emoji data files using the PHP ``zlib`` extension: + +.. code-block:: terminal + + # adjust the path to the 'compress' binary based on your application installation + $ php ./vendor/symfony/emoji/Resources/bin/compress + +.. _emoji-transliteration: + +Emoji Transliteration +--------------------- + +The ``EmojiTransliterator`` class offers a way to translate emojis into their +textual representation in all languages based on the `Unicode CLDR dataset`_:: + + use Symfony\Component\Emoji\EmojiTransliterator; + + // Describe emojis in English + $transliterator = EmojiTransliterator::create('en'); + $transliterator->transliterate('Menus with 🍕 or 🍝'); + // => 'Menus with pizza or spaghetti' + + // Describe emojis in Ukrainian + $transliterator = EmojiTransliterator::create('uk'); + $transliterator->transliterate('Menus with 🍕 or 🍝'); + // => 'Menus with піца or спагеті' + +.. tip:: + + When using the :ref:`slugger ` from the String component, + you can combine it with the ``EmojiTransliterator`` to :ref:`slugify emojis `. + +Transliterating Emoji Text Short Codes +-------------------------------------- + +Services like GitHub and Slack allows to include emojis in your messages using +text short codes (e.g. you can add the ``:+1:`` code to render the 👍 emoji). + +Symfony also provides a feature to transliterate emojis into short codes and vice +versa. The short codes are slightly different on each service, so you must pass +the name of the service as an argument when creating the transliterator. + +GitHub Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Convert emojis to GitHub short codes with the ``emoji-github`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-github'); + $transliterator->transliterate('Teenage 🐢 really love 🍕'); + // => 'Teenage :turtle: really love :pizza:' + +Convert GitHub short codes to emojis with the ``github-emoji`` locale:: + + $transliterator = EmojiTransliterator::create('github-emoji'); + $transliterator->transliterate('Teenage :turtle: really love :pizza:'); + // => 'Teenage 🐢 really love 🍕' + +Gitlab Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Convert emojis to Gitlab short codes with the ``emoji-gitlab`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-gitlab'); + $transliterator->transliterate('Breakfast with 🥝 or 🥛'); + // => 'Breakfast with :kiwi: or :milk:' + +Convert Gitlab short codes to emojis with the ``gitlab-emoji`` locale:: + + $transliterator = EmojiTransliterator::create('gitlab-emoji'); + $transliterator->transliterate('Breakfast with :kiwi: or :milk:'); + // => 'Breakfast with 🥝 or 🥛' + +Slack Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Convert emojis to Slack short codes with the ``emoji-slack`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-slack'); + $transliterator->transliterate('Menus with 🥗 or 🧆'); + // => 'Menus with :green_salad: or :falafel:' + +Convert Slack short codes to emojis with the ``slack-emoji`` locale:: + + $transliterator = EmojiTransliterator::create('slack-emoji'); + $transliterator->transliterate('Menus with :green_salad: or :falafel:'); + // => 'Menus with 🥗 or 🧆' + +.. _text-emoji: + +Universal Emoji Short Codes Transliteration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you don't know which service was used to generate the short codes, you can use +the ``text-emoji`` locale, which combines all codes from all services:: + + $transliterator = EmojiTransliterator::create('text-emoji'); + + // Github short codes + $transliterator->transliterate('Breakfast with :kiwi-fruit: or :milk-glass:'); + // Gitlab short codes + $transliterator->transliterate('Breakfast with :kiwi: or :milk:'); + // Slack short codes + $transliterator->transliterate('Breakfast with :kiwifruit: or :glass-of-milk:'); + + // all the above examples produce the same result: + // => 'Breakfast with 🥝 or 🥛' + +You can convert emojis to short codes with the ``emoji-text`` locale:: + + $transliterator = EmojiTransliterator::create('emoji-text'); + $transliterator->transliterate('Breakfast with 🥝 or 🥛'); + // => 'Breakfast with :kiwifruit: or :milk-glass: + +Inverse Emoji Transliteration +----------------------------- + +Given the textual representation of an emoji, you can reverse it back to get the +actual emoji thanks to the :ref:`emojify filter `: + +.. code-block:: twig + + {{ 'I like :kiwi-fruit:'|emojify }} {# renders: I like 🥝 #} + {{ 'I like :kiwi:'|emojify }} {# renders: I like 🥝 #} + {{ 'I like :kiwifruit:'|emojify }} {# renders: I like 🥝 #} + +By default, ``emojify`` uses the :ref:`text catalog `, which +merges the emoji text codes of all services. If you prefer, you can select a +specific catalog to use: + +.. code-block:: twig + + {{ 'I :green-heart: this'|emojify }} {# renders: I 💚 this #} + {{ ':green_salad: is nice'|emojify('slack') }} {# renders: 🥗 is nice #} + {{ 'My :turtle: has no name yet'|emojify('github') }} {# renders: My 🐢 has no name yet #} + {{ ':kiwi: is a great fruit'|emojify('gitlab') }} {# renders: 🥝 is a great fruit #} + +Removing Emojis +--------------- + +The ``EmojiTransliterator`` can also be used to remove all emojis from a string, +via the special ``strip`` locale:: + + use Symfony\Component\Emoji\EmojiTransliterator; + + $transliterator = EmojiTransliterator::create('strip'); + $transliterator->transliterate('🎉Hey!🥳 🎁Happy Birthday!🎁'); + // => 'Hey! Happy Birthday!' + +.. _`Unicode CLDR dataset`: https://github.com/unicode-org/cldr diff --git a/event_dispatcher.rst b/event_dispatcher.rst index ef9f74c4ae9..27885af267b 100644 --- a/event_dispatcher.rst +++ b/event_dispatcher.rst @@ -41,6 +41,9 @@ The most common way to listen to an event is to register an **event listener**:: // Customize your response object to display the exception details $response = new Response(); $response->setContent($message); + // the exception message can contain unfiltered user input; + // set the content-type to text to avoid XSS issues + $response->headers->set('Content-Type', 'text/plain; charset=utf-8'); // HttpExceptionInterface is a special type of exception that // holds status code and header details @@ -162,7 +165,10 @@ having to add any configuration in external files:: } } -You can add multiple ``#[AsEventListener()]`` attributes to configure different methods:: +You can add multiple ``#[AsEventListener]`` attributes to configure different methods. +The ``method`` property is optional, and when not defined, it defaults to +``on`` + uppercased event name. In the example below, the ``'foo'`` event listener +doesn't explicitly define its method, so the ``onFoo()`` method will be called:: namespace App\EventListener; @@ -198,7 +204,7 @@ can also be applied to methods directly:: final class MyMultiListener { - #[AsEventListener()] + #[AsEventListener] public function onCustomEvent(CustomEvent $event): void { // ... @@ -795,3 +801,11 @@ could listen to the ``mailer.post_send`` event and change the method's return va That's it! Your subscriber should be called automatically (or read more about :ref:`event subscriber configuration `). + +Learn More +---------- + +- :ref:`The Request-Response Lifecycle ` +- :doc:`/reference/events` +- :ref:`Security-related Events ` +- :doc:`/components/event_dispatcher` diff --git a/form/bootstrap5.rst b/form/bootstrap5.rst index 400747bba12..db098a1ba09 100644 --- a/form/bootstrap5.rst +++ b/form/bootstrap5.rst @@ -171,7 +171,7 @@ class to the label: ], // ... -.. caution:: +.. warning:: Switches only work with **checkbox**. @@ -201,7 +201,7 @@ class to the ``row_attr`` option. } }) }} -.. caution:: +.. warning:: If you fill the ``help`` option of your form, it will also be rendered as part of the group. @@ -239,7 +239,7 @@ of your form type. } }) }} -.. caution:: +.. warning:: You **must** provide a ``label`` and a ``placeholder`` to make floating labels work properly. diff --git a/form/create_custom_field_type.rst b/form/create_custom_field_type.rst index e0eb08f3665..0d92a967fa0 100644 --- a/form/create_custom_field_type.rst +++ b/form/create_custom_field_type.rst @@ -449,7 +449,7 @@ are some examples of Twig block names for the postal address type: ``postal_address_zipCode_label`` The label block of the ZIP Code field. -.. caution:: +.. warning:: When the name of your form class matches any of the built-in field types, your form might not be rendered correctly. A form type named @@ -465,7 +465,6 @@ Symfony passes a series of variables to the template used to render the form type. You can also pass your own variables, which can be based on the options defined by the form or be completely independent:: - // src/Form/Type/PostalAddressType.php namespace App\Form\Type; diff --git a/form/data_mappers.rst b/form/data_mappers.rst index cb5c7936701..38c92ce35ae 100644 --- a/form/data_mappers.rst +++ b/form/data_mappers.rst @@ -126,7 +126,7 @@ in your form type:: } } -.. caution:: +.. warning:: The data passed to the mapper is *not yet validated*. This means that your objects should allow being created in an invalid state in order to produce @@ -215,7 +215,7 @@ If available, these options have priority over the property path accessor and the default data mapper will still use the :doc:`PropertyAccess component ` for the other form fields. -.. caution:: +.. warning:: When a form has the ``inherit_data`` option set to ``true``, it does not use the data mapper and lets its parent map inner values. diff --git a/form/data_transformers.rst b/form/data_transformers.rst index 4e81fc3e930..db051a04bbc 100644 --- a/form/data_transformers.rst +++ b/form/data_transformers.rst @@ -8,7 +8,7 @@ can be rendered as a ``yyyy-MM-dd``-formatted input text box. Internally, a data converts the ``DateTime`` value of the field to a ``yyyy-MM-dd`` formatted string when rendering the form, and then back to a ``DateTime`` object on submit. -.. caution:: +.. warning:: When a form field has the ``inherit_data`` option set to ``true``, data transformers are not applied to that field. @@ -340,7 +340,7 @@ that, after a successful submission, the Form component will pass a real If the issue isn't found, a form error will be created for that field and its error message can be controlled with the ``invalid_message`` field option. -.. caution:: +.. warning:: Be careful when adding your transformers. For example, the following is **wrong**, as the transformer would be applied to the entire form, instead of just this @@ -472,7 +472,7 @@ Which transformer you need depends on your situation. To use the view transformer, call ``addViewTransformer()``. -.. caution:: +.. warning:: Be careful with model transformers and :doc:`Collection ` field types. diff --git a/form/direct_submit.rst b/form/direct_submit.rst index 5931b47b98f..7a08fb6978a 100644 --- a/form/direct_submit.rst +++ b/form/direct_submit.rst @@ -17,7 +17,7 @@ control over when exactly your form is submitted and what data is passed to it:: $form = $this->createForm(TaskType::class, $task); if ($request->isMethod('POST')) { - $form->submit($request->request->all($form->getName())); + $form->submit($request->getPayload()->get($form->getName())); if ($form->isSubmitted() && $form->isValid()) { // perform some action... @@ -41,7 +41,7 @@ the fields defined by the form class. Otherwise, you'll see a form validation er if ($request->isMethod('POST')) { // '$json' represents payload data sent by React/Angular/Vue // the merge of parameters is needed to submit all form fields - $form->submit(array_merge($json, $request->request->all())); + $form->submit(array_merge($json, $request->getPayload()->all())); // ... } @@ -65,7 +65,7 @@ the fields defined by the form class. Otherwise, you'll see a form validation er argument to ``submit()``. Passing ``false`` will remove any missing fields within the form object. Otherwise, the missing fields will be set to ``null``. -.. caution:: +.. warning:: When the second parameter ``$clearMissing`` is ``false``, like with the "PATCH" method, the validation will only apply to the submitted fields. If @@ -73,4 +73,4 @@ the fields defined by the form class. Otherwise, you'll see a form validation er manually so that they are validated:: // 'email' and 'username' are added manually to force their validation - $form->submit(array_merge(['email' => null, 'username' => null], $request->request->all()), false); + $form->submit(array_merge(['email' => null, 'username' => null], $request->getPayload()->all()), false); diff --git a/form/dynamic_form_modification.rst b/form/dynamic_form_modification.rst index 3159f927bd0..09be80ebb5a 100644 --- a/form/dynamic_form_modification.rst +++ b/form/dynamic_form_modification.rst @@ -9,7 +9,7 @@ how to customize your form based on three common use-cases: Example: you have a "Product" form and need to modify/add/remove a field based on the data on the underlying Product being edited. -2) :ref:`How to dynamically Generate Forms Based on user Data ` +2) :ref:`How to Dynamically Generate Forms Based on User Data ` Example: you create a "Friend Message" form and need to build a drop-down that contains only users that are friends with the *current* authenticated @@ -188,7 +188,7 @@ Great! Now use that in your form class:: .. _form-events-user-data: -How to dynamically Generate Forms Based on user Data +How to Dynamically Generate Forms Based on User Data ---------------------------------------------------- Sometimes you want a form to be generated dynamically based not only on data @@ -455,7 +455,7 @@ The type would now look like:: ]) ; - $formModifier = function (FormInterface $form, Sport $sport = null): void { + $formModifier = function (FormInterface $form, ?Sport $sport = null): void { $positions = null === $sport ? [] : $sport->getAvailablePositions(); $form->add('position', EntityType::class, [ @@ -487,7 +487,7 @@ The type would now look like:: $formModifier($event->getForm()->getParent(), $sport); } ); - + // by default, action does not appear in the
tag // you can set this value by passing the controller route $builder->setAction($options['action']); @@ -546,7 +546,7 @@ field according to the current selection in the ``sport`` field: .. code-block:: html+twig {# templates/meetup/create.html.twig #} - {{ form_start(form, { attr: { id: 'supply_history_form' } }) }} + {{ form_start(form, { attr: { id: 'sport_meetup_form' } }) }} {{ form_row(form.sport) }} {# `` element. -.. caution:: +.. warning:: + + As HTML5 number format is normalized, it is incompatible with the ``grouping`` + option. + +input +~~~~~ + +**type**: ``string`` **default**: ``float`` + +By default, the money value is converted to a ``float`` PHP type. If you need the +value to be converted into an integer (e.g. because some library needs money +values stored in cents as integers) set this option to ``integer``. + +.. versionadded:: 7.1 - As HTML5 number format is normalized, it is incompatible with ``grouping`` option. + The ``input`` option was introduced in Symfony 7.1. scale ~~~~~ diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst index 86d8eda3116..7e125a5fd05 100644 --- a/reference/forms/types/number.rst +++ b/reference/forms/types/number.rst @@ -10,8 +10,6 @@ that you want to use for your number. +---------------------------+----------------------------------------------------------------------+ | Default invalid message | Please enter a number. | +---------------------------+----------------------------------------------------------------------+ -| Legacy invalid message | The value {{ value }} is not valid. | -+---------------------------+----------------------------------------------------------------------+ | Parent type | :doc:`FormType ` | +---------------------------+----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\NumberType` | diff --git a/reference/forms/types/options/_date_limitation.rst.inc b/reference/forms/types/options/_date_limitation.rst.inc index 4e5b1be4c87..04106ee7e21 100644 --- a/reference/forms/types/options/_date_limitation.rst.inc +++ b/reference/forms/types/options/_date_limitation.rst.inc @@ -1,4 +1,4 @@ -.. caution:: +.. warning:: If ``timestamp`` is used, ``DateType`` is limited to dates between Fri, 13 Dec 1901 20:45:54 UTC and Tue, 19 Jan 2038 03:14:07 UTC on 32bit diff --git a/reference/forms/types/options/choice_name.rst.inc b/reference/forms/types/options/choice_name.rst.inc index 4ec8abb6ffe..4268c307d17 100644 --- a/reference/forms/types/options/choice_name.rst.inc +++ b/reference/forms/types/options/choice_name.rst.inc @@ -25,7 +25,7 @@ By default, the choice key or an incrementing integer may be used (starting at ` See the :ref:`"choice_loader" option documentation `. -.. caution:: +.. warning:: The configured value must be a valid form name. Make sure to only return valid names when using a callable. Valid form names must be composed of diff --git a/reference/forms/types/options/constraints.rst.inc b/reference/forms/types/options/constraints.rst.inc index 7aab319f302..3e1af29f3ab 100644 --- a/reference/forms/types/options/constraints.rst.inc +++ b/reference/forms/types/options/constraints.rst.inc @@ -1,7 +1,7 @@ ``constraints`` ~~~~~~~~~~~~~~~ -**type**: ``array`` or :class:`Symfony\\Component\\Validator\\Constraint` **default**: ``null`` +**type**: ``array`` or :class:`Symfony\\Component\\Validator\\Constraint` **default**: ``[]`` Allows you to attach one or more validation constraints to a specific field. For more information, see :ref:`Adding Validation `. diff --git a/reference/forms/types/options/data.rst.inc b/reference/forms/types/options/data.rst.inc index c3562d0a8b1..34f86e7c4c6 100644 --- a/reference/forms/types/options/data.rst.inc +++ b/reference/forms/types/options/data.rst.inc @@ -16,7 +16,7 @@ an individual field, you can set it in the data option:: 'data' => 'abcdef', ]); -.. caution:: +.. warning:: The ``data`` option *always* overrides the value taken from the domain data (object) when rendering. This means the object value is also overridden when diff --git a/reference/forms/types/options/empty_data_description.rst.inc b/reference/forms/types/options/empty_data_description.rst.inc index e654a7037df..b143b9438fe 100644 --- a/reference/forms/types/options/empty_data_description.rst.inc +++ b/reference/forms/types/options/empty_data_description.rst.inc @@ -22,7 +22,7 @@ initial value in the rendered form. :doc:`/form/use_empty_data` article for more details about these options. -.. caution:: +.. warning:: :doc:`Form data transformers ` will still be applied to the ``empty_data`` value. This means that an empty string will diff --git a/reference/forms/types/options/inherit_data.rst.inc b/reference/forms/types/options/inherit_data.rst.inc index 1b63cc4b56f..f35f6d56b00 100644 --- a/reference/forms/types/options/inherit_data.rst.inc +++ b/reference/forms/types/options/inherit_data.rst.inc @@ -7,7 +7,7 @@ This option determines if the form will inherit data from its parent form. This can be useful if you have a set of fields that are duplicated across multiple forms. See :doc:`/form/inherit_data_option`. -.. caution:: +.. warning:: When a field has the ``inherit_data`` option set, it uses the data of the parent form as is. This means that diff --git a/reference/forms/types/options/sanitize_html.rst.inc b/reference/forms/types/options/sanitize_html.rst.inc index 1f906fd1354..2b5e8a3515b 100644 --- a/reference/forms/types/options/sanitize_html.rst.inc +++ b/reference/forms/types/options/sanitize_html.rst.inc @@ -5,7 +5,7 @@ sanitize_html When ``true``, the text input will be sanitized using the :doc:`Symfony HTML Sanitizer component ` after the form is -submitted. This protects the form input against XSS, clickjacking and CSS +submitted. This protects the form input against :ref:`XSS `, clickjacking and CSS injection. .. note:: diff --git a/reference/forms/types/options/value.rst.inc b/reference/forms/types/options/value.rst.inc index ddbfff6660d..e4669faa7e4 100644 --- a/reference/forms/types/options/value.rst.inc +++ b/reference/forms/types/options/value.rst.inc @@ -6,7 +6,7 @@ The value that's actually used as the value for the checkbox or radio button. This does not affect the value that's set on your object. -.. caution:: +.. warning:: To make a checkbox or radio button checked by default, use the `data`_ option. diff --git a/reference/forms/types/password.rst b/reference/forms/types/password.rst index 7fb760471ef..59e40fb19d1 100644 --- a/reference/forms/types/password.rst +++ b/reference/forms/types/password.rst @@ -8,8 +8,6 @@ The ``PasswordType`` field renders an input password text box. +---------------------------+------------------------------------------------------------------------+ | Default invalid message | The password is invalid. | +---------------------------+------------------------------------------------------------------------+ -| Legacy invalid message | The value {{ value }} is not valid. | -+---------------------------+------------------------------------------------------------------------+ | Parent type | :doc:`TextType ` | +---------------------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\PasswordType` | @@ -45,7 +43,7 @@ Data passed to the form must be a :class:`Symfony\\Component\\Security\\Core\\User\\PasswordAuthenticatedUserInterface` object. -.. caution:: +.. warning:: To minimize the risk of leaking the plain password, this option can only be used with the :ref:`"mapped" option ` diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst index ce985488c76..b46ca298c53 100644 --- a/reference/forms/types/percent.rst +++ b/reference/forms/types/percent.rst @@ -14,8 +14,6 @@ the input. +---------------------------+-----------------------------------------------------------------------+ | Default invalid message | Please enter a percentage value. | +---------------------------+-----------------------------------------------------------------------+ -| Legacy invalid message | The value {{ value }} is not valid. | -+---------------------------+-----------------------------------------------------------------------+ | Parent type | :doc:`FormType ` | +---------------------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\PercentType` | diff --git a/reference/forms/types/radio.rst b/reference/forms/types/radio.rst index 7702b87cbad..7ab90086803 100644 --- a/reference/forms/types/radio.rst +++ b/reference/forms/types/radio.rst @@ -15,8 +15,6 @@ If you want to have a boolean field, use :doc:`CheckboxType ` | +---------------------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\RadioType` | diff --git a/reference/forms/types/range.rst b/reference/forms/types/range.rst index 294023ce0c6..06eebfd5473 100644 --- a/reference/forms/types/range.rst +++ b/reference/forms/types/range.rst @@ -9,8 +9,6 @@ The ``RangeType`` field is a slider that is rendered using the HTML5 +---------------------------+---------------------------------------------------------------------+ | Default invalid message | Please choose a valid range. | +---------------------------+---------------------------------------------------------------------+ -| Legacy invalid message | The value {{ value }} is not valid. | -+---------------------------+---------------------------------------------------------------------+ | Parent type | :doc:`TextType ` | +---------------------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\RangeType` | diff --git a/reference/forms/types/repeated.rst b/reference/forms/types/repeated.rst index e5bd0cd4520..36211237bbd 100644 --- a/reference/forms/types/repeated.rst +++ b/reference/forms/types/repeated.rst @@ -11,8 +11,6 @@ accuracy. +---------------------------+------------------------------------------------------------------------+ | Default invalid message | The values do not match. | +---------------------------+------------------------------------------------------------------------+ -| Legacy invalid message | The value {{ value }} is not valid. | -+---------------------------+------------------------------------------------------------------------+ | Parent type | :doc:`FormType ` | +---------------------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\RepeatedType` | diff --git a/reference/forms/types/search.rst b/reference/forms/types/search.rst index e38021bc461..ad4a8f7978a 100644 --- a/reference/forms/types/search.rst +++ b/reference/forms/types/search.rst @@ -4,15 +4,11 @@ SearchType Field This renders an ```` field, which is a text box with special functionality supported by some browsers. -Read about the input search field at `DiveIntoHTML5.info`_ - +---------------------------+----------------------------------------------------------------------+ | Rendered as | ``input search`` field | +---------------------------+----------------------------------------------------------------------+ | Default invalid message | Please enter a valid search term. | +---------------------------+----------------------------------------------------------------------+ -| Legacy invalid message | The value {{ value }} is not valid. | -+---------------------------+----------------------------------------------------------------------+ | Parent type | :doc:`TextType ` | +---------------------------+----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\SearchType` | @@ -65,5 +61,3 @@ The default value is ``''`` (the empty string). .. include:: /reference/forms/types/options/row_attr.rst.inc .. include:: /reference/forms/types/options/trim.rst.inc - -.. _`DiveIntoHTML5.info`: http://diveintohtml5.info/forms.html#type-search diff --git a/reference/forms/types/tel.rst b/reference/forms/types/tel.rst index 675f8e3f5cd..e8ab9c322fe 100644 --- a/reference/forms/types/tel.rst +++ b/reference/forms/types/tel.rst @@ -15,8 +15,6 @@ to input phone numbers. +---------------------------+-------------------------------------------------------------------+ | Default invalid message | Please provide a valid phone number. | +---------------------------+-------------------------------------------------------------------+ -| Legacy invalid message | The value {{ value }} is not valid. | -+---------------------------+-------------------------------------------------------------------+ | Parent type | :doc:`TextType ` | +---------------------------+-------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TelType` | diff --git a/reference/forms/types/textarea.rst b/reference/forms/types/textarea.rst index 0460bca6942..47a32368b99 100644 --- a/reference/forms/types/textarea.rst +++ b/reference/forms/types/textarea.rst @@ -19,10 +19,10 @@ Renders a ``textarea`` HTML element. ``