Add soo much internal doc descriptions.

Author: janbarasek

README.md

@@ -5,6 +5,15 @@ Variable generator
 
 Generate new variable symbol by last variable and selected strategy.
 
+Idea
+----
+
+A series of smart tools for generating variable symbols and order numbers in your e-shop.
+
+Generating order numbers or other number series hides a number of complex problems. For example, adhering to the specified format according to the specification, handling transaction entries (to avoid duplication) and handling the case when the generated value overflows.
+
+This package contains a set of algorithms and ready-made strategies to elegantly solve these problems. If any of the algorithms do not suit you, you can implement your own just by satisfying the defined interface.
+
 📦 Installation
 ---------------
 

src/Order/OrderEntity.php

@@ -5,6 +5,11 @@
 namespace Baraja\VariableGenerator\Order;
 
 
+/**
+ * A generic definition of an entity (most often an entity representing an order) in your database schema.
+ * Each variant entity has a unique identifier (often a row ID) and a unique human-friendly generated number.
+ * This data serves as the basis for generating a new number.
+ */
 interface OrderEntity
 {
 	public function getId(): string|int|null;

src/Strategy/FormatStrategy.php

@@ -5,12 +5,25 @@
 namespace Baraja\VariableGenerator\Strategy;
 
 
+/**
+ * Generates the next number in the sequence based on the implemented strategy.
+ * The next number is always determined by a deterministic algorithm based on the defined input.
+ * If you are servicing a large number of orders in parallel,
+ * you can request a number of numbers in advance and cache the results.
+ *
+ * Each strategy guarantees that a valid number in the defined range
+ * (or the first number if none existed before) will always be returned.
+ */
 interface FormatStrategy
 {
+	/**
+	 * Returns the next number in sequence based on the input.
+	 * The generation is always done by a deterministic algorithm.
+	 */
 	public function generate(string $last): string;
 
 	/**
-	 * Generate first variable, if last does not exist.
+	 * Generate the first variable, if last does not exist.
 	 */
 	public function getFirst(): string;
 }

src/Strategy/SimpleIncrementStrategy.php

@@ -5,6 +5,11 @@
 namespace Baraja\VariableGenerator\Strategy;
 
 
+/**
+ * The service just adds one to the last generated number and tries to keep the range.
+ * No further logic is performed.
+ * If the number did not exist before, it generates a new one with the prefix of the current year.
+ */
 final class SimpleIncrementStrategy implements FormatStrategy
 {
 	public function __construct(

src/Strategy/YearPrefixIncrementStrategy.php

@@ -5,6 +5,23 @@
 namespace Baraja\VariableGenerator\Strategy;
 
 
+/**
+ * The general formatting strategy that generates this format:
+ *
+ * YYXXXXXX
+ * ^ ^
+ * | \_ Generated number
+ * \___ Year prefix
+ *
+ * Sample generated number can be 21000001 for first number in 2021.
+ *
+ * This strategy tries to maintain a defined number of characters.
+ * The number of characters may overflow in case of a large number of orders.
+ * The minimum length of the generated number is 3 characters.
+ *
+ * If there is a natural year change (during New Year's Eve),
+ * the number series will automatically reset and the new number will be the first in the sequence of the new year.
+ */
 final class YearPrefixIncrementStrategy implements FormatStrategy
 {
 	public function __construct(
@@ -16,20 +33,16 @@ public function __construct(
 
 	public function generate(string $last): string
 	{
-		if (preg_match('/^(?<year>\d{2})(?<count>\d+)$/', $last, $variableParser)) {
-			$year = date('y');
-			if ($year === $variableParser['year']) {
-				$length = $this->length ?? strlen($variableParser['count']);
-				$new = $variableParser['year']
-					. str_pad(
-						string: (string) ($variableParser['count'] + 1),
-						length: $length,
-						pad_string: '0',
-						pad_type: STR_PAD_LEFT,
-					);
-			} else {
-				$new = $year . str_repeat('0', strlen($variableParser['count']) - 1) . '1';
-			}
+		$year = date('y');
+		if (preg_match('/^' . $year . '(?<count>\d+)$/', $last, $parser)) {
+			$length = $this->length ?? strlen($parser['count']);
+			$new = $year
+				. str_pad(
+					string: (string) ($parser['count'] + 1),
+					length: $length,
+					pad_string: '0',
+					pad_type: STR_PAD_LEFT,
+				);
 		} else {
 			$new = $this->getFirst();
 		}

src/VariableGenerator.php

@@ -11,6 +11,9 @@
 use Baraja\VariableGenerator\Strategy\YearPrefixIncrementStrategy;
 use Doctrine\ORM\EntityManagerInterface;
 
+/**
+ * A generic service for generating a unique order number, variable symbol or other unique identifier.
+ */
 final class VariableGenerator
 {
 	private VariableLoader $variableLoader;
@@ -42,6 +45,10 @@ public function generate(?string $last = null): int
 	}
 
 
+	/**
+	 * Returns the current latest number. For example, the order number.
+	 * Warning: Never use this number for create a new entity, in this case use the generate() method.
+	 */
 	public function getCurrent(bool $findReal = true): int
 	{
 		$currentValue = $findReal === true
@@ -58,6 +65,13 @@ public function setStrategy(FormatStrategy $strategy): void
 	}
 
 
+	/**
+	 * Automatically finds a unique Doctrine entity that implements the OrderEntity interface.
+	 * In most applications, there is only one unique entity for an order,
+	 * so this interface can be used as the key for the search.
+	 * If your application uses multiple entities for which you need to generate variable symbols,
+	 * implement a custom service for VariableLoader.
+	 */
 	private function resolveVariableLoader(?VariableLoader $loader, ?EntityManagerInterface $em): VariableLoader
 	{
 		if ($loader !== null) {

src/VariableLoader.php

@@ -5,6 +5,11 @@
 namespace Baraja\VariableGenerator;
 
 
+/**
+ * A generic interface that gets the number of the last stored entity of the type.
+ * It is most commonly used as a DIC service to retrieve the last order from the database.
+ * This service also solves the loading problem about database transactions.
+ */
 interface VariableLoader
 {
 	public function getCurrent(): ?string;