Skip to content

Commit 03ea85e

Browse files
morozovmorozov
authored
Merge pull request #7108 from morozov/sequence-editor
Introduce sequence editor
2 parents e07f21d + cfa4a04 commit 03ea85e

15 files changed

+332
-45
lines changed

‎UPGRADE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,13 @@ awareness about deprecated code.
88

99
# Upgrade to 4.4
1010

11+
## Deprecated `Sequence` features
12+
13+
1. The `Sequence` constructor has been marked as internal. Use `Sequence::editor()` to instantiate an editor and
14+
`SequenceEditor::create()` to create a sequence.
15+
2. Passing a negative value as sequence cache size has been deprecated.
16+
3. The `Sequence::getCache()` method has been deprecated. Use `Sequence::getCacheSize()` instead.
17+
1118
## Deprecated extension of schema classes
1219

1320
Extending the following classes has been deprecated. Use them directly.

‎src/Platforms/OraclePlatform.php‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -155,31 +155,27 @@ public function getCreateSequenceSQL(Sequence $sequence): string
155155
' START WITH ' . $sequence->getInitialValue() .
156156
' MINVALUE ' . $sequence->getInitialValue() .
157157
' INCREMENT BY ' . $sequence->getAllocationSize() .
158-
$this->getSequenceCacheSQL($sequence);
158+
$this->getSequenceCacheSQL($sequence->getCacheSize());
159159
}
160160

161161
public function getAlterSequenceSQL(Sequence $sequence): string
162162
{
163163
return 'ALTER SEQUENCE ' . $sequence->getQuotedName($this) .
164164
' INCREMENT BY ' . $sequence->getAllocationSize()
165-
. $this->getSequenceCacheSQL($sequence);
165+
. $this->getSequenceCacheSQL($sequence->getCacheSize());
166166
}
167167

