Skip to content

Commit 82a4063

Browse files
derrabusderrabus
authored
Document stdClass structures used by CommitOrderCalculator (#10315)
1 parent 8093c2e commit 82a4063

File tree

7 files changed

+133
-57
lines changed

7 files changed

+133
-57
lines changed

‎UPGRADE.md

+10
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# Upgrade to 2.14
22

3+
## Deprecated constants of `Doctrine\ORM\Internal\CommitOrderCalculator`
4+
5+
The following public constants have been deprecated:
6+
7+
* `CommitOrderCalculator::NOT_VISITED`
8+
* `CommitOrderCalculator::IN_PROGRESS`
9+
* `CommitOrderCalculator::VISITED`
10+
11+
These constants were used for internal purposes. Relying on them is discouraged.
12+
313
## Deprecated `Doctrine\ORM\Query\AST\InExpression`
414

515
The AST parser will create a `InListExpression` or a `InSubselectExpression` when

‎lib/Doctrine/ORM/Internal/CommitOrder/Edge.php

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Doctrine\ORM\Internal\CommitOrder;
6+
7+
/** @internal */
8+
final class Edge
9+
{
10+
/**
11+
* @var string
12+
* @readonly
13+
*/
14+
public $from;
15+
16+
/**
17+
* @var string
18+
* @readonly
19+
*/
20+
public $to;
21+
22+
/**
23+
* @var int
24+
* @readonly
25+
*/
26+
public $weight;
27+
28+
public function __construct(string $from, string $to, int $weight)
29+
{
30+
$this->from = $from;
31+
$this->to = $to;
32+
$this->weight = $weight;
33+
}
34+
}

‎lib/Doctrine/ORM/Internal/CommitOrder/Vertex.php

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Doctrine\ORM\Internal\CommitOrder;
6+
7+
use Doctrine\ORM\Mapping\ClassMetadata;
8+
9+
/** @internal */
10+
final class Vertex
11+
{
12+
/**
13+
* @var string
14+
* @readonly
15+
*/
16+
public $hash;
17+
18+
/**
19+
* @var int
20+
* @psalm-var VertexState::*
21+
*/
22+
public $state = VertexState::NOT_VISITED;
23+
24+
/**
25+
* @var ClassMetadata
26+
* @readonly
27+
*/
28+
public $value;
29+
30+
/** @var array<string, Edge> */
31+
public $dependencyList = [];
32+
33+
public function __construct(string $hash, ClassMetadata $value)
34+
{
35+
$this->hash = $hash;
36+
$this->value = $value;
37+
}
38+
}

‎lib/Doctrine/ORM/Internal/CommitOrder/VertexState.php

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Doctrine\ORM\Internal\CommitOrder;
6+
7+
/** @internal */
8+
final class VertexState
9+
{
10+
public const NOT_VISITED = 0;
11+
public const IN_PROGRESS = 1;
12+
public const VISITED = 2;
13+
14+
private function __construct()
15+
{
16+
}
17+
}

‎lib/Doctrine/ORM/Internal/CommitOrderCalculator.php

+31-46
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@
44

55
namespace Doctrine\ORM\Internal;
66

7-
use stdClass;
7+
use Doctrine\ORM\Internal\CommitOrder\Edge;
8+
use Doctrine\ORM\Internal\CommitOrder\Vertex;
9+
use Doctrine\ORM\Internal\CommitOrder\VertexState;
10+
use Doctrine\ORM\Mapping\ClassMetadata;
811

912
use function array_reverse;
1013

@@ -17,33 +20,28 @@
1720
*/
1821
class CommitOrderCalculator
1922
{
20-
public const NOT_VISITED = 0;
21-
public const IN_PROGRESS = 1;
22-
public const VISITED = 2;
23+
/** @deprecated */
24+
public const NOT_VISITED = VertexState::NOT_VISITED;
25+
26+
/** @deprecated */
27+
public const IN_PROGRESS = VertexState::IN_PROGRESS;
28+
29+
/** @deprecated */
30+
public const VISITED = VertexState::VISITED;
2331

2432
/**
2533
* Matrix of nodes (aka. vertex).
26-
* Keys are provided hashes and values are the node definition objects.
27-
*
28-
* The node state definition contains the following properties:
29-
*
30-
* - <b>state</b> (integer)
31-
* Whether the node is NOT_VISITED or IN_PROGRESS
32-
*
33-
* - <b>value</b> (object)
34-
* Actual node value
3534
*
36-
* - <b>dependencyList</b> (array<string>)
37-
* Map of node dependencies defined as hashes.
35+
* Keys are provided hashes and values are the node definition objects.
3836
*
39-
* @var array<stdClass>
37+
* @var array<string, Vertex>
4038
*/
4139
private $nodeList = [];
4240

4341
/**
4442
* Volatile variable holding calculated nodes during sorting process.
4543
*
46-
* @psalm-var list<object>
44+
* @psalm-var list<ClassMetadata>
4745
*/
4846
private $sortedNodeList = [];
4947

@@ -62,21 +60,14 @@ public function hasNode($hash)
6260
/**
6361
* Adds a new node (vertex) to the graph, assigning its hash and value.
6462
*
65-
* @param string $hash
66-
* @param object $node
63+
* @param string $hash
64+
* @param ClassMetadata $node
6765
*
6866
* @return void
6967
*/
7068
public function addNode($hash, $node)
7169
{
72-
$vertex = new stdClass();
73-
74-
$vertex->hash = $hash;
75-
$vertex->state = self::NOT_VISITED;
76-
$vertex->value = $node;
77-
$vertex->dependencyList = [];
78-
79-
$this->nodeList[$hash] = $vertex;
70+
$this->nodeList[$hash] = new Vertex($hash, $node);
8071
}
8172

8273
/**
@@ -90,14 +81,8 @@ public function addNode($hash, $node)
9081
*/
9182
public function addDependency($fromHash, $toHash, $weight)
9283
{
93-
$vertex = $this->nodeList[$fromHash];
94-
$edge = new stdClass();
95-
96-
$edge->from = $fromHash;
97-
$edge->to = $toHash;
98-
$edge->weight = $weight;
99-
100-
$vertex->dependencyList[$toHash] = $edge;
84+
$this->nodeList[$fromHash]->dependencyList[$toHash]
85+
= new Edge($fromHash, $toHash, $weight);
10186
}
10287

10388
/**
@@ -106,12 +91,12 @@ public function addDependency($fromHash, $toHash, $weight)
10691
*
10792
* {@internal Highly performance-sensitive method.}
10893
*
109-
* @psalm-return list<object>
94+
* @psalm-return list<ClassMetadata>
11095
*/
11196
public function sort()
11297
{
11398
foreach ($this->nodeList as $vertex) {
114-
if ($vertex->state !== self::NOT_VISITED) {
99+
if ($vertex->state !== VertexState::NOT_VISITED) {
115100
continue;
116101
}
117102

@@ -131,19 +116,19 @@ public function sort()
131116
*
132117
* {@internal Highly performance-sensitive method.}
133118
*/
134-
private function visit(stdClass $vertex): void
119+
private function visit(Vertex $vertex): void
135120
{
136-
$vertex->state = self::IN_PROGRESS;
121+
$vertex->state = VertexState::IN_PROGRESS;
137122

138123
foreach ($vertex->dependencyList as $edge) {
139124
$adjacentVertex = $this->nodeList[$edge->to];
140125

141126
switch ($adjacentVertex->state) {
142-
case self::VISITED:
127+
case VertexState::VISITED:
143128
// Do nothing, since node was already visited
144129
break;
145130

146-
case self::IN_PROGRESS:
131+
case VertexState::IN_PROGRESS:
147132
if (
148133
isset($adjacentVertex->dependencyList[$vertex->hash]) &&
149134
$adjacentVertex->dependencyList[$vertex->hash]->weight < $edge->weight
@@ -153,25 +138,25 @@ private function visit(stdClass $vertex): void
153138
foreach ($adjacentVertex->dependencyList as $adjacentEdge) {
154139
$adjacentEdgeVertex = $this->nodeList[$adjacentEdge->to];
155140

156-
if ($adjacentEdgeVertex->state === self::NOT_VISITED) {
141+
if ($adjacentEdgeVertex->state === VertexState::NOT_VISITED) {
157142
$this->visit($adjacentEdgeVertex);
158143
}
159144
}
160145

161-
$adjacentVertex->state = self::VISITED;
146+
$adjacentVertex->state = VertexState::VISITED;
162147

163148
$this->sortedNodeList[] = $adjacentVertex->value;
164149
}
165150

166151
break;
167152

168-
case self::NOT_VISITED:
153+
case VertexState::NOT_VISITED:
169154
$this->visit($adjacentVertex);
170155
}
171156
}
172157

173-
if ($vertex->state !== self::VISITED) {
174-
$vertex->state = self::VISITED;
158+
if ($vertex->state !== VertexState::VISITED) {
159+
$vertex->state = VertexState::VISITED;
175160

176161
$this->sortedNodeList[] = $vertex->value;
177162
}

‎lib/Doctrine/ORM/UnitOfWork.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -1281,7 +1281,7 @@ private function executeDeletions(ClassMetadata $class): void
12811281
/**
12821282
* Gets the commit order.
12831283
*
1284-
* @return list<object>
1284+
* @return list<ClassMetadata>
12851285
*/
12861286
private function getCommitOrder(): array
12871287
{

‎psalm-baseline.xml

+2-10
Original file line numberDiff line numberDiff line change
@@ -410,13 +410,9 @@
410410
</UndefinedMethod>
411411
</file>
412412
<file src="lib/Doctrine/ORM/Internal/CommitOrderCalculator.php">
413-
<InvalidPropertyAssignmentValue occurrences="2">
414-
<code>$this-&gt;sortedNodeList</code>
415-
<code>$this-&gt;sortedNodeList</code>
416-
</InvalidPropertyAssignmentValue>
417413
<RedundantCondition occurrences="2">
418-
<code>$vertex-&gt;state !== self::VISITED</code>
419-
<code>$vertex-&gt;state !== self::VISITED</code>
414+
<code>$vertex-&gt;state !== VertexState::VISITED</code>
415+
<code>$vertex-&gt;state !== VertexState::VISITED</code>
420416
</RedundantCondition>
421417
</file>
422418
<file src="lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php">
@@ -2895,10 +2891,6 @@
28952891
</UnresolvableInclude>
28962892
</file>
28972893
<file src="lib/Doctrine/ORM/UnitOfWork.php">
2898-
<ArgumentTypeCoercion occurrences="2">
2899-
<code>$class</code>
2900-
<code>$class</code>
2901-
</ArgumentTypeCoercion>
29022894
<DocblockTypeContradiction occurrences="2">
29032895
<code>! is_object($object)</code>
29042896
<code>is_object($object)</code>

0 commit comments

Comments
 (0)