Re: [PHP-DEV] Proposal for Discussion: Effect Declarations and Capability-Gated Process Execution in PHP

[David Maye]

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 ? (The `filesystem.read` you 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 Maye

On Oct 25, 2026 2:38 PM, Arsan Gamal <arsan.ga...@gmail.com> wrote:

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