PHP SDK Quickstart

[bold drift]

That is definitely possible!
The PHP SDK is already using itself to run phpunit and phpcs

You can use the dev module there as a reference but I haven't updated it to use some of the latest features yet.

The PHP SDK is past the Proof of Concept stage, but is still considered new, experimental, etc.
As such you wont find it documented in the quickstart guide.

Put simply, if you have begun by following the Quickstart.
When you get to the part about initializing a module you'd instead call:

dagger init --sdk=php --source=./dagger

That would set up a basic skeleton for your module.

[bold drift]

I won't bombard you with everything at once but I assure you, it is possible to set up phpstan and php cs fixer through dagger. I've set up phpunit, phpstan and phpcs through dagger. I'm sure php cs fixer will work fine too.

If you do decide to give it a try, you can always ask questions as you go 👍

[cloud depot]

Sounds great, thanks for the pointers. Will try it out this week, possibly this afternoon.

[steep ledge]

As @bold drift mentioned, PHP SDK is experiemental, but there is a great group of Daggernauts that are managing it and are here to help 🙂

[viscid hawk]

@cloud depot more official docs are coming soon. I've started them, and working with some Dagger team members on that initative.

We had the christmas holiday season and such so just paused and we will be pickling it up in Jan/Feb to finish it all off

Meanwhile just ask questions or for examples on how to do soething, here in discord, and we will give you whatever you need

🙂

[cloud depot]

Great! Ive planned to try some things this afternoon.

The biggest issue i see now is getting dagger to work with gitlab and making sure that caching works. I saw the depot announcement for github. Something like it for gitlab would be great (unrelated to the php part of dagger). Just need some play time to figure that out.

[cloud depot]

Im trying the quickstart with the php sdk. Should it already work with 0.15.2? Is there a way i can share the trace here?

Im trying to write the buildEnv function as php code

[bold drift]

It will work with 0.15.2

[bold drift]

I don't know if there is an easy way to share traces unless it's from a public repo pipeline, I may be wrong though.

For an initial sanity check. This would be a brutally simple call to phpstan:

    #[DaggerFunction]
    public function brutallySimplePhpstan(Directory $project): Container
    {
        return dag()
            ->container()
            ->from('php:8.3-fpm-alpine')
            ->withMountedDirectory('/src', $project)
            ->withWorkdir('/src')
            ->withExec(['./vendor/bin/phpstan']);
    }

It would work, but it would rely on taking your vendor/ directory without using composer.
Naturally it would suck for a CI pipeline if we left it like that.

Also you may hit a memory limit with phpstan so it probably wants specifying.

Then it would look like this:

    #[DaggerFunction]
    public function simpleButCarefulPhpstan(
        Directory $project,
        string $memoryLimit = '1G',
    ): Container {
        return dag()
            ->container()
            ->from('php:8.3-fpm-alpine')
            ->withMountedDirectory('/src', $project)
            ->withWorkdir('/src')
            ->withExec([
                './vendor/bin/phpstan',
                "--memory-limit={$memoryLimit}"
            ]);
    }

But you'll want composer to install vendor/ on CI, so we could cram that in there.

#[DaggerFunction]
    public function independentPhpstan(
        Directory $project,
        string $memoryLimit = '1G',
    ): Container {
        $container = dag()
            ->container()
            ->from('php:8.3-fpm-alpine');

        $containerWithComposer = $container
                ->withFile('/usr/bin/composer', dag()
                ->container()
                ->from('composer:2')
                ->file('/usr/bin/composer'))
            ->withMountedCache('/root/.composer', dag()
                ->cacheVolume('composer-php:8.3-cli-alpine'))
            ->withEnvVariable('COMPOSER_HOME', '/root/.composer')
            ->withEnvVariable('COMPOSER_ALLOW_SUPERUSER', '1');

        $containerWithProject = $containerWithComposer
            ->withMountedDirectory('/src', $project)
            ->withWorkdir('/src');

        $containerWithProjectAndVendor = $containerWithProject
            ->withExec(['composer', 'install']);

        return $containerWithProjectAndVendor->withExec([
            './vendor/bin/phpstan',
            "--memory-limit={$memoryLimit}"
        ]);
    }

That works but obviously it's quite messy and that's where you can start splitting it up how you want into smaller, reusable functions

You'd split it exactly as you would any normal PHP function. You only need #[DaggerFunction] for functions you actually want to manually call

@cloud depot We've written a README that should have generated alongside your dagger module. It has some guidance on the basics of the PHP SDK and how to use it.

If you have trouble with anything in the README: outdated, confusing, misleading, etc. Let me know, I'll improve it.

[cloud depot]

Ill install discord on my dev machine and post the php stacktrace in half an hour.

I currently use the hello dagger quickstart so i can make a fork to get a public trace.

[viscid hawk]

@cloud depot

Is there a way i can share the trace here?

You can use github gist for showing us output.

If you're using Dagger Cloud to generate a profile trace, you can also make that trace public and share it with us .. jsut let us know so we can show you stuff.

[cloud depot]

