A Dagger module for managing Dagger modules that use the PHP SDK.
SDK-specific module authoring (scaffolding new modules, codegen) lives in
modules like this one. The engine drives the SDK: it records a module scope in
dagger.toml, sets the workspace cwd to it, and asks this module to generate
the scope through findClientRoot and generateScope. This module writes the
template files, the module's dagger-module.toml and the generated SDK files;
the engine owns the workspace bookkeeping. Dependencies between modules are
module clients, which this SDK generates into the sdk/ of a module or a PHP
program; see Module clients.
The PHP library and codegen live under sdk/, vendored from
dagger/dagger; sdk/VENDOR.md records the commit. Generation
writes them into each module with a client generated against
v1.0.0-beta.27.
A module requires PHP ^8.2, the floor of the library in sdk/composer.json. The
module image builds and runs with PHP 8.4. The library's dev tooling (PHPUnit 12)
needs PHP 8.3 or later. Modules do not need the dev tooling, so their floor stays
^8.2.
This module needs an engine from v1.0.0-beta.27, the release it generates
modules for. On an older engine, dagger generate and dagger module init stop
with a message that names the engine: upgrade the engine to generate. The engine
resolves its built-in PHP runtime from github.com/dagger/dagger/sdk/php, not
from this module, so a module on the built-in runtime still loads on an older
engine, without this module generating it.
From your workspace root:
dagger module install github.com/dagger/php-sdkThe engine recognizes the SDK interface and records the module as the php SDK
in dagger.toml. After install, the module is also available in dagger call
as php-sdk.
Calls that return a Changeset will print the diff and prompt you to confirm
before writing anything to your workspace.
dagger module init php --name my-moduleThe engine records the module scope in dagger.toml and calls generateScope,
which seeds the starter template, writes dagger-module.toml, the SDK and the
entrypoint in one step. Files already in the module directory are kept.
--template is default (a container function over the workspace) or
empty:
dagger module init php --name my-module --template emptyA module calls the core API from Dagger\core():
use function Dagger\core;
return core()->container()->from('alpine:3.24');Code written for the built-in PHP runtime calls the global client,
Dagger\dag(), which sdk/src/dag.php defines and sdk/src/functions.php
loads when the file is there. Generation keeps the file when the module is on the
built-in runtime ([runtime] source = "php", or "sdk": {"source": "php"} in a
legacy dagger.json) or its sdk/ already has dag(), in dag.php or in the
functions.php an earlier release of this SDK wrote. A new module does not get
it.
dag() returns the same client as core(), so it restores core calls only. Call
a dependency through Dagger\Clients\<Name>; see Module clients.
The globalClient setting overrides that: true writes dag(), and false
leaves it out. dagger call php-sdk mod ... generate reads it from
[sdks.php.scopes."<module path>".settings] in dagger.toml. The global client is
temporary: move the code to core() and set globalClient = false.
A role attribute next to #[DaggerFunction] registers the function for a CLI command. The
SDK rejects a role function that does not match its row in the table. An argument is
optional when it has a default value, a nullable type or #[DefaultPath]; others are required.
| Attribute | Command | Return type | Required arguments | Engine API since |
|---|---|---|---|---|
#[Check] |
dagger check |
Container or void |
Workspace only |
v0.19.7 |
#[Generate] |
dagger generate |
non-null Changeset |
Workspace only |
v0.19.11 |
#[Up] |
dagger start, alias dagger up |
non-null Service |
Workspace only |
v0.20.4 |
#[Agent] |
dagger agent |
non-null LLM |
exactly one required LLM; any other required argument is Workspace or Agent |
v1.0.0-beta.10 |
The engine floor, v1.0.0-beta.27, has all four APIs and commands.
Inside a #[DaggerObject] class, with the attributes from Dagger\Attribute:
#[DaggerFunction, Check]
public function lint(): Container
{
return core()->container()->from('php:8.4-cli')->withExec(['php', '--version']);
}
#[DaggerFunction, Generate]
public function generateFile(): Changeset
{
return core()
->directory()
->withNewFile('generated.txt', 'generated')
->changes(core()->directory());
}
#[DaggerFunction, Up]
public function serve(): Service
{
return core()->container()->from('alpine:latest')->asService();
}
#[DaggerFunction, Agent]
public function review(LLM $base): LLM
{
return $base->withPrompt('Review the code in this module');
}For every recorded PHP module scope:
dagger generateFor a single module:
dagger call php-sdk mod --path my-module generatemod walks up from --path to the nearest module config, supporting both CLI
1.0 dagger-module.toml and legacy dagger.json. rootPath is the stable
workspace-root-relative identity; path is relative to the caller's current
directory.
See php-sdk.dang for the full type surface.
Generation writes sdk/ and a Dang entrypoint in sdk/entrypoint/: main.dang,
types.dang, build.dang and dang.toml. dagger-module.toml names the
entrypoint, and the engine runs a function through it, including its
role. Commit sdk/ and
composer.lock: a module loaded from Git needs them.
A module on the built-in PHP runtime moves to the entrypoint when it is self-contained. This SDK does not have the engine generate a module on that runtime. Generation refuses a module that has any of the following and changes nothing. The refusal names each reason it finds from the module's files and points to Migrate from the built-in PHP runtime. An exclusion of a file generation writes is found only by generating the module, so it is reported once the other reasons are fixed. Each reason comes with its fix:
[[dependencies]]that no client of the scope provides: add each dependency as a client; see Module clients.dagger call php-sdk mod ... generatedoes not know the scope's clients, so it refuses a module with dependencies or clients: rundagger generate.blueprint: the generated entrypoint has no equivalent; remove it.toolchains: rundagger module migrate, which records them as clients.- a
[[clients]]table: remove the table and add each client withdagger module client add. disableDefaultFunctionCaching = true: remove it. The generated entrypoint caches every function by default, and no PHP attribute sets a cache policy.- an
engineVersionlater thanv1.0.0-beta.27: set it tov1.0.0-beta.27or lower. - a
sourceother than the module directory: move the module; see Migrate from the built-in PHP runtime. - a Composer
vendor-dirother thanvendor: removeconfig.vendor-dirfromcomposer.json. The generated entrypoint loadsvendor/autoload.php. - a Composer path or autoload path that is absolute, starts with
~, holds a variable, has a..after a directory name, leaves the workspace, or names the workspace root, or that names a file outside the module: point it at a directory of the workspace, reached through leading..segments only. - an
includepath outside the module that is absolute, holds a variable, leaves the workspace, names the workspace root or a file, or is a glob; an exclusion outside the module; or a plainincludepattern after an exclusion, unless it names a directory beside the module rather than one above it: change the patterns; see Migrate from the built-in PHP runtime. - an exclusion of a file generation writes, such as
sdk/orcomposer.json, or of a name that starts with!: remove the exclusion.
This SDK does not move a module with a runtime other than php, or with an
entrypoint it did not write, to the generated entrypoint.
A module without composer.json also moves to the entrypoint. Generation first
adds the starter template's files that the module does not have, as the engine's
PHP runtime does. The template setting selects the template. A new module in a
directory that already has a composer.json keeps it and gets no starter files.
A module whose composer.json has no path repository ./sdk also moves to the
entrypoint. Generation adds that repository and the requirement
dagger/dagger: *@dev with Composer's own commands, as it does for a PHP
program. Module clients describes that wiring. These commands
keep the other keys but may reformat the file. They replace a dagger/dagger
requirement that the module already has, such as a version from Packagist. A
module that already has the ./sdk repository keeps its composer.json
unchanged.
A Composer path repository or autoload directory outside the module, such as ../lib,
moves with the module. Generation lists each such directory in the manifest's
include, so the engine loads it with the module. The engine loads a local
module's files from its Git repository, so the directory must be inside that
repository. Run dagger generate again after you change those paths.
The engine loads such a directory as it loads any include path: for a local
module, every file its .gitignore rules keep, vendor/ and a nested .git
included unless a rule ignores them; for a Git module, every committed file.
Ignore vendor/ in that directory's .gitignore to keep it out of the module's
context. The build installs the module's dependencies itself and does not read it.
Generation fails for such a path in the cases below. A failed generation applies none of its changes.
- The path holds no file.
.gitignoredrops every file of the path.- The path goes through a symlink.
A module with include or exclude patterns inside the module also moves to the
entrypoint. The engine always loads the module directory, so a plain pattern
changes nothing. An exclude entry, or an include pattern that starts with !,
drops files: the engine leaves them out of the module. The migrated manifest keeps the
patterns in include, with each exclude entry as a ! pattern. Every generation
reads them again, so editing include and running dagger generate updates the
build.
A plain include directory outside the module, such as ../data, moves with the
module, as a Composer path outside it does. Generation lists the Composer
directories outside the module before the patterns. It does not remove an entry
it added. After you remove such a Composer path, remove its entry from include
too.
A module with [[dependencies]] moves to the entrypoint when each dependency is a
client of its scope; see Module clients. In dagger/dagger
v1.0.0-beta.27, dagger module migrate records a module's dependencies as the
clients of its scope (core/workspace/migrate.go, MigratedModuleClients).
Generation drops [[dependencies]] from the manifest and generates each dependency
as a client.
A dependency matches a client by its source only, whatever the dependency's name,
so a dependency named by an alias matches the client of its source. A local path
is relative to the module. A Git ref must be spelled as the client was added,
with the same version or version query such as @v1, or at the client's pin; a
dependency with a pin is compared at that pin. A ref with a # selector, such
as https://host/org/repo#v1:sub, is refused: write it as host/org/repo/sub@v1. A
dependency written as a source string, as in a legacy dagger.json, is read as
that source.
Generation refuses a dependency that no client provides. The message lists one
dagger module client add <source> command per such dependency, to run from the
module directory. The command names the dependency's pin in place of its
version when the dependency has one.
The runtime generated a dependency's types into namespace Dagger, next to core, and
its constructor on dag(). A client generates them into Dagger\Clients\<Name>, and
its constructor is a static method of Dagger\Clients\<Name>\Client. Generation does
not change the module's code, and does not detect a call through the runtime's API:
such a call fails when it runs. Update the module's code when it moves:
// On the runtime:
$report = dag()->lister()->lint($source);
// On the entrypoint:
use Dagger\Clients\Lister\Client as Lister;
$report = Lister::lister()->lint($source);A module already on the generated entrypoint fails to generate when it gains one of these patterns or Composer paths.
Generating the entrypoint fails for an enum whose cases the engine would give one name,
such as Low and LOW, because the engine would replace one with the other without
an error. The message names the enum and both cases. The failed generation applies none
of its changes: the module's manifest and sdk/ stay as they were, so a module moving
from the built-in runtime stays as it was until you rename one of the cases and update its
references. The engine can still update the workspace's dagger.lock when the session
ends. A generated entrypoint gets this check the next time it is generated.
Generation asks the engine for the names. It names Base64 BASE64, not BASE_64,
so Base64 and BASE64 collide and Base64 and BASE_64 do not.
A PHP interface with #[DaggerObject] is a module interface. A module function
can take a module interface, or a list of one, as an argument. Generation writes a
class for each module interface into sdk/generated/ModuleInterfaces/. The function
receives the argument as an instance of that class.
Every method of a module interface needs #[DaggerFunction]. No method can be
static or variadic, or be named id or queryLeaf. A module interface cannot have
a constant named GRAPHQL_TYPE. A function of a module interface takes and returns
only bool, int, float, string, void and non-null core objects such as
Directory.
A module function can return a module interface, or a list of one, that it received as an argument. An object field cannot hold a module interface. A module loaded under another name, as a dependency alias, cannot take its own interfaces.
Generation refuses a module on the built-in PHP runtime that cannot move to the
generated entrypoint, for the reasons listed in
Generated entrypoint, and the refusal points here. One
such module stops dagger generate for its whole scope. The module still loads,
because the engine regenerates it when it loads. To move the module, apply the
fix of each reason, then run dagger generate.
A module whose source is not the module directory is refused. The
generated entrypoint builds from the module directory, and a version 2 manifest
has no source key. To move the module:
- Move the files of the source directory, such as
composer.json,composer.lockandsrc/, into the module directory. - Remove
sourcefromdagger-module.toml. - Run
dagger generate.
Moving dagger-module.toml into the source directory, and removing source from
it, also moves the module. That changes the module's directory, which
dagger.toml records for the module's scope. This README does not cover updating
dagger.toml after such a move. Moving the files up, as in the steps above, keeps
the module's directory.
A module whose include or exclude pattern is refused needs the pattern
changed. To move the module:
- Change an
includeglob outside the module to the directory it reads, such as../libfor../lib/*.php. The module then loads every file of that directory, not only the files the glob matched. - Remove an exclusion outside the module.
- Check which files each exclusion matches. The engine leaves every one of them out of the module.
- Remove a plain
includepattern that follows an exclusion, unless it names a directory beside the module. - Run
dagger generate.
A module with an entrypoint this SDK did not write keeps that entrypoint.
Generation does not change the entrypoint, and the engine runs it as written. A
module in a PHP scope whose runtime is not php keeps that runtime, and
generation changes no files.
The engine reads the entrypoint from the module's files, which .gitignore filters.
Generation appends rules to the module's .gitignore and changes no existing rule:
!/sdk/ and !/sdk/** after any rule other than a vendor/ rule, and /vendor/
when no rule ignores vendor/. An ignore rule in a directory above the module still
applies. Remove that rule yourself.
The SDK manages the Dagger version in sdk/entrypoint/dang.toml, and sets it to the
version the module's client is generated against, v1.0.0-beta.27. Generation
replaces dagger = true or an older version on the Dagger import, requires
dang = "2.1", and keeps every other setting. Comments and formatting are lost, and
keys are written in alphabetical order.
Generation fails, and applies none of its changes, in these cases:
dangdeclares another language version.- The
Daggerimport has apathor a non-emptyendpoint. - Another import declares a different Dagger version.
- An import has a
pathinsidesdk/, which generation replaces. sdk/entrypoint/dang.tomlexists and the module's manifest does not name the entrypoint this SDK wrote.sdk/exists and is not this SDK's library.- A
dang.tomlabove the entrypoint within the module holds settings that the generated file would hide. Files are not merged, so move those settings intosdk/entrypoint/dang.toml.
Generation never changes a dang.toml above the entrypoint.
dang = "2.1" is the language version. The version on the import is a Dagger
version, and parsing it needs Dang v2.2.0. Standalone Dang tooling older than v2.2.0
may reject the import.
The engine selects the module's API view from that import, and its calls from
DAGGER_CLIENT_VERSION on the exec that runs the module, which carries the same
version. The engine names the module's types, functions and enum members by the
identifier rules of that version.
findClientRoot detects the PHP client root containing your current directory:
the nearest composer.json at or above it. This is how
dagger module client add finds the module you are standing in. The SDK
vendored under a module's sdk/ has a composer.json of its own; from there
the module that owns it answers.
Detection records nothing. The scopes dagger generate regenerates are the ones
recorded in dagger.toml under [sdks.php.scopes."<path>"].
The engine's dagger module client add, dagger module client rm and
dagger generate commands record a module's clients in its scope in
dagger.toml and regenerate the module with them. A local client's path is
relative to the directory that holds dagger.toml.
Each client generates into sdk/generated/Clients/<Name>/, in namespace
Dagger\Clients\<Name>, where <Name> is the client module's name in PascalCase.
sdk/composer.json already autoloads it, so the module's composer.json does not
change. A call starts from a static method of the class Client, named after the
client module:
use Dagger\Clients\Lister\Client as Lister;
$report = Lister::lister()->lint($source);A client shares the session of Dagger\core(), so core
objects such as a Dagger\Directory pass into its calls. A Git client is bound to
its address and to the commit the engine resolved it to. Commit sdk/ with its clients.
A scope without a module is a PHP program, such as a Composer project that calls
Dagger. Its clients generate the same way, against the same core schema as a
module's, without workspace fields such as currentWorkspace. Generation also adds
the path repository ./sdk and the requirement dagger/dagger: *@dev to its
composer.json with Composer's own commands, which keep the other keys but may
reformat the file, then updates composer.lock. When the last client is removed,
generation keeps the Composer wiring and regenerates sdk/ without clients. A
program with no clients and no sdk/ from this SDK is left unchanged. A program
loads a local client's module by its path from the root of the workspace it runs
in. Commit sdk/, composer.json and composer.lock.
Generation fails, and applies none of its changes, in these cases:
- The module cannot move from the PHP runtime; see Generated entrypoint.
- A scope without a module and without
composer.jsonis given clients. - A program's
composer.json, or a module's without the./sdkrepository, names another repositorydagger-sdk, which generation would replace with./sdk. - The Composer repositories of such a program or module install
dagger/daggerfrom somewhere other than./sdk, such as an earlier repository or a filter on./sdk. - A client is the module itself, by its path. A module of a workspace opened from Git can arrive as a Git client, which this check does not catch.
- Two clients have the same name once case and separators are ignored, such as
file-listerandFileLister. - A client module declares a release before the identifier-casing cut at
v1.0.0-beta.26. The engine names the client module by the rules of the release it declares, whatever the API view of the session that calls it, and its client uses the names ofv1.0.0-beta.27. Set the client module'sengineVersiontov1.0.0-beta.27. - A module function takes or returns a client's type. The message is in the generation's log; the error itself carries only the exit code.
- A client module adds a field to a core type other than
Query.
To exclude a directory tree from generation, drop an empty
.dagger-php-sdk-skip-generate file at or above the module root. Useful for
fixtures, vendored modules, or anything you don't want regenerated in bulk.
touch some/fixture/.dagger-php-sdk-skip-generate