Jane 8 overview

[Korbeil]

I think we should be fine with Jane 7 and its features so I would like to start thinking/planning about it , Jane 8 is planned to be for:

• PHP 8.1
• Typed properties
• Static analysis
• Split components
• Documentation

PHP 8.1

Let's move forward with PHP support ! PHP 7.4 support will be dropped within the end of 2022 so I think we should aim the current latest version (why not 8.2 since I don't think Jane 8 will be out before 8.2 is here).

Typed properties & static analysis

We are in 2022, typed properties are there since PHP 7 (almost 5y old already) let's start using them ! This will require a heavy refactoring of Jane but I think this is required to move forward and to make a new start !
Also, I believe static analysis should be used with high level everyone on the code and that's why I put a strong emphasis on this point. Nothing complex here, PHPStan with at least level 6 should be fine.
Also, I would like to replace current DTO with get/set methods by public typed properties (with readonly parameter when the OpenAPI spec tells to add it).
To finish, since I would like to type everything, this could be a good idea to use objects for parameters.

Split components

And to finish, most important thing I wanna do is to make components that have meaning. For example JsonSchema component handle parsing, metadata and generating while it should be splitted in a component for each task. This should also make Jane easier to understand as a developper or an OSS contributor when you look at the code !

Here is a schema on how I think it should be done:

Documentation

The current documentation and website of Jane old and does not help at all, it's hard to read it and missing lots of things.
I want that for this next version, while working on the new components, we write the documentation in the same time so nothing is missed and the documentation becomes something necessary !
A great tool to help on how to make documentation: https://diataxis.fr/

This issue is here to share my vision of Jane 8, if you have any ideas / things you want to propose feel free to do it ! I'll be glad to hear you out :)

[fbourigault]

This looks great!

What about using objects instead of arrays for query parameters?

[Korbeil]

What about using objects instead of arrays for query parameters?

This is indeed a good idea and something we should do so we can mutualize validation for both models & parameters (instead of using ParameterBag for parameters and Validator for models at the moment)

[uuf6429]

Maybe consider using public readonly instead of getters and promoted properties?
That would also dramatically reduce generated code.

old code:

class Entity
{
    /**
     * @var int|string 
     */
    private $theProperty;

    /**
     * @return int|string
     */
    public function getTheProperty()
    {
        return $this->theProperty;
    }

    /**
     * @param int|string $theProperty
     */
    public function setTheProperty($theProperty): void
    {
        $this->theProperty = $theProperty;
    }
}

new code:

class Entity
{
    public function __construct(
        public readonly int|string $theProperty,
        public readonly bool $theOtherProperty,
    ) {
    }
    
    public function withTheProperty(int|string $newTheProperty): self
    {
        return new self($newTheProperty, $this->theOtherProperty);
    }
    
    public function withTheOtherProperty(bool $newTheOtherProperty): self
    {
        return new self($this->theProperty, $newTheOtherProperty);
    }
}

[Korbeil]

@uuf6429 Thanks for your feedback ! I updated the main description according to that, I don't think I'll do the withX methods cause they can be numeros with more properties. But the public type properties is definitely a big yes ! For the readonly keyword, I'll prefer to use it only when the property is stated as readonly in the OpenAPI specification 😉

[uuf6429]

@Korbeil just to be clear: the intention of readonly+withX is to have immutable objects (and kind of forcing the constructor to be one big setter). As you mentioned, it also works, but they won't be immutable.

[Korbeil]

Hello there, I have focused a lot on this recently and started to make some parts of Jane v8, since it's a complete rewrite it will take some time but everything can be seen on this repository: https://github.com/Korbeil/jane-v8
I prefer to make a separate repository for now, when it will be ready I'll create a 7.x branch for current next and replace next branch with this repository contents.

Also, since documentation is one of my focus, you can found the work-in-progress documentation on the following URL: https://korbeil.github.io/jane-v8/

If any of you guys want to help or try to make things better feels free to comment or tell me what you would suggest 🙏

[l-you]

The minimum PHP version of Jane 8 should be PHP 8.2.
In 2023, Symfony requires PHP 8.2 as a minimum version for its components.