Update charcoal to support PHP 8.3 - 8.5

[JoelAlphonso]

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

[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]

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

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

[mcaskill]

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

[mcaskill]

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]

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]

--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]

According to Rector, couldn't one skip AddOverrideAttributeToOverriddenPropertiesRector?

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

[mcaskill]

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

[mcaskill]

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

[mcaskill]

This review covers UI, User, and View packages.

[mcaskill]

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]

Replace mixed with static|string.

[mcaskill]

Replace mixed with static.

[mcaskill]

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]

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]

Add return type:

Suggested change

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

[mcaskill]

Missing property types which influence other methods throughout the trait.

    private int $position = 0;

    private array $structure = [];

[mcaskill]

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]

This method should round and clamp its result.

[mcaskill]

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]

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]

Missing parameter type on $domain throughout a few methods.

[mcaskill]

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]

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

[mcaskill]

This review covers Property package.

---

In regards to all packages: The Override attribute should not applied to methods that call their parent such as dataUpload(), fileUpload(), setDependencies().

[mcaskill]

• val should be mixed and default to null.
• label, description, and notes should be ?Translation and default to null.
• multipleOptions and viewOptions should be ?array and default to null.
• displayType should be ?string and default to null.

[mcaskill]

Might as well simplify this method with early returns instead of using else:

public function __toString(): string
{
    $val = $this->val();
    if (is_string($val)) {
        return $val;
    }

    if (is_object($val)) {
        return (string)$val;
    }

    return '';
}

[mcaskill]

Like parseVal and parseOne, inputVal and displayVal should also type $val as mixed.

[mcaskill]

Should be Translation|string

[mcaskill]

If the parameter is to be bool, the method should be simplified.

[mcaskill]

Parameter should be typed bool instead of casting.

[mcaskill]

Should be bool and default to true.

[mcaskill]

Parameter should be typed string and the is_string() guard should be removed.

[mcaskill]

Should be typed ?ViewInterface and default to null.

[mcaskill]

Parameter should be typed bool instead of casting.

[mcaskill]

This review covers Object package.

[mcaskill]

Parameters should be typed int. A float would be very problematic.

[mcaskill]

Parameter should be typed int and is_numeric() guard below should be removed.

- if (!is_numeric($page)) {
-     throw new InvalidArgumentException(
-         'Page number needs to be numeric.'
-     );
- }
- 
- $page = (int)$page;
  if ($page < 0) {
      throw new InvalidArgumentException(
-         'Page number needs to be greater than or equal 0.'
+         'Page number must be at least 0'
      );
  }
  
  $this->page = $page;

[mcaskill]

Parameter should be typed int and is_numeric() guard below should be removed.

- if (!is_numeric($num)) {
-     throw new InvalidArgumentException(
-         'Num-per-page needs to be numeric.'
-     );
- }
- 
- $num = (int)$num;
  if ($num < 0) {
      throw new InvalidArgumentException(
-         'Num-per-page needs to be >= 0.'
+         'Num-per-page must be at least 0'
      );
  }
  
  $this->numPerPage = $num;

[mcaskill]

• $master should be typed int|string|null.
• $hierarchy, $children, and $siblings should be typed ?array.
• $masterObject should be typed ?HierarchicalInterface.
• $objectCache should be typed array and annotation should be @var array<class-string, array<int|string, ModelInterface>.

[mcaskill]

Methods hierarchy(), children(), and siblings() can be simplified using null coalescing assignment operator. For example:

return $this->hierarchy ??= $this->loadHierarchy();

And their return types should be array.

[mcaskill]

Methods objFromIdent(), loadObjectFromCache(), and loadObjectFromSource() should return either:

• (HierarchicalInterface&ModelInterface)|null
• ?HierarchicalInterface
• ?ModelInterface

[mcaskill]

Method getRouteObjectPrototype() should have return type ObjectRouteInterface.

[mcaskill]

Method isActiveRoute() should have return type bool.

[mcaskill]

• Class property $ip should be typed int|string|null and setIp() simplified to delegate IP address parsing to IpProperty.
• Class properties $lang and $origin should be typed ?string and default to null.

Equivalent accessor and mutator methods should be updated correspondingly.

[mcaskill]

Method parameter $lang should be typed ?string and guards below removed.

[mcaskill]

Method parameter $origin should be typed ?string and guards below removed.

[mcaskill]

This review covers Image package.

I don't think the build directory shout not be indexed in the Image package based on the last release.

[mcaskill]

Class property $channel should be typed string.

Equivalent accessor and mutator methods should be updated accordingly including removing any pre-PHP 7.4 guards.

[mcaskill]

Class property $gravity should be typed string.

Equivalent accessor and mutator methods should be updated accordingly including removing any pre-PHP 7.4 guards and casts.

Method parameters of doCrop() should be typed int and have return type void.