I meant the dagger cloud. Just couldnt find a share button. Am i overlooking it?

This is what i'm seeing. Added this code to my HelloDagger.php to imitate the buildEnv step from the quickstart

#[DaggerFunction]
#[Doc('Build a ready-to-use development environment')]
public function buildEnv(Directory $source): array
{
    $nodeCache = dag().cacheVolume("node");
    return dag()
        .container()
        .from("node:21-slim")
        .withDirectory("/src", $source)
        .withMountedCache("/root/.npm", $nodeCache)
        .withWorkdir("/src")
        .withExec(["npm", "install"]);
}

So i'm stuck on this step: https://docs.dagger.io/quickstart/daggerize#construct-a-pipeline-using-dagger-functions I figured it just go through the quickstart and use the easiest function to get a feeling for how this works.

[bold drift]

So the issue there is atm you've set it to return an array

It can return an array, but it requires some extra work.

Also it doesn't look like you're returning an array

[cloud depot]

ah, some auto completed stuff, the error could use some DX 🙂

it now parses correctly, now it complains it can't run buildEnv.

Ok, also fixed that one, need to run with build-env instead of build_env or buildEnv. that is explained on the next page of the quickstart 🙂 . Now getting a new error

[ERROR] Call to undefined function DaggerModule\cacheVolume()

is that already supported in php?

[bold drift]

It is, but looking at the code I do notice that the notation looks like javascript/typescript

php uses -> instead of . for chaining methods

[cloud depot]

you are right, i just copied it in. Ok sorry about that

ok it's building now

[bold drift]

No problem.

Also I do agree, getting a clear error if the return type is different from what is returned might be handy...

It would probably be somewhat tricky and involve some phpstan levels of reflection

[cloud depot]

Thanks for the help, seems i can now really start playing with this. If possible having the quickstart docs with the php steps would be a good step to get people in i think.

Just like the note on the way to call dagger with build-env instead of buildEnv, the same note could be added on the return types. Which i probably wouldn't have hit if there was a php version of the quickstart code

Anyway, i understand it's early days and not an official sdk (yet?)

Maybe the readme you mentioned could have a little section on the quickstart?

[bold drift]

I completely agree. We would love to see the PHP SDK have a section in the quickstart.

There was some discussion on it a few months back but I think the consensus was that the docs would focus primarily on the SDKs updated by the dagger core team.

That is not to say there wont be any official docs for PHP, as @viscid hawk said, he's working on some docs in the near future.

[cloud depot]

I can understand that decision. Having a place where just the code examples are available which you can read next to the official docs would be a big help already. So maybe a quickstart.MD with just the code examples and some titles so you can read along the normal docs.

I can add a PR if you would want something like it and point me to the right git repo. i want to walk through the quickstart anyway.

[bold drift]

Okay so TODO:

• [] In the README Make it clear how methods are renamed: camelCase becomes kebab-case
• [] Add a QuickStart.md that covers something similar to the quickstart docs.

Did I miss anything?

[cloud depot]

Bonus points for extending the quickstart with an example on how doing phpstan 😉

or the tests quickstart but then use phpunit instead of npm test

Anyway, those 2 TODO points would already be a huge help for onboarding people i think

[bold drift]

Sounds good, I've made two issues for it

[cloud depot]

I'm now reading the readme and see a couple issues.

For example:
This example uses the old notation with #[DaggerFunction("description") instead of the new one. https://github.com/dagger/dagger/blob/main/sdk/php/runtime/template/README.md#check-module-functions

And it mentions src/Example.php but you need to know that this only works when running from the example directory. As in my quickstart case, it's called src/HelloDagger.php

Is it useful to submit a PR for those kinda issues? Or whats the best way to help out?

[bold drift]

Sorry if I'm missing it, which bit is the old notation?

[cloud depot]

https://github.com/dagger/dagger/pull/9409

the $description in DaggerFunction is deprecated

[bold drift]

Oh!

Wow, awkward on my part, I literally deprecated that myself XD

[cloud depot]

I think you fixed the other examples, just missed the first one

If i'm not following any practices with this PR, let me know. For example i've no idea how you want those PR's named. should it use a php prefix?

[bold drift]

You got the main one: sign-off on commits.

The only thing for bonus points would be to prefix with doc: https://docs.dagger.io/contributing/#commit-messages

Thank you for the quick PR!

[cloud depot]

will keep that in mind, probably more will follow

[bold drift]

That's completely fine, I'll merge it as soon as the pipeline passes.

Thank you for contributing! 🙂

[cloud depot]

I'll see if i can whip up a PR for a quickstart when i work through the official one somewhere during next week.

Thanks for the quick help, much appreciated

[viscid hawk]

@cloud depot I'm actively collaborating with the dagger team on the strategy and rollout of the PHP documentation. Stay tuned.

We have a bunch of stuff already documented, and ready to go, it's just about agreeing on the correct rollout strategy for this.

Docs is my highest priority right now

[manic onyx]

it does say in the error that if it occurs outside of SDK development, it's a bug. -> We should look at sorting that.