Jul 29, 2022 · Jul 26, 2022 · Jul 26, 2022 · Jul 26, 2022 · Aug 16, 2022
diff --git a/contributing/code/standards.rst b/contributing/code/standards.rst
     */
    class FooBar
    {
        const SOME_CONST = 42;
 publicconst SOME_CONST = 42;

        /**
         * @var string
         */
        private $fooBar;

        private $qux;

        /**
         * @paramstring$dummySome argument description
         * @param $dummysome argument description
         */
        public function __construct($dummy, Qux $qux)
        public function __construct(string$dummy, Qux $qux)
        {
            $this->fooBar = $this->transformText($dummy);
            $this->qux = $qux;
        }

        /**
         * @return string
         *
         * @deprecated
         */
        public function someDeprecatedMethod()
        public function someDeprecatedMethod(): string
        {
            trigger_deprecation('symfony/package-name', '5.1', 'The %s() method is deprecated, use Acme\Baz::someMethod() instead.', __METHOD__);

        /**
         * Transforms the input given as the first argument.
         *
         * @param bool|string $dummy   Some argument description
         * @param array       $options An options collection to be used within the transformation
         * @param $options an options collection to be used within the transformation
         *
         * @return string|null The transformed input
         *
         * @throws \RuntimeException When an invalid option is provided
         * @throws \RuntimeException when an invalid option is provided
         */
        private function transformText($dummy, array $options = [])
        private function transformText(bool|string$dummy, array $options = []): ?string
        {
            $defaultOptions = [
                'some_default' => 'values',
                }
            }

            $mergedOptions = array_merge(
                $defaultOptions,
                $options
            );
            $mergedOptions = array_merge($defaultOptions, $options);

            if (true === $dummy) {
                return 'something';
            }

            if (is_string($dummy)) {
            if (\is_string($dummy)) {
                if ('values' === $mergedOptions['some_default']) {
                    return substr($dummy, 0, 5);
                }

        /**
         * Performs some basic operations for a given value.
         *
         * @param mixed $value     Some value to operate against
         * @param bool  $theSwitch Some switch to control the method's flow
         */
        private function performOperations($value = null, $theSwitch = false)
        private function performOperations(mixed$value = null, bool $theSwitch = false)
        {
            if (!$theSwitch) {
                return;
 * Use ``return null;`` when a function explicitly returns ``null`` values and
  use ``return;`` when the function returns ``void`` values;

 * Do not add the ``void`` return type to methods in tests;

 * Use braces to indicate control structure body regardless of the number of
  statements it contains;

 Documentation
 ~~~~~~~~~~~~~

 * Add PHPDoc blocks for all classes, methods, and functions (though you may
  be asked to remove PHPDoc that do not add value);
 * Add PHPDoc blocks for classes, methods, and functions only when they add
  relevant information that does not duplicate the name, native type
  declaration or context (e.g. ``instanceof`` checks);

 * Only use annotations and types defined in `the PHPDoc reference`_. In
  order to improve types for static analysis, the following annotations are
  also allowed:

  * `Generics`_, with the exception of ``@template-covariant``.
  * `Conditional return types`_ using the vendor-prefixed ``@psalm-return``;
  * `Class constants`_;
  * `Callable types`_;

 * Group annotations together so that annotations of the same type immediately
  follow each other, and annotations of a different type are separated by a
  single blank line;

 * Omit the ``@return`` tag if the method does not return anything;

 * The ``@package`` and ``@subpackage`` annotations are not used;
 * Omit the ``@return`` annotation if the method does not return anything;

 * Don't inline PHPDoc blocks, even when they contain just one tag (e.g. don't
  put ``/** {@inheritdoc} */`` in a single line);
 * Don't use one-line PHPDoc blocks on classes, methods and functions, even
  when they contain just one annotation (e.g. don't put ``/** {@inheritdoc} */``
  in a single line);

 * When adding a new class or when making significant changes to an existing class,
  an ``@author`` tag with personal contact information may be added, or expanded.
 .. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
 .. _`constructor property promotion`: https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion
 .. _`trailing comma`: https://wiki.php.net/rfc/trailing_comma_in_parameter_list
 .. _`the PHPDoc reference`: https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html
 .. _`Conditional return types`: https://psalm.dev/docs/annotating_code/type_syntax/conditional_types/
 .. _`Class constants`: https://psalm.dev/docs/annotating_code/type_syntax/value_types/#regular-class-constants
 .. _`Callable types`: https://psalm.dev/docs/annotating_code/type_syntax/callable_types/
 .. _`Generics`: https://psalm.dev/docs/annotating_code/templated_annotations/
Original file line number	Diff line number	Diff line change
Expand Up		@@ -47,30 +47,27 @@ short example containing most features described below::
		*/
		class FooBar
		{
		const SOME_CONST = 42;
		publicconst SOME_CONST = 42;

		/**
		* @var string
		*/
		private $fooBar;

		private $qux;

		/**
		* @paramstring$dummySome argument description
		* @param $dummysome argument description
		*/
		public function __construct($dummy, Qux $qux)
		public function __construct(string$dummy, Qux $qux)
		{
		$this->fooBar = $this->transformText($dummy);
		$this->qux = $qux;
		}

		/**
		* @return string
		*
		* @deprecated
		*/
		public function someDeprecatedMethod()
		public function someDeprecatedMethod(): string
		{
		trigger_deprecation('symfony/package-name', '5.1', 'The %s() method is deprecated, use Acme\Baz::someMethod() instead.', __METHOD__);

Expand All		@@ -80,14 +77,11 @@ short example containing most features described below::
		/**
		* Transforms the input given as the first argument.
		*
		* @param bool\|string $dummy Some argument description
		* @param array $options An options collection to be used within the transformation
		* @param $options an options collection to be used within the transformation
		*
		* @return string\|null The transformed input
		*
		* @throws \RuntimeException When an invalid option is provided
		* @throws \RuntimeException when an invalid option is provided
		*/
		private function transformText($dummy, array $options = [])
		private function transformText(bool\|string$dummy, array $options = []): ?string
		{
		$defaultOptions = [
		'some_default' => 'values',
Expand All		@@ -100,16 +94,13 @@ short example containing most features described below::
		}
		}

		$mergedOptions = array_merge(
		$defaultOptions,
		$options
		);
		$mergedOptions = array_merge($defaultOptions, $options);

		if (true === $dummy) {
		return 'something';
		}

		if (is_string($dummy)) {
		if (\is_string($dummy)) {
		if ('values' === $mergedOptions['some_default']) {
		return substr($dummy, 0, 5);
		}
Expand All		@@ -122,11 +113,8 @@ short example containing most features described below::

		/**
		* Performs some basic operations for a given value.
		*
		* @param mixed $value Some value to operate against
		* @param bool $theSwitch Some switch to control the method's flow
		*/
		private function performOperations($value = null, $theSwitch = false)
		private function performOperations(mixed$value = null, bool $theSwitch = false)
		{
		if (!$theSwitch) {
		return;
Expand DownExpand Up		@@ -162,6 +150,8 @@ Structure
		* Use ``return null;`` when a function explicitly returns ``null`` values and
		use ``return;`` when the function returns ``void`` values;

		* Do not add the ``void`` return type to methods in tests;

		* Use braces to indicate control structure body regardless of the number of
		statements it contains;

Expand DownExpand Up		@@ -265,19 +255,28 @@ Service Naming Conventions
		Documentation
		~~~~~~~~~~~~~

		* Add PHPDoc blocks for all classes, methods, and functions (though you may
		be asked to remove PHPDoc that do not add value);
		* Add PHPDoc blocks for classes, methods, and functions only when they add
		relevant information that does not duplicate the name, native type
		declaration or context (e.g. ``instanceof`` checks);

		* Only use annotations and types defined in `the PHPDoc reference`_. In
		order to improve types for static analysis, the following annotations are
		also allowed:

		* `Generics`_, with the exception of ``@template-covariant``.
Copy link Member derrabusJul 26, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Why do we make that exception? Copy link MemberAuthor wouterjJul 26, 2022• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. As far as I know, this is not (yet?) supported by PHPstan. Copy link Member stofAug 16, 2022 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. phpstan supports it (otherwise, they would not havethis blog post explaining it)
		* `Conditional return types`_ using the vendor-prefixed ``@psalm-return``;
		* `Class constants`_;
		* `Callable types`_;

		* Group annotations together so that annotations of the same type immediately
		follow each other, and annotations of a different type are separated by a
		single blank line;

		* Omit the ``@return`` tag if the method does not return anything;

		* The ``@package`` and ``@subpackage`` annotations are not used;
		* Omit the ``@return`` annotation if the method does not return anything;

		* Don't inline PHPDoc blocks, even when they contain just one tag (e.g. don't
		put ``/** {@inheritdoc} */`` in a single line);
		* Don't use one-line PHPDoc blocks on classes, methods and functions, even
		when they contain just one annotation (e.g. don't put ``/** {@inheritdoc} */``
		in a single line);

		* When adding a new class or when making significant changes to an existing class,
		an ``@author`` tag with personal contact information may be added, or expanded.
Expand All		@@ -303,3 +302,8 @@ License
		.. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
		.. _`constructor property promotion`: https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion
		.. _`trailing comma`: https://wiki.php.net/rfc/trailing_comma_in_parameter_list
		.. _`the PHPDoc reference`: https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html
		.. _`Conditional return types`: https://psalm.dev/docs/annotating_code/type_syntax/conditional_types/
		.. _`Class constants`: https://psalm.dev/docs/annotating_code/type_syntax/value_types/#regular-class-constants
		.. _`Callable types`: https://psalm.dev/docs/annotating_code/type_syntax/callable_types/
		.. _`Generics`: https://psalm.dev/docs/annotating_code/templated_annotations/