Forem: Alexander Schnitzler

Extbase entities and lazy loaded typed properties

Alexander Schnitzler — Sun, 18 Sep 2022 16:33:59 +0000

Hi folks,

today I want to write about property types for lazy loaded entity properties in extbase:

use TYPO3\CMS\Extbase\Annotation as Extbase;

class Foo
{
    /**
     * @Extbase\ORM\Lazy
     * @var Bar
     */
    private $bar;
}

That's how things looked until PHP 7.3, but how do we deal with it with it with PHP 7.4+ (property types) and PHP 8.0+ (union types)?

Well, let's start with 7.4 and also take \TYPO3\CMS\Extbase\Persistence\Generic\LazyObjectStorage into account.

Something we cannot do with PHP 7.4 is to use union types. The following example look neat but is impossible to implement.

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

class Foo
{
    /**
     * @Extbase\ORM\Lazy
     */
    private Bar|LazyLoadingProxy|null $bar = null;
}

But missing union types in PHP 7.4 aren't the only limitation we are facing here. There is a limitation/bug in extbase's reflection framework which lets extbase only detect a single type even in phpdoc blocks. So annotating @var Bar|LazyLoadingProxy already leads to an error as extbase does skip the whole property processing.

So the last example isn't working due to a missing language feature (in PHP 7.4), but the following example isn't working because of a limitation/bug in extbase:

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

class Foo
{
    /**
     * @Extbase\ORM\Lazy
     * @var Bar|LazyLoadingProxy
     */
    private $bar;
}

Given the circumstances, what's the best approach here to be as strict and meaningful as possible? Here's my current best practice:

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

class Foo
{
    /**
     * @Extbase\ORM\Lazy
     * @var Bar|null
     * @phpstan-var Bar|LazyLoadingProxy|null
     */
    private ?object $bar = null;
}

As phpdoc take precedence in extbase, the ?object property type is not relevant for extbase, but it already narrows down the allowed types. Depending on your IDE and it's support for custom annotations for static code analysis tools like phpstan, it will or will not know that the property can be a LazyLoadingProxy, but it will at least know the type is null or Bar. PHPStan, in this case, will know the whole truth and to me that's more important than full IDE support.

Speaking if LazyLoadingProxy...
\TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy::_loadRealInstance() is our public api to resolve the actual value of the proxy but unfortunately, the return type annotation of that method is just wrong. It says object which is neither specific nor correct. The actual return type is hard to tell because it is actually dynamic, in theory at least. It's very unlikely that the internal logic may fail but from a static code analysis standpoint, it's possible. If the actual value of the proxy cannot be resolved, _loadRealInstance() returns the actual value of the property, which in most cases is null. This means, the following code can break:

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

class Foo
{
    /**
     * @Extbase\ORM\Lazy
     * @var Bar|null
     * @phpstan-var Bar|LazyLoadingProxy|null
     */
    private ?object $bar = null;

    public function getBar(): ?Bar
    {
        return $this->bar instanceof LazyLoadingProxy
            ? $this->bar->_loadRealInstance()
            : $this->bar;
    }
}

It's really just a theoretical case but my best practice for those getters looks like this:

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Persistence\Generic\LazyLoadingProxy;

class Foo
{
    /**
     * @Extbase\ORM\Lazy
     * @var Bar|null
     * @phpstan-var Bar|LazyLoadingProxy|null
     */
    private ?object $bar = null;

    public function getBar(): ?Bar
    {
        if ($this->bar instanceof LazyLoadingProxy) {
            /** @var Bar|null $resolvedValue */
            $resolvedValue = $this->bar->_loadRealInstance();
            return $this->bar = $resolvedValue instanceof Bar
                ? $resolvedValue
                : null;
        }

        return $this->bar;
    }
}

What about LazyObjectStorage?

Right, there is LazyObjectStorage as well. How to deal with that? Well, this is a lot easier because LazyObjectStorage is a sub class of ObjectStorage which enables us to write this code:

use TYPO3\CMS\Extbase\Annotation as Extbase;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;

class Foo
{
    /**
     * @Extbase\ORM\Lazy
     */
    private ObjectStorage $bar;

    public function __construct() {
        $this->initializeObject();
    }

    public function initializeObject() {
        $this->bar = new ObjectStorage();
    }

    public function getBar(): ObjectStorage
    {
        return $this->bar;
    }
}

We completely omit the LazyObjectStorage type here because we really don't need it. There is no benefit for PHPStan and the like to know, neither for your IDE or you personally because the api of LazyObjectStorage is the same as for ObjectStorage and the underlying code can work the same both. Easy, right?

That's it for today.
Have a nice one!

Extbase entities and property types

Alexander Schnitzler — Sat, 17 Sep 2022 17:17:20 +0000

Hi folks, me again, with a post about extbase entities and property types.

We all were happy when PHP 7.4 introduced property types, right? We were able to finally switch from

class Foo {
    /**
     * @var string
     */
    private $bar;

    public function __construct() {
       $this->bar = 'string';
    }
}

class Foo {
    private string $bar;

    public function __construct() {
       $this->bar = 'string';
    }
}

except with extbase, we didn't, not to all extends. At least not until recently. Let's talk TYPO3(extbase) versions. There is this patch https://review.typo3.org/c/Packages/TYPO3.CMS/+/72005 which took care of uninitialized properties but it has only been merged to main and 11.5. So with 10.4 and prior we still have a little problem I'd like to shorty write about.

