I often give objects static methods and properties that do not require the object to be initialized. For example:
class SomeObject {
public function __construct($object_id) {
$this->loadProperties($object_id);
}
public static function getSomeStaticString() {
return "some static string";
}
}
Now we subclass these objects and have some sort of controller that returns an object class string under certain circumstances where the object should not yet be initialized. For example:
class SomeObjectController {
public function getSomeObjectWithTheseProperties(array $properties) {
if($properties[0] === "somevalue") {
if($properties[1] === "someothervalue") {
return SomeSubclassObject::class;
}
return SomeObject::class;
}
return NULL;
}
}
At times I might want to call the static function SomeObject::getSomeStaticString() without actually initializing the object (because that would involve an unneeded database fetch). For instance:
$controller = new SomeObjectController;
$properties = array("somevalue", "someothervalue");
$object_class = $controller->getSomeObjectWithTheseProperties($properties);
echo $object_class::getSomeStaticString();
Question: can I somehow tell PhpStorm, preferably through phpDoc, that $object_class is a class string of a subclass of SomeObject?
If I tell my IDE it's a string, it will notify me getSomeStaticString() is an invalid method. On the other hand, if I tell my IDE it's an instance of SomeObject, it thinks I can access regular non-static methods and properties, which I can't.
PHPStan uses the class-string PHPDoc type for this. It has been supported by PHPStorm since 2020.3, but it seems to work properly (with all autocompletion available) as of 2021.2, when they added support for Generics.
In your case the return type annotation would be #return class-string<SomeObject>.
/** #var SomeObject $object_class */
$object_class = $controller->getSomeObjectWithTheseProperties($properties);
Sorry, no other way as to tell that it's an instance of SomeObject.
... if I tell my IDE it's an instance of SomeObject, it thinks I can access regular non-static methods and properties, which I can't.
So? Just do not access non-static methods and properties.
UPDATE 2021-10-26: Since v2020.3 PhpStorm has Psalm Support and PHPStan Support plugins bundled. They support most of the syntax/types supported by those tools (you can check PhpStorm Issue Tracker here for all the tickets for those plugins (resolved and still pending)).
With those tools you can use class-string pseudo type:
https://psalm.dev/docs/annotating_code/type_syntax/scalar_types/#class-string-interface-string
https://phpstan.org/writing-php-code/phpdoc-types#class-string
If you want perfect type hinting you may create an Interface which only lists the static methods (and properties) of your class, and use that Interface as the type hint for your classname string returned from SomeObjectController::getSomeObjectWithTheseProperties().
It adds overhead to the maintenance to ensure the Interface and the classes are kept in sync, but if you need those type hints to work properly, this is the way.
You can also use this workaround:
/**
* #return string|SomeObject
*/
public function getSomeObjectClass()
{
return SomeObject::class;
}
Related
Is there a way to document that a certain class has magic methods for every method defined in another class?
I am using PhpStorm, so I would be happy with any solution that will get autocomplete to work properly for that.
class A
{
// a bunch of functions go here...
}
/**
* Class B
* What should go here to make it work???
*/
class B
{
private $aInstance;
public function __construct() {
$this->aInstance = new A();
}
public function __call($name, $arguments) {
// TODO: Implement __call() method.
if(method_exists($this->aInstance, $name)) {
return $this->aInstance->{$name}(...$arguments);
}
throw new BadMethodCallException();
}
// a bunch more functions go here...
}
The proper solution is to use supported #method PHPDoc tags. This way it will also work in other editors/IDEs that support PHPDoc and understand such standard tag.
This approach requires every method to be listed separately. More on this in another StackOverflow question/answer: https://stackoverflow.com/a/15634488/783119.
In current PhpStorm versions you may use not-in-PHPDoc-specs (and therefore possibly PhpStorm-specific) #mixin tag.
Adding #mixing className in PHPDoc comment for your target class should do the job for you.
/**
* Class B
*
* #mixin A
*/
class B
{
Basically, #mixin tag does what actual PHP's traits do.
Please note that there is no guarantee that support for such tag will not be removed at some point in the future, although it's pretty unlikely.
I am a junior PHP programmer. I still have a lot to learn. That's why I ask this question. In a class you have a public function which you can call it from outside that class. Sometimes you have a private function which you can call several times in that class where the private function resides, for reusable purpose. I like to set the private function to static and I call that function with:
self::privateFunctionName();
By using self it reminds me that this private function resides in that class. if I use $this->privateFunctionName() for non-static function, it could be in the superclass/base class or in that subclass itself. That is why I like to use static private function. In a professional point of view, is it a good idea to use static private function instead of non-static? Is there any disadvantage that a professional programmer like you prefers to avoid the static function?
Only using self::... must not mean the method is static. parent:: and self:: work as well for non-static methods. You can find this in the PHP manual - Scope Resolution Operator (::) and I add some exemplary code excerpt at the end of the answer.
You perhaps might want to read through all answers of this earlier question:
When to use self over $this?
In total you will get there more details then my short description in this answer.
You might have been confused by the scope-resolution-operator :: which is used by those. I had a similar understanding problem grasping that.
However, do not just choose to use static methods for such a limited reason. Those static class methods should only be used in very limited and narrowed situations. As a rule of thumb:
"Do not use static class methods."
If you like to start with object oriented programming, just use normal object methods.
Here is an excerpt from existing code that shows that self:: as well as parent:: are used with standard (non-static) methods:
<?php
...
/**
* Class XMLElementIterator
*
* Iterate over XMLReader element nodes
*/
class XMLElementIterator extends XMLReaderIterator
{
private $index;
private $name;
private $didRewind;
/**
* #param XMLReader $reader
* #param null|string $name element name, leave empty or use '*' for all elements
*/
public function __construct(XMLReader $reader, $name = null)
{
parent::__construct($reader);
$this->setName($name);
}
/**
* #return void
*/
public function rewind()
{
parent::rewind();
$this->ensureCurrentElementState();
$this->didRewind = true;
$this->index = 0;
}
/**
* #return XMLReaderNode|null
*/
public function current()
{
$this->didRewind || self::rewind();
$this->ensureCurrentElementState();
return self::valid() ? new XMLReaderNode($this->reader) : null;
}
...
self:: does not in fact mean that the method is part of the same class, it may as well have been inherited from a parent class!
You should not use the semantics of static method calls to differentiate "internal" and "external" methods. There's no real point to it anyway, and you're just abusing language features for something they weren't meant for. Maybe let that be a primary lesson: don't try to invent clever new ways of using language features. Just don't.
You should view methods as small, self contained black boxes. You don't need to know and don't want to know what they do. All you know is that when you call method foo with parameter $bar, x will happen or it will return y. You don't care how this happens, just that it does because that's what the method is supposed to do.
As such, static and non-static methods convey a different use with different limitations. static methods are supposed to be called when you don't have an object, for example as alternative constructor methods (e.g. DateTime::createFromFormat).
Further, restricting a method to being static means it has no access to object instance data, which may limit you in the future. As your project evolves, you may find that your method now needs to take into account some additional data from the object to do its job. If you declared it as non-static from the beginning, all it takes is a little modification to the method itself; to the outside world it still does its job the same way (input → output). However, if you declared it as static and suddenly find yourself needing to make it non-static, you have to change a lot more code than just that one method.
Bottom line: if your method is not supposed to be exposed publicly because it's nobody's business to call it except for your own class, make it private. If the method needs to be static because it must work without object context, make it static. If it fulfils both requirements, make it private static. Otherwise, don't.
Well basically a "private static" function is a construct which is totally nonsense because it cannot be called from the outside.
There is no real difference between $this-> and using self:: expect the fact that it can be called from the outside without a object and its the same amount of work for the CPU to call the function, no matter in what namespace/class this function is located.
However the fact that a private function can only be called within the same class you always have an object and the "static" modifier is somewhat superflous here because it makes no difference.
In this cases I always like to say: do what you like its just a matter of your personal style but dont switch arround, keep it that way to develop and use the standard you feel comfortable with.
In some cases there is just "another" way and a "professional" way does not exist at all.
The trend often makes the one or the other method to become popular over time.
Consider the following PHP interfaces:
interface Item {
// some methods here
}
interface SuperItem extends Item {
// some extra methods here, not defined in Item
}
interface Collection {
public function add(Item $item);
// more methods here
}
interface SuperCollection extends Collection {
public function add(SuperItem $item);
// more methods here that "override" the Collection methods like "add()" does
}
I'm using PHPStorm, and when I do this, I get an error in the IDE that basically states the definition for add() in SuperCollection is not compatible with the definition in the interface it extends, Collection.
In one way, I can see this being a problem, as the signature of the method does not match the one it "overrides" exactly. However, I do feel that this would be compatible, as SuperItem extends Item, so I would view add(SuperItem) the same as add(Item).
I'm curious as to if this is supported by PHP (version 5.4 or above), and maybe the IDE has a bug that doesn't properly catch this.
No, I'm pretty sure PHP doesn't support this, in any version, and it would rather defeat the point of an interface.
The point of an interface is that it gives you a fixed contract with other code that references the same interface.
For example, consider a function like this:
function doSomething(Collection $loopMe) { ..... }
This function expects to receive an object that implements the Collection interface.
Within the function, the programmer would be able to write calls to methods that are defined in Collection, knowing that the object would implement those methods.
If you have an overridden interface like this, then you have a problem with this, because a SuperCollection object could be passed into the function. It would work because it also is a Collection object due to the inheritance. But then the code in the function could no longer be sure that it knows what the definition of the add() method is.
An interface is, by definition, a fixed contract. It is immutable.
As an alternative, you could consider using abstract classes instead of interfaces. This would allow you to override in non-Strict mode, although you'll still get errors if you use Strict Mode, for the same reasons.
As a workaround I'm using PHPDoc blocks in interfaces.
interface Collection {
/**
* #param Item $item
*/
public function add($item);
// more methods here
}
interface SuperCollection extends Collection {
/**
* #param SuperItem $item
*/
public function add($item);
// more methods here that "override" the Collection methods like "add()" does
}
This way, in case you are properly using interfaces, IDE should help you catch some errors. You can use similar technique to override return value types as well.
PHP 7.4, released November 2019 has improved type variance.
The code from the question remains invalid:
interface Item {
// some methods here
}
interface SuperItem extends Item {
// some extra methods here, not defined in Item
}
interface Collection {
public function add(Item $item);
// more methods here
}
interface SuperCollection extends Collection {
public function add(SuperItem $item); // This will still be a compile error
// more methods here that "override" the Collection methods like "add()" does
}
Because the Collection interface guarantees that anything that implements it can accept any object of type Item as the parameter of add.
However, the following code is valid in PHP 7.4:
interface Item {
// some methods here
}
interface SuperItem extends Item {
// some extra methods here, not defined in Item
}
interface Collection {
public function add(SuperItem $item);
// more methods here
}
interface SuperCollection extends Collection {
public function add(Item $item); // no problem
// more methods here that "override" the Collection methods like "add()" does
}
In this case Collection guarantees that that it can accept any SuperItem. Since all SuperItems are Items, SuperCollection also makes this guarantee, while also guaranteeing that it can accept any other type of Item. This is known as a Contravariant method parameter type.
There is a limited form of type variance in earlier versions of PHP. Assuming other interfaces are as in the question, the SuperCollection may be defined as:
interface SuperCollection extends Collection {
public function add($item); // no problem
// more methods here that "override" the Collection methods like "add()" does
}
This can be interpreted as meaning any value whatsoever may be passed to the add method. That of course includes all Items, so this is still type safe, or it can be interpreted as meaning that an unspecified class of values, generally documented as mixed may be passed and the programmer needs to use other knowledge of exactly what can work with the function.
You cannot change the methods arguments.
http://php.net/manual/en/language.oop5.interfaces.php
Extending interface is not allowed to change method definitions. If your SuperItem is extending Item, it should be passing through classes implementing Collection interface without problems.
But based on what you really want to do, you can try:
Create interface with slightly different methods for SuperItem and implement that:
interface SuperCollection extends Collection {
public function addSuper(SuperItem $superItem);
}
Use decorator pattern to create almost same interface without extending:
interface Collection {
public function add(Item $item);
// more methods here
}
interface SuperCollection {
public function add(SuperItem $item);
// more methods here that "override" the Collection methods like "add()" does
}
Then decorator (abstract) class, which will use this interface:
class BasicCollection implements Collection {
public function add(Item $item)
{
}
}
class DecoratingBasicCollection implements SuperCollection {
protected $collection;
public function __construct(Collection $collection)
{
$this->collection = $collection;
}
public function add(SuperItem $item)
{
$this->collection->add($item);
}
}
The problem is not in the IDE. In PHP you cannot override a method. And the compatibility is only in the opposite direction - you can safely expect an instance of the parent class and receive a subclass. But when you expect a subclass, you cannot be safe if you receive the parent class - the subclass may define methods that do not exist in the parent. But still, you can't override the method
When I have a method that I may need to overload (which PHP does not support), I make sure that one of the method arguments (usually the last) is an array. In this way I can pass whatever I need to. I can then test within the function for various array elements to tell me what routine in the method I need to perform, usually in a select/case.
Although this question is about DocBlocks in general, my use-case is about PHP.
Consider the following PHP code:
<?php
class ParentClass {
/**
* Says 'hi' to the world.
* #return ParentClass Returns itself for chaining.
*/
public function say_hi(){
echo 'hi';
return $this;
}
}
class ChildClass extends ParentClass {
/**
* Says 'bye' to the world.
* #return ChildClass Returns itself for chaining.
*/
public function say_bye(){
echo 'bye';
return $this;
}
}
$c = new ChildClass;
$c->say_hi()->say_b| <- type hinting won't suggest "say_bye" here
?>
This is just a trivial class with some chaining. The extended class looses type hinting because the parent class' docblock is making use of a specific class name which does not have the methods/properties of the child class.
Assuming we do want type-hinting capability, (if not, please leave this question - I don't want useless arguments here), how should I fix this?
I came up with the following possibilities:
Change the PHPDoc standard to allow a special keyword
Add a superfluous say_hi() method which calls the parent just to redeclare docblock
Do not specify the return type at all, let the IDE decide what return $this; means (does this even work?)
You can solve this like this :
class ParentClass {
/**
* Says 'hi' to the world.
* #return static
*/
public function say_hi(){
echo 'hi';
return $this;
}
}
The "#return static" statement allows exactly what you want, PhpStorm works just fine with it.
What you describe is commonly called a "fluent interface", where all of an object's methods do their work and return the object itself.
I have not personally seen any PHPDoc guideline finalized on how to do exactly that. As such, I'm not aware that any IDE has put forth a means for its autocomplete functionality to handle the use case.
A likely path that PHPDoc will take on this is to utilize "#return $this" to be the convention to indicate fluent methods, as it matches the code syntax itself and is therefore very clear. I doubt that any IDEs will build that capability in until the standard itself incorporates this use case.
In the short term, I think that your superfluous "ChildClass::say_hi(){parent::say_hit();}" might get your IDE autocompletion to work. Again, might, because having the autocomplete also recognize method chaining itself (e.g. $foo->bar()->baz()->roll()->tide();) might not exist.
As the title says, I'm wanting to create an instance of a class from within a static method of the same class. I've figured out so far is that I can by doing something like this:
class Foo{
public $val;
public static function bar($val){
$inst = new Foo;
$inst->val = $val;
return $inst;
}
}
Which therefore lets me do this.
$obj = Foo::bar("some variable");
Which is great.
So now the questions. Is there an easier way of doing this that I'm not aware of, or any shortcuts to achieving the same result? Are there any advantages or disadvantages of creating an instance in this fashion?
Thanks.
They way you're doing it is fine. There are a few other things that can make your life easier that you can do as well.
Don't hardcode the class name. If you're on 5.3+, use the keyword static. That way, if you extend the class, the new function can instantiate that one as well:
public static function bar($var) {
$obj = new static();
$obj->var = $var;
return $obj;
}
Then you can use it in any extending class without needing to override anything.
Figure out if $var should be passed in through a constructor rather than set after construction. If the object depends upon it, you should require it.
public function __construct($var) {
$this->var = $var;
}
That way you can't instantiate the object without setting the variable.
Enforce the instantiation of the class through the static method. If you're doing anything in there that you need to do, then make the constructor either protected or private. That way, someone can't bypass the static method.
protected function __construct() {}
private function __construct() {}
Edit: Based on your comment above, it sounds to me like you're trying to implement the Singleton Design Pattern. There's tons of information out there about why it's not a great idea and the bad things it may do. It has uses as well.
But there are a few other patterns that may be of use to you depending on what you're doing exactly.
You can use the Factory Method if you're trying to create different objects using the same steps.
If all of the objects start off the same and then are customized, you could use the Prototype Pattern.
You could use an Object Pool if it's particularly expensive to create your object.
But one thing to consider, is that in PHP objects are pretty light weight. Don't try to avoid creating a new object just for that overhead. Avoid doing heavy things like database queries or filesystem accesses multiple times. But don't worry about calling new Foo() unless foo's constructor is particularly heavy...
This looks like a simple factory method pattern.
You have a nice advantage: suppose that in the future you want to start using a different implementation (but that does the same thing). Using a factory you can change all the objects that are created in many places of a complex system simply by changing the creator method. Note that this would work easier if you used an external class (as is in the first link below).
Keeping it as you have now, you can also subclass this class and override the method to create a more complex object. I don't think this is what you want to achieve in here.
Anyway, this is good to enable Test Driven Development, abstraction and lots of other good things.
links:
Php patterns
Factory method pattern on wikipedia
If you're just creating an object, this isn't very usefull. You could just call a constructor. But if you're doing something more complicated (like you're starting with some sort of singleton pattern but haven't included all the details in this example), then:
This sounds about right. If you want to prevent objects created in the default way like this:
$obj = new Foo("Some Variable");
You can add a private constructor:
class Foo{
public $val;
private __construct(){}
public static function bar($val){
$inst = new Foo;
$inst->val = $val;
return $inst;
}
}
Now you enforce people to use your static class. The need to set the val in the function might be gone, so you could even add the value-parameter to your private constructor but do the other things (that you presumably want to do, like check for some sort of singleton pattern) in your 'bar' function
Super late but found this useful.
A good example of this in the wild is this static method from Audi's UI library returning an Array of instantiated TextField classes from within TextField's static method upgradeElements.
/**
* Class constructor for Textfield AUI component.
* Implements AUI component design pattern defined at:
* https://github.com/...
*
* #param {HTMLElement} element The element that will be upgraded.
*/
export default class Textfield extends Component {
/**
* Upgrades all Textfield AUI components.
* #returns {Array} Returns an array of all newly upgraded components.
*/
static upgradeElements() {
let components = [];
Array.from(document.querySelectorAll(SELECTOR_COMPONENT)).forEach(element => {
if (!Component.isElementUpgraded(element)) {
components.push(new Textfield(element));
}
});
return components;
};
constructor(element) {
super(element);
}
...
See the rest in the repo
https://github.com/audi/audi-ui/blob/master/src/textfield/textfield.js#L25