168168
/**
169169
* Cache definition for sequences
170170
*/
171-
private function getSequenceCacheSQL(Sequence $sequence): string
171+
private function getSequenceCacheSQL(?int $cacheSize): string
172172
{
173-
if ($sequence->getCache() === 0) {
173+
if ($cacheSize === 0 || $cacheSize === 1) {
174174
return ' NOCACHE';
175175
}
176176

177-
if ($sequence->getCache() === 1) {
178-
return ' NOCACHE';
179-
}
180-
181-
if ($sequence->getCache() > 1) {
182-
return ' CACHE ' . $sequence->getCache();
177+
if ($cacheSize > 1) {
178+
return ' CACHE ' . $cacheSize;
183179
}
184180

185181
return '';

‎src/Platforms/PostgreSQLPlatform.php‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -330,23 +330,23 @@ public function getCreateSequenceSQL(Sequence $sequence): string
330330
' INCREMENT BY ' . $sequence->getAllocationSize() .
331331
' MINVALUE ' . $sequence->getInitialValue() .
332332
' START ' . $sequence->getInitialValue() .
333-
$this->getSequenceCacheSQL($sequence);
333+
$this->getSequenceCacheSQL($sequence->getCacheSize());
334334
}
335335

336336
public function getAlterSequenceSQL(Sequence $sequence): string
337337
{
338338
return 'ALTER SEQUENCE ' . $sequence->getQuotedName($this) .
339339
' INCREMENT BY ' . $sequence->getAllocationSize() .
340-
$this->getSequenceCacheSQL($sequence);
340+
$this->getSequenceCacheSQL($sequence->getCacheSize());
341341
}
342342

343343
/**
344344
* Cache definition for sequences
345345
*/
346-
private function getSequenceCacheSQL(Sequence $sequence): string
346+
private function getSequenceCacheSQL(?int $cacheSize): string
347347
{
348-
if ($sequence->getCache() > 1) {
349-
return ' CACHE ' . $sequence->getCache();
348+
if ($cacheSize > 1) {
349+
return ' CACHE ' . $cacheSize;
350350
}
351351

352352
return '';

‎src/Schema/Exception/InvalidSequenceDefinition.php‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Doctrine\DBAL\Schema\Exception;
6+
7+
use Doctrine\DBAL\Schema\SchemaException;
8+
use LogicException;
9+
10+
use function sprintf;
11+
12+
final class InvalidSequenceDefinition extends LogicException implements SchemaException
13+
{
14+
public static function nameNotSet(): self
15+
{
16+
return new self('Sequence name is not set.');
17+
}
18+
19+
public static function fromNegativeCacheSize(int $cacheSize): self
20+
{
21+
return new self(sprintf('Sequence cache size must be a non-negative integer, %d given.', $cacheSize));
22+
}
23+
}

‎src/Schema/Sequence.php‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ class Sequence extends AbstractNamedObject
2424

2525
protected int $initialValue = 1;
2626

27+
/**
28+
* @internal Use {@link Sequence::editor()} to instantiate an editor and {@link SequenceEditor::create()} to create
29+
* a sequence.
30+
*
31+
* @param ?non-negative-int $cache
32+
*/
2733
public function __construct(
2834
string $name,
2935
int $allocationSize = 1,
@@ -32,6 +38,14 @@ public function __construct(
3238
) {
3339
parent::__construct($name);
3440

41+
if ($cache < 0) {
42+
Deprecation::triggerIfCalledFromOutside(
43+
'doctrine/dbal',
44+
'https://github.com/doctrine/dbal/pull/7108',
45+
'Passing a negative value as sequence cache size is deprecated.',
46+
);
47+
}
48+
3549
$this->setAllocationSize($allocationSize);
3650
$this->setInitialValue($initialValue);
3751
}
@@ -51,11 +65,29 @@ public function getInitialValue(): int
5165
return $this->initialValue;
5266
}
5367

68+
/**
69+
* @deprecated Use {@see getCacheSize()} instead.
70+
*
71+
* @return ?non-negative-int
72+
*/
5473
public function getCache(): ?int
5574
{
75+
Deprecation::triggerIfCalledFromOutside(
76+
'doctrine/dbal',
77+
'https://github.com/doctrine/dbal/pull/7108',
78+
'%s is deprecated, use `getCacheSize()` instead.',
79+
__METHOD__,
80+
);
81+
5682
return $this->cache;
5783
}
5884

85+
/** @return ?non-negative-int */
86+
public function getCacheSize(): ?int
87+
{
88+
return $this->getCache();
89+
}
90+
5991
public function setAllocationSize(int $allocationSize): self
6092
{
6193
$this->allocationSize = $allocationSize;
@@ -70,6 +102,7 @@ public function setInitialValue(int $initialValue): self
70102
return $this;
71103
}
72104

105+
/** @param non-negative-int $cache */
73106
public function setCache(int $cache): self
74107
{
75108
$this->cache = $cache;
@@ -118,4 +151,24 @@ public function isAutoIncrementsFor(Table $table): bool
118151

119152
return $tableSequenceName === $sequenceName;
120153
}
154+
155+
/**
156+
* Instantiates a new sequence editor.
157+
*/
158+
public static function editor(): SequenceEditor
159+
{
160+
return new SequenceEditor();
161+
}
162+
163+
/**
164+
* Instantiates a new sequence editor and initializes it with the sequence's properties.
165+
*/
166+
public function edit(): SequenceEditor
167+
{
168+
return self::editor()
169+
->setName($this->getObjectName())
170+
->setAllocationSize($this->getAllocationSize())
171+
->setInitialValue($this->getInitialValue())
172+
->setCacheSize($this->getCacheSize());
173+
}
121174
}

‎src/Schema/SequenceEditor.php‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Doctrine\DBAL\Schema;
6+
7+
use Doctrine\DBAL\Schema\Exception\InvalidSequenceDefinition;
8+
use Doctrine\DBAL\Schema\Name\OptionallyQualifiedName;
9+
10+
final class SequenceEditor
11+
{
12+
private ?OptionallyQualifiedName $name = null;
13+
14+
private int $allocationSize = 1;
15+
16+
private int $initialValue = 1;
17+
18+
/** @var ?non-negative-int */
19+
private ?int $cacheSize = null;
20+
21+
/** @internal Use {@link Sequence::editor()} or {@link Sequence::edit()} to create an instance */
22+
public function __construct()
23+
{
24+
}
25+
26+
public function setName(OptionallyQualifiedName $name): self
27+
{
28+
$this->name = $name;
29+
30+
return $this;
31+
}
32+
33+
/**
34+
* @param non-empty-string $unqualifiedName
35+
* @param ?non-empty-string $qualifier
36+
*/
37+
public function setUnquotedName(string $unqualifiedName, ?string $qualifier = null): self
38+
{
39+
$this->name = OptionallyQualifiedName::unquoted($unqualifiedName, $qualifier);
40+
41+
return $this;
42+
}
43+
44+
/**
45+
* @param non-empty-string $unqualifiedName
46+
* @param ?non-empty-string $qualifier
47+
*/
48+
public function setQuotedName(string $unqualifiedName, ?string $qualifier = null): self
49+
{
50+
$this->name = OptionallyQualifiedName::quoted($unqualifiedName, $qualifier);
51+
52+
return $this;
53+
}
54+
55+
public function setAllocationSize(int $allocationSize): self
56+
{
57+
$this->allocationSize = $allocationSize;
58+
59+
return $this;
60+
}
61+
62+
public function setInitialValue(int $initialValue): self
63+
{
64+
$this->initialValue = $initialValue;
65+
66+
return $this;
67+
}
68+
69+
/** @param ?non-negative-int $cacheSize */
70+
public function setCacheSize(?int $cacheSize): self
71+
{
72+
if ($cacheSize < 0) {
73+
throw InvalidSequenceDefinition::fromNegativeCacheSize($cacheSize);
74+
}
75+
76+
$this->cacheSize = $cacheSize;
77+
78+
return $this;
79+
}
80+
81+
public function create(): Sequence
82+
{
83+
if ($this->name === null) {
84+
throw InvalidSequenceDefinition::nameNotSet();
85+
}
86+
87+
return new Sequence(
88+
$this->name->toString(),
89+
$this->allocationSize,
90+
$this->initialValue,
91+
$this->cacheSize,
92+
);
93+
}
94+
}

‎tests/Functional/Schema/PostgreSQL/SchemaTest.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,9 @@ public function testCreateTableWithSequenceInColumnDefinition(): void
3535
)
3636
->create();
3737

38-
$sequence = new Sequence('my_table_id_seq');
38+
$sequence = Sequence::editor()
39+
->setUnquotedName('my_table_id_seq')
40+
->create();
3941

4042
$schema = new Schema([$table], [$sequence]);
4143
foreach ($schema->toSql($platform) as $sql) {

‎tests/Functional/Schema/SchemaManagerFunctionalTestCase.php‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,11 @@ public function testCreateSequence(): void
107107

108108
$name = 'create_sequences_test_seq';
109109

110-
$this->schemaManager->createSequence(new Sequence($name));
110+
$this->schemaManager->createSequence(
111+
Sequence::editor()
112+
->setUnquotedName($name)
113+
->create(),
114+
);
111115

112116
self::assertNotNull($this->findObjectByShortestName($this->schemaManager->listSequences(), $name));
113117
}
@@ -157,7 +161,11 @@ public function testListSequences(): void
157161
}
158162

159163
$this->schemaManager->createSequence(
160-
new Sequence('list_sequences_test_seq', 20, 10),
164+
Sequence::editor()
165+
->setUnquotedName('list_sequences_test_seq')
166+
->setAllocationSize(20)
167+
->setInitialValue(10)
168+
->create(),
161169
);
162170

163171
$createdSequence = $this->findObjectByShortestName(
@@ -1429,8 +1437,18 @@ public function testCreateAndListSequences(): void
14291437
$sequence2Name = 'sequence_2';
14301438
$sequence2AllocationSize = 3;
14311439
$sequence2InitialValue = 4;
1432-
$sequence1 = new Sequence($sequence1Name, $sequence1AllocationSize, $sequence1InitialValue);
1433-
$sequence2 = new Sequence($sequence2Name, $sequence2AllocationSize, $sequence2InitialValue);
1440+
1441+
$sequence1 = Sequence::editor()
1442+
->setUnquotedName($sequence1Name)
1443+
->setAllocationSize($sequence1AllocationSize)
1444+
->setInitialValue($sequence1InitialValue)
1445+
->create();
1446+
1447+
$sequence2 = Sequence::editor()
1448+
->setUnquotedName($sequence2Name)
1449+
->setAllocationSize($sequence2AllocationSize)
1450+
->setInitialValue($sequence2InitialValue)
1451+
->create();
14341452

14351453
$this->schemaManager->createSequence($sequence1);
14361454
$this->schemaManager->createSequence($sequence2);
@@ -1459,7 +1477,12 @@ public function testComparisonWithAutoDetectedSequenceDefinition(): void
14591477
$sequenceName = 'sequence_auto_detect_test';
14601478
$sequenceAllocationSize = 5;
14611479
$sequenceInitialValue = 10;
1462-
$sequence = new Sequence($sequenceName, $sequenceAllocationSize, $sequenceInitialValue);
1480+
1481+
$sequence = Sequence::editor()
1482+
->setUnquotedName($sequenceName)
1483+
->setAllocationSize($sequenceAllocationSize)
1484+
->setInitialValue($sequenceInitialValue)
1485+
->create();
14631486

14641487
try {
14651488
$this->schemaManager->dropSequence(

‎tests/Platforms/OraclePlatformTest.php‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -407,14 +407,19 @@ public function testDoesNotPropagateUnnecessaryTableAlterationOnBinaryType(): vo
407407
);
408408
}
409409

410+
/** @param non-negative-int $cacheSize */
410411
#[DataProvider('dataCreateSequenceWithCache')]
411412
public function testCreateSequenceWithCache(int $cacheSize, string $expectedSql): void
412413
{
413-
$sequence = new Sequence('foo', 1, 1, $cacheSize);
414+
$sequence = Sequence::editor()
415+
->setUnquotedName('foo')
416+
->setCacheSize($cacheSize)
417+
->create();
418+
414419
self::assertStringContainsString($expectedSql, $this->platform->getCreateSequenceSQL($sequence));
415420
}
416421

417-
/** @return mixed[][] */
422+
/** @return iterable<array{non-negative-int, string}> */
418423
public static function dataCreateSequenceWithCache(): iterable
419424
{
420425
return [

0 commit comments

Comments
 (0)