Update charcoal to support PHP 8.3 - 8.5 by JoelAlphonso · Pull Request #96 · charcoalphp/charcoal

JoelAlphonso · 2026-06-02T16:04:16Z

PHP 8.3 / 8.4 Compatibility

Branch: joel/php8 → main

Summary

Updates all 17 Charcoal packages for PHP 8.3 and 8.4 compatibility, addressing breaking changes and deprecations introduced in recent PHP versions.

Breaking Changes Fixed

strftime() removed in PHP 8.4 (charcoal/cms)

Replaced all strftime() calls in DateHelper.php with IntlDateFormatter equivalents (6 occurrences)
strftime() was deprecated in PHP 8.1 and removed in PHP 8.4

Implicit nullable parameters (all packages)

Fixed 166 occurrences of function foo(Type $param = null) → function foo(?Type $param = null) across all packages
PHP 8.4 deprecates this pattern; it will become a fatal error in a future version

Dynamic properties (affected model classes)

Added #[AllowDynamicProperties] attribute to classes relying on dynamic property assignment
PHP 8.2 deprecated dynamic properties; PHP 8.3+ raises deprecation notices

Dependency Updates

PHP constraint — updated in all 17 composer.json files:

"php": "^7.4 || ^8.0"  →  "php": " ^8.3"

Dev dependencies (all packages):

Package	Before	After
`phpunit/phpunit`	`^9.5`	`^11.0`
`vimeo/psalm`	`^4.23`	`^5.0`
`phpstan/phpstan`	`^1.7`	`^2.0`
`squizlabs/php_codesniffer`	`^3.6`	`^3.10`

Testing

Static analysis passing under PHP 8.4 target (phpstan, psalm)
PHPUnit test suite green on PHP 8.3 and 8.4
All changes applied via Rector where applicable; manually reviewed for correctness

Notes

Slim 3.7 (charcoal/app) is EOL but functions on PHP 8.4; a Slim 4 migration is tracked separately
charcoal/cms DateHelper.php locale handling preserves existing output format across all supported locales — the strftime → IntlDateFormatter replacement was validated against fr_CA and en_CA locale strings

Introduced a utility script to streamline monorepo package management. Supports listing packages in default, JSON, or pretty formats.

…ions

… package handling

…proved localization Replaced the deprecated `strftime` with `IntlDateFormatter` for date formatting. Introduced locale support to the `DateHelper` class for better internationalization.

…5 and Xdebug

…s` and removing redundant parsing

…monorepo-builder` configuration

…ma and cleanup deprecated settings

…ed cache and log files

…or for modern PHP syntax (rector utility) Applied strict typing declarations across packages. Updated composer dependencies to require PHP 8.3 and PHPUnit ^12.5. Refactored codebase with type hints, `static` return type, and improved null checks.

…erties

Introduced `$tableExistsCache` for caching table existence checks. Replaced `property_exists` logic with an internal cache and added `#[\AllowDynamicProperties]` for PHP 8.2 compatibility.

…, PHPUnit, and other libraries

…^7.2, Slim ^3.13, Stash ^1.1, and PSR/Cache ^2.0

… add type hints, and refactor for modern PHP syntax - Eliminated `MessageSelector` as it is no longer required with `MessageFormatter`. - Added type hints and return types across various components, improving strict typing consistency. - Simplified logic and migrated to modern PHP syntax for better code maintainability.

…ethods, and modernize for strict typing compliance

…ibility

…ecated docblocks to modern syntax

…ts, and fix syntax issues for immutability compliance

…nce across CollectionContainerTrait and TableWidget

