Open question: You could have a @field annotation on a @type class with an "inputType" property declared.
Did you consider splitting @field into 2 classes: @Field and @InputField ?

I thought about this and came to a decision that it would be more convenient to describe fields for both type and input within one annotation. You can apply @Input and @Type annotation for the same class and in most cases you'd want to mark the same properties as fields.

With two annotations you'd need to do this twice which is kind of redundant:

/**
 * User entity.
 *
 * @GQL\Type()
 * @GQL\Input()
 */
class User
{
    /**
     * @var string Username or login
     *
     * @GQL\Field()
     * @GQL\InputField()
     */
    private string $username;

    /**
     * @var string User email
     *
     * @GQL\Field()
     * @GQL\InputField()
     */
    private string $email;

    /**
     * @var DateTimeInterface|null Birthday
     *
     * @GQL\Field()
     * @GQL\InputField()
     */
    private ?DateTimeInterface $birthday = null;
}

With one @Field annotation it looks more simple and clean:

/**
 * User entity.
 *
 * @GQL\Type()
 * @GQL\Input()
 */
class User
{
    /**
     * @var string Username or login
     *
     * @GQL\Field()
     */
    private string $username;

    /**
     * @var string User email
     *
     * @GQL\Field()
     */
    private string $email;

    /**
     * @var DateTimeInterface|null Birthday
     *
     * @GQL\Field()
     */
    private ?DateTimeInterface $birthday = null;
}

You need to separate input fields from output you can use for attribute.

But here it is the problem with inputType and outputType attributes. If I want to set the same type for both cases and the same field - which is 99% use case I think, I'd need to do this: @GQL\Field(inputType="Date", outputType="Date").

I considered alternative option - deprecate outputType and add another attribute type - which would suit for both input and output types. @GQL\Field(type="Date") looks much better. What do you think about that?

Ok, I understand your will to not repeat Field and InputField annotations. It makes sense.

I'm trying to assess if there are any corner-cases that might bother us in the future.

Let's imagine this:

/**
 * User entity.
 *
 * @GQL\Type()
 * @GQL\Input()
 */
class User
{
    // ...

    /**
     * @var string Username or login
     *
     * @GQL\Field()
     */
    private string $password;

    public function setPassword(string $password): void {
    	$this->password = $password;
    }
}

In this case, we have a @field annotation on the property, a setter, but no getter.

What should happen in your opinion? Should GraphQLite throw an error? (something like "Output field "password" is not reachable via a getter, please add a "getPassword" method). Or should we silently put only an input field and no output field?

(I'm trying to put as much attention as possible to all the error messages a user can have and to have meaningful error messages)

It's a good question.

Or should we silently put only an input field and no output field?

I don't think silently hiding fields is the way to go. At some point it might confuse developers, especially with models containing a lot of properties, why their field is not working even though there's a @Field annotation.

I like the idea of throwing an error. At the moment if you try accessing such field PHP will throw an error like Cannot access private property .... It would be much better to display a message as you suggested to give more accurate explanation of the problem.

Since fields can be set in the constructor, wouldn't it make sense if the @Field annotation could be declared in the constructor too? (the problem being that in @Field(for=...), the for is referring a typename right now and not a variable name (as in the rest of the application).

Also, something is coming to my mind: with the @Factory annotation, you can use many additional annotations like @Autowire, @UseInputType, etc... since a constructor is a kind of default factory, wouldn't it make sense to reuse a part of the code used to instantiate objects declared with the @Factory annotation?

I'm not sure if we should overload constructor with such logic. It's job is only to instantiate an object with a given parameters. Current implementation assumes that required constructor parameters have defined fields on properties with the same name in the class. When object is instantiated users payload is mapped to the constructor parameters.

For example:

/**
 * @GQL\Input()
 */
class User
{
    /**
     * @var string Username or login
     *
     * @GQL\Field()
     */
    private string $username;

    /**
     * @param string $username
     */
    public function __construct(string $username)
    {
        $this->username = $username;
    }
}

In this case we definitely know that input type has a field called username and it's required. There's a constructor parameter with the same name so when the object is instantiated value from the request payload will be passed to it. For this createInstance() function is responsible - this is kind of default factory, which knows how to map data to a constructor and instantiate an object.

I agree that it would be nice to provide a custom and flexible way of creating instances before they are populated with new data. At the beginning I thought of reusing @Factory. We could add a new attribute @Input(init="FactoryName"). But after that I realized that it's not very flexible. For example it would be nice to reuse the same input type in different mutations, but pre-load should be done with different identificators. For example:

updateUser(id: ID!, user: UserInput!)
updateUserByEmail(email: String!, user: UserInput)
updateMe(user: UserInput)

Considering this we'd need to create 3 different input types with the same fields but different init attributes.

As an alternative this init attribute could be added to @UseInputType annotation. This way we choose what type should be used and how the object should be initialized for each particular mutation. Also extra parameters such as "id: ID!" or "email: String!" described in factories could be mapped not to input types, but to mutations directly. I hope it won't be confusing. Here's an example of what I mean:

/**
 * @GQL\Type()
 * @GQL\Input()
 */
class User
{

    /**
     * @var string
     *
     * @GQL\Field(for="User")
     */
    private string $id;
    
    /**
     * @var string
     *
     * @GQL\Field()
     */
    private string $username;

    ...
}

...

class UserFactory
{

    /**
     * @Factory(name="LoadUser")
     * 
     * @param string $id
     * 
     * @return User
     */
    public function loadUser(string $id): User {
       // ... Load user from DB
    }
}

...

class UserController
{

    /**
     * @Mutation(name="UpdateUser")
     * @UseInputType(for="$user", inputType="UserInput!", init="LoadUser")
     * 
     * @param User $user
     * 
     * @return User
     */
    public function updateUser(User $user): User {
       // ... $user is loaded from DB and populated with given data. Just validate and save it. 
    }
}

Because @UseInputType points to "LoadUser" factory with init attribute, another field id will be added to the mutation as loadUser() function requires it as a parameter. So the request mapping will be like this:

updateUserByEmail(id: String!, user: UserInput)

My only concern is that it might be not obvious that by adding init attribute your mutation signature is split across different methods - actual mutation method and supportive "init" factory. It might be a bit confusing or not obvious...
What do you think about this idea? Do you see other ways to achieve this?

About the "init" idea: I would even go one step further. The concept of @factory is hard to explain and I'm getting a lot of people confused with it.

Since quite often, a factory is used by only one mutation, we could even imagine something like this:

class UserController
{

    /**
     * @Mutation(name="UpdateUser")
     * @UseInputType(for="$user", factory="UserFactory::loadUser", inputName="UpdateUserInput")
     * 
     * @param User $user
     * 
     * @return User
     */
    public function updateUser(User $user): User {
       // ... $user is loaded from DB and populated with given data. Just validate and save it. 
    }
}

and this might actually be easier to understand for many people.

Is UserFactory just some service with loadUser function and has nothing to do with @Factory annotation?

I considered similar approach, but in this case you'd need to specify an absolute class name. For example: @UseInputType(for="$user", factory="App\Services\UserFactory::loadUser", inputName="UpdateUserInput"). It will be easier to understand and use. Not sure only if it looks good in the code though 😄