Add year and month support to invoice sequence configuration

Author: tomkalon

CHANGELOG-2.0.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+### v2.0.3 (2025-10-21)
+
+- [#373](https://github.com/Sylius/InvoicingPlugin/pull/373) Add configurable invoice sequence scope (`monthly`/`annually`/`global`)
+  via SYLIUS_INVOICING_SEQUENCE_SCOPE ENV ([@tomkalon](https://github.com/tomkalon))
+
 ### v2.0.2 (2025-07-03)
 
 - [#373](https://github.com/Sylius/InvoicingPlugin/pull/373) Add sylius/test-application ([@Wojdylak](https://github.com/Wojdylak))

UPGRADE-2.0.md

@@ -1,3 +1,17 @@
+# UPGRADE FROM 2.0.2 TO 2.0.3
+
+## Changes
+
+1. Added support for configurable invoice sequence scoping via the SYLIUS_INVOICING_SEQUENCE_SCOPE environment variable:
+
+- monthly: resets invoice numbering each month
+- annually: resets invoice numbering each year
+- global or unset (default): uses a single global sequence (as previously)
+
+## Deprecations
+
+1. Not passing the $scope argument (of type InvoiceSequenceScopeEnum) to the constructor of SequentialInvoiceNumberGenerator is deprecated and will be required starting from version 3.0.
+
 # UPGRADE FROM 1.X TO 2.0
 
 1. Support for Sylius 2.0 has been added, it is now the recommended Sylius version to use with InvoicingPlugin.

config/doctrine/InvoiceSequence.orm.xml

@@ -11,6 +11,9 @@
         </id>
         <field name="index" column="idx" type="integer" />
         <field name="version" type="integer" version="true" />
+        <field name="year" type="integer" nullable="true"/>
+        <field name="month" type="integer"/>
+
     </mapped-superclass>
 
 </doctrine-mapping>

config/services/generators.xml

@@ -22,7 +22,7 @@
             <argument type="service" id="sylius_invoicing.factory.invoice_sequence" />
             <argument type="service" id="sylius_invoicing.manager.invoice_sequence" />
             <argument type="service" id="clock" />
-            <argument type="string">%sylius_invoicing.sequence_scope%</argument>
+            <argument key="$scope">%sylius_invoicing.sequence_scope%</argument>
         </service>
 
         <service id="sylius_invoicing.generator.invoice_identifier" class="Sylius\InvoicingPlugin\Generator\UuidInvoiceIdentifierGenerator" />

src/Entity/InvoiceSequence.php

@@ -23,9 +23,9 @@ class InvoiceSequence implements InvoiceSequenceInterface
 
     protected ?int $version = 1;
 
-    protected int $year;
+    protected ?int $year;
 
-    protected int $month;
+    protected ?int $month;
 
     /** @return mixed */
     public function getId()
@@ -53,22 +53,22 @@ public function setVersion(?int $version): void
         $this->version = $version;
     }
 
-    public function getYear(): int
+    public function getYear(): ?int
     {
         return $this->year;
     }
 
-    public function getMonth(): int
+    public function setYear(?int $year): void
     {
-        return $this->month;
+        $this->year = $year;
     }
 
-    public function setYear(int $year): void
+    public function getMonth(): ?int
     {
-        $this->year = $year;
+        return $this->month;
     }
 
-    public function setMonth(int $month): void
+    public function setMonth(?int $month): void
     {
         $this->month = $month;
     }

src/Entity/InvoiceSequenceInterface.php

@@ -22,11 +22,11 @@ public function getIndex(): int;
 
     public function incrementIndex(): void;
 
-    public function getYear(): int;
+    public function getYear(): ?int;
 
-    public function getMonth(): int;
+    public function getMonth(): ?int;
 
-    public function setYear(int $year): void;
+    public function setYear(?int $year): void;
 
-    public function setMonth(int $month): void;
+    public function setMonth(?int $month): void;
 }

src/Generator/SequentialInvoiceNumberGenerator.php

@@ -36,8 +36,8 @@ public function __construct(
             trigger_deprecation(
                 'sylius/invoicing-plugin',
                 '2.1',
-                'Not passing a "%s" to "%s" is deprecated and will be required in SyliusInvoicingPlugin 3.0.',
-                InvoiceSequenceScopeEnum::class,
+                'Not passing the "%s" argument to "%s::__construct()" is deprecated and will be required in version 3.0. Pass a valid scope explicitly (e.g. "monthly", "annually", or "global").',
+                'scope',
                 self::class,
             );
         }

src/Migrations/Version20251021074051.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * This file is part of the Sylius package.
+ *
+ * (c) Sylius Sp. z o.o.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Sylius\InvoicingPlugin\Migrations;
+
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+final class Version20251021074051 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'Add year and month columns to sylius_invoicing_plugin_sequence table';
+    }
+
+    public function up(Schema $schema): void
+    {
+        $this->addSql('ALTER TABLE sylius_invoicing_plugin_sequence ADD year INT DEFAULT NULL, ADD month INT NOT NULL');
+    }
+
+    public function down(Schema $schema): void
+    {
+        $this->addSql('ALTER TABLE sylius_invoicing_plugin_sequence DROP year, DROP month');
+    }
+}