There is still an open issue about how to annotate array keys with PhpDoc: https://github.com/phpDocumentor/phpDocumentor2/issues/650
I tried the following notations:
/**
* #return array<string, SomeClass>
* #return SomeClass[string]
*/
public function someMethod(): array { ... }
but PhpStorm seem to be unable resolve this appropriate, so that when using e.g.
foreach the inner object is unknown:
foreach($obj->someMethod() as $some) {
$some->methodOfSomeClass(); // PhpStorm -> Method not found
}
I know i can use the pipe operator:
#return array<string, SomeClass>|SomeClass[]
I also know that i can type hint variables:
/** #var SomeClass $obj */
$obj
But is there a way to configure PhpStorm to know the array value type without using the pipe?
In PHP you either have numeric indexed arrays which have integer keys or associative arrays with string keys. Due to the dynamic typing you can just mix these up and therefore can have both types.
Also in your example you are not using your key but the value, these are hinted with ClassName[].
/**
* #return Class[]
*/
function getClasses(): array {
return [new Class()];
}
With this typhinting PHPStorm will provide valid tooltips in forEach loops.
Otherwise you can use the inline #type comment.
foreach ($objs as $obj) {
/* #type Class $obj */
$obj->someMethod(); //Is hinted
}
This question already has answers here:
Best way to document Array options in PHPDoc?
(9 answers)
Closed 1 year ago.
How can I specify an array index and sub-index type? Note: I will use it with PHPStorm.
Array example:
function name ($options) {
// $options['length'] => integer
// $options['more'] => array
// $options['more']['test1'] => boolean
// $options['more']['test2'] => boolean
}
Example (that not works):
/**
* #param array $options
* #var int $length
* #var array $more
* #var bool $test1
* #var bool $test2
*/
In general, PhpStorm only support simple syntax, just as Sam has stated, e.g.
/**
* #param string[] $options
*/
The code above described parameter which is array of strings.
Install Options completion plugin -- it supports new proposed syntax for hashes (describing array keys and its' types) in PHPDoc: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-describing-hashes
This plugin will add code completion for array keys.
<?php
class Element {
/**
* Initializes this class with the given options.
*
* #param array $options {
* #var bool $required Whether this element is required
* #var string $label The display name for this element
* }
*/
public function __construct(array $options = array())
{
// some code here
}
}
new Element(['label' => 'Bob', '|' ]);
// | Ctrl+Space will show supported attributes
NOTE: Main purpose of this plugin is to offer array keys completion -- I'm not sure how well it supports type resolutions for each of array elements (in case if they are different like in your example).
It looks like, according to the docs, that it's only possible to define an array as a set of one specific type (instead of setting a type for each index):
/**
* #param string[] $options
*/
The better solution would probably be to make $options a class, so length and test1 could be properties with default values and pre-defined types.
To document a variable that can take an array that receives a vector whose values are strings:
/*
* #var string[] An array of string objects.
*/
$foo = array('A', 'B', 'C');
To document a variable that can take an array that receives a vector whose values are integer:
/*
* #var int[] An array of string objects.
*/
$foo = array(1, 5, 0);
how should I document a variable whose values are mixed arrays?
I need document a array like this:
$foo = array(
array('value A', 1, $this),
array('value b', 2, NULL),
array('value X', 15, new Test)
);
I imagine it's something like this:
/*
* #var array[][string|int|object|null] Description.
*/
According to the current draft of PHPDoc (FIG PSR-5 applicant), the #var tag is deprecated. They suggest using an #type tag instead.
The type of variable is still an array; the contents of that array would be be briefly mentioned in the description.
/**
* #var array $foo An array of string elements.
*/
or
/**
* #type array $foo An array of string elements.
*/
If the variable might contain things other than strings, I might say An array of mixed elements., or if I knew specifically what they might be An array of bool|string|object elements.
If the variable itself might be of various types, I would give the list of types it might be.
/**
* #type bool|string|array $foo Mixed type, depending on result of baz().
*/
<?php
/*
Sample: $results = XMLParser::load('<xml ....');
$results = XMLParser::load(VSCHEMAS.'/Users.edit.xml');
*/
/**
* Abstract XMLParser class. A non-instantiable class that uses SimpleXML to parse XML, based on a path or body passed into the load method
*
* #abstract
*/
abstract class XMLParser {
/**
* convert function. Converts a SimpleXMLElement object to an associative array, usable for iteration
*
* #see http://www.if-not-true-then-false.com/2009/12/php-tip-convert-stdclass-object-to-multidimensional-array-and-convert-multidimensional-array-to-stdclass-object/
* #access private
* #static
* #param mixed $node node to convert to a non-object based value
* #return array associative array of the passed in node/object, ultimately representing the initially passed in object as an associative array
*/
private static function convert($node) {
if(is_object($node))
$node = get_object_vars($node);
if(is_array($node))
return array_map(array('self', 'convert'), $node);
return $node;
}
/**
* load function. Loads a source (either a local path or source body) document, and returns as associative array of it's results
*
* #access public
* #static
* #param string $source xml body, or path to local xml file
* #return array SimpleXML results, parsed as an associative array
*/
public static function load($source) {
$path = false;
if(preg_match('/^\//', $source) > 0)
$path = true;
$simpleXMLElement = new SimpleXMLElement($source, LIBXML_NOENT, $path);
return self::convert($simpleXMLElement);
}
}
?>
I'm using the above code to parse xml files and convert them to a more traversable array. I'm running into an issue though. When I have some sample xml like:
<fields>
<rule whatever="lolcats" />
</fields>
vs.
<fields>
<rule whatever="lolcats" />
<rule whatever="lolcats" />
</fields>
the resulting array isn't consistent. Namely, in the first case, it's of the format:
Array
(
[field] => Array
(
[#attributes]...
Whereas in the latter, it's of the format:
Array
(
[field] => Array
(
[0]...
What I'm saying here, is that it's indexing the sub-xml elements numerically, which is what I want, but only when there is more than 1. Any thoughts on what to change to always have them indexed numerically, rather than a direct reference to the one-and-only element's #attributes array?
Any help would be much appreciated :D
Well you cant have an element or a attrib that is an int so simply testing for the array key 0 and then forging the array you expect should work.
boom! i played around with the bit of code below for a couple hours, and finally knocked it out of the editor! the trick was to loop through the vars with the value's being references, and if it was indeed an object, but the key wasn't '#attributes' (as mentioned above) then wrap it in an array :D
/**
* convert function. Converts a SimpleXMLElement object to an associative array, usable for iteration
*
* #see http://www.if-not-true-then-false.com/2009/12/php-tip-convert-stdclass-object-to-multidimensional-array-and-convert-multidimensional-array-to-stdclass-object/
* #access private
* #static
* #param mixed $node node to convert to a non-object based value
* #return array associative array of the passed in node/object, ultimately representing the initially passed in object as an associative array
*/
private static function convert($node) {
if(is_object($node)) {
$vars = get_object_vars($node);
foreach($vars as $key => &$var) {
if($key!=='#attributes' && is_object($var))
$var = array($var);
}
$node = $vars;
}
if(is_array($node))
return array_map(array('self', 'convert'), $node);
return $node;
}
I'm looking at the PHP Manual, and I'm not seeing a section on data structures that most languages have, such as lists and sets. Am I just blind or does PHP not have anything like this built in?
The only native data structure in PHP is array. Fortunately, arrays are quite flexible and can be used as hash tables as well.
http://www.php.net/array
However, there is SPL which is sort of a clone of C++ STL.
http://www.php.net/manual/en/book.spl.php
PHP offers data structures through the Standard PHP Library (SPL) basic extension, which is available and compiled by default in PHP 5.0.0.
The data structures offered are available with PHP 5 >= 5.3.0, and includes:
Doubly Linked Lists
A Doubly Linked List (DLL) is a list of nodes linked in both directions to each others. Iterator’s operations, access to both ends, addition or removal of nodes have a cost of O(1) when the underlying structure is a DLL. It hence provides a decent implementation for stacks and queues.
SplDoublyLinkedList class
SplStack class
SplQueue class
Heaps
Heaps are tree-like structures that follow the heap-property: each node is greater than or equal to its children, when compared using the implemented compare method which is global to the heap.
SplHeap class
SplMaxHeap class
SplMinHeap class
SplPriorityQueue class
Arrays
Arrays are structures that store the data in a continuous way, accessible via indexes. Don’t confuse them with PHP arrays: PHP arrays are in fact implemented as ordered hashtables.
SplFixedArray class
Map
A map is a datastructure holding key-value pairs. PHP arrays can be seen as maps from integers/strings to values. SPL provides a map from objects to data. This map can also be used as an object set.
SplObjectStorage class
Source: http://php.net/manual/en/spl.datastructures.php
PHP 7 introduced an extension called ds providing specialized data structures as an alternative to the array.
The ds,
uses the Ds\ namespace.
has 3 interfaces namely,Collection, Sequence and Hashable
has 8 classes namely, Vector, Deque,Queue, PriorityQueue, Map, Set, Stack, and Pair
For more information checkout the Manual and also This blog post has some awesome information including benchmarks.
The associative array can be used for most basic data structures hashtable, queue, stack. But if you want something like a tree or heap I don't think they exist by default but I'm sure there are free libraries anywhere.
To have an array emulate a stack use array_push() to add and array_pop() to take off
To have an array emulate a queue use array_push() to enqueue and array_shift() to dequeue
An associative array is a hash by default. In PHP they are allowed to have strings as indexes so this works as expected:
$array['key'] = 'value';
Finally, you can kind of emulate a binary tree with an array with the potential to have wasted space. Its useful if you know you're going to have a small tree. Using a linear array, you say for any index (i) you put its left child at index (2i+1) and right child at index (2i+2).
All of these methods are covered nicely in this article on how to make JavaScript arrays emulate higher level data structures.
PHP has arrays, which are actually associative arrays and can also be used as sets. Like many interpreted languages, PHP offers all this under one hood instead of providing different explicit data types.
E.g.
$lst = array(1, 2, 3);
$hsh = array(1 => "This", 2 => "is a", 3 => "test");
Also, take a look in the manual.
PHP's array doubles as both a list and a dictionary.
$myArray = array("Apples", "Oranges", "Pears");
$myScalar = $myArray[0] // == "Apples"
Or to use it as an associative array:
$myArray = array("a"=>"Apples", "b"=>"Oranges", "c"=>"Pears");
$myScalar = $myArray["a"] // == "Apples"
I think you might want to be a bit more specific, when you say data structures my mind goes in a few directions...
Arrays - They are certainly well documented and available in. (http://us.php.net/manual/en/book.array.php)
SQL Data - Depends on the database you are using, but most are available. (http://us.php.net/manual/en/book.mysql.php)
OOP - Depending on the version objects can be designed and implemented. (http://us.php.net/manual/en/language.oop.php) I had to search for OOP to find this on the php site.
Of course PHP has data structures. The array in php is incredibly flexible. Some examples:
$foo = array(
'bar' => array(1,'two',3),
'baz' => explode(" ", "Some nice words")
);
Then you have an absolute plethora of array functions available to map/filter/walk/etc the structures, or convert, flip, reverse, etc.
You can always create your own if you don't feel PHP includes a specific type of data structure. For example, here is a simple Set data structure backed by an Array.
class ArraySet
{
/** Elements in this set */
private $elements;
/** the number of elements in this set */
private $size = 0;
/**
* Constructs this set.
*/
public function ArraySet() {
$this->elements = array();
}
/**
* Adds the specified element to this set if
* it is not already present.
*
* #param any $element
*
* #returns true if the specified element was
* added to this set.
*/
public function add($element) {
if (! in_array($element, $this->elements)) {
$this->elements[] = $element;
$this->size++;
return true;
}
return false;
}
/**
* Adds all of the elements in the specified
* collection to this set if they're not already present.
*
* #param array $collection
*
* #returns true if any of the elements in the
* specified collection where added to this set.
*/
public function addAll($collection) {
$changed = false;
foreach ($collection as $element) {
if ($this->add($element)) {
$changed = true;
}
}
return $changed;
}
/**
* Removes all the elements from this set.
*/
public function clear() {
$this->elements = array();
$this->size = 0;
}
/**
* Checks if this set contains the specified element.
*
* #param any $element
*
* #returns true if this set contains the specified
* element.
*/
public function contains($element) {
return in_array($element, $this->elements);
}
/**
* Checks if this set contains all the specified
* element.
*
* #param array $collection
*
* #returns true if this set contains all the specified
* element.
*/
public function containsAll($collection) {
foreach ($collection as $element) {
if (! in_array($element, $this->elements)) {
return false;
}
}
return true;
}
/**
* Checks if this set contains elements.
*
* #returns true if this set contains no elements.
*/
public function isEmpty() {
return count($this->elements) <= 0;
}
/**
* Get's an iterator over the elements in this set.
*
* #returns an iterator over the elements in this set.
*/
public function iterator() {
return new SimpleIterator($this->elements);
}
/**
* Removes the specified element from this set.
*
* #param any $element
*
* #returns true if the specified element is removed.
*/
public function remove($element) {
if (! in_array($element, $this->elements)) return false;
foreach ($this->elements as $k => $v) {
if ($element == $v) {
unset($this->elements[$k]);
$this->size--;
return true;
}
}
}
/**
* Removes all the specified elements from this set.
*
* #param array $collection
*
* #returns true if all the specified elemensts
* are removed from this set.
*/
public function removeAll($collection) {
$changed = false;
foreach ($collection as $element) {
if ($this->remove($element)) {
$changed = true;
}
}
return $changed;
}
/**
* Retains the elements in this set that are
* in the specified collection. If the specified
* collection is also a set, this method effectively
* modifies this set into the intersection of
* this set and the specified collection.
*
* #param array $collection
*
* #returns true if this set changed as a result
* of the specified collection.
*/
public function retainAll($collection) {
$changed = false;
foreach ($this->elements as $k => $v) {
if (! in_array($v, $collection)) {
unset($this->elements[$k]);
$this->size--;
$changed = true;
}
}
return $changed;
}
/**
* Returns the number of elements in this set.
*
* #returns the number of elements in this set.
*/
public function size() {
return $this->size;
}
/**
* Returns an array that contains all the
* elements in this set.
*
* #returns an array that contains all the
* elements in this set.
*/
public function toArray() {
$elements = $this->elements;
return $elements;
}
}
PHP can also have an array of arrays which is called a "multidimensional array" or "matrix". You can have 2-dimensional arrays, 3-dimensional arrays, etc.