php-sdk.dang

"""
Manage Dagger modules that use the PHP SDK.
"""
type PhpSdk {
  # Matches `"sdk": { "source": "php" }` in a legacy dagger.json.
  let legacyConfigPattern = "\"sdk\"\\s*:\\s*\\{[^}]*\"source\"\\s*:\\s*\"php\""

  # Matches a `[runtime]` table with `source = "php"` in a CLI 1.0
  # dagger-module.toml.
  let tomlConfigPattern = "\\[runtime\\][^\\[]*source\\s*=\\s*\"php\""

  let moduleConfigFilenames: [String!]! = ["dagger-module.toml", "dagger.json"]

  """
  Marker filename that skips generate when found at or above a PHP SDK module root.
  """
  pub skipGenerateFilename: String! = ".dagger-php-sdk-skip-generate"

  """
  Runtime source to write into modules created by this SDK.
  """
  pub targetRuntime: String! { "php" }

  """
  Return every managed PHP SDK module visible from the client's cwd: every
  module at or below the cwd, plus the nearest enclosing module when the cwd
  itself is not managed.

  The engine owns both the managed list and the cwd policy, so the SDK does no
  filesystem discovery of its own. Paths come back workspace-root-relative, the
  currency Mod.rootPath uses.
  """
  pub modules(ws: Workspace!): [Mod!]! {
    currentModule
      .asSDK(workspace: ws)
      .modules.{{path}}
      .map { module => Mod(rootPath: module.path, ws: ws, skipGenerateFilename: skipGenerateFilename) }
  }

  let normalizePath(path: String!): String! {
    let normalized = path.trimPrefix("./").trimPrefix("/").trimSuffix("/")
    if (normalized == "") { "." } else { normalized }
  }

  """
  Return init templates tracked by this module.

  Templates live under templates/<name> and are materialized into the new
  module before generation. Passing an empty template to init uses the module
  default.
  """
  pub templates: [Template!]! {
    if (currentModule.source.exists("templates")) {
      let root = currentModule.source.directory("templates")
      root.entries.map { name =>
        Template(
          name: name.trimSuffix("/"),
          source: root.directory(name),
        )
      }
    } else {
      directory.entries.map { name =>
        Template(
          name: name,
          source: directory,
        )
      }
    }
  }

  """
  Return the PHP SDK module at or above a workspace path.

  When `findUp` is true, `path` may point inside the module.
  """
  pub mod(ws: Workspace!, path: String! = ".", findUp: Boolean! = true): Mod! {
    let modPath = if (findUp) {
      # Pick the nearest enclosing config regardless of filename ordering.
      let foundConfigPath = moduleConfigFilenames.reduce(null) { nearest, filename =>
        let found = ws.findUp(filename, path)
        if (configHitDepth(found) > configHitDepth(nearest)) { found } else { nearest }
      }
      if (foundConfigPath == null) {
        raise "no Dagger module found containing path: " + path
      } else {
        let configPath = foundConfigPath.trimPrefix("/")
        if (isPhpConfig(ws, configPath) == false) {
          raise "Dagger module does not use the PHP SDK: " + path
        } else {
          let dir = configPath.split("/").dropLast(1).join("/")
          if (dir == "") { "." } else { dir }
        }
      }
    } else {
      normalizePath(path)
    }

    Mod(
      rootPath: modPath,
      ws: ws,
      skipGenerateFilename: skipGenerateFilename,
    )
  }

  """
  Return the depth of the directory containing a find-up result.
  """
  let configHitDepth(hit: String): Int! {
    if (hit == null) {
      -1
    } else {
      let dir = hit.split("/").dropLast(1).join("/").trimPrefix("/")
      if (dir == "") { 0 } else { dir.split("/").length }
    }
  }

  """
  Whether a module config selects the PHP runtime.
  """
  let isPhpConfig(ws: Workspace!, configPath: String!): Boolean! {
    let pattern = if (configPath.trimSuffix("dagger-module.toml") != configPath) {
      tomlConfigPattern
    } else {
      legacyConfigPattern
    }
    ws
      .directory("/", include: [configPath])
      .file(configPath)
      .search(
        pattern: pattern,
        multiline: true,
        dotall: true,
        limit: 1,
      )
      .{{id}}
      .length > 0
  }

  """
  Initialize PHP-owned files for a new Dagger module.

  Returns a Changeset with only the SDK-owned template files layered onto the
  new module's `path`. Engine-owned files (dagger-module.toml, workspace config
  updates) are produced by the engine and merged with this changeset.

  Pass `template` to materialize files from templates/<template>. The empty
  default uses this module's minimal template.
  """
  pub initModule(ws: Workspace!, name: String!, path: String!, template: String! = ""): Changeset! {
    let rawPath = path.trimPrefix("./").trimPrefix("/")

    let modPath = if (rawPath == "" or rawPath == ".") {
      "."
    } else if (rawPath == ".." or rawPath.trimPrefix("../") != rawPath) {
      raise "path escapes workspace: " + rawPath
    } else {
      rawPath.trimSuffix("/")
    }

    let selectedTemplate = if (template == "") { "minimal" } else { template }

    if (currentModule.source.exists("templates/" + selectedTemplate) == false) {
      raise "unknown init template: " + template
    } else {
      # modPath is workspace-root-relative: a relative path resolves from
      # ws.cwd and would be prefixed a second time on a direct call from a
      # subdirectory.
      let target = if (modPath == ".") { "/" } else { "/" + modPath }

      # Init must never remove files a user already keeps at the module path.
      ws.withDirectory(target, renderedTemplate(name, selectedTemplate)).changes(ws)
    }
  }

  """
  Generate a typed PHP client for `module` at `path`.

  The engine records the managed client in workspace config before calling
  this function. The engine owns materializing the generated client files.
  """
  pub initClient(ws: Workspace!, path: String!, module: String!, dev: Boolean! = false): Changeset! {
    changeset
  }

  """
  Render a PHP template with the requested module name.
  """
  let renderedTemplate(name: String!, templateName: String!): Directory! {
    container
      .from("golang:1.25-alpine")
      .withoutEntrypoint
      .withMountedCache("/go/pkg/mod", cacheVolume("go-mod"))
      .withMountedCache("/root/.cache/go-build", cacheVolume("go-build"))
      .withDirectory("/helper", currentModule.source.directory("helpers/render-template"))
      .withDirectory("/template", currentModule.source.directory("templates/" + templateName))
      .withWorkdir("/helper")
      .withExec(["go", "build", "-o", "/usr/local/bin/render-template", "."])
      .withExec(["render-template", name, "/template", "/rendered"])
      .directory("/rendered")
  }

  """
  Generate every managed PHP SDK module visible from the client's cwd.

  Modules with the generate skip marker are skipped.
  """
  pub generateAll(ws: Workspace!): Changeset! @generate {
    changeset.withChangesets(
      modules(ws)
        .filter { mod => mod.skipGenerate == false }
        .map { mod => mod.generate },
    )
  }
}