I've been studying PHP OOP and I came across this interesting function declaration:
class ShopProductWriter {
public $products = array();
public function addProduct(ShopProduct $shopProduct) {
//code here..
}
}
notice how the first parameter of the addProduct function ShopProduct doesn't have a dollar sign? What does it mean?
it is not a parameter. it is the type definition of $shopProduct. this function takes only 1 parameter so $shopProduct can only be a ShopProduct class
It's typehinting.
A parameter-list has to be comma-separated. This stands in front of a parameter and declares the parameter's type.
Your example typehint is for an object of the class ShopProduct.
Meaning: If something else was passed, like an integer or an array, the method would throw an exception. (It reflects inheritance. Assume there was an instance of SpecificShopProduct, a class that would be extending ShopProduct, you could pass that as well.)
It is possible to typehint objects and an array, an Class or an Interface. It is not possible to typehint normal variables types like integers or a string, and you cannot typehint an array of objects.
public function foo(array someArray, LoggerInterface $logger)
{
}
Yet for some of the other types you could use phpDoc comments, yet those are for readability and IDE support, they would not enforce a type; meaning you would have to take to check for yourself that a correct type was passed.
/**
* #param ShopProductWriter[] arrayOfObjects
* #param int $someInt
* #param string $someString
*/
public function foo(array arrayOfObjects, $someInt, $someString)
{
}
Related
I wonder what is the good practices :
Let's say I have 2 entities, ManyToOne. Both are ApiResources, and both have an Output DTO. So Both have a transformer.
<?php
/**
* #ORM\Entity
* #ApiResource(
* output="Dto\Foo"
* )
*/
class Foo
{
private int $id;
/**
* #ORM\ManyToOne(targetEntity="Bar")
*/
private Bar $bar;
}
Problem is, when I transform the entity Foo into a DTO Foo, I want to hydrate it with a Bar DTO, not a Bar entity. But since I hydrate it with from an entity, I have a Bar entity. Later in the process, the Bar entity is replaced by a Bar DTO, ApiPlateform is working, but my mental problem is : the bar property type is modified over time (Moreover it can't be Typehinted). Seems dirty to me, isn't it ?
Illustration:
the Transofmer
<?php
use ApiPlatform\Core\DataTransformer\DataTransformerInterface;
class FooEntityToFooDToTransormer implements DataTransformerInterface
{
public function transform($object, string $to, array $context = [])
{
return new FooDto($object);
// maybe there is a better way to hydrate FooDto, by getting directly a BarDto here ?
}
}
The DTO :
<?php
namespace Dto;
class Foo
{
public int $id;
// problem is I cant typehint here
public $bar;
public function __construct(FooEntity $fooEntity)
{
$this->id = $fooEntity->getId();
$this->bar = $fooEntity->getBar(); // <-- return a Bar entity, transformed later by ApiPlatform into a Bar DTO.
}
}
It there a way or a good practice to proper hydrate a DTO from an entity, especially about relations ?
Edit :
I actually prefer not Typehint $bar as its normalization (so its transformation) should be handled by ApiPlateform. But then, circular references are not handeled (memory limit) and I don't really know why (probably confusion between object and DTO).
I don't think my FooTransformer should know how to transform Bar, because according to the context I could need one transformer or another, or an IRI... Test all of them with "supportTransformation" and so, for every relation ? And what about circular ?
It's a little mess, my solution for now is to choose to return FooDto (without transform barDto) or to return an IRI, according to the context (which I am absolutly not sure of what I'm doing with it due to the lack of documentation about $context).
Same for BarTransformer.
So every transformer need to choose to actually transform the object without handeling transformation of relations, or return the correspondant IRI. That is the less dirty I found.
I guess you have two possible solutions here, to extend your DTO's constructor signature by one more argument and adjust your transformer or to do the transformation right inside your DTO's constructor:
<?php
namespace Dto;
class FooDto
{
public BarDto $bar;
// first variant
public function __construct(FooEntity $fooEntity, BarDto $barDto)
{
$this->id = $fooEntity->getId();
$this->bar = $barDto;
}
// second
public function __construct(FooEntity $fooEntity)
{
$this->id = $fooEntity->getId();
$this->bar = new BarDto($fooEntity->getBar());
}
}
I have a constructor that asks for a type of class, but it doesn't define that as a type hint. You are able to pass anything you want to it, and it will accept it. Is there a way to pass a class type to the constructor, and in the add() method it only accepts that type?
Currently what I have, is the ability to pass anything to the constructor such as an int, string, bool, etc. Is there a way to make it so that the constructor only accepts class types?
class Main{
protected $items = [];
protected $type = '';
public function __construct($type){
$this->type = $type;
}
public function add($object){
if($object instanceof $this->type){
$this->items[] = $object;
}
}
}
class Test{}
class Awesome{}
$main1 = new Main(Test::class);
$main2 = new Main(Awesome::class);
// Successful:
$main1->add(new Test());
// Fail:
$main1->add(new Awesome());
// Successful:
$main2->add(new Awesome());
// Fail:
$main2->add(new Test());
If I were to do it in C# it would look something like this:
Main main1 = new Main<Test>();
Main main2 = new Main<Awesome>();
Basically it says that add() will only allow instances of Test. Is there a way to do some
Php doesn't support template like declarations like e.g. c++.
The best way you may be able to achive this is by passing a lambda which then in return gets used in order to validate the passed parameter in add.
<?php
class Test {
private $validator = null;
public function __construct($validator) {
$this->validator = $validator;
}
public function add($value) {
$func = $this->validator;
$validated = $func($value);
echo $validated ? 'OK' : 'NG';
}
}
$obj = new Test(function($value) {
return is_int($value);
});
$obj->add(11);
$obj->add('string');
Another possibility would be to pass the type e.g. "ClassName" in your constructor and use get_class() and gettype() for the validation.
In the future there may be smarter solutions since you'll be able to write anonymous classes but I haven't really thought about that but in the end they would work similarly to lambdas.
Basically it says that add() will only allow instances of Test.
It's possible to achieve this in PHP by simply adding the type before the argument name in the function definition (similar with C/C++/C# types):
class Main {
protected $items = [];
public function add(Test $object) {
$this->items[] = $object;
}
}
PHP 5 accepts classes, interfaces, array and callable as type hints. If Test is a class then Main::add() accepts objects of class Test and its children. If Test is an interface, then the method Main::add() accepts objects that implement Test or one of its children.
PHP 7 (coming soon to a server near you) introduces type hinting for scalar types too.
PHP does not support anything similar with C++ templates or C# generics. If you want to create a class that works with objects of type A and another class that has identical behaviour but works with objects of type B you have several options but none of them is as elegant as the templates/generics:
Create two classes having identical behaviour, one for objects of type A, another for objects of type B; use different type hints (A and B) in the arguments lists of the methods of the two classes to enforce the separation - not scalable;
Something similar to your code, use the allowed class name as a string property and check it on any operation; you can also validate the argument of the constructor using class_exists() - the code becomes cluttered with tests and less readable;
Use OOP polymorphism; extend both A and B from the same class T or, even better, make A and B implement the same interface I. A PHP interface can be empty, it doesn't need to declare anything; empty interfaces used just for type hinting are common practice in PHP.
Then write a single class Main and use I as type hint for all its methods that accept objects. It will accept objects of both types A and B but if you also declare functions in I (and implement them in A and B, of course) then use them in Main you can be sure nothing breaks (I becomes a contract between Main and the objects its accepts as arguments for its methods).
I would choose option #3 because it gets the most help from the interpreter; it verifies the type of the arguments on each function call that has type hints and triggers a recoverable fatal error (in PHP 5) or throws an exception (in PHP 7).
Also some IDEs and static code analysis tools can validate the calls without running the code and help you fix it.
Is there a way to make it so that the constructor only accepts class
types?
Nope!
It is not possible in PHP. Not like C#, at least.
You need either set a type hint or set any types.
However, there's a closer solution in order to accept only class when instancing a class: Using ReflectionClass!
class Main {
protected $items = [];
protected $type = null;
public function __construct($type) {
$reflector = new ReflectionClass($type);
$this->type = $reflector->getName(); # or: $this->type = $type;
}
public function add($object) {
if($object instanceof $this->type) {
$this->items[] = $object;
}
}
}
As ReflectionClass contructor argument only accpets a string containing the name of the class to reflect, you can take advantage that, so passing scalars strings will cause an exception.
$main = new Main(Test::class); # Okay!
$main = new Main('Test'); # Okay!
However
$main = new Main('bool');
// Results
# PHP Fatal error: Uncaught exception 'ReflectionException'
# with message 'Class bool does not exist' in ...
Change your constructor to this:
public function __construct(Type $type){
$this->type = $type;
}
This is based on the assumption that $type is an instance of Type.
Mockery has a method hasKey(), which checks if a given parameter has a certain key. I want to make sure that the passed array has multiple keys. I would also like to assert that the array has x amount of elements.
Is there a built-in way to allow for custom parameter expectations? I tried using a closure that returns true or false based on the given parameter, but that didn't work.
Thanks.
Edit:
Example
$obj = m::mock('MyClass');
$obj->shouldReceive('method')->once()->with(m::hasKey('mykeyname'));
What I'm trying to do is to have more insight into what is passed to the method using with(). I want to assert that an array passed to a method has both key a AND key b. It would be great if I could use a closure somehow to create my own assertion, such as counting the number of array elements.
You can user a custom matcher.
Out of the top of my head (not tested) this could look something like this:
class HasKeysMatcher extends \Mockery\Matcher\MatcherAbstract
{
protected $expectedNumberOfElements;
public function __construct($expectedKeys, $expectedNumberOfElements)
{
parent::__construct($expectedKeys);
$this->expectedNumberOfElements =$expectedNumberOfElements;
}
public function match(&$actual)
{
foreach($this->_expected as $expectedKey){
if (!array_key_exists($expectedKey, $actual)){
return false;
}
}
return $this->expectedNumberOfElements==count($actual);
}
/**
* Return a string representation of this Matcher
*
* #return string
*/
public function __toString()
{
return '<HasKeys>';
}
}
and then use it like this:
$obj = m::mock('MyClass');
$obj->shouldReceive('method')->once()->with(new HasKeysMatcher(array('key1','key2'),5));
Let's say I have a PHP class called Color, it's constructor accepts various params.
// hex color
$myColor = new Color('#FF008C');
// rgb channels
$myColor = new Color(253,15,82);
// array of rgb channels
$myColor = new Color(array(253,15,82));
// X11 color name
$myColor = new Color('lightGreen');
How should I use phpDoc to create API documentation for constructor and other methods like this?
How to use phpDoc with overloaded methods?
class Color {
/**
* Constructor
* what should be here?
*/
public function __construct() {
/* CODE */
}
}
Just my point of view, but you should not have multiple constructors in the first place - your constructor is going to be full of if/else-ladders, which really isn't a good idea, especially for something lightweight like a representation of a Color.
I strongly encourage you to try something like this instead:
class Color
{
protected function __construct($r, $g, $b)
{ ... }
public static function fromHex($hex) {
return new Color(...);
}
public static function fromRGB($r, $g, $b) { ... }
public static function fromArray(array $rgb) { ... }
...
}
Now, in consumer code, instead of somewhat mysterious and ambiguous constructor calls like these:
$a = new Color(0,0,0);
$b = new Color('#000000');
Instead you can have more legible and semantic consumer code, like this:
$a = Color::fromRGB(0,0,0);
$b = Color::fromHex('#000000');
This probably makes more sense to somebody reading the consumer code, it eliminates the logic required to make the ambiguous constructor work, and as a bonus (if you're using an IDE such as PhpStorm) you can have all your inspections pass. If you're running a documentation generator, this also ensures that all the options are documented individually, rather than lumped together in a verbal description.
Note that I declared the constructor protected - this is a personal preference, but if I'm going to have multiple static factory-methods, I prefer to see those consistently used in consumer code, rather than sometimes seeing Color::fromRGB(...) and other times new Color(...).
I think that is better to use #method annotation for class/interface, which declares overloading methods. This question is interesting for me too.
/**
* #method void setValue(int $value)
* #method void setValue(string $value)
* #method void setValue(string $value, int $startFrom)
*/
class Example
{
public function setValue($arg1, $arg2)
{
// ...
}
}
See http://phpdoc.org/docs/latest/references/phpdoc/tags/method.html
Because you allow variable length arguments there are two ways I would do this.
I would simply list the allowed arguments are parameters.
/**
* #param mixed $arg1 ... description
* #param mixed $arg2 ... description
* #param mixed $arg3 ... description
*/
public function __construct() {}
Or I would simply provide an explanation with some examples.
/**
* Explanation of different expected argument combinations.
*/
public function __construct() {}
Another alternative, since only one of the examples has more than one argument, would be to simply define the arguments in the method signature making the last 2 optional. Like this:
/**
* #param mixed $arg1 ...
* #param int $arg2 ...
* #param int $arg3 ...
*/
public function __construct($arg1, $arg2 = null, $arg3 = null) {}
I know of no elegant way to do this with phpDoc. The phpDoc comment/api formatting is based on a the Javadoc format. Javadoc doesn't have a feature set to support this because in java, if you want a method to have a variable number of arguments you re-declare the method prototype for each variation.
public double foo() {
}
public double foo(double my_param) {
}
So, my performance preference is to do something like
/**
* My General description
*
* Here explain what each argument combination can do
* #param mixed $arg1 can be array, string, hex as string, or int
* #param int $arg2 if arg1 is int, then this is etc, otherwise optional
* #param int $arg3 if ar1 is int, then this is etc, otherwise optional
*/
but this may not play nice with the various auto-documentation tools.
The according to Hoyle way to accomplish this can be found at the phpDoc site.
When I define an object of a class using new like this
$blah = new Whatever();
I get autocomplete for $blah. But how do I do it when I have $blah as a function parameter? Without autocomplete I am incomplete.
Edit: How do I do it if it's in an include and PDT or Netbeans can't figure it out? Is there any way to declare types for variables in PHP?
Method in first comment is called "type hinting", but you should use that wisely. Better solution is phpDoc.
/**
* Some description of function behaviour.
*
* #param Whatever $blah
*/
public function myFunction($blah)
{
$blah->
// Now $blah is Whatever object, autocompletion will work.
}
You can also use an inline phpDoc comment which does exactly the same thing.
public function myFunction($blah)
{
/* #var $blah Whatever */
$blah->
// Now $blah is Whatever object, autocompletion will work.
}
Try to pass parameter class definition into the function:
function myFunction(Whatever $blah) {
}