Is there a standard way to document the expected class of entities inside a Collection in the docblock comment in a Doctrine project? Something like:
/**
* #var Collection<User>
*/
protected $users;
Looks like PHPDoc is the de-facto standard for docblock annotations now, but I couldn't find any mention for this use case.
Here is a solution that enables you to have autocompletion both on the Collection methods and your objects methods:
/**
* #param Collection|User[] $users
*/
public function foo($users)
{
$users-> // autocompletion on Collection methods works
foreach ($users as $user) {
$user-> // autocompletion on User methods work
}
}
It works like a charm in PhpStorm at least.
UPDATE 2022
Doctrine now documents the generic types of Collection with the #template syntax, which is nowadays supported by PhpStorm & static analysis tools (Psalm & PHPStan) at least:
/**
* #var Collection<int, User>
*/
protected Collection $users;
The old PhpStorm hacky way of documenting this, Collection|User[] is no longer required.
There are a few different ways to document expected variables. Have a look at the phpDoc documentation for a full list of available tags.
class MyClass
{
/**
* Users collection
* #var \Doctrine\ORM\ArrayCollection
*/
protected $users;
/**
* My method that doesn't do much
* #param \Doctrine\ORM\ArrayCollection $users
* #return void
*/
public function myMethod(\Doctrine\ORM\ArrayCollection $users)
{
/** #var \Entities\Users $user */
$user = current($this->users);
}
}
I think User[] should work. Don't remember where I found that.
Related
I have defined an interface for an ordered list. The class docblock looks like this:
/**
* Interface ListOrderedInterface
* #template ListOrderedElement
*/
Within the method docblocks for this interface, ListOrderedElement is used to ensure that the type of thing being added to the list is consistent. PHPStan runs clean on ListOrderedInterface.php. So far so good.
Next I defined an interface for a factory that makes an ordered list. The definition looks like this:
/**
* Class ListFactoryInterface
*/
interface ListOrderedFactoryInterface
{
/**
* makeList
* #return ListOrderedInterface
*/
public function makeList(): ListOrderedInterface;
}
phpstan is complaining with the warning message "phpstan:: Method makeList return type with generic interface ListOrderedInterface does not specify its types". I don't know how to specify the types for the interface.
Thanks for helping with this.
You need provide a specialization for your ListOrderedInterface in the makeList phpdoc in the #return part.
interface ListOrderedFactoryInterface
{
/**
* This is an example with a concrete type, syntax is <type>
* #return ListOrderedInterface<string>
*/
public function makeList(): ListOrderedInterface;
}
If you need this to generic as well, you would need to add the #template on the factory also and return a generic type from makeList.
/**
* #template T
*/
interface ListOrderedFactoryInterface
{
/**
* #return ListOrderedInterface<T>
*/
public function makeList(): ListOrderedInterface;
}
And in the classes that implement FactoryInterface, add the #implements phpdoc.
/**
* Instead of string put the actual type it should return
* #implements ListOrderedFactoryInterface<string>
*/
class ConcreteFactory implements ListOrderedFactoryInterface
{
}
You can find more examples in the official docs: https://phpstan.org/blog/generics-by-examples
Our classes don't have explictic getPropertyName() and setPropertyName() methods. Instead we're using trait, which implements combination of magic __get(), __set() and __call() methods, so, we can have following as result:
class Device {
use ModelAttributes;
/**
* #var \string
*/
protected $title;
/**
* #var \string
*/
protected $subtitle;
}
$device = new Device();
$device->setTitle('PC');
$device->getTitle();
But the problem is, that now PhpStorm can't recognize and highlights these methods.
I know, that I can add #method string getTitle() into class phpDoc, but this will mean, taht I again need to add all get-ers and set-ers, but in form of phpDoc commetns, and I want to avoid this.
It would be really great, if I could do something like:
/**
* #var \string
* #get
* #set
*/
protected $title;
Does someone have experience with such situation?
i'm working with huge models on PHPStorm. I'm trying to minimize my annotations.
I want to turn this
Class Stack
{
/** #var string */
public $foo;
/** #var string */
public $bar;
/** #var int */
public $foobar;
}
into this:
Class Stack
{
/** #var string */ //for both vars
public $foo;
public $bar;
/** #var int */
public $foobar;
}
I found the ##+ syntax to define multiple vars but seems that is not working. Maybe there is a workaround?
Thank you very much.
By the way, can i tell phpstorm that
$this->MyModel is a MyModel type? Something like:
/** #var $this->MyModel MyModel **/
$this->MyModel
Because CodeIgniter puts all of your models inside a param of the controller.
I'm afraid that I've not seen any IDE that knows how to recognize the docblock template syntax of /*##+/.
As for $this->MyModel, you could try using the #property tag on that class where you are using $this->MyModel.
Although some IDEs can reportedly recognize that #var syntax to set a datatype on a local variable:
/** #var \MyModel $model */
$model = $this->MyModel;
I don't think it would work with a class property like that.
Why you cannot declare it with #property in the PHPDoc block of the class?
/**
* #property myModel MyModelClass
*/
class Test
{}
$t = new Test();
$t->myModel->[CTRL+Space will return available methods];
Anyway most better to declare property manually in the class. Just make it transparent.
It's really weird to use group comment for objects. I haven't had such practice.
But feel free to use similar code:
/**##+
* Test
*
* #var int
*/
protected $_aa = 1;
protected $_aa2 = 2;
/**##-*/
As more and more service oriented PHP is being done these days, I find myself with a lot of PHP files that have this long chunk of code just for initialization. In other languages like C++ or typescript you can do the following without all the duplication. A PHP example:
namespace Test\Controllers;
use Test\Services\AppleService;
use Test\Services\BananaService;
use Test\Services\PearService;
use Test\Services\LemonService;
use Test\Services\PeachService;
class TestController{
protected $appleService;
protected $bananaService;
protected $lemonService;
protected $pearService;
protected $peachService;
public function __construct(
AppleService $appleService,
BananaService $bananaService,
LemonService $lemonService,
PearService $pearService,
PeachService $peachService
){
$this->appleService = $appleService;
$this->bananaService = $bananaService;
$this->lemonService = $lemonService;
$this->pearService = $pearService;
$this->peachService = $peachService;
}
}
A Typescript Example:
module namespace Test.Controllers {
export class TestController{
constructor(
private appleService:Test.Services.AppleService,
private bananaService:Test.Services.BananaService,
private lemonService:Test.Services.LemonService,
private pearService:Test.Services.PearService,
private peachService:Test.Services.PeachService
){}
}
}
Are there better/shorter ways to do the same thing, and/or is any support to make this easier planned for upcoming PHP releases?
There is an alternative, property injection:
use DI\Annotation\Inject;
class TestController
{
/**
* #Inject
* #var AppleService
*/
private $appleService;
/**
* #Inject
* #var BananaService
*/
private $bananaService;
/**
* #Inject
* #var LemonService
*/
private $lemonService;
/**
* #Inject
* #var PearService
*/
private $pearService;
/**
* #Inject
* #var PeachService
*/
private $peachService;
}
Is that shorter, or simpler to write? I'll let you judge. But I love it, I don't end up with a bloated constructor. This is inspired from Java/Spring FYI.
Now this example works with PHP-DI (disclaimer: I work on that), but there may be other DI containers that offer the same functionality.
WARNING: property injection doesn't fit everywhere.
I find it appropriate for controllers (since controllers are not supposed to be reused). Read more here.
I don't think it would be appropriate to use it in services. So that's not the ultimate solution.
This syntactic sugar will finally arrive in PHP 8.0 (November 26, 2020).
By prefixing arguments in the contructor with public, protected or private, they will be copied to and defined as class properties with the same name.
In PHP 8.0 the example of OP can be written as:
namespace Test\Controllers;
use Test\Services\AppleService;
use Test\Services\BananaService;
use Test\Services\PearService;
use Test\Services\LemonService;
use Test\Services\PeachService;
class TestController{
public function __construct(
protected AppleService $appleService,
protected BananaService $bananaService,
protected LemonService $lemonService,
protected PearService $pearService,
protected PeachService $peachService
){
}
}
https://wiki.php.net/rfc/constructor_promotion
https://stitcher.io/blog/constructor-promotion-in-php-8
How to store a document inside another document, with Doctrine ODM?
I don't see an Array or Json type in the documentation.
I would like to be able to do something like this:
class Post {
/**
* #MongoDB\String
*/
protected $body;
/**
* #MongoDB\Array
*/
protected $comments = array();
}
I don't want to have a separate collection for comments. I want them saved inside each post.
/**
* #MongoDB\Document
*/
class Post
{
/**
* #MongoDB\Id
*/
private $id;
/**
* #MongoDB\String
*/
private $body;
/**
* #MongoDB\EmbedMany(targetDocument="Comment")
*/
private $comments;
public function __construct()
{
$this->comments = new ArrayCollection();
}
}
/**
* #MongoDB\EmbeddedDocument
*/
class Comment
{
/**
* #MongoDB\String
*/
private $body;
}
But note that comments are not good candidates for embedding — contrary to probably the most popular example of embeds in MongoDB. I started with comments as embeds too, but then run into some problems and decided to store them in a separate collection. I don't remember all the problems, but the main one was the inability to sort comments on the database side. The quick solution was to sort them on the client side, but when it comes to pagination, it just doesn't scale.
I think this is what you're looking for: http://www.doctrine-project.org/docs/mongodb_odm/1.0/en/reference/embedded-mapping.html
In my __construct() I need
new \Doctrine\Common\Collections\ArrayCollection();
where you just have
new ArrayCollection();