diff --git a/sitemap.xml b/sitemap.xml index 4ee0b14..48e1e6a 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -81,4 +81,7 @@ https://scherzer.dev/Blog/20260309-php-friends + + https://scherzer.dev/Blog/20260410-define-deprecated + diff --git a/src/Blog/posts/20260410-define-deprecated.md b/src/Blog/posts/20260410-define-deprecated.md new file mode 100644 index 0000000..fc9ccfd --- /dev/null +++ b/src/Blog/posts/20260410-define-deprecated.md @@ -0,0 +1,109 @@ +--- +extensions: + pygments: true +title: Introducing define_deprecated() for PHP +--- + +# Introducing define_deprecated() for PHP + +In PHP 8.5, I introduced support for [attributes on constants][blog-attribs], +which allows marking compile-time global constants as deprecated. However, +that functionality was not made easily available when defining constants at +*runtime*, or in code that supports older versions of PHP. My new library, +[danielescherzer/define-deprecated][lib-def-dep], provides that support. + +## Overview + +PHP 8.5's support for attributes on constants introduced new syntax that older +versions of PHP cannot parse. This creates a problem for libraries that want to +support multiple versions of PHP: even *declaring* a constant with attributes +will cause a parser error on older versions of PHP. The solution is to wrap the +constant declaration in [`eval()`][docs-eval], which ensures that the code is +parsed at runtime, making it possible to conditionally execute it on PHP 8.5+. + +While `eval()` is often avoided, here it provides a controlled way to +conditionally use syntax that older versions of PHP are unable to understand. +Exhaustive tests, and the use of [`var_export()`][docs-var-export], confirm that +`eval()` does not present an opportunity for executing arbitrary code, even when +passing untrusted inputs to the library. That said, on PHP 8.4, as attributes +are unavailable, `eval()` is unnecessary; the declaration of constants can be +delegated to the existing function for creating new constants at runtime: +[`define()`][docs-define]. `eval()` is only required for, and used on, PHP 8.5+. + +My new library exposes a new global function, `define_deprecated()`, in the +`\DanielEScherzer\DefineDeprecated` namespace with the following signature: + +```php startinline=True +function define_deprecated( + string $constant_name, + mixed $value, + ?string $message, + ?string $since +): bool { + // ... +} +``` + +The first two parameters, `$constant_name` and `$value`, correspond to the +parameters for the `define()` function, or to the constant name and value used +in compile-time declarations. The remaining two parameters, `$message` and +`$since`, correspond to the parameters of the +[`#[\Deprecated]`][docs-deprecated] attribute - the message explaining why the +constant is deprecated, and the version in which the constant was deprecated. + +While the `#[\Deprecated]` attribute does allow the `$message` and `$since` to +be omitted (defaulting to `null`), this function requires them to be explicitly +passed (even if `null`) to encourage documenting deprecations. + +## Example + +To make use of the new library, install the package via composer, for example: + +```bash +composer require danielescherzer/define-deprecated +``` + +After installing the package, you can define a deprecated constant like this: + +```php + 'https://packagist.org/packages/danielescherzer/commonmark-ext-pygments-highlighter', 'desc' => 'CommonMark extension for code highlighting with Pygments', ], + 'define-deprecated' => [ + 'name' => 'danielescherzer/define-deprecated', + 'link' => 'https://packagist.org/packages/danielescherzer/define-deprecated', + 'desc' => 'Allow defining deprecated global constants at runtime without dropping PHP <8.5 support', + ], 'html-builder' => [ 'name' => 'danielescherzer/html-builder', 'link' => 'https://packagist.org/packages/danielescherzer/html-builder', @@ -345,7 +350,7 @@ private function addPackagesSection(): void { 'p', [], <<magna cum laude in 2024 with a Bachelor of Science degree. As part of my work in Computer Science, I chose to write an honors thesis in my senior year, see here for details. I continued at Tufts for graduate school, graduating in 2025 with a Master of Science in Computer Science degree.

See the links in the navigation bar above for more information about my -experience.

Contact

Blog

I also have a blog. You can see a full index of my posts here. My latest blog post is:

Friends in PHP

Monday, 09 March 2026

As I mentioned in my last blog post, while at ConFoo I and a few -other developers worked on some ideas for adding friendship support to PHP. To -be clear, these are just ideas at the moment, but I figured they were worth -sharing. Continue reading...

Content is © 2026 Daniel Scherzer
\ No newline at end of file +experience.

Contact

Blog

I also have a blog. You can see a full index of my posts here. My latest blog post is:

Introducing define_deprecated() for PHP

Friday, 10 April 2026

In PHP 8.5, I introduced support for attributes on constants, +which allows marking compile-time global constants as deprecated. However, +that functionality was not made easily available when defining constants at +runtime, or in code that supports older versions of PHP. My new library, +danielescherzer/define-deprecated, provides that support. Continue reading...

Content is © 2026 Daniel Scherzer
\ No newline at end of file diff --git a/tests/data/OpenSource.html b/tests/data/OpenSource.html index c17cc91..3969c4a 100644 --- a/tests/data/OpenSource.html +++ b/tests/data/OpenSource.html @@ -9,8 +9,8 @@ decide between the volunteers (luckily there were plenty of candidates) and I was one of the two "rookie" candidates chosen to help with the release. You can read more in my blog post.

PHP uses a process of requests for comment when proposing and implementing major -changes; my RFCs include:

Packages

I also wrote multiple open-source PHP packages - though they are currently +changes; my RFCs include:

Packages

I also wrote multiple open-source PHP packages - though some are currently primarily used by me, I am a firm supporter of open-source code and figured that -they might be useful to others. The packages that I have created so far are:

Website

The source code for my website is also public, in case the code is useful to +they might be useful to others. The packages that I have created so far are:

Website

The source code for my website is also public, in case the code is useful to others. The actual text about me is probably not going to be relevant, but my setup, configuration, and style pages may be useful. See the code here.

Content is © 2026 Daniel Scherzer
\ No newline at end of file diff --git a/tests/data/blog-index.html b/tests/data/blog-index.html index 28b30b3..b9b9720 100644 --- a/tests/data/blog-index.html +++ b/tests/data/blog-index.html @@ -1,5 +1,9 @@ -Blog index
HomeRésuméOpen SourceWorkBlog

Blog index

Friends in PHP

Monday, 09 March 2026

As I mentioned in my last blog post, while at ConFoo I and a few +Blog index

HomeRésuméOpen SourceWorkBlog

Blog index

Introducing define_deprecated() for PHP

Friday, 10 April 2026

In PHP 8.5, I introduced support for attributes on constants, +which allows marking compile-time global constants as deprecated. However, +that functionality was not made easily available when defining constants at +runtime, or in code that supports older versions of PHP. My new library, +danielescherzer/define-deprecated, provides that support. Continue reading...

Friends in PHP

Monday, 09 March 2026

As I mentioned in my last blog post, while at ConFoo I and a few other developers worked on some ideas for adding friendship support to PHP. To be clear, these are just ideas at the moment, but I figured they were worth sharing. Continue reading...

ConFoo 2026

Monday, 02 March 2026

Last week, I was in Montreal for the ConFoo conference, where I gave two talks,