home / skills / windmill-labs / windmill / write-script-php

write-script-php skill

Q: How do I ensure the platform passes credentials into my script?

Define a class with the exact resource type name and fields you expect, guarded by class_exists. Windmill will instantiate and pass it to your main function.

Q: How do I add third-party PHP libraries?

List each package on its own comment line before main using the require: comment format. The runtime installs them and autoloading is already handled.

safe

/system_prompts/auto-generated/skills/write-script-php

This skill guides you in writing PHP scripts by structuring main function, resource types, and required libraries for Windmill workflows.

npx playbooks add skill windmill-labs/windmill --skill write-script-php

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: write-script-php
description: MUST use when writing PHP scripts.
---

## CLI Commands

Place scripts in a folder. After writing, run:
- `wmill script generate-metadata` - Generate .script.yaml and .lock files
- `wmill sync push` - Deploy to Windmill

Use `wmill resource-type list --schema` to discover available resource types.

# PHP

## Structure

The script must start with `<?php` and contain at least one function called `main`:

```php
<?php

function main(string $param1, int $param2) {
    return ["result" => $param1, "count" => $param2];
}
```

## Resource Types

On Windmill, credentials and configuration are stored in resources and passed as parameters to main.

You need to **redefine** the type of the resources that are needed before the main function. Always check if the class already exists using `class_exists`:

```php
<?php

if (!class_exists('Postgresql')) {
    class Postgresql {
        public string $host;
        public int $port;
        public string $user;
        public string $password;
        public string $dbname;
    }
}

function main(Postgresql $db) {
    // $db contains the database connection details
}
```

The resource type name has to be exactly as specified.

## Library Dependencies

Specify library dependencies as comments before the main function:

```php
<?php

// require:
// guzzlehttp/guzzle
// stripe/stripe-php@^10.0

function main() {
    // Libraries are available
}
```

One dependency per line. No need to require autoload, it is already done.

Overview

This skill guides you to write PHP scripts that run on the Windmill platform. It explains the required script structure, how to declare resource types, and how to list runtime library dependencies so your script runs as a deployable Windmill task. It also covers the basic CLI steps to generate metadata and push scripts to the platform.

How this skill works

Scripts must begin with the PHP opening tag and expose a main function that Windmill will call with parameters. Credentials and configuration are modeled as resource objects; you must redefine resource classes in your script (guarded by a class_exists check) so Windmill can marshal those resources into typed parameters. External libraries are declared as in-file comments and are auto-installed for the runtime.

When to use it

When authoring PHP tasks intended to run on Windmill
When your script needs platform-managed credentials or typed configuration
When you want to declare runtime third-party libraries for the script
When preparing scripts to be converted into webhooks, UIs, or workflows on the platform
When validating that resource types exist and are correctly typed before use

Best practices

Always start the file with <?php and define a main function with typed parameters
Redefine resource classes exactly using the resource type names and protect definitions with class_exists
Declare each external dependency as a single-line comment before main (one package per line)
Keep resource classes minimal: only include fields Windmill will supply (host, port, user, password, etc.)
Run metadata generation and push commands after writing or changing scripts to update the platform's catalogs

Example use cases

A PHP task that reads credentials from a Postgresql resource and runs a query
A webhook handler that uses guzzlehttp/guzzle to call an external API
A scheduled workflow step that requires stripe/stripe-php for billing operations
A simple string-processing script that returns structured results via the main function
A self-hosted deployment where scripts are stored in a folder and synced to Windmill

FAQ

How do I ensure the platform passes credentials into my script?

Define a class with the exact resource type name and fields you expect, guarded by class_exists. Windmill will instantiate and pass it to your main function.

How do I add third-party PHP libraries?

List each package on its own comment line before main using the require: comment format. The runtime installs them and autoloading is already handled.