Hello PHP Internals,
I would like to propose an idea for discussion regarding the introduction
of effect declarations in PHP, with a particular focus on making function
behavior more explicit and improving the security and auditability of
sensitive operations.
Currently, PHP function signatures describe parameters and return values
but do not indicate which external operations a function may perform. A
function may execute operating-system commands, access the filesystem, or
make network requests through its implementation or dependencies without
these operations being visible in its signature.
I believe an effect system could help address this limitation by allowing
functions to declare the operations they may perform. These declarations
could support static analysis, contract checking, code auditing, and
potentially stronger security controls.
Proposed syntax
As an initial proposal, effects could be declared alongside a function's
return type:
function generateReport(string $input): string
effects [process.execute]
{
// Implementation
}
Effects could also accept parameters to describe the scope of an operation:
function generateReport(string $input): string
effects [
process.execute(
commands: ['/usr/bin/report-renderer']
)
]
{
// Implementation
}
In this example, the effect declaration indicates that the function may
execute a process, with the declared contract restricting the intended
executable to the report renderer.
The same concept could be extended to other operations:
function readConfiguration(): string
effects [
filesystem.read(
paths: ['/etc/myapp/config.json']
)
]
{
// Implementation
}
function fetchReport(string $url): string
effects [
network.request(
hosts: ['api.example.com']
)
]
{
// Implementation
}
These examples are illustrative and are not intended to prescribe the final
grammar. The syntax, supported effect types, parameter formats, and
enforcement rules would need to be discussed and evaluated.
Effect checking and security
I envision effects serving as explicit contracts describing the operations
a function may perform. A static analyzer or compiler could check whether
implementations and their dependencies respect these declarations, identify
undeclared effects, and make sensitive operations more visible during code
review.
Parameterized effects could provide additional information about the
intended scope of an operation. For example, a function declaring a
process-execution effect restricted to a particular executable could be
checked for attempts to execute other programs.
I would also like to explore how this proposal could complement a
capability-based security model. Effects and capabilities would have
separate responsibilities: effects would describe the operations and
constraints associated with a function, while capabilities would determine
which operations are authorized at runtime.
For example, an application could grant a request handler permission to
execute a specific binary with defined argument constraints and resource
limits. The runtime would enforce that permission when a process is
created, independently of the function's effect declaration.
This distinction is important because declaring an effect should not
automatically grant authority to perform the operation. Runtime enforcement
would remain necessary for security-sensitive operations, even if static
effect checking were available.
Scope and open questions
I recognize that PHP's dynamic features, backward-compatibility
requirements, and native extension ecosystem present significant design and
implementation challenges. Some questions that would need further
exploration include:
Whether effects should be explicitly declared, inferred, or support both
approaches.
How effects should propagate through function calls, closures, dynamic
calls, and third-party dependencies.
How parameterized effects should be represented and validated.
Whether effect contracts should be enforced by the PHP engine, external
static analysis tools, or a combination of both.
How effects could integrate with runtime capabilities and existing APIs.
How strict enforcement could be introduced without breaking existing PHP
applications.
The proposal would not, by itself, prevent vulnerabilities within the PHP
engine or native extensions. Any runtime security guarantees would depend
on the coverage and correctness of the enforcement mechanisms.
I have started drafting an RFC exploring these ideas, using process
execution as an initial use case. I would welcome feedback on whether
effect declarations and parameterized effects would be a worthwhile
direction for PHP, whether the proposed syntax fits the language, and what
scope would be appropriate for an initial RFC.
If there is interest, I would be happy to share the draft and work on a
proof of concept.
Thank you for your time and consideration.
Respectfully yours,
Arsan Gamal
Senior Software Engineer
Hello David,
Thank you for taking the time to read the proposal and share your
questions. I appreciate the feedback, and I think these are important
points to clarify.
1. Effects for process execution
I agree that invoking native binaries should not be encouraged as a default
approach when an API or shared library is more appropriate. My intention is
not to promote process execution, but to make potentially dangerous
operations explicit and controllable.
The main motivation behind this idea is to explore whether PHP could
provide stronger protection against unintended or unauthorized operations,
including attacks such as PHP2Shell. If an attacker exploits a
vulnerability in an application, the impact could be reduced if the
affected execution context is not authorized to perform sensitive
operations.
One analogy I have in mind is the permission model used by mobile operating
systems. An application may request internet access, camera access, or
filesystem access, but the operating system determines which permissions it
actually receives. Some applications may have a permission while others do
not.
Similarly, a PHP application or execution context could be granted specific
capabilities, while sensitive operations would be denied when the required
authorization is absent. Process execution is simply one potential use
case, and perhaps a useful starting point because of its security
implications.
2. Parameterized effects and configurable values
I agree with your point about API domains and environment-specific
configuration. Hardcoding a hostname in an effect declaration would create
unnecessary coupling if the endpoint changes between environments or needs
to be updated.
I would not want effect declarations to replace configuration or require a
language-level versioning change whenever a string value changes.
Instead, parameterized effects could describe constraints or categories of
operations, with the actual values supplied through configuration or
checked against runtime policy. For example, an effect could indicate that
a function may perform network requests, while the permitted hosts are
determined by the application’s configuration and enforced at runtime.
The same distinction could apply to filesystem access: an effect could
declare that a function reads files, while a runtime policy determines
which paths are permitted.
I am open to whether parameterized effects should contain literal
constraints, reference named policies, or simply describe the operation
while leaving authorization to a separate mechanism.
3. Static analysis versus runtime enforcement
I agree that static analysis cannot reliably determine every operation in a
dynamic language such as PHP, particularly when behavior depends on runtime
input, dynamic calls, or native extensions. I do not expect PHPStan or
Psalm to replace runtime security enforcement.
However, I think static analysis could still provide value by identifying
operations that contradict declared effects.
For example, if a function declares that it only performs calculations, a
static analyzer could flag direct or indirect calls to known
filesystem-reading functions, such as glob() or file_get_contents(), where
those calls are identifiable. Similar checks could be applied to network
and process-execution APIs.
This would not be a complete security guarantee. Dynamic dispatch, indirect
calls, and native extensions would introduce limitations. Runtime
enforcement would therefore be necessary for security-sensitive operations,
with the PHP engine or another trusted runtime mechanism checking whether
the active execution context has the required authority.
Consider a function exposed through an HTTP endpoint whose responsibility
is only to perform a calculation. Ideally, that function should not be able
to make arbitrary API requests, read arbitrary files, or execute system
commands merely because PHP currently allows those operations. Its
permitted effects and runtime authority should reflect what it actually
needs to do.
The broader goal is to explore whether PHP could move towards a model where
potentially sensitive operations are both visible in code and constrained
by enforceable permissions, rather than relying exclusively on developers
to remember every possible attack path.
I realize this raises substantial questions around backward compatibility,
the existing extension ecosystem, and the boundary between language
semantics and runtime security. I do not have all the answers yet, and
feedback like yours is helpful in determining the right direction and scope.
Thank you again for engaging with the proposal.
Sincerely,
Arsan Gamal
Sent from Gmail
Hello Arsan. It sounds very interesting.
However I have some questions:
Use of effect for binaries: I'm not used to the idea of using PHP to
invoke a Binary. Most of the time it tries to invoke an API or a shared
library or something similar. Is it a good idea to encourage calling native
binaries? (I'm sure some people do it. But adding such as a green check of
"you can do it", seems a little of).The use of effect for API call: It is interesting. But what if you want
to update an API endpoint/domain? You would have to manually change it in
the code. Is a SemVer-like (semantic versioning) change necessary for a
string data? As far a I know people get these value from an .env file or
something ? (Thefilesystem.readyou gave seems more appropriate.I'm not sure that any static analyser would be able to check it. Because
these kind of checks are to be done in runtime, right? Does PHPStan or
Psalm for instance do test in runtime? It seems that it would be a
responsibility for the PHP engine/runtime?What do you think?
Kind regards,
David MayeHello PHP Internals,
I would like to propose an idea for discussion regarding the introduction
of effect declarations in PHP, with a particular focus on making function
behavior more explicit and improving the security and auditability of
sensitive operations.Currently, PHP function signatures describe parameters and return values
but do not indicate which external operations a function may perform. A
function may execute operating-system commands, access the filesystem, or
make network requests through its implementation or dependencies without
these operations being visible in its signature.I believe an effect system could help address this limitation by allowing
functions to declare the operations they may perform. These declarations
could support static analysis, contract checking, code auditing, and
potentially stronger security controls.
Proposed syntaxAs an initial proposal, effects could be declared alongside a function's
return type:function generateReport(string $input): string
effects [process.execute]
{
// Implementation
}Effects could also accept parameters to describe the scope of an operation:
function generateReport(string $input): string
effects [
process.execute(
commands: ['/usr/bin/report-renderer']
)
]
{
// Implementation
}In this example, the effect declaration indicates that the function may
execute a process, with the declared contract restricting the intended
executable to the report renderer.The same concept could be extended to other operations:
function readConfiguration(): string
effects [
filesystem.read(
paths: ['/etc/myapp/config.json']
)
]
{
// Implementation
}function fetchReport(string $url): string
effects [
network.request(
hosts: ['api.example.com']
)
]
{
// Implementation
}These examples are illustrative and are not intended to prescribe the
final grammar. The syntax, supported effect types, parameter formats, and
enforcement rules would need to be discussed and evaluated.
Effect checking and securityI envision effects serving as explicit contracts describing the operations
a function may perform. A static analyzer or compiler could check whether
implementations and their dependencies respect these declarations, identify
undeclared effects, and make sensitive operations more visible during code
review.Parameterized effects could provide additional information about the
intended scope of an operation. For example, a function declaring a
process-execution effect restricted to a particular executable could be
checked for attempts to execute other programs.I would also like to explore how this proposal could complement a
capability-based security model. Effects and capabilities would have
separate responsibilities: effects would describe the operations and
constraints associated with a function, while capabilities would determine
which operations are authorized at runtime.For example, an application could grant a request handler permission to
execute a specific binary with defined argument constraints and resource
limits. The runtime would enforce that permission when a process is
created, independently of the function's effect declaration.This distinction is important because declaring an effect should not
automatically grant authority to perform the operation. Runtime enforcement
would remain necessary for security-sensitive operations, even if static
effect checking were available.
Scope and open questionsI recognize that PHP's dynamic features, backward-compatibility
requirements, and native extension ecosystem present significant design and
implementation challenges. Some questions that would need further
exploration include:
Whether effects should be explicitly declared, inferred, or support
both approaches.How effects should propagate through function calls, closures, dynamic
calls, and third-party dependencies.How parameterized effects should be represented and validated.
Whether effect contracts should be enforced by the PHP engine,
external static analysis tools, or a combination of both.How effects could integrate with runtime capabilities and existing
APIs.How strict enforcement could be introduced without breaking existing
PHP applications.The proposal would not, by itself, prevent vulnerabilities within the PHP
engine or native extensions. Any runtime security guarantees would depend
on the coverage and correctness of the enforcement mechanisms.I have started drafting an RFC exploring these ideas, using process
execution as an initial use case. I would welcome feedback on whether
effect declarations and parameterized effects would be a worthwhile
direction for PHP, whether the proposed syntax fits the language, and what
scope would be appropriate for an initial RFC.If there is interest, I would be happy to share the draft and work on a
proof of concept.Thank you for your time and consideration.
Respectfully yours,
Arsan Gamal
Senior Software Engineer
Hi Arsan,
I find the idea interesting, but I have two questions:
-
Why introduce new syntax instead of using PHP attributes? Isn't this
exactly the kind of metadata that attributes were designed for? What would
be the advantage of introducing a new language construct? -
Are you aware of any existing implementations of a similar effect system
in other programming languages? I'd be interested to see how other
languages approach this problem and whether there are any established
patterns PHP could build upon.
Best regards,
Damian
niedz., 25 paź 2026, 14:42 użytkownik Arsan Gamal arsan.gamal@gmail.com
napisał:
Hello PHP Internals,
I would like to propose an idea for discussion regarding the introduction
of effect declarations in PHP, with a particular focus on making function
behavior more explicit and improving the security and auditability of
sensitive operations.Currently, PHP function signatures describe parameters and return values
but do not indicate which external operations a function may perform. A
function may execute operating-system commands, access the filesystem, or
make network requests through its implementation or dependencies without
these operations being visible in its signature.I believe an effect system could help address this limitation by allowing
functions to declare the operations they may perform. These declarations
could support static analysis, contract checking, code auditing, and
potentially stronger security controls.
Proposed syntaxAs an initial proposal, effects could be declared alongside a function's
return type:function generateReport(string $input): string
effects [process.execute]
{
// Implementation
}Effects could also accept parameters to describe the scope of an operation:
function generateReport(string $input): string
effects [
process.execute(
commands: ['/usr/bin/report-renderer']
)
]
{
// Implementation
}In this example, the effect declaration indicates that the function may
execute a process, with the declared contract restricting the intended
executable to the report renderer.The same concept could be extended to other operations:
function readConfiguration(): string
effects [
filesystem.read(
paths: ['/etc/myapp/config.json']
)
]
{
// Implementation
}function fetchReport(string $url): string
effects [
network.request(
hosts: ['api.example.com']
)
]
{
// Implementation
}These examples are illustrative and are not intended to prescribe the
final grammar. The syntax, supported effect types, parameter formats, and
enforcement rules would need to be discussed and evaluated.
Effect checking and securityI envision effects serving as explicit contracts describing the operations
a function may perform. A static analyzer or compiler could check whether
implementations and their dependencies respect these declarations, identify
undeclared effects, and make sensitive operations more visible during code
review.Parameterized effects could provide additional information about the
intended scope of an operation. For example, a function declaring a
process-execution effect restricted to a particular executable could be
checked for attempts to execute other programs.I would also like to explore how this proposal could complement a
capability-based security model. Effects and capabilities would have
separate responsibilities: effects would describe the operations and
constraints associated with a function, while capabilities would determine
which operations are authorized at runtime.For example, an application could grant a request handler permission to
execute a specific binary with defined argument constraints and resource
limits. The runtime would enforce that permission when a process is
created, independently of the function's effect declaration.This distinction is important because declaring an effect should not
automatically grant authority to perform the operation. Runtime enforcement
would remain necessary for security-sensitive operations, even if static
effect checking were available.
Scope and open questionsI recognize that PHP's dynamic features, backward-compatibility
requirements, and native extension ecosystem present significant design and
implementation challenges. Some questions that would need further
exploration include:
Whether effects should be explicitly declared, inferred, or support
both approaches.How effects should propagate through function calls, closures, dynamic
calls, and third-party dependencies.How parameterized effects should be represented and validated.
Whether effect contracts should be enforced by the PHP engine,
external static analysis tools, or a combination of both.How effects could integrate with runtime capabilities and existing
APIs.How strict enforcement could be introduced without breaking existing
PHP applications.The proposal would not, by itself, prevent vulnerabilities within the PHP
engine or native extensions. Any runtime security guarantees would depend
on the coverage and correctness of the enforcement mechanisms.I have started drafting an RFC exploring these ideas, using process
execution as an initial use case. I would welcome feedback on whether
effect declarations and parameterized effects would be a worthwhile
direction for PHP, whether the proposed syntax fits the language, and what
scope would be appropriate for an initial RFC.If there is interest, I would be happy to share the draft and work on a
proof of concept.Thank you for your time and consideration.
Respectfully yours,
Arsan Gamal
Senior Software Engineer
Hi Arsan,
I find the idea interesting, but I have two questions:
Why introduce new syntax instead of using PHP attributes? Isn't this
exactly the kind of metadata that attributes were designed for? What
would be the advantage of introducing a new language construct?Are you aware of any existing implementations of a similar effect
system in other programming languages? I'd be interested to see how
other languages approach this problem and whether there are any
established patterns PHP could build upon.Best regards,
Damian
-
Please do not top post.
-
Attributes would be useful for static-analysis level enforcement. Something like:
#[AllowedEffects(AllowedEffects::Output)]
function doesAThing(string $thing) {
print $thing;
}
And then an SA tool could object if a print statement appears in a method without that attribute on it. That could be implemented today by any of the SA tools in the ecosystem (though they seem to prefer docblock comments to attributes, unfortunately).
If we wanted something that is enforced by the language, however, then it would need either a language-enforced attribute or new native syntax. And the general zeitgeist is that Internals favors new syntax over attributes for things that have a guaranteed-impact rather than just an optional add-on.
- "Effect systems" are a very specific thing in comp sci research. I'm not sure that what is proposed here counts as such. (Think exceptions that return to their point of throw after the handler completes. It seems mainly useful as a way to keep a routine technically-pure while still letting it do useful things.) There are some academic Haskell-like languages with it, but I don't know of anything in widespread use.
What is described here feels more like gated capabilities, similar to what Wasm does. It is an interesting concept, but for it to work it would need to integrate at a very low level. The engine would need to explicitly fail a function that tries calling print without the "I do output" flag, or opening a process without the "I start processes" flag, or reading from the file system without the "I read files" flag. The biggest issue there is, unsurprisingly, backward compatibility. A new PHP release that fails on any function that has a print or fopen statement in it until you add new syntax not available in earlier versions is a complete non-starter.
As noted, it would also need some way to specify a resource dynamically; the file path accessed will be defined at runtime, for instance. In the case of Wasm, the runtime itself passes the path to use INTO the application, chroot-style. (At least I think that's how it works; I'm going off of memory of reading the docs a while back.) I don't see how PHP could get there without completely unacceptable BC breaks.
So I like the idea in the abstract, but the first and most important question is how to make something like this piecemeal opt-in and still meaningful. Because if we can't do that, then we can't do it period.
--Larry Garfield
- "Effect systems" are a very specific thing in comp sci research. I'm not sure that what is proposed here counts as such. (Think exceptions that return to their point of throw after the handler completes. It seems mainly useful as a way to keep a routine technically-pure while still letting it do useful things.) There are some academic Haskell-like languages with it, but I don't know of anything in widespread use.
What is described here feels more like gated capabilities, similar to what Wasm does. It is an interesting concept, but for it to work it would need to integrate at a very low level. The engine would need to explicitly fail a function that tries calling print without the "I do output" flag, or opening a process without the "I start processes" flag, or reading from the file system without the "I read files" flag. The biggest issue there is, unsurprisingly, backward compatibility. A new PHP release that fails on any function that has a print or fopen statement in it until you add new syntax not available in earlier versions is a complete non-starter.
Yeah, these don't seem quite like algebraic effects. I think there is some modern interest in them again (i.e. Unison), so I would pick a different term to describe them. Capabilities also imply something more like an object capability system to me, so I would also avoid that term.