…ePassByReference`

…pdating parentheses usage, and adding return type hints where applicable

…and clean up unused selectors in translator tests

…asses in UI-related tests

…classes in user-related tests

…classes and clean up deprecated mocks in view-related tests

…uite interruptions

…json

…dist configs and removing unused bootstrap handling

…ernize schema versions

…in GitHub Actions

…ootstrap

… for package testing

…clean up unused GitHub Actions step

…cross packages

…e configurations

…ize() methods

…classes

…nit configurations across all packages

…ions with explicit loops for better compatibility

…clean up #[Override] attributes from class properties

… and update associated configuration

…property namespace

mcaskill

This is a preliminary review wherein I've looked at top-level files, Composer manifests, and PHPUnit configuration files.

I'll submit further reviews as I dive into the packages.

mcaskill · 2026-06-02T17:22:55Z

Add a .gitattributes file and exclude .ddev with export-ignore.

https://php.watch/articles/composer-gitattributes

mcaskill · 2026-06-02T17:28:02Z

@@ -1,4 +1,6 @@
 .phpunit.result.cache


With .phpunit.cache, I think we can remove .phpunit.result.cache.

mcaskill · 2026-06-02T17:31:00Z

@@ -1,4 +1,6 @@
 .phpunit.result.cache
+phpunit.xml.dist.bak


I recommend removing this rule. .bak is a generic extension used by various tools. It should be ignored globally rather than ignored at this specific level and file name.

mcaskill · 2026-06-02T17:42:41Z

+# Function to list all monorepo packages in pretty format
+packages_pretty() {
+    echo "Monorepo packages:"
+    find packages -maxdepth 2 -name "composer.json" -type f | while read -r composer_file; do
+        package_dir=$(dirname "$composer_file")
+        package_name=$(basename "$package_dir")
+        echo "  - $package_name"
+    done
+}
+
+# Function to list packages as JSON array
+packages_json() {
+    packages=$(find packages -maxdepth 2 -name "composer.json" -type f | while read -r composer_file; do
+        package_dir=$(dirname "$composer_file")
+        basename "$package_dir"
+    done | awk 'BEGIN{printf "["} {printf "%s\"%s\"", (NR>1?",":""), $0} END{printf "]\n"}')
+    echo "$packages"
+}
+
+# Function to list package names only (space-separated) - default
+packages_default() {
+    find packages -maxdepth 2 -name "composer.json" -type f | while read -r composer_file; do
+        package_dir=$(dirname "$composer_file")
+        basename "$package_dir"
+    done | tr '\n' ' ' | sed 's/ $/\n/'
+}


I would recommend having one function execute the find and extract package names.

I think this command I wrote to be more versatile (the list is also sorted for convenience):

find ./packages -type f -name 'composer.json' \ -maxdepth 2 -exec dirname {} + \ | sort -u \ | xargs basename

From that, JSON output becomes:

packages_json() { packages=$(find_packages | awk 'BEGIN{printf "["} {printf "%s\"%s\"", (NR>1?",":""), $0} END{printf "]\n"}') echo "$packages" }

Also, I don't think you need to store the result in a variable to echo afterwards?

mcaskill · 2026-06-02T17:45:50Z

+        echo "Usage: $0 packages [--type=TYPE|-t TYPE]"
+        echo "Commands:"
+        echo "  packages              List package names (space-separated, default)"
+        echo "  packages -t json      List packages as JSON array"
+        echo "  packages -t pretty    List all monorepo packages in pretty format"


--type (-t) feels like an odd choice for this kind of option. I would recommend --format (-f).

Examples using f:

https://getcomposer.org/doc/03-cli.md#check-platform-reqs

https://developer.wordpress.org/cli/commands/plugin/list/

mcaskill · 2026-06-02T17:53:19Z

According to Rector, couldn't one skip AddOverrideAttributeToOverriddenPropertiesRector?

RectorConfig::configure() ->withSkip([ AddOverrideAttributeToOverriddenPropertiesRector::class, ]);

mcaskill · 2026-06-02T17:57:03Z

        "charcoal/ui": "^5.1",
        "charcoal/user": "^5.1",
+        "guzzlehttp/guzzle": "^6.0 || ^7.0",
+        "kriswallsmith/assetic": "^1.4",


kriswallsmith/assetic will need to be replaced with assetic/framework.

mcaskill · 2026-06-02T18:00:52Z

    "require": {
-        "php": "^7.4 || ^8.0",
+        "php": "^8.3",
        "ext-json": "*",
        "psr/http-message": "^1.0",
        "charcoal/config": "^5.1",
        "erusev/parsedown": "^1.7"


erusev/parsedown should be upgraded to v1.8.0 to resolve PHP 8 deprecations.

mcaskill

This review covers UI, User, and View packages.

mcaskill · 2026-06-02T18:22:52Z

Would it be complicated to import class names instead of using fully qualified names?

The only issue I can think of is it would impact (for humans) the manually curated grouping of imports (which are per package).

mcaskill · 2026-06-02T18:28:38Z

     */
-    public function __invoke(string $text, LambdaHelper $helper = null): string
+    public function __invoke(string $text = '', ?LambdaHelper $helper = null): mixed


Replace mixed with static|string.

mcaskill · 2026-06-02T18:30:03Z

     */
-    public function __get(string $macro)
+    public function __get(string $macro): mixed


Replace mixed with static.

mcaskill · 2026-06-02T18:31:23Z

+        // Mustache v3 calls callable objects with no arguments when traversing dotted
+        // names (e.g. `_t.en`). Return $this so the traversal can continue to __get().


Use block comment for PHPDoc parsers to intercept this comment.

Suggested change

// Mustache v3 calls callable objects with no arguments when traversing dotted

// names (e.g. `_t.en`). Return $this so the traversal can continue to __get().

/**

* Mustache v3 calls callable objects with no arguments when traversing dotted

* names (e.g. `_t.en`). Return $this so the traversal can continue to __get().

*/

mcaskill · 2026-06-02T18:35:13Z

@@ -14,21 +14,23 @@
 class DebugHelpers extends AbstractExtension implements
    HelpersInterface
 {
+    public $debug;


The property needs a type, either:

public ?bool $debug = null; public bool $debug = false; public mixed $debug = false;

If bool, the null coalescing operator should be removed from the isDebug() method.

If mixed, the property should be cast to bool in isDebug().

mcaskill · 2026-06-02T19:48:32Z

@@ -339,13 +339,9 @@ protected function parseFormGroup($groupIdent, $group)
     * @param  array|null $data Optional. The form group data to set.
     * @return FormGroupInterface
     */
-    protected function createFormGroup(array $data = null)
+    protected function createFormGroup(?array $data = null)


Add return type:

Suggested change

protected function createFormGroup(?array $data = null)

protected function createFormGroup(?array $data = null): FormGroupInterface

mcaskill · 2026-06-02T19:53:30Z

Missing property types which influence other methods throughout the trait.

private int $position = 0; private array $structure = [];

mcaskill · 2026-06-02T19:55:54Z

Some methods are returning float|int|null where they should be ?int.

Example of a refactored method to enforce int.

public function rowNumColumns(?int $position = null): ?int { $position ??= $this->position(); $row = $this->rowData($position); if ($row === null) { return null; } return (int) array_sum($row['columns']); }

mcaskill · 2026-06-02T19:57:28Z

@@ -260,7 +253,7 @@ public function cellSpan($position = null)
     * @param integer $position Optional. Forced position.
     * @return integer
     */
-    public function cellSpanBy12($position = null)
+    public function cellSpanBy12($position = null): null|float|int


This method should round and clamp its result.

mcaskill · 2026-06-02T20:00:00Z


    /**
     * Return a new menu.
     *
     * @param array|\ArrayAccess $data Class dependencies.
     */
-    public function __construct($data)
+    public function __construct(?array $data)


Is there a way for this method to not support null?

Same concern applies to similar classes that such as AbstractMenuItem.

mcaskill

This review covers Translator package.

mcaskill · 2026-06-02T20:27:49Z

@@ -215,11 +189,11 @@ private function getLanguage(RequestInterface $request)
     * @param  RequestInterface $request The PSR-7 HTTP request.
     * @return string
     */
-    private function getLanguageFromHost(RequestInterface $request)
+    private function getLanguageFromHost(RequestInterface $request): int|string


Return type should be string.

return $lang; should maybe be return (string) $lang;.

Maybe also add an annotation to the $hostMap property:

/** @var array<string, string> */ private array $hostMap;

mcaskill · 2026-06-02T20:33:03Z

Missing parameter type on $domain throughout a few methods.

mcaskill · 2026-06-02T20:35:49Z

The trait's $translator property should be:

private ?Translator $translator = null;

I think we can also remove the exception thrown in translator() in favour of delegating error handling to PHP which will expect the return type.

mcaskill · 2026-06-02T20:39:49Z

     */
-    private $container;
+    private \Pimple\Container|array|null $container = null;


This property is only ever ?Container, I see no occurrence of it as an array.

JoelAlphonso added 30 commits May 15, 2026 13:56

feat(monorepo-toolbox): add helper script for managing monorepo packages

8d92c55

Introduced a utility script to streamline monorepo package management. Supports listing packages in default, JSON, or pretty formats.

ci(workflows): update PHP versions and monorepo command in GitHub Act…

f5d3ae1

…ions

ci(workflows): update PHP version in GitHub Actions to 8.5

3ad70a9

chore(dependencies): update composer dependencies to latest versions

9f4efa5

chore(dependencies): downgrade PHP requirement to ^8.3 in composer.json

9a9d0a1

tests(phpcs): update script to use ./monorepo packages and simplify…

b6d1264

… package handling

feat(date-helper): replace strftime with IntlDateFormatter for im…

dfd94ac

…proved localization Replaced the deprecated `strftime` with `IntlDateFormatter` for date formatting. Introduced locale support to the `DateHelper` class for better internationalization.

chore(ddev): add DDEV configuration for local development with PHP 8.…

08fff27

…5 and Xdebug

tests(script): simplify phpunit script by using `./monorepo package…

