Add support for Sharp constructor options

[Copilot]

Users need to pass constructor options (e.g., density for SVG/PDF rendering) but currently must modify core files to do so.

Changes

• PHP (Sharp.php): Accept optional options array in $io['input'], pass as JSON to Node.js script
• JavaScript (sharp.js): Parse third CLI argument as constructor options, pass to sharp() constructor
• Tests: Add testCanUseConstructorOptions() validating density option increases output size
• Documentation: Add usage example and link to Sharp constructor API

Usage

Sharp::run(
    [
        'input' => [
            'is_raw' => false,
            'data' => $svgPath,
            'options' => ['density' => 300]  // Any Sharp constructor option
        ],
        'output' => ['is_raw' => false, 'file' => $pngPath],
    ],
    ['toFormat' => ['format' => 'png']]
);

Backward compatible—existing code without options continues to work.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/sebastianbergmann/exporter/zipball/78c00df8f170e02473b682df15bfcdacc3d32d72
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/a7vJQA /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/global-state/zipball/bca7df1f32ee6fe93b4d4a9abbf69e13a4ada2c9
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/a7vJQA /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/object-enumerator/zipball/5c9eeac41b290a3712d88851518825ad78f45c71
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/a7vJQA /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/object-reflector/zipball/b4f479ebdbf63ac605d183ece17d8d7fe49c15c7
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/a7vJQA /usr/bin/composer install --no-interaction (http block)
• https://api.github.com/repos/sebastianbergmann/type/zipball/75e2c2a32f5e0b3aef905b9ed0b179b953b3d7c7
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/a7vJQA /usr/bin/composer install --no-interaction (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Constructor options</issue_title>
<issue_description>Hey, your Sharp wrapper is a life saver!

I have a quick one, please. Maybe I am missing something obvious, but what is the preferred way to pass options to constructor?

This works, but I am modifying your core files so that is no good :))

 // Initialize sharp with input file
 let image = sharp(file, { density: 300 });

Thx</issue_description>

<agent_instructions>Ref https://sharp.pixelplumbing.com/api-constructor/, review if it's necessary to add options at the constructor level.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@kiatng Which api are you using? For `toFormat`: ```php Sharp::run( [ 'input' => ['is_raw' => false, 'data' => $svgPath], 'output' => ['is_raw' => false, 'file' => $pngPath], ], [ 'toFormat' => [ 'format' => 'png', 'options' => ['density' => 300] ], ] );

</comments>

• Fixes Constructor options #1

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[kiatng]

@copilot Analyze tradeoffs: PR #2 vs PR #3

[Copilot]

@copilot Analyze tradeoffs: PR #2 vs PR #3

PR #2 vs PR #3 Tradeoffs

PR #2 (nested in $io['input']['options']):

• ✅ Conceptual cohesion: Constructor options belong to the input, so nesting them there is logical
• ✅ No signature change: Maintains Sharp::run($io, $params) - no new parameter
• ✅ Consistent structure: Options stay within the input configuration where they semantically belong
• ❌ Deeper nesting: Requires $io['input']['options'] - more array depth
• ❌ Less discoverable: Options hidden inside input array structure

PR #3 (third parameter $constructorOptions):

• ✅ Clearer API: Explicit third parameter makes options more visible and discoverable
• ✅ Separation of concerns: Distinct from I/O configuration
• ✅ Shallower structure: Top-level parameter, not nested
• ❌ Signature change: Adds third parameter to Sharp::run() method
• ❌ Parameter order: Constructor options come after processing params, which is less intuitive (constructor happens first)
• ❌ Three parameters: Method signature becomes Sharp::run($io, $params, $constructorOptions) - more complex

Recommendation: PR #2 is preferable for maintaining a simpler method signature and keeping constructor options contextually grouped with input configuration.

[kiatng]

Closed in favor of PR #3