You may have noticed already that I mentioned uninitialized properties. Let me explain in detail with a couple of examples.

class Foo {
    private string $bar = '';
}

This is an initialized property, i.e. a property which has a default value assigned. Let's say we instantiate that class and call get_object_vars() on it.


$object = new Foo();
var_dump(get_object_vars($object));
// array(1) {
//   ["bar"]=>
//   string(0) ""
// }

You can see that get_object_vars() detects property bar, but only because it is initialized. And this is where our problem begins.

Back then, before PHP 7.4, all our properties were initialized by default with null. Because all properties were by default capable of being nulled.

class Foo {
    /**
     * @var string
     */
    private $bar;
}

We find a lot of code snippets like these in legacy code bases. And while the phpdoc type expressed the desired/intended property type, it's actually wrong. The property can hold any value and is null by default. So what do we often do? We simply transform the code like this:

class Foo {
    private string $bar;
}

But now, the property is unitialized, it may no longer be nulled and can only be assigned a string. PHP wise this is completely valid code. But transforming extbase entities like this in a code base prior to 11.5, you will run into trouble.

Up until 10.4, extbase used get_object_vars() to detect properties and up to and including PHP 7.3 this was no problem because all properties were always initialized and said method detected all properties. With 7.4 this changed and with extbase loosing information about the existence of properties, it may no longer set the property value when reconstituting entities from the database.

As mentioned, there is a fix in 11.5 but what if you are still on 10.4 or lower? Here's a best practice for you:

class Foo {
    private string $bar = '';
}

If you have a property that can be initialized with a default value, like the value you also store as default in your database, do so. Even if you have a constructor that also sets a default value:

class Foo {
    private string $bar = '';

    public function __construct(string $bar) {
       $this->bar = $bar;
    }
}

Your IDE will most likely try to tell you, you don't need the default property value, but stick with it. Also tools like PHPStan and Psalm will most likely raise an error but you need to ignore this because in this case you know better...

But what about properties that cannot be initialized, like those holding relations to other entities? Well, the only possible way is to allow and default to null:

class Foo {
    private ?Bar $bar = null;
}

Even so if you know that relation cannot be null. Ugly, right? Let's say you are using your entities only to display data (database records) in your view and your TCA makes sure, the relation is set. Well, in that case my recommendation is to throw an Exception in the getter:

class Foo {
    private ?Bar $bar = null;

    public function getBar(): Bar
    {
        if ($this->bar instanceof Bar) {
            return $this->bar;
        }

        throw new \DomainException(
            'Foo::$bar is unexpectedly null'
        );
    }
}

I do recommend throwing an exception because that avoids a possible null value you have to deal with in underlying code. And since this case is never expected to happen, you are in the clear here.

And that's it for today. I hope this post helps you understand the framework problem and the workaround. And if you can update to 11.5, all the better!

Have a nice one.
Cheers.

symfony/form component in extbase controllers

Alexander Schnitzler — Fri, 25 Jan 2019 18:55:22 +0000

Hi folks,
during the christmas holidays in 2018 I wondered if it would be possible to use the symfony/form component in extbase controllers. For those who don't know: extbase is the extension framework of TYPO3.

tldr;

It worked! Here is a demo:
https://github.com/alexanderschnitzler/extbase-with-symfony-forms-demo

So, why did I do it anyway?

There are dozens of solutions for rendering forms in TYPO3. Extensions like powermail, formhandler, formz and many more. And on top of that, there is the core extension called form. And guess what, that's right. But I never aimed for a fully fletched competitor. All I have to offer is a proof of concept.

I got the idea when I upgraded a client's website and there were compatible versions for all extensions but for that one form extension. And when I realised that the form couldn't be more simple, I thought: It's so easy to build forms with symfony/form, can I have that in TYPO3?

And what do you do if you ask yourself such things? You google.
First thing I tried was symfony/form standalone and I had an instant hit:
https://github.com/lostedboy/symfony-form-standalone

Well, the example code was a bit outdated and that's where most of the work went into. I tried to use the code with symfony version 4.2 but it turned out that the api changed. So I had to reverse engineer and try thing and eventually understand things. Until I came up with a working setup.

As mentioned earlier, I put the proof of concept in a demo repository on github and if you are interested to see code, check it out. If you want to see the thing in action, read the README.md, follow the install instructions and you're good to go.

The good parts

If you check out the code you'll see that there is not only a simple form but a few more features that come in quite handy if dealing with forms.

First of all, you almost alway want validation. Well, it's in there. However, the shown solution doesn't support validation via doctrine/annotation annotations, buuuut, that would be possible to achieve as well.

Then, you might want to have a working solution against CSRF. Guess what? It's in there! symfony/security-csrf does a great job!

What else? Well, some might want to use twig and its form helpers. Guess what? Yes, it's in there! Ok, it's not that awesome but still, it's nice to have, isn't it?

The bad parts

Where there's light, there's shadow.

Not always true but in this case, well, there is a downside. First of all you need to setup your TYPO3 installation with composer. Yes, unfortunately it's still possible to just grab a tar ball and extensions with dependencies to other packages are worthless. But maybe all this might help raise a little awareness for how great it is to use composer to setup TYPO3.

Another downside is the initialization of all components that take place in the controller itself. Of course, a proper solution would look different. But, maybe, this is a blueprint for future developers that want to bring that into the TYPO3 core.

Well, that's it for the bad parts.

Thanks for reading and until the next one.