b12447a

…s` and removing redundant parsing

tests(bootstrap): add strict_types declaration in test bootstrap file

1627f42

chore(dependencies): update composer.lock after dependencies upgrade

e9eafd6

chore(dependencies): update phpunit to ^12.5 and fix namespace in `…

7adf894

…monorepo-builder` configuration

chore(tests): update PHPUnit configuration to match version 12.5 sche…

a8ea26f

…ma and cleanup deprecated settings

chore(rector): add Rector configuration for PHP 8.5 and PHPUnit upgrades

dc3f349

chore(gitignore): update .gitignore to include PHPUnit and test-relat…

8f7a66b

…ed cache and log files

chore(translator, core): add return type hints and allow dynamic prop…

e07c83c

…erties

chore(core): add table existence cache and use modern PHP syntax

c7fce1b

Introduced `$tableExistsCache` for caching table existence checks. Replaced `property_exists` logic with an internal cache and added `#[\AllowDynamicProperties]` for PHP 8.2 compatibility.

chore(dependencies): bump Symfony dependencies to ^7.4, update Guzzle…

5078f99

…, PHPUnit, and other libraries

chore(dependencies): upgrade multiple dependencies including Symfony …

76b9d66

…^7.2, Slim ^3.13, Stash ^1.1, and PSR/Cache ^2.0

