From 28e777e88b02dbd45f50ec8bdc7e886a96442c77 Mon Sep 17 00:00:00 2001
From: Larry Garfield <larry@garfieldtech.com>
Date: Sat, 31 May 2025 02:29:36 -0500
Subject: [PATCH 1/3] Add a v3 migration document.
---
migration-3.0.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 156 insertions(+)
create mode 100644 migration-3.0.md
diff --git a/migration-3.0.md b/migration-3.0.md
new file mode 100644
index 0000000..4e6955b
--- /dev/null
+++ b/migration-3.0.md
@@ -0,0 +1,156 @@
+# Migrating from PER-CS v1.0 (PSR-12) to PER-CS v2.0 ###
+
+## Summary
+
+PER-CS is the next evolution of the PSR set of Coding Standards from the
+PHP-FIG (Framework Interoperability Group). It extends the Coding Standards
+laid out in PSR-12 to the newest functionality added to PHP such as the match
+keyword, enums, attributes, and more.
+
+This document describes the changes and additions on a section by section
+basis between PER-CS v3.0 and PER-CS v2.0.
+
+It is derived in part from [a GitHub-generated diff](https://github.com/php-fig/per-coding-style/compare/2.0.0...3.0.0#files_bucket)
+and focuses on the changes on a section-by-section basis as its focus is to be more readable.
+
+This document intends to provide a summary of these changes that can
+then be used to drive action lists for toolset producers to support PER-CS v3.0.
+
+This document is non-normative. The published [3.0 PER-CS](https://www.php-fig.org/per/coding-style/) specification
+is the canonical source for the PER-CS formatting expectations.
+
+## [Section 2.5 - Keywords and Types](https://www.php-fig.org/per/coding-style/#25-keywords-and-types)
+
+Formatting conventions are now provided for compound types (those that include union or intersection type declarations).
+
+* The `|` and `&` symbols and parentheses MUST NOT have leading or trailing spaces.
+* If a type declaration is long enough to split to multiple lines, each ANDed block must be on one line, and each ORed block on its own line.
+* If one of the types listed is `null`, it must come last.
+* Favor `?` over `|null` in cases where both work.
+* A multi-catch statement must follow the same rules. (See section 5.6 as well.)
+
+```php
+function foo(int|string $a): User|Product
+{
+ // ...
+}
+
+function complex(array|(ArrayAccess&Traversable) $input): ArrayAccess&Traversable
+{
+ // ...
+}
+
+function veryComplex(
+ array
+ |(ArrayAccess&Traversable)
+ |(Traversable&Countable) $input): ArrayAccess&Traversable
+{
+ // ...
+}
+```
+
+## [Section 2.7 - Naming](https://www.php-fig.org/per/coding-style/#27-naming)
+
+PER-CS now recommends following the same naming conventions as PHP Internals for abbreviations and acronyms. Specifically, only uppercase the first character of the acronym: `XmlFormatter`, not `XMLFormatter`.
+
+## [Section 3 - Declare Statements, Namespace, and Import Statements](https://www.php-fig.org/per/coding-style/#3-declare-statements-namespace-and-import-statements)
+
+The `<?php` tag must always be all-lowercase.
+
+## [Section 4 - Classes, Properties, and Methods](https://www.php-fig.org/per/coding-style/#4-classes-properties-and-methods)
+
+If using PHP 8.4 or later, parentheses should be omitted around a `new` declaration.
+
+## [Section 4.3 - Properties and Constants](https://www.php-fig.org/per/coding-style/#43-properties-and-constants)
+
+Class constants must have a visibility and type declared.
+
+If a property has a `set`-visibility defined, the `get` visibility may be omitted.
+
+```php
+class Foo
+{
+ // This is allowed.
+ private(set) string $name;
+}
+```
+
+## [Section 4.6 - Modifier Keywords](https://www.php-fig.org/per/coding-style/#46-modifier-keywords)
+
+At least one of `readonly`, `get`-visibility, and `set`-visibility must be specified. If at least one is specified, the others may be omitted.
+
+```php
+class Foo
+{
+ // These are all acceptable.
+ public private(set) string $one;
+ private(set) string $two;
+ readonly string $three;
+
+ // These are not.
+ private(set) public string $four;
+}
+```
+
+## [Section 4.7 - Methods and Function Calls](https://www.php-fig.org/per/coding-style/#47-method-and-function-calls)
+
+The `exit()` and `die()` functions should always be called with parentheses, even though PHP technically permits them without.
+
+## [Section 4.9 - Property hooks](https://www.php-fig.org/per/coding-style/#49-property-hooks)
+
+Formatting guidelines for property hooks are now included.
+
+When using property hooks on a constructor promoted property, only single-line set hooks are allowed. Anything more complicated MUST be defined separately from the constructor.
+
+The following are examples of properly formatted hooks:
+
+```php
+class Example
+{
+ public string $one = 'Me' {
+ set(string $value) {
+ // ...
+ }
+ }
+
+ public string $two {
+ get {
+ // ...
+ }
+ set {
+ // ...
+ }
+ }
+
+ public string $three {
+ get => __CLASS__;
+ set => ucfirst($value);
+ }
+
+ public string $four { get => __CLASS__; }
+}
+```
+
+## [Section 5.2 - Switch, Case, and Match](https://www.php-fig.org/per/coding-style/#52-switch-case-match)
+
+When breaking a series of boolean operators across multiple lines, the operator MUST be at the beginning of each line, not the end of each line.
+
+(This applies to `switch`, `match`, `while`, `do while`, and any other expression.)
+
+## [Section 6.4 - Operator placement](https://www.php-fig.org/per/coding-style/#64-operator-placement)
+
+When breaking a series of chained operations across multiple lines, the operator MUST be at the beginning of each line, not the end of each line, and all lines but the first MUST be indented. Examples include `??` and ternary conditionals.
+
+```php
+<?php
+
+$variable1 = $ternaryOperatorExpr
+ ? 'fizz'
+ : 'buzz';
+
+$variable2 = $possibleNullableExpr
+ ?? 'fallback';
+
+$variable3 = $elvisExpr
+ ?: 'qix';
+```
From b6bb327a7e234a57e5c362bb2d6d799a1f1ef1d0 Mon Sep 17 00:00:00 2001
From: Larry Garfield <larry@garfieldtech.com>
Date: Sat, 31 May 2025 02:29:43 -0500
Subject: [PATCH 2/3] Spelling fix.
---
spec.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/spec.md b/spec.md
index 12f57a3..48e2d1e 100644
--- a/spec.md
+++ b/spec.md
@@ -370,7 +370,7 @@ class MyException extends \RuntimeException {}
```
When accessing a class member immediately after instantiating a new class, the instantiation SHOULD NOT be wrapped in
-parenthesis. For example:
+parentheses. For example:
```php
new Foo()->someMethod();
From 24ec3533525de4d10b672b5192891d6f27c8fe00 Mon Sep 17 00:00:00 2001
From: Larry Garfield <larry@garfieldtech.com>
Date: Sat, 7 Jun 2025 23:12:54 -0500
Subject: [PATCH 3/3] Update title
Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
migration-3.0.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/migration-3.0.md b/migration-3.0.md
index 4e6955b..d15b603 100644
--- a/migration-3.0.md
+++ b/migration-3.0.md
@@ -1,4 +1,4 @@
-# Migrating from PER-CS v1.0 (PSR-12) to PER-CS v2.0 ###
+# Migrating from PER-CS v2.0 to PER-CS v3.0 ###
## Summary