- Added array dereferencing support [DOC]

# http://wiki.php.net/rfc/functionarraydereferencing

NEWS

@@ -22,6 +22,7 @@
 - Added an optimization which saves memory and emalloc/efree calls for empty
   HashTables (Stas, Dmitry)
 
+- Added array dereferencing support. (Felipe)
 - Added DTrace support. (David Soria Parra)
 - Added Tokyo Cabinet abstract DB support to ext/dba. (Michael Maclean)
 - Added Jenkins's one-at-a-time hash support to ext/hash. (Martin Jansen)

UPGRADING

@@ -185,7 +185,10 @@ UPGRADE NOTES - PHP X.Y
 11. Syntax additions
 ====================
 
-- 
+- Array dereferencing.
+  e.g.
+    foo()[0]
+    $foo->bar()[0]
 
 ===================
 12. Windows support

Zend/tests/dereference_001.phpt

@@ -0,0 +1,51 @@
+--TEST--
+Testing array dereference
+--FILE--
+<?php
+error_reporting(E_ALL);
+
+function a() {
+	return array(1,array(5));
+}
+var_dump(a()[1][0]); // int(5)
+
+function b() {
+	return array();
+}
+var_dump(b()[0]); // Notice: Undefined offset: 0 
+
+class foo {
+	public $y = 1; 
+
+	public function test() {
+		return array(array(array('foobar')));
+	}
+}
+
+function c() {
+	return array(new foo);
+}
+var_dump(c()[0]->y); // int(1)
+
+function d() {
+	$obj = new foo;
+	return $obj->test();
+}
+var_dump(d()[0][0][0][3]); // string(1) "b"
+
+function e() {
+	$y = 'bar';
+	$x = array('a' => 'foo', 'b' => $y);
+	return $x;
+}
+var_dump(e()['b']); // string(3) "bar"
+
+?>
+--EXPECTF--
+int(5)
+
+Notice: Undefined offset: 0 in %s on line %d
+NULL
+int(1)
+string(1) "b"
+string(3) "bar"

Zend/tests/dereference_002.phpt

@@ -0,0 +1,79 @@
+--TEST--
+Testing array dereference on method calls
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+class  foo {
+	public function bar() {
+		$x = array();
+		$x[] = 3;
+		$x[] = array(1, 5);
+		$x[] = new foo;
+		return $x;
+	}
+}
+
+$foo = new foo;
+
+var_dump($x = $foo->bar()[1]);
+var_dump($foo->bar()[1][1]);
+var_dump($x[0]);
+var_dump($x = $foo->bar()[2]);
+var_dump($x->bar());
+var_dump($x->bar()[0]);
+
+$x = array();
+$x[] = new foo;
+var_dump($x[0]->bar()[2]);
+var_dump($foo->bar()[2]->bar()[1]);
+var_dump($foo->bar()[2]->bar()[2]->bar()[1][0]);
+var_dump($foo->bar()[2]->bar()[2]->bar()[1][0][1]);
+var_dump($foo->bar()[2]->bar()[2]->bar()[4]);
+var_dump($foo->bar()[3]->bar());
+
+?>
+--EXPECTF--
+array(2) {
+  [0]=>
+  int(1)
+  [1]=>
+  int(5)
+}
+int(5)
+int(1)
+object(foo)#2 (0) {
+}
+array(3) {
+  [0]=>
+  int(3)
+  [1]=>
+  array(2) {
+    [0]=>
+    int(1)
+    [1]=>
+    int(5)
+  }
+  [2]=>
+  object(foo)#3 (0) {
+  }
+}
+int(3)
+object(foo)#3 (0) {
+}
+array(2) {
+  [0]=>
+  int(1)
+  [1]=>
+  int(5)
+}
+int(1)
+NULL
+
+Notice: Undefined offset: 4 in %s on line %d
+NULL
+
+Notice: Undefined offset: 3 in %s on line %d
+
+Fatal error: Call to a member function bar() on a non-object in %s on line %d

Zend/tests/dereference_003.phpt

