htmlspecialchars/strpos/mkdir/file_put_contents accept fewer arguments than PHP

[mirchaemanuel]

Summary

Several commonly used builtins accept fewer arguments/flags than PHP, with no
workaround other than rewriting the call. All four are enforced explicitly in
the compiler (fixed/capped arity in src/types/signatures.rs and the
per-builtin src/builtins/** declarations), not accidental gaps — but the
capped arity is real-world limiting for anything that needs entity encoding,
substring search from an offset, recursive directory creation, or append-mode
file writes.

Environment

• elephc v0.26.0 (release, commit 892ff162), macOS ARM64
• Verified against the compiler source (tools/elephc-v0.26.0-src build tree) as well as the compiled binary

Table: function → PHP signature → elephc signature → repro

Function	PHP signature	elephc signature	Repro	Observed
htmlspecialchars	(string $s, int $flags = ENT_QUOTES|ENT_SUBSTITUTE|ENT_HTML401, ...)	(string $s) only	echo htmlspecialchars("a'b", ENT_QUOTES);	Undefined constant: ENT_QUOTES (bare 3 instead: htmlspecialchars() takes exactly 1 argument)
strpos / strrpos	(string $haystack, string $needle, int $offset = 0)	(string $haystack, string $needle), third arg rejected	strpos($s, "b", 2);	strpos() takes exactly 2 arguments
mkdir	(string $directory, int $permissions = 0777, bool $recursive = false, ...)	(string $directory) only, non-recursive	mkdir('/tmp/a/b'); (parent missing)	1-arg call only; no way to request recursive creation or non-default permissions
file_put_contents	(string $filename, mixed $data, int $flags = 0, ...)	(string $filename, string $data) only	file_put_contents($f, $s, FILE_APPEND);	2-arg call only; no append mode, no LOCK_EX

htmlspecialchars's single-argument behavior does match PHP >= 8.1's default
(ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401) byte-for-byte when no explicit
flags are needed — verified htmlspecialchars("a'b\"c<d>&e") gives
a'b"c<d>&e under both. The gap only bites when the flags
argument is passed explicitly, or when a non-default flag combination is
required.

Source pointers (v0.26.0)

• src/types/signatures.rs:213 — strpos/strrpos signature is declared
  with the full [haystack, needle, offset] param list, but
  src/builtins/string/strpos.rs caps max_args: 2, so the third argument
  is rejected by check_arity even though the type signature already models
  it (offset: Int = 0) and the shared lowering path
  (lower_string_position) presumably already knows how to consume it.
• src/builtins/string/htmlspecialchars.rs — params: [string: Str], no
  flags parameter modeled at all.
• src/builtins/io/mkdir.rs — params: [directory: Str], no permissions/
  recursive/context parameters.
• src/builtins/io/file_put_contents.rs — params: [filename: Str, data: Str],
  no flags/context parameters.

Expected

Each builtin should accept (at least) the commonly used PHP-compatible
optional arguments: htmlspecialchars($s, $flags), strpos($h, $n, $offset)
(the offset plumbing already exists in the signature — this one looks like
the smallest fix, essentially just raising max_args), mkdir($dir, $perms, $recursive), file_put_contents($file, $data, $flags).

Workarounds applied

• htmlspecialchars: called with one argument; relies on the coincidence
  that elephc's default matches PHP's current default.
• strpos: rewritten as strpos(substr($haystack, $offset), $needle) plus
  manual index translation back to the original string.
• mkdir: directories created one level at a time, parent-first.
• file_put_contents: never used to append; the app always writes whole
  files.

Notes

Found building a pastebin single-binary app (--web) for the Discord
contest, where all four functions are used in the storage/rendering layer.

[nahime0]

With the merge of #461 htmlspecialchars() / htmlentities() now accept the optional $flags and $encoding arguments

[mirchaemanuel]

Re-triaged against current main (9f74f5300), macOS ARM64. One of the four rows has changed, the other three are unchanged.

htmlspecialchars() now accepts a second argument — both the constant and a bare integer, which this report showed being rejected with Undefined constant: ENT_QUOTES and takes exactly 1 argument. But it ignores the value: every flag produces the ENT_QUOTES output. That is arguably a worse failure mode than the rejection reported here, so I filed it separately as #645 rather than folding it into this arity report.

The other three still reproduce verbatim:

strpos("abcabc", "a", 1)                 -> error[3:6]: strpos() takes exactly 2 arguments        (php: 3)
strrpos("abcabc", "a", -3)               -> error[3:6]: strrpos() takes exactly 2 arguments       (php: 3)
mkdir("/tmp/x", 0777, true)               -> error[3:1]: mkdir() takes exactly 1 argument          (php: ok)
file_put_contents("/tmp/f", "two", FILE_APPEND) -> error[4:1]: file_put_contents() takes exactly 2 arguments  (php: one\ntwo)

So this issue stays open for the remaining three.

[nahime0]

Status update from #678 (2026-08-08 audit branch): two of the four are fixed, two are not. Please keep this open for the remaining two.

Fixed

<?php
echo htmlspecialchars("a\"b<c>", ENT_QUOTES);   // a&quot;b&lt;c&gt;   — matches PHP
var_dump(strpos("abcabc", "b", 2));             // int(4)                — matches PHP

Both now compile and agree with PHP 8.4.

Still capped at the short arity

<?php
var_dump(mkdir("/tmp/e506/x/y", 0777, true));
// error[1:12]: mkdir() takes exactly 1 argument

file_put_contents("/tmp/f", "a");
file_put_contents("/tmp/f", "b", FILE_APPEND);
// error[1:40]: file_put_contents() takes exactly 2 arguments

How to address the remainder

Both are single-source registry builtins, so the change is confined to their
src/builtins/** declaration plus the lowering that consumes the extra operand:

• mkdir($directory, $permissions = 0777, $recursive = false) — the two extra
  parameters are independent. $permissions is a mode passed straight to mkdir(2);
  $recursive needs a loop that creates each missing path component and treats an
  already-existing component as success (PHP returns false with a warning only if the
  final component exists). Note PHP applies umask to $permissions.
• file_put_contents($filename, $data, $flags = 0) — only FILE_APPEND (8) and
  LOCK_EX (2) are meaningful here; FILE_USE_INCLUDE_PATH (1) can stay unsupported
  with a diagnostic. FILE_APPEND selects O_APPEND instead of O_TRUNC at open time,
  so it is a flag translation rather than new I/O machinery. The FILE_APPEND and
  LOCK_EX constants need to exist too.

Worth adding the arity cases to the error tests either way: the current diagnostics are
correct and clear, so the regression risk is in silently widening them without
implementing the semantics.