[mcaskill]

With class property $quality typed, equivalent accessor and mutator methods should be updated accordingly including removing any pre-PHP 7.4 guards and casts.

[mcaskill]

With class properties $colors and $mode typed, equivalent accessor and mutator methods should be updated accordingly including removing any pre-PHP 7.4 guards and casts.

[mcaskill]

This // Quantize comment should be indented to match array items.

[mcaskill]

Class properties $*Cmd for Imagemagick binaries should be typed ?string and default to null.

Equivalent accessor methods should be simplified. For example:

public function mogrifyCmd()
{
    return $this->mogrifyCmd ??= $this->findCmd('mogrify');
}

Equivalent accessor and mutator methods should be updated accordingly including removing any pre-PHP 7.4 guards and casts.

[mcaskill]

Given the return within the proc_open condition, the else that executes shell_exec is unnecessary.

[mcaskill]

• Class properties $source and $target should be typed ?string and default to null.
• Class property $effects should be typed array.

Equivalent accessor and mutator methods should be updated accordingly including removing any pre-PHP 7.4 guards and casts.

[mcaskill]

Method effectFactory() should be simplified:

protected function effectFactory(): EffectFactory
{
    return $this->effectFactory ??= new EffectFactory();
}

[mcaskill]

Mutator methods should have return type static.

Methods' parameters and return should be typed.

[mcaskill]

This review covers Factory package.

[mcaskill]

• Class property $resolved should be typed array and be annotated array<class-string<static>, array<string, class-string>>.
• Class properties $baseClass and $defaultClass should be typed string and be annotated class-string.
• Class property $callback should be typed ?callable and default to null.
• Class property $resolver should be typed callable.
• Class property $instances should be annotated array<string, object>.
• Class property $map should be annotated array<string, class-string>.

[mcaskill]

This should be simplified:

- if (!isset($data['resolver'])) {
-     $opts = ($data['resolver_options'] ?? null);
-     $data['resolver'] = new GenericResolver($opts);
- }
- 
- $this->setResolver($data['resolver']);
+ $this->setResolver($data['resolver'] ?? new GenericResolver($data['resolver_options'] ?? null));

[mcaskill]

Fallback for $args should be simplified to:

- if (!isset($args)) {
-     $args = $this->arguments();
- }
+ $args ??= $this->arguments();

[mcaskill]

Methods with parameter $type should be typed string and is_string() guards removed.

[mcaskill]

This review covers Email package.

[mcaskill]

For readability, promoted parameters should be spread over multiple lines.

Suggested change

	public function __construct(private readonly string $linkId, private readonly Tracker $tracker, private readonly FactoryInterface $modelFactory)
	public function __construct(
	private readonly string $linkId,
	private readonly Tracker $tracker,
	private readonly FactoryInterface $modelFactory
	)

[mcaskill]

For readability, promoted parameters should be spread over multiple lines.

Suggested change

	public function __construct(private readonly string $emailId, private readonly Tracker $tracker)
	public function __construct(
	private readonly string $emailId,
	private readonly Tracker $tracker
	)

[mcaskill]

• Class property $queueId should be typed int|string|null and default to null.
• Class properties $errorCode and $campaign should be typed ?string and default to null.

[mcaskill]

Class properties $email and $url should be typed ?string and default to null.

[mcaskill]

For readability, promoted parameters should be spread over multiple lines.

Suggested change

	public function __construct(private readonly string $baseUrl, private readonly FactoryInterface $modelFactory)
	public function __construct(
	private readonly string $baseUrl,
	private readonly FactoryInterface $modelFactory
	)

[mcaskill]

• Class property $replyTo should be typed ?string and default to null.
• Class property $attachments should be typed array.
• Class properties $logEnabled, $trackOpenEnabled and $trackLinksEnabled should be typed ?bool and default to null. Mutator methods should accept ?bool and not cast to bool to allow one to reset the value to the config's defaults in their equivalent accessors.

[mcaskill]

Class property $parser should be typed ?Parser and default to null.

[mcaskill]

Class property $smtpSecurity appears to be unused across Charcoal. I would recommend changing its type to ?string and default to null.

Its mutator (and accessor) method should be changed to support null:

public function setSmtpSecurity(?string $security): static
{
	if (is_string($security)) {
	    $security = strtoupper($security);
	    $validSecurity = [ 'TLS', 'SSL' ];
	
	    if (!in_array($security, $validSecurity)) {
	        throw new InvalidArgumentException(
	            'SMTP Security is not valid. Must be null, "TLS", or "SSL".'
	        );
	    }
    }

    $this->smtpSecurity = $security;

    return $this;
}

[mcaskill]

Class properties $subject, $msgHtml, $msgTxt, and $campaign should be typed ?string and default to null.

[mcaskill]

This review covers Core package.