@@ -0,0 +1,46 @@
+--TEST--
+Testing array dereference on method calls
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+class  foo {
+	public $x = 2;
+	public function a() {
+		$x = array();
+		$x[] = new foo;
+		return $x;
+	}
+	public function b() {
+		return array(1.2, array(new self));
+	}
+	public function c() {
+		$a = array();
+		$b = &$a;
+		$b[] = true;
+		return $a;
+	}
+	public function d() {
+		return $this->b();
+	}
+}
+
+$foo = new foo;
+
+var_dump($foo->a()[0]->x);
+var_dump($foo->a()[0]);
+var_dump($foo->b()[1][0]->a()[0]->x);
+var_dump($foo->c()[0]);
+var_dump($foo->d()[0]);
+
+?>
+--EXPECTF--
+int(2)
+object(foo)#%d (1) {
+  ["x"]=>
+  int(2)
+}
+int(2)
+bool(true)
+float(1.2)

Zend/tests/dereference_004.phpt

@@ -0,0 +1,27 @@
+--TEST--
+Testing array dereference on __invoke() result
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+class foo {
+	public $x = array();
+	public function __construct() {
+		$h = array();
+		$h[] = new stdclass;
+		$this->x = $h;
+	}
+	public function __invoke() {
+		return $this->x;
+	}
+}
+
+
+$fo = new foo;
+var_dump($fo()[0]);
+
+?>
+--EXPECTF--
+object(stdClass)#%d (0) {
+}

Zend/tests/dereference_005.phpt

@@ -0,0 +1,38 @@
+--TEST--
+Testing array dereference on object that implements ArrayAccess
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+class obj implements arrayaccess {
+    private $container = array();
+    public function __construct() {
+        $this->container = array(
+            "one"   => 1,
+            "two"   => 2,
+            "three" => 3,
+        );
+    }
+    public function offsetSet($offset, $value) {
+        $this->container[$offset] = $value;
+    }
+    public function offsetExists($offset) {
+        return isset($this->container[$offset]);
+    }
+    public function offsetUnset($offset) {
+        unset($this->container[$offset]);
+    }
+    public function offsetGet($offset) {
+        return isset($this->container[$offset]) ? $this->container[$offset] : null;
+    }
+}
+
+function x() {
+	return new obj;
+}
+var_dump(x()['two']);
+
+?>
+--EXPECT--
+int(2)

Zend/tests/dereference_006.phpt

@@ -0,0 +1,30 @@
+--TEST--
+Testing array dereference and references
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+function &foo(&$foo) {
+	return $foo;
+}
+
+$a = array(1);
+foo($a)[0] = 2;
+var_dump($a);
+
+foo($a)[] = 3;
+var_dump($a);
+
+?>
+--EXPECT--
+array(1) {
+  [0]=>
+  int(2)
+}
+array(2) {
+  [0]=>
+  int(2)
+  [1]=>
+  int(3)
+}

Zend/tests/dereference_007.phpt

@@ -0,0 +1,22 @@
+--TEST--
+Trying to write on method return
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+class foo {
+	public $x = array();
+
+	public function b() {
+		return $this->x;
+	}
+}
+
+$foo = new foo;
+
+$foo->b()[0] = 1;
+
+?>
+--EXPECTF--
+Fatal error: Can't use method return value in write context in %s on line %d

Zend/tests/dereference_008.phpt

@@ -0,0 +1,33 @@
+--TEST--
+Testing array dereference with dynamic method name and references
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+class foo {
+	public $x = array(1);
+
+	public function &b() {
+		return $this->x;
+	}
+}
+
+$foo = new foo;
+
+$a = 'b';
+var_dump($foo->$a()[0]);
+
+$h = &$foo->$a();
+$h[] = 2;
+var_dump($foo->$a());
+
+?>
+--EXPECT--
+int(1)
+array(2) {
+  [0]=>
+  int(1)
+  [1]=>
+  int(2)
+}

Zend/tests/dereference_009.phpt

@@ -0,0 +1,26 @@
+--TEST--
+Testing array dereference with references
+--FILE--
+<?php
+
+error_reporting(E_ALL);
+
+$a = array();
+
+function &a() {
+	return $GLOBALS['a'];
+}
+
+var_dump($h =& a());
+$h[] = 1;
+var_dump(a()[0]);
+
+$h[] = array($h);
+var_dump(a()[1][0][0]);
+
+?>
+--EXPECT--
+array(0) {
+}
+int(1)
+int(1)