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?
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
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
I struggle organising my code, and I would like to share my "problem" with you by using a simple example: the calculation of the area of a rectangle. I put the code for example, but reading the first intro on each class section explains the situation easily.
Entity Rectangle:
The entity Rectangle contains two inportant properties $length and $width.
// src/Acme/CalculationBundle/Entity/Rectangle.php
/**
* #ORM\Entity(repositoryClass="Acme\CalculationBundle\Repository\RectangleRepository")
* #ORM\Table(name="rectangle")
*/
class Rectangle
{
/**
* #ORM\Id
* #ORM\Column(type="integer")
* #ORM\GeneratedValue(strategy="AUTO")
*/
protected $id;
/**
* #ORM\Column(type="integer")
*/
protected $length;
/**
* #ORM\Column(type="integer")
*/
protected $width;
FORM
Of course, the user can set length and width via a form
CONTROLLER
CreateRectangleAction: renders the form on GET request and work on the data on a POST request.
ViewRectangleAction: shows the rectangle.
RECTANGLE MANAGER
Now, to make sure the controller doesn't do too much stuff, I use a RectangleManager to realise common operation on Rectangle objects and use it as a service (injecting the appropriate elements).
// src/Acme/CalculationBundle/Entity/RectangleManager.php
use Doctrine\ORM\EntityManager;
use Doctrine\ORM\EntityRepository;
use Acme\EmployerBundle\Entity\Manager;
class rectangleManager
{
/**
* Doctrine entity manager
* #var EntityManager
*/
protected $em;
/**
* #var EntityRepository
*/
protected $repository;
/**
*
* #var string
*/
protected $class;
public function __construct(EntityManager $em, $class)
{
$this->em = $em;
$this->class = $class;
$this->repository = $em->getRepository($class);
}
/**
* #param $id
* #return Rectangle
*/
public function find($id)
{
$rectangle = $this->repository->find($id);
}
THE PROBLEM: WHAT IF?
What if I need to do some calculations on the rectangle? For example, if I need to add an area property so that I can render the area directly in the template without doing the calculation (length*width) in the template?
Not knowing how to do this properly, I went for this pretty bad solution:
I created a RectangleDisplay class (where I inject the rectangle entity) and display that entity instead of the Rectangle entity when calling ViewRectangleAction in the controller.
// src/Acme/CalculationBundle/Entity/
class RectangleDisplay
{
/**
* #var Rectangle $rectangle
*/
protected $rectangle;
/**
* #var Integer
*/
protected $area;
/**
* #param Rectangle $rectangle
*/
public function __construct(rectangle $rectangle){
$this->rectangle = $rectangle;
//calculate are
$area = this->calculateArea($this->rectangle->getLength(),$this->rectangle->getWidth());
$this->area = $area;
}
/**
* #return Integer $area
*/
public function calculateArea($length,$width)
{
return $length * $width;
}
Now the property area is directly accessible in the template. In the case of a rectangle, that is fine, but in the case of a more complex element (cone, ...), I might want to use a service that is crazy at doing calculation. I am not gonna inject the container in my RectangleDisplayEntity, am I?
This belongs in your entity.
class Rectangle
{
// ...
public function getArea()
{
return $this->length * $this->width;
}
}
The area of a rectangle is a property of a rectangle. It's not some crazy calculation that should be delegated to another service, and it's especially not something display-related (though you may think that based on it being displayed in your application).
Now, if you were calculating something a lot more complex, it's probably worth moving to a service / another class. (Services = verbs, Entities = nouns and their properties).
Have you tried RectangleDisplay extends rectangleManager ?
This is the normal way to extend a class with what you need, having available all possible properties of the parent and possible override of it's functions (here you can read more about it). None of the classes are final, so it shouldn't be a problem. Don't forget to take into account classes namespace when you will be working on it.
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.