[mcaskill]

• Class property $source should be typed ?SourceInterface and default to null.
• Class property $model should be typed ?ModelInterface and default to null.
• Class property $factory should be typed ?FactoryInterface and default to null.
• Class property $callback should be typed ?callable and default to null.
• Class property $dynamicTypeField should be typed ?string and default to null.
• Class property $collectionClass should be typed ?string, annotated as 'array'|class-string|null, and default to null.

[mcaskill]

Methods that return \ArrayAccess|array (or array|\ArrayAccess) should \ArrayAccess|iterable because the collection could be a class (same applies to LazyCollectionLoader).

I would personally suggest remove ArrayAccess as a choice.

[mcaskill]

This method should be typed ModelInterface.

There's no scenario where ArrayAccess or null would be returned.

[mcaskill]

Class property $collectionLoader should be typed ?CollectionLoader and default to null.

The isset() guard in collectionLoader() method should be removed.

[mcaskill]

Class property $collectionLoaderFactory should be typed ?FactoryInterface and default to null.

Method collectionLoaderFactory() should return FactoryInterface and the isset() guard removed.

[mcaskill]

• Method parameter of setCondition() should be typed ?string.
• Method return of hasCondition() should be typed bool.
• Method return of condition() should be typed ?string.

[mcaskill]

Default value of type should be null instead of empty string.

[mcaskill]

Method parameter should be typed and guard removed.

[mcaskill]

• setKey() parameter and key() return should be typed string.
• source() return should be SourceInterface.
• save(), update(), and delete() return should be bool.

[mcaskill]

• Class property $id should default to null.
• Class property $key should be typed string.
• Class property $sourceFactory should be typed ?FactoryInterface and default to null.
• Class property $source should be typed ?SourceInterface and default to null.
• Corresponding guards in mutator methods should be removed.
• pre*() and post*() methods should return bool.

[mcaskill]

This review covers Config package.

[mcaskill]

• Class properties $keyCache, $mutatorCache, and $camelCache should be typed array.

[mcaskill]

• Method defaults() should return array.
• Method addFile() parameter should be typed string.

[mcaskill]

Method parameter of config() should be typed ?string.

[mcaskill]

• Class property $config should be typed ?ConfigInterface and default to null.
• Method parameter $key of config() should be typed ?string.

[mcaskill]

Class property $delegates should be typed array.

[mcaskill]

• Method return of keys() should be array.
• Method return of data() should be array.
• Method return of has() should be bool and parameter $key should be string.
• Method parameter $key of get() should be string.
• Method parameter $key of set() should be string.

[mcaskill]

Method parameter $path of loadFile() should be string.

[mcaskill]

Method parameter $separator of setSeparator() should be string.

[mcaskill]

• Class property $separator should be typed string and not have a default value.
• Method parameter of setSeparator() should be typed string and type guard removed.
• Method return of separator() should be typed string.
• Method parameter of *WithSeparator() should be typed string.

[mcaskill]

This review covers the CMS package.

[mcaskill]

• Class property $sectionFactory should be typed ?FactoryInterface and default to null.
• Method sectionFactory() should return FactoryInterface and guard removed.
• Methods abridgeUri() and abridgeStr() should be typed.

[mcaskill]

Method active() should return bool.

[mcaskill]

• Class property $isAttachmentMetadataFinalized should be typed bool and default to false.
• Class property $controllerIdent should be typed ?string and default to null (equivalent methods should be updated).

[mcaskill]

• Class properties $controllerIdent, $isMergingData and $extraFormGroups appear unused and should be removed.
• Class properties $formGroups and $widgetMetadata should be typed array and default to [].
• Class property $storageProperty should be typed ?ModelStructureProperty and default to null.
• Class property $widgetFactory should be typed ?FactoryInterface and default to null. Corresponding accessor method return should be typed and guard removed.

[mcaskill]

• Class properties $defaultFromEmail, $contactCategoryObj
  , $defaultContactCategory, and $contactObj should be typed ?string and default to null.
• Class properties $dateFormats and $timeFormats should be typed array.
• Class properties $homeNews and $homeEvents should be typed array and default to [].
• Class properties $newsConfig, $eventConfig, and $sectionConfig should be typed to their corresponding config class and default to null.

[mcaskill]

Class properties whose mutator methods are using Translator should be typed ?Translation.

[mcaskill]

Class property $name should be typed ?Translation.

[mcaskill]

Similar changes to AbstractEvent.

[mcaskill]

Class property $name should be typed ?Translation.

[mcaskill]

• Class properties $templateIdent and $controllerIdent should be typed ?string and default to string.
• Class property $templateOptions should be typed array.
• Class property $templateOptionsMetadata should be typed ?StructureMetadata and default to null.
• Class property $areTemplateOptionsFinalized should be typed bool.