documents new methods and classes

src/ApiResources/Shop/NewStructureArtistPremiumTrialRequest.php

@@ -14,6 +14,14 @@ use Symfony\Component\Validator\Constraints as Assert;
 
 /**
  * New structure trial request for the artist premium product.
+ *
+ * This API resource represents a request for a trial of the Artist Premium product for a new structure.
+ * It contains all the information needed to create a new organization and start a premium trial:
+ * - Structure information (name, address, email, type, legal status, etc.)
+ * - Representative information (name, function, email, phone, etc.)
+ * - Acceptance of terms and conditions
+ *
+ * The resource is exposed through API Platform for submission via a POST endpoint.
  */
 #[ApiResource(
     operations: [

src/Enum/Access/AccessIdsEnum.php

@@ -8,6 +8,11 @@ use App\Enum\EnumMethodsTrait;
 
 /**
  * Id de comptes spécifiques.
+ *
+ * This enum defines specific account IDs used in the application:
+ * - ADMIN_2IOPENSERVICE: ID of the admin2iopenservice account (10984)
+ *
+ * These IDs are used for system operations like sending emails from specific accounts.
  */
 enum AccessIdsEnum: int
 {

src/Enum/Shop/ShopRequestStatus.php

@@ -8,6 +8,13 @@ use App\Enum\EnumMethodsTrait;
 
 /**
  * Statuts d'une ShopRequest.
+ *
+ * This enum defines the possible statuses for a shop request:
+ * - PENDING: Initial status when the request is created
+ * - ACTIVATION_LINK_SENT: Status when the activation link has been sent to the user
+ * - VALIDATED: Status when the user has validated the request by clicking the activation link
+ * - COMPLETED: Status when the request has been fully processed
+ * - ERROR: Status when an error occurred during processing
  */
 enum ShopRequestStatus: string
 {

src/Enum/Shop/ShopRequestType.php

@@ -8,6 +8,11 @@ use App\Enum\EnumMethodsTrait;
 
 /**
  * Type of shop request.
+ *
+ * This enum defines the possible types of shop requests:
+ * - NEW_STRUCTURE_ARTIST_PREMIUM_TRIAL: Request for a trial of the Artist Premium product for a new structure
+ *
+ * Additional types can be added as new features are implemented.
  */
 enum ShopRequestType: string
 {

src/Message/Handler/Shop/NewStructureArtistPremiumTrialHandler.php

@@ -4,20 +4,18 @@ declare(strict_types=1);
 
 namespace App\Message\Handler\Shop;
 
-use App\ApiResources\Organization\OrganizationCreationRequest;
-use App\ApiResources\Shop\NewStructureArtistPremiumTrialRequest;
-use App\Entity\Shop\ShopRequest;
-use App\Enum\Organization\LegalEnum;
-use App\Enum\Organization\PrincipalTypeEnum;
-use App\Enum\Organization\SettingsProductEnum;
 use App\Message\Message\Shop\NewStructureArtistPremiumTrial;
-use App\Service\Organization\OrganizationFactory;
 use App\Service\Shop\ShopService;
-use Doctrine\ORM\EntityManagerInterface;
-use Psr\Log\LoggerInterface;
 use Symfony\Component\Messenger\Attribute\AsMessageHandler;
-use Symfony\Component\Serializer\SerializerInterface;
 
+/**
+ * Message handler for processing new structure artist premium trial requests.
+ *
+ * This class handles the NewStructureArtistPremiumTrial message, which is dispatched
+ * when a user validates a trial request by clicking the activation link in the email.
+ *
+ * It delegates the actual processing to the ShopService.
+ */
 #[AsMessageHandler]
 readonly class NewStructureArtistPremiumTrialHandler
 {
@@ -27,6 +25,10 @@ readonly class NewStructureArtistPremiumTrialHandler
     ) {
     }
 
+    /**
+     * @param NewStructureArtistPremiumTrial $message The message to process
+     * @return void
+     */
     public function __invoke(NewStructureArtistPremiumTrial $message): void
     {
         $token = $message->getToken();

src/Message/Message/Shop/NewStructureArtistPremiumTrial.php

@@ -6,6 +6,12 @@ namespace App\Message\Message\Shop;
 
 /**
  * Message for processing a new structure artist premium trial request.
+ *
+ * This message is dispatched when a user validates a trial request by clicking
+ * the activation link in the email. It contains the token that identifies the
+ * shop request to be processed.
+ *
+ * It is handled by the NewStructureArtistPremiumTrialHandler class.
  */
 class NewStructureArtistPremiumTrial
 {
@@ -14,11 +20,22 @@ class NewStructureArtistPremiumTrial
     ) {
     }
 
+    /**
+     * Gets the token that identifies the shop request.
+     *
+     * @return string The token
+     */
     public function getToken(): string
     {
         return $this->token;
     }
 
+    /**
+     * Sets the token that identifies the shop request.
+     *
+     * @param string $token The token
+     * @return void
+     */
     public function setToken(string $token): void
     {
         $this->token = $token;

src/Service/Dolibarr/DolibarrUtils.php

@@ -6,9 +6,20 @@ namespace App\Service\Dolibarr;
 use App\Enum\Organization\SettingsProductEnum;
 use App\Service\Utils\DatesUtils;
 use Doctrine\DBAL\Connection;
-use Doctrine\ORM\EntityManagerInterface;
 use Exception;
 
+/**
+ * Utility class for interacting with Dolibarr ERP/CRM system.
+ *
+ * This class provides various utility methods for:
+ * - Getting product IDs based on contract type and other parameters
+ * - Executing SQL queries on the Dolibarr database
+ * - Updating society commercials
+ * - Adding entries to the commercial action journal
+ * - Getting product names
+ *
+ * It handles the integration between the application and Dolibarr for shop-related operations.
+ */
 class DolibarrUtils
 {
     const ARTIST_STANDARD_CMF_PRODUCT_ID = 283;

src/Service/Shop/ShopService.php

@@ -26,6 +26,8 @@ use App\Service\Utils\DatesUtils;
 use App\Service\Utils\UrlBuilder;
 use Doctrine\DBAL\Exception;
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\Exception\ORMException;
+use Doctrine\ORM\OptimisticLockException;
 use JsonException;
 use libphonenumber\PhoneNumberUtil;
 use Psr\Log\LoggerInterface;
@@ -39,6 +41,14 @@ use Symfony\Component\Uid\Uuid;
 
 /**
  * Service for managing shop requests.
+ *
+ * This service handles various shop-related operations.
+ * It provides functionality for:
+ * - Registering new shop requests
+ * - Validating and processing shop requests
+ * - Creating organizations based on trial requests
+ * - Starting premium trials for organizations
+ * - Generating subdomains from structure names
  */
 class ShopService
 {
@@ -223,7 +233,17 @@ class ShopService
         );
     }
 
-    protected function handleNewStructureArtistPremiumTrialRequest(string $token): void
+    /**
+     * Handles the processing of a new structure artist premium trial request.
+     *
+     * @param string $token The token identifying the shop request
+     * @return void
+     * @throws Exception
+     * @throws JsonException
+     * @throws ORMException
+     * @throws OptimisticLockException
+     */
+    public function handleNewStructureArtistPremiumTrialRequest(string $token): void
     {
         // Retrieve the ShopRequest entity using its token
         $shopRequest = $this->entityManager->find(ShopRequest::class, $token);
@@ -249,6 +269,12 @@ class ShopService
         $this->logger->info('Successfully processed NewStructureArtistPremiumTrial for token: ' . $token);
     }
 
+    /**
+     * Creates a new organization based on a trial request.
+     *
+     * @param NewStructureArtistPremiumTrialRequest $trialRequest The trial request containing organization data
+     * @return Organization The created organization
+     */
     protected function createOrganization(NewStructureArtistPremiumTrialRequest $trialRequest): Organization
     {
         // Generate an OrganizationCreationRequest object
@@ -281,6 +307,9 @@ class ShopService
 
     /**
      * Generate a subdomain from a structure name.
+     *
+     * @param string $name The structure name to generate a subdomain from
+     * @return string The generated subdomain
      */
     protected function generateSubdomain(string $name): string
     {
@@ -317,6 +346,8 @@ class ShopService
     }
 
     /**
+     * Vérifie la validité d'une requête d'essai artist premium pour une nouvelle structure
+     *
      * @param NewStructureArtistPremiumTrialRequest $request
      * @return void
      */

src/State/Processor/Shop/NewStructureArtistPremiumTrialRequestProcessor.php

@@ -14,6 +14,8 @@ use Symfony\Component\Serializer\SerializerInterface;
 
 /**
  * Processor for handling new structure trial requests for the artist premium product.
+ *
+ * It is used by the NewStructureArtistPremiumTrialRequest API resource.
  */
 class NewStructureArtistPremiumTrialRequestProcessor implements ProcessorInterface
 {
@@ -24,11 +26,19 @@ class NewStructureArtistPremiumTrialRequestProcessor implements ProcessorInterfa
     }
 
     /**
-     * @param mixed $data
-     * @param Operation $operation
-     * @param array $uriVariables
-     * @param array $context
-     * @return mixed
+     * Processes the incoming request to create a new structure artist premium trial request.
+     *
+     * This method:
+     * 1. Validates that the operation is a POST
+     * 2. Serializes the request data to JSON
+     * 3. Delegates to the ShopService to register the new shop request
+     *
+     * @param mixed $data The request data (NewStructureArtistPremiumTrialRequest object)
+     * @param Operation $operation The API Platform operation
+     * @param array $uriVariables The URI variables
+     * @param array $context The context
+     * @return mixed The processed data
+     * @throws \RuntimeException If the operation is not a POST
      */
     public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
     {