chore(core, admin, translator): add type hints, refactor deprecated m…

70daf98

…ethods, and modernize for strict typing compliance

chore(core): add strict is_array check in ModelStructureProperty logic

918bb2d

chore(translator): add #[AllowDynamicProperties] for PHP 8.2 compat…

38d1d0f

…ibility

chore(core): add isset check in ModelStructureProperty, update depr…

3d1c3e6

…ecated docblocks to modern syntax

chore(translator): update deprecated annotations, add return type hin…

37fd820

…ts, and fix syntax issues for immutability compliance

chore(admin): add return type hints and improve strict typing complia…

95b0b4a

…nce across CollectionContainerTrait and TableWidget

chore(dependencies): bump PHP_CodeSniffer to ^4.0, update composer lock

d6b7f9f

chore(phpcs): remove deprecated rules NoSpaceAfterCast and `CallTim…

6abcad3

…ePassByReference`

chore(phpcs): enforce strict typing by removing spaces after casts, u…

c507b33

…pdating parentheses usage, and adding return type hints where applicable

JoelAlphonso added 23 commits May 29, 2026 13:36

tests(translator): enforce static methods, replace deprecated mocks, …

453e4d8

…and clean up unused selectors in translator tests

tests(ui): PHPUNIT: replace mocked abstract classes with anonymous cl…

782d01b

…asses in UI-related tests

tests(user): PHPUNIT: replace mocked abstract classes with anonymous …

50334bc

…classes in user-related tests

tests(view): PHPUNIT: replace mocked abstract classes with anonymous …

0a2c295

…classes and clean up deprecated mocks in view-related tests

tests(config): disable PHPUnit warnings and notices to prevent test s…

fb999bb

…uite interruptions

chore(deps): add ext-pdo_mysql as a required extension in composer.…

48771ae

…json

chore(deps): build composer.lock

1e1e248

tests(script): streamline test_package function by using phpunit.xml.…

364906c

…dist configs and removing unused bootstrap handling

tests: update PHPUnit configurations to use bootstrap scripts and mod…

247a6cd

…ernize schema versions

tests(workflow): add TEST_MODE environment variable for PHPUnit runs …

35d2af4

…in GitHub Actions

tests(user): switch from $_ENV to getenv for TEST_MODE detection in b…

3d7d577

…ootstrap

tests(workflow): set TEST_MODE environment variable in GitHub Actions…

c610168

… for package testing

tests(script): set TEST_MODE variable inline for package testing and …

37b5682

…clean up unused GitHub Actions step

tests(bootstrap): replace $_ENV with getenv for TEST_MODE detection a…

5f15581

…cross packages

tests(config): disable PHPUnit warnings and notices across all packag…

00139fa

…e configurations

style(config): fix PSR-12 formatting for __serialize() and __unserial…

9245ddd

…ize() methods

chore(build): remove obsolete code coverage reports for image effect …

f15eb63

…classes

chore(gitignore): add build report directories to ignore list

05797be

tests(config): add failOnDeprecation and failOnPhpunitWarning to PHPU…

dfa5069

…nit configurations across all packages

refactor(core): remove #[Override] attributes and replace arrow funct…

c8c1a8b

…ions with explicit loops for better compatibility

refactor(rector): add RemoveOverrideAttributeFromPropertiesRector to …

09b8b98

…clean up #[Override] attributes from class properties

refactor(rector): downgrade PHP version compatibility from 8.5 to 8.3…

c3e0d39

… and update associated configuration

refactor(composer): update PSR-4 autoload mappings to include Rector …

9fef649

…property namespace

JoelAlphonso requested review from BeneRoch, mcaskill and mducharme June 2, 2026 16:04

MouseEatsCat mentioned this pull request Jun 2, 2026

PHP 8+ Support #94

Closed

mcaskill requested changes Jun 2, 2026

View reviewed changes

		// Mustache v3 calls callable objects with no arguments when traversing dotted
		// names (e.g. `_t.en`). Return $this so the traversal can continue to __get().

	protected function createFormGroup(?array $data = null)
	protected function createFormGroup(?array $data = null): FormGroupInterface

Conversation

JoelAlphonso commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PHP 8.3 / 8.4 Compatibility

Summary

Breaking Changes Fixed

Dependency Updates

Testing

Notes

Uh oh!

mcaskill left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcaskill left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcaskill left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JoelAlphonso commented Jun 2, 2026 •

edited

Loading